# mghayaz/generativeai-learn architecture

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

- Interactive diagram: https://gitdiagram.com/mghayaz/generativeai-learn
- Repository: https://github.com/mghayaz/generativeai-learn

## Overview

This repository is a collection of generative-AI learning examples, not one integrated application. Its most complete user-facing workflow is the speaking agent: a CLI starts a conversation, the workflow uses an LLM and may dispatch tool calls, and speech modules provide audio input/output. Separate examples demonstrate RAG, queued multimodal processing, persistent graph conversations, memory, and tool-using agents. The graph follows explicit imports and calls where excerpts show them; several unsampled subsystems are included from the file tree, but their internal links are omitted rather than inferred.

Main entry points: [`genAI_Chapters/speaking_agent/workflow/chat_loop.py`](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/workflow/chat_loop.py) (Conversation loop), [`genAI_Chapters/speaking_agent/llms/chat.py`](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/chat.py) (LLM generation), [`genAI_Chapters/speaking_agent/workflow/tool_handler.py`](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/workflow/tool_handler.py) (Tool call handler), [`genAI_Chapters/speaking_agent/tools/executor.py`](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/executor.py) (Tool executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Speaking agent"]
  node_app["App entry<br/>[main.py]"]
  node_chatloop["Conversation loop<br/>[chat_loop.py]"]
  node_llmchat["LLM generation<br/>[chat.py]"]
  node_llmclient["Gemini client<br/>[client.py]"]
  node_history["Chat history<br/>[history.py]"]
  node_prompt["System prompt<br/>[system.py]"]
  node_schemas["Tool schemas<br/>[schemas.py]"]
  node_toolhandler["Tool call handler<br/>[tool_handler.py]"]
  node_executor["Tool executor<br/>[executor.py]"]
  node_policy["Tool policy<br/>[policy.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_tool_schema["Schema builder<br/>[schema_builder.py]"]
  node_weather["Weather tool<br/>[weather.py]"]
  node_speech_input["Microphone input<br/>[microphone.py]"]
  node_speech_recognition["Speech recognition<br/>[stt.py]"]
  node_audio["Audio handling<br/>[audio.py]"]
  node_speech_output["Speech synthesis<br/>[tts.py]"]
end

subgraph group_rag["Retrieval examples"]
  node_rag_ingest["PDF indexing<br/>[indexing_pdf.py]"]
  node_rag_chunk["Document chunking"]
  node_rag_embed["Embedding and indexing"]
  node_rag_query["RAG query example<br/>[united_RAG.py]"]
  node_rag_store[("Qdrant vector store")]
  node_async_api["Async RAG API<br/>[server.py]"]
  node_rq["Redis job queue<br/>[rq.py]"]
  node_worker["RAG worker<br/>[worker.py]"]
end

subgraph group_agents["Agents and memory"]
  node_agent_code["Coding and weather agent<br/>[agent_to_code.py]"]
  node_memory_agent["Memory-aware agent<br/>[mem_agent.py]"]
  node_memory_store[("Memory stores")]
end

subgraph group_graph["Graph and model examples"]
  node_mongo_graph["Mongo-backed graph<br/>[mongo_in_rag.py]"]
  node_mongodb[("MongoDB checkpoints")]
  node_langgraph["LangGraph examples"]
end

subgraph group_fundamentals["AI fundamentals"]
end

node_user(("CLI user"))
node_gemini_api["Gemini service"]
node_redis[("Redis")]

node_user -->|"starts"| node_app
node_app -->|"runs"| node_chatloop
node_chatloop -.->|"requests response"| node_llmchat
node_llmchat -->|"uses client"| node_llmclient
node_llmchat -->|"sets instruction"| node_prompt
node_llmchat -->|"builds tool config"| node_tool_schema
node_chatloop -.->|"updates history"| node_history
node_chatloop -.->|"handles calls"| node_toolhandler
node_toolhandler -->|"appends messages"| node_history
node_toolhandler -->|"executes calls"| node_executor
node_toolhandler -->|"returns summary"| node_schemas
node_executor -->|"checks policy"| node_policy
node_executor -->|"resolves tool"| node_registry
node_tool_schema -.->|"uses registry"| node_registry
node_registry -.->|"registers tool"| node_weather
node_user -.->|"speaks"| node_speech_input
node_speech_input -.->|"captures audio"| node_speech_recognition
node_speech_recognition -.->|"provides text"| node_chatloop
node_chatloop -.->|"speaks response"| node_speech_output
node_speech_output -.->|"creates audio"| node_audio
node_rag_ingest -.->|"prepares documents"| node_rag_chunk
node_rag_chunk -.->|"chunks documents"| node_rag_embed
node_rag_embed -.->|"indexes vectors"| node_rag_store
node_user -->|"asks question"| node_rag_query
node_rag_query -->|"searches chunks"| node_rag_store
node_rag_query -->|"generates answer"| node_gemini_api
node_user -->|"submits query"| node_async_api
node_async_api -->|"enqueues job"| node_rq
node_async_api -->|"queues worker task"| node_worker
node_rq -.->|"stores job"| node_redis
node_worker -->|"searches chunks"| node_rag_store
node_worker -->|"generates answer"| node_gemini_api
node_user -->|"requests task"| node_agent_code
node_agent_code -->|"requests tool calls"| node_gemini_api
node_agent_code -->|"returns tool result"| node_user
node_user -->|"asks question"| node_memory_agent
node_memory_agent -->|"searches and adds"| node_memory_store
node_memory_agent -->|"generates response"| node_gemini_api
node_mongo_graph -->|"invokes model"| node_gemini_api
node_mongo_graph -->|"persists checkpoints"| node_mongodb
node_user -->|"submits messages"| node_mongo_graph

click node_app "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/app/main.py"
click node_chatloop "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/workflow/chat_loop.py"
click node_llmchat "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/chat.py"
click node_llmclient "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/client.py"
click node_history "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/history.py"
click node_prompt "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/prompts/system.py"
click node_schemas "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/models/schemas.py"
click node_toolhandler "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/workflow/tool_handler.py"
click node_executor "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/executor.py"
click node_policy "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/policy.py"
click node_registry "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/registry.py"
click node_tool_schema "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/schema_builder.py"
click node_weather "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/weather.py"
click node_speech_input "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/microphone.py"
click node_speech_recognition "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/stt.py"
click node_audio "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/audio.py"
click node_speech_output "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/tts.py"
click node_rag_ingest "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/indexing_pdf.py"
click node_rag_chunk "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/chunking_with_langchain.py"
click node_rag_embed "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/embed_with_langchain.py"
click node_rag_query "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/united_RAG.py"
click node_async_api "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG_Asyncio_and_multimodal/server.py"
click node_rq "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG_Asyncio_and_multimodal/client_line/rq.py"
click node_worker "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG_Asyncio_and_multimodal/worker_line/worker.py"
click node_agent_code "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/agenticAi/agent_to_code.py"
click node_memory_agent "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/memory/mem_agent.py"
click node_mongo_graph "https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/MongoDb_LangGraph/mongo_in_rag.py"
click node_langgraph "https://github.com/mghayaz/generativeai-learn/tree/main/genAI_Chapters/LangGraph"

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_app,node_chatloop,node_llmchat,node_llmclient,node_history,node_prompt,node_schemas,node_toolhandler,node_executor,node_policy,node_registry,node_tool_schema,node_weather,node_speech_input,node_speech_recognition,node_audio,node_speech_output,node_user toneBlue
class node_rag_ingest,node_rag_chunk,node_rag_embed,node_rag_query,node_rag_store,node_async_api,node_rq,node_worker,node_redis toneAmber
class node_agent_code,node_memory_agent,node_memory_store toneMint
class node_mongo_graph,node_mongodb,node_langgraph toneRose
class node_gemini_api toneIndigo
```

## Components

### Speaking agent

- [App entry](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/app/main.py): `genAI_Chapters/speaking_agent/app/main.py`
- [Conversation loop](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/workflow/chat_loop.py): `genAI_Chapters/speaking_agent/workflow/chat_loop.py`
- [LLM generation](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/chat.py): `genAI_Chapters/speaking_agent/llms/chat.py`
- [Gemini client](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/client.py): `genAI_Chapters/speaking_agent/llms/client.py`
- [Chat history](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/llms/history.py): `genAI_Chapters/speaking_agent/llms/history.py`
- [System prompt](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/prompts/system.py): `genAI_Chapters/speaking_agent/prompts/system.py`
- [Tool schemas](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/models/schemas.py): `genAI_Chapters/speaking_agent/models/schemas.py`
- [Tool call handler](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/workflow/tool_handler.py): `genAI_Chapters/speaking_agent/workflow/tool_handler.py`
- [Tool executor](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/executor.py): `genAI_Chapters/speaking_agent/tools/executor.py`
- [Tool policy](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/policy.py): `genAI_Chapters/speaking_agent/tools/policy.py`
- [Tool registry](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/registry.py): `genAI_Chapters/speaking_agent/tools/registry.py`
- [Schema builder](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/schema_builder.py): `genAI_Chapters/speaking_agent/tools/schema_builder.py`
- [Weather tool](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/tools/weather.py): `genAI_Chapters/speaking_agent/tools/weather.py`
- [Microphone input](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/microphone.py): `genAI_Chapters/speaking_agent/speech/microphone.py`
- [Speech recognition](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/stt.py): `genAI_Chapters/speaking_agent/speech/stt.py`
- [Audio handling](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/audio.py): `genAI_Chapters/speaking_agent/speech/audio.py`
- [Speech synthesis](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/speaking_agent/speech/tts.py): `genAI_Chapters/speaking_agent/speech/tts.py`

### Retrieval examples

- [PDF indexing](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/indexing_pdf.py): `genAI_Chapters/RAG/indexing_pdf.py`
- [Document chunking](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/chunking_with_langchain.py): `genAI_Chapters/RAG/chunking_with_langchain.py`
- [Embedding and indexing](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/embed_with_langchain.py): `genAI_Chapters/RAG/embed_with_langchain.py`
- [RAG query example](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG/united_RAG.py): `genAI_Chapters/RAG/united_RAG.py`
- **Qdrant vector store**
- [Async RAG API](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG_Asyncio_and_multimodal/server.py): `genAI_Chapters/RAG_Asyncio_and_multimodal/server.py`
- [Redis job queue](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG_Asyncio_and_multimodal/client_line/rq.py): `genAI_Chapters/RAG_Asyncio_and_multimodal/client_line/rq.py`
- [RAG worker](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/RAG_Asyncio_and_multimodal/worker_line/worker.py): `genAI_Chapters/RAG_Asyncio_and_multimodal/worker_line/worker.py`

### Agents and memory

- [Coding and weather agent](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/agenticAi/agent_to_code.py): `genAI_Chapters/agenticAi/agent_to_code.py`
- [Memory-aware agent](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/memory/mem_agent.py): `genAI_Chapters/memory/mem_agent.py`
- **Memory stores**

### Graph and model examples

- [Mongo-backed graph](https://github.com/mghayaz/generativeai-learn/blob/main/genAI_Chapters/MongoDb_LangGraph/mongo_in_rag.py): `genAI_Chapters/MongoDb_LangGraph/mongo_in_rag.py`
- **MongoDB checkpoints**
- [LangGraph examples](https://github.com/mghayaz/generativeai-learn/tree/main/genAI_Chapters/LangGraph): `genAI_Chapters/LangGraph`

### Other components

- **CLI user**
- **Gemini service**
- **Redis**

## Connections

- CLI user → App entry: starts (evidence: `genAI_Chapters/speaking_agent/app/main.py`)
- App entry → Conversation loop: runs (evidence: `genAI_Chapters/speaking_agent/app/main.py`)
- Conversation loop → LLM generation: requests response (evidence: `genAI_Chapters/speaking_agent/workflow/chat_loop.py`)
- LLM generation → Gemini client: uses client (evidence: `genAI_Chapters/speaking_agent/llms/chat.py`)
- LLM generation → System prompt: sets instruction (evidence: `genAI_Chapters/speaking_agent/llms/chat.py`)
- LLM generation → Schema builder: builds tool config (evidence: `genAI_Chapters/speaking_agent/llms/chat.py`)
- Conversation loop → Chat history: updates history (evidence: `genAI_Chapters/speaking_agent/workflow/chat_loop.py`)
- Conversation loop → Tool call handler: handles calls (evidence: `genAI_Chapters/speaking_agent/workflow/chat_loop.py`)
- Tool call handler → Chat history: appends messages (evidence: `genAI_Chapters/speaking_agent/workflow/tool_handler.py`)
- Tool call handler → Tool executor: executes calls (evidence: `genAI_Chapters/speaking_agent/workflow/tool_handler.py`)
- Tool call handler → Tool schemas: returns summary (evidence: `genAI_Chapters/speaking_agent/workflow/tool_handler.py`)
- Tool executor → Tool policy: checks policy (evidence: `genAI_Chapters/speaking_agent/tools/executor.py`)
- Tool executor → Tool registry: resolves tool (evidence: `genAI_Chapters/speaking_agent/tools/executor.py`)
- Schema builder → Tool registry: uses registry
- Tool registry → Weather tool: registers tool
- CLI user → Microphone input: speaks
- Microphone input → Speech recognition: captures audio
- Speech recognition → Conversation loop: provides text (evidence: `genAI_Chapters/speaking_agent/workflow/chat_loop.py`)
- Conversation loop → Speech synthesis: speaks response (evidence: `genAI_Chapters/speaking_agent/workflow/chat_loop.py`)
- Speech synthesis → Audio handling: creates audio
- PDF indexing → Document chunking: prepares documents
- Document chunking → Embedding and indexing: chunks documents
- Embedding and indexing → Qdrant vector store: indexes vectors
- CLI user → RAG query example: asks question (evidence: `genAI_Chapters/RAG/united_RAG.py`)
- RAG query example → Qdrant vector store: searches chunks (evidence: `genAI_Chapters/RAG/united_RAG.py`)
- RAG query example → Gemini service: generates answer (evidence: `genAI_Chapters/RAG/united_RAG.py`)
- CLI user → Async RAG API: submits query (evidence: `genAI_Chapters/RAG_Asyncio_and_multimodal/server.py`)
- Async RAG API → Redis job queue: enqueues job (evidence: `genAI_Chapters/RAG_Asyncio_and_multimodal/server.py`)
- Async RAG API → RAG worker: queues worker task (evidence: `genAI_Chapters/RAG_Asyncio_and_multimodal/server.py`)
- Redis job queue → Redis: stores job
- RAG worker → Qdrant vector store: searches chunks (evidence: `genAI_Chapters/RAG_Asyncio_and_multimodal/worker_line/worker.py`)
- RAG worker → Gemini service: generates answer (evidence: `genAI_Chapters/RAG_Asyncio_and_multimodal/worker_line/worker.py`)
- CLI user → Coding and weather agent: requests task (evidence: `genAI_Chapters/agenticAi/agent_to_code.py`)
- Coding and weather agent → Gemini service: requests tool calls (evidence: `genAI_Chapters/agenticAi/agent_to_code.py`)
- Coding and weather agent → CLI user: returns tool result (evidence: `genAI_Chapters/agenticAi/agent_to_code.py`)
- CLI user → Memory-aware agent: asks question (evidence: `genAI_Chapters/memory/mem_agent.py`)
- Memory-aware agent → Memory stores: searches and adds (evidence: `genAI_Chapters/memory/mem_agent.py`)
- Memory-aware agent → Gemini service: generates response (evidence: `genAI_Chapters/memory/mem_agent.py`)
- Mongo-backed graph → Gemini service: invokes model (evidence: `genAI_Chapters/MongoDb_LangGraph/mongo_in_rag.py`)
- Mongo-backed graph → MongoDB checkpoints: persists checkpoints (evidence: `genAI_Chapters/MongoDb_LangGraph/mongo_in_rag.py`)
- CLI user → Mongo-backed graph: submits messages (evidence: `genAI_Chapters/MongoDb_LangGraph/mongo_in_rag.py`)
