# bespokelabsai/curator architecture

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

- Interactive diagram: https://gitdiagram.com/bespokelabsai/curator
- Repository: https://github.com/bespokelabsai/curator

## Overview

##### Main Components
- User/Application Interface:
– This is where users (or developers) interact with the library via the exposed APIs (such as the curator.LLM class), CLI commands, or even through example scripts.
- LLM Integration Module:
– Represented by components in src/bespokelabs/curator/llm and related prompt formatter and response parser logic.
– Shows the flow of prompts to external LLM services.
- Request Processing:
– Located in src/bespokelabs/curator/request_processor. This module handles both online and offline (batch) request processing, with sub-components for different providers (Anthropic, OpenAI, LiteLLM, etc.).
– Include the configuration elements (like rate limits and the _default_rate_limits.json file) and factory pattern logic.
- Code Execution Engine:
– Found under src/bespokelabs/curator/code_executor. This component abstracts code execution into several pluggable backends (multiprocessing, Docker, Ray, and e2b).
- Blocks and Specialized Data Generation:
– Represent the “blocks” (e.g., RAFT in src/bespokelabs/curator/blocks), which encapsulate domain-specific operations like fine-tuning or retrieval augmented fine-tuning (RAFT).
- Status Tracking and Caching:
– Modules such as src/bespokelabs/curator/status_tracker and database modules (db.py & code_executor/db.py) are critical for tracking ongoing processes and caching responses (including retry logic).
- Viewer/Telemetry:
– Illustrate the Curator Viewer (supported by the server.js file under viewer) that streams data and supports real-time monitoring.
– Additionally, show the telemetry client (under telemetry) that sends anonymized usage metrics.

##### Relationships and Data Flows
– Show how the Request Processor dispatches requests to external APIs (e.g., OpenAI, Anthropic, Gemini) via connectors.
– Make sure to show the integration between the core engine and the Viewer, where data (or logs) are sent for real-time visualization.
– Also capture secondary flows such as caching and status tracking that monitor request lifecycles and outcomes.

##### Architectural Patterns & Design Principles
– Modular Design: Each main functionality (LLM calls, request processing, code execution) exists as separate modules/packages.
– Pluggable Backends: Use of factory patterns and strategy patterns especially in the code_executor package, allowing different backend implementations.
– Asynchronous and Batch Processing: Stress how the system supports large-scale synthetic data generation with batch mode support.
– Extensibility: The project has clearly defined integration points for adding new LLM providers, new code backends, and even custom prompts/data parsers.

##### Incorporate External Dependencies and Technologies
– Label external APIs/integrations for OpenAI, Anthropic, Gemini, kluster.ai, and potentially vLLM.
– Emphasize any supporting tools or libraries (for example, use of pydantic for structured outputs, HuggingFace’s Dataset API for data manipulation, and the CLI for viewer interactions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User/Application Interface"
        A1("API Client/CLI"):::ui
        A2("LLM Interface"):::ui
    end

    subgraph "LLM Integration Module"
        B1("LLM Services"):::integration
        B2("Prompt Formatter"):::integration
    end

    subgraph "Request Processing"
        C1("Core Request Processor"):::processor
        C2("Rate Limits"):::processor
        C3("Factory"):::processor
        C4("Online Processing"):::processor
        C5("Offline Processing"):::processor
    end

    subgraph "Code Execution Engine"
        D1("Main Executor"):::executor
        D2("Pluggable Backends"):::executor
        D3("Code Formatter"):::executor
    end

    subgraph "Blocks and Specialized Data Generation"
        E1("RAFT Block"):::blocks
    end

    subgraph "Status Tracking and Caching"
        F1("Status Tracker"):::tracking
        F2("Caching DB (curator)"):::tracking
        F3("Caching DB (executor)"):::tracking
    end

    subgraph "Viewer/Telemetry"
        G1("Interactive Viewer"):::viewer
        G2("Telemetry Client"):::viewer
    end

    X("External LLM APIs"):::external

    %% Data Flow Connections
    A1 -->|"trigger"| B1
    A2 -->|"trigger"| B1
    B2 -->|"format_prompt"| B1
    B1 -->|"dispatch"| C1
    B1 -->|"generate-code"| D1
    D1 -->|"code-result"| C1
    C1 -->|"call-api"| X
    X -->|"response"| C1
    C1 -->|"block-process"| E1
    C1 -->|"status-update"| F1
    C1 -->|"cache-update"| F2
    C1 -->|"cache-update"| F3
    C1 -->|"online-task"| C4
    C1 -->|"offline-task"| C5
    C1 -->|"logs"| G1
    G2 -->|"send-metrics"| G1

    %% Click Events
    click A1 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/client.py"
    click A2 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/llm/llm.py"
    click B2 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/llm/prompt_formatter.py"
    click C1 "https://github.com/bespokelabsai/curator/tree/main/src/bespokelabs/curator/request_processor/"
    click C2 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/request_processor/_default_rate_limits.json"
    click C3 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/request_processor/_factory.py"
    click C4 "https://github.com/bespokelabsai/curator/tree/main/src/bespokelabs/curator/request_processor/online/"
    click C5 "https://github.com/bespokelabsai/curator/tree/main/src/bespokelabs/curator/request_processor/offline/"
    click D1 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/code_executor/code_executor.py"
    click D2 "https://github.com/bespokelabsai/curator/tree/main/src/bespokelabs/curator/code_executor/code_execution_backend/"
    click D3 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/code_executor/code_formatter.py"
    click E1 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/blocks/raft.py"
    click F1 "https://github.com/bespokelabsai/curator/tree/main/src/bespokelabs/curator/status_tracker/"
    click F2 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/db.py"
    click F3 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/code_executor/db.py"
    click G1 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/viewer/server.js"
    click G1 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/viewer/__main__.py"
    click G2 "https://github.com/bespokelabsai/curator/blob/main/src/bespokelabs/curator/telemetry/client.py"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#5DADE2,stroke-width:2px;
    classDef integration fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef processor fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef executor fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef blocks fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef tracking fill:#FDEDEC,stroke:#E74C3C,stroke-width:2px;
    classDef viewer fill:#F0B27A,stroke:#E67E22,stroke-width:2px;
    classDef external fill:#FFFFFF,stroke:#000000,stroke-dasharray: 5 5,stroke-width:2px;
```
