saidso 0.1.0__py3-none-any.whl

saidso/__init__.py

@@ -0,0 +1,57 @@
+"""saidso — a grounding firewall for action-taking AI agents.
+
+Sit between an agent and its consequential tools. Refuse to let the agent
+commit any argument that isn't grounded in what the user actually said — and
+keep a transcript-linked audit trail for every action that does run.
+
+Quick start::
+
+    from saidso import grounded, Policy, Transcript, call_context, AttestationLog
+
+    @grounded(name=Policy.SPOKEN, dob=Policy.SPOKEN)
+    def register_patient(name, dob): ...
+
+    tr = Transcript()
+    tr.add_user("Hi, this is Maria Gomez.")
+    log = AttestationLog()
+
+    with call_context(tr, ledger=log):
+        result = register_patient(name="John Doe", dob="1990-01-01")
+        # -> SteerBack(blocked=True): nothing was said about John Doe / that DOB
+"""
+
+from __future__ import annotations
+
+from .attestation import Attestation, AttestationLog
+from .context import CallContext, call_context, get_context, set_context, reset_context
+from .grounding import GroundingBlocked, GroundingConfig, grounded
+from .policy import DEFAULT_THRESHOLDS, Policy
+from .result import ArgFinding, GroundingResult, Span, SteerBack
+from .transcript import AGENT, SYSTEM, USER, Transcript, Turn
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "grounded",
+    "Policy",
+    "Transcript",
+    "Turn",
+    "USER",
+    "AGENT",
+    "SYSTEM",
+    "call_context",
+    "CallContext",
+    "get_context",
+    "set_context",
+    "reset_context",
+    "SteerBack",
+    "GroundingResult",
+    "GroundingConfig",
+    "GroundingBlocked",
+    "Span",
+    "ArgFinding",
+    "Attestation",
+    "AttestationLog",
+    "DEFAULT_THRESHOLDS",
+    "__version__",
+]

saidso/_fuzz.py

@@ -0,0 +1,49 @@
+"""Fuzzy string matching with a zero-dependency fallback.
+
+Uses ``rapidfuzz`` when it is installed (fast, C-backed) and transparently
+falls back to the stdlib ``difflib`` so ``saidso`` works with no required
+third-party dependencies.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - exercised indirectly
+    from rapidfuzz import fuzz as _rf
+
+    _HAVE_RAPIDFUZZ = True
+except Exception:  # pragma: no cover
+    _HAVE_RAPIDFUZZ = False
+    import difflib
+
+
+def ratio(a: str, b: str) -> float:
+    """Whole-string similarity in ``[0, 1]``."""
+    if not a or not b:
+        return 0.0
+    if _HAVE_RAPIDFUZZ:
+        return _rf.ratio(a, b) / 100.0
+    return difflib.SequenceMatcher(None, a, b).ratio()
+
+
+def partial_ratio(needle: str, haystack: str) -> float:
+    """How well ``needle`` appears *inside* ``haystack``, in ``[0, 1]``.
+
+    This is the workhorse for "did the caller roughly say this?" checks.
+    """
+    if not needle or not haystack:
+        return 0.0
+    if _HAVE_RAPIDFUZZ:
+        return _rf.partial_ratio(needle, haystack) / 100.0
+
+    # difflib fallback: slide a window the size of ``needle`` across ``haystack``.
+    n = len(needle)
+    if n >= len(haystack):
+        return difflib.SequenceMatcher(None, needle, haystack).ratio()
+    best = 0.0
+    step = max(1, n // 4)
+    for i in range(0, len(haystack) - n + 1, step):
+        window = haystack[i : i + n]
+        r = difflib.SequenceMatcher(None, needle, window).ratio()
+        if r > best:
+            best = r
+    return best

saidso/attestation.py

@@ -0,0 +1,74 @@
+"""The provenance ledger: proof that every committed argument was grounded."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .result import ArgFinding
+
+
+@dataclass
+class Attestation:
+    """A receipt: this action ran, and here is what grounded every argument."""
+
+    action: str
+    ts: float
+    call_id: Optional[str]
+    args: List[ArgFinding] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "action": self.action,
+            "ts": self.ts,
+            "call_id": self.call_id,
+            "args": [
+                {
+                    "arg": f.name,
+                    "policy": f.result.policy,
+                    "value": f.result.value,
+                    "confidence": round(f.result.confidence, 4),
+                    "span": f.result.span.to_dict() if f.result.span else None,
+                }
+                for f in self.args
+            ],
+        }
+
+
+class AttestationLog:
+    """Collects attestations in memory and (optionally) appends them as JSONL.
+
+    Pass ``path=`` to persist an audit trail; otherwise records are kept in
+    memory and reachable via :attr:`records`.
+    """
+
+    def __init__(self, path: Optional[str] = None) -> None:
+        self.path = path
+        self._records: List[Attestation] = []
+        self._lock = threading.Lock()
+
+    def record(self, attestation: Attestation) -> Attestation:
+        with self._lock:
+            self._records.append(attestation)
+            if self.path:
+                with open(self.path, "a", encoding="utf-8") as fh:
+                    fh.write(json.dumps(attestation.to_dict()) + "\n")
+        return attestation
+
+    def build(self, action: str, findings: List[ArgFinding], call_id: Optional[str] = None) -> Attestation:
+        return self.record(
+            Attestation(action=action, ts=time.time(), call_id=call_id, args=list(findings))
+        )
+
+    @property
+    def records(self) -> List[Attestation]:
+        return list(self._records)
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def export(self) -> List[dict]:
+        return [a.to_dict() for a in self._records]

