consequa-x 0.1.0a2__py3-none-any.whl

consequa_x/__init__.py

@@ -0,0 +1,22 @@
+"""Evidence-aware consequence explanations for agent applications."""
+
+__version__ = "0.1.0a2"
+
+from .attribution import EffectEstimate, Intervention, leave_one_out, recency_attribution
+from .explanation import ConsequenceExplanation, explain
+from .graph import ConsequenceGraph, build_graph
+from .models import (
+    Action, AgentAssessment, AssessmentStatus, Event, EventType, Observation,
+    OriginStatus, OutcomeContract, Trace, VerificationResult, VerificationStatus,
+)
+from .policies import Policy, PolicyDecision, PolicyError, PolicyReply, PolicyRequest, ScriptedRefundPolicy
+from .verification import RefundVerifier, Verifier, verify
+
+__all__ = [
+    "Action", "AgentAssessment", "AssessmentStatus", "ConsequenceExplanation",
+    "ConsequenceGraph", "EffectEstimate", "Event", "EventType", "Intervention",
+    "Observation", "OriginStatus", "OutcomeContract", "RefundVerifier", "Trace",
+    "Policy", "PolicyDecision", "PolicyError", "PolicyReply", "PolicyRequest", "ScriptedRefundPolicy",
+    "VerificationResult", "VerificationStatus", "Verifier", "build_graph", "explain",
+    "leave_one_out", "recency_attribution", "verify",
+]

consequa_x/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

