# tlepoid/explicator architecture

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

- Interactive diagram: https://gitdiagram.com/tlepoid/explicator
- Repository: https://github.com/tlepoid/explicator

## Overview

This repo is a **Python library** (not a deployed app) that provides a **ports & adapters (hexagonal) architecture** for “LLM-assisted model explanation”. The core value flow is:

**Natural language question → LLM selects/requests tools → tools run scenarios against a user-supplied analytical model → results are summarized/explained back to the user**.

It ships two primary “driving adapters” (entry points):

- **CLI adapter** (Click) for humans in terminals
- **MCP Server adapter** (FastMCP) for Claude Desktop / MCP clients

…and multiple “driven adapters” for LLM providers and storage/execution backends. The user’s model itself lives outside the library (the `examples/demo_model` shows how to wire it).

##### External Actors
- Terminal user (CLI)
- MCP client (Claude Desktop / other MCP client)
- LLM Provider(s): Anthropic Claude, Azure OpenAI (and “others via provider adapter”)

##### Driving Adapters
- CLI (Click)
- MCP Server (FastMCP)

##### Application Core
- `ModelService` (application service)

##### Domain
- Domain Models (ScenarioDefinition/Result, ModelSchema, etc.)
- Domain Ports (ScenarioRunner, ModelRepository)

##### Driven Adapters / Infrastructure
- ModelRepository implementation (in-memory in this repo; extensible)
- ScenarioRunner implementation (user-supplied or default wiring)
- User Analytical Model Function (lives in *consumer project*, shown via examples)

##### AI Subsystem
- Tool Definitions (JSON schema)
- Tool Dispatcher
- Provider Adapters (Claude, Azure OpenAI)
- Config (env vars)

- **Ports & Adapters / Hexagonal architecture**
- Domain ports (`ScenarioRunner`, `ModelRepository`) define stable boundaries.
- Adapters depend inward; core does not depend on adapters.
- **Single application entry point**
- `ModelService` is intentionally the shared API between CLI and MCP.
- **Provider-agnostic AI layer**
- Tool schemas are centralized (`ai/tools/definitions.py`).
- Providers are pluggable modules (`ai/providers/*`).
- **Parallel entry points**
- CLI and MCP Server share no code except via `ModelService`.

- **Consumer Project**
- `myapp.model:build_service()` / `explicator.create(...)`
- `User Model Function (model_fn)`
- `Scenario definitions + schema`

- **Explicator Library**
- **Application**: `ModelService`
- **Domain**: `models.py`, `ports.py`
- **AI**: `tools/definitions.py`, `dispatcher.py`, `providers/*`
- **Adapters (Inbound)**: `CLI`, `MCP Server`
- **Adapters (Outbound)**: `in_memory repo` (and placeholders for custom repo/runner)

- **External**
- Terminal User
- MCP Client (Claude Desktop)
- Anthropic API / Azure OpenAI API

- CLI → ModelService
- MCP Server → ModelService
- MCP Server ↔ AI Dispatcher → Provider Adapter → LLM API
- ModelService → ScenarioRunner → User Model Function
- ModelService → ModelRepository
- Tool definitions → (used by) Dispatcher + Providers
- Config → Provider selection

