akasha-model 0.2.0__py3-none-any.whl

akasha_model/__init__.py

@@ -0,0 +1,183 @@
+"""Small one-pass text and visual option scorers.
+
+Path A (planner + host + outcomes + wire) imports without torch. Path B scorers,
+training, and vision load lazily and require the ``torch`` extra::
+
+    pip install "akasha-model[torch]"
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .primitives import (
+    ChoiceQuestion,
+    ChoiceResult,
+    DecisionRequest,
+    NoulQuestion,
+    NoulResult,
+    OptionSpec,
+    ScoreLevel,
+    ScoreQuestion,
+    ScoreResult,
+)
+from .authority import AuthorityProfile
+from .catalog import CatalogPolicy, check_catalog_policy
+from .gate import (
+    DEFAULT_MAX_RISK_SCORE,
+    DEFAULT_MIN_CHOICE_CONFIDENCE,
+    DEFAULT_MIN_CHOICE_PROBABILITY,
+    DEFAULT_NOUL_THRESHOLD,
+    GateSignals,
+    ToolProposal,
+    default_gate_planner,
+    describe_plan,
+    evaluate_gate,
+)
+from .host import (
+    HostOutcome,
+    ToolHost,
+    describe_outcome,
+    dispatch_plan,
+    run_gated_call,
+)
+from .outcomes import (
+    GateOutcomeRecord,
+    append_outcome,
+    load_outcomes,
+    record_from_host_outcome,
+    suggest_threshold_updates,
+    summarize_outcomes,
+)
+from .tool_calling import ToolCallPlan, ToolCallPlanner, ToolSpec, validate_tool_arguments
+from .audit import (
+    GateAuditEnvelope,
+    build_audit_envelope,
+    content_hash,
+    envelope_from_dict,
+    envelope_to_dict,
+    verify_envelope,
+)
+from .wire import (
+    CONTRACT_VERSION,
+    outcome_from_dict,
+    outcome_to_dict,
+    plan_from_dict,
+    plan_to_dict,
+    request_from_dict,
+    request_to_dict,
+    schema_path,
+)
+
+__version__ = "0.2.0"
+
+# Symbols that require the optional torch stack. Resolved via __getattr__.
+_TORCH_EXPORTS = {
+    "CHESS_OPTION_IDS",
+    "DOOM_OPTION_IDS",
+    "TOTAL_OPTIONS",
+    "DecisionModel",
+    "DoomScorerV2",
+    "MultiQuestionCollator",
+    "MultiQuestionDataset",
+    "MultiQuestionTinyScorer",
+    "convert_typed_row",
+    "grpo_loss",
+    "load_decision_checkpoint",
+    "plan_scored_proposal",
+    "run_scored_gated_call",
+    "score_proposal",
+}
+
+__all__ = [
+    "CHESS_OPTION_IDS", "DOOM_OPTION_IDS", "TOTAL_OPTIONS", "DoomScorerV2",
+    "CONTRACT_VERSION", "GateAuditEnvelope",
+    "ChoiceQuestion", "ChoiceResult", "DecisionRequest", "NoulQuestion",
+    "NoulResult", "OptionSpec", "ScoreLevel", "ScoreQuestion", "ScoreResult",
+    "DEFAULT_MAX_RISK_SCORE", "DEFAULT_MIN_CHOICE_CONFIDENCE",
+    "DEFAULT_MIN_CHOICE_PROBABILITY", "DEFAULT_NOUL_THRESHOLD",
+    "AuthorityProfile", "CatalogPolicy", "DecisionModel", "MultiQuestionCollator",
+    "MultiQuestionDataset", "MultiQuestionTinyScorer", "GateOutcomeRecord",
+    "GateSignals", "HostOutcome", "ToolHost", "ToolProposal", "ToolCallPlan",
+    "ToolCallPlanner", "ToolSpec", "append_outcome", "build_audit_envelope",
+    "check_catalog_policy", "content_hash", "convert_typed_row",
+    "default_gate_planner", "describe_outcome", "describe_plan",
+    "dispatch_plan", "envelope_from_dict", "envelope_to_dict", "evaluate_gate",
+    "grpo_loss",
+    "load_decision_checkpoint", "load_outcomes", "outcome_from_dict",
+    "outcome_to_dict", "plan_from_dict", "plan_scored_proposal", "plan_to_dict",
+    "record_from_host_outcome", "request_from_dict", "request_to_dict",
+    "run_gated_call", "run_scored_gated_call", "schema_path", "score_proposal",
+    "suggest_threshold_updates", "summarize_outcomes", "validate_tool_arguments",
+    "verify_envelope",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load torch-backed exports so Path A stays installable without torch."""
+    if name not in _TORCH_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        if name in {"DecisionModel", "load_decision_checkpoint"}:
+            from .decision import DecisionModel, load_decision_checkpoint
+
+            values = {
+                "DecisionModel": DecisionModel,
+                "load_decision_checkpoint": load_decision_checkpoint,
+            }
+        elif name in {
+            "MultiQuestionCollator",
+            "MultiQuestionDataset",
+            "MultiQuestionTinyScorer",
+        }:
+            from .multitask import (
+                MultiQuestionCollator,
+                MultiQuestionDataset,
+                MultiQuestionTinyScorer,
+            )
+
+            values = {
+                "MultiQuestionCollator": MultiQuestionCollator,
+                "MultiQuestionDataset": MultiQuestionDataset,
+                "MultiQuestionTinyScorer": MultiQuestionTinyScorer,
+            }
+        elif name == "grpo_loss":
+            from .rlcd import grpo_loss
+
+            values = {"grpo_loss": grpo_loss}
+        elif name in {
+            "plan_scored_proposal",
+            "run_scored_gated_call",
+            "score_proposal",
+        }:
+            from .gate_multitask import (
+                plan_scored_proposal,
+                run_scored_gated_call,
+                score_proposal,
+            )
+
+            values = {
+                "plan_scored_proposal": plan_scored_proposal,
+                "run_scored_gated_call": run_scored_gated_call,
+                "score_proposal": score_proposal,
+            }
+        elif name == "convert_typed_row":
+            from .typed_decisions import convert_typed_row
+
+            values = {"convert_typed_row": convert_typed_row}
+        else:
+            from .vision import CHESS_OPTION_IDS, DOOM_OPTION_IDS, TOTAL_OPTIONS, DoomScorerV2
+
+            values = {
+                "CHESS_OPTION_IDS": CHESS_OPTION_IDS,
+                "DOOM_OPTION_IDS": DOOM_OPTION_IDS,
+                "TOTAL_OPTIONS": TOTAL_OPTIONS,
+                "DoomScorerV2": DoomScorerV2,
+            }
+    except ImportError as exc:  # pragma: no cover - exercised in gate-only CI
+        raise ImportError(
+            f"{name} requires the torch extra. "
+            'Install with: pip install "akasha-model[torch]"'
+        ) from exc
+    globals().update(values)
+    return values[name]

