feat(examples/python): add fallback-recovery-agent runnable example

Author: AgentPatterns

examples/agent-patterns/fallback-recovery-agent/python/README.md

@@ -0,0 +1,34 @@
+# Fallback-Recovery Agent (Python)
+
+Production-style example for the Fallback-Recovery pattern:
+
+- detect and classify tool failures
+- retry retriable failures within budget
+- switch to fallback tools when primary path is unstable
+- keep progress via checkpointed step results
+- finish with explicit `stop_reason`, `trace`, and `history`
+
+## Run
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export OPENAI_API_KEY="sk-..."
+# optional:
+# export OPENAI_MODEL="gpt-4.1-mini"
+# export OPENAI_TIMEOUT_SECONDS="60"
+
+python main.py
+```
+
+## Files
+
+- `main.py` - run flow and final output
+- `gateway.py` - recovery policy, retries, fallbacks, budgets
+- `tools.py` - deterministic primary/fallback tool stubs
+- `checkpoint_store.py` - in-memory step checkpointing
+- `llm.py` - final brief synthesis
+- `context.py` - request and policy hints
+

examples/agent-patterns/fallback-recovery-agent/python/checkpoint_store.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class CheckpointRow:
+    run_id: str
+    step_id: str
+    source: str
+    tool: str
+    result: dict[str, Any]
+    saved_at: float
+    ttl_seconds: float | None = None
+
+
+class CheckpointStore:
+    def __init__(self) -> None:
+        self._rows: dict[tuple[str, str], CheckpointRow] = {}
+
+    def get_step(self, *, run_id: str, step_id: str, now: float | None = None) -> CheckpointRow | None:
+        row = self._rows.get((run_id, step_id))
+        if row is None:
+            return None
+        if row.ttl_seconds is None:
+            return row
+        now_ts = time.time() if now is None else float(now)
+        if (now_ts - row.saved_at) > float(row.ttl_seconds):
+            # Expired checkpoint: treat as missing.
+            self._rows.pop((run_id, step_id), None)
+            return None
+        return row
+
+    def save_step(
+        self,
+        *,
+        run_id: str,
+        step_id: str,
+        source: str,
+        tool: str,
+        result: dict[str, Any],
+    ) -> None:
+        self._rows[(run_id, step_id)] = CheckpointRow(
+            run_id=run_id,
+            step_id=step_id,
+            source=source,
+            tool=tool,
+            result=result,
+            saved_at=time.time(),
+            ttl_seconds=None,
+        )
+
+    def save_step_with_ttl(
+        self,
+        *,
+        run_id: str,
+        step_id: str,
+        source: str,
+        tool: str,
+        result: dict[str, Any],
+        ttl_seconds: float,
+    ) -> None:
+        self._rows[(run_id, step_id)] = CheckpointRow(
+            run_id=run_id,
+            step_id=step_id,
+            source=source,
+            tool=tool,
+            result=result,
+            saved_at=time.time(),
+            ttl_seconds=float(ttl_seconds),
+        )
+
+    def dump_run(self, *, run_id: str) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        for row in self._rows.values():
+            if row.run_id != run_id:
+                continue
+            out.append(
+                {
+                    "step_id": row.step_id,
+                    "source": row.source,
+                    "tool": row.tool,
+                    "result_keys": sorted(row.result.keys()),
+                    "saved_at": row.saved_at,
+                }
+            )
+        out.sort(key=lambda item: item["saved_at"])
+        return out

examples/agent-patterns/fallback-recovery-agent/python/context.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_operations_context(*, report_date: str, region: str) -> dict[str, Any]:
+    return {
+        "goal": "Prepare a customer-safe operations update for the payments incident.",
+        "request": {
+            "report_date": report_date,
+            "region": region.upper(),
+        },
+        "policy_hints": {
+            "max_retries": 1,
+            "max_fallbacks": 2,
+            "allow_cached_fallback": True,
+            "avoid_absolute_guarantees": True,
+        },
+    }
+