Quickstart

The following example launches a small placeholder dashboard using the default building blocks from the Algomancy ecosystem. Copy this into a file called main.py and run it.

Installation

Use your package manager to install the Algomancy suite from PyPI.

uv add algomancy

pip install algomancy

Use the syntax below if a specific version is desired

uv add algomancy==0.8.2

pip install algomancy==0.8.2

To update to the latest version, use

uv sync --upgrade-package algomancy

pip install --upgrade algomancy

Optional dependencies

The SQL-backed persistence layer (used by DatabaseDataManager and SqlScenarioRepository) requires sqlalchemy and alembic. These are not pulled in by the default install — opt in via the [database] extra:

uv add "algomancy[database]"

pip install "algomancy[database]"

Skip this extra if your app uses the default in-memory or JSON-on-disk persistence backend. The quickstart wizard will remind you to install it when you pick the database backend at step 1.

Set up a basic app

To set up a new Algomancy project, it is recommended to follow the quickstart wizard. The wizard features interactive prompts, intelligent file detection (CSV, XLSX, JSON), automatic datatype inference with column mapping, and generates code templates using Jinja2. This significantly reduces the initial setup time and provides new users with a structured starting point following framework best practices.

To launch the wizard, open terminal and use the command

algomancy-quickstart

to be guided through the set-up steps, outlined below.

  1. Creating the folder structure

    The user is prompted for some basic information (app title, host, port, interface, persistence backend), after which the following directory structure is created, with a basic main.py file.

    The interface prompt accepts a comma-separated subset of gui and api (e.g. gui, api, or gui,api). GUI-only artifacts are skipped when gui is not selected — an API-only project will not contain assets/, src/pages/, or src/styling_config.py, and steps 4 (default assets) and 5 (styling) are skipped without prompting. The persistence backend is one of none, json, or database and is wired into CoreConfig in the generated main.py. When database is selected, the wizard additionally asks for a SQLAlchemy URL (defaulting to sqlite:///myapp.db) and reminds you to install the [database] extras.

    Content after step
    Project directory after initializing with algomancy-quickstart (GUI interface)
    root/
|── assets/                  # GUI only
├── data/
│   └── setup/
├── src/
│   ├── data_handling/
│   ├── pages/               # GUI only
│   └── templates/
│       ├── kpi/
│       └── algorithm/
└── main.py

    For an API-only project (interfaces=api), the assets/ and src/pages/ folders are not created.

    The generated main.py uses a unified template that wires up only the launchers you selected and dispatches between them via --interface when more than one is chosen. It also exposes a --validate flag that builds the configuration without binding any port — useful in CI.

    main.py after initializing with algomancy-quickstart (GUI-only, placeholder content)
     1import argparse
 2
 3from algomancy_data import DataSource
 4from algomancy_scenario.core_configuration import CoreConfig
 5from algomancy_gui.configuration.appconfig import AppConfig
 6from algomancy_gui.configuration.comparepageconfig import ComparePageConfig
 7from algomancy_gui.configuration.featureconfig import FeatureConfig
 8from algomancy_gui.configuration.pageconfig import PageConfig
 9from algomancy_gui.configuration.serverconfig import ServerConfig
10from algomancy_gui.configuration.stylingconfig import StylingConfig
11from algomancy_gui.gui_launcher import GuiLauncher
12
13# Placeholder ETL factory and schemas
14from algomancy_content import PlaceholderETLFactory, PlaceholderSchema
15
16# Placeholder KPI and Algorithm
17from algomancy_content import PlaceholderKPI, PlaceholderAlgorithm
18
19
20HOST = "127.0.0.1"
21PORT = 8050
22
23
24def _core_kwargs() -> dict:
25    """Shared CoreConfig keyword arguments used by every interface."""
26    return dict(
27        etl_factory=PlaceholderETLFactory,
28        schemas=[PlaceholderSchema()],
29        kpis={"placeholder": PlaceholderKPI},
30        algorithms={"placeholder": PlaceholderAlgorithm},
31        data_object_type=DataSource,
32        autocreate=False,
33        autorun=False,
34        title="My Algomancy Dashboard",
35        has_persistent_state=False,
36        persistence_backend="none",
37    )
38
39
40def build_gui() -> AppConfig:
41    return AppConfig(
42        core_config=CoreConfig(**_core_kwargs()),
43        server_config=ServerConfig(host=HOST, port=PORT),
44        page_config=PageConfig(),
45        compare_page_config=ComparePageConfig(),
46        styling_config=StylingConfig(assets_path="assets"),
47        feature_config=FeatureConfig(),
48    )
49
50
51def run_gui() -> None:
52    cfg = build_gui()
53    app = GuiLauncher.build(cfg)
54    GuiLauncher.run(app=app, host=cfg.server.host, port=cfg.server.port)
55
56
57def main() -> None:
58    parser = argparse.ArgumentParser(description="My Algomancy Dashboard")
59    parser.add_argument("--validate", action="store_true")
60    args = parser.parse_args()
61
62    if args.validate:
63        build_gui()
64        return
65
66    run_gui()
67
68
69if __name__ == "__main__":
70    main()

  2. Implementation templates

    Next, the basic placeholders as provided by algomancy-content are replaced by implementation templates for schema, ETL, algorithm, kpi and each of the app pages (pages are GUI-only). These templates include brief DocString and todo notes that indicate where the user’s input is required.

    The user is prompted to provide a prefix for the generated files and classes. Files are named using the snake-case prefix (e.g. sales_algorithm.py, sales_kpi.py) and classes use the PascalCase prefix (e.g. SalesAlgorithm, SalesKPI). After generation, the main.py configuration is updated to import and wire in the generated material.

  3. Generating an ETL pipeline

    The data/setup/ directory is scanned for data files. In case the user has not plugged in any data files, they are instructed to add them now.

    Tip

    If the folder structure is not visible yet, try to reload from disk

    The user receives a prompt for each file that is found in data/setup/, asking whether it should be included. The wizard attempts to detect the data type of each column. The appropriate Schema classes and Extractors are generated (written to src/data_handling/generated_schemas.py, superseding the step-2 stub) and the etl_factory is updated.

    By default, validation includes

    • ExtractionSuccessValidator that validates that the extraction was successful

    • SchemaValidator that validates that the data conforms to the schema

    Transformation is left as a configurable step. The user can choose to apply transformations to the data, or skip this step. Finally, the data is loaded into a default DataSource container

    Tip

    Use a small slice of validated data for this step, to ensure that the data types are correctly inferred

  4. Installing default assets (GUI only)

    After confirmation by the user, the assets folder associated with the Algomancy library is imported from the github page. If the import fails, an offline fallback is included. However, the baked-in assets are not guaranteed to be up-to-date.

  5. Styling (GUI only)

    The user is prompted to configure the dashboard styling. A selection of default themes is made, followed by several ways in which the styling configuration can be customized.

  6. Generating pytest skeletons

    The wizard offers to generate pytest skeletons under tests/ that cover the implementations produced in earlier steps:

    • tests/conftest.py — always emitted, adds the project root to sys.path so from src... imports resolve.

    • tests/test_<prefix>_algorithm.py and tests/test_<prefix>_kpi.py — emitted when step 2 ran.

    • tests/test_etl_factory.py — emitted when either step 2 or step 3 ran.

    Run the generated suite with pytest tests/.

    Content after wizard completes
    Project directory after algomancy-quickstart (GUI interface, prefix “Test”)
    root/
|── assets/                       # GUI only
│   ├── css/
│   ├── ...
│   └── styling.css
├── data/
│   └── setup/
│       └── ...
├── src/
│   ├── data_handling/
│   │   ├── etl_factory.py
│   │   └── generated_schemas.py
│   ├── pages/                    # GUI only
│   │   ├── compare_page.py
│   │   ├── data_page.py
│   │   ├── home_page.py
│   │   ├── overview_page.py
│   │   └── scenario_page.py
│   ├── templates/
│   │   ├── kpi/
│   │   │   └── test_kpi.py
│   │   └── algorithm/
│   │       └── test_algorithm.py
│   └── styling_config.py         # GUI only
├── tests/
│   ├── conftest.py
│   ├── test_etl_factory.py
│   ├── test_test_algorithm.py
│   └── test_test_kpi.py
└── main.py
    main.py after algomancy-quickstart (GUI-only, custom implementations + generated ETL + styling)
     1import argparse
 2
 3from algomancy_data import DataSource
 4from algomancy_scenario.core_configuration import CoreConfig
 5from algomancy_gui.configuration.appconfig import AppConfig
 6from algomancy_gui.configuration.comparepageconfig import ComparePageConfig
 7from algomancy_gui.configuration.featureconfig import FeatureConfig
 8from algomancy_gui.configuration.pageconfig import PageConfig
 9from algomancy_gui.configuration.serverconfig import ServerConfig
10from algomancy_gui.gui_launcher import GuiLauncher
11
12# Generated ETL factory and schemas
13from src.data_handling.etl_factory import TestETLFactory
14from src.data_handling.generated_schemas import all_schemas
15
16# Custom implementations
17from src.templates.algorithm.test_algorithm import TestAlgorithm
18from src.templates.kpi.test_kpi import TestKPI
19from src.pages.home_page import TestHomePage
20from src.pages.data_page import TestDataPage
21from src.pages.scenario_page import TestScenarioPage
22from src.pages.compare_page import TestComparePage
23from src.pages.overview_page import TestOverviewPage
24
25# Styling configuration
26from src.styling_config import app_styling
27
28
29HOST = "127.0.0.1"
30PORT = 8050
31
32
33def _core_kwargs() -> dict:
34    return dict(
35        etl_factory=TestETLFactory,
36        schemas=all_schemas,
37        kpis={"test": TestKPI},
38        algorithms={"Test": TestAlgorithm},
39        data_object_type=DataSource,
40        autocreate=False,
41        autorun=False,
42        title="My Algomancy Dashboard",
43        has_persistent_state=False,
44        persistence_backend="none",
45    )
46
47
48def build_gui() -> AppConfig:
49    return AppConfig(
50        core_config=CoreConfig(**_core_kwargs()),
51        server_config=ServerConfig(host=HOST, port=PORT),
52        page_config=PageConfig(
53            home_page=TestHomePage(),
54            data_page=TestDataPage(),
55            scenario_page=TestScenarioPage(),
56            compare_page=TestComparePage(),
57#           overview_page=TestOverviewPage(),  # uncomment to use TestOverviewPage
58        ),
59        compare_page_config=ComparePageConfig(),
60        styling_config=app_styling,
61        feature_config=FeatureConfig(),
62    )
63
64
65def run_gui() -> None:
66    cfg = build_gui()
67    app = GuiLauncher.build(cfg)
68    GuiLauncher.run(app=app, host=cfg.server.host, port=cfg.server.port)
69
70
71def main() -> None:
72    parser = argparse.ArgumentParser(description="My Algomancy Dashboard")
73    parser.add_argument("--validate", action="store_true")
74    args = parser.parse_args()
75
76    if args.validate:
77        build_gui()
78        return
79
80    run_gui()
81
82
83if __name__ == "__main__":
84    main()

    When api is included in the selected interfaces, the template additionally emits build_api() / run_api() helpers using ApiConfiguration and ApiLauncher. If both interfaces are selected, main() dispatches on --interface {gui,api}.

Run

  • Start the app by running:

uv run main.py

python main.py

When the generated main.py exposes both interfaces, pass --interface gui or --interface api to pick one (GUI is the default). Use --validate to build the wiring and exit without binding a port.