# vectorinstitute/agent-bootcamp architecture

> Architecture diagram of the GitHub repository vectorinstitute/agent-bootcamp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vectorinstitute/agent-bootcamp
- Repository: https://github.com/vectorinstitute/agent-bootcamp

## Overview

##### Project type and purpose
- This repository is an open-source collection of Python reference implementations (CLI and Gradio apps) for “Agent Bootcamp,” demonstrating retrieval-augmented generation (RAG) agents, evaluation pipelines, and orchestration using modern tools.
- It is not a traditional full-stack web app, but rather a modular toolset/library with multiple example modules (“basics,” “frameworks,” “evals”), shared utilities, CI/CD, docs, and tests.

##### File structure
Top-level directories and files:
- src/ – contains three main module groups:
– 1_basics: minimal proof-of-concept ReAct agents
– 2_frameworks: SDK-based agents (OpenAI Agents SDK, Langfuse integration, multi-agent, code interpreter)
– 3_evals: evaluation pipelines (LLM-as-judge, synthetic data)
– prompts.py: shared prompt templates
– utils/: shared helpers (async, data loading, env vars, Gradio messages, logging, Langfuse setup, tools for code interpreter, Weaviate, etc.)
- docs/, mkdocs.yml – documentation site for the project
- tests/ – unit/integration tests organized by data and tool tests
- .github/workflows/ – CI pipelines for linting, docs, tests
- pyproject.toml – project metadata and dependencies