saidso/context.py

@@ -0,0 +1,74 @@
+"""Per-call context: the transcript, metadata, clock and attestation sink.
+
+Adapters set this once per call (via :func:`call_context`); the ``@grounded``
+decorator reads it implicitly so action functions stay clean. Values can also
+be passed explicitly to the decorated call via ``_transcript=`` / ``_context=``.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any, Dict, Optional
+
+from .transcript import Transcript
+
+
+@dataclass
+class CallContext:
+    """Everything the firewall needs to judge one call."""
+
+    transcript: Transcript = field(default_factory=Transcript)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    now: Optional[date] = None
+    call_id: Optional[str] = None
+    ledger: Any = None  # AttestationLog | None (avoid import cycle)
+
+
+_CURRENT: contextvars.ContextVar[Optional[CallContext]] = contextvars.ContextVar(
+    "saidso_call_context", default=None
+)
+
+
+def get_context() -> Optional[CallContext]:
+    return _CURRENT.get()
+
+
+def set_context(ctx: Optional[CallContext]) -> contextvars.Token:
+    return _CURRENT.set(ctx)
+
+
+def reset_context(token: contextvars.Token) -> None:
+    _CURRENT.reset(token)
+
+
+@contextmanager
+def call_context(
+    transcript: Optional[Transcript] = None,
+    *,
+    metadata: Optional[Dict[str, Any]] = None,
+    now: Optional[date] = None,
+    call_id: Optional[str] = None,
+    ledger: Any = None,
+):
+    """Scope a :class:`CallContext` for the duration of a call.
+
+    Example::
+
+        with call_context(transcript, metadata={"caller_id": "+1..."}, ledger=log):
+            await register_patient(...)
+    """
+    ctx = CallContext(
+        transcript=transcript if transcript is not None else Transcript(),
+        metadata=metadata or {},
+        now=now,
+        call_id=call_id,
+        ledger=ledger,
+    )
+    token = _CURRENT.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _CURRENT.reset(token)

saidso/grounding.py

@@ -0,0 +1,198 @@
+"""The ``@grounded`` decorator: the firewall around your action tools.
+
+Wrap a consequential function, declare a policy per argument, and the call is
+intercepted: every guarded argument is verified against the transcript before
+the body runs. Ungrounded? The body never executes and a :class:`SteerBack` is
+returned so the agent re-asks the caller. Grounded? An attestation is written.
+
+Production guarantees:
+
+* **Validated at decoration time** — a policy naming a non-existent parameter
+  raises immediately, so a typo can never silently leave a real argument
+  unguarded.
+* **Fail-closed** — if a grounding check raises unexpectedly, the argument is
+  treated as ungrounded (blocked) and the error is logged; a firewall must
+  never let a call through because the check crashed.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from . import matcher
+from .context import CallContext, get_context
+from .policy import DEFAULT_THRESHOLDS, Policy
+from .result import ArgFinding, GroundingResult, SteerBack
+
+logger = logging.getLogger("saidso")
+
+_OVERRIDE_KEYS = ("_context", "_transcript")
+
+
+@dataclass
+class GroundingConfig:
+    """Tunables for the firewall."""
+
+    thresholds: Optional[Dict[Policy, float]] = None
+    raise_on_block: bool = False  # default: return SteerBack (slots into tool loops)
+    warn_on_missing_context: bool = True
+
+    def threshold_for(self, policy: Policy) -> float:
+        if self.thresholds and policy in self.thresholds:
+            return self.thresholds[policy]
+        return DEFAULT_THRESHOLDS[policy]
+
+
+class GroundingBlocked(Exception):
+    """Raised instead of returning a SteerBack when ``raise_on_block=True``."""
+
+    def __init__(self, steer: SteerBack) -> None:
+        super().__init__(steer.message)
+        self.steer = steer
+
+
+def grounded(
+    _config: Optional[GroundingConfig] = None,
+    **arg_policies: Union[Policy, str],
+) -> Callable:
+    """Decorator factory. Map argument names to :class:`Policy` values.
+
+    Example::
+
+        @grounded(name=Policy.SPOKEN, dob=Policy.SPOKEN, phone=Policy.CALLER_ID)
+        async def register_patient(name, dob, phone): ...
+    """
+    config = _config or GroundingConfig()
+    if not arg_policies:
+        raise ValueError("@grounded requires at least one argument policy")
+    policies: Dict[str, Policy] = {}
+    for name, value in arg_policies.items():
+        try:
+            policies[name] = value if isinstance(value, Policy) else Policy(value)
+        except ValueError as exc:  # unknown policy string
+            raise ValueError(
+                f"@grounded: unknown policy {value!r} for argument {name!r}"
+            ) from exc
+
+    def decorate(fn: Callable) -> Callable:
+        sig = inspect.signature(fn)
+        params = sig.parameters
+        var_kw_name = next(
+            (n for n, p in params.items() if p.kind is inspect.Parameter.VAR_KEYWORD),
+            None,
+        )
+        accepts_var_kw = var_kw_name is not None
+        # Validate at decoration time: every guarded name must be a real param.
+        if not accepts_var_kw:
+            unknown = [n for n in policies if n not in params]
+            if unknown:
+                raise ValueError(
+                    f"@grounded on {fn.__name__}{sig}: these guarded arguments are "
+                    f"not parameters of the function: {unknown}. Check for typos."
+                )
+        # An override key only collides if the function genuinely declares it.
+        strip_keys = [k for k in _OVERRIDE_KEYS if k not in params]
+
+        def evaluate(args, kwargs):
+            override_ctx = kwargs.pop("_context", None) if "_context" in strip_keys else None
+            override_tr = kwargs.pop("_transcript", None) if "_transcript" in strip_keys else None
+
+            ctx = override_ctx or get_context()
+            if ctx is None:
+                if config.warn_on_missing_context:
+                    logger.warning(
+                        "saidso: no call_context active for %s; treating transcript "
+                        "as empty (all guarded args will block).", fn.__name__,
+                    )
+                ctx = CallContext()
+            if override_tr is not None:
+                ctx = CallContext(
+                    transcript=override_tr, metadata=ctx.metadata, now=ctx.now,
+                    call_id=ctx.call_id, ledger=ctx.ledger,
+                )
+
+            try:
+                bound = sig.bind_partial(*args, **kwargs)
+            except TypeError:
+                # Let the real function raise its own clear TypeError.
+                return _Pass(args, kwargs)
+            bound.apply_defaults()
+
+            def resolve(arg_name):
+                if arg_name in bound.arguments and arg_name != var_kw_name:
+                    return bound.arguments[arg_name]
+                if var_kw_name and var_kw_name in bound.arguments:
+                    return bound.arguments[var_kw_name].get(arg_name)
+                return None
+
+            failed: List[ArgFinding] = []
+            passed: List[ArgFinding] = []
+            for name, policy in policies.items():
+                value = resolve(name)
+                try:
+                    result = matcher.check(
+                        value, policy, ctx.transcript, ctx, config.threshold_for(policy)
+                    )
+                except Exception as exc:  # fail closed: never let a crash open the gate
+                    logger.exception(
+                        "saidso: grounding check errored for %s.%s; blocking.",
+                        fn.__name__, name,
+                    )
+                    result = GroundingResult(
+                        grounded=False, confidence=0.0, policy=policy.value,
+                        value=value, reason=f"grounding check errored: {exc}",
+                    )
+                finding = ArgFinding(name=name, result=result)
+                (passed if result.grounded else failed).append(finding)
+
+            if failed:
+                steer = SteerBack(action=fn.__name__, failed=failed, grounded=passed)
+                logger.info(
+                    "saidso blocked %s: ungrounded args %s",
+                    fn.__name__, [f.name for f in failed],
+                )
+                return steer
+
+            if ctx.ledger is not None:
+                ctx.ledger.build(fn.__name__, passed, call_id=ctx.call_id)
+            return _Pass(args, kwargs)
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def awrapper(*args, **kwargs):
+                outcome = evaluate(args, kwargs)
+                if isinstance(outcome, SteerBack):
+                    if config.raise_on_block:
+                        raise GroundingBlocked(outcome)
+                    return outcome
+                return await fn(*outcome.args, **outcome.kwargs)
+
+            awrapper.__grounded_policies__ = policies
+            return awrapper
+
+        @functools.wraps(fn)
+        def swrapper(*args, **kwargs):
+            outcome = evaluate(args, kwargs)
+            if isinstance(outcome, SteerBack):
+                if config.raise_on_block:
+                    raise GroundingBlocked(outcome)
+                return outcome
+            return fn(*outcome.args, **outcome.kwargs)
+
+        swrapper.__grounded_policies__ = policies
+        return swrapper
+
+    return decorate
+
+
+@dataclass
+class _Pass:
+    """Internal: the (possibly override-stripped) args to forward to the body."""
+
+    args: tuple
+    kwargs: dict