tide-runtime 0.2.5__py3-none-any.whl

tide/__init__.py

@@ -0,0 +1,250 @@
+"""Tide runtime governance for agent tools with real side effects.
+
+Wrap the tools your agent uses to touch business systems. Before each call a
+deterministic policy decides allow / allow_with_log / require_approval / block;
+every call, approval, and outcome is appended to a local JSONL ledger that the
+`tide ledger` CLI reads.
+
+    from tide import configure, controlled_tool, record_outcome
+
+    configure(agent_id="crm-agent", workflow_id="lead-sync", environment="prod")
+
+    @controlled_tool(name="crm.update_lead", risk_class="internal_write",
+                     capture=["lead_id"])
+    def update_lead(lead_id, status):
+        ...
+
+Zero dependencies, Python >= 3.8. Payloads are hashed by default; `capture`
+opts specific fields into the ledger.
+"""
+
+import functools
+import inspect
+import os
+import time
+
+from . import policy as _policy
+from . import store as _store
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "configure",
+    "controlled_tool",
+    "record_outcome",
+    "LedgerBlocked",
+    "LedgerDenied",
+    "LedgerPending",
+]
+
+
+class LedgerBlocked(Exception):
+    """Policy decision was block; the tool did not run."""
+
+
+class LedgerDenied(Exception):
+    """A human denied the approval request; the tool did not run."""
+
+
+class LedgerPending(Exception):
+    """Approval is pending. Approve via `tide ledger approve <id>` and call again."""
+
+    def __init__(self, approval_id, message):
+        super().__init__(message)
+        self.approval_id = approval_id
+
+
+_config = {
+    "project": os.environ.get("TIDE_LEDGER_DIR", ".tide/ledger"),
+    "agent_id": "agent",
+    "workflow_id": None,
+    "environment": None,
+    "trace_id": None,
+    "on_approval": "wait",
+    "approval_timeout": 300,
+    "approval_poll": 2,
+}
+
+
+def configure(**kwargs):
+    """Set run-level config; starts a new trace unless trace_id is passed."""
+    unknown = set(kwargs) - set(_config)
+    if unknown:
+        raise TypeError("unknown configure() options: %s" % ", ".join(sorted(unknown)))
+    _config.update(kwargs)
+    if not kwargs.get("trace_id"):
+        _config["trace_id"] = _store.new_id()
+    return dict(_config)
+
+
+def _trace_id():
+    if not _config["trace_id"]:
+        _config["trace_id"] = _store.new_id()
+    return _config["trace_id"]
+
+
+def _environment(pol):
+    return (
+        _config["environment"]
+        or os.environ.get("TIDE_ENV")
+        or os.environ.get("LEDGER_ENV")
+        or (pol or {}).get("environment")
+        or "dev"
+    )
+
+
+def _bound_args(fn, args, kwargs):
+    try:
+        bound = inspect.signature(fn).bind(*args, **kwargs)
+        bound.apply_defaults()
+        return dict(bound.arguments)
+    except TypeError:
+        return {"args": list(args), "kwargs": kwargs}
+
+
+def _wait_for_decision(project, approval_id):
+    deadline = time.time() + _config["approval_timeout"]
+    while time.time() < deadline:
+        state = _store.approval_state(project, approval_id)
+        if state == "approved":
+            return "approved"
+        if state == "denied":
+            return "denied"
+        time.sleep(_config["approval_poll"])
+    return "timeout"
+
+
+def record_outcome(status, trace_id=None, workflow_id=None, human_corrected=False,
+                   failure_tag=None, source="api", project=None):
+    """Record what the workflow achieved: usually success or failure."""
+    project = project or _config["project"]
+    record = {
+        "outcome_id": _store.new_id(),
+        "trace_id": trace_id or _trace_id(),
+        "workflow_id": workflow_id or _config["workflow_id"],
+        "status": status,
+        "source": source,
+        "human_corrected": bool(human_corrected),
+        "failure_tag": failure_tag,
+        "created_at": _store.now_iso(),
+    }
+    _store.append_jsonl(project, _store.OUTCOMES_FILE, record)
+    return record
+
+
+def controlled_tool(name, version="0.0.0", risk_class="internal_write", owner=None,
+                    capture=None, cost_usd=None):
+    """Decorator: gate a tool behind policy and record each call."""
+    capture = list(capture or [])
+
+    def decorator(fn):
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            project = _config["project"]
+            pol = _store.load_policy(project) or dict(_policy.DEFAULT_POLICY)
+            env = _environment(pol)
+            trace_id = _trace_id()
+            named = _bound_args(fn, args, kwargs)
+            resolved_risk_class = risk_class(named) if callable(risk_class) else risk_class
+            input_hash = _store.canonical_hash(named)
+            captured = {k: named[k] for k in capture if k in named}
+            decision, reason = _policy.decide(pol, name, resolved_risk_class, env)
+
+            event = {
+                "event_id": _store.new_id(),
+                "trace_id": trace_id,
+                "workflow_id": _config["workflow_id"],
+                "agent_id": _config["agent_id"],
+                "tool": name,
+                "tool_version": version,
+                "owner": owner,
+                "risk_class": resolved_risk_class,
+                "environment": env,
+                "input_hash": input_hash,
+                "captured": captured,
+                "policy_decision": decision,
+                "policy_reason": reason,
+                "approval_id": None,
+                "approval_status": None,
+                "output_hash": None,
+                "latency_ms": None,
+                "cost_usd": cost_usd,
+                "error_code": None,
+                "created_at": _store.now_iso(),
+            }
+
+            if decision == "block":
+                event["error_code"] = "blocked_by_policy"
+                _store.append_jsonl(project, _store.EVENTS_FILE, event)
+                raise LedgerBlocked("%s blocked by policy: %s" % (name, reason))
+
+            if decision == "require_approval":
+                grant = _store.find_grant(project, name, input_hash)
+                if grant:
+                    _store.append_jsonl(project, _store.APPROVALS_FILE, {
+                        "type": "consumed",
+                        "approval_id": grant,
+                        "event_id": event["event_id"],
+                        "created_at": _store.now_iso(),
+                    })
+                    event["approval_id"] = grant
+                    event["approval_status"] = "approved"
+                else:
+                    approval_id = _store.new_id()
+                    _store.append_jsonl(project, _store.APPROVALS_FILE, {
+                        "type": "request",
+                        "approval_id": approval_id,
+                        "event_id": event["event_id"],
+                        "trace_id": event["trace_id"],
+                        "tool": name,
+                        "tool_version": version,
+                        "risk_class": resolved_risk_class,
+                        "input_hash": input_hash,
+                        "input_summary": captured,
+                        "policy_reason": reason,
+                        "agent_id": _config["agent_id"],
+                        "workflow_id": _config["workflow_id"],
+                        "created_at": _store.now_iso(),
+                    })
+                    event["approval_id"] = approval_id
+                    hint = "approve with: tide ledger approve %s --project %s" % (approval_id[:8], project)
+                    if _config["on_approval"] == "raise":
+                        event["approval_status"] = "pending"
+                        _store.append_jsonl(project, _store.EVENTS_FILE, event)
+                        raise LedgerPending(approval_id, "%s needs approval - %s" % (name, hint))
+                    result_state = _wait_for_decision(project, approval_id)
+                    if result_state == "denied":
+                        event["approval_status"] = "denied"
+                        event["error_code"] = "approval_denied"
+                        _store.append_jsonl(project, _store.EVENTS_FILE, event)
+                        raise LedgerDenied("%s was denied by a human approver" % name)
+                    if result_state == "timeout":
+                        event["approval_status"] = "pending"
+                        event["error_code"] = "approval_timeout"
+                        _store.append_jsonl(project, _store.EVENTS_FILE, event)
+                        raise LedgerPending(approval_id, "%s approval timed out - %s" % (name, hint))
+                    _store.append_jsonl(project, _store.APPROVALS_FILE, {
+                        "type": "consumed",
+                        "approval_id": approval_id,
+                        "event_id": event["event_id"],
+                        "created_at": _store.now_iso(),
+                    })
+                    event["approval_status"] = "approved"
+
+            start = time.time()
+            try:
+                result = fn(*args, **kwargs)
+            except Exception as exc:
+                event["latency_ms"] = int((time.time() - start) * 1000)
+                event["error_code"] = type(exc).__name__
+                _store.append_jsonl(project, _store.EVENTS_FILE, event)
+                raise
+            event["latency_ms"] = int((time.time() - start) * 1000)
+            event["output_hash"] = _store.canonical_hash(result)
+            _store.append_jsonl(project, _store.EVENTS_FILE, event)
+            return result
+
+        wrapper.__tide__ = {"name": name, "version": version, "risk_class": risk_class, "owner": owner}
+        return wrapper
+
+    return decorator

