explicator 0.1.0__py3-none-any.whl

explicator/adapters/mcp_server/server.py

@@ -0,0 +1,308 @@
+"""MCP Server adapter for Explicator.
+
+Exposes the ModelService as an MCP server with tools, resources, and prompts.
+This adapter sits alongside the CLI as a parallel entry point into the application
+layer — it does not bypass or duplicate any domain logic.
+
+Start with:
+    python -m explicator.adapters.mcp_server
+or via the entry point:
+    explicator-mcp
+"""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from explicator.application.service import ModelService
+
+# Module-level service instance set by the application wiring.
+# Using a module-level variable allows the MCP decorators to close over it
+# while keeping the server testable via set_service().
+_service: ModelService | None = None
+
+mcp = FastMCP("Explicator")
+
+
+def set_service(service: ModelService) -> None:
+    """Wire the ModelService instance used by this MCP server."""
+    global _service
+    _service = service
+
+
+def _get_service() -> ModelService:
+    if _service is None:
+        raise RuntimeError(
+            "ModelService has not been wired. "
+            "Call set_service() before starting the server."
+        )
+    return _service
+
+
+# ------------------------------------------------------------------
+# Tools — actions Claude can invoke
+# ------------------------------------------------------------------
+
+
+@mcp.tool()
+def run_scenario(name: str, overrides: dict[str, float] | None = None) -> dict:
+    """
+    Run a named scenario through the portfolio model.
+
+    Applies any active session-level overrides plus any overrides provided here
+    (call-specific overrides take precedence). Returns the full set of model outputs.
+    """
+    try:
+        result = _get_service().run_scenario(name, overrides=overrides)
+        return result.to_dict()
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool()
+def override_input(source: str, field: str, value: float) -> dict:
+    """
+    Apply a persistent session-level override to a model input.
+
+    This override is applied to all subsequent scenario runs until
+    reset_overrides is called. Use source to group related inputs
+    (e.g. "rates", "credit", "equity").
+    """
+    try:
+        message = _get_service().override_input(source, field, value)
+        return {"message": message, "source": source, "field": field, "value": value}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool()
+def reset_overrides() -> dict:
+    """Clear all active session-level overrides, restoring model defaults."""
+    try:
+        message = _get_service().reset_overrides()
+        return {"message": message}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool()
+def compare_scenarios(
+    scenario_a: str,
+    scenario_b: str,
+    metrics: list[str] | None = None,
+) -> dict:
+    """
+    Run two scenarios and return a structured side-by-side comparison.
+
+    Returns absolute deltas and percentage changes for each output metric.
+    If metrics is not provided, all shared output fields are compared.
+    """
+    try:
+        comparison = _get_service().compare_scenarios(scenario_a, scenario_b, metrics)
+        return comparison.to_dict()
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool()
+def get_available_scenarios() -> dict:
+    """List all configured scenarios with names, descriptions, and stress rationale."""
+    try:
+        scenarios = _get_service().get_available_scenarios()
+        return {"scenarios": [s.to_dict() for s in scenarios]}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+# ------------------------------------------------------------------
+# Resources — context Claude can read
+# ------------------------------------------------------------------
+
+
+@mcp.resource("model://schema")
+def get_model_schema() -> str:
+    """
+    Full structured description of all model inputs, outputs, assumptions, and caveats.
+
+    This is the primary source of truth for Claude's understanding of the domain.
+    Includes financial meaning, units, typical ranges, and interpretation guidance
+    for every field.
+    """
+    try:
+        schema = _get_service().get_model_schema()
+        return json.dumps(schema.to_dict(), indent=2)
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+@mcp.resource("model://scenarios")
+def get_scenarios_resource() -> str:
+    """Return scenario definitions, including what each is designed to stress-test."""
+    try:
+        scenarios = _get_service().get_available_scenarios()
+        return json.dumps([s.to_dict() for s in scenarios], indent=2)
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+@mcp.resource("model://results/latest")
+def get_latest_results() -> str:
+    """Most recent run results for all scenarios executed this session."""
+    try:
+        results = _get_service().get_current_results()
+        return json.dumps(
+            {name: r.to_dict() for name, r in results.items()},
+            indent=2,
+        )
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+@mcp.resource("model://overrides/current")
+def get_current_overrides() -> str:
+    """All input overrides currently active in this session."""
+    try:
+        overrides = _get_service().get_active_overrides()
+        return json.dumps([o.to_dict() for o in overrides], indent=2)
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+# ------------------------------------------------------------------
+# Prompts — reusable AI prompt templates
+# ------------------------------------------------------------------
+
+
+@mcp.prompt()
+def explain_scenario_result(scenario_name: str) -> str:
+    """Explain what drove the result of a given scenario in plain English."""
+    try:
+        results = _get_service().get_current_results()
+        schema = _get_service().get_model_schema()
+
+        if scenario_name not in results:
+            return (
+                f"No result found for scenario '{scenario_name}'. "
+                f"Run it first using the run_scenario tool."
+            )
+
+        result = results[scenario_name]
+        return (
+            f"You are a portfolio risk analyst. Explain the following scenario result "
+            f"in plain English to a non-technical stakeholder.\n\n"
+            f"Model: {schema.name}\n"
+            f"Scenario: {scenario_name}\n\n"
+            f"Inputs used:\n{json.dumps(result.inputs_used, indent=2)}\n\n"
+            f"Overrides applied:\n{json.dumps(result.overrides_applied, indent=2)}\n\n"
+            f"Outputs:\n{json.dumps(result.outputs, indent=2)}\n\n"
+            f"Focus on: what drove the key outputs, what risks this scenario reveals, "
+            f"and what a portfolio manager should take away from this result."
+        )
+    except Exception as exc:
+        return f"Error generating prompt: {exc}"
+
+
+@mcp.prompt()
+def compare_scenarios_narrative(scenario_a: str, scenario_b: str) -> str:
+    """Narrate the key differences between two scenario outcomes in plain English."""
+    try:
+        schema = _get_service().get_model_schema()
+        comparison = _get_service().compare_scenarios(scenario_a, scenario_b)
+        return (
+            f"You are a portfolio risk analyst. Compare these two scenario outcomes "
+            f"and narrate the key differences for a senior investment committee.\n\n"
+            f"Model: {schema.name}\n"
+            f"Comparing: '{scenario_a}' vs '{scenario_b}'\n\n"
+            "Comparison data:\n"
+            f"{json.dumps(comparison.to_dict(), indent=2)}\n\n"
+            "Focus on: the most significant differences, which scenario is more "
+            "stressful and why, and what risk factors are driving the divergence."
+        )
+    except Exception as exc:
+        return f"Error generating prompt: {exc}"
+
+
+@mcp.prompt()
+def summarise_portfolio_risk() -> str:
+    """Summarise current risk exposures across all scenarios that have been run."""
+    try:
+        results = _get_service().get_current_results()
+        schema = _get_service().get_model_schema()
+        overrides = _get_service().get_active_overrides()
+
+        if not results:
+            return (
+                "No scenarios have been run yet. Use the run_scenario tool to execute "
+                "one or more scenarios before requesting a risk summary."
+            )
+
+        return (
+            f"You are a chief risk officer. Summarise the portfolio's current risk "
+            f"exposures based on the scenario results below.\n\n"
+            f"Model: {schema.name}\n"
+            "Active overrides: "
+            f"{json.dumps([o.to_dict() for o in overrides], indent=2)}\n\n"
+            "Scenario results:\n"
+            f"{json.dumps({n: r.to_dict() for n, r in results.items()}, indent=2)}\n\n"
+            "Focus on: overall risk level, which scenarios are most severe, "
+            "key drivers of risk, and any concentrations or tail risks to flag."
+        )
+    except Exception as exc:
+        return f"Error generating prompt: {exc}"
+
+
+@mcp.prompt()
+def explain_input_sensitivity(input_field: str) -> str:
+    """Explain how sensitive the model is to a given input field."""
+    try:
+        schema = _get_service().get_model_schema()
+        field_info = next((i for i in schema.inputs if i.name == input_field), None)
+        field_desc = (
+            json.dumps(field_info.to_dict(), indent=2)
+            if field_info
+            else f"Field '{input_field}' not found in schema."
+        )
+        return (
+            "You are a quantitative analyst. Explain how sensitive this portfolio "
+            "model is to the following input, and what happens when it moves.\n\n"
+            f"Model: {schema.name}\n"
+            f"Input field: {input_field}\n"
+            f"Field details:\n{field_desc}\n\n"
+            "Explain: the financial meaning of this input, what drives it in practice, "
+            f"how the portfolio is exposed to it, and what a 1 standard deviation move "
+            f"might mean for portfolio outcomes."
+        )
+    except Exception as exc:
+        return f"Error generating prompt: {exc}"
+
+
+# ------------------------------------------------------------------
+# Entry point
+# ------------------------------------------------------------------
+
+
+def main() -> None:
+    """Start the MCP server.
+
+    Reads an optional service path from the first CLI argument::
+
+        explicator-mcp myapp.model:build_service
+
+    Falls back to stub wiring if no path is given.
+    """
+    import sys
+
+    if len(sys.argv) > 1:
+        import explicator as _explicator
+
+        service = _explicator.load_service(sys.argv[1])
+    else:
+        from explicator.adapters.data.in_memory import _build_stub_wiring
+
+        repository, runner = _build_stub_wiring()
+        service = ModelService(runner=runner, repository=repository)
+
+    set_service(service)
+    mcp.run()

