# deepsense-ai/ragbits architecture

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

- Interactive diagram: https://gitdiagram.com/deepsense-ai/ragbits
- Repository: https://github.com/deepsense-ai/ragbits

## Overview

##### Project type and purpose
- This is a monorepo for “Ragbits,” an open-source, modular Python toolkit plus accompanying UI and CLI for building GenAI (RAG/chat) applications.
- It provides core building blocks (LLMs, embeddings, prompts, vector stores), higher-level modules (agents, document search, evaluation, guardrails), a CLI (`ragbits`), and a React-based Chat UI.

##### File structure
- Top‐level directories and files:
- `packages/…` – each subfolder (ragbits-core, ragbits-chat, ragbits-document-search, ragbits-evaluate, ragbits-agents, ragbits-guardrails, ragbits-cli) is a standalone Python package exposing one or more entrypoints (APIs/CLI commands).
- `ui/` – front-end application (TypeScript/React/Vite).
- `scripts/` – monorepo helper scripts (release, package generation).
- `.github/` – CI/CD: workflows for tests, docs, PyPI.
- `pyproject.toml`, `mkdocs.yml` – root build/configuration.
- Each Python package under `packages/` follows:
- `src/ragbits/<component>` – module code (interfaces, sub‐packages)
- `tests/` – unit/integration tests
- `pyproject.toml` + `README.md` + `CHANGELOG.md`
- The UI folder has its own package.json, Vite config, contexts, components, plugin system.

##### README for additional insights
- Describes:
- Core features: LLM abstraction, vector store adapters, prompts.
- Optional modules: document search (ingest, retrieval), agents, evaluation pipelines, guardrails (moderation).
- A CLI for interactive use and orchestration.
- A Chat UI leveraging the underlying Python API via an HTTP or local host interface.