akasha_model/audit.py

@@ -0,0 +1,185 @@
+"""Tamper-evident (hash-only) audit envelopes for Path A plans / outcomes.
+
+v1 is content-hash integrity without cryptography. Hosts may attach signatures
+later. Construction has no side effects and does not execute tools.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+from .gate import GateSignals, ToolProposal
+from .host import HostOutcome
+from .tool_calling import ToolCallPlan, ToolSpec
+from .wire import (
+    CONTRACT_VERSION,
+    outcome_to_dict,
+    plan_to_dict,
+    proposal_to_dict,
+    signals_to_dict,
+    tool_spec_to_dict,
+)
+
+
+def _canonical_json(payload: Mapping[str, Any]) -> bytes:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode(
+        "utf-8",
+    )
+
+
+def content_hash(payload: Mapping[str, Any]) -> str:
+    """Stable SHA-256 hex digest over canonical JSON (Python/Rust parity target)."""
+    return hashlib.sha256(_canonical_json(payload)).hexdigest()
+
+
+@dataclass(frozen=True)
+class GateAuditEnvelope:
+    """Package-owned audit record for one evaluate / dispatch decision."""
+
+    contract_version: int
+    request_id: str | None
+    recorded_at: str
+    proposal: Mapping[str, Any]
+    signals: Mapping[str, Any] | None
+    plan: Mapping[str, Any]
+    host_action: str | None
+    host_reason: str | None
+    tools: Mapping[str, Any] | None
+    content_sha256: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return envelope_to_dict(self)
+
+
+def envelope_to_dict(envelope: GateAuditEnvelope) -> dict[str, Any]:
+    return {
+        "contract_version": envelope.contract_version,
+        "request_id": envelope.request_id,
+        "recorded_at": envelope.recorded_at,
+        "proposal": dict(envelope.proposal),
+        "signals": None if envelope.signals is None else dict(envelope.signals),
+        "plan": dict(envelope.plan),
+        "host_action": envelope.host_action,
+        "host_reason": envelope.host_reason,
+        "tools": None if envelope.tools is None else dict(envelope.tools),
+        "content_sha256": envelope.content_sha256,
+    }
+
+
+def envelope_from_dict(data: Mapping[str, Any]) -> GateAuditEnvelope:
+    version = int(data.get("contract_version", CONTRACT_VERSION))
+    if version != CONTRACT_VERSION:
+        raise ValueError(
+            f"unsupported envelope contract_version {version}; "
+            f"this package speaks {CONTRACT_VERSION}"
+        )
+    return GateAuditEnvelope(
+        contract_version=version,
+        request_id=data.get("request_id"),
+        recorded_at=str(data["recorded_at"]),
+        proposal=dict(data["proposal"]),
+        signals=None if data.get("signals") is None else dict(data["signals"]),
+        plan=dict(data["plan"]),
+        host_action=data.get("host_action"),
+        host_reason=data.get("host_reason"),
+        tools=None if data.get("tools") is None else dict(data["tools"]),
+        content_sha256=str(data["content_sha256"]),
+    )
+
+
+def _body_for_hash(
+    *,
+    contract_version: int,
+    request_id: str | None,
+    recorded_at: str,
+    proposal: Mapping[str, Any],
+    signals: Mapping[str, Any] | None,
+    plan: Mapping[str, Any],
+    host_action: str | None,
+    host_reason: str | None,
+    tools: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    # Hash excludes content_sha256 itself.
+    return {
+        "contract_version": contract_version,
+        "request_id": request_id,
+        "recorded_at": recorded_at,
+        "proposal": dict(proposal),
+        "signals": None if signals is None else dict(signals),
+        "plan": dict(plan),
+        "host_action": host_action,
+        "host_reason": host_reason,
+        "tools": None if tools is None else dict(tools),
+    }
+
+
+def build_audit_envelope(
+    *,
+    plan: ToolCallPlan,
+    proposal: ToolProposal,
+    signals: GateSignals | None = None,
+    tools: Mapping[str, ToolSpec] | None = None,
+    outcome: HostOutcome | None = None,
+    request_id: str | None = None,
+    recorded_at: str | None = None,
+) -> GateAuditEnvelope:
+    """Build an envelope without I/O. Idempotency / persistence stay host-owned."""
+    stamp = recorded_at or datetime.now(timezone.utc).isoformat()
+    plan_wire = plan_to_dict(plan, request_id=request_id)
+    proposal_wire = proposal_to_dict(proposal)
+    signals_wire = None if signals is None else signals_to_dict(signals)
+    tools_wire = (
+        None
+        if tools is None
+        else {name: tool_spec_to_dict(spec) for name, spec in tools.items()}
+    )
+    host_action = outcome.action if outcome is not None else None
+    host_reason = outcome.host_reason if outcome is not None else None
+    if outcome is not None:
+        # Prefer outcome plan wire (same plan, ensures consistency).
+        plan_wire = outcome_to_dict(outcome, request_id=request_id)["plan"]
+    body = _body_for_hash(
+        contract_version=CONTRACT_VERSION,
+        request_id=request_id,
+        recorded_at=stamp,
+        proposal=proposal_wire,
+        signals=signals_wire,
+        plan=plan_wire,
+        host_action=host_action,
+        host_reason=host_reason,
+        tools=tools_wire,
+    )
+    digest = content_hash(body)
+    return GateAuditEnvelope(
+        contract_version=CONTRACT_VERSION,
+        request_id=request_id,
+        recorded_at=stamp,
+        proposal=proposal_wire,
+        signals=signals_wire,
+        plan=plan_wire,
+        host_action=host_action,
+        host_reason=host_reason,
+        tools=tools_wire,
+        content_sha256=digest,
+    )
+
+
+def verify_envelope(envelope: GateAuditEnvelope | Mapping[str, Any]) -> bool:
+    data = envelope_to_dict(envelope) if isinstance(envelope, GateAuditEnvelope) else dict(envelope)
+    expected = data.get("content_sha256")
+    body = {k: v for k, v in data.items() if k != "content_sha256"}
+    return expected == content_hash(body)
+
+
+__all__ = [
+    "GateAuditEnvelope",
+    "build_audit_envelope",
+    "content_hash",
+    "envelope_from_dict",
+    "envelope_to_dict",
+    "verify_envelope",
+]

akasha_model/authority.py

@@ -0,0 +1,163 @@
+"""Optional Path A authority profiles (MIDAS-inspired, executor-free).
+
+Profiles tune *how far* authorization goes once a tool is proposed. Catalog
+policy (#15) decides *what* may be proposed; OS ``check_permissions`` remains
+the final grant check.
+
+Statuses stay ``ready`` / ``abstain`` / ``blocked`` for backward compatibility.
+When a profile is supplied, ``plan.reason`` is prefixed with a stable code:
+
+- ``escalate:`` — within authority chain but over profile threshold (human review)
+- ``reject:`` — hard policy / risk deny
+- ``clarify:`` — insufficient context / missing required context keys
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from .tool_calling import ToolCallPlan
+
+
+@dataclass(frozen=True)
+class AuthorityProfile:
+    """Optional thresholds bound to a decision surface / tool class.
+
+    All fields are optional; ``None`` means “use the planner defaults / ignore”.
+    """
+
+    name: str = "default"
+    min_authorized: float | None = None
+    min_sufficient_context: float | None = None
+    max_risk_score: float | None = None
+    max_consequence: float | None = None
+    required_context_keys: tuple[str, ...] = ()
+
+
+def annotate_reason(code: str, detail: str) -> str:
+    return f"{code}: {detail}"
+
+
+def apply_authority_profile(
+    plan: ToolCallPlan,
+    *,
+    profile: AuthorityProfile | None,
+    authorized: float,
+    sufficient_context: float,
+    risk_score: float | None,
+    consequence: float | None,
+    context: Mapping[str, object] | None,
+) -> ToolCallPlan:
+    """Re-map or annotate a plan when an authority profile is active.
+
+    Callers that omit ``profile`` keep today's behaviour unchanged.
+    """
+    if profile is None:
+        return plan
+
+    if profile.required_context_keys:
+        ctx = context or {}
+        missing = [key for key in profile.required_context_keys if key not in ctx]
+        if missing:
+            return ToolCallPlan(
+                "abstain",
+                plan.tool_name,
+                None,
+                annotate_reason(
+                    "clarify",
+                    "missing required context key(s): " + ", ".join(missing),
+                ),
+                plan.choice_probability,
+                plan.choice_confidence,
+                plan.risk_score,
+            )
+
+    if (
+        profile.min_sufficient_context is not None
+        and sufficient_context < profile.min_sufficient_context
+    ):
+        return ToolCallPlan(
+            "abstain",
+            plan.tool_name,
+            None,
+            annotate_reason(
+                "clarify",
+                "sufficient_context below authority profile minimum",
+            ),
+            plan.choice_probability,
+            plan.choice_confidence,
+            plan.risk_score,
+        )
+
+    if profile.min_authorized is not None and authorized < profile.min_authorized:
+        return ToolCallPlan(
+            "blocked",
+            plan.tool_name,
+            None,
+            annotate_reason("reject", "authorized below authority profile minimum"),
+            plan.choice_probability,
+            plan.choice_confidence,
+            plan.risk_score,
+        )
+
+    if (
+        profile.max_risk_score is not None
+        and risk_score is not None
+        and risk_score > profile.max_risk_score
+    ):
+        return ToolCallPlan(
+            "blocked",
+            plan.tool_name,
+            None,
+            annotate_reason("reject", "risk score exceeds authority profile maximum"),
+            plan.choice_probability,
+            plan.choice_confidence,
+            risk_score,
+        )
+
+    if (
+        profile.max_consequence is not None
+        and consequence is not None
+        and consequence > profile.max_consequence
+    ):
+        return ToolCallPlan(
+            "abstain",
+            plan.tool_name,
+            None,
+            annotate_reason(
+                "escalate",
+                "consequence exceeds authority profile; human review required",
+            ),
+            plan.choice_probability,
+            plan.choice_confidence,
+            plan.risk_score,
+        )
+
+    # Already non-ready from planner: prefix stable codes where obvious.
+    if plan.status == "blocked" and plan.reason.startswith(
+        ("authorization", "Risk score", "required capability", "explicit human"),
+    ):
+        return ToolCallPlan(
+            plan.status,
+            plan.tool_name,
+            plan.arguments,
+            annotate_reason("reject", plan.reason),
+            plan.choice_probability,
+            plan.choice_confidence,
+            plan.risk_score,
+        )
+    if plan.status == "blocked" and "context sufficiency" in plan.reason:
+        return ToolCallPlan(
+            "abstain",
+            plan.tool_name,
+            None,
+            annotate_reason("clarify", plan.reason),
+            plan.choice_probability,
+            plan.choice_confidence,
+            plan.risk_score,
+        )
+    return plan
+
+
+__all__ = ["AuthorityProfile", "annotate_reason", "apply_authority_profile"]

akasha_model/calibration.py

@@ -0,0 +1,87 @@
+"""Post-hoc temperature calibration for one-pass choice models."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import torch
+from torch.nn import functional as F
+from torch.utils.data import DataLoader
+
+from .data import JsonlDataset
+from .model import load_checkpoint, select_device
+from .train import move
+
+
+def _pad_logits(items: list[torch.Tensor]) -> torch.Tensor:
+    width = max(item.shape[1] for item in items)
+    fill = -1e4
+    return torch.cat([
+        F.pad(item.clamp_min(fill), (0, width - item.shape[1]), value=fill)
+        for item in items
+    ])
+
+
+@torch.no_grad()
+def collect_logits(model, loader, device):
+    model.eval()
+    logits, labels = [], []
+    for host_batch in loader:
+        batch = move(host_batch, device)
+        logits.append(model(batch).cpu())
+        labels.append(batch["labels"].cpu())
+    return _pad_logits(logits), torch.cat(labels)
+
+
+def fit_temperature(logits: torch.Tensor, labels: torch.Tensor) -> float:
+    """Fit one positive temperature by minimizing held-out NLL."""
+    log_temperature = torch.zeros((), requires_grad=True)
+    optimiser = torch.optim.Adam([log_temperature], lr=0.05)
+    for _ in range(200):
+        optimiser.zero_grad()
+        temperature = log_temperature.clamp(-5.0, 5.0).exp()
+        loss = F.cross_entropy(logits / temperature, labels)
+        loss.backward()
+        optimiser.step()
+        with torch.no_grad():
+            log_temperature.clamp_(-5.0, 5.0)
+    return float(log_temperature.detach().clamp(-5.0, 5.0).exp())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("checkpoint")
+    parser.add_argument("calibration_data")
+    parser.add_argument("--output", default="runs/calibrated.pt")
+    parser.add_argument("--batch-size", type=int, default=64)
+    parser.add_argument("--device", choices=("auto", "cpu", "mps", "cuda"), default="auto")
+    args = parser.parse_args()
+
+    device = select_device(args.device)
+    model, collator, config = load_checkpoint(args.checkpoint, device)
+    loader = DataLoader(
+        JsonlDataset(args.calibration_data), batch_size=args.batch_size,
+        collate_fn=collator,
+    )
+    logits, labels = collect_logits(model, loader, device)
+    old_temperature = float(config.get("temperature", 1.0))
+    temperature = fit_temperature(logits, labels) * old_temperature
+
+    payload = torch.load(args.checkpoint, map_location="cpu", weights_only=False)
+    payload["config"]["temperature"] = temperature
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    torch.save(payload, output)
+    print(json.dumps({
+        "checkpoint": str(output),
+        "calibration_examples": int(labels.numel()),
+        "old_temperature": old_temperature,
+        "temperature": temperature,
+        "device": str(device),
+    }))
+
+
+if __name__ == "__main__":
+    main()

akasha_model/catalog.py

@@ -0,0 +1,72 @@
+"""Optional phase-3 catalog constraints for Path A.
+
+Layering (outer → inner):
+
+1. **CatalogPolicy** (this module) — which tools may be proposed on a surface
+   (allowlist / denylist / required placement tags).
+2. **ToolSpec** — per-tool schema, capabilities, confirmation, irreversible.
+3. **OS ``check_permissions``** — final ACL / capability grant on the host.
+
+No execution here. Outcomes suggestions (#8) never auto-write these rules.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+from .tool_calling import ToolCallPlan, ToolSpec
+
+
+@dataclass(frozen=True)
+class CatalogPolicy:
+    """Optional constraints applied before planner thresholds.
+
+    - ``allowlist``: if set, proposal tool must be in the set.
+    - ``denylist``: proposal tool must not be in the set.
+    - ``required_placement``: every listed tag must appear on the tool's
+      ``placement_tags`` (e.g. ``offline``, ``preview``).
+    """
+
+    allowlist: frozenset[str] | None = None
+    denylist: frozenset[str] = field(default_factory=frozenset)
+    required_placement: frozenset[str] = field(default_factory=frozenset)
+
+
+def check_catalog_policy(
+    tools: Mapping[str, ToolSpec],
+    tool_name: str,
+    policy: CatalogPolicy | None,
+) -> ToolCallPlan | None:
+    """Return a blocked plan when policy rejects the proposal, else ``None``."""
+    if policy is None:
+        return None
+    if policy.allowlist is not None and tool_name not in policy.allowlist:
+        return ToolCallPlan(
+            "blocked",
+            tool_name,
+            None,
+            f"catalog_allowlist: tool not permitted: {tool_name}",
+        )
+    if tool_name in policy.denylist:
+        return ToolCallPlan(
+            "blocked",
+            tool_name,
+            None,
+            f"catalog_denylist: tool denied: {tool_name}",
+        )
+    if policy.required_placement:
+        spec = tools.get(tool_name)
+        tags = frozenset(getattr(spec, "placement_tags", ()) or ()) if spec else frozenset()
+        missing = sorted(policy.required_placement - tags)
+        if missing:
+            return ToolCallPlan(
+                "blocked",
+                tool_name,
+                None,
+                "catalog_placement: missing tag(s): " + ", ".join(missing),
+            )
+    return None
+
+
+__all__ = ["CatalogPolicy", "check_catalog_policy"]