How tlepoid/explicator works
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.