antikythera_orchestrator.api

Classes

ActiveSession dataclass

ActiveSession(
    orchestrator: Orchestrator,
    blueprint_id: str,
    broker_host: str,
    broker_port: int,
    started_at: datetime,
)

Runtime wrapper for a currently active blueprint session.

EndpointStats dataclass

EndpointStats(
    count: int = 0,
    total_ms: float = 0.0,
    min_ms: float = float("inf"),
    max_ms: float = 0.0,
    recent: deque = (lambda: deque(maxlen=MAX_TIMING_HISTORY))(),
)

Aggregated statistics for an endpoint.

SessionInfo

Response model for listing sessions.

TimingRecord dataclass

TimingRecord(
    timestamp: datetime, method: str, path: str, duration_ms: float, status_code: int
)

A single request timing measurement.

Functions:

delete_model

delete_model(model_id: str) -> DeleteModelResponse

Delete a model from the database.

Parameters:

• model_id (str) –

  The ID of the model to delete.

Returns:

• DeleteModelResponse –

  Response containing the model ID and success message.

Raises:

• HTTPException –

  If the model is not found or cannot be deleted.

get_blueprint

get_blueprint(blueprint_id: str)

Retrieve a blueprint by its ID.

If the blueprint is currently active in a session, the active (possibly expanded) version is returned. Otherwise, the stored version is returned.

Parameters:

• blueprint_id (str) –

  The ID of the blueprint to retrieve.

Returns:

• Response –

  The blueprint data as a JSON response.

Raises:

• HTTPException –

  If the blueprint is not found.

get_blueprint_context

get_blueprint_context(session_id: str, blueprint_id: str)

Get the context for a specific blueprint within a session.

blueprint_id must be of a dynamically expanded composite blueprint.

Parameters:

• session_id (str) –

  The ID of the session.

• blueprint_id (str) –

  The ID of the blueprint to get context for.

Returns:

• Response –

  The blueprint context as a JSON response.

Raises:

• HTTPException –

  If the session or blueprint is not found.

get_model

get_model(model_id: str)

Retrieve a model by its ID.

Parameters:

• model_id (str) –

  The ID of the model to retrieve.

Returns:

• Response –

  The model data as a JSON response.

Raises:

• HTTPException –

  If the model is not found.

get_running_composites

get_running_composites(session_id: str)

Get the IDs of all composite blueprints in a session that currently have running tasks.

Parameters:

• session_id (str) –

  The ID of the session.

Returns:

• Response –

  A JSON response containing a list of composite blueprint IDs with running tasks.

Raises:

• HTTPException –

  If the session is not found.

get_session_details

get_session_details(session_id: str)

Retrieve full details of a session including blueprints and parameters.

Parameters:

• session_id (str) –

  The ID of the session to retrieve.

Returns:

• Response –

  The session data as a JSON response.

Raises:

• HTTPException –

  If the session is not found.

get_timing_metrics

get_timing_metrics()

Returns timing statistics for all API endpoints.

list_models

list_models() -> list[str]

List all available model IDs.

Returns:

• list[str] –

  A list of model IDs.

restart_session

restart_session(session_id: str) -> StartBlueprintResponse

Run a finished session's blueprint again as a brand new session.

A finished session is the record of a run, so restarting never rewinds it: the original keeps its task states and data store, and the re-run gets a fresh session ID which the caller is expected to follow.

The blueprint is re-read from blueprint storage rather than copied off the old session, whose own copy carries the finished task states and the dynamic tasks expanded during the run that just ended.

stream_session_events async

stream_session_events(session_id: str)

Server-Sent Events stream for real-time session and task state updates.

Emits task_state_changed and session_state_changed events as the session progresses. The connection stays open until the session reaches a terminal state or the client disconnects.

timing_middleware async

timing_middleware(request: Request, call_next)

Middleware to record and log request timing.

upload_blueprint async

upload_blueprint(file: UploadFile) -> UploadBlueprintResponse

Upload a blueprint JSON file to the database.

Parameters:

• file (UploadFile) –

  The blueprint JSON file to upload.

Returns:

• UploadBlueprintResponse –

  Response containing the blueprint ID and success message.

Raises:

• HTTPException –

  400 if the file is not JSON, cannot be parsed, or fails the dataflow check (the detail then carries a problems list).

upload_model async

upload_model(file: UploadFile) -> UploadModelsResponse

Upload a model JSON file to the database.

Parameters:

• file (UploadFile) –

  The model JSON file to upload.

Returns:

• UploadModelResponse –

  Response containing the model ID and success message.

Raises:

• HTTPException –

  If the file is not a JSON file or cannot be parsed.