Current State
Snapshot
As of 2026-03-30, the backend is a FastAPI sidecar with in-process background job
execution. It exposes the active local workflows for assets, conversion authoring,
saved configs, conversions, jobs, outputs, tags, and dashboard rollups.
All durable state lives in the hephaes workspace (workspace.db) plus local
filesystem storage. The backend no longer has episode, visualization, output-action,
or SQLAlchemy/ORM surfaces.
API Surface
Health
GET /health
Assets
| Method | Route | Description |
|---|---|---|
| POST | /assets/register | Register asset by file path |
| POST | /assets/upload | Upload a raw file into local backend storage and register it |
| POST | /assets/register-dialog | Open the native file dialog and register selected files |
| POST | /assets/scan-directory | Scan a directory for supported asset files |
| POST | /assets/{asset_id}/index | Trigger indexing for one asset |
| POST | /assets/{asset_id}/tags | Attach a tag to an asset |
| DELETE | /assets/{asset_id}/tags/{tag_id} | Detach a tag from an asset |
| POST | /assets/reindex-all | Reindex pending or failed assets |
| GET | /assets | List assets with search, tag, type, status, duration, and start-time filters |
| GET | /assets/{asset_id} | Asset detail with indexed metadata, tags, related jobs, and recent conversions |
Tags
| Method | Route | Description |
|---|---|---|
| GET | /tags | List tag catalog with asset counts |
| POST | /tags | Create a tag |
Conversions
| Method | Route | Description |
|---|---|---|
| POST | /conversions | Create and execute a conversion from a saved config or spec |
| GET | /conversions | List conversion runs with representation-policy filters |
| GET | /conversions/{conversion_id} | Conversion detail with linked job and output files |
| GET | /conversions/capabilities | Capability metadata for authoring and output contracts |
| POST | /conversions/inspect | Inspect asset topics through hephaes |
| POST | /conversions/draft | Generate a draft conversion spec and persist draft history |
| POST | /conversions/preview | Preview sample conversion rows for a spec |
Conversion Configs
| Method | Route | Description |
|---|---|---|
| GET | /conversion-configs | List saved configs |
| POST | /conversion-configs | Create a saved config |
| GET | /conversion-configs/{config_id} | Config detail with revisions and migration notes |
| PATCH | /conversion-configs/{config_id} | Update a saved config |
| POST | /conversion-configs/{config_id}/duplicate | Duplicate a saved config |
Saved configs persist spec documents with immutable revision history. Configs migrate
on load through hephaes and surface upgrade notes in responses.
Jobs
| Method | Route | Description |
|---|---|---|
| GET | /jobs | List jobs with type/status filters |
| GET | /jobs/{job_id} | Job detail with effective representation policy when available |
Job types surfaced today: index, convert. Statuses: queued, running,
succeeded, failed.
Outputs
| Method | Route | Description |
|---|---|---|
| GET | /outputs | List outputs with filters for format, role, asset, conversion, and availability |
| GET | /outputs/{output_id} | Output detail with manifest and artifact metadata |
| GET | /outputs/{output_id}/content | Serve output file content directly when available |
Output roles include datasets, manifests, reports, and other sidecars.
Dashboard
| Method | Route | Description |
|---|---|---|
| GET | /dashboard/summary | Aggregate counts and freshness timestamps |
| GET | /dashboard/trends | Per-day trend buckets for a 1-90 day window |
| GET | /dashboard/blockers | Failed or missing state counts |
Persistence Model
The backend has no separate database layer of its own.
It bootstraps and reads a package-owned workspace that stores:
- registered assets and indexed metadata
- tags and asset/tag associations
- durable jobs and conversion runs
- saved configs and immutable config revisions
- draft heads and draft revisions
- output artifacts
Filesystem storage is split between workspace data, staged uploads, generated outputs, and logs.
Tests
17 test modules under tests/ using pytest with httpx cover:
- asset registration, upload, listing, filtering, and indexing
- conversion authoring APIs (
inspect,draft,preview) - saved config persistence, duplication, and migration notes
- conversion execution and representation-policy handling
- output artifact listing, detail, content serving, and missing-file refresh behavior
- dashboard summary, trends, and blockers
- tags, configuration, sidecar bootstrap, and workspace bootstrapping
Known Limitations
- conversions run on an in-process background runner; there is no external worker queue, cancellation API, or retry API
- no replay, visualization, or output-action endpoints are part of the active backend surface
- some asset list filters such as file size and registration date are still applied client-side in the frontend
- the frontend type layer still carries a few legacy enum and field names even though the routed backend surface is slimmer