tide/policy.py

@@ -0,0 +1,43 @@
+"""Deterministic policy engine: risk class x environment -> decision."""
+
+RISK_CLASSES = (
+    "read_only",
+    "draft_only",
+    "internal_write",
+    "customer_visible",
+    "money_movement",
+    "destructive",
+)
+
+DECISIONS = ("allow", "allow_with_log", "require_approval", "block")
+
+DEFAULT_POLICY = {
+    "version": 1,
+    "environment": "dev",
+    "decisions": {
+        "read_only": {"dev": "allow", "prod": "allow"},
+        "draft_only": {"dev": "allow", "prod": "allow_with_log"},
+        "internal_write": {"dev": "allow_with_log", "prod": "require_approval"},
+        "customer_visible": {"dev": "require_approval", "prod": "require_approval"},
+        "money_movement": {"dev": "require_approval", "prod": "require_approval"},
+        "destructive": {"dev": "require_approval", "prod": "block"},
+    },
+    "tools": {},
+}
+
+
+def decide(policy, tool_name, risk_class, environment):
+    """Return (decision, reason). Per-tool override wins over the class table."""
+    tool_rule = (policy.get("tools") or {}).get(tool_name)
+    if tool_rule:
+        decision = tool_rule.get("decision")
+        if decision in DECISIONS:
+            return decision, tool_rule.get("reason") or ("per-tool override for " + tool_name)
+        return "block", "invalid per-tool override for %s - failing closed" % tool_name
+    table = (policy.get("decisions") or {}).get(risk_class)
+    if not isinstance(table, dict):
+        return "block", "unknown risk class '%s' - failing closed" % risk_class
+    decision = table.get(environment, table.get("prod"))
+    if decision not in DECISIONS:
+        return "block", "no valid decision for %s in '%s' - failing closed" % (risk_class, environment)
+    return decision, "%s in %s -> %s" % (risk_class, environment, decision)

