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:
SmarterOrchestratorExceptionA run that has taken
maxIterationssteps, and may take no more.
- exception smarter.apps.orchestrator.runtime.OrchestrationRefused(message, status=HTTPStatus.BAD_REQUEST)[source]
Bases:
SmarterOrchestratorExceptionA 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:
SmarterOrchestratorExceptionA step that failed, which ends a sequential run.
- class smarter.apps.orchestrator.runtime.RunContext(run, plan, sessions=<factory>)[source]
Bases:
objectA 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:
harness (
OrchestratorHarness) – The step’s harness.message (
str) – The message to send.
- 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.
- step(harness, message)[source]
Execute one step: check the iterations left and the budgets, call the harness’s LLMClient, and record it.
- Parameters:
harness (
OrchestratorHarness) – The step’s harness.message (
str) – The message to send.
- Return type:
StepOutput- Returns:
What the step produced.
- Raises:
IterationsExhausted – If the run has taken
maxIterationssteps.
- class smarter.apps.orchestrator.runtime.RunPlan(participants, coordinator, summarizer)[source]
Bases:
objectThe harnesses of a run: those that answer, in order, the one that coordinates them, if any, and the summarizer.
In
sequentialandparallel, every active harness but the summarizer answers. Insupervisor, the first active planner coordinates, and inrouter, the first active router; neither answers the objective.- __init__(participants, coordinator, summarizer)
- all()[source]
Return every harness of the plan.
- Return type:
- 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:
- 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:
objectWhat 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:
- 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.
- 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:
- 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.