algomancy-api
FastAPI HTTP interface that exposes the same scenario- and data-management
surface used by algomancy-gui, so a remote frontend (browser SPA, native
desktop app, another Python process) can drive an Algomancy backend over
the network instead of importing it in-process.
The HTTP layer is deliberately thin: every route maps to a single
ScenarioManager / SessionManager method and responses use the existing
to_dict() payloads. There is no parallel domain model — clients work with
the same Scenario, DataSource, and KPI concepts the Dash GUI does.
Quick start
from algomancy_api import ApiConfiguration, ApiLauncher
from algomancy_data import DataSource
cfg = ApiConfiguration(
etl_factory=MyETLFactory,
kpis=kpis,
algorithms=algorithms,
schemas=schemas,
data_object_type=DataSource,
has_persistent_state=True,
data_path="data",
autocreate=False,
autorun=False,
)
app = ApiLauncher.build(cfg) # returns a standard FastAPI app
ApiLauncher.run(app) # blocks; uses cfg.host / cfg.port
The server starts (default 127.0.0.1:8051) and serves the OpenAPI schema at
/openapi.json plus the interactive Swagger UI at /docs. All scenario/data
endpoints live under /api/v1/sessions/{session_id}/....
ApiLauncher.build returns a standard FastAPI instance — for production
deploys you can hand it to your own uvicorn / gunicorn process manager
instead of using ApiLauncher.run.
To try it against the bundled example wiring:
from algomancy_api import ApiLauncher
from algomancy_api.example import build_example_config
ApiLauncher.run(ApiLauncher.build(build_example_config()))
Endpoint inventory
All routes are prefixed with cfg.prefix (default /api/v1).
Sessions
GET /sessions— list[{id, display_name}, ...]and the default idPOST /sessions— create a new session — body{"display_name": "..."}POST /sessions/{sid}/copy— copy — body{"new_display_name": "..."}PATCH /sessions/{sid}— rename — body{"display_name": "..."}DELETE /sessions/{sid}— delete a session and all its data; the last remaining session is auto-replaced with a fresh"main"
{sid} accepts either the session's UUID (canonical) or its current
display_name (soft-compat alias).
Algorithm + KPI discovery
GET /sessions/{sid}/algorithms— list algorithm namesGET /sessions/{sid}/algorithms/{name}/parameters— per-parameter descriptorsGET /sessions/{sid}/kpis— list KPI template names
Scenarios
GET /sessions/{sid}/scenarios— list scenariosPOST /sessions/{sid}/scenarios— create a scenarioGET /sessions/{sid}/scenarios/{id}— full scenario incl. KPIs and resultDELETE /sessions/{sid}/scenarios/{id}— delete a scenarioPOST /sessions/{sid}/scenarios/{id}/run— enqueue for processingGET /sessions/{sid}/scenarios/{id}/status— lightweight status/progress (polling)GET /sessions/{sid}/processing— currently running scenario, ornull
Data
GET /sessions/{sid}/data— list dataset keysGET /sessions/{sid}/data/{key}— parsed JSON of a datasetDELETE /sessions/{sid}/data/{key}— delete a datasetPOST /sessions/{sid}/data/{key}/derive— derive a new datasetPOST /sessions/{sid}/data/from-json— add a dataset fromDataSource.to_json()payloadPOST /sessions/{sid}/etl— run ETL over a multipart upload
Meta
GET /health— liveness probeGET /openapi.json,GET /docs— OpenAPI schema and Swagger UI
Polling pattern
import time
import httpx
base = "http://127.0.0.1:8051/api/v1"
session = httpx.get(f"{base}/sessions").json()["default"]
scenario = httpx.post(
f"{base}/sessions/{session}/scenarios",
json={
"tag": "my-run",
"dataset_key": "Master data",
"algo_name": "Slow",
"algo_params": {"duration": 5},
},
).json()
httpx.post(f"{base}/sessions/{session}/scenarios/{scenario['id']}/run")
while True:
status = httpx.get(
f"{base}/sessions/{session}/scenarios/{scenario['id']}/status"
).json()
if status["status"] in ("complete", "failed"):
break
time.sleep(0.5)
print(httpx.get(f"{base}/sessions/{session}/scenarios/{scenario['id']}").json())
Error mapping
| Exception | HTTP | When |
|---|---|---|
ValueError |
400 |
Generic bad input |
ParameterError |
400 |
Algorithm parameter validation failure |
AssertionError |
409 |
Framework precondition (e.g. deleting data referenced by a scenario) |
Route-level HTTPException |
404 / 409 |
Unknown session/scenario/algorithm/dataset, duplicate tag, name conflict |
| Anything else | 500 |
Unexpected; logged with traceback |
Response shape is always {"detail": "<message>"} — branch on the status
code, not the message text.
For the full reference (including the parameter-descriptor schema and CORS configuration) see the HTTP API reference in the published documentation.
Metadata
Release files for algomancy-api 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| algomancy_api-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for algomancy_api-0.10.0-py3-none-any.whl |
Release files / algomancy_api-0.10.0-py3-none-any.whl
| Download URL | algomancy_api-0.10.0-py3-none-any.whl |
|---|---|
| Size | 19.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ec946a3d8fd97de807118036a5dbbf93ebcb4c46104aed2eb432ce4f7fbe81eb
|
|
BLAKE2b-256 checksum How to use checksums |
386a707840a467b1e59a6289c2d8f1b472e19b83fda07acbe907530313d1a2eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for algomancy-api 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.