matrixai-core 1.0.0__py3-none-any.whl

matrixai/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Roberto Llamosas Conde
+
+"""MatrixAI MVP package."""
+
+__version__ = "1.0.0"

matrixai/__main__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Roberto Llamosas Conde
+
+from matrixai.cli import main
+
+raise SystemExit(main())

matrixai/actions/__init__.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Roberto Llamosas Conde
+
+from matrixai.actions.schema import (
+    ActionContractSpec,
+    RollbackSpec,
+    RateLimitSpec,
+    SandboxLimitsSpec,
+    CAPABILITIES,
+    HIGH_RISK_CAPABILITIES,
+    MUTATING_CAPABILITIES,
+)
+from matrixai.actions.parser import MxactParseError, parse_mxact
+from matrixai.actions.registry import (
+    CapabilityRegistry,
+    REQUIRED_SCOPE_FIELDS,
+    ScopeValidationResult,
+    registry,
+)
+from matrixai.actions.dryrun import (
+    DryRunReport,
+    DryRunSimulator,
+    RateTracker,
+)
+from matrixai.actions.executor import (
+    ActionExecutor,
+    ActionExecutorError,
+    ActionResult,
+    ExecutionContext,
+)
+from matrixai.actions.sandbox import (
+    SandboxedActionExecutor,
+    SandboxedExecutorError,
+    SandboxParams,
+    SandboxResult,
+)
+from matrixai.actions.trace import (
+    ActionTrace,
+    build_action_trace,
+    sign_action_trace,
+    verify_action_trace,
+)
+from matrixai.actions.rollback import (
+    RollbackManager,
+    RollbackResult,
+    RollbackError,
+)
+from matrixai.actions.approval import (
+    ApprovalStore,
+    ApprovalError,
+    HumanApprovalGate,
+    PendingExecution,
+)
+from matrixai.actions.contract import (
+    ActionContractValidationResult,
+    canonical_dict,
+    check_signing_key_available,
+    compute_action_contract_hash,
+    require_signing_key,
+    validate_action_contract,
+)
+
+__all__ = [
+    "ActionContractSpec",
+    "ActionContractValidationResult",
+    "MxactParseError",
+    "RollbackSpec",
+    "RateLimitSpec",
+    "SandboxLimitsSpec",
+    "CAPABILITIES",
+    "HIGH_RISK_CAPABILITIES",
+    "MUTATING_CAPABILITIES",
+    "canonical_dict",
+    "check_signing_key_available",
+    "compute_action_contract_hash",
+    "parse_mxact",
+    "require_signing_key",
+    "validate_action_contract",
+    "CapabilityRegistry",
+    "REQUIRED_SCOPE_FIELDS",
+    "ScopeValidationResult",
+    "registry",
+    "DryRunReport",
+    "DryRunSimulator",
+    "RateTracker",
+    "ActionExecutor",
+    "ActionExecutorError",
+    "ActionResult",
+    "ExecutionContext",
+    "SandboxedActionExecutor",
+    "SandboxedExecutorError",
+    "SandboxParams",
+    "SandboxResult",
+    "ActionTrace",
+    "build_action_trace",
+    "sign_action_trace",
+    "verify_action_trace",
+    "RollbackManager",
+    "RollbackResult",
+    "RollbackError",
+    "ApprovalStore",
+    "ApprovalError",
+    "HumanApprovalGate",
+    "PendingExecution",
+]

