Runtime

The orchestration runtime: start an Orchestrator’s run, then execute it, one step at a time (ADR-037).

A step is a prompt. It calls its harness LLMClient in-process, with smarter.apps.llmclient.prompting.send_message(), through the same handler as the LLMClient prompt api, as the LLMClient’s owner, in a Prompt session of its own, so that tools, guardrails, the chat history, charges and budgets apply to it exactly as to any other prompt. The user who started the run is each step’s acting user, whom MCP servers learn of.

run = start_run(orchestrator, user_profile, "Prepare the board pack for Q4 2025.")
# a Celery task executes it: execute_orchestration_run.delay(run.pk)
run.refresh_from_db()
run.status, run.result

It runs the sequential, parallel, supervisor and router strategies, and a summarizer harness after any of them. voting and debate are refused, by name.

exception smarter.apps.orchestrator.runtime.IterationsExhausted(message='')[source]

Bases: SmarterOrchestratorException

A run that has taken maxIterations steps, and may take no more.

exception smarter.apps.orchestrator.runtime.OrchestrationRefused(message, status=HTTPStatus.BAD_REQUEST)[source]

Bases: SmarterOrchestratorException

A run that may not start, with the http status that says why.

__init__(message, status=HTTPStatus.BAD_REQUEST)[source]
exception smarter.apps.orchestrator.runtime.OrchestrationStepFailed(message='')[source]

Bases: SmarterOrchestratorException

A step that failed, which ends a sequential run.

class smarter.apps.orchestrator.runtime.RunContext(run, plan, sessions=<factory>)[source]

Bases: object

A run while it executes: its plan, and one Prompt session per harness, so that a harness that answers twice, e.g.

a planner, keeps its conversation.

__init__(run, plan, sessions=<factory>)
plan: RunPlan
required_step(harness, message)[source]

Execute one step whose failure ends the run, e.g. a coordinator’s or the summarizer’s.

Parameters:
Return type:

StepOutput

Returns:

What the step produced.

Raises:

OrchestrationStepFailed – If it failed.

run: OrchestrationRun
session(harness)[source]

Return the harness’s session in this run, a new one the first time.

Parameters:

harness (OrchestratorHarness) – The harness.

Return type:

Prompt

Returns:

The session.

sessions: dict[int, Prompt]
step(harness, message)[source]

Execute one step: check the iterations left and the budgets, call the harness’s LLMClient, and record it.

Parameters:
Return type:

StepOutput

Returns:

What the step produced.

Raises:

IterationsExhausted – If the run has taken maxIterations steps.

class smarter.apps.orchestrator.runtime.RunPlan(participants, coordinator, summarizer)[source]

Bases: object

The harnesses of a run: those that answer, in order, the one that coordinates them, if any, and the summarizer.

In sequential and parallel, every active harness but the summarizer answers. In supervisor, the first active planner coordinates, and in router, the first active router; neither answers the objective.

__init__(participants, coordinator, summarizer)
all()[source]

Return every harness of the plan.

Return type:

list[OrchestratorHarness]

Returns:

The participants, then the coordinator and the summarizer, if any.

coordinator: OrchestratorHarness | None
participant_named(name)[source]

Return the participant whose LLMClient has the name, e.g. a planner’s or a router’s choice.

Parameters:

name (object) – The name, as a coordinator wrote it.

Return type:

OrchestratorHarness | None

Returns:

The participant, or None.

participants: list[OrchestratorHarness]
summarizer: OrchestratorHarness | None
smarter.apps.orchestrator.runtime.SUPPORTED_STRATEGIES = (OrchestrationStrategy.SEQUENTIAL, OrchestrationStrategy.PARALLEL, OrchestrationStrategy.SUPERVISOR, OrchestrationStrategy.ROUTER)

The strategies that this version runs.

The others are refused, by name.

(
    OrchestrationStrategy.SEQUENTIAL,
    OrchestrationStrategy.PARALLEL,
    OrchestrationStrategy.SUPERVISOR,
    OrchestrationStrategy.ROUTER,
)
class smarter.apps.orchestrator.runtime.StepOutput(harness_name, text, failed)[source]

Bases: object

What one step produced: its harness’s name, and the text its LLMClient answered, or why it failed.

__init__(harness_name, text, failed)
failed: bool
harness_name: str
text: str
smarter.apps.orchestrator.runtime.check_may_run(orchestrator, user)[source]

Refuse a run that may not start.

That is an inactive Orchestrator, a strategy that can’t run yet, no harness to answer, no planner for a supervisor or router for a router, or a harness LLMClient that the user may not read. An Orchestrator must not become a way around an account’s sharing, so the user who starts a run must be able to read every LLMClient that it calls (ADR-037).

Parameters:
  • orchestrator (Orchestrator) – The Orchestrator.

  • user (User) – The user who starts the run.

Raises:

OrchestrationRefused – If the run may not start.

Return type:

None

smarter.apps.orchestrator.runtime.execute_run(run_id)[source]

Execute a pending run, and record its result, or why it failed.

A run that isn’t pending is left as it is.

Parameters:

run_id (int) – The run’s id.

Return type:

None

smarter.apps.orchestrator.runtime.plan_run(orchestrator)[source]

Return the plan of a run of the Orchestrator: its active harnesses, by role and execution order.

Parameters:

orchestrator (Orchestrator) – The Orchestrator.

Return type:

RunPlan

Returns:

The plan.

smarter.apps.orchestrator.runtime.start_run(orchestrator, user_profile, objective)[source]

Start a run of the Orchestrator: check that it may start, record it, and queue its execution.

Parameters:
  • orchestrator (Orchestrator) – The Orchestrator.

  • user_profile (UserProfile) – The profile of the user who starts it.

  • objective (str) – What the run is to achieve, e.g. “Prepare the board pack for Q4 2025.”

Return type:

OrchestrationRun

Returns:

The run, pending.

Raises:

OrchestrationRefused – If the run may not start.

smarter.apps.orchestrator.runtime.step_message(objective, earlier, instructions)[source]

Return the one user message that a step sends to its LLMClient.

Parameters:
  • objective (str) – The run’s objective.

  • earlier (list[StepOutput]) – The outputs of the steps that this one builds on, labeled by harness.

  • instructions (str | None) – The harness’s own config.instructions, if any.

Return type:

str

Returns:

The message.