# jackmpcollins/magentic architecture

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

- Interactive diagram: https://gitdiagram.com/jackmpcollins/magentic
- Repository: https://github.com/jackmpcollins/magentic

## Overview

##### Project Type and Purpose
- magentic is an open-source Python library/tool (not a web app) that provides decorators (`@prompt`, `@chatprompt`, `@prompt_chain`, etc.) to let Python code seamlessly orchestrate LLM queries, structured outputs (via Pydantic), streaming, and function calls.
- It targets developers who want to embed LLM-driven logic into their Python applications, supporting multiple LLM backends (OpenAI, Anthropic, LiteLLM, Mistral), observability (OpenTelemetry), retries, and more.

##### High-Level File Structure Analysis
- src/magentic: core library code, subpackages for decorators, parsing, streaming, formatting, function-calling, logging, settings, and the chat_model interface plus plug‐in backends.
- docs + mkdocs.yml: static documentation site assets and content.
- tests: test harness using VCR-style cassettes to mock LLM responses, unit tests for core modules.
- CI/CD configs (.github/workflows): build, test, publish to PyPI, and deploy documentation.

##### Main Components
a. **User Code Layer**
- Python scripts/modules that import and use `@prompt`, `@chatprompt`, `@prompt_chain` decorators.
b. **Magentic Core Library**
- Decorators & runtime:
- `_chat.py`, `_parsing.py`, `_pydantic.py`, `_streamed_response.py`
- `prompt_chain.py`, `chatprompt.py`, `prompt_function.py`, `function_call.py`
- Formatting & utilities: `formatting.py`, `logger.py`, `streaming.py`, `typing.py`
- Configuration & settings: `settings.py`, environment var loader
c. **ChatModel Interface & Backends**
- Base class (`chat_model/base.py`)
- Backend implementations: `openai_chat_model.py`, `anthropic_chat_model.py`, `litellm_chat_model.py`, `mistral_chat_model.py`, plus `retry_chat_model.py` wrapper.
d. **External LLM Providers**
- HTTP APIs: OpenAI, Anthropic, LiteLLM, Mistral endpoints (could be local or cloud)
e. **Function Execution Engine**
- Drives FunctionCall objects: discovers candidate Python functions, invokes them, marshals I/O back into the LLM loop (prompt chains).
f. **Observability & Retry Subsystem**
- OpenTelemetry instrumentation, Pydantic Logfire integration, retry logic for schema adherence.
g. **Documentation Pipeline**
- MkDocs site generator (docs/ + mkdocs.yml)
- GitHub Actions job “deploy_docs.yml” to push to gh-pages.
h. **CI/CD Pipeline**
- GitHub Actions:
- test.yml → runs pytest with recorded cassettes
- publish.yml → builds & publishes PyPI package
- deploy_docs.yml → builds and deploys docs.

##### Relationships and Interactions
- **User Code → Magentic Decorators**: calls to decorated functions hand off to Magentic runtime.
- **Runtime → ChatModel (interface)**: runtime formulates a Chat API request (messages, function schemas, streaming flags).
- **ChatModel Backend → External API**: sends HTTP request, receives streamed or full response.
- **Response → Magentic Parsers**: streams text or objects, including detecting FunctionCall JSON schemas.
- **FunctionCall → Function Execution Engine**: if LLM requests a tool call, Magentic invokes the user’s Python function, then feeds the result back into the prompt chain.
- **Observability**: each step emits OpenTelemetry spans/logs.
- **Configuration**: environment variables or decorator arguments override default ChatModel selection (settings module orchestrates).
- **CI/CD**: GitHub Actions orchestrates testing → publishing → docs deployment.

##### Architectural Patterns & Design Principles
- **Plugin Architecture**: ChatModel backends adhere to a common interface; new backends can be dropped in.
- **Decorator Pattern**: user-facing functions are no-ops rerouted via decorators to Magentic logic.
- **Chain of Responsibility**: prompt chains and function calls form a pipeline until final answer.
- **Dependency Injection**: ChatModel instance can be passed explicitly, via context manager, or via environment configuration.
- **Streaming & Async Patterns**: supports both synchronous and asynchronous generations, streaming outputs, and concurrent async tasks.