tide/store.py

@@ -0,0 +1,101 @@
+"""File contract for the Tide ledger directory.
+
+policy.json      policy config
+events.jsonl     one record per controlled tool call
+approvals.jsonl  request / decision / consumed records
+outcomes.jsonl   workflow outcome events
+"""
+
+import hashlib
+import json
+import os
+import uuid
+from datetime import datetime, timezone
+
+POLICY_FILE = "policy.json"
+EVENTS_FILE = "events.jsonl"
+APPROVALS_FILE = "approvals.jsonl"
+OUTCOMES_FILE = "outcomes.jsonl"
+
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def new_id():
+    return uuid.uuid4().hex
+
+
+def canonical_hash(obj):
+    blob = json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str)
+    return "sha256:" + hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+def ensure_project(project):
+    os.makedirs(project, exist_ok=True)
+    return project
+
+
+def load_policy(project):
+    path = os.path.join(project, POLICY_FILE)
+    if not os.path.exists(path):
+        return None
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def append_jsonl(project, filename, record):
+    ensure_project(project)
+    with open(os.path.join(project, filename), "a", encoding="utf-8") as f:
+        f.write(json.dumps(record, sort_keys=True, default=str) + "\n")
+
+
+def read_jsonl(project, filename):
+    path = os.path.join(project, filename)
+    if not os.path.exists(path):
+        return []
+    records = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                records.append(json.loads(line))
+            except ValueError:
+                continue
+    return records
+
+
+def approval_state(project, approval_id):
+    state = None
+    for r in read_jsonl(project, APPROVALS_FILE):
+        if r.get("approval_id") != approval_id:
+            continue
+        kind = r.get("type")
+        if kind == "request":
+            state = "pending"
+        elif kind == "decision":
+            state = "approved" if r.get("decision") == "approved" else "denied"
+        elif kind == "consumed":
+            state = "consumed"
+    return state
+
+
+def find_grant(project, tool_name, input_hash):
+    """Find an approved, unconsumed approval bound to this exact tool and input."""
+    requests = {}
+    for r in read_jsonl(project, APPROVALS_FILE):
+        aid = r.get("approval_id")
+        kind = r.get("type")
+        if kind == "request":
+            requests[aid] = {"record": r, "state": "pending"}
+        elif kind == "decision" and aid in requests:
+            requests[aid]["state"] = "approved" if r.get("decision") == "approved" else "denied"
+        elif kind == "consumed" and aid in requests:
+            requests[aid]["state"] = "consumed"
+    for aid, info in requests.items():
+        req = info["record"]
+        if info["state"] == "approved" and req.get("tool") == tool_name and req.get("input_hash") == input_hash:
+            return aid
+    return None