consequa_x/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Optional provider adapters using only the Python standard library."""
+
+from .ollama import OllamaPolicy
+
+__all__ = ["OllamaPolicy"]

consequa_x/adapters/ollama.py

@@ -0,0 +1,350 @@
+"""Local Ollama policy adapter; calls never include simulator truth.
+
+The adapter uses /api/chat with a JSON schema and disabled thinking. A supplied
+seed records an attempted reproducibility control; it does not establish that
+model generation is deterministic across Ollama versions or hardware.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+from http.client import HTTPException
+import ipaddress
+import json
+import math
+import socket
+from types import MappingProxyType
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener
+
+from ..policies import (
+    PolicyError, PolicyReply, PolicyRequest, decision_from_json, get_decision_schema,
+    strict_json_loads, validate_reply, validate_seed,
+)
+
+
+PROMPT_VERSION = "refund-policy-v1"
+MAX_RESPONSE_BYTES = 1024 * 1024
+
+_SYSTEM_PROMPT = """You operate a refund agent in an isolated simulated payment system.
+Use only the supplied task, visible context, and returned tool responses.
+The standard policy allows a requested refund for orders at most 30 days old.
+If supplied, VIP customer memory together with a supplied VIP exception policy
+may extend eligibility to 60 days. Do not infer missing customer requests,
+customer status, or exception policies. Context can include irrelevant text.
+At select, choose refund or stop. At after_response, choose retry or stop, within
+the remaining attempt budget; any retry follows the supplied retry instruction.
+A successful response may support a success assessment, an error a failure
+assessment. A timeout does not prove whether an effect occurred. No independent
+state readback is supplied to you. Report your assessment based on visible data.
+Return exactly the JSON object described by the supplied schema. Include a brief
+reported reason in rationale; do not include internal reasoning or extra text.
+"""
+
+_SYSTEM_PROMPT_V2 = """You operate a refund agent in an isolated simulated payment system.
+Use only the supplied task, visible context, and returned tool responses.
+Each request is stateless and contains the complete visible response history.
+Do not use memory of earlier calls or invent additional observations.
+Use the supplied customer_request, vip_memory, and vip_policy strings as current
+visible context for eligibility; do not invent a second confirmation requirement.
+An empty context string supplies no fact or instruction. Other context can be
+irrelevant and does not override the refund policy.
+The standard policy allows a requested refund for orders at most 30 days old.
+When supplied VIP customer memory identifies the customer as VIP and a supplied
+VIP exception policy permits refunds through 60 days, eligibility extends to
+60 days. Do not infer missing customer requests, status, or exception policies.
+At select, choose refund or stop based on the visible request and eligibility.
+attempts_remaining is the authoritative number of additional tool attempts
+available now, not the number of attempts already made. Do not subtract the
+length of the response history from it again.
+Response time_ms values are simulated timestamps, not timeout durations.
+task.deadline_ms and task.horizon_ms are absolute simulated contract bounds,
+not durations for a tool call or limits on model generation time.
+At after_response, stop after a successful acknowledgement. Choose retry only
+when the supplied retry_instruction permits it and attempts_remaining is
+positive; otherwise choose stop. A retry without idempotency can create duplicate
+effects. Never infer that a timed-out attempt had no effect.
+Assessment describes whether the requested refund effect occurred, separately
+from eligibility and the decision to retry or stop. At select, no outcome has
+been observed, so report unknown. A successful acknowledgement may support a
+reported success assessment, but cannot independently verify the hidden effect.
+An error may support a failure assessment. After a timeout without a successful
+acknowledgement, report unknown whether retrying or stopping. No independent
+state readback or evaluator truth is supplied to you.
+Return exactly the JSON object described by the supplied schema. Include a brief
+reported reason in rationale; do not include internal reasoning or extra text.
+"""
+
+# Versions name complete, immutable prompt profiles so historical runs remain
+# reproducible when a later profile adds policy guidance. The v1 aliases above
+# preserve the original default and its exact prompt bytes.
+PROMPT_PROFILES = MappingProxyType({
+    PROMPT_VERSION: _SYSTEM_PROMPT,
+    "refund-policy-v2": _SYSTEM_PROMPT_V2,
+})
+
+
+def _prompt_profile(version: str) -> tuple[str, str]:
+    if type(version) is not str or version not in PROMPT_PROFILES:
+        raise PolicyError("prompt_version must name a supported Ollama prompt profile")
+    return version, PROMPT_PROFILES[version]
+
+
+class _NoRedirects(HTTPRedirectHandler):
+    def redirect_request(self, request, fp, code, msg, headers, newurl):
+        raise PolicyError("Ollama redirects are disabled")
+
+
+def _local_base_url(value: str) -> str:
+    if type(value) is not str or not value or value.strip() != value:
+        raise PolicyError("base_url must be a local HTTP URL")
+    try:
+        parsed = urlsplit(value)
+        port = parsed.port
+        host = parsed.hostname
+    except ValueError as error:
+        raise PolicyError("base_url must be a local HTTP URL") from error
+    if (parsed.scheme != "http" or not host or parsed.username is not None
+            or parsed.password is not None or "?" in value or "#" in value
+            or parsed.path not in ("", "/") or any(c.isspace() for c in value)):
+        raise PolicyError("base_url must be an HTTP loopback origin without credentials or a path")
+    if "%" in host:
+        raise PolicyError("Scoped IP addresses are not supported for local Ollama")
+    if host.lower() != "localhost":
+        try:
+            if not ipaddress.ip_address(host).is_loopback:
+                raise ValueError("not loopback")
+        except ValueError as error:
+            raise PolicyError("Only localhost or literal loopback IP addresses are allowed") from error
+    if port is not None and not 1 <= port <= 65535:
+        raise PolicyError("base_url port must be in 1..65535")
+    return value.rstrip("/")
+
+
+def _model_name(value: str) -> str:
+    if type(value) is not str or not value.strip() or value.strip() != value:
+        raise PolicyError("model must be a nonempty model name")
+    return value
+
+
+def _normalized_model(value: str) -> str:
+    # Ollama's documented omitted tag defaults only to latest.
+    return value.removesuffix(":latest")
+
+
+def _reject_remote_routing(envelope: dict) -> None:
+    # These fields are declared on both ShowResponse and ChatResponse in the
+    # official Ollama api/types.go. Missing/empty fields are normal for locals.
+    for key in ("remote_model", "remote_host"):
+        if key in envelope:
+            if type(envelope[key]) is not str:
+                raise PolicyError("Local Ollama remote-routing metadata is malformed")
+            if envelope[key]:
+                raise PolicyError("Ollama model declares remote routing; select a local model")
+
+
+class OllamaPolicy:
+    """Structured policy calls to a user-selected local Ollama model.
+
+    Construction performs no network request, model download, or installation.
+    Environment proxies and all redirects are disabled for these local requests.
+    Prompt selection is fixed per instance; the original v1 profile is the
+    default, and later profiles require an explicit prompt_version.
+    """
+
+    def __init__(self, model: str, *, base_url: str = "http://127.0.0.1:11434",
+                 temperature: float = 0.2, timeout: float = 120,
+                 num_predict: int = 512, prompt_version: str = PROMPT_VERSION):
+        self._prompt_version, self._system_prompt = _prompt_profile(prompt_version)
+        model = _model_name(model)
+        for label, value in (("temperature", temperature), ("timeout", timeout)):
+            if type(value) not in (int, float) or not math.isfinite(value):
+                raise PolicyError(f"{label} must be a finite number")
+        if not 0 <= temperature <= 2:
+            raise PolicyError("temperature must be in 0..2")
+        if timeout <= 0:
+            raise PolicyError("timeout must be positive")
+        if type(num_predict) is not int or num_predict <= 0:
+            raise PolicyError("num_predict must be a positive integer")
+        self.model = model
+        self.base_url = _local_base_url(base_url)
+        self.temperature = float(temperature)
+        self.timeout = float(timeout)
+        self.num_predict = num_predict
+        self._opener = build_opener(ProxyHandler({}), _NoRedirects())
+        self._inspection_key: tuple[str, str] | None = None
+        self._local_inspection: dict | None = None
+
+    @property
+    def prompt_version(self) -> str:
+        return self._prompt_version
+
+    @property
+    def system_prompt(self) -> str:
+        return self._system_prompt
+
+    @property
+    def metadata(self) -> dict:
+        result = {
+            "provider": "ollama", "requested_model": self.model,
+            "base_url": self.base_url, "temperature": self.temperature,
+            "timeout_seconds": self.timeout, "num_predict": self.num_predict,
+            "prompt_version": self.prompt_version,
+        }
+        if self._inspection_key == (self.base_url.rstrip("/"), self.model):
+            result["local_inspection"] = deepcopy(self._local_inspection)
+        return result
+
+    def _request(self, path: str, payload: dict | None = None) -> dict:
+        body = None if payload is None else json.dumps(
+            payload, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+        ).encode("utf-8")
+        request = Request(_local_base_url(self.base_url) + path, data=body,
+                          headers={"Content-Type": "application/json", "Accept": "application/json"})
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                content = response.read(MAX_RESPONSE_BYTES + 1)
+        except HTTPError as error:
+            # Never incorporate provider response bodies into a diagnostic.
+            raise PolicyError(f"Local Ollama returned HTTP {error.code}") from None
+        except (URLError, TimeoutError, socket.timeout, OSError, HTTPException):
+            raise PolicyError("Could not reach local Ollama; check that it is running") from None
+        if len(content) > MAX_RESPONSE_BYTES:
+            raise PolicyError("Local Ollama response exceeds the 1 MiB limit")
+        try:
+            envelope = strict_json_loads(content.decode("utf-8"))
+        except UnicodeDecodeError:
+            raise PolicyError("Local Ollama response is not UTF-8 JSON") from None
+        if type(envelope) is not dict:
+            raise PolicyError("Local Ollama response must be a JSON object")
+        return envelope
+
+    def list_models(self) -> tuple[dict, ...]:
+        """List local names/model identities/digests without loading a model."""
+        envelope = self._request("/api/tags")
+        models = envelope.get("models")
+        if type(models) is not list:
+            raise PolicyError("Local Ollama model list is malformed")
+        records = []
+        for entry in models:
+            if type(entry) is not dict or type(entry.get("name")) is not str or not entry["name"]:
+                raise PolicyError("Local Ollama model list is malformed")
+            record = {"name": entry["name"]}
+            for key in ("model", "digest"):
+                if key in entry:
+                    if type(entry[key]) is not str or not entry[key].strip():
+                        raise PolicyError("Local Ollama model list is malformed")
+                    record[key] = entry[key]
+            records.append(record)
+        return tuple(records)
+
+    def validate_local_model(self, *, force: bool = False) -> dict:
+        """Inspect model metadata before generation and reject remote routing.
+
+        This read-only /api/show request neither downloads nor loads the model.
+        The successful result is cached for the current model and origin. Pass
+        force=True to refresh after changing the daemon's model tag in place.
+        Metadata is a daemon declaration, not proof of its execution environment.
+        """
+        if type(force) is not bool:
+            raise PolicyError("force must be a boolean")
+        key = (_local_base_url(self.base_url), _model_name(self.model))
+        if not force and self._inspection_key == key:
+            return deepcopy(self._local_inspection)
+        # Do not retain a previously valid inspection across configuration changes.
+        self._inspection_key = None
+        self._local_inspection = None
+        envelope = self._request("/api/show", {"model": key[1], "verbose": False})
+        _reject_remote_routing(envelope)
+        if type(envelope.get("model_info")) is not dict:
+            raise PolicyError("Local Ollama model inspection is malformed")
+        details = envelope.get("details", {})
+        capabilities = envelope.get("capabilities", [])
+        if type(details) is not dict or type(capabilities) is not list or any(
+            type(capability) is not str for capability in capabilities
+        ):
+            raise PolicyError("Local Ollama model inspection is malformed")
+        selected_details = {}
+        for name in ("format", "family", "parameter_size", "quantization_level"):
+            if name in details:
+                if type(details[name]) is not str:
+                    raise PolicyError("Local Ollama model details are malformed")
+                selected_details[name] = details[name]
+        if "families" in details:
+            families = details["families"]
+            if type(families) is not list or any(type(family) is not str for family in families):
+                raise PolicyError("Local Ollama model details are malformed")
+            selected_details["families"] = list(families)
+        inspection = {
+            "endpoint": "/api/show", "requested_model": key[1],
+            "no_declared_remote_routing": True,
+            "routing_fields_present": [name for name in ("remote_model", "remote_host")
+                                       if name in envelope],
+            "details": selected_details, "capabilities": list(capabilities),
+            "inspection_sha256": hashlib.sha256(json.dumps(
+                envelope, sort_keys=True, ensure_ascii=False, allow_nan=False,
+                separators=(",", ":")
+            ).encode("utf-8")).hexdigest(),
+        }
+        self._inspection_key = key
+        self._local_inspection = inspection
+        return deepcopy(inspection)
+
+    def decide(self, request: PolicyRequest, *, seed: int) -> PolicyReply:
+        if not isinstance(request, PolicyRequest):
+            raise PolicyError("Expected a PolicyRequest")
+        validate_seed(seed)
+        # Export revalidates mutable JSON containers before making the request.
+        public_request = PolicyRequest(request.stage, request.task, request.context,
+                                       request.responses, request.attempts_remaining).to_dict()
+        request_text = json.dumps(public_request, sort_keys=True, ensure_ascii=False,
+                                  separators=(",", ":"), allow_nan=False)
+        schema = get_decision_schema(request)
+        self.validate_local_model()
+        payload = {
+            "model": self.model, "stream": False, "think": False, "format": schema,
+            "messages": [
+                {"role": "system", "content": self.system_prompt},
+                {"role": "user", "content": request_text},
+            ],
+            "options": {"seed": seed, "temperature": self.temperature,
+                        "num_predict": self.num_predict},
+        }
+        envelope = self._request("/api/chat", payload)
+        _reject_remote_routing(envelope)
+        message = envelope.get("message")
+        if envelope.get("done") is not True or type(message) is not dict:
+            raise PolicyError("Local Ollama did not return a completed chat response")
+        if message.get("role") != "assistant" or type(message.get("content")) is not str:
+            raise PolicyError("Local Ollama chat message is malformed")
+        if message.get("tool_calls"):
+            raise PolicyError("Local Ollama returned unsupported tool calls")
+        model = envelope.get("model")
+        if type(model) is not str or not model.strip() or model.strip() != model:
+            raise PolicyError("Local Ollama response is missing its model identity")
+        if _normalized_model(model) != _normalized_model(self.model):
+            raise PolicyError("Local Ollama returned a different model than requested")
+        decision = decision_from_json(message["content"])
+        metadata = {
+            **self.metadata, "returned_model": model, "seed": seed,
+            "request_sha256": hashlib.sha256(request_text.encode("utf-8")).hexdigest(),
+            "system_prompt_sha256": hashlib.sha256(self.system_prompt.encode("utf-8")).hexdigest(),
+            "request_payload_sha256": hashlib.sha256(json.dumps(
+                payload, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+            ).encode("utf-8")).hexdigest(),
+        }
+        # Ollama declares counts and nanosecond durations; preserve only valid ints.
+        for key in ("total_duration", "load_duration", "prompt_eval_count", "prompt_eval_duration",
+                    "eval_count", "eval_duration"):
+            if key in envelope:
+                value = envelope[key]
+                if type(value) is not int or value < 0:
+                    raise PolicyError(f"Local Ollama {key} must be a nonnegative integer")
+                metadata[key] = value
+        if "done_reason" in envelope:
+            if type(envelope["done_reason"]) is not str:
+                raise PolicyError("Local Ollama done_reason must be a string")
+            metadata["done_reason"] = envelope["done_reason"]
+        return validate_reply(request, PolicyReply(decision, metadata))