nlalpha-backtest 0.8.0__py3-none-any.whl

nlalpha_backtest/__init__.py

@@ -0,0 +1,66 @@
+"""nlalpha-backtest: Backtest execution MCP tool."""
+
+from __future__ import annotations
+
+from importlib.metadata import version as _distribution_version
+
+from typing import Callable
+
+from nlalpha.core.backtest import BacktestResult, BatchBacktestInput
+from nlalpha.core.contracts.market import Bar
+from nlalpha_backtest.execution import BacktestExecutor, run_batch_strategy_code
+
+__version__ = _distribution_version("nlalpha-backtest")
+
+__all__ = [
+    "run",
+    "run_batch",
+    "run_batch_strategy_code",
+    "BacktestExecutor",
+]
+
+
+async def run(
+    job_id: str,
+    strategy,
+    data: list[Bar],
+    execution_config: dict | None = None,
+    capital_config: dict | None = None,
+    contract_config: dict | None = None,
+    progress_callback: Callable[[float, str], None] | None = None,
+    engine: str | None = None,
+) -> BacktestResult:
+    """Execute a backtest. Main entry point for backtest execution."""
+    service = BacktestExecutor()
+    return await service.run(
+        job_id=job_id,
+        strategy=strategy,
+        data=data,
+        execution_config=execution_config,
+        capital_config=capital_config,
+        contract_config=contract_config,
+        progress_callback=progress_callback,
+        engine=engine,
+    )
+
+
+async def run_batch(
+    job_id: str,
+    inputs: BatchBacktestInput,
+    execution_config: dict | None = None,
+    capital_config: dict | None = None,
+    contract_config: dict | None = None,
+    progress_callback: Callable[[float, str], None] | None = None,
+    engine: str | None = None,
+) -> BacktestResult:
+    """Execute one batch-signals run using an explicitly versioned input."""
+    service = BacktestExecutor()
+    return await service.run_batch(
+        job_id=job_id,
+        inputs=inputs,
+        execution_config=execution_config,
+        capital_config=capital_config,
+        contract_config=contract_config,
+        progress_callback=progress_callback,
+        engine=engine,
+    )

nlalpha_backtest/context.py

@@ -0,0 +1,5 @@
+"""Compatibility import for the shared event-driven backtest context."""
+
+from nlalpha.core.backtest import BacktestContext as BacktestContext
+
+__all__ = ["BacktestContext"]

nlalpha_backtest/data.py

