# helmanofer/pydantic-prompter architecture

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

- Interactive diagram: https://gitdiagram.com/helmanofer/pydantic-prompter
- Repository: https://github.com/helmanofer/pydantic-prompter

## Overview

##### Project Type & Purpose
- This is an open-source Python library focused on prompt engineering and structured data parsing.
- The README emphasizes seamless integration with multiple LLM providers (e.g., OpenAI, Cohere, Bedrock) and the use of Pydantic to generate structured outputs.

##### Key Components Identified in the File Structure
- Core Library Code (src/pydantic_prompter):
– Main API exposed via the Prompter decorator (found in prompter.py).
– Functions for parsing annotations (annotation_parser.py) and common helper utilities (common.py).
– Settings management (settings.py).
- LLM Providers:
– A dedicated submodule (src/pydantic_prompter/llm_providers) which contains integration modules for different LLM services such as OpenAI, Cohere, and multiple Bedrock variants.
– A base provider (base.py) that defines interfaces and common functionality.
- Prompt Templates:
– Organized under src/pydantic_prompter/prompt_templates, supporting both Jinja2 templating and simple string formatting.
- Testing Infrastructure:
– Found in the tests directory and configuration files (tox.ini, pdm.lock, pyproject.toml) that support automated testing.
- Documentation & Examples:
– The docs and examples directories illustrate usage patterns and provide guidance on prompt creation and LLM integration.
- CI/CD & Maintenance:
– GitHub workflows for testing, publishing to PyPI, and documentation deployment are present, which indicate automated processes to maintain the project.

##### Relationships & Interactions
- The core component (Prompter) intercepts decorated functions. When invoked, it:
- Parses function annotations and prompt strings.
- Selects and processes the appropriate prompt template (using either Jinja2 or basic formatting).
- The processed prompt is then sent to an LLM provider by calling the function in one of the modules from the llm_providers directory. Each provider module implements the specifics of interacting with its respective LLM API.
- The LLM response is captured and parsed into a Pydantic model defined by the user, enabling structured data outputs.
- Logging and exception handling (e.g., exceptions.py) work in tandem to provide debugging and error reporting.

##### Architectural Patterns and Design Principles
- Modularity: Clearly separated layers for prompt construction, LLM provider integration, and output parsing.
- Abstraction via Decorators: The Prompter decorator abstracts the underlying complexity, letting users call LLMs like regular functions.
- Extensibility: Coded for multiple LLM providers and templating strategies, supporting future expansions.
- Separation of Concerns: Each module (template parsing, provider management, configuration) is clearly delineated in its own file/directory.

##### Putting It All Together
- Next, detail how the Prompter decorator processes the call:
– It parses annotations (annotation_parser), composes the prompt using a template (prompt_templates), and then hands the formatted prompt to the LLM provider adapter.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Layer
    subgraph "User Code Layer"
        user("User Code"):::user
    end

    %% Prompter Engine Layer
    subgraph "Prompter Engine"
        pd("Prompter Decorator"):::engine
        pa("Annotation Parser"):::engine
        cu("Common Utilities"):::engine
        sm("Settings Management"):::engine
        pt("Prompt Templates"):::engine
        pp("Pydantic Parsing"):::engine
    end

    %% LLM Provider Adapters Layer
    subgraph "LLM Provider Adapters"
        lpb("LLM Provider Base"):::adapter
        oa("OpenAI Adapter"):::adapter
        ca("Cohere Adapter"):::adapter
        ba("Bedrock Anthropic Adapter"):::adapter
        bb("Bedrock Base Adapter"):::adapter
        bc("Bedrock Cohere Adapter"):::adapter
        bl("Bedrock Llama2 Adapter"):::adapter
    end

    %% External LLM Services
    subgraph "External LLM Services"
        ext1("OpenAI Service"):::external
        ext2("Cohere Service"):::external
        ext3("Bedrock Service"):::external
    end

    %% DevOps, Testing & Documentation
    subgraph "DevOps & Maintenance"
        test("Automated Tests & Config"):::devops
        docs("Documentation & Examples"):::devops
        ci("CI/CD Workflows"):::devops
    end

    %% Data Flow Connections
    user -->|"calls"| pd
    pd -->|"parses"| pa
    pd -->|"formats"| pt
    pd -->|"utilizes"| cu
    pd -->|"loads"| sm
    pd -->|"dispatches"| lpb

    lpb -->|"routes to"| oa
    lpb -->|"routes to"| ca
    lpb -->|"routes to"| ba
    lpb -->|"routes to"| bb
    lpb -->|"routes to"| bc
    lpb -->|"routes to"| bl

    oa -->|"calls"| ext1
    ca -->|"calls"| ext2
    ba -->|"calls"| ext3
    bb -->|"calls"| ext3
    bc -->|"calls"| ext3
    bl -->|"calls"| ext3

    ext1 -->|"responds to"| oa
    ext2 -->|"responds to"| ca
    ext3 -->|"responds to"| ba
    ext3 -->|"responds to"| bb
    ext3 -->|"responds to"| bc
    ext3 -->|"responds to"| bl

    %% Response pathway back into parsing and then to user
    lpb -->|"sends raw output"| pp
    pp -->|"returns structured data"| user

    %% DevOps interactions
    ci -->|"triggers"| test
    ci -->|"updates"| docs

    %% Click Events for Core Library and Adapters
    click pd "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/prompter.py"
    click pa "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/annotation_parser.py"
    click cu "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/common.py"
    click sm "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/settings.py"
    click pt "https://github.com/helmanofer/pydantic-prompter/tree/main/src/pydantic_prompter/prompt_templates"
    click lpb "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/base.py"
    click oa "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/openai.py"
    click ca "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/cohere.py"
    click ba "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/bedrock_anthropic.py"
    click bb "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/bedrock_base.py"
    click bc "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/bedrock_cohere.py"
    click bl "https://github.com/helmanofer/pydantic-prompter/blob/main/src/pydantic_prompter/llm_providers/bedrock_llama2.py"
    click test "https://github.com/helmanofer/pydantic-prompter/tree/main/tests"
    click docs "https://github.com/helmanofer/pydantic-prompter/tree/main/docs"
    click ci "https://github.com/helmanofer/pydantic-prompter/tree/main/.github/workflows"

    %% Styles
    classDef user fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef engine fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef adapter fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef external fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef devops fill:#f5b7b1,stroke:#333,stroke-width:2px;
```