a. Main components
- Ragbits-Core (LLMs, embeddings, prompts, vector stores)
- Ragbits-Document-Search (ingestion, retrieval pipelines)
- Ragbits-Agents (agent orchestration layer)
- Ragbits-Evaluate (evaluation pipelines: dataloaders, metrics, optimizer)
- Ragbits-Guardrails (safety/moderation wrappers)
- Ragbits-Chat (API server, chat interface, persistence, UI assets)
- Ragbits-CLI (shell tool integrating all modules)
- Frontend UI (React app served by Ragbits-Chat)
- External services:
– LLM providers (OpenAI, local, LiteLLM)
– Vector stores (Qdrant, PgVector, In-Memory)
– Data sources (S3, GCS, Azure, Git, Web)
– Observability (OpenTelemetry, Grafana)
b. Relationships & interactions
- UI ↔ Ragbits-Chat API: HTTP/WebSocket for chat sessions.
- CLI ↔ Underlying Python modules via command‐line commands.
- Ragbits-Chat ↔ Ragbits-Core (calls LLM, embeddings).
- Document-Search ↔ Core embedding + vector store adapters.
- Agents layer orchestrates prompt → LLM → action → memory storage.
- Evaluate pipelines orchestrate Document-Search or Chat flows for metrics collection.
- Guardrails wrap calls to LLM to enforce safety policies.
- All modules may read/write from persistence (SQL, file) managed by Ragbits-Chat or provided by user.
- Observability hooks (traces, metrics) plugged into core and CLI.
c. Architectural patterns & design principles
- Modular, plugin-based architecture – each component is installable independently, discoverable via entry points.
- Adapter pattern – for LLMs, embeddings, vector stores, parsers, enrichers.
- Pipeline chaining – ingestion strategies, retrieval re-rankers, evaluation pipelines.
- Observer pattern – telemetry integration, event hooks.
- Separation of concerns – core vs. higher-level modules vs. UI/CLI.
d. Key technologies
- Python + Pydantic for API models
- AsyncIO for concurrency in ingestion, LLM calls
- Entry points for CLI and modular plugin discovery
- React, Vite, TypeScript for chat UI
- OpenTelemetry for tracing
- Ray for distributed ingestion (optional)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        WebUI["Web UI (React App)"]:::ui
        App["App.tsx"]:::ui
        Main["main.tsx"]:::ui
        Components["Components"]:::ui
        Plugins["Plugins & Utils"]:::ui
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        ChatAPI["Ragbits-Chat API Server"]:::orchestration
        ChatCLI["Ragbits-CLI"]:::orchestration
        Persistence["Chat Persistence"]:::orchestration
        UIAssets["Chat UI Assets"]:::orchestration
    end

    %% Library Layer
    subgraph "Library Layer"
        direction TB
        Core["ragbits-core"]:::library
        DocSearch["ragbits-document-search"]:::library
        Agents["ragbits-agents"]:::library
        Evaluate["ragbits-evaluate"]:::library
        Guardrails["ragbits-guardrails"]:::library
    end

    %% External Systems
    subgraph "External Services"
        direction TB
        LLM["LLM Providers"]:::external
        VectorStore["Vector Stores"]:::external
        DataSources["Data Sources"]:::external
        Observability["Observability"]:::external
    end

    %% Relationships
    WebUI -->|"HTTP/WebSocket"| ChatAPI
    App --> WebUI
    Main --> WebUI
    Components --> WebUI
    Plugins --> WebUI

    ChatAPI -->|depends on| Core
    ChatAPI -->|calls embeddings| DocSearch
    ChatAPI -->|uses| Persistence
    ChatAPI -->|serves assets| UIAssets

    ChatCLI -->|invokes modules| Core
    ChatCLI -->|invokes modules| DocSearch
    ChatCLI -->|invokes modules| Agents
    ChatCLI -->|invokes modules| Evaluate
    ChatCLI -->|invokes modules| Guardrails

    Core -->|adapter| LLM
    Core -->|adapter| VectorStore

    DocSearch -->|uses embedder| Core
    DocSearch -->|stores vectors| VectorStore

    Agents -->|orchestrates| Core
    Agents -->|uses| DocSearch

    Evaluate -->|runs pipelines| DocSearch
    Evaluate -->|runs pipelines| ChatAPI

    Guardrails -->|wraps| Core

    Core -->|emits telemetry| Observability
    ChatCLI -->|emits telemetry| Observability

    DataSources -->|ingest| DocSearch

    %% Click Events
    click Core "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-core/src/ragbits/core"
    click DocSearch "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-document-search/src/ragbits/document_search"
    click Agents "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-agents/src/ragbits/agents"
    click Evaluate "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-evaluate/src/ragbits/evaluate"
    click Guardrails "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-guardrails/src/ragbits/guardrails"
    click ChatAPI "https://github.com/deepsense-ai/ragbits/blob/main/packages/ragbits-chat/src/ragbits/chat/api.py"
    click Persistence "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-chat/src/ragbits/chat/persistence"
    click UIAssets "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-chat/src/ragbits/chat/ui-build/assets"
    click ChatCLI "https://github.com/deepsense-ai/ragbits/tree/main/packages/ragbits-cli/src/ragbits/cli"
    click WebUI "https://github.com/deepsense-ai/ragbits/tree/main/ui/"
    click App "https://github.com/deepsense-ai/ragbits/blob/main/ui/src/App.tsx"
    click Main "https://github.com/deepsense-ai/ragbits/blob/main/ui/src/main.tsx"
    click Components "https://github.com/deepsense-ai/ragbits/tree/main/ui/src/core/components"
    click Plugins "https://github.com/deepsense-ai/ragbits/tree/main/ui/src/core/utils/plugins"

    %% Styles
    classDef library fill:#e0f7fa,stroke:#006064
    classDef orchestration fill:#fff3e0,stroke:#e65100
    classDef ui fill:#f3e5f5,stroke:#4a148c
    classDef external fill:#f1f8e9,stroke:#33691e
```