@@ -0,0 +1,33 @@
+"""Backtest data models: MarketContext and BacktestResult."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from nlalpha.core.contracts.market import Bar, Position
+from nlalpha.core.backtest import BacktestResult as BacktestResult
+
+@dataclass
+class MarketContext:
+    """Strategy input: a stable, branch-free data structure."""
+
+    bars: dict[str, Bar] = field(default_factory=dict)
+    series: dict[str, dict[str, list[float]]] = field(default_factory=dict)
+    positions: dict[str, Position] = field(default_factory=dict)
+    equity: float = 0.0
+    cash: float = 0.0
+    timestamp: datetime | None = None
+    step: int = 0
+
+    def get(self, symbol: str, field: str = "close") -> float | None:
+        """Get current bar field for a symbol."""
+        bar = self.bars.get(symbol)
+        return getattr(bar, field, None) if bar else None
+
+    def get_series(self, symbol: str, field: str = "close") -> list[float]:
+        """Get historical series for a symbol."""
+        return self.series.get(symbol, {}).get(field, [])
+
+
+__all__ = ["BacktestResult", "MarketContext"]

nlalpha_backtest/engine.py

@@ -0,0 +1,254 @@
+"""Engine registry and compatibility imports for shared backtest contracts."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nlalpha_backtest.execution.backend import EngineCapability, EngineDiagnostic, ExecutionCapabilities
+
+from nlalpha.core.backtest import (
+    BATCH_SIGNALS,
+    EVENT_DRIVEN,
+    BacktestContext as BacktestContext,
+    BacktestEngineProvider as BacktestEngineProvider,
+    BacktestResult as BacktestResult,
+    EngineManifest as EngineManifest,
+)
+from nlalpha.core.errors import StrategyRuntimeError
+
+logger = logging.getLogger("nlalpha_backtest.engine")
+
+
+@dataclass(frozen=True)
+class _EngineRecord:
+    """One cached provider load and its manifest, guidance, or failure diagnostic."""
+
+    engine_id: str | None
+    provider: BacktestEngineProvider | None
+    manifest: EngineManifest | None
+    capability: EngineCapability | None
+    diagnostic: EngineDiagnostic | None
+
+
+class EngineRegistry:
+    """Discover each installed engine once and select only verified providers."""
+
+    _records: list[_EngineRecord] = []
+    _default_order: list[str] = ["nautilus", "vector"]
+    _DISCOVERY_DONE = False
+    _lock = threading.RLock()
+
+    @classmethod
+    def register(cls, name: str, provider: BacktestEngineProvider) -> None:
+        """Register an explicit provider after validating its identity and guidance."""
+        record = cls._provider_record(name, provider, None, None, f"registered:{name}")
+        with cls._lock:
+            cls._append(record)
+
+    @classmethod
+    def _provider_record(cls, name, provider, package, version, entry_point):
+        """Cache one provider manifest and its exact guidance after identity validation."""
+        from nlalpha_backtest.execution.backend import EngineCapability, EngineDiagnostic
+
+        manifest = provider.manifest()
+        if not isinstance(manifest, EngineManifest) or manifest.engine_id != name:
+            raise ValueError("provider manifest engine_id must match the registered engine identity")
+        if not manifest.available:
+            diagnostic = EngineDiagnostic("unavailable", manifest.unavailable_reason or "provider reports unavailable",
+                                          name, entry_point, package, version)
+            return _EngineRecord(name, provider, manifest, None, diagnostic)
+        confession = provider.confess()
+        capability = EngineCapability(manifest, package, version, confession, entry_point)
+        return _EngineRecord(name, provider, manifest, capability, None)
+
+    @classmethod
+    def _append(cls, record: _EngineRecord) -> None:
+        """Retain a load record and disable every conflicting engine identity."""
+        from nlalpha_backtest.execution.backend import EngineDiagnostic
+
+        duplicates = [index for index, item in enumerate(cls._records)
+                      if record.engine_id is not None and item.engine_id == record.engine_id]
+        if duplicates:
+            reason = f"duplicate engine identity: {record.engine_id}"
+            for index in duplicates:
+                prior = cls._records[index]
+                origin = prior.capability or prior.diagnostic
+                diagnostic = EngineDiagnostic("load_failed", reason, record.engine_id,
+                                              origin.entry_point, origin.package, origin.version)
+                cls._records[index] = replace(prior, capability=None, diagnostic=diagnostic)
+            origin = record.capability or record.diagnostic
+            record = replace(record, capability=None, diagnostic=EngineDiagnostic(
+                "load_failed", reason, record.engine_id, origin.entry_point, origin.package, origin.version))
+        cls._records.append(record)
+        if record.diagnostic:
+            logger.warning("engine unavailable | engine_id=%s entry_point=%s package=%s status=%s reason=%s",
+                           record.engine_id, record.diagnostic.entry_point, record.diagnostic.package,
+                           record.diagnostic.status, record.diagnostic.reason)
+
+    @classmethod
+    def _record(cls, name: str) -> _EngineRecord | None:
+        """Find the cached load record for an engine identity."""
+        return next((item for item in cls._records if item.engine_id == name), None)
+
+    @classmethod
+    def get(cls, name: str) -> BacktestEngineProvider:
+        """Return a provider whose cached discovery record is available."""
+        record = cls._record(name)
+        if record is None or record.capability is None:
+            raise KeyError(f"Engine {name!r} is not available. Available: {[item.engine_id for item in cls.list_available()]}")
+        return record.provider
+
+    @classmethod
+    def get_default(cls, *, runtime_mode: str = EVENT_DRIVEN, input_schema: str | None = None) -> BacktestEngineProvider:
+        """Select a verified compatible provider in the explicit preference order."""
+        cls._validate_request(runtime_mode, input_schema)
+        manifests = []
+        for name in dict.fromkeys(cls._default_order):
+            record = cls._record(name)
+            if record is None:
+                continue
+            if record.capability is not None and record.manifest.supports(runtime_mode, input_schema):
+                return record.provider
+            if record.manifest is not None:
+                manifests.append(record.manifest.to_dict())
+        raise StrategyRuntimeError(
+            f"No available backtest engine supports runtime mode {runtime_mode!r} with input schema {input_schema!r}.",
+            details={"reason": "no_compatible_engine", "runtime_mode": runtime_mode,
+                     "input_schema": input_schema, "engines": manifests},
+        )
+
+    @classmethod
+    def resolve(cls, engine_id: str | None = None, *, runtime_mode: str = EVENT_DRIVEN,
+                input_schema: str | None = None) -> BacktestEngineProvider:
+        """Resolve an explicit verified provider or apply the configured preference order."""
+        cls._validate_request(runtime_mode, input_schema)
+        if engine_id is None:
+            return cls.get_default(runtime_mode=runtime_mode, input_schema=input_schema)
+        details = {"engine_id": engine_id, "runtime_mode": runtime_mode, "input_schema": input_schema}
+        record = cls._record(engine_id)
+        if record is None:
+            raise StrategyRuntimeError(f"Engine {engine_id!r} is not registered.", details={
+                **details, "reason": "engine_not_registered", "registered_engines": list(dict.fromkeys(
+                    item.engine_id for item in cls._records if item.engine_id is not None))})
+        if record.manifest is not None:
+            details["manifest"] = record.manifest.to_dict()
+        if record.capability is None:
+            raise StrategyRuntimeError(f"Engine {engine_id!r} is unavailable: {record.diagnostic.reason}",
+                                       details={**details, "reason": "engine_unavailable",
+                                                "diagnostic": record.diagnostic.to_dict()})
+        if not record.manifest.supports(runtime_mode, input_schema):
+            raise StrategyRuntimeError(
+                f"Engine {engine_id!r} does not support runtime mode {runtime_mode!r} with input schema {input_schema!r}.",
+                details={**details, "reason": "engine_incompatible"})
+        return record.provider
+
+    @staticmethod
+    def _validate_request(runtime_mode: str, input_schema: str | None) -> None:
+        """Reject invalid runtime and input-schema combinations before selection."""
+        details = {"runtime_mode": runtime_mode, "input_schema": input_schema}
+        if runtime_mode not in (EVENT_DRIVEN, BATCH_SIGNALS):
+            raise StrategyRuntimeError(
+                f"Unknown backtest runtime mode: {runtime_mode!r}.",
+                details={
+                    **details,
+                    "reason": "invalid_runtime_mode",
+                    "supported_runtime_modes": [EVENT_DRIVEN, BATCH_SIGNALS],
+                },
+            )
+        if runtime_mode == BATCH_SIGNALS and (
+            not isinstance(input_schema, str) or not input_schema.strip()
+        ):
+            raise StrategyRuntimeError(
+                "Batch signal execution requires a non-empty input schema.",
+                details={**details, "reason": "input_schema_required"},
+            )
+        if runtime_mode == EVENT_DRIVEN and input_schema is not None:
+            raise StrategyRuntimeError(
+                "Event-driven execution does not accept an input schema.",
+                details={**details, "reason": "unexpected_input_schema"},
+            )
+
+    @classmethod
+    def list_available(cls) -> list[EngineManifest]:
+        """List manifests from the same verified records used for provider selection."""
+        return [record.manifest for record in cls._records if record.capability is not None]
+
+    @classmethod
+    def list_all(cls) -> list[EngineManifest]:
+        """List every successfully read manifest with its effective availability."""
+        return [record.manifest if record.capability is not None else replace(
+            record.manifest, available=False, unavailable_reason=record.diagnostic.reason)
+            for record in cls._records if record.manifest is not None]
+
+    @classmethod
+    def capabilities(cls) -> ExecutionCapabilities:
+        """Return the installed engine directory and retained load diagnostics."""
+        from nlalpha_backtest.execution.backend import ExecutionCapabilities
+
+        cls.discover_engines()
+        return ExecutionCapabilities(
+            tuple(record.capability for record in cls._records if record.capability is not None),
+            tuple(record.diagnostic for record in cls._records if record.diagnostic is not None),
+            {"kind": "local"},
+        )
+
+    @classmethod
+    def discover_engines(cls) -> None:
+        """Load installed entry points once while retaining each plugin's failure evidence."""
+        from importlib.metadata import entry_points
+        from nlalpha_backtest.execution.backend import EngineDiagnostic
+
+        with cls._lock:
+            if cls._DISCOVERY_DONE:
+                return
+            entries = list(entry_points(group="nlalpha.engines"))
+            for entry in sorted(entries, key=lambda item: (item.name, item.value)):
+                package = version = engine_id = None
+                source = f"{entry.name}={entry.value}"
+                manifest = None
+                provider = None
+                try:
+                    package = entry.dist.metadata["Name"]
+                    version = entry.dist.version
+                    plugin = entry.load()()
+                    engine_id = plugin.engine_id
+                    if not isinstance(engine_id, str) or not engine_id.strip() or engine_id != engine_id.strip():
+                        raise ValueError("plugin engine_id must be a nonempty trimmed string")
+                    available = plugin.is_available()
+                    if not isinstance(available, bool):
+                        raise TypeError("plugin is_available must return a boolean")
+                    declared = plugin.get_manifest()
+                    if not isinstance(declared, dict):
+                        raise TypeError("plugin get_manifest must return a manifest object")
+                    fields = {"engine_id", "engine_name", "available", "unavailable_reason", "runtime_modes", "input_schemas"}
+                    if not fields.issubset(declared):
+                        raise ValueError("plugin get_manifest is missing manifest fields")
+                    manifest = EngineManifest(**{name: declared[name] for name in fields})
+                    if manifest.engine_id != engine_id:
+                        raise ValueError("plugin manifest engine_id does not match plugin identity")
+                    if not available or not manifest.available:
+                        diagnostic = EngineDiagnostic("unavailable", manifest.unavailable_reason or "plugin reports unavailable",
+                                                      engine_id, source, package, version)
+                        record = _EngineRecord(engine_id, None, manifest, None, diagnostic)
+                    else:
+                        provider = plugin.get_provider()
+                        record = cls._provider_record(engine_id, provider, package, version, source)
+                        if record.manifest != manifest:
+                            raise ValueError("plugin and provider manifests disagree")
+                except Exception as exc:
+                    if not isinstance(engine_id, str) or not engine_id.strip() or engine_id != engine_id.strip():
+                        engine_id = None
+                    if (not isinstance(package, str) or not package.strip() or package != package.strip()
+                            or not isinstance(version, str) or not version.strip() or version != version.strip()):
+                        package = version = None
+                    diagnostic = EngineDiagnostic("load_failed", f"{type(exc).__name__}: {exc}".strip(),
+                                                  engine_id, source, package, version)
+                    record = _EngineRecord(engine_id, provider, manifest, None, diagnostic)
+                cls._append(record)
+            cls._DISCOVERY_DONE = True
+            logger.info("engine discovery completed | available=%d diagnostics=%d",
+                        len(cls.list_available()), sum(item.diagnostic is not None for item in cls._records))

