# nerdai/llm-agents-from-scratch architecture

> Architecture diagram of the GitHub repository nerdai/llm-agents-from-scratch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nerdai/llm-agents-from-scratch
- Repository: https://github.com/nerdai/llm-agents-from-scratch

## Overview

1. **What this repo is**
   - `llm_agents_from_scratch` is a Python library that implements an educational LLM-agent stack from first principles.
   - The codebase is organized around a small core runtime plus pluggable adapters for models, tools, skills, and memory.

2. **Top-level runtime boundary**
   - The main runtime lives under `src/llm_agents_from_scratch`.
   - Everything outside `src` is supporting material: notebooks, docs, capstones, talks, tests, and a few deployment/demo assets.

3. **Agent orchestration layer**
   - `agent/` is the central coordination layer.
   - `LLMAgentBuilder` assembles an agent from an LLM backend, tool set, memory, and optional skill support.
   - `llm_agent.py` is the execution path where user input is turned into prompts, tool calls are handled, and final responses are returned.

4. **Core control flow**
   - Typical flow is: user prompt → agent → LLM → tool selection/output → tool execution → tool results back to LLM → final answer.
   - The repo is structured to make that loop explicit rather than hiding it behind a large framework.

5. **Model/provider abstraction**
   - `base/llm.py` defines the common LLM interface.
   - `llms/openai/` and `llms/ollama/` are concrete provider adapters.
   - This creates a clear boundary between agent logic and the external inference runtime, whether that is OpenAI’s API or a local Ollama server.

6. **Tooling subsystem**
   - `base/tool.py` defines the tool contract.
   - `tools/simple_function.py` and `tools/pydantic_function.py` adapt ordinary Python callables into LLM-callable tools.
   - `tools/default/` contains built-in utilities such as file reading and an interpreter-like tool.
   - `tools/mcp/` integrates Model Context Protocol tools through a provider and tool wrapper.

7. **Skill subsystem**
   - `skills/` supports filesystem-discovered “skills” stored as directories with `SKILL.md`, optional scripts, and resources.
   - Discovery and validation live in `skills/discovery.py`, `skills/skill.py`, and `skills/utils.py`.
   - Skills are a higher-level extension mechanism than tools: they package instructions, assets, and helper scripts that the agent can consume.

8. **Memory subsystem**
   - `memory/` provides the abstraction used by the agent to persist or recall conversational/contextual state.
   - `memory_stores/json.py` offers a lightweight local store.
   - `memory_stores/qdrant/` connects to Qdrant for vector-backed retrieval and similarity-style memory.
   - `memory/recipes.py` suggests higher-level memory patterns built on top of the store abstraction.

9. **Shared data models and errors**
   - `data_structures/` holds the canonical objects passed across subsystem boundaries: agent, LLM, memory, skill, and tool models.
   - `errors/` centralizes typed exceptions for agent, memory, MCP, skill, and task handling failures.
   - These two packages act as the contract layer for the rest of the codebase.

10. **Educational assets and examples**
   - `examples/`, `more-examples/`, `docs/more-examples/`, and `capstones/` show the runtime in progressively richer scenarios.
   - The notebooks are not just demos; they document how the agent, tool, skill, and memory subsystems compose in practice.
   - `extra/mcp-hailstone/` is a separate MCP server example that demonstrates external tool integration.

11. **Documentation and publishing**
   - `docs/` is a MkDocs site with API references, chapter notebooks, capstones, and rendered assets.
   - `github/workflows` contains CI for linting, tests, docs publishing, and release automation.
   - The docs are part of the repo’s architecture because they mirror the library’s module boundaries and usage patterns.

12. **Testing and verification**
   - `tests/` mirrors the source tree almost one-to-one, which makes the package boundaries explicit.
   - There are dedicated tests for agent flow, LLM adapters, tools, skills, memory stores, notebook utilities, and API import stability.
   - This indicates the architecture is intentionally modular and contract-driven.

