explicator 0.1.0__py3-none-any.whl

explicator/ai/tools/definitions.py

@@ -0,0 +1,124 @@
+"""Tool definitions in OpenAI function-calling JSON schema format.
+
+This module is the single source of truth for all tool schemas.
+All AI providers (Claude, Azure OpenAI, etc.) consume these definitions
+and translate to their own wire format internally.
+
+No provider-specific code lives here.
+"""
+
+TOOL_DEFINITIONS: list[dict] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "run_scenario",
+            "description": (
+                "Run a named scenario through the portfolio model, optionally applying "
+                "additional input overrides for this run only. Returns the full set of "
+                "model outputs including portfolio metrics."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "The name of the scenario to run.",
+                    },
+                    "overrides": {
+                        "type": "object",
+                        "description": (
+                            "Optional map of input field names to numeric values to "
+                            "override for this run only. These do not persist."
+                        ),
+                        "additionalProperties": {"type": "number"},
+                    },
+                },
+                "required": ["name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "override_input",
+            "description": (
+                "Apply a persistent session-level override to a specific model input. "
+                "This override will be applied to all subsequent scenario runs until "
+                "reset_overrides is called."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "source": {
+                        "type": "string",
+                        "description": "The input source group, e.g. 'rates'.",
+                    },
+                    "field": {
+                        "type": "string",
+                        "description": "The field name within that source group.",
+                    },
+                    "value": {
+                        "type": "number",
+                        "description": "The numeric value to apply.",
+                    },
+                },
+                "required": ["source", "field", "value"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "reset_overrides",
+            "description": (
+                "Clear all active session-level input overrides, restoring all model "
+                "inputs to their configured defaults."
+            ),
+            "parameters": {"type": "object", "properties": {}, "required": []},
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "compare_scenarios",
+            "description": (
+                "Run two named scenarios and return a side-by-side comparison "
+                "of their outputs, including absolute and percentage differences. "
+                "Optionally restrict the comparison to specific output metrics."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scenario_a": {
+                        "type": "string",
+                        "description": "Name of the first scenario.",
+                    },
+                    "scenario_b": {
+                        "type": "string",
+                        "description": "Name of the second scenario.",
+                    },
+                    "metrics": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "Optional list of output field names to compare. "
+                            "If omitted, all shared outputs are compared."
+                        ),
+                    },
+                },
+                "required": ["scenario_a", "scenario_b"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_available_scenarios",
+            "description": (
+                "List all configured scenarios with their names, descriptions, "
+                "and stress rationale."
+            ),
+            "parameters": {"type": "object", "properties": {}, "required": []},
+        },
+    },
+]

explicator/application/__init__.py

@@ -0,0 +1 @@
+"""Application service layer for Explicator."""

explicator/application/service.py

