Clean README with trading demo focus

Author: azender1

README.md

@@ -1,239 +1,83 @@
-# Execution Guard — Exactly-Once Execution for AI Agents
+# SafeAgent / Execution Guard
 
-A missing layer for safe side effects in agent systems.
+## Prevent duplicate or incorrect execution when retries happen
 
-Retries can duplicate irreversible actions:
-payments, emails, trades, and external API mutations.
+A missing execution boundary for AI agents, trading bots, automations, and workflow systems.
 
-Execution Guard ensures a side effect runs exactly once — even under retries.
+When a system hits:
+- timeout
+- partial failure
+- retry
+- uncertain completion
 
-> Even if your system runs it twice, it executes once.
+…it often does not know whether the action already happened.
 
----
-
-## Quickstart (runs in ~10 seconds)
-
-Run the same request twice — it executes once.
-
-Install:
-
-```bash
-pip install safeagent-exec-guard
-```
-
-Minimal local example (SQLite):
-
-```python
-from safeagent_exec_guard.sqlite_store import SQLiteExecutionStore
-
-store = SQLiteExecutionStore("safeagent.db")
-store.init_db()
-
-def send_payment(request_id: str):
-    action = "send_payment"
-
-    if store.insert_if_not_exists(request_id, action):
-        print("executing side effect")
-        result = {"status": "sent", "receipt_id": "rcpt_12345"}
-        store.complete(request_id, result)
-        print("result:", result)
-    else:
-        print("duplicate blocked")
+That is how you get:
+- duplicate trades
+- duplicate payments
+- duplicate emails
+- duplicate API mutations
 
-send_payment("req_123")
-send_payment("req_123")
-```
-
-Expected output:
+SafeAgent adds a durable execution boundary around real side effects so retries can be reconciled instead of replayed.
 
-```text
-executing side effect
-result: {'status': 'sent', 'receipt_id': 'rcpt_12345'}
-duplicate blocked
-```
+> Most systems can retry. Very few can decide when a retry is still correct.
 
 ---
 
-## Demo
-
-A retry without protection can execute the same irreversible action twice.
-
-Execution Guard guarantees the side effect runs once — even if the agent retries.
-
-### Same request ID. Same retry. Different result.
+## Demo — duplicate trade prevented after uncertain completion
 
-Without an execution boundary, retries can re-run irreversible side effects.  
-With Execution Guard, the second attempt returns the original receipt instead of executing again.
+![SafeAgent Trading Demo](assets/safeagent_trading_demo_v2.gif)
 
-![Execution Guard Demo](assets/execution_guard_demo.gif)
+Without SafeAgent:
+- retry replays the action
+- duplicate trade executes
 
-SafeAgent is a reference implementation of the Execution Guard pattern.
+With SafeAgent:
+- retry resolves against existing execution
+- duplicate is blocked
 
 ---
 
-## Install
+## Quickstart
 
-```bash
 pip install safeagent-exec-guard
-```
-
----
-
-## Quick start (SQLite)
-
-Use SQLite for local development, demos, and single-process workflows.
 
 ```python
 from safeagent_exec_guard.sqlite_store import SQLiteExecutionStore
 
 store = SQLiteExecutionStore("safeagent.db")
 store.init_db()
 
-request_id = "payment_123"
-action = "send_payment"
-
-def do_side_effect():
-    print("Executing payment...")
-    return {"status": "sent", "receipt_id": "rcpt_12345"}
-
-if store.insert_if_not_exists(request_id, action):
-    result = do_side_effect()
-    store.complete(request_id, result)
-    print("Executed:", result)
-else:
-    print("Duplicate request detected — execution blocked")
-
-```
-See also: Wrap a side effect
-
-## Postgres (production)
-
-Use Postgres for distributed workers, production services, and multi-instance agent systems.
-
-### Start Postgres with Docker
-
-```bash
-docker run --name safeagent-postgres \
-  -e POSTGRES_PASSWORD=postgres \
-  -e POSTGRES_USER=postgres \
-  -e POSTGRES_DB=postgres \
-  -p 5432:5432 \
-  -d postgres:16
-```
-
-### Example
-
-```python
-import os
-from safeagent_exec_guard.postgres_store import PostgresExecutionStore
-
-dsn = os.getenv(
-    "POSTGRES_DSN",
-    "postgresql://postgres:postgres@localhost:5432/postgres"
-)
-
-store = PostgresExecutionStore(dsn)
-store.init_db()
-
-request_id = "payment_123"
-action = "send_payment"
-
-def do_side_effect():
-    print("Executing payment...")
-    return {"status": "sent", "receipt_id": "rcpt_12345"}
-
-if store.insert_if_not_exists(request_id, action):
-    result = do_side_effect()
-    store.complete(request_id, result)
-    print("Executed:", result)
-else:
-    print("Duplicate request detected — execution blocked")
-```
-
-### Reset the demo table
-
-```bash
-docker exec -it safeagent-postgres psql -U postgres -d postgres -c "TRUNCATE TABLE execution_requests;"
-```
-
----
-
-## How it works
+def send_payment(request_id: str):
+    action = "send_payment"
 
-```python
-if store.insert_if_not_exists(request_id, action):
-    result = do_side_effect()
-    store.complete(request_id, result)
-else:
-    print("Duplicate request detected — execution blocked")
+    if store.insert_if_not_exists(request_id, action):
+        result = {"status": "sent"}
+        store.complete(request_id, result)
+        print("executed")
+    else:
+        print("duplicate blocked")
 ```
 
-A request is identified once. Every retry resolves against that same execution record.
-
 ---
 
 ## Mental model
 
 Without SafeAgent:
-
-1. Request is sent.
-2. Timeout or uncertainty happens.
-3. The system retries.
-4. The side effect runs again.
+retry → replay → duplicate
 
 With SafeAgent:
-
-1. Request is sent with a `request_id`.
-2. Execution is recorded durably.
-3. The side effect runs once.
-4. Retries are blocked for the same request.
+retry → resolve → safe
 
 ---
 
 ## Where this matters
 
-- Payments
-- Trading systems
-- Background jobs
-- Webhooks
-- External API mutations
-- AI agent tool calls
-- Ticketing and messaging workflows
-
-Any system where running the same side effect twice is unacceptable.
-
----
-
-## Why this exists
-
-Retries do not mean “nothing happened.”
-
-They mean “we do not know what happened.”
-
-Most systems retry anyway.
-
-That is fine for reads.
-
-It is dangerous for side effects.
-
-That is how you get duplicate payments, duplicate emails, duplicate trades, and repeated external mutations.
-
-Execution Guard adds a safety boundary at the side-effect layer:
-
-- record the execution attempt
-- execute once
-- resolve retries safely
-
----
-
-## Case studies
-
-- [Trading Bot Case Study](docs/TRADING_BOT_CASE_STUDY.md)
-
-## Backends
-
-- SQLite → local / single process
-- Postgres → distributed / production
+- trading
+- payments
+- APIs
+- agents
+- workflows
 
 ---