devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/capability.py

@@ -0,0 +1,639 @@
+"""
+Sprint 3 – Ωᵢ capability declaration (v2.1 A1 fields) + PST runner.
+
+OmegaCapability is the per-agent capability record that must be set and valid
+before a node may participate in Textual Mode. It captures the empirical
+Lipschitz bound (L̂), calibration metadata, and PST (Prompt Stability Test)
+results. CapabilityStore handles on-disk persistence, and PSTRunner provides
+the evaluation harness for measuring output stability.
+
+A1 Textual Mode gate (RACP spec v2.1):
+  Textual Mode is allowed iff ALL of the following hold:
+    1. A valid Ωᵢ exists (not None / not stub format).
+    2. Calibration date is within expiry_days of today.
+    3. L̂ ≤ L_max (configurable; default = 2.0).
+    4. pst_status == "passed".
+  If any condition fails a CAPABILITY_DEGRADED event is emitted by the
+  GCCRepository layer, and the agent MUST fall back to Numerical-only /
+  deterministic mode.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Callable, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXPIRY_DAYS_DEFAULT: int = 90        # Calibration expires after 90 days
+L_MAX_DEFAULT: float = 2.0           # Default Lipschitz bound threshold
+PST_SCORE_THRESHOLD: float = 0.80    # PST must score ≥ 80 % to pass
+
+PST_STATUS_PASSED = "passed"
+PST_STATUS_FAILED = "failed"
+PST_STATUS_NOT_RUN = "not_run"
+
+CAPABILITY_DEGRADED_EVENT = "CAPABILITY_DEGRADED"
+OMEGA_SCHEMA_VERSION = "omega-v2.1"
+
+ROLE_POLICY_FILENAME = "role_policy.json"
+ROLES_SUBDIR = "roles"
+
+
+# ---------------------------------------------------------------------------
+# AgentRole dataclass
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class AgentRole:
+    """
+    Role-based policy for agent capabilities and concept access.
+
+    A role constrains what an agent may do based on its OmegaCapability:
+    - allowed_concepts: concept names the role may touch (empty means all).
+    - disallowed_concepts: concept names the role may never touch.
+    - required_capabilities: OmegaCapability field names that must be present.
+    - max_temperature: optional sampling-temperature ceiling.
+    """
+
+    role_id: str
+    name: str
+    allowed_concepts: List[str]
+    disallowed_concepts: List[str]
+    required_capabilities: List[str]
+    max_temperature: Optional[float] = None
+    created_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+    updated_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+
+    def __post_init__(self) -> None:
+        if not self.role_id.strip():
+            raise ValueError("role_id must not be empty.")
+        if not self.name.strip():
+            raise ValueError("name must not be empty.")
+        if self.max_temperature is not None and not (0.0 <= self.max_temperature <= 2.0):
+            raise ValueError("max_temperature must be in [0.0, 2.0].")
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentRole":
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+# ---------------------------------------------------------------------------
+# RolePolicy dataclass
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class RolePolicy:
+    """Collection of AgentRole objects with a default_role identifier."""
+
+    roles: List[AgentRole]
+    default_role: str
+    created_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+    updated_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+
+    def __post_init__(self) -> None:
+        if not self.default_role.strip():
+            raise ValueError("default_role must not be empty.")
+        role_ids = {r.role_id for r in self.roles}
+        if self.default_role not in role_ids:
+            raise ValueError(
+                f"default_role '{self.default_role}' is not in roles {role_ids}."
+            )
+        if len(role_ids) != len(self.roles):
+            raise ValueError("role_ids must be unique within a RolePolicy.")
+
+    def to_dict(self) -> dict:
+        return {
+            "roles": [r.to_dict() for r in self.roles],
+            "default_role": self.default_role,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RolePolicy":
+        roles = [AgentRole.from_dict(r) for r in d.get("roles", [])]
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(
+            roles=roles,
+            default_role=d.get("default_role", ""),
+            **{k: v for k, v in d.items() if k in known and k not in ("roles", "default_role")},
+        )
+
+    def get_role(self, role_id: str) -> Optional[AgentRole]:
+        for role in self.roles:
+            if role.role_id == role_id:
+                return role
+        return None
+
+
+# ---------------------------------------------------------------------------
+# OmegaCapability dataclass
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class OmegaCapability:
+    """
+    Per-agent capability declaration (Ωᵢ) for RACP v2.1 A1 compliance.
+
+    Required A1 fields
+    ------------------
+    agent_id                : Unique agent identifier.
+    lipschitz_bound         : Empirical L̂ from calibration (must be ≤ L_max).
+    calibration_dataset_hash: SHA-256 hex digest of the calibration corpus.
+    embedding_model         : Name/version of the embedding model used.
+    calibration_date        : ISO-8601 date (YYYY-MM-DD) of the calibration run.
+    temperature_used        : Sampling temperature used during calibration [0, 2].
+
+    Optional A1 fields
+    ------------------
+    lipschitz_p95           : 95th-percentile Lipschitz estimate.
+
+    PST fields (populated by PSTRunner)
+    ------------------------------------
+    pst_status              : "passed" | "failed" | "not_run".
+    pst_score               : Mean stability score [0, 1].
+    pst_n_prompts           : Number of prompts used.
+    pst_n_repetitions       : Number of repetitions per prompt.
+
+    Lifecycle
+    ---------
+    expiry_days             : Days after calibration_date before the declaration expires.
+    schema_version          : Fixed to "omega-v2.1".
+    created_at / updated_at : ISO-8601 UTC timestamps.
+    """
+
+    # Core A1 fields (required)
+    agent_id: str
+    lipschitz_bound: float
+    calibration_dataset_hash: str
+    embedding_model: str
+    calibration_date: str
+    temperature_used: float
+
+    # Optional A1 field
+    lipschitz_p95: Optional[float] = None
+
+    # PST results
+    pst_status: str = PST_STATUS_NOT_RUN
+    pst_score: Optional[float] = None
+    pst_n_prompts: int = 0
+    pst_n_repetitions: int = 0
+
+    # Lifecycle
+    expiry_days: int = EXPIRY_DAYS_DEFAULT
+
+    # Metadata
+    schema_version: str = OMEGA_SCHEMA_VERSION
+    created_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+    updated_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+
+    def __post_init__(self) -> None:
+        if self.pst_status not in (PST_STATUS_PASSED, PST_STATUS_FAILED, PST_STATUS_NOT_RUN):
+            raise ValueError(
+                f"pst_status must be 'passed', 'failed', or 'not_run', "
+                f"got '{self.pst_status}'"
+            )
+        if self.lipschitz_bound < 0:
+            raise ValueError("lipschitz_bound must be non-negative.")
+        if not (0.0 <= self.temperature_used <= 2.0):
+            raise ValueError("temperature_used must be in [0.0, 2.0].")
+        if not self.agent_id.strip():
+            raise ValueError("agent_id must not be empty.")
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "OmegaCapability":
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+    # ------------------------------------------------------------------
+    # A1 gate logic
+    # ------------------------------------------------------------------
+
+    def is_expired(self) -> bool:
+        """True if the calibration_date is older than expiry_days from today."""
+        try:
+            cal = _dt.date.fromisoformat(self.calibration_date[:10])
+        except (ValueError, TypeError):
+            return True  # Unparseable → treat as expired
+        return (_dt.date.today() - cal).days > self.expiry_days
+
+    def textual_mode_allowed(
+        self, l_max: float = L_MAX_DEFAULT
+    ) -> tuple[bool, List[str]]:
+        """
+        Return (allowed, [failure_reasons]).
+
+        All three conditions must hold for Textual Mode to be permitted:
+        - Calibration not expired.
+        - L̂ ≤ L_max.
+        - PST status is "passed".
+        """
+        reasons: List[str] = []
+        if self.is_expired():
+            reasons.append(
+                f"Calibration expired "
+                f"(calibration_date={self.calibration_date}, expiry_days={self.expiry_days})."
+            )
+        if self.lipschitz_bound > l_max:
+            reasons.append(
+                f"L\u0302={self.lipschitz_bound} exceeds L_max={l_max}."
+            )
+        if self.pst_status != PST_STATUS_PASSED:
+            reasons.append(
+                f"PST status is '{self.pst_status}' (must be '{PST_STATUS_PASSED}')."
+            )
+        return len(reasons) == 0, reasons
+
+
+# ---------------------------------------------------------------------------
+# CapabilityValidationResult
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class CapabilityValidationResult:
+    """Summary returned by CapabilityStore.validate()."""
+
+    valid: bool
+    textual_mode_allowed: bool
+    reasons: List[str]
+    agent_id: str
+    pst_status: str
+    lipschitz_bound: float  # float("inf") if no capability exists
+    is_expired: bool
+
+
+# ---------------------------------------------------------------------------
+# CapabilityStore
+# ---------------------------------------------------------------------------
+
+class CapabilityStore:
+    """
+    Reads and writes OmegaCapability to `.GCC/capabilities/omega.json`.
+
+    The legacy stub format (`schema == "omega-stub-v0"`) is recognised but
+    treated as "no capability set", so callers get a clear signal to run
+    `devtorch capability set` before proceeding.
+    """
+
+    def __init__(self, capabilities_dir: Path) -> None:
+        self.dir = capabilities_dir
+        self.omega_path = capabilities_dir / "omega.json"
+        self.roles_dir = capabilities_dir / ROLES_SUBDIR
+        self.policy_path = capabilities_dir / ROLE_POLICY_FILENAME
+
+    def save(self, cap: OmegaCapability) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.omega_path.write_text(
+            json.dumps(cap.to_dict(), indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    def load(self) -> Optional[OmegaCapability]:
+        if not self.omega_path.exists():
+            return None
+        try:
+            data = json.loads(self.omega_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+        # Detect legacy stub format from Sprint 0
+        if data.get("schema") == "omega-stub-v0":
+            return None
+        try:
+            return OmegaCapability.from_dict(data)
+        except (TypeError, ValueError):
+            return None
+
+    def validate(self, l_max: float = L_MAX_DEFAULT) -> CapabilityValidationResult:
+        """Run A1 gate checks and return a structured result."""
+        cap = self.load()
+        if cap is None:
+            return CapabilityValidationResult(
+                valid=False,
+                textual_mode_allowed=False,
+                reasons=["No valid capability declaration found (Ωᵢ not set)."],
+                agent_id="<none>",
+                pst_status=PST_STATUS_NOT_RUN,
+                lipschitz_bound=float("inf"),
+                is_expired=True,
+            )
+        allowed, reasons = cap.textual_mode_allowed(l_max=l_max)
+        return CapabilityValidationResult(
+            valid=allowed,
+            textual_mode_allowed=allowed,
+            reasons=reasons,
+            agent_id=cap.agent_id,
+            pst_status=cap.pst_status,
+            lipschitz_bound=cap.lipschitz_bound,
+            is_expired=cap.is_expired(),
+        )
+
+    # ------------------------------------------------------------------
+    # Role / policy persistence
+    # ------------------------------------------------------------------
+
+    def save_role(self, role: AgentRole) -> None:
+        self.roles_dir.mkdir(parents=True, exist_ok=True)
+        path = self.roles_dir / f"{role.role_id}.json"
+        path.write_text(
+            json.dumps(role.to_dict(), indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    def load_role(self, role_id: str) -> Optional[AgentRole]:
+        path = self.roles_dir / f"{role_id}.json"
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+        try:
+            return AgentRole.from_dict(data)
+        except (TypeError, ValueError):
+            return None
+
+    def list_roles(self) -> List[str]:
+        if not self.roles_dir.exists():
+            return []
+        roles = []
+        for path in self.roles_dir.iterdir():
+            if path.is_file() and path.suffix == ".json":
+                roles.append(path.stem)
+        return sorted(roles)
+
+    def save_policy(self, policy: RolePolicy) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.policy_path.write_text(
+            json.dumps(policy.to_dict(), indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    def load_policy(self) -> Optional[RolePolicy]:
+        if not self.policy_path.exists():
+            return None
+        try:
+            data = json.loads(self.policy_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+        try:
+            return RolePolicy.from_dict(data)
+        except (TypeError, ValueError):
+            return None
+
+    def check_role_policy(
+        self,
+        cap: OmegaCapability,
+        role: AgentRole,
+        concepts_used: List[str],
+    ) -> List[str]:
+        """
+        Return a list of human-readable reasons if `cap` does not satisfy the
+        constraints of `role` for `concepts_used`.  An empty list means allowed.
+        """
+        reasons: List[str] = []
+
+        # Required capability fields
+        for field in role.required_capabilities:
+            if not hasattr(cap, field):
+                reasons.append(f"Missing required capability field '{field}'.")
+                continue
+            value = getattr(cap, field)
+            if value is None:
+                reasons.append(f"Required capability field '{field}' is unset.")
+            elif isinstance(value, (int, float)) and value == 0:
+                # zero numeric fields are considered present
+                pass
+            elif isinstance(value, str) and not value.strip():
+                reasons.append(f"Required capability field '{field}' is empty.")
+
+        # Temperature ceiling
+        if role.max_temperature is not None and cap.temperature_used > role.max_temperature:
+            reasons.append(
+                f"temperature_used={cap.temperature_used} exceeds "
+                f"role max_temperature={role.max_temperature}."
+            )
+
+        # Disallowed concepts
+        for concept in concepts_used:
+            if concept in role.disallowed_concepts:
+                reasons.append(f"Role may not touch disallowed concept '{concept}'.")
+
+        # Allowed-concept whitelist
+        if role.allowed_concepts:
+            allowed = set(role.allowed_concepts)
+            for concept in concepts_used:
+                if concept not in allowed:
+                    reasons.append(
+                        f"Role is not allowed to touch concept '{concept}'."
+                    )
+
+        return reasons
+
+
+def apply_default_policy(store: CapabilityStore) -> RolePolicy:
+    """
+    Create a sensible default role policy and persist it through `store`.
+
+    Returns the policy object.
+    """
+    roles = [
+        AgentRole(
+            role_id="architect",
+            name="System Architect",
+            allowed_concepts=["design", "architecture", "security", "api"],
+            disallowed_concepts=["payments", "secrets", "pii"],
+            required_capabilities=["lipschitz_bound", "embedding_model"],
+            max_temperature=1.0,
+        ),
+        AgentRole(
+            role_id="implementer",
+            name="Implementer",
+            allowed_concepts=["code", "tests", "api", "schema"],
+            disallowed_concepts=["payments", "secrets", "pii"],
+            required_capabilities=["lipschitz_bound"],
+            max_temperature=1.2,
+        ),
+        AgentRole(
+            role_id="reviewer",
+            name="Reviewer",
+            allowed_concepts=["code", "tests", "security", "api", "schema"],
+            disallowed_concepts=["payments", "secrets", "pii"],
+            required_capabilities=["lipschitz_bound", "lipschitz_p95", "pst_status"],
+            max_temperature=0.5,
+        ),
+        AgentRole(
+            role_id="ops",
+            name="Operations",
+            allowed_concepts=["infrastructure", "deployment", "config"],
+            disallowed_concepts=["pii", "payments", "auth"],
+            required_capabilities=["lipschitz_bound"],
+            max_temperature=0.3,
+        ),
+    ]
+    policy = RolePolicy(roles=roles, default_role="implementer")
+    for role in roles:
+        store.save_role(role)
+    store.save_policy(policy)
+    return policy
+
+
+# ---------------------------------------------------------------------------
+# PST runner
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class PSTReport:
+    """Structured output from a PSTRunner.run() call."""
+
+    agent_id: str
+    n_prompts: int
+    n_repetitions: int
+    pst_score: float
+    per_prompt_scores: List[float]
+    status: str          # "passed" | "failed"
+    threshold: float
+    run_at: str
+
+
+# ---------------------------------------------------------------------------
+# A1 Round Cap (S9)
+# ---------------------------------------------------------------------------
+
+T_MAX_MULTIPLIER: float = 2.0        # T_max = T_MAX_MULTIPLIER × T_txt
+CONVERGENCE_TIMEOUT_ROUNDS: int = 20  # Absolute fallback cap
+
+
+@dataclasses.dataclass
+class RoundCapResult:
+    allowed: bool          # whether next round is allowed
+    current_round: int
+    t_max: int
+    reason: str            # human-readable explanation
+
+
+def check_round_cap(
+    current_round: int,
+    t_txt: int,
+    t_max_multiplier: float = T_MAX_MULTIPLIER,
+    absolute_cap: int = CONVERGENCE_TIMEOUT_ROUNDS,
+) -> RoundCapResult:
+    """
+    Check whether a Textual Mode round is permitted under A1 round cap.
+    T_max = floor(t_max_multiplier × t_txt), capped at absolute_cap.
+    Returns RoundCapResult with allowed=False and CONVERGENCE_TIMEOUT reason
+    if current_round > T_max.
+    """
+    t_max = min(int(t_max_multiplier * t_txt), absolute_cap)
+    if current_round > t_max:
+        return RoundCapResult(
+            allowed=False,
+            current_round=current_round,
+            t_max=t_max,
+            reason=f"CONVERGENCE_TIMEOUT: round {current_round} exceeds T_max={t_max} "
+                   f"(= {t_max_multiplier}×T_txt={t_txt}, cap={absolute_cap})",
+        )
+    return RoundCapResult(
+        allowed=True,
+        current_round=current_round,
+        t_max=t_max,
+        reason="ok",
+    )
+
+
+class PSTRunner:
+    """
+    Prompt Stability Test (PST) harness.
+
+    Runs `n_prompts` canonical prompts × `n_repetitions` repetitions through
+    a caller-supplied `run_fn(prompt: str, rep: int) -> str`.  The per-prompt
+    stability score is the fraction of repetitions that produced the most
+    common output.  The overall PST_score is the mean across all prompts.
+
+    Example (deterministic stub):
+        runner = PSTRunner(
+            agent_id="agent-1",
+            run_fn=lambda p, r: "always the same",
+        )
+        report = runner.run()   # pst_score == 1.0, status == "passed"
+
+    The OSS-local mode intentionally does *not* call an external LLM; callers
+    supply their own run_fn, which can wrap any LLM client or a local stub.
+    """
+
+    DEFAULT_PROMPTS: List[str] = [
+        "Summarise the current reasoning context in one sentence.",
+        "What is the primary constraint in the current decision?",
+        "List the top three risks in the current plan.",
+        "Is the current approach deterministic? Answer yes or no.",
+        "What data is marked PRIVATE in the current context?",
+    ]
+
+    def __init__(
+        self,
+        agent_id: str,
+        run_fn: Callable[[str, int], str],
+        n_prompts: int = 5,
+        n_repetitions: int = 3,
+        threshold: float = PST_SCORE_THRESHOLD,
+        prompts: Optional[List[str]] = None,
+    ) -> None:
+        self.agent_id = agent_id
+        self.run_fn = run_fn
+        self.n_prompts = n_prompts
+        self.n_repetitions = n_repetitions
+        self.threshold = threshold
+        self.prompts = (prompts if prompts is not None else self.DEFAULT_PROMPTS)[: n_prompts]
+
+    def run(self) -> PSTReport:
+        """Execute the PST and return a PSTReport."""
+        per_prompt_scores: List[float] = []
+        for prompt in self.prompts:
+            outputs = [self.run_fn(prompt, rep) for rep in range(self.n_repetitions)]
+            most_common_count = Counter(outputs).most_common(1)[0][1]
+            stability = most_common_count / self.n_repetitions
+            per_prompt_scores.append(stability)
+
+        pst_score = (
+            sum(per_prompt_scores) / len(per_prompt_scores)
+            if per_prompt_scores
+            else 0.0
+        )
+        status = PST_STATUS_PASSED if pst_score >= self.threshold else PST_STATUS_FAILED
+
+        return PSTReport(
+            agent_id=self.agent_id,
+            n_prompts=self.n_prompts,
+            n_repetitions=self.n_repetitions,
+            pst_score=round(pst_score, 6),
+            per_prompt_scores=[round(s, 6) for s in per_prompt_scores],
+            status=status,
+            threshold=self.threshold,
+            run_at=_dt.datetime.now(tz=_dt.timezone.utc).isoformat(),
+        )

devtorch_core/cloud/__init__.py

@@ -0,0 +1 @@
+"""Cloud MCP server client configuration and IDE wiring."""