tbay 0.1.0__tar.gz

tbay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tbay-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: tbay
+Version: 0.1.0
+Summary: Execution safety for AI agent tool calls: idempotency, caching, singleflight, policy, and approval gating, as a library, not a service.
+Author: tbay contributors
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: psycopg2-binary>=2.9; extra == "dev"
+Dynamic: license-file
+
+# tbay
+
+Execution safety for AI agent tool calls: idempotency, TTL caching,
+singleflight deduplication, risk-tiered policy, and human approval gating,
+as a library you install, not a service you depend on.
+
+```python
+from tbay import TbayClient, guarded
+
+client = TbayClient("sqlite:///~/.tbay/db.sqlite")
+# or: TbayClient("postgresql://user:pass@host/dbname")
+
+@guarded(client, policy="readonly")
+def github_search(query: str) -> dict:
+    return real_github_api_call(query)
+
+@guarded(client, policy="destructive")
+def refund_customer(customer_id: str, amount: float) -> dict:
+    return stripe_refund(customer_id, amount)
+```
+
+`@guarded` only ever wraps a plain callable, so it drops in under
+LangChain's `@tool`, the OpenAI Agents SDK's `@function_tool`, CrewAI tools,
+or bare functions, with zero framework-specific code. See `examples/`.
+
+## Why
+
+Agent frameworks solve planning and orchestration. None of them solve
+*execution safety*: once a tool is selected, nothing stops it from being
+called twice, cached when it shouldn't be, called too often, or fired on a
+destructive action without a human in the loop. tbay sits underneath any
+framework and handles that, durably, across processes, in whatever database
+you already run.
+
+**This is not a hosted service.** You `pip install` it; state (idempotency
+keys, cached results, the audit log) lives entirely in a database you own.
+Nothing calls home.
+
+## Install
+
+```
+pip install tbay               # SQLite backend, stdlib only
+pip install tbay[postgres]     # + Postgres backend
+
+# or, with uv:
+uv add tbay
+uv add "tbay[postgres]"
+```
+
+## How it works
+
+Every `@guarded` call computes an idempotency key (tool name + normalized
+args + tenant), then atomically claims a row in your database:
+
+- **First caller** for a given key becomes the owner and runs the real
+  function.
+- **Concurrent callers** with the identical key block and receive the same
+  result once the owner finishes (singleflight). No in-memory daemon is
+  required; coordination happens through the database's own atomicity
+  (`INSERT ... ON CONFLICT`, plus an advisory lock for the Postgres backend
+  when `max_concurrent` is set).
+- **Later callers**, after the owner finishes, get the stored result
+  instead of re-running: permanently for `mutating`/`destructive` policies
+  (true idempotency), or until the policy's `cache_ttl` expires for
+  `readonly` policies.
+- **`destructive`-policy calls** pause in `WAITING_APPROVAL` until someone
+  runs `tbay approve <execution_id>` (optionally after a webhook fires).
+- **Not every tool call is idempotent.** An LLM call used to decide
+  something, "roll a die", "get the current time": calling these twice with
+  the same arguments should *not* return the same cached answer. Use the
+  `volatile` policy (`idempotent: false`) for these; tbay then ignores
+  caching, dedup, and `key_fn` entirely and runs the call fresh every time.
+
+## Policies
+
+```yaml
+policies:
+  # Safe to call repeatedly; safe to serve a slightly stale answer.
+  readonly:
+    cache_ttl: 5m
+    singleflight: true
+    max_retries: 2
+    retry_backoff: 1s
+
+  # Has a real effect, but must never double-run for the same input.
+  mutating:
+    idempotent: true
+    cache_ttl: 0          # 0/omitted means "keep the result forever"
+    max_retries: 0
+
+  # Has a real-world consequence a human should sign off on.
+  destructive:
+    idempotent: true
+    approval_required: true
+    approval_timeout: 1h
+    approval_bypass_arg: amount     # optional: skip approval for small values
+    approval_bypass_max: 50
+    redact_args: [card_number]       # optional: mask these args in the audit log
+
+  # Runs fresh every time, even with identical arguments: an LLM call used
+  # to decide something, a random number, "get the current time".
+  volatile:
+    idempotent: false
+    max_retries: 1
+    retry_backoff: 0.5
+```
+
+Pass a policy file via `TbayClient(db_url, policy_file="policy.yaml")`, or
+override policies in code (`client.policies["readonly"].cache_ttl = 60`).
+See `policy.example.yaml` for every field, including the `rate_limit` and
+`max_concurrent` throughput guardrails.
+
+### Approval webhooks
+
+Setting `approval_webhook` on a policy makes tbay fire an HTTP POST when a
+call enters `WAITING_APPROVAL`, so a human finds out without polling
+`tbay log` themselves. The body is
+`{"execution_id": "...", "tool_name": "..."}`; look the execution up with
+`tbay log --tool <tool_name>` to see its (possibly redacted) arguments
+before approving or rejecting it.
+
+The webhook is best-effort: if the URL is unreachable or returns an error,
+tbay ignores it silently and the call still waits normally. `tbay
+approve`/`tbay reject` always work, whether or not the webhook fired, so a
+flaky webhook endpoint can never leave a call stuck.
+
+### Approval bypass and other guardrails
+
+`approval_bypass_arg`/`approval_bypass_max` let small, low-risk calls
+through automatically while still pausing anything larger for a human:
+a refund of $50 or less runs immediately, a refund of $500 waits for
+`tbay approve`. `rate_limit` and `max_concurrent` protect a tool (and
+whatever paid or rate-limited API it calls) from a runaway agent loop by
+capping how often it can be called and how many calls can be in flight at
+once. `execution_timeout` gives up on a hung call after a set time, though
+this is best-effort: Python can't force-kill a thread, so the call may keep
+running in the background even after tbay marks it failed.
+
+## CLI
+
+```
+tbay log                                   # the audit log
+tbay log --tool refund_customer --status WAITING_APPROVAL
+tbay approve <execution_id>
+tbay reject <execution_id>
+```
+
+Point the CLI at the same database as your app with `--db-url` or the
+`TBAY_DB_URL` environment variable.
+
+## Examples
+
+- `examples/plain_python_demo.py`: no framework, just `@guarded` functions,
+  covering readonly caching, mutating idempotency, a volatile LLM call, and
+  an approval bypass threshold.
+- `examples/langchain_demo.py`: stacks under LangChain's `@tool`.
+- `examples/openai_agents_demo.py`: stacks under the OpenAI Agents SDK's
+  `@function_tool`.
+
+## Development
+
+Uses [uv](https://docs.astral.sh/uv/) for dependency management:
+
+```
+uv sync --extra dev
+uv run pytest
+```
+
+Postgres-backed tests are skipped unless `TBAY_TEST_PG_DSN` is set to a
+running Postgres instance (CI provides one automatically).
+
+## License
+
+MIT

tbay-0.1.0/README.md

@@ -0,0 +1,174 @@
+# tbay
+
+Execution safety for AI agent tool calls: idempotency, TTL caching,
+singleflight deduplication, risk-tiered policy, and human approval gating,
+as a library you install, not a service you depend on.
+
+```python
+from tbay import TbayClient, guarded
+
+client = TbayClient("sqlite:///~/.tbay/db.sqlite")
+# or: TbayClient("postgresql://user:pass@host/dbname")
+
+@guarded(client, policy="readonly")
+def github_search(query: str) -> dict:
+    return real_github_api_call(query)
+
+@guarded(client, policy="destructive")
+def refund_customer(customer_id: str, amount: float) -> dict:
+    return stripe_refund(customer_id, amount)
+```
+
+`@guarded` only ever wraps a plain callable, so it drops in under
+LangChain's `@tool`, the OpenAI Agents SDK's `@function_tool`, CrewAI tools,
+or bare functions, with zero framework-specific code. See `examples/`.
+
+## Why
+
+Agent frameworks solve planning and orchestration. None of them solve
+*execution safety*: once a tool is selected, nothing stops it from being
+called twice, cached when it shouldn't be, called too often, or fired on a
+destructive action without a human in the loop. tbay sits underneath any
+framework and handles that, durably, across processes, in whatever database
+you already run.
+
+**This is not a hosted service.** You `pip install` it; state (idempotency
+keys, cached results, the audit log) lives entirely in a database you own.
+Nothing calls home.
+
+## Install
+
+```
+pip install tbay               # SQLite backend, stdlib only
+pip install tbay[postgres]     # + Postgres backend
+
+# or, with uv:
+uv add tbay
+uv add "tbay[postgres]"
+```
+
+## How it works
+
+Every `@guarded` call computes an idempotency key (tool name + normalized
+args + tenant), then atomically claims a row in your database:
+
+- **First caller** for a given key becomes the owner and runs the real
+  function.
+- **Concurrent callers** with the identical key block and receive the same
+  result once the owner finishes (singleflight). No in-memory daemon is
+  required; coordination happens through the database's own atomicity
+  (`INSERT ... ON CONFLICT`, plus an advisory lock for the Postgres backend
+  when `max_concurrent` is set).
+- **Later callers**, after the owner finishes, get the stored result
+  instead of re-running: permanently for `mutating`/`destructive` policies
+  (true idempotency), or until the policy's `cache_ttl` expires for
+  `readonly` policies.
+- **`destructive`-policy calls** pause in `WAITING_APPROVAL` until someone
+  runs `tbay approve <execution_id>` (optionally after a webhook fires).
+- **Not every tool call is idempotent.** An LLM call used to decide
+  something, "roll a die", "get the current time": calling these twice with
+  the same arguments should *not* return the same cached answer. Use the
+  `volatile` policy (`idempotent: false`) for these; tbay then ignores
+  caching, dedup, and `key_fn` entirely and runs the call fresh every time.
+
+## Policies
+
+```yaml
+policies:
+  # Safe to call repeatedly; safe to serve a slightly stale answer.
+  readonly:
+    cache_ttl: 5m
+    singleflight: true
+    max_retries: 2
+    retry_backoff: 1s
+
+  # Has a real effect, but must never double-run for the same input.
+  mutating:
+    idempotent: true
+    cache_ttl: 0          # 0/omitted means "keep the result forever"
+    max_retries: 0
+
+  # Has a real-world consequence a human should sign off on.
+  destructive:
+    idempotent: true
+    approval_required: true
+    approval_timeout: 1h
+    approval_bypass_arg: amount     # optional: skip approval for small values
+    approval_bypass_max: 50
+    redact_args: [card_number]       # optional: mask these args in the audit log
+
+  # Runs fresh every time, even with identical arguments: an LLM call used
+  # to decide something, a random number, "get the current time".
+  volatile:
+    idempotent: false
+    max_retries: 1
+    retry_backoff: 0.5
+```
+
+Pass a policy file via `TbayClient(db_url, policy_file="policy.yaml")`, or
+override policies in code (`client.policies["readonly"].cache_ttl = 60`).
+See `policy.example.yaml` for every field, including the `rate_limit` and
+`max_concurrent` throughput guardrails.
+
+### Approval webhooks
+
+Setting `approval_webhook` on a policy makes tbay fire an HTTP POST when a
+call enters `WAITING_APPROVAL`, so a human finds out without polling
+`tbay log` themselves. The body is
+`{"execution_id": "...", "tool_name": "..."}`; look the execution up with
+`tbay log --tool <tool_name>` to see its (possibly redacted) arguments
+before approving or rejecting it.
+
+The webhook is best-effort: if the URL is unreachable or returns an error,
+tbay ignores it silently and the call still waits normally. `tbay
+approve`/`tbay reject` always work, whether or not the webhook fired, so a
+flaky webhook endpoint can never leave a call stuck.
+
+### Approval bypass and other guardrails
+
+`approval_bypass_arg`/`approval_bypass_max` let small, low-risk calls
+through automatically while still pausing anything larger for a human:
+a refund of $50 or less runs immediately, a refund of $500 waits for
+`tbay approve`. `rate_limit` and `max_concurrent` protect a tool (and
+whatever paid or rate-limited API it calls) from a runaway agent loop by
+capping how often it can be called and how many calls can be in flight at
+once. `execution_timeout` gives up on a hung call after a set time, though
+this is best-effort: Python can't force-kill a thread, so the call may keep
+running in the background even after tbay marks it failed.
+
+## CLI
+
+```
+tbay log                                   # the audit log
+tbay log --tool refund_customer --status WAITING_APPROVAL
+tbay approve <execution_id>
+tbay reject <execution_id>
+```
+
+Point the CLI at the same database as your app with `--db-url` or the
+`TBAY_DB_URL` environment variable.
+
+## Examples
+
+- `examples/plain_python_demo.py`: no framework, just `@guarded` functions,
+  covering readonly caching, mutating idempotency, a volatile LLM call, and
+  an approval bypass threshold.
+- `examples/langchain_demo.py`: stacks under LangChain's `@tool`.
+- `examples/openai_agents_demo.py`: stacks under the OpenAI Agents SDK's
+  `@function_tool`.
+
+## Development
+
+Uses [uv](https://docs.astral.sh/uv/) for dependency management:
+
+```
+uv sync --extra dev
+uv run pytest
+```
+
+Postgres-backed tests are skipped unless `TBAY_TEST_PG_DSN` is set to a
+running Postgres instance (CI provides one automatically).
+
+## License
+
+MIT

tbay-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tbay"
+version = "0.1.0"
+description = "Execution safety for AI agent tool calls: idempotency, caching, singleflight, policy, and approval gating, as a library, not a service."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "tbay contributors" }]
+dependencies = [
+    "pyyaml>=6.0",
+    "click>=8.1",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+postgres = ["psycopg2-binary>=2.9"]
+dev = ["pytest>=7.4", "psycopg2-binary>=2.9"]
+
+[project.scripts]
+tbay = "tbay.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tbay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tbay-0.1.0/src/tbay/__init__.py

@@ -0,0 +1,25 @@
+from .client import TbayClient
+from .decorator import guarded
+from .exceptions import (
+    ApprovalRejected,
+    ApprovalTimeout,
+    ConcurrencyLimitExceeded,
+    ExecutionFailed,
+    ExecutionTimeout,
+    RateLimitExceeded,
+    TbayError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TbayClient",
+    "guarded",
+    "TbayError",
+    "ApprovalRejected",
+    "ApprovalTimeout",
+    "ExecutionFailed",
+    "ExecutionTimeout",
+    "RateLimitExceeded",
+    "ConcurrencyLimitExceeded",
+]

tbay-0.1.0/src/tbay/backends/__init__.py

@@ -0,0 +1,3 @@
+from .base import AcquireResult, ExecutionRecord, StorageBackend
+
+__all__ = ["AcquireResult", "ExecutionRecord", "StorageBackend"]

tbay-0.1.0/src/tbay/backends/base.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ..exceptions import ApprovalTimeout, ExecutionTimeout
+
+RUNNING = "RUNNING"
+SUCCEEDED = "SUCCEEDED"
+FAILED = "FAILED"
+WAITING_APPROVAL = "WAITING_APPROVAL"
+
+APPROVAL_PENDING = "pending"
+APPROVAL_APPROVED = "approved"
+APPROVAL_REJECTED = "rejected"
+
+
+@dataclass
+class ExecutionRecord:
+    """One row of the audit log: everything tbay knows about a single
+    tool call, keyed by (tool_name, idempotency_key, tenant)."""
+
+    id: str
+    tool_name: str
+    idempotency_key: str
+    tenant: str
+    status: str
+    args_hash: str
+    args_json: Optional[str]
+    result_json: Optional[str]
+    error: Optional[str]
+    policy_name: str
+    retry_count: int
+    cache_expires_at: Optional[float]
+    created_at: float
+    finished_at: Optional[float]
+
+
+@dataclass
+class AcquireResult:
+    """What acquire_or_get() decided the caller should do next. Exactly one
+    of the flags below matters:
+
+    - owner:              caller must run the real function.
+    - use_cached:          caller should return record.result_json right away.
+    - follow_running:      caller should block on wait_for_result().
+    - follow_approval:     caller should block on wait_for_approval(), then wait_for_result().
+    - raise_stored_error:  caller should raise the stored error right away (no retry left).
+    - wait_for_slot:       max_concurrent is full; caller should pause briefly and call
+                           acquire_or_get() again (record is None in this case, since
+                           nothing was reserved).
+    """
+
+    record: Optional[ExecutionRecord]
+    owner: bool = False
+    use_cached: bool = False
+    follow_running: bool = False
+    wait_for_slot: bool = False
+    follow_approval: bool = False
+    raise_stored_error: bool = False
+
+
+class StorageBackend:
+    """The interface SQLiteBackend and PostgresBackend both implement.
+
+    Coordinating multiple callers, possibly in different processes or on
+    different machines, is entirely the database's job here: acquire_or_get
+    must claim a lease atomically (INSERT ... ON CONFLICT DO NOTHING,
+    followed by a compare-and-swap UPDATE when reclaiming an expired or
+    failed row). There's no shared in-memory state between callers, only
+    whatever the database itself guarantees.
+    """
+
+    def init_schema(self) -> None:
+        """Create the executions/approvals tables if they don't already exist."""
+        raise NotImplementedError
+
+    def acquire_or_get(
+        self,
+        *,
+        execution_id: str,
+        tool_name: str,
+        idempotency_key: str,
+        tenant: str,
+        policy_name: str,
+        args_hash: str,
+        args_json: Optional[str],
+        max_retries: int,
+        retry_backoff: float,
+        max_concurrent: Optional[int] = None,
+    ) -> AcquireResult:
+        """Try to become the owner of this (tool_name, idempotency_key, tenant).
+        If someone already owns it, report back what the caller should do instead.
+
+        If max_concurrent is set, the RUNNING count check and the insert
+        happen in the same transaction, so this is atomic, not a separate
+        check-then-act: two simultaneous new callers can't both slip through
+        past the cap the way a check performed before this call would allow.
+        """
+        raise NotImplementedError
+
+    def mark_waiting_approval(self, execution_id: str) -> None:
+        raise NotImplementedError
+
+    def complete(self, execution_id: str, result_json: str, cache_ttl_seconds: Optional[float]) -> None:
+        raise NotImplementedError
+
+    def fail(self, execution_id: str, error: str) -> None:
+        raise NotImplementedError
+
+    def get(self, execution_id: str) -> Optional[ExecutionRecord]:
+        raise NotImplementedError
+
+    def get_approval_status(self, execution_id: str) -> Optional[str]:
+        raise NotImplementedError
+
+    def resolve_approval(self, execution_id: str, approved: bool, resolver: str = "") -> None:
+        raise NotImplementedError
+
+    def list_executions(
+        self,
+        *,
+        tool_name: Optional[str] = None,
+        status: Optional[str] = None,
+        tenant: Optional[str] = None,
+        limit: int = 50,
+    ) -> List[ExecutionRecord]:
+        raise NotImplementedError
+
+    def count_since(self, tool_name: str, tenant: str, since: float) -> int:
+        """How many calls to this tool (for this tenant) were created at or
+        after `since` (a time.time() timestamp). Backs the rate_limit guardrail."""
+        raise NotImplementedError
+
+    # -- generic polling helpers, shared by every backend --
+
+    def wait_for_result(self, execution_id: str, timeout: float, poll_interval: float) -> ExecutionRecord:
+        deadline = time.time() + timeout
+        while True:
+            record = self.get(execution_id)
+            if record and record.status in (SUCCEEDED, FAILED):
+                return record
+            if time.time() > deadline:
+                raise ExecutionTimeout(f"timed out waiting for execution {execution_id} to finish")
+            time.sleep(poll_interval)
+
+    def wait_for_approval(self, execution_id: str, timeout: float, poll_interval: float) -> str:
+        deadline = time.time() + timeout
+        while True:
+            status = self.get_approval_status(execution_id)
+            if status and status != APPROVAL_PENDING:
+                return status
+            if time.time() > deadline:
+                raise ApprovalTimeout(f"nobody approved or rejected execution {execution_id} in time")
+            time.sleep(poll_interval)