# scale3-labs/dspy-examples architecture

> Architecture diagram of the GitHub repository scale3-labs/dspy-examples, 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/scale3-labs/dspy-examples
- Repository: https://github.com/scale3-labs/dspy-examples

## Overview

##### Project Type and Purpose
- This is an **open-source collection of AI program examples** built on the DSPy framework.
- Its purpose is to demonstrate how to assemble, configure, and run various DSPy “programs” (pipelines of LLM-driven steps) with minimal boilerplate.

##### File Structure
- Top level:
- README.md, LICENSE, requirements.txt
- `src/` – contains one subdirectory per example
- Under `src/`:
- `receipt_processing/`, `self_optimizing_chat/`, `simple_miprov2/`, `structured_output/`, `summarization/`, `vision_lm/`
- Within each example directory:
- One or more `programs/` or standalone files (`main.py`, `program.py`)
- Typical program subfolder includes: `dataset(.jsonl)`, `program.py`, `signatures.py`, `run.py`.

##### Extract Insights from the README
- Confirms each “program” is an independent DSPy pipeline with:
– **`dataset`**: input data
– **`program.py`**: pipeline steps
– **`signatures.py`**: interface definitions
– **`run.py`**: CLI entrypoint
- Notes that “compound systems” may chain multiple DSPy programs together.

##### Main Components
a. **Core DSPy Runtime**
- The library providing orchestration, signature enforcement, and LLM integration.
b. **Example Modules** (six main examples)
- receipt_processing
- self_optimizing_chat
- simple_miprov2
- structured_output
- summarization
- vision_lm
c. **Within Each Example**
- **Dataset Store** (JSONL or other)
- **Signatures** layer (API contracts for LLM calls)
- **Program Logic** (`program.py`)
- **Entry Script** (`run.py` or `main.py`)
d. **External Services**
- LLM provider (e.g., OpenAI API)
- Any other external data sources (e.g., image storage for vision_lm)

##### Relationships and Data Flow
- **run.py** → boots DSPy runtime → loads **dataset** → invokes **program.py**
- **program.py** steps call the LLM via **signatures.py** contracts
- Output from one program may feed into another for “compound systems”
- Results are returned or written back to disk

##### Architectural Patterns
- **Plugin/Modular**: each example is a plugin to the DSPy core
- **Pipeline**: stepwise transformations, each step defined in code + signature
- **Monorepo**: shared dependencies (requirements.txt) and conventions