##### Technologies, Frameworks, Libraries
- Python 3.x, Pydantic for schema enforcement, OpenTelemetry for tracing, Pytest + VCR cassettes for testing, MkDocs for docs, GitHub Actions for CI/CD, pip/uv for distribution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code Layer
    subgraph "User Code Layer"
        direction TB
        UC["User Python Code\n@prompt / @chatprompt"]:::user
    end

    %% Core Library
    subgraph "Magentic Core Library" 
        direction TB
        ChatRuntime["_chat.py\n_parsing.py\n_pydantic.py\n_streamed_response.py"]:::core
        PromptChain["prompt_chain.py"]:::core
        ChatPrompt["chatprompt.py"]:::core
        PromptFunctionDeco["prompt_function.py"]:::core
        FunctionCallCore["function_call.py"]:::core
        Formatting["formatting.py"]:::core
        LoggerCore["logger.py"]:::core
        StreamingCore["streaming.py"]:::core
        TypingCore["typing.py"]:::core
    end

    %% Configuration & Settings
    subgraph "Configuration & Settings" 
        direction TB
        Settings["settings.py"]:::config
        BackendOrch["backend.py"]:::config
    end

    %% ChatModel Interface & Plugins
    subgraph "ChatModel Interface & Backends"
        direction TB
        Interface["chat_model/base.py\nfunction_schema.py\nmessage.py\nstream.py"]:::interface
        subgraph "Backend Plugins"
            direction TB
            OpenAI["openai_chat_model.py"]:::backend
            Anthropic["anthropic_chat_model.py"]:::backend
            LiteLLM["litellm_chat_model.py"]:::backend
            Mistral["mistral_chat_model.py"]:::backend
            RetryWrap["retry_chat_model.py"]:::backend
        end
    end

    %% External LLM Providers
    subgraph "External LLM Providers"
        direction TB
        OpenAIAPI["OpenAI API"]:::external
        AnthropicAPI["Anthropic API"]:::external
        LiteLLMAPI["LiteLLM API"]:::external
        MistralAPI["Mistral API"]:::external
    end

    %% Function Execution Engine
    subgraph "Function Execution Engine"
        direction TB
        FuncExec["FunctionCall Loop"]:::engine
    end

    %% Observability & Retry Subsystem
    subgraph "Observability & Retry"
        direction TB
        Observability["OpenTelemetry & Logfire Hooks"]:::obs
        RetryConfig["Retry Policies\n(via settings)"]:::obs
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        DocsContent["docs/ + mkdocs.yml"]:::pipeline
        DeployDocs[".github/workflows/deploy_docs.yml"]:::pipeline
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        TestCI[".github/workflows/test.yml"]:::pipeline
        PublishCI[".github/workflows/publish.yml"]:::pipeline
    end

    %% Testing Harness
    subgraph "Testing Harness"
        direction TB
        Tests["tests/ + cassettes/"]:::pipeline
    end

    %% Connections
    UC -->|"calls decorator"| ChatRuntime
    ChatRuntime -->|"uses"| PromptChain
    ChatRuntime -->|"uses"| ChatPrompt
    ChatRuntime -->|"uses"| PromptFunctionDeco
    PromptFunctionDeco -->|"invokes"| FunctionCallCore
    FunctionCallCore -->|"executes"| FuncExec
    FuncExec -->|"returns result"| ChatRuntime
    ChatRuntime -->|"formats"| Formatting
    ChatRuntime -->|"streams via"| StreamingCore
    ChatRuntime -->|"logs spans"| LoggerCore
    ChatRuntime -->|"types"| TypingCore
    ChatRuntime -->|"load settings"| Settings
    Settings -->|"selects backend"| BackendOrch
    BackendOrch -->|"implements interface"| Interface
    Interface -->|"plugin"| OpenAI
    Interface -->|"plugin"| Anthropic
    Interface -->|"plugin"| LiteLLM
    Interface -->|"plugin"| Mistral
    Interface -->|"wrapped by"| RetryWrap
    OpenAI -->|"HTTP request"| OpenAIAPI
    Anthropic -->|"HTTP request"| AnthropicAPI
    LiteLLM -->|"HTTP request"| LiteLLMAPI
    Mistral -->|"HTTP request"| MistralAPI
    ChatRuntime -->|"observability spans"| Observability
    RetryWrap -->|"uses policies"| RetryConfig
    TestCI -->|"runs tests on"| Tests
    PublishCI -->|"publishes package"| UC
    DeployDocs -->|"deploys docs from"| DocsContent

    %% Click Events
    click ChatRuntime "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/_chat.py"
    click ChatRuntime "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/_parsing.py"
    click ChatRuntime "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/_pydantic.py"
    click ChatRuntime "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/_streamed_response.py"
    click PromptChain "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/prompt_chain.py"
    click ChatPrompt "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chatprompt.py"
    click PromptFunctionDeco "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/prompt_function.py"
    click FunctionCallCore "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/function_call.py"
    click Formatting "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/formatting.py"
    click LoggerCore "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/logger.py"
    click StreamingCore "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/streaming.py"
    click TypingCore "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/typing.py"
    click Settings "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/settings.py"
    click BackendOrch "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/backend.py"
    click Interface "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/base.py"
    click Interface "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/function_schema.py"
    click Interface "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/message.py"
    click Interface "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/stream.py"
    click OpenAI "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/openai_chat_model.py"
    click Anthropic "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/anthropic_chat_model.py"
    click LiteLLM "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/litellm_chat_model.py"
    click Mistral "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/mistral_chat_model.py"
    click RetryWrap "https://github.com/jackmpcollins/magentic/blob/main/src/magentic/chat_model/retry_chat_model.py"
    click DocsContent "https://github.com/jackmpcollins/magentic/tree/main/docs/"
    click DocsContent "https://github.com/jackmpcollins/magentic/blob/main/mkdocs.yml"
    click DeployDocs "https://github.com/jackmpcollins/magentic/blob/main/.github/workflows/deploy_docs.yml"
    click TestCI "https://github.com/jackmpcollins/magentic/blob/main/.github/workflows/test.yml"
    click PublishCI "https://github.com/jackmpcollins/magentic/blob/main/.github/workflows/publish.yml"
    click Tests "https://github.com/jackmpcollins/magentic/tree/main/tests/"

    %% Styles
    classDef user fill:#f9c,stroke:#333,stroke-width:1px;
    classDef core fill:#bbdefb,stroke:#333,stroke-width:1px;
    classDef config fill:#b2dfdb,stroke:#333,stroke-width:1px;
    classDef interface fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef backend fill:#aed581,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcc80,stroke:#333,stroke-width:1px;
    classDef engine fill:#d1c4e9,stroke:#333,stroke-width:1px;
    classDef obs fill:#fff9c4,stroke:#333,stroke-width:1px;
    classDef pipeline fill:#eceff1,stroke:#333,stroke-width:1px;
```
