arvis 0.1.0a12__py3-none-any.whl

arvis/__init__.py

@@ -0,0 +1,24 @@
+# arvis/__init__.py
+"""
+Top-level public API.
+
+Only stable high-level entrypoints are exposed here.
+"""
+
+from .api.audit import AuditCommitmentPolicy
+from .api.engine import ArvisEngine
+from .api.os import CognitiveOS, CognitiveOSConfig
+from .api.runtime_controls import TrustedRuntimeControls
+from .api.runtime_mode import RuntimeMode
+from .api.version import PACKAGE_VERSION
+
+__version__ = PACKAGE_VERSION
+
+__all__ = [
+    "ArvisEngine",
+    "AuditCommitmentPolicy",
+    "CognitiveOS",
+    "CognitiveOSConfig",
+    "RuntimeMode",
+    "TrustedRuntimeControls",
+]

arvis/action/__init__.py

@@ -0,0 +1,13 @@
+# arvis/action/__init__.py
+
+from .action_context import ActionContext
+from .action_decision import ActionDecision
+from .action_mode import ActionMode
+from .action_template import ActionTemplate
+
+__all__ = [
+    "ActionContext",
+    "ActionDecision",
+    "ActionMode",
+    "ActionTemplate",
+]

arvis/action/action_context.py

@@ -0,0 +1,18 @@
+# arvis/action/action_context.py
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ActionContext:
+    """
+    Minimal kernel-safe action context.
+
+    Kernel invariants:
+    - immutable
+    - no backend dependency
+    - no place/control coupling
+    """
+
+    user_id: str
+    responsibility_mode: str = "standard"

arvis/action/action_decision.py

@@ -0,0 +1,26 @@
+# arvis/action/action_decision.py
+
+from dataclasses import dataclass
+from typing import Any
+
+from .action_mode import ActionMode
+
+
+@dataclass(frozen=True)
+class ActionDecision:
+    """
+    Declarative result of evaluating an action.
+
+    Kernel invariants:
+    - immutable
+    - no execution
+    - explicit decision surface
+    """
+
+    allowed: bool
+    requires_user_validation: bool = False
+    denied_reason: str | None = None
+    audit_required: bool = False
+    tool: str | None = None
+    tool_payload: dict[str, Any] | None = None
+    action_mode: ActionMode = ActionMode.ASSISTED

arvis/action/action_evaluator.py

@@ -0,0 +1,97 @@
+# arvis/action/action_evaluator.py
+
+from __future__ import annotations
+
+from typing import Any
+
+from arvis.action.action_context import ActionContext
+from arvis.math.signals import RiskSignal
+
+from .action_decision import ActionDecision
+from .action_mapper import map_verdict_to_action
+from .action_template import ActionTemplate
+
+
+def evaluate_action(
+    verdict: Any,
+    template: ActionTemplate,
+    risk: RiskSignal,
+    context: ActionContext | None = None,
+) -> ActionDecision:
+    """
+    Context-aware action evaluation.
+
+    Combines:
+    - cognitive verdict
+    - action capabilities
+    - system risk
+
+    Kernel invariants:
+    - deterministic
+    - no side effects
+    - no external dependencies
+    """
+
+    base_decision = map_verdict_to_action(verdict)
+
+    # --------------------------------------------------
+    # Risk overrides
+    # --------------------------------------------------
+
+    # High risk + destructive action → block
+    if float(risk) > 0.7 and template.writes_data:
+        return ActionDecision(
+            allowed=False,
+            requires_user_validation=False,
+            denied_reason="high_risk_write_block",
+            audit_required=True,
+            action_mode=base_decision.action_mode,
+        )
+
+    # External trigger + medium risk → require validation
+    if float(risk) > 0.4 and template.triggers_external:
+        return ActionDecision(
+            allowed=True,
+            requires_user_validation=True,
+            denied_reason=None,
+            audit_required=True,
+            action_mode=base_decision.action_mode,
+        )
+
+    # Irreversible + any risk → require validation
+    if not template.reversible and float(risk) > 0.2:
+        return ActionDecision(
+            allowed=True,
+            requires_user_validation=True,
+            denied_reason=None,
+            audit_required=True,
+            action_mode=base_decision.action_mode,
+        )
+
+    # --------------------------------------------------
+    # Context overrides (user responsibility)
+    # --------------------------------------------------
+
+    if context is not None:
+        # Strict mode → force validation
+        if context.responsibility_mode == "strict":
+            return ActionDecision(
+                allowed=base_decision.allowed,
+                requires_user_validation=True,
+                denied_reason=base_decision.denied_reason,
+                audit_required=True,
+                action_mode=base_decision.action_mode,
+            )
+
+        # Autonomous mode → reduce friction (safe only)
+        if context.responsibility_mode == "autonomous":
+            if base_decision.allowed and float(risk) < 0.3:
+                return ActionDecision(
+                    allowed=True,
+                    requires_user_validation=False,
+                    denied_reason=None,
+                    audit_required=False,
+                    action_mode=base_decision.action_mode,
+                )
+
+    return base_decision

