explicator 0.1.0__tar.gz

explicator-0.1.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["uv_build>=0.6"]
+build-backend = "uv_build"
+
+[project]
+name = "explicator"
+version = "0.1.0"
+authors = [{ name = "Tim le Poidevin", email = "lepoidevin.tim@gmail.com" }]
+description = "Provider-agnostic natural language AI interface for scenario-driven modelling"
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0.0", "click>=8.0", "python-dotenv>=1.0"]
+
+[project.optional-dependencies]
+claude = ["anthropic>=0.40.0"]
+azure = ["openai>=1.0.0"]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-mock>=3.12",
+  "mcp[cli]",
+  "pre-commit>=4.5.1",
+  "ruff>=0.15.4",
+]
+
+[project.scripts]
+explicator = "explicator.adapters.cli.main:cli"
+explicator-mcp = "explicator.adapters.mcp_server.server:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

explicator-0.1.0/src/explicator/__init__.py

@@ -0,0 +1,169 @@
+"""Explicator — provider-agnostic AI interface for scenario-driven modelling."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from explicator.adapters.data.in_memory import (
+    FunctionalScenarioRunner,
+    InMemoryModelRepository,
+)
+from explicator.application.service import ModelService
+from explicator.domain.models import (
+    InputField,
+    ModelSchema,
+    OutputField,
+    Override,
+    ScenarioComparison,
+    ScenarioDefinition,
+    ScenarioResult,
+)
+from explicator.domain.ports import ModelRepository, ScenarioRunner
+
+if TYPE_CHECKING:
+    from explicator.ai.providers.base import AIProvider
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ModelService",
+    "ModelSchema",
+    "InputField",
+    "OutputField",
+    "ScenarioDefinition",
+    "ScenarioResult",
+    "ScenarioComparison",
+    "Override",
+    "FunctionalScenarioRunner",
+    "InMemoryModelRepository",
+    "ModelRepository",
+    "ScenarioRunner",
+    "create",
+    "run_mcp",
+    "run_chat",
+    "load_service",
+]
+
+
+def create(
+    model_fn: Callable[[dict[str, Any]], dict[str, Any]],
+    base_inputs: dict[str, Any],
+    schema: ModelSchema,
+    scenarios: list[ScenarioDefinition],
+) -> ModelService:
+    """Create a ModelService from a model function, schema, and scenario list.
+
+    This is the quickest way to wrap a plain Python model function.
+    For custom storage or execution backends, instantiate ModelService directly
+    using your own ModelRepository and ScenarioRunner implementations.
+
+    Example::
+
+        service = explicator.create(
+            model_fn=my_model,
+            base_inputs={"rate": 5.0},
+            schema=my_schema,
+            scenarios=my_scenarios,
+        )
+    """
+    repo = InMemoryModelRepository(schema=schema, scenarios=scenarios)
+    runner = FunctionalScenarioRunner(model_fn=model_fn, base_inputs=base_inputs)
+    return ModelService(runner=runner, repository=repo)
+
+
+def run_mcp(service: ModelService) -> None:
+    """Start the MCP server backed by the given service.
+
+    Intended as the entry point in your run script::
+
+        if __name__ == "__main__":
+            explicator.run_mcp(service)
+    """
+    from explicator.adapters.mcp_server.server import mcp, set_service
+
+    set_service(service)
+    mcp.run()
+
+
+def run_chat(
+    service: ModelService,
+    *,
+    question: str | None = None,
+) -> None:
+    """Start an interactive chat REPL, or answer a single question.
+
+    Requires an AI provider to be configured (e.g. ANTHROPIC_API_KEY).
+
+    Args:
+        service: The ModelService to query.
+        question: If provided, answer this single question and return.
+                  If omitted, start an interactive REPL.
+    """
+    from explicator.ai.dispatcher import ToolDispatcher
+    from explicator.ai.providers.base import AIMessage
+    from explicator.ai.tools.definitions import TOOL_DEFINITIONS
+    from explicator.config import build_provider
+
+    provider = build_provider()
+    dispatcher = ToolDispatcher(service)
+
+    def _turn(messages: list[AIMessage]) -> str:
+        while True:
+            response = provider.chat(messages, tools=TOOL_DEFINITIONS)
+            messages.append(response.message)
+            if not response.tool_calls:
+                return response.message.content or ""
+            for tc in response.tool_calls:
+                result = dispatcher.dispatch(tc["name"], tc["arguments"])
+                messages.append(
+                    AIMessage(
+                        role="tool",
+                        content=json.dumps(result),
+                        tool_call_id=tc["id"],
+                        name=tc["name"],
+                    )
+                )
+
+    if question:
+        print(_turn([AIMessage(role="user", content=question)]))
+        return
+
+    print("Explicator chat — type 'exit' or Ctrl+D to quit.\n")
+    messages: list[AIMessage] = []
+    while True:
+        try:
+            user_input = input("You> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if user_input.lower() in {"exit", "quit"}:
+            break
+        messages.append(AIMessage(role="user", content=user_input))
+        print(f"\n{_turn(messages)}\n")
+
+
+def load_service(path: str) -> ModelService:
+    """Load a ModelService from a dotted import path.
+
+    The path format is ``'module.path:attribute'``, where the attribute is
+    either a ``ModelService`` instance or a zero-argument callable that returns
+    one.
+
+    Example::
+
+        service = explicator.load_service("myapp.model:build_service")
+        service = explicator.load_service("myapp.model:service")
+    """
+    import importlib
+
+    if ":" not in path:
+        raise ValueError(
+            f"Service path must be 'module:attribute', got '{path}'. "
+            "Example: 'myapp.model:build_service'"
+        )
+    module_path, attr = path.rsplit(":", 1)
+    module = importlib.import_module(module_path)
+    obj = getattr(module, attr)
+    return obj() if callable(obj) else obj

explicator-0.1.0/src/explicator/adapters/__init__.py

@@ -0,0 +1 @@
+"""Explicator adapters — CLI, MCP server, and data implementations."""

explicator-0.1.0/src/explicator/adapters/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI adapter for Explicator."""