explicator/ai/__init__.py

@@ -0,0 +1 @@
+"""AI provider abstractions and tool dispatch for Explicator."""

explicator/ai/dispatcher.py

@@ -0,0 +1,71 @@
+"""Tool execution dispatcher — shared across all AI providers.
+
+When any provider returns a tool call, this dispatcher handles it by routing
+to the appropriate ModelService method. Provider identity is irrelevant here:
+the same dispatcher handles tool calls from Claude, Azure OpenAI, or any other provider.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from explicator.application.service import ModelService
+
+
+class ToolDispatcher:
+    """
+    Routes tool call requests from AI providers to the ModelService.
+
+    Always returns a JSON-serialisable dict. Errors are returned as structured
+    dicts rather than raised, so the provider can relay them to the user.
+    """
+
+    def __init__(self, service: ModelService) -> None:
+        """Initialise with the ModelService to dispatch tool calls to."""
+        self._service = service
+        self._handlers: dict[str, Any] = {
+            "run_scenario": self._run_scenario,
+            "override_input": self._override_input,
+            "reset_overrides": self._reset_overrides,
+            "compare_scenarios": self._compare_scenarios,
+            "get_available_scenarios": self._get_available_scenarios,
+        }
+
+    def dispatch(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        """
+        Execute a named tool with the given arguments.
+
+        Returns a JSON-serialisable dict. Never raises.
+        """
+        try:
+            handler = self._handlers.get(name)
+            if handler is None:
+                return {"error": f"Unknown tool '{name}'."}
+            return handler(**arguments)
+        except Exception as exc:
+            return {"error": str(exc)}
+
+    def _run_scenario(self, name: str, overrides: dict | None = None) -> dict:
+        result = self._service.run_scenario(name, overrides=overrides)
+        return result.to_dict()
+
+    def _override_input(self, source: str, field: str, value: float) -> dict:
+        message = self._service.override_input(source, field, value)
+        return {"message": message, "source": source, "field": field, "value": value}
+
+    def _reset_overrides(self) -> dict:
+        message = self._service.reset_overrides()
+        return {"message": message}
+
+    def _compare_scenarios(
+        self,
+        scenario_a: str,
+        scenario_b: str,
+        metrics: list[str] | None = None,
+    ) -> dict:
+        comparison = self._service.compare_scenarios(scenario_a, scenario_b, metrics)
+        return comparison.to_dict()
+
+    def _get_available_scenarios(self) -> dict:
+        scenarios = self._service.get_available_scenarios()
+        return {"scenarios": [s.to_dict() for s in scenarios]}

explicator/ai/providers/__init__.py

@@ -0,0 +1 @@
+"""Concrete AI provider adapters (Claude, Azure OpenAI)."""

explicator/ai/providers/azure_openai.py

@@ -0,0 +1,111 @@
+"""Azure OpenAI provider adapter.
+
+This is the only module in the codebase that imports `openai`.
+All Azure OpenAI-specific API details are encapsulated here.
+"""
+
+from __future__ import annotations
+
+import json
+
+from explicator.ai.providers.base import AIMessage, AIProvider, AIResponse
+
+
+class AzureOpenAIProvider(AIProvider):
+    """AI provider adapter for Azure OpenAI."""
+
+    def __init__(
+        self,
+        api_key: str,
+        azure_endpoint: str,
+        deployment_name: str,
+        api_version: str = "2024-02-01",
+    ) -> None:
+        """Initialise the Azure OpenAI client with endpoint and deployment details."""
+        try:
+            from openai import AzureOpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "The 'openai' package is required for AzureOpenAIProvider. "
+                "Install it with: pip install 'explicator[azure]'"
+            ) from exc
+
+        from openai import AzureOpenAI
+
+        self._client = AzureOpenAI(
+            api_key=api_key,
+            azure_endpoint=azure_endpoint,
+            api_version=api_version,
+        )
+        self._deployment = deployment_name
+
+    def chat(
+        self,
+        messages: list[AIMessage],
+        tools: list[dict],
+        system: str | None = None,
+    ) -> AIResponse:
+        """Send a conversation to Azure OpenAI and return a normalised response."""
+        oai_messages = []
+        if system:
+            oai_messages.append({"role": "system", "content": system})
+        oai_messages.extend([self._to_oai_message(m) for m in messages])
+
+        response = self._client.chat.completions.create(
+            model=self._deployment,
+            messages=oai_messages,
+            tools=tools,  # OpenAI format matches our definitions directly
+            tool_choice="auto",
+        )
+
+        choice = response.choices[0]
+        msg = choice.message
+
+        tool_calls: list[dict] = []
+        if msg.tool_calls:
+            for tc in msg.tool_calls:
+                tool_calls.append(
+                    {
+                        "id": tc.id,
+                        "name": tc.function.name,
+                        "arguments": json.loads(tc.function.arguments),
+                    }
+                )
+
+        return AIResponse(
+            message=AIMessage(
+                role="assistant",
+                content=msg.content,
+                tool_calls=tool_calls or None,
+            ),
+            tool_calls=tool_calls,
+            finish_reason=choice.finish_reason or "stop",
+        )
+
+    @staticmethod
+    def _to_oai_message(msg: AIMessage) -> dict:
+        if msg.role == "tool":
+            return {
+                "role": "tool",
+                "tool_call_id": msg.tool_call_id,
+                "name": msg.name or "",
+                "content": msg.content or "",
+            }
+        if msg.role == "assistant" and msg.tool_calls:
+            oai_tool_calls = [
+                {
+                    "id": tc["id"],
+                    "type": "function",
+                    "function": {
+                        "name": tc["name"],
+                        "arguments": json.dumps(tc["arguments"]),
+                    },
+                }
+                for tc in msg.tool_calls
+            ]
+            return {
+                "role": "assistant",
+                "content": msg.content,
+                "tool_calls": oai_tool_calls,
+            }
+        return {"role": msg.role, "content": msg.content or ""}

explicator/ai/providers/base.py

@@ -0,0 +1,60 @@
+"""Abstract AI provider interface.
+
+All provider adapters implement this interface. The orchestration layer
+only ever speaks AIMessage / AIResponse — never provider-specific types.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AIMessage:
+    """A single message in a conversation, normalised across all providers."""
+
+    role: str  # "system" | "user" | "assistant" | "tool"
+    content: str | None = None
+    tool_calls: list[dict] | None = None  # [{id, name, arguments}]
+    tool_call_id: str | None = None  # for role="tool" responses
+    name: str | None = None  # tool name for role="tool"
+
+
+@dataclass
+class AIResponse:
+    """Normalised response from an AI provider."""
+
+    message: AIMessage
+    tool_calls: list[dict] = field(default_factory=list)  # [{id, name, arguments}]
+    finish_reason: str = "stop"
+
+
+class AIProvider(ABC):
+    """
+    Abstract base for AI provider adapters.
+
+    Each concrete implementation is responsible for translating to and from
+    its provider's wire format. The orchestration layer must never contain
+    provider-specific code.
+    """
+
+    @abstractmethod
+    def chat(
+        self,
+        messages: list[AIMessage],
+        tools: list[dict],
+        system: str | None = None,
+    ) -> AIResponse:
+        """
+        Send a conversation to the provider and return a normalised response.
+
+        Args:
+            messages: Conversation history in normalised AIMessage format.
+            tools: Tool definitions in OpenAI function-calling JSON schema format.
+            system: Optional system prompt (passed separately, not as a message).
+
+        Returns:
+            Normalised AIResponse. Check finish_reason and tool_calls to determine
+            whether the model wants to invoke a tool or has finished responding.
+        """

