decisioncontrol 0.1.0__py3-none-any.whl

decisioncontrol/models.py

@@ -0,0 +1,171 @@
+"""Versioned, provider-neutral inputs for a bounded ticket action."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+import math
+
+
+class DecisionError(ValueError):
+    """Invalid input or evidence; no action is authorized."""
+
+
+class StateError(DecisionError):
+    """The requested lifecycle transition is not permitted."""
+
+
+class Verdict(str, Enum):
+    ALLOW = "ALLOW"
+    DENY = "DENY"
+    REVIEW = "REVIEW"
+    ABSTAIN = "ABSTAIN"
+
+
+class Status(str, Enum):
+    READY = "READY"
+    PENDING_REVIEW = "PENDING_REVIEW"
+    DENIED = "DENIED"
+    ABSTAINED = "ABSTAINED"
+    REJECTED = "REJECTED"
+    CANCELLED = "CANCELLED"
+    EXECUTED = "EXECUTED"
+    STALE = "STALE"
+
+
+def _fields(value, required, optional=()):
+    if not isinstance(value, Mapping):
+        raise DecisionError("expected a JSON object")
+    missing = set(required) - value.keys()
+    extra = value.keys() - set(required) - set(optional)
+    if missing or extra:
+        raise DecisionError(f"invalid fields: missing {sorted(missing)}, unexpected {sorted(extra, key=str)}")
+    return value
+
+
+def _text(value, name):
+    if not isinstance(value, str) or not value or value != value.strip():
+        raise DecisionError(f"{name} must be a nonempty string without surrounding whitespace")
+    return value
+
+
+def _probability(value, name):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise DecisionError(f"{name} must be a finite probability in [0, 1]")
+    if not 0 <= value <= 1 or not math.isfinite(value):
+        raise DecisionError(f"{name} must be a finite probability in [0, 1]")
+    return float(value)
+
+
+def _names(value, name, allow_empty=False):
+    if not isinstance(value, (list, tuple)):
+        raise DecisionError(f"{name} must be a list or tuple of names")
+    names = tuple(_text(item, name) for item in value)
+    if (not names and not allow_empty) or len(set(names)) != len(names):
+        raise DecisionError(f"{name} must contain {'unique' if allow_empty else 'one or more unique'} names")
+    return names
+
+
+@dataclass(frozen=True)
+class Recommendation:
+    action: str
+    ticket_id: str
+    destination: str
+    probability: float | None
+    model: str
+    question_version: str
+    refused: bool = False
+
+    def __post_init__(self):
+        for name in ("action", "ticket_id", "destination", "model", "question_version"):
+            _text(getattr(self, name), name)
+        if self.probability is not None:
+            object.__setattr__(self, "probability", _probability(self.probability, "probability"))
+        if not isinstance(self.refused, bool):
+            raise DecisionError("refused must be a boolean")
+
+    def to_dict(self):
+        return {"action": self.action, "ticket_id": self.ticket_id,
+                "destination": self.destination, "probability": self.probability,
+                "model": self.model, "question_version": self.question_version,
+                "refused": self.refused}
+
+    @classmethod
+    def from_dict(cls, value):
+        raw = _fields(value, {"action", "ticket_id", "destination", "model", "question_version"},
+                      {"probability", "refused"})
+        return cls(action=raw["action"], ticket_id=raw["ticket_id"], destination=raw["destination"],
+                   probability=raw.get("probability"), model=raw["model"],
+                   question_version=raw["question_version"], refused=raw.get("refused", False))
+
+
+@dataclass(frozen=True)
+class Ticket:
+    id: str
+    department: str
+    revision: int = 0
+
+    def __post_init__(self):
+        _text(self.id, "ticket id")
+        _text(self.department, "department")
+        if type(self.revision) is not int or self.revision < 0:
+            raise DecisionError("revision must be a nonnegative integer")
+
+    def to_dict(self):
+        return {"id": self.id, "department": self.department, "revision": self.revision}
+
+    @classmethod
+    def from_dict(cls, value):
+        raw = _fields(value, {"id", "department", "revision"})
+        return cls(**raw)
+
+
+@dataclass(frozen=True)
+class RoutingPolicy:
+    version: str
+    allowed_destinations: tuple[str, ...]
+    review_destinations: tuple[str, ...]
+    reviewers: tuple[str, ...]
+    min_probability: float = 0.8
+
+    def __post_init__(self):
+        _text(self.version, "policy version")
+        object.__setattr__(self, "allowed_destinations", _names(self.allowed_destinations, "allowed_destinations"))
+        object.__setattr__(self, "review_destinations", _names(self.review_destinations, "review_destinations", True))
+        object.__setattr__(self, "reviewers", _names(self.reviewers, "reviewers"))
+        object.__setattr__(self, "min_probability", _probability(self.min_probability, "min_probability"))
+        if not set(self.review_destinations) <= set(self.allowed_destinations):
+            raise DecisionError("review_destinations must be a subset of allowed_destinations")
+
+    def to_dict(self):
+        return {"version": self.version, "allowed_destinations": list(self.allowed_destinations),
+                "review_destinations": list(self.review_destinations), "reviewers": list(self.reviewers),
+                "min_probability": self.min_probability}
+
+    @classmethod
+    def from_dict(cls, value):
+        raw = _fields(value, {"version", "allowed_destinations", "review_destinations", "reviewers"},
+                      {"min_probability"})
+        return cls(**raw)
+
+
+@dataclass(frozen=True)
+class Evaluation:
+    verdict: Verdict
+    reasons: tuple[str, ...]
+
+    def __post_init__(self):
+        if not isinstance(self.verdict, Verdict):
+            raise DecisionError("verdict must be a Verdict")
+        object.__setattr__(self, "reasons", _names(self.reasons, "reasons"))
+
+    def to_dict(self):
+        return {"verdict": self.verdict.value, "reasons": list(self.reasons)}
+
+    @classmethod
+    def from_dict(cls, value):
+        raw = _fields(value, {"verdict", "reasons"})
+        try:
+            verdict = Verdict(raw["verdict"])
+        except (ValueError, TypeError) as error:
+            raise DecisionError("unknown verdict") from error
+        return cls(verdict, raw["reasons"])

decisioncontrol/policy.py

@@ -0,0 +1,32 @@
+"""Deterministic authorization; model probabilities never grant permissions."""
+
+from .models import Evaluation, Recommendation, RoutingPolicy, Ticket, Verdict
+
+
+INITIAL_STATUS = {
+    Verdict.ALLOW: "READY",
+    Verdict.REVIEW: "PENDING_REVIEW",
+    Verdict.DENY: "DENIED",
+    Verdict.ABSTAIN: "ABSTAINED",
+}
+
+
+def evaluate(recommendation: Recommendation, ticket: Ticket, policy: RoutingPolicy) -> Evaluation:
+    """Evaluate a proposal against trusted ticket state and a trusted policy snapshot."""
+    if recommendation.ticket_id != ticket.id:
+        return Evaluation(Verdict.DENY, ("ticket_mismatch",))
+    if recommendation.action != "reassign_ticket":
+        return Evaluation(Verdict.DENY, ("action_not_permitted",))
+    if recommendation.destination not in policy.allowed_destinations:
+        return Evaluation(Verdict.DENY, ("destination_not_permitted",))
+    if recommendation.destination == ticket.department:
+        return Evaluation(Verdict.DENY, ("already_assigned",))
+    if recommendation.refused:
+        return Evaluation(Verdict.ABSTAIN, ("model_refused",))
+    if recommendation.probability is None:
+        return Evaluation(Verdict.ABSTAIN, ("probability_unknown",))
+    if recommendation.probability < policy.min_probability:
+        return Evaluation(Verdict.ABSTAIN, ("below_probability_threshold",))
+    if recommendation.destination in policy.review_destinations:
+        return Evaluation(Verdict.REVIEW, ("destination_requires_review",))
+    return Evaluation(Verdict.ALLOW, ("policy_permits_reassignment",))

decisioncontrol/store.py

@@ -0,0 +1,317 @@
+"""Durable decisions and atomic reassignment of a local SQLite ticket queue."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import json
+import hashlib
+from pathlib import Path
+import sqlite3
+from threading import RLock
+from typing import Iterator
+from uuid import uuid4
+
+from . import __version__
+from .evidence import _canonical, _validate_record
+from .models import (
+    DecisionError,
+    Recommendation,
+    RoutingPolicy,
+    StateError,
+    Status,
+    Ticket,
+    _text,
+)
+from .policy import INITIAL_STATUS, evaluate
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds")
+
+
+STORE_SCHEMA_VERSION = 1
+
+
+class PendingDecisions(list):
+    """Valid pending records, with skipped row diagnostics in ``skipped``."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.skipped: list[dict[str, str]] = []
+
+
+class TicketStore:
+    """Store local tickets and frozen decision records.
+
+    Each mutation holds a SQLite write transaction, so independent processes or
+    connections cannot execute the same decision twice. A lock protects use of
+    one instance by multiple threads. Reviewer labels come from the trusted
+    caller; membership in the frozen policy is authorization, not authentication.
+    """
+
+    def __init__(self, db_path: str | Path):
+        self._lock = RLock()
+        self._closed = False
+        self._connection = sqlite3.connect(
+            db_path, timeout=30.0, isolation_level=None, check_same_thread=False,
+        )
+        self._connection.row_factory = sqlite3.Row
+        try:
+            with self._transaction() as connection:
+                version = connection.execute("PRAGMA user_version").fetchone()[0]
+                if version > STORE_SCHEMA_VERSION:
+                    raise DecisionError(f"Unsupported store schema version {version}; supported: {STORE_SCHEMA_VERSION}")
+                connection.execute(
+                    "CREATE TABLE IF NOT EXISTS tickets ("
+                    "id TEXT PRIMARY KEY NOT NULL, department TEXT NOT NULL, "
+                    "revision INTEGER NOT NULL CHECK (revision >= 0))"
+                )
+                connection.execute(
+                    "CREATE TABLE IF NOT EXISTS decisions ("
+                    "id TEXT PRIMARY KEY NOT NULL, created_at TEXT NOT NULL, "
+                    "status TEXT NOT NULL, record TEXT NOT NULL)"
+                )
+                connection.execute(
+                    "CREATE INDEX IF NOT EXISTS decisions_pending "
+                    "ON decisions (status, created_at, id)"
+                )
+                connection.execute(f"PRAGMA user_version = {STORE_SCHEMA_VERSION}")
+        except BaseException:
+            self.close()
+            raise
+
+    def __enter__(self) -> TicketStore:
+        with self._lock:
+            self._ensure_open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+    def close(self) -> None:
+        with self._lock:
+            if not self._closed:
+                self._connection.close()
+                self._closed = True
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise StateError("TicketStore is closed")
+
+    @contextmanager
+    def _transaction(self) -> Iterator[sqlite3.Connection]:
+        with self._lock:
+            self._ensure_open()
+            self._connection.execute("BEGIN IMMEDIATE")
+            try:
+                yield self._connection
+                self._connection.commit()
+            except BaseException:
+                if self._connection.in_transaction:
+                    self._connection.rollback()
+                raise
+
+    def create_ticket(self, ticket_id: str, department: str) -> Ticket:
+        ticket = Ticket.from_dict({"id": ticket_id, "department": department, "revision": 0})
+        with self._transaction() as connection:
+            if connection.execute("SELECT 1 FROM tickets WHERE id = ?", (ticket.id,)).fetchone():
+                raise DecisionError(f"Ticket already exists: {ticket.id}")
+            connection.execute(
+                "INSERT INTO tickets (id, department, revision) VALUES (?, ?, ?)",
+                (ticket.id, ticket.department, ticket.revision),
+            )
+        return ticket
+
+    def _get_ticket(self, ticket_id: str) -> Ticket:
+        if not isinstance(ticket_id, str) or not ticket_id or ticket_id != ticket_id.strip():
+            raise DecisionError("Ticket ID must be a nonempty, stripped string")
+        row = self._connection.execute(
+            "SELECT id, department, revision FROM tickets WHERE id = ?", (ticket_id,),
+        ).fetchone()
+        if row is None:
+            raise DecisionError(f"Unknown ticket: {ticket_id}")
+        return Ticket.from_dict(dict(row))
+
+    def get_ticket(self, ticket_id: str) -> Ticket:
+        with self._lock:
+            self._ensure_open()
+            return self._get_ticket(ticket_id)
+
+    def submit(self, recommendation: Recommendation, policy: RoutingPolicy, proposed_by: str) -> dict:
+        if not isinstance(recommendation, Recommendation) or not isinstance(policy, RoutingPolicy):
+            raise DecisionError("submit requires a Recommendation and a RoutingPolicy")
+        _text(proposed_by, "proposed_by")
+        recommendation = Recommendation.from_dict(recommendation.to_dict())
+        policy = RoutingPolicy.from_dict(policy.to_dict())
+        with self._transaction() as connection:
+            ticket = self._get_ticket(recommendation.ticket_id)
+            evaluation = evaluate(recommendation, ticket, policy)
+            created_at = _now()
+            record = {
+                "schema_version": 3,
+                "produced_by": {"name": "decisioncontrol", "version": __version__},
+                "proposed_by": proposed_by,
+                "policy_sha256": hashlib.sha256(_canonical(policy.to_dict())).hexdigest(),
+                "id": str(uuid4()),
+                "created_at": created_at,
+                "recommendation": recommendation.to_dict(),
+                "ticket": ticket.to_dict(),
+                "policy": policy.to_dict(),
+                "evaluation": evaluation.to_dict(),
+                "status": INITIAL_STATUS[evaluation.verdict],
+                "review": None,
+                "result": None,
+                "events": [{"event": "SUBMITTED", "at": created_at}],
+            }
+            connection.execute(
+                "INSERT INTO decisions (id, created_at, status, record) VALUES (?, ?, ?, ?)",
+                (record["id"], created_at, record["status"], self._serialize(record)),
+            )
+        return record
+
+    @staticmethod
+    def _serialize(record: dict) -> str:
+        return json.dumps(record, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+
+    @staticmethod
+    def _decode(row: sqlite3.Row) -> dict:
+        try:
+            record = json.loads(row["record"])
+        except (json.JSONDecodeError, TypeError, UnicodeError) as exc:
+            raise DecisionError("Stored decision is not valid JSON") from exc
+        _validate_record(record)
+        if (
+            record["id"] != row["id"]
+            or record["created_at"] != row["created_at"]
+            or record["status"] != row["status"]
+        ):
+            raise DecisionError("Stored decision disagrees with its database index")
+        return record
+
+    def _get(self, decision_id: str) -> dict:
+        if not isinstance(decision_id, str) or not decision_id or decision_id != decision_id.strip():
+            raise DecisionError("Decision ID must be a nonempty, stripped string")
+        row = self._connection.execute(
+            "SELECT id, created_at, status, record FROM decisions WHERE id = ?", (decision_id,),
+        ).fetchone()
+        if row is None:
+            raise DecisionError(f"Unknown decision: {decision_id}")
+        return self._decode(row)
+
+    def get(self, decision_id: str) -> dict:
+        with self._lock:
+            self._ensure_open()
+            return self._get(decision_id)
+
+    def pending(self) -> PendingDecisions:
+        with self._lock:
+            self._ensure_open()
+            rows = self._connection.execute(
+                "SELECT id, created_at, status, record FROM decisions "
+                "WHERE status = ? ORDER BY created_at, id",
+                (Status.PENDING_REVIEW.value,),
+            ).fetchall()
+            pending = PendingDecisions()
+            for row in rows:
+                try:
+                    pending.append(self._decode(row))
+                except DecisionError as error:
+                    pending.skipped.append({"id": row["id"], "error": str(error)})
+            return pending
+
+    def _save(self, record: dict) -> None:
+        _validate_record(record)
+        self._connection.execute(
+            "UPDATE decisions SET status = ?, record = ? WHERE id = ?",
+            (record["status"], self._serialize(record), record["id"]),
+        )
+
+    @staticmethod
+    def _authorize_reviewer(record: dict, reviewer: str, note: str) -> None:
+        if not isinstance(reviewer, str) or not reviewer or reviewer != reviewer.strip():
+            raise DecisionError("Reviewer must be a nonempty, stripped identifier")
+        if not isinstance(note, str):
+            raise DecisionError("Review note must be a string")
+        if (record["schema_version"] == 3 and record["evaluation"]["verdict"] == "REVIEW"
+                and reviewer == record["proposed_by"]):
+            raise StateError("The proposer cannot review or cancel their own REVIEW decision")
+        # The frozen policy has already been validated by _get.
+        if reviewer not in record["policy"]["reviewers"]:
+            raise StateError(f"Reviewer is not authorized by this decision's policy: {reviewer}")
+
+    def _review(self, decision_id: str, reviewer: str, note: str, decision: str) -> dict:
+        with self._transaction():
+            record = self._get(decision_id)
+            self._authorize_reviewer(record, reviewer, note)
+            previous = record["review"]
+            if previous is not None and (
+                previous["decision"] == decision
+                and previous["reviewer"] == reviewer
+                and previous["note"] == note
+                and record["status"] != Status.CANCELLED.value
+            ):
+                return record
+            if record["status"] != Status.PENDING_REVIEW.value:
+                raise StateError(f"Cannot record {decision.lower()} review in state {record['status']}")
+            at = _now()
+            record["review"] = {"decision": decision, "reviewer": reviewer, "note": note, "at": at}
+            record["status"] = Status.READY.value if decision == "APPROVED" else Status.REJECTED.value
+            record["events"].append({"event": decision, "at": at})
+            self._save(record)
+            return record
+
+    def approve(self, decision_id: str, reviewer: str, note: str = "") -> dict:
+        return self._review(decision_id, reviewer, note, "APPROVED")
+
+    def reject(self, decision_id: str, reviewer: str, note: str = "") -> dict:
+        return self._review(decision_id, reviewer, note, "REJECTED")
+
+    def cancel(self, decision_id: str, reviewer: str, note: str) -> dict:
+        """Withdraw an unexecuted decision; retain any prior approval and its provenance."""
+        with self._transaction():
+            record = self._get(decision_id)
+            self._authorize_reviewer(record, reviewer, note)
+            if not note.strip():
+                raise DecisionError("Cancellation requires a nonempty reason")
+            if record["status"] == Status.CANCELLED.value:
+                cancellation = record["events"][-1]
+                if cancellation["reviewer"] == reviewer and cancellation["note"] == note:
+                    return record
+                raise StateError("Cancellation is already recorded with a different actor or reason")
+            if record["status"] not in (Status.READY.value, Status.PENDING_REVIEW.value):
+                raise StateError(f"Cannot cancel decision in state {record['status']}")
+            if record["schema_version"] == 1:
+                record["schema_version"] = 2
+            record["status"] = Status.CANCELLED.value
+            record["events"].append({
+                "event": "CANCELLED", "at": _now(), "reviewer": reviewer, "note": note,
+            })
+            self._save(record)
+            return record
+
+    def execute(self, decision_id: str) -> dict:
+        with self._transaction() as connection:
+            record = self._get(decision_id)
+            if record["status"] == Status.EXECUTED.value:
+                return record
+            if record["status"] != Status.READY.value:
+                raise StateError(f"Cannot execute decision in state {record['status']}")
+            frozen_ticket = Ticket.from_dict(record["ticket"])
+            recommendation = Recommendation.from_dict(record["recommendation"])
+            current = self._get_ticket(frozen_ticket.id)
+            at = _now()
+            if current.revision != frozen_ticket.revision or current.department != frozen_ticket.department:
+                record["status"] = Status.STALE.value
+                record["events"].append({"event": "STALE", "at": at})
+            else:
+                result = Ticket(current.id, recommendation.destination, current.revision + 1)
+                connection.execute(
+                    "UPDATE tickets SET department = ?, revision = ? WHERE id = ?",
+                    (result.department, result.revision, result.id),
+                )
+                record["result"] = result.to_dict()
+                record["status"] = Status.EXECUTED.value
+                record["events"].append({"event": "EXECUTED", "at": at})
+            self._save(record)
+            return record