arvis/action/action_mapper.py

@@ -0,0 +1,47 @@
+# arvis/action/action_mapper.py
+
+from __future__ import annotations
+
+from arvis.math.lyapunov.lyapunov_gate import LyapunovVerdict
+
+from .action_decision import ActionDecision
+from .action_mode import ActionMode
+
+
+def map_verdict_to_action(verdict: LyapunovVerdict) -> ActionDecision:
+    """
+    Pure mapping from cognitive verdict → action decision.
+
+    Kernel invariants:
+    - no side effects
+    - deterministic
+    - no external dependency
+    - no pipeline coupling
+    """
+
+    if verdict == LyapunovVerdict.ABSTAIN:
+        return ActionDecision(
+            allowed=False,
+            requires_user_validation=False,
+            denied_reason="stability_guard",
+            audit_required=True,
+            action_mode=ActionMode.MANUAL,
+        )
+
+    if verdict == LyapunovVerdict.REQUIRE_CONFIRMATION:
+        return ActionDecision(
+            allowed=True,
+            requires_user_validation=True,
+            denied_reason=None,
+            audit_required=True,
+            action_mode=ActionMode.ASSISTED,
+        )
+
+    # ALLOW
+    return ActionDecision(
+        allowed=True,
+        requires_user_validation=False,
+        denied_reason=None,
+        audit_required=False,
+        action_mode=ActionMode.AUTOMATIC,
+    )

arvis/action/action_mode.py

@@ -0,0 +1,17 @@
+# arvis/action/action_mode.py
+
+from enum import StrEnum
+
+
+class ActionMode(StrEnum):
+    """
+    Describes how an action is initiated and validated.
+
+    Kernel invariant:
+    - declarative only
+    """
+
+    MANUAL = "manual"
+    ASSISTED = "assisted"
+    AUTOMATIC = "automatic"
+    BLOCKED = "blocked"

arvis/action/action_policy.py

@@ -0,0 +1,61 @@
+# arvis/action/action_policy.py
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from arvis.action.action_decision import ActionDecision
+from arvis.action.action_mode import ActionMode
+from arvis.math.signals import RiskSignal
+
+
+@dataclass(frozen=True)
+class ActionPolicy:
+    """
+    Global policy layer (system-level constraints)
+
+    ZKCS-safe:
+    - deterministic
+    - no external calls
+    """
+
+    max_risk_threshold: float = 0.85
+    require_audit_above: float = 0.6
+
+    def apply(
+        self,
+        decision: ActionDecision,
+        risk: RiskSignal,
+    ) -> ActionDecision:
+        # --------------------------------------------------
+        # 1. Hard block (system safety)
+        # --------------------------------------------------
+        if float(risk) >= self.max_risk_threshold:
+            return ActionDecision(
+                allowed=False,
+                requires_user_validation=False,
+                denied_reason="policy_risk_threshold",
+                audit_required=True,
+                tool=decision.tool,
+                tool_payload=decision.tool_payload,
+                action_mode=ActionMode.BLOCKED,
+            )
+
+        # --------------------------------------------------
+        # 2. Force audit
+        # --------------------------------------------------
+        if float(risk) >= self.require_audit_above:
+            return ActionDecision(
+                allowed=decision.allowed,
+                requires_user_validation=decision.requires_user_validation,
+                denied_reason=decision.denied_reason,
+                audit_required=True,
+                tool=decision.tool,
+                tool_payload=decision.tool_payload,
+                action_mode=decision.action_mode,
+            )
+
+        # --------------------------------------------------
+        # 3. passthrough
+        # --------------------------------------------------
+        return decision

arvis/action/action_resolver.py

