# shameendra/mrkl_agent architecture

> Architecture diagram of the GitHub repository shameendra/mrkl_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shameendra/mrkl_agent
- Repository: https://github.com/shameendra/mrkl_agent

## Overview

This repository is a **Python MRKL-style reasoning agent** that can be run:
- as an **interactive CLI** or **single-shot CLI** (`main.py`)
- as an **HTTP API server** with JSON endpoints and a **streaming** endpoint (`main.py`)

Core behavior:
- Accept a user question
- (Optionally) generate a plan
- Execute a **reasoning loop** that repeatedly:
1) calls an LLM for “thought/action”
2) dispatches to a selected **tool**
3) feeds the observation back into the next step
- Produces a final answer (and optionally emits streaming events)

The architectural center is the **MRKLAgent** (`agent.py`) + **tool registry/implementations** (`tools.py`) + **runtime config** (`config.py`). `local_mrkl_agent.py` likely represents a variant/alternate implementation (e.g., local-only execution or simplified agent).

##### /query/stream (streaming events)

Participants:
- Client (CLI or HTTP Client)
- API/CLI handler (`main.py`)
- MRKLAgent (`agent.py`)
- LLM API
- Tool Dispatcher
- Specific Tool (e.g., `web_search`, then `calculator`)
- External service (SerpAPI/Web, etc.)

Key loop:
- LLM decides tool → tool executes → observation → back to LLM → repeat until final answer or max iteration/timeouts.

##### Control flow (orchestration)
- `main.py` orchestrates request lifecycle (HTTP/CLI).
- `agent.py` orchestrates reasoning iterations and decides when to stop.

##### Data flow (artifacts)
- Input: `question`, `with_planning`
- Intermediate: `plan[]`, `thought`, `action`, `action_input`, `observation`
- Output: `answer`, plus optionally `plan` and step trace
- Streaming: events per step (thought/action/observation/final)

##### Constraints (very important in agent systems)
From `config.py` / README:
- `MAX_ITERATIONS` (loop guard)
- `MAX_EXECUTION_TIME` (timeout guard)
- error handling & fallback tool attempts
As annotations on the reasoning loop component.

- **MRKL architecture**: “LLM-as-controller + modular tools”
- **Plugin/Registry pattern** for tools (`tools.py` as a registry; tools are replaceable)
- **Strategy selection** (dynamic tool selection)
- **Event streaming** (server → client incremental output)
- **Fail-soft execution** (tool failure → retry/alternate path)

##### Clients
- CLI User
- HTTP Client
##### Your App (Python Process)
- `main.py` (CLI + API)
- `agent.py` (Planner, Reasoning Loop, Tool Dispatcher, Streaming)
- `tools.py` (Tool Registry + Tools)
- `config.py`
##### External Services / Stores
- OpenAI (LLM)
- SerpAPI/Web, News, Wolfram
- SQL DB
- Knowledge Base store
- Python Execution Sandbox/Subprocess

