# camel-ai/loong architecture

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

- Interactive diagram: https://gitdiagram.com/camel-ai/loong
- Repository: https://github.com/camel-ai/loong

## Overview

##### Project Type and Purpose
- This is a research and open-source project focused on using small, high-quality seed datasets to facilitate self-improvement in LLM agents. It leverages synthetic data generation and verification to bootstrap training, under the umbrella of a collaborative initiative.
- The project’s key components include seed datasets curated across various domains (math, physics, finance, etc.), cookbooks with reusable scripts and notebooks for synthetic data generation and verification, and an agent-environment loop that incorporates a generator, verifier, and trainable agent.

##### Analyzing the File Structure
- Top-Level Folders:
- “data”: Contains subdirectories for each domain, holding seed datasets (typically JSON files and metadata). This folder represents the core data input into the system.
- “cookbooks”: Includes scripts (e.g., distillation.py and notebooks) that implement synthetic data generation and related processes.
- “scripts”: Contains utility scripts (e.g., for uploading data to Hugging Face and validating seed dataset structure) that are part of the data pipeline and CI/CD.
- “.github”: Holds CI/CD configuration files (workflows) for automating tasks like data validation and uploading, ensuring quality control.
- Additional files like “pyproject.toml”, “LICENSE”, “README.md”, and “uv.lock” support project configuration, licensing, and dependency management.

##### Main Components
a. Seed Datasets – Represented by the “data” folder:
- Individual datasets for domains like Advanced Math, Physics, Finance, etc.
- A combined dataset file (“all_seed_dataset.json”) for aggregated processing.
b. Synthetic Data Generation (Generator) – Represented in the “cookbooks”:
- Scripts and notebooks that use seed datasets to generate synthetic questions, answers, and rationales.
- This component takes input from the seed datasets and applies generation strategies.
c. Verification Process (Verifier) – Also found in “cookbooks” and supported by scripts:
- Verifiers execute rationale code and compare outputs to known answers, validating data accuracy.
- With training pipelines (possibly implemented in cookbooks or later integration) that iteratively learn from the verified synthetic Q&As.
e. CI/CD & Deployment:
- GitHub workflows (under “.github/workflows”) manage continuous integration tasks such as validating seed data structure and uploading data.
- This ensures that every change in the datasets or cookbooks goes through quality checks and automated data deployment (upload to Hugging Face).

##### Relationships and Data Flow
- Once verified, the “Trainable Agent” component leverages the quality-controlled Q&As, incorporating reinforcement learning and iterative improvement.
- Complementing these flows, the CI/CD pipelines ensure automated checks and deployments (e.g., verifying directory structures and uploading datasets).

##### Architectural Patterns and Technologies
- The architecture follows a modular design with separation of concerns – clearly partitioning data ingestion, synthetic generation, and verification or training.
- It is built upon pipelines that are re-usable and extensible, evidenced by the “cookbooks” and “scripts” folders.
- Technologies include Python (for scripts, notebooks, and cookbooks), JSON (for datasets), and GitHub Actions (for CI/CD workflows). Additionally, integration with platforms like Hugging Face is highlighted through upload scripts.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Seed Data Layer
    SD["Seed Data Repository"]:::data
    click SD "https://github.com/camel-ai/loong/tree/main/data/"

    %% Synthetic Data Generation Subgraph
    subgraph "Synthetic Data Generation"
        DS["Distillation Script"]:::generator
        click DS "https://github.com/camel-ai/loong/blob/main/cookbooks/distillation.py"
        GN["Generator Notebook"]:::generator
        click GN "https://github.com/camel-ai/loong/blob/main/cookbooks/env_with_generator.ipynb"
    end

    %% Verification Process Subgraph
    subgraph "Verification Process"
        VP1["Verifier (Execution)"]:::verifier
        click VP1 "https://github.com/camel-ai/loong/blob/main/data/security_and_safety/verify.py"
        VP2["Schema Validator"]:::verifier
        click VP2 "https://github.com/camel-ai/loong/blob/main/scripts/validate_seed_data_strucutre.py"
    end

    %% Trainable Agent
    TA["RL-Trainable Agent"]:::agent
    click TA "https://github.com/camel-ai/loong/blob/main/cookbooks/env_with_generator.ipynb"
    
    %% CI/CD & Deployment Subgraph
    subgraph "CI/CD & Deployment"
        VWF["Validation Workflow"]:::cicd
        click VWF "https://github.com/camel-ai/loong/blob/main/.github/workflows/validate-seed-data-structure.yml"
        UW["Upload Workflow"]:::cicd
        click UW "https://github.com/camel-ai/loong/blob/main/.github/workflows/upload-to-hf.yml"
        HF["Hugging Face Uploader"]:::cicd
        click HF "https://github.com/camel-ai/loong/blob/main/scripts/upload_to_hf.py"
    end

    %% Data Flow Connections
    SD -->|"supplies"| GN
    GN -->|"generates"| VP1
    GN -->|"generates"| VP2
    VP1 -->|"verifies"| TA
    VP2 -->|"validates"| TA
    SD -->|"triggers"| VWF

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef generator fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef verifier fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef agent fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef cicd fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