##### Detail Is Key
- If an example is “compound,” show its internal chaining of DSPy programs.
- Call out shared elements: `requirements.txt`, `LICENSE`, and the fact that all examples depend on the same DSPy core.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services
    LLM["LLM Provider API"]:::external
    IMG["Image Storage Service"]:::external

    %% Core DSPy Runtime
    DSPyCore["DSPy Core Runtime"]:::core

    %% Shared Repo Files
    README["README.md"]:::core
    REQS["requirements.txt"]:::core
    LICENSE["LICENSE"]:::core

    %% Connections from externals to core
    LLM -->|"API calls"| DSPyCore
    IMG -->|"Image fetch"| DSPyCore

    %% Shared files to core
    README --> DSPyCore
    REQS --> DSPyCore
    LICENSE --> DSPyCore

    %% Example Modules
    subgraph "receipt_processing" 
        direction TB
        RP_Data[(Dataset Store)]:::datastore
        RP_Sign["Signatures Layer"]:::example
        RP_Logic["Program Logic"]:::example
        RP_Run["Entry Script"]:::example
        RP_Run --> DSPyCore
        DSPyCore --> RP_Data
        RP_Data --> RP_Logic
        RP_Logic --> RP_Sign
        RP_Logic -->|calls| LLM
    end

    subgraph "self_optimizing_chat" 
        direction TB
        SOC_Data[(Dataset Store)]:::datastore
        SOC_Logic["Program Logic"]:::example
        SOC_Run["Entry Script"]:::example
        SOC_Run --> DSPyCore
        DSPyCore --> SOC_Data
        SOC_Data --> SOC_Logic
        SOC_Logic -->|calls| LLM
    end

    subgraph "simple_miprov2"
        direction TB
        SM_Run["Runner"]:::example
        subgraph "Step1_Bootstrap_Few_Shot"
            direction TB
            SM1_Sign["Signatures"]:::example
            SM1_Logic["Program Logic"]:::example
        end
        subgraph "Step2_Bootstrap_Instruction"
            direction TB
            SM2_Sign["Signatures"]:::example
            SM2_Logic["Program Logic"]:::example
        end
        subgraph "Step3_Generate_Final_Prompt"
            direction TB
            SM3_Sign["Signatures"]:::example
            SM3_Logic["Program Logic"]:::example
        end
        SM_Run --> DSPyCore
        DSPyCore --> SM1_Logic
        SM1_Logic --> SM1_Sign
        SM1_Logic -->|calls| LLM
        DSPyCore --> SM2_Logic
        SM2_Logic --> SM2_Sign
        SM2_Logic -->|calls| LLM
        DSPyCore --> SM3_Logic
        SM3_Logic --> SM3_Sign
        SM3_Logic -->|calls| LLM
    end

    subgraph "structured_output"
        direction TB
        SO_Logic["Program Logic"]:::example
        SO_Sign["LLM-config/Signatures"]:::example
        SO_Run["Entry Script"]:::example
        SO_Run --> DSPyCore
        DSPyCore --> SO_Logic
        SO_Logic --> SO_Sign
        SO_Logic -->|calls| LLM
    end

    subgraph "summarization"
        direction TB
        subgraph "Metric_Program"
            direction TB
            SUM1_Data[(Dataset Store)]:::datastore
            SUM1_Sign["Signatures"]:::example
            SUM1_Logic["Program Logic"]:::example
            SUM1_Run["Runner"]:::example
        end
        subgraph "Summarize_Program"
            direction TB
            SUM2_Data[(Dataset Store)]:::datastore
            SUM2_Sign["Signatures"]:::example
            SUM2_Logic["Program Logic"]:::example
            SUM2_Run["Runner"]:::example
        end
        SUM1_Run --> DSPyCore
        DSPyCore --> SUM1_Data
        SUM1_Data --> SUM1_Logic
        SUM1_Logic --> SUM1_Sign
        SUM1_Logic -->|calls| LLM

        SUM2_Run --> DSPyCore
        DSPyCore --> SUM2_Data
        SUM2_Data --> SUM2_Logic
        SUM2_Logic --> SUM2_Sign
        SUM2_Logic -->|calls| LLM
    end

    subgraph "vision_lm"
        direction TB
        VL_Data[(Dataset Store)]:::datastore
        VL_Sign["Signatures Layer"]:::example
        VL_Logic["Program Logic"]:::example
        VL_Run["Entry Script"]:::example
        VL_Run --> DSPyCore
        DSPyCore --> VL_Data
        VL_Data --> VL_Logic
        VL_Logic --> VL_Sign
        VL_Logic -->|calls| LLM
        VL_Logic -->|fetch image| IMG
    end

    %% Click Events
    click RP_Data "https://github.com/scale3-labs/dspy-examples/tree/main/src/receipt_processing/data"
    click RP_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/receipt_processing/signature.py"
    click RP_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/receipt_processing/program.py"
    click RP_Run "https://github.com/scale3-labs/dspy-examples/blob/main/src/receipt_processing/main.py"
    click SOC_Data "https://github.com/scale3-labs/dspy-examples/blob/main/src/self_optimizing_chat/programs/rule_following_chat/rules.jsonl"
    click SOC_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/self_optimizing_chat/programs/rule_following_chat/program.py"
    click SM_Run "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/run.py"
    click SM1_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/step1_bootstrap_few_shot/program.py"
    click SM1_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/step1_bootstrap_few_shot/signatures.py"
    click SM2_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/step2_bootstrap_instruction/program.py"
    click SM2_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/step2_bootstrap_instruction/signatures.py"
    click SM3_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/step3_generate_final_prompt/program.py"
    click SM3_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/simple_miprov2/programs/step3_generate_final_prompt/signatures.py"
    click SO_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/structured_output/program.py"
    click SO_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/structured_output/outlines_lm.py"
    click SUM1_Data "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/metric/dataset.jsonl"
    click SUM1_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/metric/program.py"
    click SUM1_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/metric/signatures.py"
    click SUM1_Run "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/metric/run.py"
    click SUM2_Data "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/summarize/dataset.jsonl"
    click SUM2_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/summarize/program.py"
    click SUM2_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/summarize/signatures.py"
    click SUM2_Run "https://github.com/scale3-labs/dspy-examples/blob/main/src/summarization/programs/summarize/run.py"
    click VL_Data "https://github.com/scale3-labs/dspy-examples/tree/main/src/vision_lm/data"
    click VL_Sign "https://github.com/scale3-labs/dspy-examples/blob/main/src/vision_lm/signature.py"
    click VL_Logic "https://github.com/scale3-labs/dspy-examples/blob/main/src/vision_lm/program.py"
    click VL_Run "https://github.com/scale3-labs/dspy-examples/blob/main/src/vision_lm/main.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef example fill:#d4edda,stroke:#155724,color:#155724;
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