nlalpha_backtest/execution/__init__.py

@@ -0,0 +1,50 @@
+"""Backtest execution contracts, local backend, runner, and runtime."""
+
+from nlalpha_backtest.execution.backtest_executor import BacktestExecutor
+from nlalpha_backtest.execution.backend import (
+    BatchBacktestRequest,
+    BacktestRequest,
+    CancelOutcome,
+    CancelStatus,
+    ExecutionBackend,
+    ExecutionCapabilities,
+    EngineCapability,
+    EngineDiagnostic,
+    ExecutionCancelled,
+    ExecutionError,
+    ExecutionFailed,
+    ExecutionObservation,
+    ExecutionOutcome,
+    ExecutionRequest,
+    ExecutionTimedOut,
+    OperationStatus,
+)
+from nlalpha_backtest.execution.local_executor import LocalExecutor
+from nlalpha_backtest.execution.runner import BacktestRunner
+from nlalpha_backtest.execution.runtime import run_batch_strategy_code, run_strategy_code
+from nlalpha_backtest.execution.validation import validate_runtime_mode
+
+__all__ = [
+    "BacktestExecutor",
+    "BacktestRequest",
+    "BatchBacktestRequest",
+    "BacktestRunner",
+    "CancelOutcome",
+    "CancelStatus",
+    "ExecutionBackend",
+    "ExecutionCapabilities",
+    "EngineCapability",
+    "EngineDiagnostic",
+    "ExecutionCancelled",
+    "ExecutionError",
+    "ExecutionFailed",
+    "ExecutionObservation",
+    "ExecutionOutcome",
+    "ExecutionRequest",
+    "ExecutionTimedOut",
+    "LocalExecutor",
+    "OperationStatus",
+    "run_batch_strategy_code",
+    "run_strategy_code",
+    "validate_runtime_mode",
+]