tide_runtime-0.2.5.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: tide-runtime
+Version: 0.2.5
+Summary: Tide runtime policy, approvals, and earned-use ledger for AI agent tools.
+Project-URL: Repository, https://github.com/rippletideco/rippletide-package
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Tide Runtime SDK
+
+Python SDK for wrapping production agent tools with Tide policy, approvals, and
+earned-use logging.
+
+```bash
+pip install tide-runtime
+tide ledger init
+```
+
+```python
+from tide import configure, controlled_tool, record_outcome
+
+configure(agent_id="crm-agent", workflow_id="lead-sync", environment="prod")
+
+@controlled_tool(name="crm.update_lead", risk_class="internal_write", capture=["lead_id"])
+def update_lead(lead_id, status):
+    return {"lead_id": lead_id, "status": status}
+
+try:
+    update_lead("L-1", "qualified")
+    record_outcome("success")
+except Exception:
+    record_outcome("failure")
+    raise
+```
+
+Default files live in `.tide/ledger/`. Override with `TIDE_LEDGER_DIR` or
+`configure(project="...")`.

tide_runtime-0.2.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+tide/__init__.py,sha256=QanIyZb3Z-hJDvpyUlJfQSZ8QlcDGHXT5-MPYkHHycc,9478
+tide/policy.py,sha256=Ds5JF4ZaurCFMut9jT11o-5Mw6k3EolaqW8a4rcjDWs,1760
+tide/store.py,sha256=XwMlrzgfe9zfiSEYOpeEDSPnsMMtu9WfYr40bclBc9o,2990
+tide_runtime-0.2.5.dist-info/METADATA,sha256=CN3ZhDft-miHeWr_XCIH76MKBO5qXmBKPihO0QW8cF8,1016
+tide_runtime-0.2.5.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tide_runtime-0.2.5.dist-info/top_level.txt,sha256=VWFFwJ9JGbJhNRC7ewPF2GjEHeIMv-bnDWco7XP7xMc,5
+tide_runtime-0.2.5.dist-info/RECORD,,

tide_runtime-0.2.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tide_runtime-0.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+tide