Metadata-Version: 2.4
Name: Algomancy
Version: 0.3.13
Summary: A dashboarding framework for visualizing performances of algorithms or simulations in various scenarios.
Keywords: visualization,algorithm,simulation,scenario
Author: Pepijn Wissing
Author-email: Pepijn Wissing <pepijn.wissing@cqm.nl>
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Requires-Dist: algomancy-cli>=0.3.13
Requires-Dist: algomancy-content>=0.3.13
Requires-Dist: algomancy-data>=0.3.13
Requires-Dist: algomancy-gui>=0.3.13
Requires-Dist: algomancy-scenario>=0.3.13
Requires-Dist: algomancy-utils>=0.3.13
Requires-Dist: pytest>=8.4.2
Requires-Dist: ruff>=0.13.1
Requires-Dist: strenum>=0.4.15
Maintainer: Pepijn Wissing, Bart Post
Maintainer-email: Pepijn Wissing <pepijn.wissing@cqm.nl>, Bart Post <bart.post@cqm.nl>
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Algomancy

A lightweight framework for building interactive dashboards to visualize the performance of algorithms and/or simulations across scenarios. It provides data ingestion (ETL), scenario orchestration, KPI computation, and a Dash-based UI with modular pages.

### Overview
- Language/stack: Python 3.14+, Dash (frontend/server), Waitress (production WSGI), PyTest (tests), Ruff (lint). Optional: uv as package manager (uv.lock present).
- Package layout: Installable Python package (setuptools/pyproject). Library entry points are in algomancy/, with an example executable script main-example.py.
- Use cases: Rapid prototyping of algorithm scenario experiments and visual inspection of results.

### Requirements
- Python: 3.14+
- OS: Windows, macOS, or Linux
- Dependencies (core): dash, dash-bootstrap-components, dash-auth (optional), dash-extensions, dash-iconify, pandas, fastparquet, openpyxl, diskcache, strenum, tabulate, waitress, python-dotenv
- Dev/test tools: pytest, ruff, wheel
- Optional tools: uv (if you prefer uv over pip)

## Installation
You can install the published package from the private Azure Artifacts feed (keep this section) or install locally in editable/development mode.

### From PyPI
- Install Algomancy:
```
uv add algomancy
```

### Running the Example App
This repo includes an example application that exercises the framework components.
- CLI
  python main-example.py --host 127.0.0.1 --port 8050 --threads 8 --connections 100 --debug False
- Defaults
  If flags are omitted, sensible defaults are applied inside main() (e.g., host differs by OS, port=8050).
- After starting, open http://127.0.0.1:8050 (or the host/port you chose) in your browser.

### Programmatic Usage (library)
You can embed Algomancy into your own app using the DashLauncher helper.
- Minimal sketch:

```python
from src.algomancy import BaseDataSource
from src.algomancy.gui_launcher import GuiLauncher
from algomancy_gui.appconfiguration import AppConfiguration

configuration = {
  "assets_path": "assets",
  "data_path": "tests/data",
  "has_persistent_state": True,
  "save_type": "json",
  "data_object_type": BaseDataSource,
  "etl_factory": YourETLFactory,
  "kpi_templates": your_kpi_templates,
  "algo_templates": your_algorithm_templates,
  "input_configs": your_input_configs,
  "autorun": False,
  "home_content": "placeholder",
  "data_content": "placeholder",
  "scenario_content": "placeholder",
  "compare_content": "placeholder",
  "compare_compare": "placeholder",
  "compare_details": "placeholder",
  "overview_content": "placeholder",
  "home_callbacks": None,
  "data_callbacks": None,
  "scenario_callbacks": None,
  "compare_callbacks": None,
  "overview_callbacks": None,
  "styling_config": None,  # see StylingConfigurator for options
  "title": "My Algomancy Dashboard",
  "use_authentication": False,
}
app_cfg = AppConfiguration.from_dict(configuration)  # or AppConfiguration(asset_path=...)

app = GuiLauncher.build(app_cfg)
GuiLauncher.run(app, host=app_cfg.host, port=app_cfg.port)
```
### Environment Variables
- Authentication (optional): If configuration["use_authentication"] is True, set these before launching:
  APP_USERNAME=<username>
  APP_PASSWORD=<password>
  If either is missing, DashLauncher.build will raise a ValueError.
- Other env vars: Not required by default. You may use a .env file with python-dotenv if you extend the app. TODO: Document any project-specific environment variables if/when they are introduced.

### Scripts and Common Commands
- Run example app:
  python main-example.py
- Run tests:
  pytest -q
- Run tests with verbose output:
  pytest -vv
- Lint with Ruff:
  ruff check .
- Format with Ruff (if you choose to enable it):
  ruff format .

### Testing
- Framework uses pytest; tests are under tests/.
- Example dataset is in tests/data and tests/data/example_data.
- Some tests are marked xfail intentionally (e.g., missing setters) to capture current behavior. You can run them as-is to verify baseline expectations.

### Project Structure
High-level layout (non-exhaustive):
- algomancy/                Core package
  - launcher.py             Build and run Dash app (DashLauncher)
  - dataengine/             Data loading, ETL, schema, validation
  - scenarioengine/         Scenario orchestration, algorithms, KPIs
  - components/             Dash UI components and pages
  - contentcreatorlibrary/  Ready-made content creators (examples/standard/placeholder)
  - dashboardlogger/        Logging utilities
  - settingsmanager.py      Shared runtime settings access
  - stylingconfigurator.py  Theme, colors, layout selection
- example_implementation/   Example ETL, pages, and templates
- assets/                   Static assets (images/styles)
- tests/                    PyTest suites and data files
- main-example.py           Example app entry point
- pyproject.toml            Build configuration (setuptools)
- uv.lock                   Lock file for uv (optional)

### Entry Points
- Example executable: main-example.py (CLI and default run)
- Library: DashLauncher in algomancy/launcher.py
- There are no console_scripts defined in pyproject.toml.

### Configuration Notes
- Styling: See algomancy/stylingconfigurator.py for layout and color options.
- Content registration: algomancy/contentcreatorlibrary and algomancy/contentregistry.py provide standard/example/placeholder content.
- Server: DashLauncher.run uses Waitress in non-debug mode; Dash’s built-in server is used for debug.

### Package Management
- The project is defined via pyproject.toml with setuptools. Use pip for installs by default.
- A uv.lock file is present; you may use uv if preferred. This repository does not mandate uv.

### CI/CD
- Pipelines configuration files are present under Pipelines/ (Azure DevOps YAML). TODO: Document pipeline triggers, variables, and publishing steps if relevant.

### License
- License: Restricted (as declared in pyproject.toml). Distribution and usage may be limited. Consult the project owners for permissions.

### Changelog
- See changelog.md for notable changes.

### Contributing
- Open issues and pull requests as needed. Run ruff and pytest locally before pushing.
- TODO: Add contributor guidelines and code style policy if required.

### Support
- Maintainers: See pyproject.toml authors/maintainers fields.
- For private package feed access or deployment, contact project maintainers.

# Update version
Option A: Update Pipfile to point to the existing wheel (preferred)
In Pipfile, replace the algomancy source pointing to 0.2.5 with the local 0.2.6 wheel path:
Example: algomancy = {path = "dist/algomancy-0.2.6-py3-none-any.whl"}
Then regenerate lockfile and install:
pipenv lock --clear
pipenv install