# snowflake-labs/arctic_agentic_rag architecture

> Architecture diagram of the GitHub repository snowflake-labs/arctic_agentic_rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snowflake-labs/arctic_agentic_rag
- Repository: https://github.com/snowflake-labs/arctic_agentic_rag

## Overview

##### Project Type and Purpose
- This is an enterprise-focused, modular, retrieval-augmented generation (RAG) framework designed to handle ambiguous queries and deliver smarter, faster, and more reliable AI-driven workflows.
- It is built around agent-based modular design with multiple integrations for various LLM backends (including Azure OpenAI, Cortex, Ollama, and vLLM) and incorporates retrieval and ranking capabilities.
- The framework also supports YAML-based configuration and comes with prebuilt examples and demo projects.

##### File Structure to Extract Core Components
- The core package (“arctic_agentic_rag”) is organized into several submodules:
- Agent Module (arctic_agentic_rag/agent): Contains the agent logic driving the agentic workflow.
- LLM Module (arctic_agentic_rag/llm): Manages integrations with different LLM providers (azure_oai.py, cortex_complete.py, oai.py, ollama.py, vllm_provider.py). This is your bridge to various external AI services.
- Ranking Module (arctic_agentic_rag/ranking): Includes functionality for clustering and encoding to rank or cluster results.
- Retrieval Module (arctic_agentic_rag/retrieval): Provides the base interface plus implementations, such as cortex_search and qwen_retrieval for fetching information.
- Template Module (arctic_agentic_rag/template): Supports dynamic template creation/field templating for prompt engineering.
- Utility and Logging Modules: Provide cross-cutting support like logging, helper functions, and miscellaneous utilities.
- Additional directories like examples and projects demonstrate concrete use cases (e.g., ambiguous query resolution in Episode 1 and simple RAG demos).
- Configuration files (YAML in examples and projects) define how to set up pipelines and experiments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level container
    A["Arctic Agentic RAG Framework"]:::core

    %% Core Modules Container
    subgraph "Core Modules"
        A1["Agent Workflow Orchestrator"]:::module
        A2["LLM Providers Cluster"]:::module
        A3["Retrieval Engine"]:::retrieval
        A4["Ranking Engine"]:::ranking
        A5["Template Engine"]:::template
        A6["Utilities & Logging"]:::utility
    end

    %% LLM Providers Cluster Details
    subgraph "LLM Providers"
        L1["Azure OpenAI"]:::integration
        L2["Cortex (LLM)"]:::integration
        L3["OpenAI API"]:::integration
        L4["Ollama"]:::integration
        L5["vLLM"]:::integration
    end

    %% Retrieval Modules Details
    subgraph "Retrieval Modules"
        R1["Base Retrieval Interface"]:::retrieval
        R2["Cortex Search"]:::retrieval
        R3["Qwen Retrieval"]:::retrieval
    end

    %% Ranking Modules Details
    subgraph "Ranking Modules"
        K1["Clustering"]:::ranking
        K2["Encoder"]:::ranking
    end

    %% Template Modules Details
    subgraph "Template Modules"
        T1["Template Logic"]:::template
        T2["Field Templating"]:::template
    end

    %% Configuration & Demo Use Cases
    subgraph "Configurations & Demos"
        D1["Example: Ambiguity Detection"]:::config
        D2["Example: Simple RAG"]:::config
        D3["Example: Simple Template Agent"]:::config
        D4["Demo: Ambiguous QA"]:::config
    end

    %% Support Utilities Details
    subgraph "Support Utilities"
        U1["Logging"]:::utility
        U2["Other Utilities"]:::utility
    end

    %% Connections from Core Framework to Internal Modules
    A --> A1
    A --> A2
    A --> A3
    A --> A4
    A --> A5
    A --> A6

    %% Agent interactions
    A1 -->|"calls"| A2
    A1 -->|"invokes"| A3
    A1 -->|"receives_prompts_from"| A5

    %% LLM Cluster: connecting internal LLM cluster to individual providers
    A2 --> L1
    A2 --> L2
    A2 --> L3
    A2 --> L4
    A2 --> L5

    %% Retrieval Module Connections
    A3 --> R1
    A3 --> R2
    A3 --> R3

    %% Ranking: data flow from retrieval to ranking and back to agent
    R1 --> A4
    R2 --> A4
    R3 --> A4
    A4 --> A1

    %% Template modules feeding the agent
    T1 --> A1
    T2 --> A1

    %% Utilities support for core modules
    A1 --- U1
    A2 --- U1
    A3 --- U1
    A4 --- U1
    A5 --- U1
    A6 --- U1
    A1 --- U2
    A2 --- U2
    A3 --- U2
    A4 --- U2
    A5 --- U2
    A6 --- U2

    %% Configurations and demos provide setup for the agent module
    D1 --> A1
    D2 --> A1
    D3 --> A1
    D4 --> A1

    %% External communications: dashed lines for external API calls from LLM providers
    L1 -.->|"external"| A2
    L2 -.->|"external"| A2
    L3 -.->|"external"| A2
    L4 -.->|"external"| A2
    L5 -.->|"external"| A2

    %% Additional connection: retrieval engine to ranking engine
    A3 --> A4

    %% Click Events
    click A "https://github.com/snowflake-labs/arctic_agentic_rag/tree/main/arctic_agentic_rag"
    click A1 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/agent/agent.py"
    click L1 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/llm/azure_oai.py"
    click L2 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/llm/cortex_complete.py"
    click L3 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/llm/oai.py"
    click L4 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/llm/ollama.py"
    click L5 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/llm/vllm_provider.py"
    click R1 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/retrieval/base_retrieval.py"
    click R2 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/retrieval/cortex_search.py"
    click R3 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/retrieval/qwen_retrieval.py"
    click K1 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/ranking/clustering.py"
    click K2 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/ranking/encoder.py"
    click T1 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/template/template.py"
    click T2 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/template/field.py"
    click U1 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/logging.py"
    click U2 "https://github.com/snowflake-labs/arctic_agentic_rag/blob/main/arctic_agentic_rag/utils.py"
    click D1 "https://github.com/snowflake-labs/arctic_agentic_rag/tree/main/examples/ambiguity_detection"
    click D2 "https://github.com/snowflake-labs/arctic_agentic_rag/tree/main/examples/simple_RAG"
    click D3 "https://github.com/snowflake-labs/arctic_agentic_rag/tree/main/examples/simple_template_agent"
    click D4 "https://github.com/snowflake-labs/arctic_agentic_rag/tree/main/projects/ambiguous_qa"

    %% Style Definitions
    classDef core fill:#f39c12,stroke:#e67e22,stroke-width:2px;
    classDef module fill:#3498db,stroke:#2980b9,stroke-width:2px;
    classDef integration fill:#9b59b6,stroke:#8e44ad,stroke-width:2px;
    classDef retrieval fill:#1abc9c,stroke:#16a085,stroke-width:2px;
    classDef ranking fill:#e74c3c,stroke:#c0392b,stroke-width:2px;
    classDef template fill:#f1c40f,stroke:#f39c12,stroke-width:2px;
    classDef utility fill:#95a5a6,stroke:#7f8c8d,stroke-width:2px;
    classDef config fill:#2ecc71,stroke:#27ae60,stroke-width:2px;

    class A core;
    class A1,A2,A3,A4,A5,A6 module;
    class L1,L2,L3,L4,L5 integration;
    class R1,R2,R3 retrieval;
    class K1,K2 ranking;
    class T1,T2 template;
    class U1,U2 utility;
    class D1,D2,D3,D4 config;
```