Even without overthinking, quickly confirm in the code:
- What web framework is used for API mode (FastAPI/Flask) in `main.py`
- How streaming is implemented (SSE vs websockets vs chunked responses)
- Whether `python_executor` is sandboxed or uses `exec`/subprocess
- Where tool definitions live (LangChain tools vs custom functions)
- How the tool registry is constructed (`get_all_tools()` signature)
- Whether `local_mrkl_agent.py` is an alternative runtime path that should be shown as “optional/variant”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context + Container/Component Hybrid (Vertical)
  %% =========================

  U["User"]:::user
  H["HTTP Client\n(curl/browser/app)"]:::user

  subgraph RUNTIME["MRKL Agent App (Python Runtime Process)"]
    subgraph ENTRY["Entry Points / Interfaces"]
      MAIN["main.py\n- CLI: interactive + --query + --plan\n- HTTP API: POST /query, /query/stream, /plan"]:::entry
      REQ["requirements.txt\n- Web framework + clients\n- Runtime deps"]:::doc
      DOC["README.md\n- Usage + endpoints\n- Tool list + env vars"]:::doc
    end

    subgraph CORE["Core Domain (MRKL)"]
      AGENT["agent.py\nMRKLAgent\n- Optional Planner\n- Reasoning Loop (MRKL)\n- Tool Dispatcher\n- Streaming/Event Emitter\n- Fail-soft execution"]:::core
      LOCAL["local_mrkl_agent.py\nAlternate/variant agent path\n(local-only/simplified)"]:::coreOpt
      CFG["config.py\nRuntime config\n- MAX_ITERATIONS\n- MAX_EXECUTION_TIME\n- VERBOSE\n- TEMPERATURE\n- API keys via env"]:::config
      NOTE_LIMITS["Constraints/Guards\n- iteration guard\n- timeout guard\n- error handling & fallback"]:::note
    end

    subgraph TOOLS_LAYER["Tooling Subsystem (Plugin/Registry Pattern)"]
      TOOLS["tools.py\nTool Registry: get_all_tools()\nTool Implementations:\n- web_search\n- news_search\n- wolfram_alpha\n- calculator\n- python_executor\n- sql_query\n- datetime_tool\n- knowledge_base\n- logical_reasoning"]:::tools
      DISPATCH["Dynamic Tool Selection\n(Strategy selection)\nLLM chooses next action/tool"]:::note
    end

    MAIN -->|"invoke MRKLAgent\n(question,with_planning)"| AGENT
    MAIN -->|"loads docs/usage"| DOC
    MAIN -->|"deps & server framework"| REQ

    AGENT -->|"reads limits/temp/verbosity\n& env keys"| CFG
    AGENT -->|"loop guards"| NOTE_LIMITS
    AGENT -->|"loads registry\n& executes tool"| TOOLS
    AGENT -.->|"optional variant\n(alternate runtime)"| LOCAL
    TOOLS -->|"registry enables replaceable tools"| DISPATCH
  end

  subgraph EXTERNAL["External Services / Stores"]
    LLM["LLM Provider API\n(OpenAI)\nOPENAI_API_KEY"]:::cloud
    SEARCH["Web Search API\n(SerpAPI/Web)\nSERPAPI_KEY"]:::cloud
    WOLF["Wolfram Alpha API"]:::cloud
    NEWS["News API"]:::cloud
    SQL[(SQL Database)]:::db
    KB[(Knowledge Base Store\ndocs/embeddings/files)]:::db
    PY["Python Execution Environment\nSandbox/Subprocess boundary"]:::runtime
  end

  %% Clients -> App
  U -->|"CLI input: {question}\nflags: --plan/--query"| MAIN
  H -->|"HTTP JSON: {question,with_planning}"| MAIN

  %% App -> Client outputs
  MAIN -->|"HTTP JSON: {answer,plan?,trace?}"| H
  MAIN -.->|"stream events:\nthought/action/observation/final"| H
  MAIN -->|"CLI output: answer\n(optional plan/trace)"| U

  %% Agent -> external services (MRKL: LLM-as-controller + tools)
  AGENT -->|"prompt/completion\n(thought/action or final)"| LLM
  TOOLS -->|"tool call: query"| SEARCH
  TOOLS -->|"tool call: compute"| WOLF
  TOOLS -->|"tool call: headlines/search"| NEWS
  TOOLS -->|"tool call: SQL query"| SQL
  TOOLS -->|"tool call: retrieve docs"| KB
  TOOLS -->|"tool call: execute code"| PY

  %% Architectural labels
  PATTERN1["MRKL Pattern\nLLM-as-controller + modular tools"]:::note
  PATTERN2["Event streaming\n(server -> client incremental output)"]:::note
  DISPATCH --> PATTERN1
  AGENT --> PATTERN2

  %% =========================
  %% Interaction Flow (Flowchart representation of the original sequence diagrams)
  %% =========================

  subgraph SEQHOLDER["Runtime Interaction (MRKL)"]
    SEQNOTE["Two request modes:\n1) /query (non-stream)\n2) /query/stream (streamed events)"]:::note

    subgraph SEQ_QUERY["/query (non-streaming)"]
      Q1["Client -> main.py\nHTTP POST /query\n{question, with_planning?}"]:::note
      Q2["main.py -> agent.py\nask(question, with_planning)"]:::note
      Q3["agent.py -> config.py\nread MAX_ITERATIONS/MAX_EXECUTION_TIME\nVERBOSE/TEMPERATURE/env keys"]:::note
      Q4["(opt) with_planning\nagent.py -> LLM: plan prompt\nLLM -> agent.py: plan[]"]:::note
      Q5["loop (guarded):\nagent.py <-> LLM for thought/action OR final\nif action: agent.py -> tools.py -> external -> observation\nelse: final answer"]:::note
      Q6["agent.py -> main.py\n{return answer, plan?, trace?}"]:::note
      Q7["main.py -> Client\nHTTP 200 JSON {answer, plan?, trace?}"]:::note

      Q1 --> Q2 --> Q3 --> Q4 --> Q5 --> Q6 --> Q7
    end

    subgraph SEQ_STREAM["/query/stream (streaming events)"]
      S1["Client -> main.py\nHTTP POST /query/stream\n{question, with_planning?}"]:::note
      S2["main.py -> agent.py\nask_stream(question, with_planning)"]:::note
      S3["agent.py -> config.py\nread guards + env keys"]:::note
      S4["(opt) with_planning\nagent.py -> LLM: plan prompt\nagent.py -> main.py -> Client: stream plan event"]:::note
      S5["loop (streamed):\nagent.py <-> LLM for thought/action OR final\nagent.py -> main.py -> Client: stream thought/action\nif tool: tools dispatch + observation streamed\nelse: final streamed"]:::note

      S1 --> S2 --> S3 --> S4 --> S5
    end

    SEQNOTE --> SEQ_QUERY
    SEQ_QUERY --> SEQ_STREAM
  end

  %% Click Events (from component_mapping)
  click MAIN "https://github.com/shameendra/mrkl_agent/blob/main/main.py"
  click AGENT "https://github.com/shameendra/mrkl_agent/blob/main/agent.py"
  click LOCAL "https://github.com/shameendra/mrkl_agent/blob/main/local_mrkl_agent.py"
  click CFG "https://github.com/shameendra/mrkl_agent/blob/main/config.py"
  click TOOLS "https://github.com/shameendra/mrkl_agent/blob/main/tools.py"
  click REQ "https://github.com/shameendra/mrkl_agent/blob/main/requirements.txt"
  click DOC "https://github.com/shameendra/mrkl_agent/blob/main/README.md"

  %% Styles
  classDef user fill:#E8F1FF,stroke:#2B5DB7,stroke-width:1.5px,color:#0B1B3A
  classDef entry fill:#E9FFF3,stroke:#1C7C54,stroke-width:1.5px,color:#08301F
  classDef core fill:#FFF3E6,stroke:#B35C00,stroke-width:1.5px,color:#3A1F00
  classDef coreOpt fill:#FFF3E6,stroke:#B35C00,stroke-width:1.5px,stroke-dasharray:5 3,color:#3A1F00
  classDef tools fill:#F1E8FF,stroke:#5B2DB7,stroke-width:1.5px,color:#1A083A
  classDef config fill:#FFFBE6,stroke:#B39B00,stroke-width:1.5px,color:#2E2700
  classDef cloud fill:#E6FBFF,stroke:#007A8C,stroke-width:1.5px,color:#002B31
  classDef db fill:#FFFFFF,stroke:#444,stroke-width:1.5px,color:#111
  classDef runtime fill:#FFE6F2,stroke:#A1005B,stroke-width:1.5px,color:#3A001F
  classDef note fill:#F7F7F7,stroke:#777,stroke-width:1px,color:#111
  classDef doc fill:#F0F0F0,stroke:#666,stroke-width:1px,color:#111
```