matrixai/actions/approval.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Roberto Llamosas Conde
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
+
+from matrixai.actions.dryrun import _input_hash as _hash_input
+
+if TYPE_CHECKING:
+    from matrixai.actions.executor import ExecutionContext
+
+_DEFAULT_TTL_SECONDS = 300  # 5 minutes
+
+
+@dataclass
+class PendingExecution:
+    execution_id: str
+    contract_name: str
+    capability: str
+    input_data: dict
+    input_hash: str           # hash of input_data at submit time
+    model_hash: str
+    parameter_set_id: str
+    action_contract_hash: str
+    created_at: str          # ISO8601 UTC
+    expires_at: str          # ISO8601 UTC
+    status: str = "pending"  # pending | approved | rejected | expired
+    channel: str | None = None
+    decided_at: str | None = None
+    decided_by: str | None = None
+
+    def is_expired(self, now: datetime | None = None) -> bool:
+        ts = now or datetime.now(tz=timezone.utc)
+        return ts >= datetime.fromisoformat(self.expires_at)
+
+    def is_approved(self, now: datetime | None = None) -> bool:
+        return self.status == "approved" and not self.is_expired(now)
+
+
+class ApprovalStore:
+    """In-memory store for PendingExecution records."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, PendingExecution] = {}
+
+    def submit(
+        self,
+        context: "ExecutionContext",
+        *,
+        ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+        channel: str | None = None,
+        now: datetime | None = None,
+    ) -> PendingExecution:
+        ts = now or datetime.now(tz=timezone.utc)
+        execution_id = str(uuid.uuid4())
+        pending = PendingExecution(
+            execution_id=execution_id,
+            contract_name=context.contract.name,
+            capability=context.contract.capability,
+            input_data=context.input_data,
+            input_hash=context.dry_run_report.input_hash,
+            model_hash=context.model_hash,
+            parameter_set_id=context.parameter_set_id,
+            action_contract_hash=context.dry_run_report.action_contract_hash,
+            created_at=ts.isoformat(),
+            expires_at=(ts + timedelta(seconds=ttl_seconds)).isoformat(),
+            status="pending",
+            channel=channel,
+        )
+        self._store[execution_id] = pending
+        return pending
+
+    def get(self, execution_id: str) -> PendingExecution | None:
+        return self._store.get(execution_id)
+
+    def approve(
+        self,
+        execution_id: str,
+        *,
+        decided_by: str | None = None,
+        now: datetime | None = None,
+    ) -> PendingExecution:
+        pending = self._get_or_raise(execution_id)
+        self._check_not_decided(pending)
+        if pending.is_expired(now):
+            pending.status = "expired"
+            raise ApprovalError(f"Execution {execution_id!r} has expired")
+        ts = now or datetime.now(tz=timezone.utc)
+        pending.status = "approved"
+        pending.decided_at = ts.isoformat()
+        pending.decided_by = decided_by
+        return pending
+
+    def reject(
+        self,
+        execution_id: str,
+        *,
+        decided_by: str | None = None,
+        now: datetime | None = None,
+    ) -> PendingExecution:
+        pending = self._get_or_raise(execution_id)
+        self._check_not_decided(pending)
+        ts = now or datetime.now(tz=timezone.utc)
+        pending.status = "rejected"
+        pending.decided_at = ts.isoformat()
+        pending.decided_by = decided_by
+        return pending
+
+    def list_pending(self, now: datetime | None = None) -> list[PendingExecution]:
+        ts = now or datetime.now(tz=timezone.utc)
+        result = []
+        for p in self._store.values():
+            if p.status == "pending":
+                if p.is_expired(ts):
+                    p.status = "expired"
+                else:
+                    result.append(p)
+        return result
+
+    def _get_or_raise(self, execution_id: str) -> PendingExecution:
+        p = self._store.get(execution_id)
+        if p is None:
+            raise ApprovalError(f"No pending execution found with id {execution_id!r}")
+        return p
+
+    @staticmethod
+    def _check_not_decided(pending: PendingExecution) -> None:
+        if pending.status in ("approved", "rejected"):
+            raise ApprovalError(
+                f"Execution {pending.execution_id!r} is already {pending.status}"
+            )
+
+
+class ApprovalError(Exception):
+    pass
+
+
+class HumanApprovalGate:
+    """Check whether a context requires human approval and whether it has been granted."""
+
+    def __init__(self, store: ApprovalStore) -> None:
+        self._store = store
+
+    def requires_approval(self, context: "ExecutionContext") -> bool:
+        return context.contract.human_approval
+
+    def find_approved(
+        self,
+        context: "ExecutionContext",
+        now: datetime | None = None,
+    ) -> PendingExecution | None:
+        """Return the first approved, non-expired PendingExecution matching this context."""
+        for pending in self._store._store.values():
+            if (
+                pending.action_contract_hash == context.dry_run_report.action_contract_hash
+                and pending.input_hash == context.dry_run_report.input_hash
+                and pending.model_hash == context.model_hash
+                and pending.parameter_set_id == context.parameter_set_id
+                and pending.is_approved(now)
+            ):
+                return pending
+        return None
+
+    def check(
+        self,
+        context: "ExecutionContext",
+        now: datetime | None = None,
+    ) -> bool:
+        """Return True if approval is not required, or if a valid approval exists."""
+        if not self.requires_approval(context):
+            return True
+        return self.find_approved(context, now) is not None

matrixai/actions/composite_integration.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Roberto Llamosas Conde
+
+"""P21 C10 — P20 action contract integration with composite models."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ComponentChainEntry:
+    alias: str
+    registry_name: str
+    version: str
+    mode: str
+    entry_hash: str
+    interpretability_level: str
+    is_terminal: bool
+
+
+@dataclass(frozen=True)
+class CompositeAuditResult:
+    composite_model_hash: str
+    component_chain: list[ComponentChainEntry]
+    errors: list[str]
+    warnings: list[str]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def get_component_chain(program: Any, registry: Any) -> list[ComponentChainEntry]:
+    """Return ordered list of imported components with registry info."""
+    from matrixai.registry.model_registry import EntryNotFoundError
+
+    # Find terminal nodes: nodes that have no outgoing edges to other import nodes
+    import_aliases = {imp.alias for imp in getattr(program, "imports", [])}
+    out_nodes = {src for src, dst in program.graph.edges}
+    terminal_aliases = import_aliases - (import_aliases & out_nodes)
+
+    chain = []
+    for imp in sorted(getattr(program, "imports", []), key=lambda x: x.alias):
+        try:
+            entry = registry.get(imp.registry_name, imp.version)
+            chain.append(ComponentChainEntry(
+                alias=imp.alias,
+                registry_name=imp.registry_name,
+                version=imp.version,
+                mode=imp.mode,
+                entry_hash=entry.entry_hash,
+                interpretability_level=entry.interpretability_level,
+                is_terminal=imp.alias in terminal_aliases,
+            ))
+        except EntryNotFoundError:
+            chain.append(ComponentChainEntry(
+                alias=imp.alias,
+                registry_name=imp.registry_name,
+                version=imp.version,
+                mode=imp.mode,
+                entry_hash="",
+                interpretability_level="unknown",
+                is_terminal=imp.alias in terminal_aliases,
+            ))
+    return chain
+
+
+def validate_composite_action_contract(
+    program: Any,
+    registry: Any,
+    *,
+    contract: Any = None,
+) -> CompositeAuditResult:
+    """Validate that the composite program satisfies action contract rules.
+
+    Rules:
+    - Intermediate imported components must not have real_with_audit actions (blockers).
+    - Only the terminal node may carry an action contract.
+    """
+    from matrixai.registry.composite_hash import compute_composite_model_hash
+    from matrixai.registry.model_registry import EntryNotFoundError
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    import_aliases = {imp.alias for imp in getattr(program, "imports", [])}
+    # A node is intermediate if it has both incoming AND outgoing edges to/from import nodes
+    in_nodes = {dst for src, dst in program.graph.edges}
+    out_nodes = {src for src, dst in program.graph.edges}
+    intermediate_aliases = import_aliases & in_nodes & out_nodes
+
+    for imp in getattr(program, "imports", []):
+        if imp.alias not in intermediate_aliases:
+            continue
+        try:
+            entry = registry.get(imp.registry_name, imp.version)
+            blockers = getattr(entry, "blockers", [])
+            if "real_with_audit_action" in blockers:
+                errors.append(
+                    f"Intermediate component {imp.alias!r} has real_with_audit action — "
+                    f"only the terminal component may carry real actions"
+                )
+        except EntryNotFoundError:
+            errors.append(f"Component {imp.alias!r} not found in registry")
+
+    try:
+        composite_hash = compute_composite_model_hash(program, registry)
+    except Exception as exc:  # noqa: BLE001
+        errors.append(f"Cannot compute composite_model_hash: {exc}")
+        composite_hash = ""
+
+    chain = get_component_chain(program, registry)
+    return CompositeAuditResult(
+        composite_model_hash=composite_hash,
+        component_chain=chain,
+        errors=errors,
+        warnings=warnings,
+    )
+
+
+def composite_dry_run(
+    program: Any,
+    registry: Any,
+    input_data: Any,
+    *,
+    parameter_set: Any = None,
+) -> dict[str, Any]:
+    """Resolve all imports and simulate forward pass for dry-run validation."""
+    from matrixai.registry.resolver import CompositeModelResolver, ImportResolutionError
+    from matrixai.registry.composite_hash import compute_composite_model_hash
+
+    errors: list[str] = []
+
+    # Resolve all imports
+    resolver = CompositeModelResolver(registry)
+    try:
+        hydrated_imports = resolver.resolve(program, allow_mutable_tags=True)
+    except ImportResolutionError as exc:
+        errors.append(str(exc))
+        hydrated_imports = []
+
+    composite_hash = ""
+    if not errors:
+        try:
+            composite_hash = compute_composite_model_hash(program, registry)
+        except Exception as exc:  # noqa: BLE001
+            errors.append(str(exc))
+
+    return {
+        "ok": not errors,
+        "errors": errors,
+        "resolved_imports": [
+            {
+                "alias": imp.alias,
+                "registry_name": imp.registry_name,
+                "version": imp.version,
+                "resolved_entry_hash": imp.resolved_entry_hash,
+            }
+            for imp in hydrated_imports
+        ],
+        "composite_model_hash": composite_hash,
+        "input": input_data,
+    }