@@ -0,0 +1,154 @@
+"""Application service layer — the single entry point for all business logic.
+
+All adapters (CLI, MCP server, AI orchestrator) call into this service.
+No business logic lives in adapters. No framework code lives here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from explicator.domain.models import (
+    ModelSchema,
+    Override,
+    ScenarioComparison,
+    ScenarioDefinition,
+    ScenarioResult,
+)
+from explicator.domain.ports import ModelRepository, ScenarioRunner
+
+
+class ModelService:
+    """
+    Framework-agnostic application service layer.
+
+    Owns session state (active overrides, cached results). Delegates
+    scenario execution to the ScenarioRunner port and model metadata
+    to the ModelRepository port.
+    """
+
+    def __init__(self, runner: ScenarioRunner, repository: ModelRepository) -> None:
+        """Initialise the service with a runner and repository."""
+        self._runner = runner
+        self._repository = repository
+        self._overrides: list[Override] = []
+        self._last_results: dict[str, ScenarioResult] = {}
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    def get_available_scenarios(self) -> list[ScenarioDefinition]:
+        """Return all configured scenarios with their descriptions."""
+        return self._repository.get_scenarios()
+
+    def get_current_results(self) -> dict[str, ScenarioResult]:
+        """Return the most recent result for each scenario run this session."""
+        return dict(self._last_results)
+
+    def get_model_schema(self) -> ModelSchema:
+        """Return the full structured description of model inputs and outputs."""
+        return self._repository.get_schema()
+
+    def get_active_overrides(self) -> list[Override]:
+        """Return all currently active session-level input overrides."""
+        return list(self._overrides)
+
+    # ------------------------------------------------------------------
+    # Commands
+    # ------------------------------------------------------------------
+
+    def run_scenario(
+        self,
+        name: str,
+        overrides: dict[str, Any] | None = None,
+    ) -> ScenarioResult:
+        """
+        Run a named scenario, merging active overrides with any call-specific overrides.
+
+        Precedence (highest wins): call-specific overrides > session overrides >
+        scenario definition overrides > model base inputs.
+        """
+        scenarios = {s.name: s for s in self._repository.get_scenarios()}
+        if name not in scenarios:
+            available = ", ".join(scenarios.keys())
+            raise ValueError(f"Unknown scenario '{name}'. Available: {available}")
+
+        scenario = scenarios[name]
+
+        combined: dict[str, Any] = {}
+        for ov in self._overrides:
+            combined[ov.field] = ov.value
+        if overrides:
+            combined.update(overrides)
+
+        result = self._runner.run(scenario, extra_overrides=combined)
+        self._last_results[name] = result
+        return result
+
+    def override_input(self, source: str, field: str, value: float) -> str:
+        """Apply a session-level override to a specific input field.
+
+        Replaces any existing override for the same field.
+        """
+        self._overrides = [o for o in self._overrides if o.field != field]
+        self._overrides.append(Override(source=source, field=field, value=value))
+        return f"Override applied: {source}.{field} = {value}"
+
+    def reset_overrides(self) -> str:
+        """Clear all active session-level input overrides."""
+        count = len(self._overrides)
+        self._overrides = []
+        return f"Cleared {count} override(s). All inputs restored to model defaults."
+
+    def compare_scenarios(
+        self,
+        scenario_a: str,
+        scenario_b: str,
+        metrics: list[str] | None = None,
+    ) -> ScenarioComparison:
+        """Run two scenarios and return a structured side-by-side comparison.
+
+        If metrics is None, all output fields present in both results are compared.
+        """
+        result_a = self.run_scenario(scenario_a)
+        result_b = self.run_scenario(scenario_b)
+
+        all_outputs = set(result_a.outputs.keys()) | set(result_b.outputs.keys())
+        compare_metrics = metrics if metrics else sorted(all_outputs)
+
+        differences: dict[str, dict] = {}
+        for metric in compare_metrics:
+            val_a = result_a.outputs.get(metric)
+            val_b = result_b.outputs.get(metric)
+            if val_a is not None and val_b is not None:
+                try:
+                    delta = float(val_b) - float(val_a)
+                    pct = (delta / float(val_a) * 100) if val_a != 0 else None
+                    differences[metric] = {
+                        "a": val_a,
+                        "b": val_b,
+                        "delta": round(delta, 6),
+                        "pct_change": round(pct, 2) if pct is not None else None,
+                    }
+                except (TypeError, ValueError):
+                    differences[metric] = {
+                        "a": val_a,
+                        "b": val_b,
+                        "delta": None,
+                        "pct_change": None,
+                    }
+            else:
+                differences[metric] = {
+                    "a": val_a,
+                    "b": val_b,
+                    "delta": None,
+                    "pct_change": None,
+                }
+
+        return ScenarioComparison(
+            scenario_a=result_a,
+            scenario_b=result_b,
+            metrics=compare_metrics,
+            differences=differences,
+        )

explicator/config.py

@@ -0,0 +1,72 @@
+"""Configuration loading for Explicator.
+
+Reads from environment variables with optional .env file support.
+Follows the existing application pattern — no new config mechanisms.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from explicator.ai.providers.base import AIProvider
+
+
+@dataclass
+class Config:
+    """Runtime configuration loaded from environment variables."""
+
+    ai_provider: str = "claude"  # "claude" | "azure_openai"
+    claude_api_key: str | None = None
+    claude_model: str = "claude-sonnet-4-6"
+    azure_api_key: str | None = None
+    azure_endpoint: str | None = None
+    azure_deployment: str | None = None
+    azure_api_version: str = "2024-02-01"
+
+
+def load_config() -> Config:
+    """Load configuration from environment variables (and optional .env file)."""
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv()
+    except ImportError:
+        pass  # python-dotenv is optional
+
+    return Config(
+        ai_provider=os.getenv("AI_PROVIDER", "claude"),
+        claude_api_key=os.getenv("ANTHROPIC_API_KEY"),
+        claude_model=os.getenv("CLAUDE_MODEL", "claude-sonnet-4-6"),
+        azure_api_key=os.getenv("AZURE_OPENAI_API_KEY"),
+        azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
+        azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT"),
+        azure_api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-02-01"),
+    )
+
+
+def build_provider(config: Config | None = None) -> AIProvider:
+    """Instantiate the AI provider selected by configuration."""
+    if config is None:
+        config = load_config()
+
+    if config.ai_provider == "claude":
+        from explicator.ai.providers.claude import ClaudeProvider
+
+        return ClaudeProvider(api_key=config.claude_api_key, model=config.claude_model)
+
+    if config.ai_provider == "azure_openai":
+        from explicator.ai.providers.azure_openai import AzureOpenAIProvider
+
+        return AzureOpenAIProvider(
+            api_key=config.azure_api_key,
+            azure_endpoint=config.azure_endpoint,
+            deployment_name=config.azure_deployment,
+            api_version=config.azure_api_version,
+        )
+
+    raise ValueError(
+        f"Unknown AI_PROVIDER '{config.ai_provider}'. Supported: claude, azure_openai"
+    )

