feat: add financial governance evaluators (spend limits + transaction policy)

evaluators/contrib/financial-governance/README.md

@@ -0,0 +1,220 @@
+# Financial Governance Evaluators for Agent Control
+
+Evaluators that enforce financial spend limits and transaction policies for autonomous AI agents.
+
+As agents transact autonomously via protocols like [x402](https://github.com/coinbase/x402) and payment layers like [agentpay-mcp](https://github.com/AI-Agent-Economy/agentpay-mcp), enterprises need governance over what agents spend. These evaluators bring financial policy enforcement into the Agent Control framework.
+
+## Evaluators
+
+### `financial_governance.spend_limit`
+
+Tracks cumulative agent spend and enforces rolling budget limits. Stateful — records approved transactions and checks new ones against accumulated spend.
+
+- **Per-transaction cap** — reject any single payment above a threshold
+- **Rolling period budget** — reject payments that would exceed a time-windowed budget
+- **Context-aware overrides** — different limits per channel, agent, or session via evaluate metadata
+- **Pluggable storage** — abstract `SpendStore` protocol with built-in `InMemorySpendStore`; bring your own PostgreSQL, Redis, etc.
+
+### `financial_governance.transaction_policy`
+
+Static policy checks with no state tracking. Enforces structural rules on individual transactions.
+
+- **Currency allowlist** — only permit specific currencies (e.g., `["USDC", "USDT"]`)
+- **Recipient blocklist/allowlist** — control which addresses an agent can pay
+- **Amount bounds** — minimum and maximum per-transaction limits
+
+## Installation
+
+```bash
+# From the repo root (development) — install directly from contrib path
+cd evaluators/contrib/financial-governance
+pip install -e ".[dev]"
+```
+
+> **Note:** This package is not yet wired into `agent-control-evaluators` extras.
+> Install directly from the contrib path as shown above.
+
+## Configuration
+
+### Spend Limit
+
+```yaml
+controls:
+  - name: spend-limit
+    evaluator:
+      type: financial_governance.spend_limit
+      config:
+        max_per_transaction: "100.00"   # Max USDC per single payment (Decimal string)
+        max_per_period: "1000.00"       # Rolling 24h budget
+        period_seconds: 86400           # Budget window (default: 24 hours)
+        currency: USDC                  # Currency to govern
+    selector:
+      path: input                       # Extract step.input (transaction dict)
+    action: deny
+```
+
+### Transaction Policy
+
+```yaml
+controls:
+  - name: transaction-policy
+    evaluator:
+      type: financial_governance.transaction_policy
+      config:
+        allowed_currencies: [USDC, USDT]
+        blocked_recipients: ["0xDEAD..."]
+        allowed_recipients: ["0xALICE...", "0xBOB..."]
+        min_amount: "0.01"
+        max_amount: "5000.00"
+    selector:
+      path: input
+    action: deny
+```
+
+## Selector Paths
+
+Both evaluators support two selector configurations:
+
+- **`selector.path: "input"`** (recommended) — The evaluator receives `step.input` directly, which should be the transaction dict. Context fields (`channel`, `agent_id`, `session_id`) are merged from `step.context` into the transaction dict by the engine before evaluation.
+- **`selector.path: "*"`** — The evaluator receives the full Step object. It automatically extracts `step.input` for transaction fields and `step.context` for channel/agent/session metadata.
+
+## Input Data Schema
+
+The transaction dict (from `step.input`) should contain:
+
+```python
+# step.input — transaction payload
+{
+    "amount": "50.00",           # required — transaction amount (Decimal-compatible)
+    "currency": "USDC",          # required — payment currency
+    "recipient": "0xABC...",     # required — payment recipient
+}
+```
+
+## Context-Aware Limits
+
+Context fields (`channel`, `agent_id`, `session_id`) and per-context limit overrides can be provided in two ways:
+
+**Option A: Via `step.context`** (recommended for engine integration)
+
+```python
+step = Step(
+    type="tool",
+    name="payment",
+    input={"amount": "75.00", "currency": "USDC", "recipient": "0xABC"},
+    context={
+        "channel": "experimental",
+        "agent_id": "agent-42",
+        "channel_max_per_transaction": "50.00",
+        "channel_max_per_period": "200.00",
+    },
+)
+```
+
+When using `selector.path: "input"`, context fields (channel, agent_id, session_id) are merged from `step.context` into the transaction dict by the engine. When using `selector.path: "*"`, the evaluator merges `step.context` fields itself.
+
+**Option B: Inline in the transaction dict** (simpler, for direct SDK use)
+
+```python
+result = await evaluator.evaluate({
+    "amount": "75.00",
+    "currency": "USDC",
+    "recipient": "0xABC",
+    "channel": "experimental",
+    "channel_max_per_transaction": "50.00",
+    "channel_max_per_period": "200.00",
+})
+```
+
+Spend budgets are **scoped by context** — spend in channel A does not count against channel B's budget. When no context fields are present, budgets are global.
+
+## Custom SpendStore
+
+The `SpendStore` protocol requires two methods. Implement them for your backend:
+
+```python
+from decimal import Decimal
+from agent_control_evaluator_financial_governance.spend_limit import (
+    SpendStore,
+    SpendLimitConfig,
+    SpendLimitEvaluator,
+)
+
+class PostgresSpendStore:
+    """Example: PostgreSQL-backed spend tracking."""
+
+    def __init__(self, connection_string: str):
+        self._conn = connect(connection_string)
+
+    def record_spend(self, amount: Decimal, currency: str, metadata: dict | None = None) -> None:
+        self._conn.execute(
+            "INSERT INTO agent_spend (amount, currency, metadata, recorded_at) VALUES (%s, %s, %s, NOW())",
+            (str(amount), currency, json.dumps(metadata)),
+        )
+
+    def get_spend(
+        self,
+        currency: str,
+        start: float,
+        end: float | None = None,
+        scope: dict[str, str] | None = None,
+    ) -> Decimal:
+        end_clause = "AND recorded_at <= to_timestamp(%s)" if end is not None else ""
+        params = [currency, start]
+        if end is not None:
+            params.append(end)
+        row = self._conn.execute(
+            f"SELECT COALESCE(SUM(amount), 0) FROM agent_spend "
+            f"WHERE currency = %s AND recorded_at >= to_timestamp(%s) {end_clause}",
+            params,
+        ).fetchone()
+        return Decimal(str(row[0]))
+
+# Use it:
+store = PostgresSpendStore("postgresql://...")
+evaluator = SpendLimitEvaluator(config, store=store)
+```
+
+## Error Handling
+
+Malformed or incomplete runtime payloads (missing `amount`, missing `currency`, non-numeric values, etc.) return `matched=False, error=None` — they are treated as non-matching transactions, not evaluator errors. The `error` field is reserved for evaluator infrastructure failures (crashes, timeouts, missing dependencies).
+
+## Running Tests
+
+```bash
+cd evaluators/contrib/financial-governance
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Design Decisions
+
+1. **Decimal for money** — All monetary amounts use `Decimal` to avoid float precision errors in financial calculations.
+2. **Decoupled from data source** — The `SpendStore` protocol means no new tables in core Agent Control. Bring your own persistence.
+3. **Context-aware limits** — Override keys in the evaluate data dict allow per-channel, per-agent, or per-session limits without multiple evaluator instances.
+4. **Python SDK compatible** — Uses the standard evaluator interface; works with both the server and the Python SDK evaluation engine.
+5. **Fail-open on malformed data** — Missing or invalid fields return `matched=False` with `error=None`, following Agent Control conventions.
+
+## Known Limitations
+
+### Race Condition (read-then-write is not atomic)
+The spend-limit evaluator reads current period spend and then writes a new record as two separate operations. Under concurrent load this can allow transactions to slip through just above the budget. For hard enforcement use a `SpendStore` implementation that provides atomic `check_and_record` semantics (e.g., a Redis `MULTI`/`EXEC` block or a PostgreSQL `SELECT ... FOR UPDATE`). The `InMemorySpendStore` is thread-safe within a single process but does not provide atomic check-and-record.
+
+### Tuple-Scoped Budgets
+When context fields (`channel`, `agent_id`, `session_id`) are all present, they form a **single composite scope key** — not independent per-dimension budgets. For example, a scope of `{"channel": "A", "agent_id": "bot-1"}` matches only records that have *both* `channel=="A"` AND `agent_id=="bot-1"`. To enforce truly independent per-channel and per-agent budgets you would need separate `get_spend()` calls with separate scope dicts.
+
+### Package Not Yet in Extras
+This package is not yet wired into the `agent-control-evaluators` extras install target. Install directly from the contrib path:
+
+```bash
+pip install -e "evaluators/contrib/financial-governance"
+```
+
+## Related Projects
+
+- [x402](https://github.com/coinbase/x402) — HTTP 402 payment protocol
+- [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) — MCP server for non-custodial agent payments
+
+## License
+
+Apache-2.0 — see [LICENSE](../../../LICENSE).

evaluators/contrib/financial-governance/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "agent-control-evaluator-financial-governance"
+version = "0.1.0"
+description = "Financial governance evaluators for agent-control — spend limits and transaction policy enforcement"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "agent-control contributors" }]
+keywords = ["agent-control", "evaluator", "financial", "spend-limit", "x402", "agentpay"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "agent-control-evaluators>=3.0.0",
+    "agent-control-models>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.8.0",
+]
+
+[project.entry-points."agent_control.evaluators"]
+"financial_governance.spend_limit" = "agent_control_evaluator_financial_governance.spend_limit:SpendLimitEvaluator"
+"financial_governance.transaction_policy" = "agent_control_evaluator_financial_governance.transaction_policy:TransactionPolicyEvaluator"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_control_evaluator_financial_governance"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.uv.sources]
+agent-control-evaluators = { path = "../../builtin", editable = true }
+agent-control-models = { path = "../../../models", editable = true }

evaluators/contrib/financial-governance/src/agent_control_evaluator_financial_governance/__init__.py

@@ -0,0 +1,55 @@
+"""Financial governance evaluators for agent-control.
+
+Provides two evaluators for enforcing financial policy on AI agent transactions:
+
+- ``financial_governance.spend_limit``: Tracks cumulative spend against rolling
+  period budgets and per-transaction caps.
+- ``financial_governance.transaction_policy``: Static policy checks — allowlists,
+  blocklists, amount bounds, and permitted currencies.
+
+Both evaluators are registered automatically when this package is installed and
+the ``agent_control.evaluators`` entry point group is discovered.
+
+Example usage in an agent-control control config::
+
+    {
+      "condition": {
+        "selector": {"path": "input"},
+        "evaluator": {
+          "name": "financial_governance.spend_limit",
+          "config": {
+            "max_per_transaction": "100.00",
+            "max_per_period": "1000.00",
+            "period_seconds": 86400,
+            "currency": "USDC"
+          }
+        }
+      },
+      "action": {"decision": "deny"}
+    }
+
+Note on ``selector.path``:
+    Use ``selector.path: "input"`` (recommended) to pass ``step.input``
+    directly as the transaction dict.  Context fields (``channel``,
+    ``agent_id``, ``session_id``) are merged from ``step.context`` into
+    the transaction dict by the engine before evaluation.
+
+    Use ``selector.path: "*"`` to pass the full Step object; the evaluator
+    will extract ``step.input`` and merge ``step.context`` fields itself.
+"""
+
+from agent_control_evaluator_financial_governance.spend_limit import (
+    SpendLimitConfig,
+    SpendLimitEvaluator,
+)
+from agent_control_evaluator_financial_governance.transaction_policy import (
+    TransactionPolicyConfig,
+    TransactionPolicyEvaluator,
+)
+
+__all__ = [
+    "SpendLimitEvaluator",
+    "SpendLimitConfig",
+    "TransactionPolicyEvaluator",
+    "TransactionPolicyConfig",
+]

evaluators/contrib/financial-governance/src/agent_control_evaluator_financial_governance/spend_limit/__init__.py

@@ -0,0 +1,12 @@
+"""Spend-limit evaluator package."""
+
+from .config import SpendLimitConfig
+from .evaluator import SpendLimitEvaluator
+from .store import InMemorySpendStore, SpendStore
+
+__all__ = [
+    "SpendLimitEvaluator",
+    "SpendLimitConfig",
+    "SpendStore",
+    "InMemorySpendStore",
+]