explicator-0.1.0/src/explicator/adapters/cli/main.py

@@ -0,0 +1,158 @@
+"""CLI adapter for Explicator.
+
+Provides a command-line interface for running scenarios and chatting with an AI.
+No business logic lives here — this is a thin translation layer.
+
+Usage::
+
+    explicator --service myapp.model:build_service run base_case
+    explicator --service myapp.model:build_service chat
+    EXPLICATOR_SERVICE=myapp.model:service explicator compare base stress
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+import explicator
+from explicator.application.service import ModelService
+
+
+def _load_service(path: str | None) -> ModelService:
+    """Load the service from a path, or fall back to stub wiring."""
+    if path:
+        try:
+            return explicator.load_service(path)
+        except Exception as exc:
+            raise click.UsageError(
+                f"Could not load service from '{path}': {exc}"
+            ) from exc
+
+    from explicator.adapters.data.in_memory import _build_stub_wiring
+
+    repository, runner = _build_stub_wiring()
+    return ModelService(runner=runner, repository=repository)
+
+
+@click.group()
+@click.option(
+    "--service",
+    "service_path",
+    envvar="EXPLICATOR_SERVICE",
+    default=None,
+    help="Service path: 'module:attribute'. Also reads EXPLICATOR_SERVICE env var.",
+)
+@click.pass_context
+def cli(ctx: click.Context, service_path: str | None) -> None:
+    """Explicator — natural language AI interface for scenario-driven modelling."""
+    ctx.ensure_object(dict)
+    ctx.obj["service"] = _load_service(service_path)
+
+
+@cli.command("scenarios")
+@click.pass_context
+def list_scenarios(ctx: click.Context) -> None:
+    """List all available scenarios."""
+    service: ModelService = ctx.obj["service"]
+    for s in service.get_available_scenarios():
+        click.echo(f"\n{s.name}")
+        click.echo(f"  {s.description}")
+        click.echo(f"  Stress rationale: {s.stress_rationale}")
+
+
+@cli.command("run")
+@click.argument("scenario_name")
+@click.option(
+    "--override",
+    "-o",
+    multiple=True,
+    metavar="FIELD=VALUE",
+    help="Override an input field for this run, e.g. -o yield_10y=5.0",
+)
+@click.pass_context
+def run_scenario(
+    ctx: click.Context, scenario_name: str, override: tuple[str, ...]
+) -> None:
+    """Run a named scenario and print results as JSON."""
+    service: ModelService = ctx.obj["service"]
+
+    overrides: dict = {}
+    for o in override:
+        if "=" not in o:
+            click.echo(f"Invalid override format '{o}'. Use FIELD=VALUE.", err=True)
+            sys.exit(1)
+        field, value = o.split("=", 1)
+        try:
+            overrides[field.strip()] = float(value.strip())
+        except ValueError:
+            click.echo(f"Override value must be numeric: '{value}'", err=True)
+            sys.exit(1)
+
+    result = service.run_scenario(scenario_name, overrides=overrides or None)
+    click.echo(json.dumps(result.to_dict(), indent=2))
+
+
+@cli.command("compare")
+@click.argument("scenario_a")
+@click.argument("scenario_b")
+@click.option(
+    "--metric", "-m", multiple=True, help="Restrict comparison to this output field"
+)
+@click.pass_context
+def compare(
+    ctx: click.Context,
+    scenario_a: str,
+    scenario_b: str,
+    metric: tuple[str, ...],
+) -> None:
+    """Compare two scenarios side by side."""
+    service: ModelService = ctx.obj["service"]
+    comparison = service.compare_scenarios(
+        scenario_a,
+        scenario_b,
+        metrics=list(metric) if metric else None,
+    )
+    click.echo(json.dumps(comparison.to_dict(), indent=2))
+
+
+@cli.command("schema")
+@click.pass_context
+def show_schema(ctx: click.Context) -> None:
+    """Print the full model schema as JSON."""
+    service: ModelService = ctx.obj["service"]
+    click.echo(json.dumps(service.get_model_schema().to_dict(), indent=2))
+
+
+@cli.command("override")
+@click.argument("source")
+@click.argument("field")
+@click.argument("value", type=float)
+@click.pass_context
+def set_override(ctx: click.Context, source: str, field: str, value: float) -> None:
+    """Apply a persistent session override to an input field."""
+    service: ModelService = ctx.obj["service"]
+    click.echo(service.override_input(source, field, value))
+
+
+@cli.command("reset")
+@click.pass_context
+def reset_overrides(ctx: click.Context) -> None:
+    """Clear all active overrides and restore model defaults."""
+    service: ModelService = ctx.obj["service"]
+    click.echo(service.reset_overrides())
+
+
+@cli.command("chat")
+@click.argument("question", required=False)
+@click.pass_context
+def chat(ctx: click.Context, question: str | None) -> None:
+    """Chat with an AI about the model. Omit QUESTION for interactive mode."""
+    service: ModelService = ctx.obj["service"]
+    try:
+        explicator.run_chat(service, question=question)
+    except Exception as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)

explicator-0.1.0/src/explicator/adapters/data/__init__.py

@@ -0,0 +1 @@
+"""In-memory data adapters for Explicator."""

explicator-0.1.0/src/explicator/adapters/data/in_memory.py

@@ -0,0 +1,134 @@
+"""In-memory implementations of the domain ports.
+
+Useful for testing and for wiring up demo/example models.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from explicator.domain.models import (
+    InputField,
+    ModelSchema,
+    OutputField,
+    ScenarioDefinition,
+    ScenarioResult,
+)
+from explicator.domain.ports import ModelRepository, ScenarioRunner
+
+
+class InMemoryModelRepository(ModelRepository):
+    """
+    A fully in-memory ModelRepository.
+
+    Construct with a ModelSchema and list of ScenarioDefinitions.
+    Suitable for testing and for wrapping functional demo models.
+    """
+
+    def __init__(
+        self,
+        schema: ModelSchema,
+        scenarios: list[ScenarioDefinition],
+    ) -> None:
+        """Initialise with a schema and list of scenario definitions."""
+        self._schema = schema
+        self._scenarios = scenarios
+
+    def get_scenarios(self) -> list[ScenarioDefinition]:
+        """Return all available scenario definitions."""
+        return list(self._scenarios)
+
+    def get_schema(self) -> ModelSchema:
+        """Return the full model schema."""
+        return self._schema
+
+    def get_inputs(self) -> list[InputField]:
+        """Return current state of all model inputs."""
+        return list(self._schema.inputs)
+
+
+class FunctionalScenarioRunner(ScenarioRunner):
+    """
+    A ScenarioRunner that delegates to a user-supplied callable.
+
+    The callable receives the merged inputs dict and returns an outputs dict.
+    This lets you wrap any pure Python model function without subclassing.
+
+    Example::
+
+        runner = FunctionalScenarioRunner(
+            model_fn=my_model,
+            base_inputs={"rate": 5.0, "spread": 1.2},
+        )
+    """
+
+    def __init__(
+        self,
+        model_fn: Callable[[dict[str, Any]], dict[str, Any]],
+        base_inputs: dict[str, Any],
+    ) -> None:
+        """Initialise with a model callable and its base input values."""
+        self._model_fn = model_fn
+        self._base_inputs = base_inputs
+
+    def run(
+        self,
+        scenario: ScenarioDefinition,
+        extra_overrides: dict[str, Any],
+    ) -> ScenarioResult:
+        """Run a scenario, merging its overrides and any extra overrides over base."""
+        inputs = dict(self._base_inputs)
+        inputs.update(scenario.overrides)
+        inputs.update(extra_overrides)
+
+        outputs = self._model_fn(inputs)
+
+        return ScenarioResult(
+            scenario_name=scenario.name,
+            inputs_used=inputs,
+            outputs=outputs,
+            overrides_applied={**scenario.overrides, **extra_overrides},
+            run_at=datetime.now(UTC).isoformat(),
+        )
+
+
+def _build_stub_wiring() -> tuple[InMemoryModelRepository, FunctionalScenarioRunner]:
+    """Build fallback stub wiring used when no real model is configured.
+
+    Returns a minimal repository and runner so the server starts without error.
+    Replace this in your own entry point with real implementations.
+    """
+    schema = ModelSchema(
+        name="Stub Model",
+        description=(
+            "No model has been configured. "
+            "Wire a real ModelRepository and ScenarioRunner in your entry point."
+        ),
+        inputs=[],
+        outputs=[
+            OutputField(
+                name="stub",
+                description="Placeholder output.",
+                units="",
+                interpretation="Replace this model with a real implementation.",
+            )
+        ],
+        assumptions=["This is a stub."],
+        caveats=["Wire a real model before use."],
+    )
+    scenarios = [
+        ScenarioDefinition(
+            name="base",
+            description="Stub base case.",
+            stress_rationale="Stub — no real stress applied.",
+            overrides={},
+        )
+    ]
+    repo = InMemoryModelRepository(schema=schema, scenarios=scenarios)
+    runner = FunctionalScenarioRunner(
+        model_fn=lambda inputs: {"stub": True, "message": "No model configured."},
+        base_inputs={},
+    )
+    return repo, runner

explicator-0.1.0/src/explicator/adapters/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server adapter for Explicator."""

explicator-0.1.0/src/explicator/adapters/mcp_server/__main__.py

@@ -0,0 +1,29 @@
+"""Entry point: python -m explicator.adapters.mcp_server [module:attribute]."""
+
+import sys
+
+import explicator
+
+
+def main() -> None:
+    """Start the MCP server.
+
+    Accepts an optional service path argument::
+
+        python -m explicator.adapters.mcp_server myapp.model:build_service
+
+    Falls back to stub wiring if no path is given.
+    """
+    if len(sys.argv) > 1:
+        service = explicator.load_service(sys.argv[1])
+    else:
+        from explicator.adapters.data.in_memory import _build_stub_wiring
+        from explicator.application.service import ModelService
+
+        repository, runner = _build_stub_wiring()
+        service = ModelService(runner=runner, repository=repository)
+
+    explicator.run_mcp(service)
+
+
+main()