That set captures “as many components as possible” without hallucinating infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External actors & systems
    %% =========================
    TU["Terminal User"]:::external
    MCPClient["MCP Client (Claude Desktop / other)"]:::external
    AnthropicAPI["Anthropic API"]:::external
    AzureAPI["Azure OpenAI API"]:::external

    %% =========================
    %% Consumer project (composition root)
    %% =========================
    subgraph "Consumer Project (outside library)"
        BuildService["myapp.model:build_service() / explicator.create(...)"]:::consumer
        UserModelFn["User Analytical Model Function (model_fn)"]:::consumer
        UserScenarioDefs["Scenario definitions + schema"]:::consumer
    end

    %% =========================
    %% Explicator library (hexagonal)
    %% =========================
    subgraph "Explicator Library (Python package)"
        direction TB

        %% ---- Driving adapters (inbound) ----
        subgraph "Driving Adapters (Inbound)"
            direction TB
            CLI["explicator.adapters.cli (Click CLI)"]:::inbound
            MCPServer["explicator.adapters.mcp_server (FastMCP Server)"]:::inbound
            MCPMain["mcp_server __main__ (entry point)"]:::inbound_aux
        end

        %% ---- Application core ----
        subgraph "Application (Inner Ring)"
            direction TB
            ModelService["explicator.application.ModelService (service.py)"]:::app
        end

        %% ---- Domain core ----
        subgraph "Domain (Core)"
            direction TB
            DomainModels["explicator.domain.models (ScenarioDefinition/Result, ModelSchema, ...)"]:::domain
            DomainPorts["explicator.domain.ports (ScenarioRunner, ModelRepository)"]:::domain
            ScenarioRunnerPort["Port: ScenarioRunner"]:::port
            ModelRepoPort["Port: ModelRepository"]:::port
        end

        %% ---- Driven adapters (outbound/infrastructure) ----
        subgraph "Driven Adapters (Outbound / Infrastructure)"
            direction TB
            InMemoryAdapter["explicator.adapters.data.in_memory (repo/runner wiring)"]:::outbound
            RepoImpl["InMemory ModelRepository (implements port)"]:::outbound
            RunnerImpl["ScenarioRunner wiring (implements port)"]:::outbound
        end

        %% ---- AI subsystem (provider-agnostic) ----
        subgraph "AI Subsystem"
            direction TB
            ToolDefs["explicator.ai.tools.definitions (function schemas)"]:::ai
            Dispatcher["explicator.ai.dispatcher.ToolDispatcher"]:::ai
            Config["explicator.config (env-driven selection/keys/endpoints)"]:::config

            subgraph "AI Provider Adapters (Pluggable)"
                direction TB
                ProviderBase["explicator.ai.providers.base (Base Provider Adapter)"]:::provider
                ClaudeProvider["explicator.ai.providers.claude (Anthropic Claude Adapter)"]:::provider
                AzureProvider["explicator.ai.providers.azure_openai (Azure OpenAI Adapter)"]:::provider
            end
        end

        %% ---- Tests (validation edges) ----
        subgraph "Tests (validation of boundaries)"
            direction TB
            TestService["tests/unit/test_service.py"]:::test
            TestDispatcher["tests/unit/test_dispatcher.py"]:::test
            TestMcpTools["tests/unit/test_mcp_tools.py"]:::test
            TestMcpIntegration["tests/integration/test_mcp_server.py"]:::test
        end
    end

    %% =========================
    %% Example runner (consumer side)
    %% =========================
    subgraph "Examples"
        direction TB
        ExampleMcpRun["examples/demo_model/run_mcp.py (starts MCP with example service)"]:::consumer_aux
    end

    %% =========================
    %% Runtime flows (solid)
    %% =========================
    TU -->|"invokes"| CLI
    CLI -->|"commands:scenarios/run/compare/chat"| ModelService
    ModelService -->|"uses"| DomainModels
    ModelService -->|"depends-on ports"| DomainPorts

    ModelService -->|"calls ScenarioRunner"| ScenarioRunnerPort
    ModelService -->|"calls ModelRepository"| ModelRepoPort

    ScenarioRunnerPort -->|"implemented-by"| RunnerImpl
    ModelRepoPort -->|"implemented-by"| RepoImpl
    InMemoryAdapter -->|"provides"| RunnerImpl
    InMemoryAdapter -->|"provides"| RepoImpl

    RunnerImpl -->|"executes"| UserModelFn
    BuildService -->|"wires"| ModelService
    BuildService -->|"provides"| UserModelFn
    BuildService -->|"provides"| UserScenarioDefs

    MCPClient -->|"connects"| MCPServer
    MCPMain -->|"starts"| MCPServer
    MCPServer -->|"tools:list/run/compare"| ModelService

    %% Tool-calling loop via MCP
    MCPServer <-->|"chat orchestration"| Dispatcher
    Dispatcher -->|"uses schemas"| ToolDefs
    Dispatcher -->|"tool invokes"| ModelService
    Dispatcher -->|"calls provider"| ProviderBase

    ProviderBase -->|"impl"| ClaudeProvider
    ProviderBase -->|"impl"| AzureProvider
    ClaudeProvider -->|"LLM API"| AnthropicAPI
    AzureProvider -->|"LLM API"| AzureAPI

    %% Responses back out
    ModelService -->|"structured results"| Dispatcher
    Dispatcher -->|"final explanation"| MCPServer
    MCPServer -->|"response"| MCPClient

    %% Example runner wiring
    ExampleMcpRun -->|"loads build_service()"| BuildService
    ExampleMcpRun -->|"runs"| MCPServer

    %% =========================
    %% Dependency/config edges (dashed)
    %% =========================
    Config -.->|"selects via AI_PROVIDER"| ProviderBase
    ToolDefs -.->|"single source of truth"| ClaudeProvider
    ToolDefs -.->|"single source of truth"| AzureProvider

    %% Hexagonal dependency direction (adapters depend inward)
    CLI -.->|"imports/depends-on"| ModelService
    MCPServer -.->|"imports/depends-on"| ModelService
    InMemoryAdapter -.->|"implements ports"| DomainPorts
    ModelService -.->|"depends-on"| DomainPorts
    DomainPorts -.->|"types in"| DomainModels

    %% Tests validate components
    TestService -.->|"validates"| ModelService
    TestDispatcher -.->|"validates"| Dispatcher
    TestMcpTools -.->|"validates tool defs"| ToolDefs
    TestMcpIntegration -.->|"validates boundary"| MCPServer

    %% =========================
    %% Click events (component mapping)
    %% =========================
    click DomainModels "https://github.com/tlepoid/explicator/blob/main/src/explicator/domain/models.py"
    click DomainPorts "https://github.com/tlepoid/explicator/blob/main/src/explicator/domain/ports.py"
    click ModelService "https://github.com/tlepoid/explicator/blob/main/src/explicator/application/service.py"
    click Dispatcher "https://github.com/tlepoid/explicator/blob/main/src/explicator/ai/dispatcher.py"
    click ToolDefs "https://github.com/tlepoid/explicator/blob/main/src/explicator/ai/tools/definitions.py"
    click ProviderBase "https://github.com/tlepoid/explicator/blob/main/src/explicator/ai/providers/base.py"
    click ClaudeProvider "https://github.com/tlepoid/explicator/blob/main/src/explicator/ai/providers/claude.py"
    click AzureProvider "https://github.com/tlepoid/explicator/blob/main/src/explicator/ai/providers/azure_openai.py"
    click CLI "https://github.com/tlepoid/explicator/blob/main/src/explicator/adapters/cli/main.py"
    click MCPServer "https://github.com/tlepoid/explicator/blob/main/src/explicator/adapters/mcp_server/server.py"
    click MCPMain "https://github.com/tlepoid/explicator/blob/main/src/explicator/adapters/mcp_server/__main__.py"
    click InMemoryAdapter "https://github.com/tlepoid/explicator/blob/main/src/explicator/adapters/data/in_memory.py"
    click Config "https://github.com/tlepoid/explicator/blob/main/src/explicator/config.py"
    click BuildService "https://github.com/tlepoid/explicator/blob/main/examples/demo_model/model.py"
    click ExampleMcpRun "https://github.com/tlepoid/explicator/blob/main/examples/demo_model/run_mcp.py"
    click TestService "https://github.com/tlepoid/explicator/blob/main/tests/unit/test_service.py"
    click TestDispatcher "https://github.com/tlepoid/explicator/blob/main/tests/unit/test_dispatcher.py"
    click TestMcpTools "https://github.com/tlepoid/explicator/blob/main/tests/unit/test_mcp_tools.py"
    click TestMcpIntegration "https://github.com/tlepoid/explicator/blob/main/tests/integration/test_mcp_server.py"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440
    classDef consumer fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
    classDef consumer_aux fill:#F1F8E9,stroke:#558B2F,stroke-width:1px,color:#33691E
    classDef inbound fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1
    classDef inbound_aux fill:#E1F5FE,stroke:#0277BD,stroke-width:1px,color:#01579B
    classDef app fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#E65100
    classDef domain fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#4A148C
    classDef port fill:#F8EAFB,stroke:#8E24AA,stroke-width:1px,stroke-dasharray:4 3,color:#4A148C
    classDef outbound fill:#E0F2F1,stroke:#00695C,stroke-width:1px,color:#004D40
    classDef ai fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#B71C1C
    classDef provider fill:#FCE4EC,stroke:#AD1457,stroke-width:1px,color:#880E4F
    classDef config fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#F57F17
    classDef test fill:#FAFAFA,stroke:#616161,stroke-width:1px,color:#212121
```