@@ -0,0 +1,34 @@
+# arvis/action/action_resolver.py
+
+from __future__ import annotations
+
+from typing import Any
+
+from arvis.action.action_template import ActionTemplate
+
+
+def resolve_action(decision_result: Any) -> ActionTemplate:
+    """
+    Resolve an ActionTemplate from a cognitive decision.
+
+    Kernel invariants:
+    - deterministic
+    - no side effects
+    - no external dependency
+    - no pipeline coupling
+    """
+
+    # Minimal v1 strategy:
+    # fallback to generic safe action
+
+    # You can branch later on decision_result.reason, intent, etc.
+
+    return ActionTemplate(
+        action_id="default_read",
+        description="default safe read action",
+        reads_data=True,
+        writes_data=False,
+        triggers_external=False,
+        risk_level="low",
+        reversible=True,
+    )

arvis/action/action_template.py

@@ -0,0 +1,28 @@
+# arvis/action/action_template.py
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ActionTemplate:
+    """
+    Declarative description of a possible action.
+
+    Kernel invariants:
+    - immutable
+    - no execution
+    - no side effects
+    - capability description only
+    """
+
+    action_id: str
+    description: str
+
+    reads_data: bool = False
+    writes_data: bool = False
+    triggers_external: bool = False
+
+    risk_level: str = "low"
+    reversible: bool = True
+
+    user_facing_label: str | None = None

arvis/adapters/__init__.py

@@ -0,0 +1,10 @@
+# arvis/adapters/__init__.py
+"""
+ARVIS adapters package.
+"""
+
+from .registry import get_llm_adapter
+
+__all__ = [
+    "get_llm_adapter",
+]

arvis/adapters/ir/adaptive_adapter.py

@@ -0,0 +1,20 @@
+# arvis/adapters/ir/adaptive_adapter.py
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AdaptiveIRAdapter:
+    @staticmethod
+    def from_adaptive(snapshot: Any) -> dict[str, Any] | None:
+        if snapshot is None:
+            return None
+
+        return {
+            "schema_version": "v1",
+            "available": True,
+            "stability_band": getattr(snapshot, "band", None),
+            "veto": bool(getattr(snapshot, "is_unstable", False)),
+            "margin": getattr(snapshot, "margin", None),
+        }

arvis/adapters/ir/cognitive_ir_builder.py

@@ -0,0 +1,50 @@
+# arvis/adapters/ir/cognitive_ir_builder.py
+
+from __future__ import annotations
+
+from typing import Any
+
+from arvis.ir.cognitive_ir import CognitiveIR
+
+
+class CognitiveIRBuilder:
+    @staticmethod
+    def from_context(ctx: Any) -> CognitiveIR:
+        """
+        Build canonical IR from pipeline context.
+
+        Pure projection:
+        - no logic
+        - no mutation
+        - no side effects
+        """
+
+        tool_results: list[dict[str, Any]] | None = None
+
+        extra = getattr(ctx, "extra", None)
+        if isinstance(extra, dict):
+            results = extra.get("tool_results", [])
+            if results:
+                tool_results = [
+                    {
+                        "tool_name": r.tool_name,
+                        "success": r.success,
+                        "output": r.output,
+                        "error": r.error,
+                        "latency_ms": getattr(r, "latency_ms", None),
+                    }
+                    for r in results
+                ]
+
+        return CognitiveIR(
+            input=getattr(ctx, "ir_input", None),
+            context=getattr(ctx, "ir_context", None),
+            decision=getattr(ctx, "ir_decision", None),
+            state=getattr(ctx, "ir_state", None),
+            gate=getattr(ctx, "ir_gate", None),
+            projection=getattr(ctx, "ir_projection", None),
+            validity=getattr(ctx, "ir_validity", None),
+            stability=getattr(ctx, "ir_stability", None),
+            adaptive=getattr(ctx, "ir_adaptive", None),
+            tools=tool_results,
+        )

arvis/adapters/ir/decision_adapter.py