##### README for additional insights
- Confirms the three module categories and their purposes.
- Highlights external services: OpenAI API, Langfuse for traceability, Hugging Face Datasets, Weaviate vector store.
- Describes how to run each demo via CLI or Gradio, and how to execute evaluation scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    subgraph "User Interfaces" 
        direction TB
        CLI1["CLI Runner (Basics)"]:::frontend
        CLI2["CLI Runner (Frameworks)"]:::frontend
        GR1["Gradio App (Search Demo)"]:::frontend
        GR2["Gradio App (ReAct RAG Basic)"]:::frontend
        GR3["Gradio App (ReAct RAG Frameworks)"]:::frontend
        GR4["Gradio App (Langfuse SDK)"]:::frontend
        GR5["Gradio App (Code Interpreter)"]:::frontend
        GR6["Gradio App (Synthetic Diversity)"]:::frontend
    end

    %% Core Modules
    subgraph "Core Modules" 
        direction TB
        MB1["Basics Module"]:::core
        MF1["Frameworks Module"]:::core
        ME1["Evals Module"]:::core
    end

    %% Shared Utilities
    subgraph "Shared Utility Layer"
        direction TB
        PROMPTS["prompts.py"]:::util
        UTILS["utils/"]:::util
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAI["OpenAI API"]:::external
        LF["Langfuse"]:::external
        WEAV["Weaviate Vector Store"]:::external
        HFDATA["Hugging Face Datasets"]:::external
    end

    %% Data Stores
    subgraph "Data Stores & Artifacts"
        direction TB
        SYNTH["Synthetic Datasets"]:::datastore
        EVALRES["Evaluation Results"]:::datastore
    end

    %% CI & Docs
    subgraph "CI/CD, Tests & Docs"
        direction TB
        TESTS["tests/"]:::infra
        CI1["code_checks.yml"]:::infra
        CI2["unit_tests.yml"]:::infra
        CI3["docs.yml"]:::infra
        DOCS["docs/ & mkdocs.yml"]:::infra
    end

    %% Relationships
    CLI1 -->|uses| MB1
    GR1 -->|uses| MB1
    GR2 -->|uses| MB1

    CLI2 -->|uses| MF1
    GR3 -->|uses| MF1
    GR4 -->|uses| MF1
    GR5 -->|uses| MF1

    MB1 ---|imports| PROMPTS
    MF1 ---|imports| PROMPTS
    ME1 ---|imports| PROMPTS

    MB1 ---|calls| UTILS
    MF1 ---|calls| UTILS
    ME1 ---|calls| UTILS

    UTILS -->|LLM calls| OAI
    UTILS -->|Vector ops| WEAV
    UTILS -->|Dataset ops| HFDATA
    UTILS -->|Tracing| LF

    OAI -->|responses| MB1
    OAI -->|responses| MF1
    OAI -->|responses| ME1

    MB1 -->|logs/traces| LF
    MF1 -->|logs/traces| LF
    ME1 -->|logs/traces| LF

    ME1 -->|writes| SYNTH
    ME1 -->|writes| EVALRES
    SYNTH -->|visualize| GR6
    EVALRES -->|visualize| GR6

    TESTS -->|validate| CLI1
    TESTS -->|validate| CLI2
    TESTS -->|validate| GR1
    TESTS -->|validate| GR2
    TESTS -->|validate| GR3
    TESTS -->|validate| GR4
    TESTS -->|validate| GR5
    TESTS -->|validate| GR6
    TESTS -->|validate| MB1
    TESTS -->|validate| MF1
    TESTS -->|validate| ME1
    TESTS -->|validate| UTILS

    CI1 -->|runs| TESTS
    CI2 -->|runs| TESTS
    CI3 -->|checks| DOCS

    DOCS -->|docs for| MB1
    DOCS -->|docs for| MF1
    DOCS -->|docs for| ME1
    DOCS -->|docs for| UTILS

    %% Click Events Interfaces
    click CLI1 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/1_basics/1_react_rag/cli.py"
    click CLI2 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/2_frameworks/1_react_rag/cli.py"
    click GR1 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/1_basics/0_search_demo/app.py"
    click GR2 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/1_basics/1_react_rag/app.py"
    click GR3 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/2_frameworks/1_react_rag/app.py"
    click GR4 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/2_frameworks/1_react_rag/langfuse_gradio.py"
    click GR5 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/2_frameworks/3_code_interpreter/app.py"
    click GR6 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/3_evals/2_synthetic_data/gradio_visualize_diversity.py"

    %% Click Events Core Modules
    click MB1 "https://github.com/vectorinstitute/agent-bootcamp/tree/main/src/1_basics/"
    click MF1 "https://github.com/vectorinstitute/agent-bootcamp/tree/main/src/2_frameworks/"
    click ME1 "https://github.com/vectorinstitute/agent-bootcamp/tree/main/src/3_evals/"

    %% Click Events Utilities
    click PROMPTS "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/prompts.py"
    click UTILS "https://github.com/vectorinstitute/agent-bootcamp/tree/main/src/utils/"

    %% Click Events Langfuse
    click LF "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/langfuse/oai_sdk_setup.py"
    click LF "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/langfuse/otlp_env_setup.py"
    click LF "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/langfuse/shared_client.py"
    click LF "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/langfuse/trace_id.py"

    %% Click Events Weaviate
    click WEAV "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/tools/kb_weaviate.py"

    %% Click Events HF Datasets
    click HFDATA "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/data/load_dataset.py"
    click HFDATA "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/data/chunk_hf_dataset.py"
    click HFDATA "https://github.com/vectorinstitute/agent-bootcamp/blob/main/src/utils/data/batching.py"

    %% Click Events Testing & CI
    click TESTS "https://github.com/vectorinstitute/agent-bootcamp/tree/main/tests/"
    click CI1 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/.github/workflows/code_checks.yml"
    click CI2 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/.github/workflows/unit_tests.yml"
    click CI3 "https://github.com/vectorinstitute/agent-bootcamp/blob/main/.github/workflows/docs.yml"

    %% Click Events Docs
    click DOCS "https://github.com/vectorinstitute/agent-bootcamp/tree/main/docs/"
    click DOCS "https://github.com/vectorinstitute/agent-bootcamp/blob/main/mkdocs.yml"
    click DOCS "https://github.com/vectorinstitute/agent-bootcamp/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#DFF5E1,stroke:#28a745,color:#28a745
    classDef util fill:#FFF4C1,stroke:#f1c40f,color:#f39c12
    classDef external fill:#FDE2E2,stroke:#e02f2f,color:#e02f2f
    classDef infra fill:#E0E0E0,stroke:#707070,color:#707070
    classDef datastore fill:#E8F0FE,stroke:#4285F4,color:#4285F4
```
