> For the complete documentation index, see [llms.txt](https://docs.cortensor.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortensor.network/community-and-ecosystem/products-and-agents/pyclaw/diagrams.md). # Diagrams Below are exportable ASCII diagrams (copy/paste) covering architecture, runtime flow, context packing, skill flow, tool policy approvals, telemetry, and V2 multi-agent slots. *** ### 1) System overview (modules + boundaries) ``` +------------------------------+ | Channels / Inputs | | CLI | Telegram | Others | +--------------+---------------+ | v +--------------------------+ | openminion-controlplane | | adapters + routing | +------------+-------------+ | v +-------------------------------------------------------------------+ | openminion-runtime | | orchestrates turn: session -> context -> llm -> policy -> tool | +----+-----------+-----------+------------+------------+-------------+ | | | | | v v v v v +---------+ +---------+ +--------+ +---------+ +--------+ | session | | context | | llm | | policy | | tool | +----+----+ +----+----+ +---+----+ +----+----+ +---+----+ | | | | | | | | | +-------------------+ | | | | | | | | | +---------v---------+ | | | | | tool plugins | | | | | | exec/browser/... | | | | | +-------------------+ | | | +--------------------+ | | v v +---------+ +-----------+ +-----------+ +-----------+ | compress| | skill | | memory | | identity | +---------+ +-----------+ +-----------+ +-----------+ (optional sidecar) +-------------------+ | openminion-telemetry | +-------------------+ ``` *** ### 2) Runtime “turn” flow (single turn, potentially multiple packs) ``` User Input | v controlplane.receive() | v runtime.run_turn(session_id, agent_id) | +--> session.next_turn_id() -> turn_id +--> trace_id = uuid() +--> session.append(user.message) | +--> (optional) identity.get_capsule() +--> (optional) memory.retrieve() +--> (optional) skill.shortlist() +--> (optional) skill.select + skill.expand() | v PACK LOOP (pack_id = t{turn_id}-pN) | +--> context.build_pack(...) | | | +--> (optional) telemetry.emit(context.pack) | +--> llm.complete(prompt_view) | | | +--> (optional) telemetry.emit(llm.usage) | +--> if LLM returns TOOL_CALL: | session.append(tool.request) | policy.authorize() | | | +--> NEEDS_APPROVAL --> return PendingAction to controlplane | | | +--> ALLOW --> tool.execute() --> session.append(tool.result) --> loop | | | +--> DENY --> session.append(tool.result: denied) --> (loop or stop) | +--> else FINAL_ANSWER: session.append(agent.message) compress.maybe_summarize() telemetry.emit(turn.outcome) return response ``` *** ### 3) Context packing (how PromptView is assembled under budget) ``` Inputs: - identity capsule (small) - session summary (small) - recent messages (bounded K) - memory snippets (bounded top-N) - skill cards shortlist (bounded top-N) - selected skill excerpt (optional, bounded) - tool digest (minimal) context.build_pack() | v [1] establish budgets total_budget reserved_budget (system + tool overhead) available_budget | v [2] build sections in priority order 1 system 2 identity 3 task directive (latest user intent) 4 summary 5 recent messages 6 memory snippets 7 skill cards 8 selected skill excerpt (if any) 9 tool digest | v [3] enforce caps - trim sections by rules - drop low priority sections if needed - record truncations/drops | v PromptView (bounded) -> sent to LLM | +--> telemetry: ContextPackReport (tokens, drops, truncations, composition) ``` *** ### 4) Skill integration flow (many skills → shortlist → one expanded) ``` All skills (many SKILL.md) | v openminion-skill.index -> SkillCards (tiny metadata) | v skill.shortlist(query=intent, tools_available, N) -> top SkillCards | v context.attach_skill_cards(SkillCards) (bounded) | v brain/runtime selects skill_id or NONE | +--> if selected: | skill.expand(skill_id, goal, max_tokens=M) | context.attach_selected_skill(excerpt) (bounded) | session.append(skill.selected) | v LLM uses skill excerpt to plan + call tools reliably ``` *** ### 5) Tool execution + policy approvals (approve once / window / forever) ``` LLM TOOL_CALL (tool_name, args) | v runtime -> session.append(tool.request) | v policy.authorize(tool_name, risk, scopes, args_summary) | +--> ALLOW | | | v | runtime -> tool.execute() | | | v | session.append(tool.result) | | | v | back to pack loop | +--> NEEDS_APPROVAL | | | v | return PendingAction: | - approve once | - approve for time window | - approve until revoked | - deny | +--> DENY | v session.append(tool.result: denied) (runtime loops for alternative plan OR stops based on config) ``` *** ### 6) Telemetry flow (context-focused, per pack + per turn) ``` context.build_pack(pack_id) | +--> emit: context.pack | - token budget + usage estimate | - section breakdown | - drops/truncations + reasons | llm.complete(pack_id) | +--> emit: llm.usage | - actual tokens (if provided) | - latency, model/provider | runtime ends turn | +--> emit: turn.outcome - packs used - tool calls count - status ok/retry/error/blocked - total latency Sinks: - sqlite (default) - jsonl (debug) - otel (future) ``` *** ### 7) Session durability (full history preserved; prompt stays compact) ``` Session Store (SQLite, append-only) - stores ALL events forever (or retention policy) - user/agent messages - tool req/result - skill selection refs - summaries - memory refs PromptView (context output) - only selected subset: identity + summary + recent window + top memory + skill card(s) + tool digest - bounded by token budget => Full history is preserved in session, but only compact view is sent to LLM. ``` *** ### 8) V2 slots (daemon + registry + local/remote + multi-agent) ``` +---------------------+ | openminion-registry | | discover agents | +----------+----------+ | +-----------+-----------+ | | v v +-------------------+ +-------------------+ | agent daemon A | | agent daemon B | | openminion-runtime| | openminion-runtime| +---------+---------+ +---------+---------+ | | +----------+------------+ | v openminion-a2a (V2) - local queue (V1) - remote RPC/MCP (V2) - auth/signing (V2) ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cortensor.network/community-and-ecosystem/products-and-agents/pyclaw/diagrams.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.