@@ -0,0 +1,154 @@
+# arvis/adapters/ir/decision_adapter.py
+
+from __future__ import annotations
+
+from hashlib import sha256
+from json import dumps
+from typing import Any
+
+from arvis.ir.decision import (
+    CognitiveActionIR,
+    CognitiveConflictIR,
+    CognitiveDecisionIR,
+    CognitiveGapIR,
+    CognitiveKnowledgeIR,
+    CognitiveUncertaintyIR,
+)
+
+
+def _hash(payload: dict[str, Any]) -> str:
+    return sha256(dumps(payload, sort_keys=True, default=str).encode()).hexdigest()
+
+
+def _string_value(value: object | None, default: str = "") -> str:
+    if value is None:
+        return default
+    enum_value = getattr(value, "value", None)
+    if isinstance(enum_value, str):
+        return enum_value
+    return str(value)
+
+
+def _normalize_reason_codes(value: object | None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, (list, tuple)):
+        return tuple(str(x).strip() for x in value if str(x).strip())
+    raw = str(value)
+    return tuple(part.strip() for part in raw.split("|") if part.strip())
+
+
+class DecisionIRAdapter:
+    @staticmethod
+    def from_result(result: object) -> CognitiveDecisionIR:
+        reason_codes = _normalize_reason_codes(
+            getattr(result, "reason_codes", None) or getattr(result, "reason", None)
+        )
+
+        actions = tuple(
+            CognitiveActionIR(
+                action_id=str(getattr(a, "action_id", "unknown")),
+                category=str(getattr(a, "category", "unknown")),
+                severity=DecisionIRAdapter._severity(a),
+                requires_confirmation=DecisionIRAdapter._severity(a) != "safe",
+                parameters=getattr(a, "parameters", {}) or {},
+            )
+            for a in (getattr(result, "proposed_actions", []) or [])
+        )
+
+        gaps = tuple(
+            CognitiveGapIR(
+                gap_type=_string_value(getattr(g, "type", None), "unknown"),
+                severity=_string_value(getattr(g, "severity", None), "medium"),
+                description=str(getattr(g, "description", "")),
+            )
+            for g in (getattr(result, "gaps", []) or [])
+        )
+
+        conflicts = tuple(
+            CognitiveConflictIR(
+                conflict_type=_string_value(getattr(c, "type", None), "unknown"),
+                severity=_string_value(getattr(c, "severity", None), "high"),
+                description=str(getattr(c, "description", "")),
+                resolvable_by_confirmation=bool(
+                    getattr(c, "resolvable_by_confirmation", True)
+                ),
+            )
+            for c in (getattr(result, "conflicts", []) or [])
+        )
+
+        knowledge_snapshot = getattr(result, "knowledge_snapshot", None)
+        knowledge = None
+        if knowledge_snapshot is not None:
+            knowledge = CognitiveKnowledgeIR(
+                state=_string_value(
+                    getattr(knowledge_snapshot, "state", None), "unknown"
+                ).lower(),
+                support_level=getattr(knowledge_snapshot, "support_level", None),
+            )
+
+        uncertainty = tuple(
+            CognitiveUncertaintyIR(
+                axis=_string_value(getattr(u, "axis", None), "epistemic"),
+                level=float(getattr(u, "level", 0.5)),
+                explanation=getattr(u, "explanation", None),
+            )
+            for u in (getattr(result, "uncertainty_frames", []) or [])
+        )
+
+        memory_intent = _string_value(
+            getattr(result, "memory_intent", None), "none"
+        ).lower()
+
+        payload = {
+            "reason_codes": reason_codes,
+            "memory_intent": memory_intent,
+            "actions": [a.action_id for a in actions],
+            "gaps": [g.gap_type for g in gaps],
+            "conflicts": [c.conflict_type for c in conflicts],
+        }
+
+        return CognitiveDecisionIR(
+            decision_id=_hash(payload),
+            decision_kind=DecisionIRAdapter._kind(reason_codes, memory_intent),
+            memory_intent=memory_intent,
+            reason_codes=reason_codes,
+            proposed_actions=actions,
+            gaps=gaps,
+            conflicts=conflicts,
+            reasoning_intents=tuple(
+                _string_value(x)
+                for x in (getattr(result, "reasoning_intents", []) or [])
+            ),
+            uncertainty_frames=uncertainty,
+            knowledge=knowledge,
+            context_hints=getattr(result, "context_hints", {}) or {},
+        )
+
+    @staticmethod
+    def _kind(reason_codes: tuple[str, ...], memory_intent: str) -> str:
+        tokens = set(reason_codes)
+
+        if "action_request" in tokens:
+            return "action"
+        if "search_user_files" in tokens:
+            return "action"
+        if memory_intent not in {"", "none"}:
+            return "memory"
+        if "conversation" in tokens:
+            return "conversational"
+        if "search" in tokens or "informational_query" in tokens:
+            return "informational"
+        if "meta_query" in tokens:
+            return "meta"
+        return "unknown"
+
+    @staticmethod
+    def _severity(action: object) -> str:
+        action_id = str(getattr(action, "action_id", ""))
+
+        if action_id in {"search_user_files", "retrieve", "summarize"}:
+            return "safe"
+        if action_id == "memory_store":
+            return "confirm"
+        return "confirm"