explicator/ai/providers/claude.py

@@ -0,0 +1,114 @@
+"""Anthropic Claude provider adapter.
+
+This is the only module in the codebase that imports `anthropic`.
+All Claude-specific API details are encapsulated here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from explicator.ai.providers.base import AIMessage, AIProvider, AIResponse
+
+
+class ClaudeProvider(AIProvider):
+    """AI provider adapter for Anthropic's Claude API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = "claude-sonnet-4-6",
+    ) -> None:
+        """Initialise the Anthropic client with the given API key and model."""
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise ImportError(
+                "The 'anthropic' package is required for ClaudeProvider. "
+                "Install it with: pip install 'explicator[claude]'"
+            ) from exc
+
+        self._client = anthropic.Anthropic(api_key=api_key)
+        self._model = model
+
+    def chat(
+        self,
+        messages: list[AIMessage],
+        tools: list[dict],
+        system: str | None = None,
+    ) -> AIResponse:
+        """Send a conversation to Claude and return a normalised response."""
+        anthropic_messages = [self._to_anthropic_message(m) for m in messages]
+        anthropic_tools = [self._to_anthropic_tool(t) for t in tools]
+
+        kwargs: dict[str, Any] = {
+            "model": self._model,
+            "max_tokens": 4096,
+            "messages": anthropic_messages,
+            "tools": anthropic_tools,
+        }
+        if system:
+            kwargs["system"] = system
+
+        response = self._client.messages.create(**kwargs)
+
+        tool_calls: list[dict] = []
+        text_content: str | None = None
+
+        for block in response.content:
+            if block.type == "tool_use":
+                tool_calls.append(
+                    {"id": block.id, "name": block.name, "arguments": block.input}
+                )
+            elif block.type == "text":
+                text_content = block.text
+
+        finish_reason = "tool_calls" if tool_calls else "stop"
+
+        return AIResponse(
+            message=AIMessage(
+                role="assistant",
+                content=text_content,
+                tool_calls=tool_calls or None,
+            ),
+            tool_calls=tool_calls,
+            finish_reason=finish_reason,
+        )
+
+    @staticmethod
+    def _to_anthropic_message(msg: AIMessage) -> dict:
+        if msg.role == "tool":
+            return {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": msg.tool_call_id,
+                        "content": msg.content or "",
+                    }
+                ],
+            }
+        if msg.role == "assistant" and msg.tool_calls:
+            content: list[dict] = []
+            if msg.content:
+                content.append({"type": "text", "text": msg.content})
+            for tc in msg.tool_calls:
+                content.append(
+                    {
+                        "type": "tool_use",
+                        "id": tc["id"],
+                        "name": tc["name"],
+                        "input": tc["arguments"],
+                    }
+                )
+            return {"role": "assistant", "content": content}
+        return {"role": msg.role, "content": msg.content or ""}
+
+    @staticmethod
+    def _to_anthropic_tool(tool: dict) -> dict:
+        fn = tool["function"]
+        return {
+            "name": fn["name"],
+            "description": fn["description"],
+            "input_schema": fn["parameters"],
+        }

explicator/ai/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool definitions in OpenAI function-calling JSON schema format."""