matrixai/actions/contract.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Roberto Llamosas Conde
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+
+from matrixai.actions.registry import registry
+from matrixai.actions.schema import (
+    ActionContractSpec,
+    CAPABILITIES,
+    RateLimitSpec,
+    RollbackSpec,
+    SandboxLimitsSpec,
+)
+from matrixai.ir.schema import MatrixAIProgram
+
+
+# ── canonical serialization ───────────────────────────────────────────────────
+
+def _ser_rollback(rb: RollbackSpec | None) -> dict | None:
+    if rb is None:
+        return None
+    return {
+        "capability": rb.capability,
+        "name": rb.name,
+        "scope": dict(sorted(rb.scope.items())),
+    }
+
+
+def _ser_rate_limit(rl: RateLimitSpec | None) -> dict | None:
+    if rl is None:
+        return None
+    return {"per_hour": rl.per_hour, "per_minute": rl.per_minute}
+
+
+def _ser_sandbox_limits(sl: SandboxLimitsSpec | None) -> dict | None:
+    if sl is None:
+        return None
+    return {
+        "allowed_env_vars": sorted(sl.allowed_env_vars),
+        "max_cpu_seconds": sl.max_cpu_seconds,
+        "max_memory_mb": sl.max_memory_mb,
+        "max_wall_seconds": sl.max_wall_seconds,
+        "no_network": sl.no_network,
+    }
+
+
+def canonical_dict(spec: ActionContractSpec) -> dict:
+    """Canonical dict for deterministic hashing — keys always sorted."""
+    return {
+        "approval_channel": spec.approval_channel,
+        "approval_timeout_seconds": spec.approval_timeout_seconds,
+        "capability": spec.capability,
+        "dry_run_required": spec.dry_run_required,
+        "human_approval": spec.human_approval,
+        "name": spec.name,
+        "rate_limit": _ser_rate_limit(spec.rate_limit),
+        "risk_level": CAPABILITIES[spec.capability],
+        "rollback": _ser_rollback(spec.rollback),
+        "sandbox_limits": _ser_sandbox_limits(spec.sandbox_limits),
+        "sandbox_required": spec.sandbox_required,
+        "scope": dict(sorted(spec.scope.items())),
+        "signature_required": spec.signature_required,
+    }
+
+
+def compute_action_contract_hash(spec: ActionContractSpec) -> str:
+    """Return 'sha256:<hex>' of the canonical JSON of spec."""
+    payload = json.dumps(canonical_dict(spec), sort_keys=True, separators=(",", ":"))
+    digest = hashlib.sha256(payload.encode()).hexdigest()
+    return f"sha256:{digest}"
+
+
+# ── compatibility validation ──────────────────────────────────────────────────
+
+@dataclass
+class ActionContractValidationResult:
+    ok: bool
+    errors: list[str]
+
+
+def validate_action_contract(
+    spec: ActionContractSpec,
+    program: MatrixAIProgram,
+) -> ActionContractValidationResult:
+    """Validate that spec is compatible with the .mxai program."""
+    errors: list[str] = []
+
+    matching = [a for a in program.actions if a.name == spec.name]
+    if not matching:
+        errors.append(f"Action {spec.name!r} not found in program actions")
+        return ActionContractValidationResult(ok=False, errors=errors)
+
+    action = matching[0]
+
+    if action.target and action.target != spec.capability:
+        errors.append(
+            f"Action {spec.name!r} TARGET {action.target!r} does not match "
+            f"contract CAPABILITY {spec.capability!r}"
+        )
+
+    if action.policy != "real_with_audit":
+        errors.append(
+            f"Action {spec.name!r} must have POLICY real_with_audit, got {action.policy!r}"
+        )
+
+    scope_result = registry.validate_scope(spec.capability, spec.scope)
+    if not scope_result.ok:
+        errors.extend(scope_result.errors)
+
+    return ActionContractValidationResult(ok=len(errors) == 0, errors=errors)
+
+
+# ── signing key check ─────────────────────────────────────────────────────────
+
+def check_signing_key_available() -> bool:
+    """Return True if MATRIXAI_ACTION_SIGNING_KEY is set in environment."""
+    return bool(os.environ.get("MATRIXAI_ACTION_SIGNING_KEY", ""))
+
+
+def require_signing_key(spec: ActionContractSpec) -> None:
+    """Raise RuntimeError if spec requires a signing key that is not available."""
+    if spec.signature_required and not check_signing_key_available():
+        raise RuntimeError(
+            f"ActionContract {spec.name!r} requires MATRIXAI_ACTION_SIGNING_KEY "
+            f"but it is not set in the environment"
+        )