# lerabyte/ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/lerabyte/ai-agent
- Repository: https://github.com/lerabyte/ai-agent

## Overview

This repository is a hands-on course for building a local Python AI agent, accompanied by a browser dashboard. The learner progresses from a model request through tool use, looping, multiple tools, error recovery, and permission-controlled file access. The README documents this sequence and the model/tool round trip; sampled solutions show dispatch, validation, and file controls. The dashboard excerpt shows lesson progress and an interactive simulation. The course’s lesson materials are represented by their part directories; unsampled lesson internals are not assumed to call one another.

Main entry points: [`parts`](https://github.com/lerabyte/ai-agent/tree/main/parts) (Lesson materials), [`parts/06-permissions-and-limits/solution/agent.py`](https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/solution/agent.py) (Controlled agent), [`parts/02-first-tool/solution/agent.py`](https://github.com/lerabyte/ai-agent/blob/main/parts/02-first-tool/solution/agent.py) (First tool round trip), [`parts/04-multiple-tools/solution/agent.py`](https://github.com/lerabyte/ai-agent/blob/main/parts/04-multiple-tools/solution/agent.py) (Multiple tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_course["Course experience"]
  node_dashboard["Course dashboard<br/>[app.js]"]
  node_progress[("Browser progress")]
  node_lessons["Lesson materials"]
end

subgraph group_agent["Agent progression"]
  node_connect["Connect model<br/>[agent.py]"]
  node_first_tool["First tool round trip<br/>[agent.py]"]
  node_loop["Agent loop<br/>[agent.py]"]
  node_multi["Multiple tools<br/>[agent.py]"]
  node_recovery["Error recovery<br/>[agent.py]"]
end

subgraph group_tools["Tool capabilities"]
  node_python_tools["Python tools<br/>[agent.py]"]
end

subgraph group_safety["Safety controls"]
  node_controlled["Controlled agent<br/>[agent.py]"]
  node_safe_starter["Controlled-agent starter<br/>[agent.py]"]
  node_workspace[("Agent workspace")]
  node_approval["Write approval<br/>[agent.py]"]
end

node_learner(("Learner"))
node_local_model{{"Local Ollama model"}}
node_terminal(("Terminal answer"))

node_learner -->|"opens"| node_dashboard
node_dashboard -->|"stores progress"| node_progress
node_learner -->|"follows lessons"| node_lessons
node_lessons -->|"starts with"| node_connect
node_connect -->|"requests completion"| node_local_model
node_first_tool -->|"requests tool call"| node_local_model
node_local_model -->|"returns tool request"| node_first_tool
node_first_tool -->|"runs tool"| node_python_tools
node_first_tool -->|"sends tool result"| node_local_model
node_lessons -->|"continues with"| node_loop
node_loop -->|"repeats requests"| node_local_model
node_lessons -->|"adds multiple tools"| node_multi
node_multi -->|"offers tools"| node_local_model
node_multi -->|"dispatches calls"| node_python_tools
node_lessons -->|"adds recovery"| node_recovery
node_recovery -->|"returns tool errors"| node_local_model
node_lessons -->|"adds controls"| node_controlled
node_controlled -->|"limits tool turns"| node_local_model
node_controlled -->|"reads and writes"| node_workspace
node_controlled -->|"requests approval"| node_approval
node_approval -->|"asks before writing"| node_learner
node_controlled -->|"prints answer"| node_terminal

click node_dashboard "https://github.com/lerabyte/ai-agent/blob/main/course/app.js"
click node_lessons "https://github.com/lerabyte/ai-agent/tree/main/parts"
click node_connect "https://github.com/lerabyte/ai-agent/blob/main/parts/01-connect-model/solution/agent.py"
click node_first_tool "https://github.com/lerabyte/ai-agent/blob/main/parts/02-first-tool/solution/agent.py"
click node_loop "https://github.com/lerabyte/ai-agent/blob/main/parts/03-agent-loop/solution/agent.py"
click node_multi "https://github.com/lerabyte/ai-agent/blob/main/parts/04-multiple-tools/solution/agent.py"
click node_recovery "https://github.com/lerabyte/ai-agent/blob/main/parts/05-error-recovery/solution/agent.py"
click node_controlled "https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/solution/agent.py"
click node_safe_starter "https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/starter/agent.py"
click node_python_tools "https://github.com/lerabyte/ai-agent/blob/main/parts/04-multiple-tools/solution/agent.py"
click node_approval "https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/solution/agent.py"

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_dashboard,node_progress,node_lessons toneBlue
class node_connect,node_first_tool,node_loop,node_multi,node_recovery toneAmber
class node_python_tools toneMint
class node_controlled,node_safe_starter,node_workspace,node_approval toneRose
class node_learner,node_local_model,node_terminal toneIndigo
```

## Components

### Course experience

- [Course dashboard](https://github.com/lerabyte/ai-agent/blob/main/course/app.js): `course/app.js`
- **Browser progress**
- [Lesson materials](https://github.com/lerabyte/ai-agent/tree/main/parts): `parts`

### Agent progression

- [Connect model](https://github.com/lerabyte/ai-agent/blob/main/parts/01-connect-model/solution/agent.py): `parts/01-connect-model/solution/agent.py`
- [First tool round trip](https://github.com/lerabyte/ai-agent/blob/main/parts/02-first-tool/solution/agent.py): `parts/02-first-tool/solution/agent.py`
- [Agent loop](https://github.com/lerabyte/ai-agent/blob/main/parts/03-agent-loop/solution/agent.py): `parts/03-agent-loop/solution/agent.py`
- [Multiple tools](https://github.com/lerabyte/ai-agent/blob/main/parts/04-multiple-tools/solution/agent.py): `parts/04-multiple-tools/solution/agent.py`
- [Error recovery](https://github.com/lerabyte/ai-agent/blob/main/parts/05-error-recovery/solution/agent.py): `parts/05-error-recovery/solution/agent.py`

### Tool capabilities

- [Python tools](https://github.com/lerabyte/ai-agent/blob/main/parts/04-multiple-tools/solution/agent.py): `parts/04-multiple-tools/solution/agent.py`

### Safety controls

- [Controlled agent](https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/solution/agent.py): `parts/06-permissions-and-limits/solution/agent.py`
- [Controlled-agent starter](https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/starter/agent.py): `parts/06-permissions-and-limits/starter/agent.py`
- **Agent workspace**
- [Write approval](https://github.com/lerabyte/ai-agent/blob/main/parts/06-permissions-and-limits/solution/agent.py): `parts/06-permissions-and-limits/solution/agent.py`

### Other components

- **Learner**
- **Local Ollama model**
- **Terminal answer**

## Connections

- Learner → Course dashboard: opens (evidence: `README.md`)
- Course dashboard → Browser progress: stores progress (evidence: `course/app.js`)
- Learner → Lesson materials: follows lessons (evidence: `README.md`)
- Lesson materials → Connect model: starts with (evidence: `README.md`)
- Connect model → Local Ollama model: requests completion (evidence: `README.md`)
- First tool round trip → Local Ollama model: requests tool call (evidence: `README.md`)
- Local Ollama model → First tool round trip: returns tool request (evidence: `README.md`)
- First tool round trip → Python tools: runs tool (evidence: `parts/02-first-tool/solution/agent.py`)
- First tool round trip → Local Ollama model: sends tool result (evidence: `parts/02-first-tool/solution/agent.py`)
- Lesson materials → Agent loop: continues with (evidence: `README.md`)
- Agent loop → Local Ollama model: repeats requests (evidence: `parts/03-agent-loop/solution/agent.py`)
- Lesson materials → Multiple tools: adds multiple tools (evidence: `README.md`)
- Multiple tools → Local Ollama model: offers tools (evidence: `parts/04-multiple-tools/solution/agent.py`)
- Multiple tools → Python tools: dispatches calls (evidence: `parts/04-multiple-tools/solution/agent.py`)
- Lesson materials → Error recovery: adds recovery (evidence: `README.md`)
- Error recovery → Local Ollama model: returns tool errors (evidence: `parts/05-error-recovery/solution/agent.py`)
- Lesson materials → Controlled agent: adds controls (evidence: `README.md`)
- Controlled agent → Local Ollama model: limits tool turns (evidence: `parts/06-permissions-and-limits/solution/agent.py`)
- Controlled agent → Agent workspace: reads and writes (evidence: `parts/06-permissions-and-limits/solution/agent.py`)
- Controlled agent → Write approval: requests approval (evidence: `parts/06-permissions-and-limits/solution/agent.py`)
- Write approval → Learner: asks before writing (evidence: `parts/06-permissions-and-limits/solution/agent.py`)
- Controlled agent → Terminal answer: prints answer (evidence: `parts/06-permissions-and-limits/solution/agent.py`)