# py-why/pywhy-llm architecture

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

- Interactive diagram: https://gitdiagram.com/py-why/pywhy-llm
- Repository: https://github.com/py-why/pywhy-llm

## Overview

##### Project Type and Purpose
- PyWhy-LLM is an open-source Python library (no frontend) that augments causal analysis by driving Large Language Models (LLMs).
- Key functionality lives in three “Suggester” components (Model, Identification, Validation), which implement causal‐analysis operations by issuing prompts to an external LLM API.

##### Main Components
a. Client API Layer
- ModelSuggester, IdentificationSuggester, ValidationSuggester
- RelationshipStrategy enum
b. Core Protocol Interfaces
- protocols/estimator.py, identifier.py, modeler.py, validator.py
- Methods the Suggester implementations must expose
c. Prompt & Helper Modules
- prompts.py – prompt templates for each operation
- helpers.py – utility functions for building requests, parsing responses
d. Suggester Implementations
- suggesters/*.py – concrete classes implementing each protocol
e. External LLM Service
- OpenAI/GPT-4 or compatible LLM endpoint (not part of repo)
f. Documentation & Notebooks
- docs/ (Sphinx source, notebooks, Makefiles)
g. Testing
- tests/ – unit tests for each suggester via data providers
h. CI/CD
- .github/workflows/python-package.yml – linting, testing, packaging
i. Packaging
- pyproject.toml – project metadata, dependencies

##### Component Relationships & Data Flows
1. User Code → imports a Suggester class
2. Suggester → calls Helper to build a prompt
3. Helper → invokes LLM Adapter (HTTP client) → External LLM API
4. LLM API → returns response → Helper parses into Python objects
5. Suggester → returns suggestions to User
6. Tests → instantiate Suggesters with test LLM stubs → validate outputs
7. Docs builder (Sphinx) → reads source + notebooks → publishes HTML

##### Architectural Patterns & Principles
- Interface Segregation: clear protocols define boundaries between modules
- Layering: Presentation (API) → Business Logic (Suggesters, Protocols) → Infrastructure (Helper, LLM Adapter) → External Service
- Modularity: each “suggester” is interchangeable; new ones can be dropped in

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    UserApp["User Application"]:::internal

    %% Suggester Layer
    subgraph "pywhyllm.suggesters"
        direction TB
        ModelSuggester["ModelSuggester"]:::internal
        IdentificationSuggester["IdentificationSuggester"]:::internal
        ValidationSuggester["ValidationSuggester"]:::internal
        SimpleIdentification["SimpleIdentificationSuggester"]:::internal
        SimpleModel["SimpleModelSuggester"]:::internal
        TuebingenModel["TuebingenModelSuggester"]:::internal
    end

    %% Protocols Layer
    subgraph "pywhyllm.protocols"
        direction TB
        EstimatorProtocol["Estimator Protocol"]:::internal
        IdentifierProtocol["Identifier Protocol"]:::internal
        ModelerProtocol["Modeler Protocol"]:::internal
        ValidatorProtocol["Validator Protocol"]:::internal
    end

    %% Helpers and Prompts
    Prompts["prompts.py"]:::internal
    Helpers["helpers.py"]:::internal

    %% External Service
    ExternalLLM["External LLM API"]:::external

    %% Artifacts
    docs["docs/"]:::artifact
    tests["tests/"]:::artifact

    %% CI/CD and Packaging
    CICD["CI/CD Pipeline"]:::cicd
    Packaging["pyproject.toml"]:::internal

    %% Data Flows
    UserApp -->|"import Suggester"| ModelSuggester
    UserApp -->|"import Suggester"| IdentificationSuggester
    UserApp -->|"import Suggester"| ValidationSuggester

    ModelSuggester -->|"implements"| EstimatorProtocol
    IdentificationSuggester -->|"implements"| IdentifierProtocol
    ValidationSuggester -->|"implements"| ValidatorProtocol

    ModelSuggester -->|"uses prompts"| Prompts
    IdentificationSuggester -->|"uses prompts"| Prompts
    ValidationSuggester -->|"uses prompts"| Prompts

    Prompts -->|"build prompt"| Helpers
    Helpers -->|"HTTP request"| ExternalLLM
    ExternalLLM -->|"response"| Helpers
    Helpers -->|"parse response"| ModelSuggester
    Helpers -->|"parse response"| IdentificationSuggester
    Helpers -->|"parse response"| ValidationSuggester
    ModelSuggester -->|"return suggestions"| UserApp
    IdentificationSuggester -->|"return suggestions"| UserApp
    ValidationSuggester -->|"return suggestions"| UserApp

    %% Testing & Docs & CI/CD
    subgraph "Development Workflow"
        direction TB
        Source["Codebase"]:::internal
        Source -->|"unit test run"| tests
        Source -->|"doc build"| docs
        Source -->|"CI/CD trigger"| CICD
        CICD -->|"publish package"| Packaging
    end

    %% Click Events
    click ModelSuggester "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/suggesters/model_suggester.py"
    click IdentificationSuggester "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/suggesters/identification_suggester.py"
    click ValidationSuggester "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/suggesters/validation_suggester.py"
    click EstimatorProtocol "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/protocols/estimator.py"
    click IdentifierProtocol "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/protocols/identifier.py"
    click ModelerProtocol "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/protocols/modeler.py"
    click ValidatorProtocol "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/protocols/validator.py"
    click Prompts "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/prompts.py"
    click Helpers "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/helpers.py"
    click SimpleIdentification "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/suggesters/simple_identification_suggester.py"
    click SimpleModel "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/suggesters/simple_model_suggester.py"
    click TuebingenModel "https://github.com/py-why/pywhy-llm/blob/main/pywhyllm/suggesters/tuebingen_model_suggester.py"
    click docs "https://github.com/py-why/pywhy-llm/tree/main/docs/"
    click tests "https://github.com/py-why/pywhy-llm/tree/main/tests/"
    click CICD "https://github.com/py-why/pywhy-llm/blob/main/.github/workflows/python-package.yml"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef artifact fill:#90EE90,stroke:#000,stroke-width:1px,shape:cylinder
    classDef cicd fill:#D3D3D3,stroke:#000,stroke-width:1px
```
