# calvhobbes/ai-agents architecture

> Architecture diagram of the GitHub repository calvhobbes/ai-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/calvhobbes/ai-agents
- Repository: https://github.com/calvhobbes/ai-agents

## Overview

##### Project Type and Purpose
- This is a small demo project (“sample AI agent code”) that implements Retrieval-Augmented Generation (RAG) agents using LlamaIndex for vector indexing plus Google’s Gemini-Flash model (via the google.generativeai client) in place of the paid Vertex AI API.
- It consists of two Jupyter notebooks showing two flavors of an “agent” (one with a RAG pipeline, one illustrating pure Gemini-Flash agent patterns), plus the requirements file.

##### High-Level Architecture
A. Data & Indexing Layer
– Source documents or data you want to query (PDFs, text, etc.)
– LlamaIndex component that ingests those documents and builds/stores a vector store.
B. Agent Orchestration Layer
– A Python “controller” (the notebook code) that:
- Accepts a user query
- Fetches relevant context from the vector store via LlamaIndex
- Packages the context + query into a prompt template
- Invokes the Gemini-Flash model through google.generativeai
C. LLM Service Layer
– External Gemini-Flash API endpoint (hosted by Google) that returns model completions.

##### Main Components
1. “Data Sources” node (local files, external corpus)
2. “LlamaIndex” node (vector store & index builder)
3. “Agent Controller” node (the notebook code split into: ingestion module, query handler, prompt builder)
4. “Google Gemini-Flash” node (external service)
5. “User / Client” node (the user or upstream service sending queries)

##### Relationships & Data Flows
- User → Agent Controller: submits a query
- Agent Controller → LlamaIndex: “retrieve top-k relevant documents”
- LlamaIndex → Agent Controller: returns document embeddings + metadata
- Agent Controller → Gemini-Flash API: submits prompt (query + context)
- Gemini-Flash → Agent Controller: returns text completion
- Agent Controller → User: returns the final answer

##### Architectural Patterns & Design Principles
- Layered separation: keep data ingestion/indexing separate from “agent logic.”
- Modular notebook code: split into functions or classes for ingestion, retrieval, prompt-templating, and external calls.
- Dependency management: capture all third-party libraries in agentic_rag_llamaindex_requirements.txt.
- Stateless orchestration: the notebooks themselves are stateless controllers that call out to the vector store and LLM service.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User / Client"]:::user

    %% Data & Indexing Layer
    DataSources["Data Sources"]:::green
    LlamaIndex["LlamaIndex Vector Store"]:::green

    %% Agent Orchestration Layer
    NotebookRAG["Agentic_RAG_with_LLamaIndex.ipynb"]:::blue
    NotebookGemini["Gemini_Agents.ipynb"]:::blue

    %% LLM Service Layer
    GeminiFlash["Google Gemini-Flash API"]:::orange
    VertexAI["Vertex AI (legacy)"]:::legacy

    %% Project Files
    Requirements["agentic_rag_llamaindex_requirements.txt"]:::docs
    Readme["readme.md"]:::docs

    %% Data & Indexing flows
    DataSources -->|"ingest documents"| LlamaIndex

    %% User to Controllers
    User -->|"submits query"| NotebookRAG
    User -->|"submits query"| NotebookGemini

    %% RAG pipeline flows
    NotebookRAG -->|"retrieve(index.query)"| LlamaIndex
    LlamaIndex -->|"return embeddings+metadata"| NotebookRAG
    NotebookRAG -.->|"legacy calls"| VertexAI
    NotebookRAG -->|"generate(prompt)"| GeminiFlash
    GeminiFlash -->|"completion response"| NotebookRAG
    NotebookRAG -->|"return answer"| User

    %% Pure Gemini-Flash pipeline
    NotebookGemini -->|"generate(prompt)"| GeminiFlash
    GeminiFlash -->|"completion response"| NotebookGemini
    NotebookGemini -->|"return answer"| User

    %% Documentation and requirements
    NotebookRAG -.-> Requirements
    NotebookRAG -.-> Readme
    NotebookGemini -.-> Requirements
    NotebookGemini -.-> Readme

    %% Click Events
    click NotebookRAG "https://github.com/calvhobbes/ai-agents/blob/main/Agentic_RAG_with_LLamaIndex.ipynb"
    click NotebookGemini "https://github.com/calvhobbes/ai-agents/blob/main/Gemini_Agents.ipynb"
    click Requirements "https://github.com/calvhobbes/ai-agents/blob/main/agentic_rag_llamaindex_requirements.txt"
    click Readme "https://github.com/calvhobbes/ai-agents/blob/main/readme.md"

    %% Styles
    classDef green fill:#8fbc8f,stroke:#333,stroke-width:1px
    classDef blue fill:#add8e6,stroke:#333,stroke-width:1px
    classDef orange fill:#ffa500,stroke:#333,stroke-width:1px
    classDef legacy fill:#dddddd,stroke:#888,stroke-width:1px,stroke-dasharray: 5 5
    classDef user fill:#fffacd,stroke:#333,stroke-width:1px
    classDef docs fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