explicator/domain/__init__.py

@@ -0,0 +1 @@
+"""Core domain models and port interfaces for Explicator."""

explicator/domain/models.py

@@ -0,0 +1,160 @@
+"""Core domain model — data structures shared across the entire application.
+
+These are plain dataclasses with no framework dependencies. All adapters
+(CLI, MCP server, AI providers) work with these types.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class InputField:
+    """A single model input variable."""
+
+    name: str
+    source: str  # logical grouping, e.g. "rates", "credit", "equity"
+    description: str
+    units: str
+    typical_min: float
+    typical_max: float
+    current_value: float | None = None
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "name": self.name,
+            "source": self.source,
+            "description": self.description,
+            "units": self.units,
+            "typical_min": self.typical_min,
+            "typical_max": self.typical_max,
+            "current_value": self.current_value,
+        }
+
+
+@dataclass
+class OutputField:
+    """A single model output metric."""
+
+    name: str
+    description: str
+    units: str
+    interpretation: str
+    good_threshold: float | None = None  # value below which result is concerning
+    bad_threshold: float | None = None  # value below which result is critical
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "units": self.units,
+            "interpretation": self.interpretation,
+            "good_threshold": self.good_threshold,
+            "bad_threshold": self.bad_threshold,
+        }
+
+
+@dataclass
+class ModelSchema:
+    """Full description of the model's inputs, outputs, assumptions, and caveats."""
+
+    name: str
+    description: str
+    inputs: list[InputField]
+    outputs: list[OutputField]
+    assumptions: list[str]
+    caveats: list[str]
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputs": [i.to_dict() for i in self.inputs],
+            "outputs": [o.to_dict() for o in self.outputs],
+            "assumptions": self.assumptions,
+            "caveats": self.caveats,
+        }
+
+
+@dataclass
+class ScenarioDefinition:
+    """A named scenario with its baseline overrides and stress description."""
+
+    name: str
+    description: str
+    stress_rationale: str
+    overrides: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "stress_rationale": self.stress_rationale,
+            "overrides": self.overrides,
+        }
+
+
+@dataclass
+class ScenarioResult:
+    """The result of running a scenario through the model."""
+
+    scenario_name: str
+    inputs_used: dict[str, Any]
+    outputs: dict[str, Any]
+    overrides_applied: dict[str, Any]
+    run_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "scenario_name": self.scenario_name,
+            "inputs_used": self.inputs_used,
+            "outputs": self.outputs,
+            "overrides_applied": self.overrides_applied,
+            "run_at": self.run_at,
+        }
+
+
+@dataclass
+class Override:
+    """A single active session-level input override."""
+
+    source: str
+    field: str
+    value: Any
+    applied_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "source": self.source,
+            "field": self.field,
+            "value": self.value,
+            "applied_at": self.applied_at,
+        }
+
+
+@dataclass
+class ScenarioComparison:
+    """Side-by-side comparison of two scenario results."""
+
+    scenario_a: ScenarioResult
+    scenario_b: ScenarioResult
+    metrics: list[str]
+    differences: dict[str, dict]  # metric -> {a, b, delta, pct_change}
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-compatible dict."""
+        return {
+            "scenario_a": self.scenario_a.to_dict(),
+            "scenario_b": self.scenario_b.to_dict(),
+            "metrics": self.metrics,
+            "differences": self.differences,
+        }

explicator/domain/ports.py

@@ -0,0 +1,43 @@
+"""Abstract ports — interfaces that adapters must implement.
+
+These define the boundary between the application layer and the
+infrastructure/data layer. Concrete implementations live in adapters/data/.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from explicator.domain.models import (
+    InputField,
+    ModelSchema,
+    ScenarioDefinition,
+    ScenarioResult,
+)
+
+
+class ScenarioRunner(ABC):
+    """Port: executes scenarios against the underlying model."""
+
+    @abstractmethod
+    def run(
+        self,
+        scenario: ScenarioDefinition,
+        extra_overrides: dict[str, Any],
+    ) -> ScenarioResult:
+        """Run a scenario with optional additional overrides beyond the definition."""
+
+
+class ModelRepository(ABC):
+    """Port: provides access to model configuration and metadata."""
+
+    @abstractmethod
+    def get_scenarios(self) -> list[ScenarioDefinition]:
+        """Return all available scenario definitions."""
+
+    @abstractmethod
+    def get_schema(self) -> ModelSchema:
+        """Return the full model schema."""
+
+    @abstractmethod
+    def get_inputs(self) -> list[InputField]:
+        """Return current state of all model inputs."""

