# daveebbelaar/ai-cookbook architecture

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

- Interactive diagram: https://gitdiagram.com/daveebbelaar/ai-cookbook
- Repository: https://github.com/daveebbelaar/ai-cookbook

## Overview

This repository is an AI engineering cookbook: tutorial scripts demonstrate agents, retrieval and knowledge preparation, model capabilities, MCP tools, and workflow patterns rather than forming one deployed application. A representative user-to-result flow is the web research agent: a user asks a question, the agent calls an appropriate handbook or page tool (and may use built-in web search), then returns a structured answer. Knowledge examples separately cover document ingestion and hybrid retrieval. The graph preserves those capability branches; relationships for unsampled tutorials are omitted rather than inferred.

Main entry points: [`context/web/4-search-agent.py`](https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/4-search-agent.py) (Research agent), [`knowledge/hybrid-retrieval/6-evaluate.py`](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/6-evaluate.py) (Retrieval evaluation), [`mcp/servers/youtube/src/service.py`](https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/src/service.py) (Transcript service), [`knowledge/docling/3-embedding.py`](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/3-embedding.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Agents and context"]
  node_research_agent["Research agent<br/>[4-search-agent.py]"]
  node_handbook_tool["Handbook lookup<br/>[search_handbook.py]"]
  node_web_page_tool["Page fetch<br/>[get_web_page.py]"]
  node_web_search_tool["Web search<br/>[web_search.py]"]
  node_agent_examples["Agent patterns"]
  node_agent_blocks["Agent building blocks"]
end

subgraph group_knowledge["Knowledge systems"]
  node_doc_ingestion["Document ingestion<br/>[3-embedding.py]"]
  node_tokenizer["Tokenizer adapter<br/>[tokenizer.py]"]
  node_doc_search["Document search and chat<br/>[4-search.py]"]
  node_hybrid_eval["Retrieval evaluation<br/>[6-evaluate.py]"]
  node_retrievers["BM25 and dense retrievers<br/>[retrievers.py]"]
  node_fusion["Rank fusion<br/>[fusion.py]"]
  node_reranker["Result reranking<br/>[reranker.py]"]
  node_rag_examples["Agentic RAG"]
  node_memory_examples["Memory examples"]
end

subgraph group_models["Model examples"]
  node_model_examples["Model APIs and outputs"]
  node_model_routing["Model routing patterns"]
  node_transcription["Audio transcription<br/>[transcribe.py]"]
end

subgraph group_mcp["MCP integrations"]
  node_mcp_client["MCP clients<br/>[client.py]"]
  node_knowledge_server["Knowledge-base server<br/>[server.py]"]
  node_youtube_server["YouTube transcript server<br/>[server.py]"]
  node_youtube_service["Transcript service<br/>[service.py]"]
  node_video_id["Video ID parser<br/>[utils.py]"]
end

subgraph group_workflows["Workflow patterns"]
  node_workflow_examples["Workflow patterns"]
end

node_user(("User"))
node_openai{{"OpenAI API"}}
node_youtube{{"YouTube transcripts"}}

node_user -->|"asks"| node_research_agent
node_research_agent -->|"requests responses"| node_openai
node_research_agent -->|"calls lookup"| node_handbook_tool
node_research_agent -->|"calls fetch"| node_web_page_tool
node_research_agent -->|"offers search"| node_web_search_tool
node_research_agent -->|"returns answer"| node_user
node_doc_ingestion -->|"uses tokenizer"| node_tokenizer
node_hybrid_eval -->|"evaluates retrieval"| node_retrievers
node_hybrid_eval -->|"evaluates fusion"| node_fusion
node_hybrid_eval -->|"evaluates reranking"| node_reranker
node_youtube_server -->|"calls service"| node_youtube_service
node_youtube_service -->|"extracts ID"| node_video_id
node_youtube_service -->|"fetches transcript"| node_youtube

click node_research_agent "https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/4-search-agent.py"
click node_handbook_tool "https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/tools/search_handbook.py"
click node_web_page_tool "https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/tools/get_web_page.py"
click node_web_search_tool "https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/tools/web_search.py"
click node_agent_examples "https://github.com/daveebbelaar/ai-cookbook/tree/main/agents/agent-complexity"
click node_agent_blocks "https://github.com/daveebbelaar/ai-cookbook/tree/main/agents/building-blocks"
click node_doc_ingestion "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/3-embedding.py"
click node_tokenizer "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/utils/tokenizer.py"
click node_doc_search "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/4-search.py"
click node_hybrid_eval "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/6-evaluate.py"
click node_retrievers "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/utils/retrievers.py"
click node_fusion "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/utils/fusion.py"
click node_reranker "https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/utils/reranker.py"
click node_rag_examples "https://github.com/daveebbelaar/ai-cookbook/tree/main/knowledge/agentic-rag"
click node_memory_examples "https://github.com/daveebbelaar/ai-cookbook/tree/main/knowledge/mem0"
click node_model_examples "https://github.com/daveebbelaar/ai-cookbook/tree/main/models/openai"
click node_model_routing "https://github.com/daveebbelaar/ai-cookbook/tree/main/models/jev"
click node_transcription "https://github.com/daveebbelaar/ai-cookbook/blob/main/models/whisper/transcribe.py"
click node_mcp_client "https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/crash-course/4-openai-integration/client.py"
click node_knowledge_server "https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/crash-course/4-openai-integration/server.py"
click node_youtube_server "https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/server.py"
click node_youtube_service "https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/src/service.py"
click node_video_id "https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/src/utils.py"
click node_workflow_examples "https://github.com/daveebbelaar/ai-cookbook/tree/main/patterns/workflows"

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_research_agent,node_handbook_tool,node_web_page_tool,node_web_search_tool,node_agent_examples,node_agent_blocks,node_user toneBlue
class node_doc_ingestion,node_tokenizer,node_doc_search,node_hybrid_eval,node_retrievers,node_fusion,node_reranker,node_rag_examples,node_memory_examples toneAmber
class node_model_examples,node_model_routing,node_transcription,node_openai toneMint
class node_mcp_client,node_knowledge_server,node_youtube_server,node_youtube_service,node_video_id toneRose
class node_workflow_examples,node_youtube toneIndigo
```

## Components

### Agents and context

- [Research agent](https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/4-search-agent.py): `context/web/4-search-agent.py`
- [Handbook lookup](https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/tools/search_handbook.py): `context/web/tools/search_handbook.py`
- [Page fetch](https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/tools/get_web_page.py): `context/web/tools/get_web_page.py`
- [Web search](https://github.com/daveebbelaar/ai-cookbook/blob/main/context/web/tools/web_search.py): `context/web/tools/web_search.py`
- [Agent patterns](https://github.com/daveebbelaar/ai-cookbook/tree/main/agents/agent-complexity): `agents/agent-complexity`
- [Agent building blocks](https://github.com/daveebbelaar/ai-cookbook/tree/main/agents/building-blocks): `agents/building-blocks`

### Knowledge systems

- [Document ingestion](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/3-embedding.py): `knowledge/docling/3-embedding.py`
- [Tokenizer adapter](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/utils/tokenizer.py): `knowledge/docling/utils/tokenizer.py`
- [Document search and chat](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/docling/4-search.py): `knowledge/docling/4-search.py`
- [Retrieval evaluation](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/6-evaluate.py): `knowledge/hybrid-retrieval/6-evaluate.py`
- [BM25 and dense retrievers](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/utils/retrievers.py): `knowledge/hybrid-retrieval/utils/retrievers.py`
- [Rank fusion](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/utils/fusion.py): `knowledge/hybrid-retrieval/utils/fusion.py`
- [Result reranking](https://github.com/daveebbelaar/ai-cookbook/blob/main/knowledge/hybrid-retrieval/utils/reranker.py): `knowledge/hybrid-retrieval/utils/reranker.py`
- [Agentic RAG](https://github.com/daveebbelaar/ai-cookbook/tree/main/knowledge/agentic-rag): `knowledge/agentic-rag`
- [Memory examples](https://github.com/daveebbelaar/ai-cookbook/tree/main/knowledge/mem0): `knowledge/mem0`

### Model examples

- [Model APIs and outputs](https://github.com/daveebbelaar/ai-cookbook/tree/main/models/openai): `models/openai`
- [Model routing patterns](https://github.com/daveebbelaar/ai-cookbook/tree/main/models/jev): `models/jev`
- [Audio transcription](https://github.com/daveebbelaar/ai-cookbook/blob/main/models/whisper/transcribe.py): `models/whisper/transcribe.py`

### MCP integrations

- [MCP clients](https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/crash-course/4-openai-integration/client.py): `mcp/crash-course/4-openai-integration/client.py`
- [Knowledge-base server](https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/crash-course/4-openai-integration/server.py): `mcp/crash-course/4-openai-integration/server.py`
- [YouTube transcript server](https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/server.py): `mcp/servers/youtube/server.py`
- [Transcript service](https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/src/service.py): `mcp/servers/youtube/src/service.py`
- [Video ID parser](https://github.com/daveebbelaar/ai-cookbook/blob/main/mcp/servers/youtube/src/utils.py): `mcp/servers/youtube/src/utils.py`

### Workflow patterns

- [Workflow patterns](https://github.com/daveebbelaar/ai-cookbook/tree/main/patterns/workflows): `patterns/workflows`

### Other components

- **User**
- **OpenAI API**
- **YouTube transcripts**

## Connections

- User → Research agent: asks (evidence: `context/web/4-search-agent.py`)
- Research agent → OpenAI API: requests responses (evidence: `context/web/4-search-agent.py`)
- Research agent → Handbook lookup: calls lookup (evidence: `context/web/4-search-agent.py`)
- Research agent → Page fetch: calls fetch (evidence: `context/web/4-search-agent.py`)
- Research agent → Web search: offers search (evidence: `context/web/4-search-agent.py`)
- Research agent → User: returns answer (evidence: `context/web/4-search-agent.py`)
- Document ingestion → Tokenizer adapter: uses tokenizer (evidence: `knowledge/docling/3-embedding.py`)
- Retrieval evaluation → BM25 and dense retrievers: evaluates retrieval (evidence: `knowledge/hybrid-retrieval/6-evaluate.py`)
- Retrieval evaluation → Rank fusion: evaluates fusion (evidence: `knowledge/hybrid-retrieval/6-evaluate.py`)
- Retrieval evaluation → Result reranking: evaluates reranking (evidence: `knowledge/hybrid-retrieval/6-evaluate.py`)
- YouTube transcript server → Transcript service: calls service (evidence: `mcp/servers/youtube/server.py`)
- Transcript service → Video ID parser: extracts ID (evidence: `mcp/servers/youtube/src/service.py`)
- Transcript service → YouTube transcripts: fetches transcript (evidence: `mcp/servers/youtube/src/service.py`)
