# haasonsaas/dspy-advanced-prompting architecture

> Architecture diagram of the GitHub repository haasonsaas/dspy-advanced-prompting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haasonsaas/dspy-advanced-prompting
- Repository: https://github.com/haasonsaas/dspy-advanced-prompting

## Overview

##### Project Type and Purpose
- This is an open-source Python library/tool (not a full-stack web app).
- Purpose: Provide reusable modules (“techniques” and “prompts”) built on DSpy and LLMs (e.g., OpenAI), plus an evaluation framework, example scripts, and notebooks.

##### File Structure
- Top-level directories and files:
- src/ – core Python package
– prompts/ – Manager-style, role prompting, etc.
– techniques/ – escape hatches, few-shot, meta-prompting, etc.
– evaluations/ – evaluation_framework.py
- examples/ – quick_start scripts
- notebooks/ – interactive tutorials
- validate_with_dspy.py, validate_with_real_api.py – validation entry points
- main.py – interactive demo
- setup.py, requirements.txt – packaging & dependencies
- Key config: .env for API keys; .env.example as template.

##### README Insights
- Underlying runtime: Python + DSpy framework + OpenAI API (config via dspy.settings).
- Architectural patterns:
- Modular design (each technique is a standalone DSpy module)
- Pluggable evaluation framework (TestCase, EvaluationSuite)
- Pipelines (e.g., model_distillation pipeline)
- No web/UI layer – everything is library + CLI + notebooks.

##### Main Components and Relationships
a. User/Developer
– Runs CLI scripts (validate, main.py, examples)
– Writes custom configs (e.g., ManagerStylePromptConfig)
– Executes notebooks
b. Core Library (src/)
– Prompts Module
– Techniques Module
– Evaluations Module
– Model Distillation Pipeline
c. External Services
– DSpy Framework (imported library dependency)
– LLM API (OpenAI, configured via .env)
d. Examples & Tutorials
– Quick-start scripts (examples/quick_start.py)
– Jupyter notebooks
e. Packaging & Deployment
– setup.py for pip install
– requirements.txt for dependencies

Interactions:
- Developer → runs validate_with_dspy.py → invokes src.evaluations → tests modules without API
- Developer → runs validate_with_real_api.py → src invokes DSpy → OpenAI API
- main.py/examples → import from src.prompts and src.techniques → DSpy.LM call → OpenAI
- Notebooks → import src modules interactively

##### Architectural Patterns & Design Principles
- Modularity: each prompting technique is a discrete module
- Pluggability: new techniques can be added by dropping in another .py under src/techniques
- Pipeline abstraction: evaluation and distillation pipelines formalize multi-step workflows
- Dependency Injection: DSpy.settings.configure allows swapping LMs
- Separation of concerns: prompts vs. techniques vs. evaluations

##### Technologies & Frameworks to Call Out
- Python 3.x
- DSpy (core prompting framework)
- OpenAI API (LLM provider)
- Jupyter Notebooks (interactive tutorials)
- pytest (implied by test_notebooks.py)
- Packaging: setuptools via setup.py

##### Elements
- src.prompts
- src.techniques
- src.evaluations
- DSpy Framework
- OpenAI API
- Examples & Notebooks
- CLI scripts (main.py, validate scripts)
- Developer triggers CLI → loads modules → calls DSpy → hits OpenAI → returns results → evaluation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Entry Points
    subgraph "User Entry Points"
        Dev["Developer"]:::entry
        VDS["validate_with_dspy.py"]:::script
        VRAPI["validate_with_real_api.py"]:::script
        Main["main.py"]:::script
        ExamplesScript["quick_start.py"]:::script
        Notebooks["Jupyter Notebooks"]:::script
    end

    %% Core Library
    subgraph "Core Library (src)"
        subgraph "Prompts Module"
            Prompts["src.prompts"]:::module
            Manager["ManagerStylePrompt"]:::module
        end
        subgraph "Techniques Module"
            Techniques["src.techniques"]:::module
            Escape["Escape Hatches"]:::module
            Few["Few-Shot"]:::module
            Meta["Meta-Prompting"]:::module
            Distill["Model Distillation"]:::module
            Folding["Prompt Folding"]:::module
            Role["Role Prompting"]:::module
            Structured["Structured Output"]:::module
            TaskPlan["Task Planning"]:::module
            Thinking["Thinking Traces"]:::module
        end
        subgraph "Evaluations Module"
            EvalMod["src.evaluations"]:::module
            EvalFrame["Evaluation Framework"]:::module
        end
    end

    %% External Services
    subgraph "External Services"
        DSpy["DSpy Framework"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% Relationships
    Dev --> VDS
    Dev --> VRAPI
    Dev --> Main
    Dev --> ExamplesScript
    Dev --> Notebooks

    VDS --> EvalFrame
    EvalFrame --> EvalMod

    VRAPI --> DSpy

    Main --> Prompts
    Main --> Techniques
    ExamplesScript --> Prompts
    ExamplesScript --> Techniques
    Notebooks --> Prompts
    Notebooks --> Techniques
    Notebooks --> EvalFrame

    Prompts --> DSpy
    Techniques --> DSpy
    DSpy --> OpenAI

    %% Click Events
    click Prompts "https://github.com/haasonsaas/dspy-advanced-prompting/tree/main/src/prompts/"
    click Manager "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/prompts/manager_style.py"
    click Techniques "https://github.com/haasonsaas/dspy-advanced-prompting/tree/main/src/techniques/"
    click Escape "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/escape_hatches.py"
    click Few "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/few_shot.py"
    click Meta "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/meta_prompting.py"
    click Distill "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/model_distillation.py"
    click Folding "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/prompt_folding.py"
    click Role "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/role_prompting.py"
    click Structured "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/structured_output.py"
    click TaskPlan "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/task_planning.py"
    click Thinking "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/techniques/thinking_traces.py"
    click EvalMod "https://github.com/haasonsaas/dspy-advanced-prompting/tree/main/src/evaluations/"
    click EvalFrame "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/src/evaluations/evaluation_framework.py"
    click ExamplesScript "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/examples/quick_start.py"
    click Notebooks "https://github.com/haasonsaas/dspy-advanced-prompting/tree/main/notebooks/"
    click VDS "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/validate_with_dspy.py"
    click VRAPI "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/validate_with_real_api.py"
    click Main "https://github.com/haasonsaas/dspy-advanced-prompting/blob/main/main.py"

    %% Styles
    classDef entry fill:#E3F2FD,stroke:#42A5F5
    classDef script fill:#FFF3E0,stroke:#FB8C00
    classDef module fill:#E8F5E9,stroke:#43A047
    classDef external fill:#FFEBEE,stroke:#E53935
```
