asap-protocol 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/examples/error_recovery.py

@@ -0,0 +1,248 @@
+"""Error recovery patterns example for ASAP protocol.
+
+This module demonstrates retry with backoff, circuit breaker, and fallback
+patterns using ASAP's built-in support and small helpers you can reuse.
+
+Patterns:
+    1. Retry with backoff: RetryConfig + ASAPClient, or a standalone retry loop.
+    2. Circuit breaker: CircuitBreaker (and ASAPClient with circuit_breaker_enabled).
+    3. Fallback: Try primary operation; on failure use fallback result or backup agent.
+
+Run:
+    uv run python -m asap.examples.error_recovery
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import time
+from typing import Callable, Sequence, TypeVar
+
+from asap.observability import get_logger
+from asap.transport.circuit_breaker import CircuitBreaker, CircuitState
+from asap.transport.client import RetryConfig
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+# Demo defaults (short delays so the example runs quickly)
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BASE_DELAY = 0.05
+DEFAULT_MAX_DELAY = 0.5
+DEFAULT_CB_THRESHOLD = 2
+DEFAULT_CB_TIMEOUT = 0.2
+
+
+def retry_with_backoff(
+    fn: Callable[[], T],
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    base_delay: float = DEFAULT_BASE_DELAY,
+    max_delay: float = DEFAULT_MAX_DELAY,
+    jitter: bool = True,
+) -> T:
+    """Call fn(); on exception, retry with exponential backoff until success or max_retries.
+
+    Same idea as ASAPClient's internal retry: delay = min(base_delay * 2^attempt, max_delay)
+    with optional jitter. Use this for custom operations outside the client.
+
+    Args:
+        fn: Callable that may raise. No arguments.
+        max_retries: Number of retries after the first attempt (total attempts = max_retries + 1).
+        base_delay: Base delay in seconds for exponential backoff.
+        max_delay: Cap on delay in seconds.
+        jitter: If True, add random jitter to each delay.
+
+    Returns:
+        Result of fn().
+
+    Raises:
+        Last exception raised by fn() if all attempts fail.
+    """
+    last_exc: BaseException | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            return fn()
+        except BaseException as e:
+            last_exc = e
+            if attempt == max_retries:
+                raise
+            delay = min(base_delay * (2**attempt), max_delay)
+            if jitter:
+                delay = delay * (0.5 + random.random())  # nosec B311
+            logger.info(
+                "asap.error_recovery.retry",
+                attempt=attempt + 1,
+                max_retries=max_retries,
+                delay_seconds=round(delay, 3),
+                error=str(e),
+            )
+            time.sleep(delay)
+    if last_exc is not None:
+        raise last_exc
+    raise RuntimeError("retry_with_backoff: no result and no exception")
+
+
+def with_fallback(
+    primary_fn: Callable[[], T],
+    fallback_fn: Callable[[], T],
+) -> T:
+    """Try primary_fn(); on exception, call fallback_fn() and return its result.
+
+    Use when you have a backup (e.g. cached value, secondary agent, default payload).
+
+    Args:
+        primary_fn: Operation that may raise.
+        fallback_fn: Called only if primary_fn raises; should not raise.
+
+    Returns:
+        Result of primary_fn or fallback_fn.
+    """
+    try:
+        return primary_fn()
+    except Exception as e:
+        logger.warning(
+            "asap.error_recovery.fallback",
+            primary_error=str(e),
+            message="Using fallback",
+        )
+        return fallback_fn()
+
+
+def demo_retry_with_backoff(
+    fails_then_succeeds_at: int = 2,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+) -> None:
+    """Demonstrate retry with backoff using a flaky callable that fails N times then succeeds."""
+    call_count = 0
+
+    def flaky_op() -> str:
+        nonlocal call_count
+        call_count += 1
+        if call_count < fails_then_succeeds_at:
+            raise ConnectionError(f"Simulated failure (call #{call_count})")
+        return "ok"
+
+    result = retry_with_backoff(
+        flaky_op,
+        max_retries=max_retries,
+        base_delay=DEFAULT_BASE_DELAY,
+        max_delay=DEFAULT_MAX_DELAY,
+    )
+    logger.info(
+        "asap.error_recovery.retry_demo_complete",
+        result=result,
+        calls=call_count,
+    )
+
+
+def demo_circuit_breaker(
+    threshold: int = DEFAULT_CB_THRESHOLD,
+    timeout: float = DEFAULT_CB_TIMEOUT,
+) -> None:
+    """Demonstrate circuit breaker: record failures until OPEN, wait, then HALF_OPEN and recover."""
+    breaker = CircuitBreaker(threshold=threshold, timeout=timeout)
+
+    # CLOSED -> record failures until OPEN
+    for _ in range(threshold):
+        breaker.record_failure()
+    assert breaker.get_state() == CircuitState.OPEN  # nosec B101
+    assert breaker.can_attempt() is False  # nosec B101
+    logger.info(
+        "asap.error_recovery.circuit_open",
+        state=breaker.get_state().value,
+        consecutive_failures=breaker.get_consecutive_failures(),
+    )
+
+    # Wait for timeout -> HALF_OPEN
+    time.sleep(timeout + 0.05)
+    assert breaker.can_attempt() is True  # nosec B101
+    assert breaker.get_state() == CircuitState.HALF_OPEN  # nosec B101
+    logger.info(
+        "asap.error_recovery.circuit_half_open",
+        state=breaker.get_state().value,
+    )
+
+    # Success -> CLOSED
+    breaker.record_success()
+    assert breaker.get_state() == CircuitState.CLOSED  # nosec B101
+    logger.info(
+        "asap.error_recovery.circuit_closed",
+        state=breaker.get_state().value,
+    )
+
+
+def demo_fallback() -> None:
+    """Demonstrate fallback: primary raises, fallback returns default result."""
+
+    def primary() -> str:
+        raise RuntimeError("Primary agent unavailable")
+
+    def fallback() -> str:
+        return '{"status": "fallback", "message": "default result"}'
+
+    result = with_fallback(primary, fallback)
+    logger.info(
+        "asap.error_recovery.fallback_demo_complete",
+        result=result,
+    )
+
+
+def show_client_retry_config() -> None:
+    """Log how to use RetryConfig with ASAPClient (for reference)."""
+    config = RetryConfig(
+        max_retries=3,
+        base_delay=1.0,
+        max_delay=60.0,
+        jitter=True,
+        circuit_breaker_enabled=True,
+        circuit_breaker_threshold=5,
+        circuit_breaker_timeout=60.0,
+    )
+    logger.info(
+        "asap.error_recovery.client_retry_config",
+        message="Use ASAPClient(..., retry_config=RetryConfig(...)); CircuitOpenError when circuit is open",
+        max_retries=config.max_retries,
+        circuit_breaker_enabled=config.circuit_breaker_enabled,
+    )
+
+
+def run_demo(
+    skip_retry: bool = False,
+    skip_circuit: bool = False,
+    skip_fallback: bool = False,
+) -> None:
+    """Run all error recovery demos (retry, circuit breaker, fallback)."""
+    if not skip_retry:
+        demo_retry_with_backoff()
+    if not skip_circuit:
+        demo_circuit_breaker()
+    if not skip_fallback:
+        demo_fallback()
+    show_client_retry_config()
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the error recovery demo."""
+    parser = argparse.ArgumentParser(
+        description="Error recovery patterns: retry with backoff, circuit breaker, fallback."
+    )
+    parser.add_argument("--skip-retry", action="store_true", help="Skip retry demo.")
+    parser.add_argument("--skip-circuit", action="store_true", help="Skip circuit breaker demo.")
+    parser.add_argument("--skip-fallback", action="store_true", help="Skip fallback demo.")
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run error recovery pattern demos."""
+    args = parse_args(argv)
+    run_demo(
+        skip_retry=args.skip_retry,
+        skip_circuit=args.skip_circuit,
+        skip_fallback=args.skip_fallback,
+    )
+
+
+if __name__ == "__main__":
+    main()

asap/examples/long_running.py

@@ -0,0 +1,287 @@
+"""Long-running task with checkpoints example for ASAP protocol.
+
+This module demonstrates saving task state as snapshots and resuming after
+a "crash" (e.g. process exit, failure). Use StateSnapshot and a SnapshotStore
+to persist progress so work can continue from the last checkpoint.
+
+Scenario:
+    - A task runs in multiple steps (e.g. step 1, 2, 3, ...).
+    - After each step we save a StateSnapshot to the store.
+    - If the process crashes or stops, we can resume by loading the latest
+      snapshot and continuing from the next step.
+
+Run:
+    uv run python -m asap.examples.long_running
+    uv run python -m asap.examples.long_running --crash-after 2  # Simulate crash after step 2
+"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+from typing import Any, Protocol, Sequence, runtime_checkable
+
+from asap.models.entities import StateSnapshot
+from asap.models.ids import generate_id
+from asap.models.types import TaskID
+from asap.observability import get_logger
+from asap.state.snapshot import InMemorySnapshotStore
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "KEY_COMPLETED",
+    "KEY_PARTIAL_RESULT",
+    "KEY_PROGRESS_PCT",
+    "KEY_STEP",
+    "InMemorySnapshotStore",
+    "SnapshotStoreLike",
+    "create_snapshot",
+    "resume_from_store",
+    "run_demo",
+    "run_steps",
+]
+
+# Keys used in snapshot data for this example
+KEY_STEP = "step"
+KEY_PROGRESS_PCT = "progress_pct"
+KEY_PARTIAL_RESULT = "partial_result"
+KEY_COMPLETED = "completed"
+
+
+@runtime_checkable
+class SnapshotStoreLike(Protocol):
+    """Minimal protocol for snapshot save/get (for type hints in this example)."""
+
+    def save(self, snapshot: StateSnapshot) -> None: ...
+    def get(self, task_id: TaskID, version: int | None = None) -> StateSnapshot | None: ...
+    def list_versions(self, task_id: TaskID) -> list[int]: ...
+
+
+def create_snapshot(
+    task_id: str,
+    version: int,
+    step: int,
+    progress_pct: int,
+    partial_result: dict[str, Any],
+    completed: bool = False,
+    checkpoint: bool = True,
+) -> StateSnapshot:
+    """Build a StateSnapshot for the long-running task progress.
+
+    Args:
+        task_id: Parent task ID.
+        version: Snapshot version (monotonically increasing).
+        step: Current step number (1-based).
+        progress_pct: Progress percentage (0–100).
+        partial_result: Result data accumulated so far.
+        completed: Whether the task is fully completed.
+        checkpoint: Whether this snapshot is a significant checkpoint.
+
+    Returns:
+        StateSnapshot ready to save to a store.
+    """
+    return StateSnapshot(
+        id=generate_id(),
+        task_id=task_id,
+        version=version,
+        data={
+            KEY_STEP: step,
+            KEY_PROGRESS_PCT: progress_pct,
+            KEY_PARTIAL_RESULT: partial_result,
+            KEY_COMPLETED: completed,
+        },
+        checkpoint=checkpoint,
+        created_at=datetime.now(timezone.utc),
+    )
+
+
+def run_steps(
+    store: SnapshotStoreLike,
+    task_id: str,
+    num_steps: int,
+    crash_after_step: int | None = None,
+) -> StateSnapshot | None:
+    """Run the long-running task: execute steps 1..num_steps and save a snapshot after each.
+
+    If crash_after_step is set, stop after that step (simulating a crash).
+    The latest snapshot remains in the store so the task can be resumed.
+
+    Args:
+        store: Snapshot store to persist state.
+        task_id: Task identifier.
+        num_steps: Total number of steps (e.g. 5).
+        crash_after_step: If set, stop after this step (1-based). None = no crash.
+
+    Returns:
+        Latest snapshot after the run, or None if no step was executed.
+    """
+    partial_result: dict[str, Any] = {"items": [], "last_step": 0}
+    last_snapshot: StateSnapshot | None = None
+
+    for step in range(1, num_steps + 1):
+        progress_pct = (step * 100) // num_steps
+        partial_result["items"].append(f"result_step_{step}")
+        partial_result["last_step"] = step
+
+        completed = step == num_steps
+        version = step
+        snapshot = create_snapshot(
+            task_id=task_id,
+            version=version,
+            step=step,
+            progress_pct=progress_pct,
+            partial_result=dict(partial_result),
+            completed=completed,
+            checkpoint=True,
+        )
+        store.save(snapshot)
+        last_snapshot = snapshot
+        logger.info(
+            "asap.long_running.checkpoint",
+            task_id=task_id,
+            step=step,
+            version=version,
+            progress_pct=progress_pct,
+        )
+
+        if crash_after_step is not None and step >= crash_after_step:
+            logger.warning(
+                "asap.long_running.crash_simulated",
+                task_id=task_id,
+                after_step=step,
+            )
+            break
+
+    return last_snapshot
+
+
+def resume_from_store(
+    store: SnapshotStoreLike,
+    task_id: str,
+    num_steps: int,
+) -> StateSnapshot | None:
+    """Resume a long-running task from the latest snapshot in the store.
+
+    Loads the latest StateSnapshot for task_id, reads the last completed step,
+    and runs from (step + 1) to num_steps, saving a snapshot after each step.
+
+    Args:
+        store: Snapshot store where state was persisted.
+        task_id: Task identifier.
+        num_steps: Total number of steps (must match original task).
+
+    Returns:
+        Latest snapshot after resume, or None if no previous snapshot or nothing left to do.
+    """
+    latest = store.get(task_id, version=None)
+    if latest is None:
+        logger.warning("asap.long_running.no_snapshot", task_id=task_id)
+        return None
+
+    data = latest.data
+    last_step = data.get(KEY_STEP, 0)
+    partial_result = dict(data.get(KEY_PARTIAL_RESULT, {"items": [], "last_step": 0}))
+
+    if last_step >= num_steps:
+        logger.info("asap.long_running.already_complete", task_id=task_id)
+        return latest
+
+    logger.info(
+        "asap.long_running.resuming",
+        task_id=task_id,
+        from_step=last_step + 1,
+        num_steps=num_steps,
+    )
+
+    last_snapshot: StateSnapshot | None = latest
+    for step in range(last_step + 1, num_steps + 1):
+        progress_pct = (step * 100) // num_steps
+        partial_result["items"].append(f"result_step_{step}")
+        partial_result["last_step"] = step
+        completed = step == num_steps
+        version = step
+        snapshot = create_snapshot(
+            task_id=task_id,
+            version=version,
+            step=step,
+            progress_pct=progress_pct,
+            partial_result=dict(partial_result),
+            completed=completed,
+            checkpoint=True,
+        )
+        store.save(snapshot)
+        last_snapshot = snapshot
+        logger.info(
+            "asap.long_running.checkpoint",
+            task_id=task_id,
+            step=step,
+            version=version,
+            progress_pct=progress_pct,
+        )
+
+    return last_snapshot
+
+
+def run_demo(
+    num_steps: int = 5,
+    crash_after_step: int | None = 2,
+) -> None:
+    """Run a full demo: execute until crash, then resume and complete.
+
+    Args:
+        num_steps: Total number of steps.
+        crash_after_step: Step after which to simulate a crash (1-based). None = no crash.
+    """
+    store: InMemorySnapshotStore = InMemorySnapshotStore()
+    task_id = generate_id()
+
+    run_steps(store, task_id, num_steps, crash_after_step=crash_after_step)
+
+    final = resume_from_store(store, task_id, num_steps)
+    if final is None:
+        raise SystemExit(1)
+    if not final.data.get(KEY_COMPLETED, False):
+        raise SystemExit(1)
+    logger.info("asap.long_running.demo_complete", task_id=task_id, final_step=final.data[KEY_STEP])
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the long-running demo.
+
+    Args:
+        argv: Optional list of CLI arguments for testing.
+
+    Returns:
+        Parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(
+        description="Long-running task with checkpoints (save snapshot, resume after crash)."
+    )
+    parser.add_argument(
+        "--num-steps",
+        type=int,
+        default=5,
+        help="Total number of steps in the task.",
+    )
+    parser.add_argument(
+        "--crash-after",
+        type=int,
+        default=2,
+        metavar="N",
+        help="Simulate crash after step N (1-based). Use 0 to disable crash.",
+    )
+    args = parser.parse_args(argv)
+    if args.crash_after == 0:
+        args.crash_after = None
+    return args
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the long-running task demo: checkpoint, crash, resume."""
+    args = parse_args(argv)
+    run_demo(num_steps=args.num_steps, crash_after_step=args.crash_after)
+
+
+if __name__ == "__main__":
+    main()