Sub-kani Orchestration¶

Sub-kanis are smaller agents spawned by the main agent to handle delegated tasks. When the user requests a multi-step build (e.g. “find gametocyte genes and subtract housekeeping”), the agent calls delegate_strategy_subtasks. The orchestrator spawns one SubtaskAgent per task, runs them in dependency order, and creates combine steps to link results.

Orchestrator¶

Purpose: Implement the delegate_strategy_subtasks logic. Validates the plan, spawns sub-agents, runs tasks with dependencies, creates combine steps, emits subkani events.

Key function: veupath_chatbot.ai.orchestration.subkani.orchestrator.delegate_strategy_subtasks()

Flow:

Build and validate veupath_chatbot.ai.orchestration.delegation.DelegationPlan from the nested plan.
Create or get the strategy graph.
For each task node (in dependency order): - Run veupath_chatbot.ai.orchestration.subkani.orchestrator.run_subkani_task() — spawn SubtaskAgent, pass dependency context. - Collect step IDs from results.
For each combine node, create the combine step via strategy_tools.
Emit subkani_task_start, subkani_tool_call_*, subkani_task_end.

Sub-kani orchestration (dependency scheduling + retries).

This module extracts the “spawn sub-agents, run tasks with dependencies, emit events” workflow out of the main agent runtime to keep concerns separated.

async veupath_chatbot.ai.orchestration.subkani.orchestrator.run_subkani_task(*, task, goal, site_id, strategy_session, graph_id, dependency_context, chat_history, emit_event, subkani_timeout_seconds, engine_factory=None)[source]¶

Return type:: JSONObject

async veupath_chatbot.ai.orchestration.subkani.orchestrator.delegate_strategy_subtasks(*, goal, site_id, strategy_session, strategy_tools, emit_event, chat_history, plan=None, engine_factory=None)[source]¶

Return type:: JSONObject

Subtask Scheduler¶

Purpose: Run task nodes with dependency ordering. Uses topological sort so that nodes run only after their dependencies complete.

Key functions: veupath_chatbot.ai.orchestration.scheduler.run_nodes_with_dependencies(), veupath_chatbot.ai.orchestration.scheduler.partition_task_results()

Run delegation graph nodes respecting dependency ordering.

async veupath_chatbot.ai.orchestration.scheduler.run_nodes_with_dependencies(*, nodes_by_id, dependents, max_concurrency, run_node, format_dependency_context, results_by_id=None)[source]¶

Execute nodes concurrently while honoring their depends_on edges.

Return type:: tuple[JSONArray, dict[str, JSONObject]]

veupath_chatbot.ai.orchestration.scheduler.partition_task_results(results)[source]¶

Split results into validated and rejected, preserving stable shape.

Parameters:: results (JSONArray) – Results array.
Return type:: tuple[JSONArray, JSONArray]

Sub-kani Prompts¶

Purpose: Prompt construction for sub-kani execution rounds. Composes task descriptions, goals, graph context, and dependency rules into execution prompts.

Prompt builders for sub-kani execution.

veupath_chatbot.ai.orchestration.subkani.prompts.build_subkani_round_prompt(*, task, goal, graph_id, dependency_context)[source]¶

Return type:: str

Sub-kani Utilities¶

Purpose: Utilities for coordinating sub-kani task execution. Parses sub-kani responses, extracts created steps, manages token counting and error aggregation.

Key types: SubKaniRoundResult – Captures token usage, created step IDs, and errors from a sub-kani round.

Utilities for coordinating sub-kani task execution.

class veupath_chatbot.ai.orchestration.subkani.utils.SubKaniRoundResult[source]¶

Bases: object

Result of a sub-kani round, including token usage.

__init__()[source]¶

response_text: str | None¶

created_steps: JSONArray¶

errors: list[str]¶

prompt_tokens: int¶

completion_tokens: int¶

llm_call_count: int¶

async veupath_chatbot.ai.orchestration.subkani.utils.consume_subkani_round(*, sub_kani, emit_event, task, round_prompt)[source]¶

Run a sub-kani round and collect created steps + error strings.

Also tracks token usage from the sub-kani’s assistant messages. Returns the accumulated result via module-level _last_round_result.

Return type:: tuple[str | None, JSONArray, list[str]]

veupath_chatbot.ai.orchestration.subkani.utils.get_round_result(task)[source]¶

Get the last round result for a task (includes token usage).

Return type:: SubKaniRoundResult | None

veupath_chatbot.ai.orchestration.subkani.utils.format_dependency_context(*, task_id, tasks_by_id, results_by_id)[source]¶

Format dependency context for a subtask prompt.

Parameters:

task_id (str) – Task ID to format context for.
tasks_by_id (dict[str, JSONObject]) – Map of task ID to task data.
results_by_id (dict[str, JSONObject]) – Map of task ID to result data.

Returns:

Formatted context string or None.

Return type:

str | None

veupath_chatbot.ai.orchestration.subkani.utils.format_task_context(context)[source]¶

Format optional per-task context for a subtask prompt.

Parameters:: context (JSONValue) – Context value.
Return type:: str | None

veupath_chatbot.ai.orchestration.subkani.utils.extract_primary_step_id(result)[source]¶

Pick the subtree root from a subtask result.

Prefers the subtreeRoot field (set by the tree-first contract enforcement in the orchestrator). Falls back to the last created step ID when subtreeRoot is not set (e.g. combine results).

Parameters:: result (JSONObject | None) – JSONObject | None.
Return type:: str | None