explicator-0.1.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.3
+Name: explicator
+Version: 0.1.0
+Summary: Provider-agnostic natural language AI interface for scenario-driven modelling
+Author: Tim le Poidevin
+Author-email: Tim le Poidevin <lepoidevin.tim@gmail.com>
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: openai>=1.0.0 ; extra == 'azure'
+Requires-Dist: anthropic>=0.40.0 ; extra == 'claude'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12 ; extra == 'dev'
+Requires-Dist: mcp[cli] ; extra == 'dev'
+Requires-Dist: pre-commit>=4.5.1 ; extra == 'dev'
+Requires-Dist: ruff>=0.15.4 ; extra == 'dev'
+Requires-Python: >=3.10
+Provides-Extra: azure
+Provides-Extra: claude
+Provides-Extra: dev

explicator-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+explicator/__init__.py,sha256=2HgPB745GgqN45QWyTWXk-QZm5B-jBj9sEUNh3imp-8,5064
+explicator/adapters/__init__.py,sha256=lDTm0Y4ieqU2KNUL1Zehmxe9Z_ICOjirFoPSA2tKSII,73
+explicator/adapters/cli/__init__.py,sha256=XtPIF5XLQlSl6443eLb6l0qF2KLLGEm13WVVoanX4kc,34
+explicator/adapters/cli/main.py,sha256=mHVdVs_IZVF9irONiWM1Gkk5is9qUeuNJ2gaaQkuslQ,4851
+explicator/adapters/data/__init__.py,sha256=xzlwIEGfaZUth2AfMQpJIvdSVJK7CefvJuKWmxAUSCY,46
+explicator/adapters/data/in_memory.py,sha256=joU9xdpK4ArxLv1-lDZrU6PO1zkmOqfUw-CJ5Wb_8I4,4113
+explicator/adapters/mcp_server/__init__.py,sha256=RRi8FUVRjPc0HSOWXyIdfjj6TnEa8wcaRtXZ5bOiN9s,41
+explicator/adapters/mcp_server/__main__.py,sha256=I0RU9vvxcCxWwVg-AGiRMKWRPWwE25g1l38hjVyxb0k,738
+explicator/adapters/mcp_server/server.py,sha256=Jmm6W33mzR8QPtIZeumOGwWMAmxoVt3rgdXXs1LGjlA,10932
+explicator/ai/__init__.py,sha256=OyfUwfz6FPqi_NpY2pjoHKHcOOpZIAkS7aEckcJ2NSQ,65
+explicator/ai/dispatcher.py,sha256=oxXHw6poLVHV8aFHArW4e2qpGxcm1MZX_Mw6U_Jr7cg,2660
+explicator/ai/providers/__init__.py,sha256=p_FCStIoS1gP_M1ARuP7oIXwePHm_MUEYOjKqygzsjk,60
+explicator/ai/providers/azure_openai.py,sha256=qMlHVt05Efy8LPMWf1WQroVtAuyPW8s9qMnXuYCdWBA,3492
+explicator/ai/providers/base.py,sha256=gDgS3380t9UI85fR5xgv7Bh8cJuTbP2UxPN-9EOKgyM,1883
+explicator/ai/providers/claude.py,sha256=KE-N4h9Mcar23NMQYrU7Jvyubir2YuixmKzf_MZThfs,3660
+explicator/ai/tools/__init__.py,sha256=DyXqDcgW1OMAXa3ek_aieGkHB6wpV_or_OVzcbwV2xs,70
+explicator/ai/tools/definitions.py,sha256=nZeKhoWXgQnKHJkTT9V7o9hF6dgO1C07WJyFEZ5eijY,4599
+explicator/application/__init__.py,sha256=djB0vJ2C-GEqC4qASBvVfoenh-muBkMksywNQLfiVJs,48
+explicator/application/service.py,sha256=Lxcd0RXRF-hEunjjNfZxrF7xuHN4hWhBm_r8vmQ3XV0,5700
+explicator/config.py,sha256=OoDAQI4JIMhxrfW-RUVdebWQ2_btizkJpxETJrCZvqs,2342
+explicator/domain/__init__.py,sha256=qJJYCO6Ht2FZ6bIG-ScH0HIg-ysKbO202uhuZMeWbMM,61
+explicator/domain/models.py,sha256=25Z9NxhLbxacGxW84wH0viAdvWiPBnBULVzf7lB_kVI,4522
+explicator/domain/ports.py,sha256=At9_7aog8NyC6kmPZjcVgrg0yVIdVkitqWtwswGNMVQ,1183
+explicator-0.1.0.dist-info/WHEEL,sha256=Uo4e6VmJM8J_cLBTtiWBRVQkc1yUEkw94xaL0B_lH6c,80
+explicator-0.1.0.dist-info/entry_points.txt,sha256=RNZbSoNHKBxBRSFcKJLQJE4xnmu1ulnN1Vbk8LmWWx0,125
+explicator-0.1.0.dist-info/METADATA,sha256=ik2OjPbnuZxoxsknBKSXJtHE0M31K7Z16tr5wsYTXac,781
+explicator-0.1.0.dist-info/RECORD,,

explicator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.7
+Root-Is-Purelib: true
+Tag: py3-none-any

explicator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+explicator = explicator.adapters.cli.main:cli
+explicator-mcp = explicator.adapters.mcp_server.server:main
+