# lorenzejay/agentic-rag-practical-example architecture

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

- Interactive diagram: https://gitdiagram.com/lorenzejay/agentic-rag-practical-example
- Repository: https://github.com/lorenzejay/agentic-rag-practical-example

## Overview

##### What this project is (type + purpose)

This is a **Python “agentic RAG” orchestration project** built on **crewAI**. It defines a **hierarchical multi-agent system** where a **Manager agent** routes a user query into one or more tasks, delegating to specialized agents that use specialized tools:

- **WeaviateTool**: RAG over **internal documents** (vector DB retrieval)
- **ExaSearchTool**: RAG over **web/external search**
- **Groq** (and/or OpenAI per `.env` note): LLM inference for reasoning/summarization

It looks like a **template**/reference implementation that loads documents, runs a crew process, and produces outputs like `report.md` and artifacts in `outputs/`.

So the “system” is less a web service and more a **CLI-run orchestration pipeline** with external dependencies (LLM providers + Weaviate + web search).

Key directories/files and what they represent:

- `src/agentic_rag/main.py`
**Entry point** (invoked via `crewai run`). Owns CLI/runtime inputs and kicks off execution.

- `src/agentic_rag/crew.py`
**Orchestration assembly**: constructs the Crew, registers agents, attaches tools, sets hierarchical manager process.

- `src/agentic_rag/config/agents.yaml`
Declarative **agent definitions**: roles, goals, model settings, tool access, etc.

- `src/agentic_rag/config/tasks.yaml`
Declarative **task graph**: task descriptions, expected outputs, ordering/dependencies.

- `src/agentic_rag/tools/weaviate_tool.py`
Integration boundary to **Weaviate** (vector DB retrieval). This is a major component.

- `src/agentic_rag/tools/custom_tool.py`
Custom tools / extension point. (Also indicates where ExaSearch might be implemented if not separately present in tree.)

- `src/agentic_rag/load_docs.py`
**Ingestion/indexing pipeline** (likely reads from `internal_docs/` and pushes embeddings/docs into Weaviate).

- `docker-compose.yml`

- `internal_docs/*.md`
Data source for internal knowledge.

- `report.md`, `outputs/*`
Output artifacts (end of the workflow).

- `pyproject.toml`, `uv.lock`

##### What the README adds (behavior + interactions)

The README confirms:
- **Hierarchical manager-agent pattern** (manager assigns tasks)
- Specialized RAG tools:
- Weaviate (internal)
- Exa (web)
- **Groq** for fast inference (plus mention of `OPENAI_API_KEY`, so LLM provider is an external service boundary)
- Output: generates a `report.md`

##### Level 0 (Context)
Actors / external systems:
- **User / Operator** (runs `crewai run`, provides prompt/query)
- **LLM Provider** (Groq + possibly OpenAI)
- **Weaviate** (vector database)
- **Web Search Provider** (ExaSearch)
- (Optional) **Local filesystem** (internal_docs input, outputs/report output)

##### Level 1 (Containers)
- **AgenticRag CLI Application (Python)**
- Runs crewAI process
- Reads YAML configs
- Calls tools
- Writes outputs

- **Weaviate (Docker container)**
- Stores vectors/documents
- Serves semantic search

- **LLM Inference Service (Groq/OpenAI)**
- Used by agents for reasoning and generation

- **Exa Search API**
- Used for web retrieval

- **Filesystem**
- `internal_docs/` as knowledge source
- `report.md` and `outputs/` as sinks

##### Level 2 (Components inside the Python app)
- `main.py` → **Runtime/CLI entry**
- `crew.py` → **Crew builder / Manager-agent orchestration**
- `config/agents.yaml` → **Agent registry/config**
- `config/tasks.yaml` → **Task definitions / workflow**
- `tools/weaviate_tool.py` → **Weaviate retrieval tool**
- `tools/custom_tool.py` → **Custom/extension tools (possibly Exa wrapper)**
- `load_docs.py` → **Document ingestion/indexing**

##### `load_docs.py` → Weaviate: upsert documents + vectors