13. **Deployment/runtime extras**
   - `docker/runpod/` provides a GPU-friendly container entrypoint for notebook or demo execution.
   - The README’s default runtime assumes Ollama locally, with Lightning AI and Runpod as supported execution environments for larger models.

14. **How to draw the architecture**
   - A good diagram would place `agent/` in the center, fed by `llms/`, `tools/`, `skills/`, and `memory/`.
   - Surround that with `data_structures/` and `errors/` as shared contracts.
   - Show external boundaries for Ollama/OpenAI, Qdrant, and MCP servers, plus separate documentation/example environments around the core library.

Main entry points: [`src/llm_agents_from_scratch`](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch) (Library), [`tests`](https://github.com/nerdai/llm-agents-from-scratch/tree/main/tests) (Tests), [`src/llm_agents_from_scratch/memory`](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/memory) (Memory), [`examples`](https://github.com/nerdai/llm-agents-from-scratch/tree/main/examples) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_src_root["Library"]
  node_agent["Agent<br/>orchestrator"]
  node_builder["Builder<br/>assembly<br/>[builder.py]"]
  node_llm_agent["Runtime loop<br/>execution<br/>[llm_agent.py]"]
  node_base["Base APIs<br/>contracts"]
  node_llm_base["LLM API<br/>interface<br/>[llm.py]"]
  node_tool_base["Tool API<br/>interface<br/>[tool.py]"]
  node_memory_store_base["Store API<br/>interface<br/>[memory_store.py]"]
  node_llms["LLM adapters<br/>providers"]
  node_openai_llm["OpenAI<br/>adapter<br/>[llm.py]"]
  node_ollama_llm["Ollama<br/>adapter<br/>[llm.py]"]
  node_tools["Tools<br/>tooling"]
  node_simple_tool["Function tool<br/>adapter<br/>[simple_function.py]"]
  node_pydantic_tool["Pydantic tool<br/>adapter"]
  node_mcp_tool["MCP tool<br/>integration<br/>[tool.py]"]
  node_skills["Skills<br/>extension"]
  node_memory["Memory<br/>state"]
  node_json_store["JSON store<br/>[json.py]"]
  node_qdrant_store["Qdrant store<br/>[store.py]"]
  node_models_errors["Models & errors<br/>contracts"]
end

subgraph group_adjacent["Examples and docs"]
  node_examples["Examples<br/>notebooks"]
  node_docs["Docs site<br/>documentation"]
  node_capstones["Capstones<br/>notebooks"]
  node_mcp_example["MCP demo<br/>service example"]
end

subgraph group_verification["Tests and CI"]
  node_tests["Tests<br/>verification"]
  node_ci["CI workflows<br/>automation<br/>[workflows]"]
  node_docker_runpod["Runpod image<br/>runtime"]
end

subgraph group_external["External systems"]
  node_openai_api(("OpenAI API<br/>external service"))
  node_ollama_server(("Ollama server<br/>external runtime"))
  node_qdrant_service(("Qdrant<br/>external service"))
  node_mcp_server(("MCP server<br/>external service"))
end

node_src_root -->|"contains"| node_agent
node_src_root -->|"contains"| node_base
node_src_root -->|"contains"| node_llms
node_src_root -->|"contains"| node_tools
node_src_root -->|"contains"| node_skills
node_src_root -->|"contains"| node_memory
node_src_root -->|"contains"| node_models_errors
node_agent -->|"assembles"| node_builder
node_agent -->|"executes"| node_llm_agent
node_builder -->|"uses"| node_llm_base
node_builder -->|"uses"| node_tool_base
node_builder -->|"uses"| node_memory_store_base
node_builder -->|"enables"| node_skills
node_llm_agent -->|"calls"| node_llm_base
node_llm_agent -->|"invokes"| node_tool_base
node_llm_agent -->|"reads/writes"| node_memory
node_llm_agent -->|"consumes"| node_skills
node_llms -->|"implements"| node_openai_llm
node_llms -->|"implements"| node_ollama_llm
node_openai_llm -->|"connects to"| node_openai_api
node_ollama_llm -->|"connects to"| node_ollama_server
node_tools -->|"contains"| node_simple_tool
node_tools -->|"contains"| node_pydantic_tool
node_tools -->|"contains"| node_mcp_tool
node_mcp_tool -->|"connects to"| node_mcp_server
node_skills -->|"shares models"| node_models_errors
node_memory -->|"uses"| node_json_store
node_memory -->|"uses"| node_qdrant_store
node_qdrant_store -->|"connects to"| node_qdrant_service
node_memory -->|"shares models"| node_models_errors
node_examples -->|"demonstrates"| node_agent
node_examples -->|"demonstrates"| node_tools
node_examples -->|"demonstrates"| node_skills
node_examples -->|"demonstrates"| node_memory
node_docs -->|"documents"| node_src_root
node_docs -->|"publishes"| node_examples
node_capstones -->|"applies"| node_agent
node_mcp_example -->|"implements"| node_mcp_server
node_tests -->|"verifies"| node_agent
node_tests -->|"verifies"| node_llms
node_tests -->|"verifies"| node_tools
node_tests -->|"verifies"| node_skills
node_tests -->|"verifies"| node_memory
node_tests -->|"verifies"| node_models_errors
node_ci -->|"runs"| node_tests
node_ci -->|"publishes"| node_docs
node_docker_runpod -->|"hosts"| node_examples

click node_src_root "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch"
click node_agent "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/agent"
click node_builder "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/agent/builder.py"
click node_llm_agent "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/agent/llm_agent.py"
click node_base "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/base"
click node_llm_base "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/base/llm.py"
click node_tool_base "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/base/tool.py"
click node_memory_store_base "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/base/memory_store.py"
click node_llms "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/llms"
click node_openai_llm "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/llms/openai/llm.py"
click node_ollama_llm "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/llms/ollama/llm.py"
click node_tools "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/tools"
click node_simple_tool "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/tools/simple_function.py"
click node_pydantic_tool "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/tools/pydantic_function.py"
click node_mcp_tool "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/tools/mcp/tool.py"
click node_skills "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/skills"
click node_memory "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/memory"
click node_json_store "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/memory_stores/json.py"
click node_qdrant_store "https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/memory_stores/qdrant/store.py"
click node_models_errors "https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/data_structures"
click node_examples "https://github.com/nerdai/llm-agents-from-scratch/tree/main/examples"
click node_docs "https://github.com/nerdai/llm-agents-from-scratch/tree/main/docs"
click node_capstones "https://github.com/nerdai/llm-agents-from-scratch/tree/main/capstones"
click node_mcp_example "https://github.com/nerdai/llm-agents-from-scratch/tree/main/extra/mcp-hailstone"
click node_tests "https://github.com/nerdai/llm-agents-from-scratch/tree/main/tests"
click node_ci "https://github.com/nerdai/llm-agents-from-scratch/blob/main/.github/workflows"
click node_docker_runpod "https://github.com/nerdai/llm-agents-from-scratch/tree/main/docker/runpod"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_root,node_agent,node_builder,node_llm_agent,node_base,node_llm_base,node_tool_base,node_memory_store_base,node_llms,node_openai_llm,node_ollama_llm,node_tools,node_simple_tool,node_pydantic_tool,node_mcp_tool,node_skills,node_memory,node_json_store,node_qdrant_store,node_models_errors toneBlue
class node_examples,node_docs,node_capstones,node_mcp_example toneAmber
class node_tests,node_ci,node_docker_runpod toneMint
class node_openai_api,node_ollama_server,node_qdrant_service,node_mcp_server toneRose
```

## Components

### Core runtime

Main library under src/llm_agents_from_scratch.

- [Library](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch): package · Top-level Python package for the runtime and adapters. · `src/llm_agents_from_scratch`
- [Agent](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/agent): orchestrator · Builds and runs the agent loop. · `src/llm_agents_from_scratch/agent`
- [Builder](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/agent/builder.py): assembly · Composes an agent from model, tools, memory, and skills. · `src/llm_agents_from_scratch/agent/builder.py`
- [Runtime loop](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/agent/llm_agent.py): execution · Turns user input into prompts, tool calls, and final responses. · `src/llm_agents_from_scratch/agent/llm_agent.py`
- [Base APIs](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/base): contracts · Abstract interfaces for models, tools, and memory stores. · `src/llm_agents_from_scratch/base`
- [LLM API](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/base/llm.py): interface · Common interface for LLM backends. · `src/llm_agents_from_scratch/base/llm.py`
- [Tool API](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/base/tool.py): interface · Common interface for callable tools. · `src/llm_agents_from_scratch/base/tool.py`
- [Store API](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/base/memory_store.py): interface · Common interface for persistence and retrieval backends. · `src/llm_agents_from_scratch/base/memory_store.py`
- [LLM adapters](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/llms): providers · Concrete providers that adapt external model runtimes. · `src/llm_agents_from_scratch/llms`
- [OpenAI](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/llms/openai/llm.py): adapter · OpenAI chat and structured-output adapter. · `src/llm_agents_from_scratch/llms/openai/llm.py`
- [Ollama](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/llms/ollama/llm.py): adapter · Local Ollama adapter for model inference. · `src/llm_agents_from_scratch/llms/ollama/llm.py`
- [Tools](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/tools): tooling · Tool adapters and built-in utilities used by the agent. · `src/llm_agents_from_scratch/tools`
- [Function tool](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/tools/simple_function.py): adapter · Wraps ordinary Python callables as LLM-callable tools. · `src/llm_agents_from_scratch/tools/simple_function.py`
- [Pydantic tool](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/tools/pydantic_function.py): adapter · Callable tool adapter with schema validation. · `src/llm_agents_from_scratch/tools/pydantic_function.py`
- [MCP tool](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/tools/mcp/tool.py): integration · Tool wrapper for Model Context Protocol integration. · `src/llm_agents_from_scratch/tools/mcp/tool.py`
- [Skills](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/skills): extension · Filesystem-discovered skill packages with instructions, scripts, and resources. · `src/llm_agents_from_scratch/skills`
- [Memory](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/memory): state · Conversation and context memory abstractions plus recipes. · `src/llm_agents_from_scratch/memory`
- [JSON store](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/memory_stores/json.py): store · Lightweight local memory store. · `src/llm_agents_from_scratch/memory_stores/json.py`
- [Qdrant store](https://github.com/nerdai/llm-agents-from-scratch/blob/main/src/llm_agents_from_scratch/memory_stores/qdrant/store.py): store · Vector-backed memory store for retrieval-style memory. · `src/llm_agents_from_scratch/memory_stores/qdrant/store.py`
- [Models & errors](https://github.com/nerdai/llm-agents-from-scratch/tree/main/src/llm_agents_from_scratch/data_structures): contracts · Shared data structures and typed exceptions used across subsystem boundaries. · `src/llm_agents_from_scratch/data_structures`

### Examples and docs

Educational materials, notebooks, and published docs that exercise the core runtime.

- [Examples](https://github.com/nerdai/llm-agents-from-scratch/tree/main/examples): notebooks · Educational notebooks that demonstrate the runtime in practice. · `examples`
- [Docs site](https://github.com/nerdai/llm-agents-from-scratch/tree/main/docs): documentation · MkDocs site mirroring the library structure and usage patterns. · `docs`
- [Capstones](https://github.com/nerdai/llm-agents-from-scratch/tree/main/capstones): notebooks · Long-form notebook projects and applied scenarios. · `capstones`
- [MCP demo](https://github.com/nerdai/llm-agents-from-scratch/tree/main/extra/mcp-hailstone): service example · Standalone MCP server example used to demonstrate external tool integration. · `extra/mcp-hailstone`

### Tests and CI

Automated verification, packaging, and release support.

- [Tests](https://github.com/nerdai/llm-agents-from-scratch/tree/main/tests): verification · Package-level tests that mirror the source tree and verify contracts. · `tests`
- [CI workflows](https://github.com/nerdai/llm-agents-from-scratch/blob/main/.github/workflows): automation · Linting, testing, docs publishing, and release automation. · `.github/workflows`
- [Runpod image](https://github.com/nerdai/llm-agents-from-scratch/tree/main/docker/runpod): runtime · Container entrypoint for GPU-friendly notebook or demo execution. · `docker/runpod`

### External systems

Outside services and runtimes the library integrates with.

- **OpenAI API**: external service · Hosted model inference runtime.
- **Ollama server**: external runtime · Local model inference runtime.
- **Qdrant**: external service · Vector database used by the memory store.
- **MCP server**: external service · External Model Context Protocol tool provider.

## Connections

- Library → Agent: contains · Core library entry point includes agent orchestration.
- Library → Base APIs: contains · Abstract interfaces live in the base layer.
- Library → LLM adapters: contains · Provider adapters live under llms.
- Library → Tools: contains · Tool adapters and built-ins live under tools.
- Library → Skills: contains · Skill discovery and validation live under skills.
- Library → Memory: contains · Memory abstractions and recipes live under memory.
- Library → Models & errors: contains · Shared models and typed errors are part of the contract layer.
- Agent → Builder: assembles · Builder wires dependencies into an agent instance.
- Agent → Runtime loop: executes · Runtime loop handles prompt, tool, and response flow.
- Builder → LLM API: uses · Builder depends on the model abstraction.
- Builder → Tool API: uses · Builder accepts tool implementations.
- Builder → Store API: uses · Builder can attach memory backends.
- Builder → Skills: enables · Builder can opt into skill support.
- Runtime loop → LLM API: calls · Agent loop asks the model for next actions or final output.
- Runtime loop → Tool API: invokes · Tool calls are executed during the agent loop.
- Runtime loop → Memory: reads/writes · Conversation state can be persisted and recalled.
- Runtime loop → Skills: consumes · Skills can augment prompts and capabilities.
- LLM adapters → OpenAI: implements · OpenAI provider adapter.
- LLM adapters → Ollama: implements · Ollama provider adapter.
- OpenAI → OpenAI API: connects to · Uses the hosted OpenAI service.
- Ollama → Ollama server: connects to · Uses a local Ollama server.
- Tools → Function tool: contains · Function-based tool adapter.
- Tools → Pydantic tool: contains · Validated callable tool adapter.
- Tools → MCP tool: contains · MCP integration lives in the tool layer.
- MCP tool → MCP server: connects to · Delegates tool execution to an external MCP provider.
- Skills → Models & errors: shares models · Skill definitions and errors use shared contracts.
- Memory → JSON store: uses · Local persistent store implementation.
- Memory → Qdrant store: uses · Vector-backed store implementation.
- Qdrant store → Qdrant: connects to · Persists and queries memory in Qdrant.
- Memory → Models & errors: shares models · Memory state and exceptions use shared contracts.
- Examples → Agent: demonstrates · Notebooks exercise the core agent flow.
- Examples → Tools: demonstrates · Examples show tool creation and execution.
- Examples → Skills: demonstrates · Examples show filesystem skills in action.
- Examples → Memory: demonstrates · Examples include memory patterns and retrieval.
- Docs site → Library: documents · Docs mirror the runtime and API boundaries.
- Docs site → Examples: publishes · Docs include notebook-based examples and chapters.
- Capstones → Agent: applies · Capstone notebooks build on the agent runtime.
- MCP demo → MCP server: implements · Standalone example MCP server.
- Tests → Agent: verifies · Agent flow and builder tests.
- Tests → LLM adapters: verifies · Adapter tests for model providers.
- Tests → Tools: verifies · Tool adapters and MCP tests.
- Tests → Skills: verifies · Skill discovery and validation tests.
- Tests → Memory: verifies · Store and recipes tests.
- Tests → Models & errors: verifies · API stability and model contract tests.
- CI workflows → Tests: runs · Workflows execute the test suite.
- CI workflows → Docs site: publishes · Workflows build and publish documentation.
- Runpod image → Examples: hosts · Container supports notebook/demo execution.