# dcaples/autodidact architecture

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

- Interactive diagram: https://gitdiagram.com/dcaples/autodidact
- Repository: https://github.com/dcaples/autodidact

## Overview

##### Project Type and Purpose
- This is a research/experimentation project that trains a self-improving search and QA agent. It autonomously generates question-answer pairs from an input corpus (e.g., the Apollo 13 mission report), creates document embeddings, performs semantic search, and uses reinforcement learning (GRPO) to improve performance.
- Key functionality includes data ingestion, embedding generation, semantic search, agent interaction via RL, and a self-verification feedback loop.

##### Analyzing the File Structure
- Top-level files indicate scripts and notebooks:
- autodidact.ipynb: Serves as the full training pipeline example.
- generate_data.py: Automates the generation of QA pairs and embeddings.
- embeddings.py: Manages embedding creation for queries/documents.
- search_module.py: Implements semantic search over the document corpus.
- rl_helpers.py: Contains reinforcement learning related utilities and feedback logic.
- simple_qa.py: Likely a simplified example of QA functionality.
- UnslothGRPOTrainerTemp.py: Indicates integration with Unsloth’s Efficient GRPO code.
- The data folder holds mission reports (markdown and PDF) that act as the corpus for the QA and search processes.
- The requirements.txt file and .gitignore denote standard project setup details.

a. Main Components to Include:
- Input Data Layer:
- Document Corpus (data folder: mission_report.md, apollo-13-mission-report.pdf)
- Data Generation & Preprocessing:
- Generate Data Pipeline (generate_data.py) – reads documents, extracts content, and creates QA pairs.
- Embedding Generation:
- Embeddings Module (embeddings.py) – processes documents and queries to generate vector representations.
- Semantic Search Component:
- Search Module (search_module.py) – leverages the embeddings to perform similarity searches over the document corpus.
- Reinforcement Learning and Self-Verification:
- RL Helpers (rl_helpers.py) – implements GRPO-based training loops, self-verification and reward mechanisms.
- Integration of Unsloth’s GRPO code (as referenced in UnslothGRPOTrainerTemp.py) – indicates reinforcement learning optimization.
- Execution/Training Pipeline:
- Jupyter Notebook (autodidact.ipynb) – orchestrates overall training, launching sequences for data generation, search operations, and training’s iterative feedback loop.
- Auxiliary/Example Components:
- Simple QA Script (simple_qa.py) – may serve as a minimal example of the question answering functionality.

- The Document Corpus feeds into the Data Generation Pipeline.
- generate_data.py calls the Embeddings Module (embeddings.py) to process the text, then creates QA pairs.
- The generated embeddings and QA pairs are used by the Search Module (search_module.py) which returns relevant document segments based on queries.
- The RL Helpers (rl_helpers.py), in concert with Unsloth’s GRPO trainer in UnslothGRPOTrainerTemp.py, manage the agentic search and self-verification loops – using the outputs from the search module to compare against expected QA outcomes.
- autodidact.ipynb serves as the control interface that strings together these components, coordinating the entire training and evaluation flow.
- Optionally, simple_qa.py can represent a streamlined execution path for demonstration or testing purposes.

##### Architectural Patterns and Design Principles
- Modular design: Each major function (data generation, embedding, search, RL) is encapsulated in its own module.
- Pipeline structure: The sequential flow from data ingestion → processing → search → agent feedback embodies a pipelined architecture.
- Self-improving feedback loop: Reinforcement learning with self-verification ensures that the system is cyclic, where outputs feed back for iterative improvement.
- Integration with external research code: Incorporation of Unsloth's GRPO trainer as a key component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Training Pipeline & Orchestration (autodidact.ipynb)"]:::orchestration

    subgraph "Document Corpus"
        B["Apollo 13 Mission Report (pdf)"]:::dataLayer
        C["Mission Report (md)"]:::dataLayer
    end

    D["Data Generation & Preprocessing (generate_data.py)"]:::processing
    E["Embedding Generation (embeddings.py)"]:::processing
    F["Semantic Search Engine (search_module.py)"]:::search
    subgraph "Reinforcement Learning (GRPO)"
        G["RL Helpers (rl_helpers.py)"]:::rl
        H["GRPO Trainer (UnslothGRPOTrainerTemp.py)"]:::rl
    end
    I["Auxiliary QA Functionality (simple_qa.py)"]:::qa

    A -->|"orchestrates"| D
    B -->|"raw_data"| D
    C -->|"raw_data"| D
    D -->|"calls"| E
    E -->|"provides_embeddings"| F
    F -->|"returns_results"| G
    G -->|"trains"| H
    H -->|"feedback"| F
    A -->|"executes_demo"| I

    classDef orchestration fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
    classDef dataLayer fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef processing fill:#DCEDC8,stroke:#7CB342,stroke-width:2px;
    classDef search fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef rl fill:#FFCDD2,stroke:#E53935,stroke-width:2px;
    classDef qa fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;

    click A "https://github.com/dcaples/autodidact/blob/main/autodidact.ipynb"
    click B "https://github.com/dcaples/autodidact/blob/main/data/apollo-13-mission-report.pdf"
    click C "https://github.com/dcaples/autodidact/blob/main/data/mission_report.md"
    click D "https://github.com/dcaples/autodidact/blob/main/generate_data.py"
    click E "https://github.com/dcaples/autodidact/blob/main/embeddings.py"
    click F "https://github.com/dcaples/autodidact/blob/main/search_module.py"
    click G "https://github.com/dcaples/autodidact/blob/main/rl_helpers.py"
    click H "https://github.com/dcaples/autodidact/blob/main/UnslothGRPOTrainerTemp.py"
    click I "https://github.com/dcaples/autodidact/blob/main/simple_qa.py"
```