Even if the README doesn’t detail ingestion, the presence of `load_docs.py` + `internal_docs/` + Weaviate strongly suggests it; include it as a separate flow.

- **crewAI** (orchestration framework)
- **Python 3.10–3.13**
- **Weaviate** (vector DB) + “docker-compose” runtime
- **Groq** and/or **OpenAI** (LLM inference)
- **ExaSearch** (web retrieval)
- **Markdown docs** as source format

##### Required elements
- **Clear labels**: use exact names where possible (`crew.py`, `weaviate_tool.py`, `agents.yaml`)
- “loads config”, “delegates task”, “retrieves passages”, “calls LLM”, “writes report”
- Another for **external services/APIs**
- Another for **data stores** (Weaviate, filesystem)
- Another for **artifacts** (reports)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0 — Context
  %% =========================
  subgraph L0["Level 0 — Context (Agentic RAG Orchestration)"]
    direction TB

    User["User / Operator\n(runs: crewai run)"]:::actor

    subgraph Local["Local Machine (Trust Boundary)"]
      direction TB
      CLI["AgenticRag CLI App\n(Python + crewAI)"]:::container
      FS[("Local Filesystem")]:::datastore
      Docs[("internal_docs/\n(Markdown sources)")]:::datastore
      Artifacts["Artifacts\nreport.md + outputs/*"]:::artifact
    end

    subgraph Internet["Internet Services (Trust Boundary)"]
      direction TB
      LLM["LLM Provider\n(Groq / OpenAI)"]:::external
      Exa["Exa Search API\n(Web Retrieval)"]:::external
    end

    Weaviate[("Weaviate Vector DB\n(Docker container)")]:::datastore

    User -->|"invokes_query"| CLI
    CLI -->|"reads_inputs"| FS
    CLI -->|"writes_report_artifacts"| Artifacts

    CLI -->|"calls_llm_inference"| LLM
    CLI -->|"web_search_retrieval"| Exa
    CLI -->|"vector_search_retrieval"| Weaviate
    Docs -->|"source_documents"| CLI
  end

  %% =========================
  %% Level 1 — Containers
  %% =========================
  subgraph L1["Level 1 — Containers (Runtime + Setup)"]
    direction TB

    subgraph Runtime["Runtime Flow (Query → RAG → Synthesis → Report)"]
      direction TB
      U1["User / Operator"]:::actor
      App1["AgenticRag CLI Application\n(crewai + Python)"]:::container
      LLM1["LLM Inference Service\n(Groq/OpenAI)"]:::external
      Exa1["ExaSearch API"]:::external
      Wv1[("Weaviate (docker-compose)")]:::datastore
      FS1[("Filesystem\n(internal_docs/, outputs/, report.md)")]:::datastore

      U1 -->|"run_and_prompt"| App1
      App1 -->|"load_docs_read_write"| FS1
      App1 -->|"retrieve_internal"| Wv1
      App1 -->|"retrieve_external"| Exa1
      App1 -->|"synthesize_generate"| LLM1
      App1 -->|"write_report"| FS1
    end

    subgraph Setup["Setup Flow (Ingest internal_docs → Index in Weaviate)"]
      direction TB
      Ingest["Doc Ingestion Job\n(load_docs.py)"]:::module
      Sources[("internal_docs/")]:::datastore
      Wv2[("Weaviate (docker-compose)")]:::datastore
      LLM2["Embedding/LLM Service\n(if applicable)"]:::external

      Sources -->|"read_markdown"| Ingest
      Ingest -->|"optional_embed"| LLM2
      Ingest -->|"upsert_vectors_docs"| Wv2
    end
  end

  %% =========================
  %% Level 2 — Components (inside CLI app)
  %% =========================
  subgraph L2["Level 2 — Components (Repository Modules)"]
    direction TB

    subgraph App["AgenticRag CLI App (src/agentic_rag/*)"]
      direction TB

      Main["main.py\nCLI Entry / Runtime Runner"]:::module
      Crew["crew.py\nCrew Builder + Manager Orchestration"]:::module

      subgraph Config["config/ (Configuration-Driven)"]
        direction TB
        AgentsCfg["agents.yaml\nAgent Definitions"]:::config
        TasksCfg["tasks.yaml\nTask Graph / Workflow"]:::config
      end

      subgraph Tools["tools/ (Tool-Based Capabilities)"]
        direction TB
        WTool["weaviate_tool.py\nWeaviateTool (Internal RAG)"]:::tool
        CTool["custom_tool.py\nCustom Tool Extension\n(e.g., Exa wrapper)"]:::tool
      end

      LoadDocs["load_docs.py\nIngestion / Indexing Pipeline"]:::module

      Manager["Manager Agent\n(hierarchical routing)"]:::agent
      Specialists["Specialist Agents\n(research/summarize/etc.)"]:::agent

      Main -->|"initialize_and_start"| Crew
      Crew -->|"loads_config"| AgentsCfg
      Crew -->|"loads_tasks"| TasksCfg

      Crew -->|"creates"| Manager
      Manager -->|"delegates_tasks"| Specialists

      Specialists -->|"internal_retrieval"| WTool
      Specialists -->|"external_retrieval"| CTool
      Specialists -->|"prompt_with_context"| LLMsvc["LLM Provider\n(Groq/OpenAI)"]:::external

      WTool -->|"query_vectors"| WvSvc[("Weaviate Vector DB")]:::datastore
      CTool -->|"web_search"| ExaSvc["Exa Search API"]:::external

      Crew -->|"writes_outputs"| OutFS[("Filesystem\nreport.md, outputs/*")]:::datastore

      DocsFS[("internal_docs/")]:::datastore
      DocsFS -->|"read_sources"| LoadDocs
      LoadDocs -->|"index_upsert"| WvSvc
    end

    subgraph Deploy["Runtime/Deployment Support"]
      direction TB
      Compose["docker-compose.yml\n(Weaviate local runtime)"]:::deploy
      Asset["assets/practical_agentic_rag.png\n(reference architecture image)"]:::artifact
      Compose -->|"starts"| WvSvc
    end
  end

  %% =========================
  %% Click events (from component mapping)
  %% =========================
  click Main "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/main.py"
  click Crew "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/crew.py"
  click AgentsCfg "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/config/agents.yaml"
  click TasksCfg "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/config/tasks.yaml"
  click WTool "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/tools/weaviate_tool.py"
  click CTool "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/tools/custom_tool.py"
  click LoadDocs "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/src/agentic_rag/load_docs.py"
  click Compose "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/docker-compose.yml"
  click Docs "https://github.com/lorenzejay/agentic-rag-practical-example/tree/main/internal_docs/"
  click DocsFS "https://github.com/lorenzejay/agentic-rag-practical-example/tree/main/internal_docs/"
  click Artifacts "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/report.md"
  click OutFS "https://github.com/lorenzejay/agentic-rag-practical-example/tree/main/outputs/"
  click Asset "https://github.com/lorenzejay/agentic-rag-practical-example/blob/main/assets/practical_agentic_rag.png"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#FFF3CD,stroke:#B08900,stroke-width:1.5px,color:#3A2C00
  classDef container fill:#D6EAF8,stroke:#1B4F72,stroke-width:1.5px,color:#0B2D3A
  classDef module fill:#E8DAEF,stroke:#512E5F,stroke-width:1.5px,color:#2E1437
  classDef config fill:#FADBD8,stroke:#922B21,stroke-width:1.5px,color:#4A0E0B
  classDef tool fill:#D5F5E3,stroke:#1E8449,stroke-width:1.5px,color:#0E3A22
  classDef agent fill:#FDEBD0,stroke:#A04000,stroke-width:1.5px,color:#4A2100
  classDef datastore fill:#FCF3CF,stroke:#7D6608,stroke-width:1.5px,color:#3A3200
  classDef external fill:#F2F4F4,stroke:#566573,stroke-width:1.5px,color:#1F2A33
  classDef artifact fill:#EAECEE,stroke:#2C3E50,stroke-width:1.5px,color:#11181F
  classDef deploy fill:#D4EFDF,stroke:#0E6251,stroke-width:1.5px,color:#083B33
```
