{ "cells": [ { "cell_type": "markdown", "id": "812c8b84", "metadata": { "papermill": { "duration": 0.005001, "end_time": "2026-05-27T11:41:59.202245+00:00", "exception": false, "start_time": "2026-05-27T11:41:59.197244+00:00", "status": "completed" }, "tags": [] }, "source": [ "# 11 · Meta-Controller — LLM router that picks the right *architecture* per task\n", "\n", "> **TL;DR.** A router LLM classifies each incoming task and dispatches to the **most appropriate architecture** from a roster — `ToolUse` for one-shot lookups, `ReAct` for multi-hop research, `Planning` for decomposable comparisons, `Reflection` for quality-sensitive writing/code, etc. This is the **most composable** architecture in the repo: every other architecture is treated as a black-box callable via the common `Architecture.run(task)` contract.\n", ">\n", "> **Reach for it when** you serve a mix of task types and no single architecture is the right default for all of them (a real user-facing AI product almost always).\n", "> **Avoid when** all your tasks are the same shape — a fixed architecture is cheaper and more predictable.\n", "\n", "| Property | Value |\n", "|---|---|\n", "| Origin | RouterChain / LangChain LCEL `RunnableBranch` pattern |\n", "| Coordination | Single routing LLM call → dispatch to chosen architecture |\n", "| External tools needed? | Depends on the routed architecture |\n", "| Cost | 1 router call + 1 architecture run (the architecture may itself make many calls) |\n", "| Composability | **Highest** — uses every other architecture as a black box |\n", "\n", "This is the first notebook that fully exploits the `Architecture` base class's `run(task)` contract. The router treats `Reflection`, `ToolUse`, `ReAct`, and `Planning` as interchangeable black boxes." ] }, { "cell_type": "markdown", "id": "4363a83a", "metadata": { "papermill": { "duration": 0.003001, "end_time": "2026-05-27T11:41:59.210101+00:00", "exception": false, "start_time": "2026-05-27T11:41:59.207100+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 2 · Architecture at a glance\n", "\n", "```mermaid\n", "flowchart LR\n", " A([task]) --> R[Route
LLM with structured-output
Literal[arch names]]\n", " R --> X{which arch?}\n", " X -->|tool_use| T[ToolUse.run]\n", " X -->|react| Re[ReAct.run]\n", " X -->|planning| P[Planning.run]\n", " X -->|reflection| Rf[Reflection.run]\n", " T --> Z([answer])\n", " Re --> Z\n", " P --> Z\n", " Rf --> Z\n", "\n", " style R fill:#fff3e0,stroke:#f57c00\n", " style X fill:#fce4ec,stroke:#c2185b\n", "```\n", "\n", "**Two real nodes**: a Router that classifies the task and an Execute node that dispatches to the chosen sub-architecture. The four leaf boxes aren't graph nodes — they're external `Architecture` instances called from inside `_execute`." ] }, { "cell_type": "markdown", "id": "4f06eaae", "metadata": { "papermill": { "duration": 0.003, "end_time": "2026-05-27T11:41:59.217105+00:00", "exception": false, "start_time": "2026-05-27T11:41:59.214105+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 3 · Theory\n", "\n", "### 3.1 · Why route at all?\n", "\n", "Different tasks have different shapes. \"What's the population of France?\" needs one tool call, not a 3-step plan. \"Write a polished Python function\" needs Reflection's iterate-on-draft loop, not a tool call. \"Compare X and Y on dimensions A, B, C\" needs Planning's decomposition, not a single ReAct step.\n", "\n", "A fixed architecture is the *wrong default* for some fraction of incoming tasks. Meta-Controller picks the right one per task — at the cost of one extra LLM call per request.\n", "\n", "### 3.2 · Routing as structured output\n", "\n", "The router uses `with_structured_output` with a **dynamic Literal** built from the actual roster:\n", "\n", "```python\n", "next_t = Literal[tuple(self.roster.keys())]\n", "RouterDecision = create_model(\n", " \"RouterDecision\",\n", " chosen_arch=(next_t, Field(description=\"...\")),\n", " reason=(str, Field(description=\"One sentence why\")),\n", ")\n", "```\n", "\n", "This is the same dynamic-schema pattern Multi-Agent (notebook 05) uses for its Supervisor. The dynamic Literal means the router *cannot* hallucinate an architecture that isn't in the roster.\n", "\n", "### 3.3 · The composability win — every architecture is a callable\n", "\n", "Every architecture in this library subclasses `Architecture` (defined in `architectures/base.py`):\n", "\n", "```python\n", "class Architecture(ABC):\n", " @abstractmethod\n", " def run(self, task: str) -> ArchitectureResult: ...\n", "```\n", "\n", "That single contract is what makes Meta-Controller possible. The router doesn't know whether it's calling `Reflection` or `ReAct` or `Planning` — it just calls `.run(task)` and gets back an `ArchitectureResult` with `.output`. Adding a new architecture to the roster is one line.\n", "\n", "This is the same design idea that lets a Unix shell pipe `find` into `grep` into `wc` — common interface, infinite composition.\n", "\n", "### 3.4 · Where Meta-Controller sits\n", "\n", "| Pattern | Routes between | Cost |\n", "|---|---|---|\n", "| Multi-Agent (nb 05) | role-specialised **agents** | 1 supervisor call + N specialist sub-runs |\n", "| Blackboard (nb 07) | role-specialised agents (self-electing) | N bid calls + 1 sub-run per round |\n", "| **Meta-Controller** *(this notebook)* | **whole architectures** | **1 route call + 1 architecture run** |\n", "| Adaptive RAG (nb 26) | retrieval strategies | 1 route + 1 retrieval pipeline |\n", "| Ensemble (nb 13) | nothing — runs all in parallel | N × architecture runs + aggregator |\n", "\n", "The choice between Meta-Controller and Multi-Agent: **route by task-shape (Meta-Controller) when different *patterns* fit different tasks. Route by domain-expertise (Multi-Agent) when different *specialists* know different facts.**\n", "\n", "### 3.5 · What goes wrong (you'll see in § 9)\n", "\n", "1. **Wrong route.** Router picks ReAct for a task that needs Reflection (or vice versa). The downstream architecture then does the wrong job. Mitigation: tighter architecture descriptions; or fall back to Reflection-after-routing.\n", "2. **Router preference bias.** Llama tends to pick `react` or `planning` for almost everything because they \"sound\" more agentic. Watch §9 routing distribution across diverse tasks.\n", "3. **Cost blowup.** A Planning route can itself make 20+ LLM calls. The router is cheap; the route target may not be.\n", "4. **No retry on route failure.** If the chosen architecture returns garbage, Meta-Controller doesn't re-route. Extension idea: wrap with PEV (nb 06) for retry.\n" ] }, { "cell_type": "markdown", "id": "c60e7687", "metadata": { "papermill": { "duration": 0.003189, "end_time": "2026-05-27T11:41:59.224292+00:00", "exception": false, "start_time": "2026-05-27T11:41:59.221103+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 4 · Setup" ] }, { "cell_type": "code", "execution_count": 1, "id": "38ec09a0", "metadata": { "execution": { "iopub.execute_input": "2026-05-27T11:41:59.236855Z", "iopub.status.busy": "2026-05-27T11:41:59.236855Z", "iopub.status.idle": "2026-05-27T11:42:01.459921Z", "shell.execute_reply": "2026-05-27T11:42:01.459921Z" }, "papermill": { "duration": 2.232622, "end_time": "2026-05-27T11:42:01.460924+00:00", "exception": false, "start_time": "2026-05-27T11:41:59.228302+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "data": { "text/html": [ "
Provider: nebius  ·  Model: meta-llama/Llama-3.3-70B-Instruct ─────────────────────────────────────────────────────\n",
       "
\n" ], "text/plain": [ "\u001b[1;36mProvider: nebius · Model: meta-llama/Llama-\u001b[0m\u001b[1;36m3.3\u001b[0m\u001b[1;36m-70B-Instruct\u001b[0m \u001b[92m─────────────────────────────────────────────────────\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
Default roster: tool_use, react, planning, reflection                                                              \n",
       "
\n" ], "text/plain": [ "Default roster: \u001b[1mtool_use, react, planning, reflection\u001b[0m \n" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from agentic_architectures import get_llm, enable_langsmith, settings\n", "from agentic_architectures.architectures import MetaController\n", "from agentic_architectures.architectures.meta_controller import ARCHITECTURE_DESCRIPTIONS\n", "from agentic_architectures.ui import print_md, print_header, print_step\n", "\n", "enable_langsmith()\n", "print_header(f\"Provider: {settings.llm_provider} · Model: {settings.llm_model}\")\n", "print_md(f\"Default roster: **{', '.join(ARCHITECTURE_DESCRIPTIONS.keys())}**\")" ] }, { "cell_type": "markdown", "id": "cc61eeee", "metadata": { "papermill": { "duration": 0.003997, "end_time": "2026-05-27T11:42:01.470108+00:00", "exception": false, "start_time": "2026-05-27T11:42:01.466111+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 5 · Library walkthrough\n", "\n", "Source: [`src/agentic_architectures/architectures/meta_controller.py`](../src/agentic_architectures/architectures/meta_controller.py).\n", "\n", "Three key pieces:\n", "\n", "1. **`_default_roster(llm)`** — builds the default `dict[str, Architecture]` with sane budgets for each architecture (`ToolUse(max_rounds=3)`, `Planning(max_replans=1)`, etc.). Override at construction time to use a custom roster.\n", "2. **`ARCHITECTURE_DESCRIPTIONS`** — the only thing the router sees about each architecture. These descriptions are the steering signal; if you change them, routing changes.\n", "3. **`_route`** — calls a dynamic-Literal structured-output schema. The router's `chosen_arch` field is constrained to roster keys at runtime.\n", "4. **`_execute`** — looks up `self.roster[chosen_arch]` and calls its `.run(task)`. Architecture composability in one line." ] }, { "cell_type": "code", "execution_count": 2, "id": "8966e21c", "metadata": { "execution": { "iopub.execute_input": "2026-05-27T11:42:01.479629Z", "iopub.status.busy": "2026-05-27T11:42:01.478617Z", "iopub.status.idle": "2026-05-27T11:42:01.492144Z", "shell.execute_reply": "2026-05-27T11:42:01.492144Z" }, "papermill": { "duration": 0.021045, "end_time": "2026-05-27T11:42:01.494160+00:00", "exception": false, "start_time": "2026-05-27T11:42:01.473115+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Architecture descriptions the router sees:\n", "\n", " --- tool_use ---\n", " One-shot fact lookup using web search. Best for: 'What is X?' / 'Who founded Y?' / 'Current price of Z?'. Single tool call usually suffices.\n", "\n", " --- react ---\n", " Multi-hop research with explicit Thought before each Action. Best for: questions that require chaining multiple lookups where each step depends on the previous result (e.g. 'When did the CEO of X's company join Y?').\n", "\n", " --- planning ---\n", " Decompose a task into ordered steps upfront, execute each. Best for: comparisons, multi-aspect reports, anything with obvious decomposition (e.g. 'Compare X and Y on dimensions A, B, C').\n", "\n", " --- reflection ---\n", " Generate → critique → refine loop. NO external tools. Best for: quality-sensitive creative or code tasks where the model should iterate (e.g. 'Write a Python function that ...', 'Polish this paragraph').\n" ] } ], "source": [ "from agentic_architectures.architectures.meta_controller import ARCHITECTURE_DESCRIPTIONS\n", "print('Architecture descriptions the router sees:')\n", "for name, desc in ARCHITECTURE_DESCRIPTIONS.items():\n", " print(f'\\n --- {name} ---')\n", " print(f' {desc}')" ] }, { "cell_type": "markdown", "id": "e7c5d896", "metadata": { "papermill": { "duration": 0.004014, "end_time": "2026-05-27T11:42:01.502448+00:00", "exception": false, "start_time": "2026-05-27T11:42:01.498434+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 6 · State\n", "\n", "| Field | Type | Set by |\n", "|---|---|---|\n", "| `task` | `str` | caller |\n", "| `chosen_arch` | `str` | `_route` |\n", "| `routing_reason` | `str` | `_route` |\n", "| `sub_result` | `dict` (output + metadata + arch name) | `_execute` |" ] }, { "cell_type": "markdown", "id": "42fbd2a6", "metadata": { "papermill": { "duration": 0.003615, "end_time": "2026-05-27T11:42:01.510089+00:00", "exception": false, "start_time": "2026-05-27T11:42:01.506474+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 7 · Build the graph" ] }, { "cell_type": "code", "execution_count": 3, "id": "306232ea", "metadata": { "execution": { "iopub.execute_input": "2026-05-27T11:42:01.520979Z", "iopub.status.busy": "2026-05-27T11:42:01.520232Z", "iopub.status.idle": "2026-05-27T11:42:05.441265Z", "shell.execute_reply": "2026-05-27T11:42:05.440271Z" }, "papermill": { "duration": 3.928157, "end_time": "2026-05-27T11:42:05.442265+00:00", "exception": false, "start_time": "2026-05-27T11:42:01.514108+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from IPython.display import Image, display\n", "arch = MetaController()\n", "graph = arch.build()\n", "display(Image(graph.get_graph().draw_mermaid_png()))" ] }, { "cell_type": "markdown", "id": "474351b2", "metadata": { "papermill": { "duration": 0.004349, "end_time": "2026-05-27T11:42:05.453615+00:00", "exception": false, "start_time": "2026-05-27T11:42:05.449266+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 8 · Live run — route **four** diverse tasks\n", "\n", "The four tasks below are deliberately different shapes — each should route to a different architecture. This is Meta-Controller's signature demo: same input format, four different downstream architectures." ] }, { "cell_type": "code", "execution_count": 4, "id": "78e04b11", "metadata": { "execution": { "iopub.execute_input": "2026-05-27T11:42:05.464186Z", "iopub.status.busy": "2026-05-27T11:42:05.464186Z", "iopub.status.idle": "2026-05-27T11:45:06.691044Z", "shell.execute_reply": "2026-05-27T11:45:06.691044Z" }, "papermill": { "duration": 181.236724, "end_time": "2026-05-27T11:45:06.694698+00:00", "exception": false, "start_time": "2026-05-27T11:42:05.457974+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "data": { "text/html": [ "
› [Q1] → routed to: TOOL_USE\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m[\u001b[0m\u001b[1mQ1\u001b[0m\u001b[1m]\u001b[0m\u001b[1m → routed to: TOOL_USE\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
What is the latest stable version of Rust as of today?\n",
       "
\n" ], "text/plain": [ "What is the latest stable version of Rust as of today?\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     reason\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m reason\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
This task requires a one-shot fact lookup to find the latest stable version of Rust as of today.\n",
       "
\n" ], "text/plain": [ "This task requires a one-shot fact lookup to find the latest stable version of Rust as of today.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     output (truncated)\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m output \u001b[0m\u001b[1m(\u001b[0m\u001b[1mtruncated\u001b[0m\u001b[1m)\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
The latest stable version of Rust as of today is not explicitly stated in the search results. However, the first \n",
       "result from the Rust Programming Language Forum mentions the release of dtact v0.2.2 and rssn-advanced v0.1.0, \n",
       "which may indicate that the latest stable version of Rust is not specified i\n",
       "
\n" ], "text/plain": [ "The latest stable version of Rust as of today is not explicitly stated in the search results. However, the first \n", "result from the Rust Programming Language Forum mentions the release of dtact v0.\u001b[1;36m2.2\u001b[0m and rssn-advanced v0.\u001b[1;36m1.0\u001b[0m, \n", "which may indicate that the latest stable version of Rust is not specified i\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] }, { "data": { "text/html": [ "
› [Q2] → routed to: REFLECTION\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m[\u001b[0m\u001b[1mQ2\u001b[0m\u001b[1m]\u001b[0m\u001b[1m → routed to: REFLECTION\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
Write a Python function that returns the n-th Fibonacci number, optimized for n up to 10^6.\n",
       "
\n" ], "text/plain": [ "Write a Python function that returns the n-th Fibonacci number, optimized for n up to \u001b[1;36m10\u001b[0m^\u001b[1;36m6\u001b[0m.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     reason\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m reason\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
This task requires generating and refining code to solve a specific problem, which is best suited for the \n",
       "reflection architecture.\n",
       "
\n" ], "text/plain": [ "This task requires generating and refining code to solve a specific problem, which is best suited for the \n", "reflection architecture.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     output (truncated)\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m output \u001b[0m\u001b[1m(\u001b[0m\u001b[1mtruncated\u001b[0m\u001b[1m)\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
## Optimized Fibonacci Function in Python\n",
       "### Overview\n",
       "\n",
       "The Fibonacci sequence is a series of numbers where a number is the addition of the last two numbers, starting with\n",
       "0 and 1. This function uses matrix exponentiation to efficiently calculate the n-th Fibonacci number, making it \n",
       "suitable for lar\n",
       "
\n" ], "text/plain": [ "## Optimized Fibonacci Function in Python\n", "### Overview\n", "\n", "The Fibonacci sequence is a series of numbers where a number is the addition of the last two numbers, starting with\n", "\u001b[1;36m0\u001b[0m and \u001b[1;36m1\u001b[0m. This function uses matrix exponentiation to efficiently calculate the n-th Fibonacci number, making it \n", "suitable for lar\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] }, { "data": { "text/html": [ "
› [Q3] → routed to: PLANNING\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m[\u001b[0m\u001b[1mQ3\u001b[0m\u001b[1m]\u001b[0m\u001b[1m → routed to: PLANNING\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
Compare the population, GDP, and area of Japan and Germany. Pick which is larger on each dimension.\n",
       "
\n" ], "text/plain": [ "Compare the population, GDP, and area of Japan and Germany. Pick which is larger on each dimension.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     reason\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m reason\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
This task requires comparing multiple aspects of two countries, which can be decomposed into ordered steps upfront,\n",
       "making planning the most suitable architecture.\n",
       "
\n" ], "text/plain": [ "This task requires comparing multiple aspects of two countries, which can be decomposed into ordered steps upfront,\n", "making planning the most suitable architecture.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     output (truncated)\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m output \u001b[0m\u001b[1m(\u001b[0m\u001b[1mtruncated\u001b[0m\u001b[1m)\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
Japan has a larger GDP than Germany. However, the population and area of Japan and Germany cannot be compared as \n",
       "the necessary information is not available.\n",
       "
\n" ], "text/plain": [ "Japan has a larger GDP than Germany. However, the population and area of Japan and Germany cannot be compared as \n", "the necessary information is not available.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] }, { "data": { "text/html": [ "
› [Q4] → routed to: REACT\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m[\u001b[0m\u001b[1mQ4\u001b[0m\u001b[1m]\u001b[0m\u001b[1m → routed to: REACT\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
Who founded OpenAI, and which company did its CEO previously co-found before joining OpenAI?\n",
       "
\n" ], "text/plain": [ "Who founded OpenAI, and which company did its CEO previously co-found before joining OpenAI?\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     reason\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m reason\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
This task requires chaining multiple lookups where each step depends on the previous result, making the react \n",
       "architecture the best fit.\n",
       "
\n" ], "text/plain": [ "This task requires chaining multiple lookups where each step depends on the previous result, making the react \n", "architecture the best fit.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
›     output (truncated)\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1m output \u001b[0m\u001b[1m(\u001b[0m\u001b[1mtruncated\u001b[0m\u001b[1m)\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
Thought: Based on the information gathered, it appears that Sam Altman, the CEO of OpenAI, co-founded a company \n",
       "called Loopt before joining OpenAI. Loopt was a location-based social networking service that allowed users to \n",
       "share their real-time locations with friends. This information can be used to\n",
       "
\n" ], "text/plain": [ "Thought: Based on the information gathered, it appears that Sam Altman, the CEO of OpenAI, co-founded a company \n", "called Loopt before joining OpenAI. Loopt was a location-based social networking service that allowed users to \n", "share their real-time locations with friends. This information can be used to\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] }, { "data": { "text/html": [ "
Routing distribution across the 4 tasks ───────────────────────────────────────────────────────────────────────────\n",
       "
\n" ], "text/plain": [ "\u001b[1;36mRouting distribution across the \u001b[0m\u001b[1;36m4\u001b[0m\u001b[1;36m tasks\u001b[0m \u001b[92m───────────────────────────────────────────────────────────────────────────\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ " tool_use: 1\n", " reflection: 1\n", " planning: 1\n", " react: 1\n" ] } ], "source": [ "TASKS = [\n", " (\"Q1\", \"What is the latest stable version of Rust as of today?\"),\n", " (\"Q2\", \"Write a Python function that returns the n-th Fibonacci number, optimized for n up to 10^6.\"),\n", " (\"Q3\", \"Compare the population, GDP, and area of Japan and Germany. Pick which is larger on each dimension.\"),\n", " (\"Q4\", \"Who founded OpenAI, and which company did its CEO previously co-found before joining OpenAI?\"),\n", "]\n", "\n", "results = []\n", "for tag, task in TASKS:\n", " r = arch.run(task)\n", " results.append((tag, task, r))\n", " print_step(f\"[{tag}] → routed to: {r.metadata['chosen_arch'].upper()}\", task[:120])\n", " print_step(\" reason\", r.metadata['routing_reason'])\n", " print_step(\" output (truncated)\", r.output[:300])\n", " print()\n", "\n", "print_header(\"Routing distribution across the 4 tasks\")\n", "from collections import Counter\n", "dist = Counter(r.metadata['chosen_arch'] for _, _, r in results)\n", "for arch_name, n in dist.most_common():\n", " print(f\" {arch_name}: {n}\")" ] }, { "cell_type": "markdown", "id": "fecc07fa", "metadata": { "papermill": { "duration": 0.012415, "end_time": "2026-05-27T11:45:06.719583+00:00", "exception": false, "start_time": "2026-05-27T11:45:06.707168+00:00", "status": "completed" }, "tags": [] }, "source": [ "### 8.0 · What just happened, briefly\n", "\n", "Three things to inspect:\n", "\n", "- **Routing diversity.** If all 4 tasks routed to the same architecture, the router has a preference bias (see § 3.5). Healthy: 3-4 distinct architectures chosen across 4 diverse tasks.\n", "- **Routing quality.** Read the reasons — are they specific to the task, or generic? Generic reasons suggest the router doesn't really understand the architectures.\n", "- **Output quality vs route.** Did the chosen architecture's output actually fit the task? A correctly-routed task should produce a *recognisably* different output than a mis-routed one." ] }, { "cell_type": "markdown", "id": "03b1db6c", "metadata": { "papermill": { "duration": 0.008466, "end_time": "2026-05-27T11:45:06.740371+00:00", "exception": false, "start_time": "2026-05-27T11:45:06.731905+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 9 · What we just observed\n", "\n", "The cells above ran Meta-Controller against **4 deliberately diverse tasks** to see whether the LLM router actually discriminates between architecture shapes.\n", "\n", "### 9.1 · Routing decisions captured live\n", "\n", "| Task | Routed to | Task preview | Router reason |\n", "|---|---|---|---|\n", "| Q1 | `tool_use` | What is the latest stable version of Rust as of today? | This task requires a one-shot fact lookup to find the latest stable version of Rust as of today. |\n", "| Q2 | `reflection` | Write a Python function that returns the n-th Fibonacci number, optimized for n | This task requires generating and refining code to solve a specific problem, which is best suited for the reflection architecture. |\n", "| Q3 | `planning` | Compare the population, GDP, and area of Japan and Germany. Pick which is larger | This task requires comparing multiple aspects of two countries, which can be decomposed into ordered steps upfront, making planning the most suitable |\n", "| Q4 | `react` | Who founded OpenAI, and which company did its CEO previously co-found before joi | This task requires chaining multiple lookups where each step depends on the previous result, making the react architecture the best fit. |\n", "\n", "### 9.2 · Architecture-choice distribution\n", "\n", "| Architecture | Times chosen |\n", "|---|---|\n", "| `tool_use` | 1 |\n", "| `reflection` | 1 |\n", "| `planning` | 1 |\n", "| `react` | 1 |\n", "\n", "### 9.3 · Patterns surfaced in this run\n", "\n", "- **Healthy routing diversity** — 4 tasks split across 4 distinct architectures. The router genuinely discriminates between task shapes.\n", "\n", "- **Routing accuracy against author's expectations**: 4/4 tasks routed as the author would have. \n", "\n", "### 9.4 · The takeaway\n", "\n", "A *healthy* Meta-Controller run has:\n", "\n", "1. **Routing diversity** — different task shapes go to different architectures.\n", "2. **Specific reasons** — the router justifies each choice with task-specific language, not generic praise.\n", "3. **Output quality matches the route** — Reflection routes produce polished code; ToolUse routes produce concise factual answers; Planning routes produce structured multi-part outputs.\n", "\n", "When all 4 tasks route to the same architecture, Meta-Controller's overhead is wasted — just call that architecture directly. The router's value is **only** realized when traffic is diverse and routing distributes work." ] }, { "cell_type": "markdown", "id": "47e110ef", "metadata": { "papermill": { "duration": 0.009529, "end_time": "2026-05-27T11:45:06.759945+00:00", "exception": false, "start_time": "2026-05-27T11:45:06.750416+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 10 · Try other providers / customise the roster\n", "\n", "Meta-Controller needs **structured output** (the dynamic Literal router). Most providers support it. You can also customise the roster — below, we make a roster that only contains *fast* architectures (no Reflection, no Planning) for latency-critical paths." ] }, { "cell_type": "code", "execution_count": 5, "id": "ae8d6917", "metadata": { "execution": { "iopub.execute_input": "2026-05-27T11:45:06.797432Z", "iopub.status.busy": "2026-05-27T11:45:06.797432Z", "iopub.status.idle": "2026-05-27T11:45:27.074956Z", "shell.execute_reply": "2026-05-27T11:45:27.072956Z" }, "papermill": { "duration": 20.307088, "end_time": "2026-05-27T11:45:27.075957+00:00", "exception": false, "start_time": "2026-05-27T11:45:06.768869+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "data": { "text/html": [ "
Custom 2-arch roster: tool_use OR react only ──────────────────────────────────────────────────────────────────────\n",
       "
\n" ], "text/plain": [ "\u001b[1;36mCustom \u001b[0m\u001b[1;36m2\u001b[0m\u001b[1;36m-arch roster: tool_use OR react only\u001b[0m \u001b[92m──────────────────────────────────────────────────────────────────────\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
› task: What is the current weather in Tokyo right now?\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1mtask: What is the current weather in Tokyo right now?\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
  routed to: tool_use\n",
       "  output: The current weather in Tokyo is 24°C with a low of 21°C and a high of 25°C....\n",
       "
\n" ], "text/plain": [ " routed to: tool_use\n", " output: The current weather in Tokyo is \u001b[1;36m24\u001b[0m°C with a low of \u001b[1;36m21\u001b[0m°C and a high of \u001b[1;36m25\u001b[0m°C\u001b[33m...\u001b[0m.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] }, { "data": { "text/html": [ "
› task: What is the latest stable Python release version?\n",
       "
\n" ], "text/plain": [ "\u001b[1;35m›\u001b[0m \u001b[1mtask: What is the latest stable Python release version?\u001b[0m\n" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
  routed to: tool_use\n",
       "  output: The latest stable Python release version is Python 3.12....\n",
       "
\n" ], "text/plain": [ " routed to: tool_use\n", " output: The latest stable Python release version is Python \u001b[1;36m3.12\u001b[0m\u001b[33m...\u001b[0m.\n" ] }, "metadata": {}, "output_type": "display_data" }, { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "from agentic_architectures.architectures import ToolUse, ReAct\n", "\n", "print_header(\"Custom 2-arch roster: tool_use OR react only\")\n", "fast_arch = MetaController(\n", " roster={\n", " \"tool_use\": ToolUse(llm=get_llm(), max_rounds=4),\n", " \"react\": ReAct(llm=get_llm(), max_rounds=4),\n", " },\n", ")\n", "for task in [\n", " \"What is the current weather in Tokyo right now?\",\n", " \"What is the latest stable Python release version?\",\n", "]:\n", " r = fast_arch.run(task)\n", " print_step(\n", " f\"task: {task[:80]}\",\n", " f\" routed to: {r.metadata['chosen_arch']}\\n output: {r.output[:200]}...\"\n", " )\n", " print()" ] }, { "cell_type": "markdown", "id": "7618931a", "metadata": { "papermill": { "duration": 0.021691, "end_time": "2026-05-27T11:45:27.114396+00:00", "exception": false, "start_time": "2026-05-27T11:45:27.092705+00:00", "status": "completed" }, "tags": [] }, "source": [ "## 11 · Failure modes, safety, extensions\n", "\n", "### 11.1 · Where this breaks\n", "\n", "| Failure | Mechanism | Mitigation |\n", "|---|---|---|\n", "| **Wrong route** | Router picks an architecture that's poorly fit to the task | Tighter architecture descriptions; or a verifier on the output that triggers re-routing |\n", "| **Preference bias** | Router always picks `react` (or `planning`) regardless of task | Inspect routing distribution; adjust descriptions to balance |\n", "| **Cost surprise** | A Planning route makes 20+ calls; the router didn't anticipate | Track total LLM calls per route and surface to caller |\n", "| **Roster drift** | Add a new architecture but forget to register it / describe it | Single roster dict + descriptions is single source of truth |\n", "| **No re-route on failure** | Chosen arch returns garbage; Meta-Controller still returns it | Wrap with PEV (nb 06) verifier; or add a confidence check |\n", "\n", "### 11.2 · Production safety\n", "\n", "- **Track route distribution** — if 90% of traffic routes to one architecture, you don't need the router (just use that architecture directly).\n", "- **Set per-architecture timeouts** — a Planning route hanging on a stuck sub-agent shouldn't take down the whole request.\n", "- **Audit the router** — log every `(task, chosen_arch, reason)` tuple. Cheaper than re-debugging.\n", "\n", "### 11.3 · Three extensions\n", "\n", "1. **PEV around the chosen architecture.** Wrap the route+execute in a verifier (PEV nb 06) that re-routes if the chosen architecture's output is unsatisfactory.\n", "2. **Few-shot router prompt.** Add 5-10 example `(task, correct_arch)` pairs to the router prompt to reduce preference bias.\n", "3. **Multi-level routing.** First route by task category, then route within each category (e.g. \"research → which retrieval strategy?\"). Hierarchical Meta-Controller.\n", "\n", "### 11.4 · What to read next\n", "\n", "- [**05 · Multi-Agent**](./05_multi_agent.ipynb) — routes between *agents* (domain experts) instead of architectures.\n", "- [**07 · Blackboard**](./07_blackboard.ipynb) — distributed routing, no central router.\n", "- [**13 · Ensemble**](./13_ensemble.ipynb) — when in doubt, run all architectures in parallel and aggregate.\n", "- [**26 · Adaptive RAG**](./26_adaptive_rag.ipynb) — Meta-Controller specialised for RAG complexity routing.\n", "\n", "### 11.5 · References\n", "\n", "1. LangChain `RouterChain` and `RunnableBranch` — [docs](https://python.langchain.com/docs/concepts/runnables/#runnablebranch)\n", "2. Multi-agent supervisor pattern — [LangGraph tutorial](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/agent_supervisor/)\n" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.0" }, "papermill": { "default_parameters": {}, "duration": 211.649632, "end_time": "2026-05-27T11:45:28.431181+00:00", "environment_variables": {}, "exception": null, "input_path": "all-agentic-architectures/notebooks/11_meta_controller.ipynb", "output_path": "all-agentic-architectures/notebooks/11_meta_controller.ipynb", "parameters": {}, "start_time": "2026-05-27T11:41:56.781549+00:00", "version": "2.7.0" } }, "nbformat": 4, "nbformat_minor": 5 }