rewind-agent 0.1.0__tar.gz

rewind_agent-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Build
+/target/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# IDE
+.cursor/
+.idea/
+.vscode/
+
+# Rewind data (user's local recordings)
+.rewind/
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+
+# Env
+.env
+.env.local

rewind_agent-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: rewind-agent
+Version: 0.1.0
+Summary: Chrome DevTools for AI agents — record, inspect, fork, replay, diff.
+Project-URL: Homepage, https://github.com/risjai/rewind
+Project-URL: Repository, https://github.com/risjai/rewind
+Project-URL: Issues, https://github.com/risjai/rewind/issues
+Project-URL: Changelog, https://github.com/risjai/rewind/blob/main/CHANGELOG.md
+Author: Rewind Contributors
+License-Expression: MIT
+Keywords: agents,ai,anthropic,crewai,debugging,langgraph,llm,observability,openai,time-travel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# rewind-agent
+
+**Python SDK for [Rewind](https://github.com/risjai/rewind) — the time-travel debugger for AI agents.**
+
+Record every LLM call. See the exact context window. Fork, fix, replay — without re-running.
+
+## Install
+
+```bash
+pip install rewind-agent
+```
+
+Requires the Rewind CLI for recording. Install with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/risjai/rewind/main/install.sh | sh
+```
+
+## Quick Start
+
+```python
+import rewind_agent
+
+# Auto-patches OpenAI/Anthropic clients to route through the Rewind proxy
+rewind_agent.init()
+
+# Your existing agent code runs unchanged — all LLM calls are recorded
+client = openai.OpenAI()
+client.chat.completions.create(model="gpt-4o", messages=[...])
+```
+
+## Agent Hooks
+
+Enrich recordings with semantic labels:
+
+```python
+@rewind_agent.step("search")
+def search(query: str) -> str:
+    return client.chat.completions.create(...)
+
+@rewind_agent.tool("calculator")
+def calculate(expr: str) -> float:
+    return eval(expr)
+
+with rewind_agent.trace("analysis"):
+    rewind_agent.annotate("confidence", 0.92)
+    result = search("Tokyo population")
+```
+
+## Framework Adapters
+
+```python
+# LangGraph
+graph = rewind_agent.wrap_langgraph(compiled_graph)
+
+# CrewAI
+crew = rewind_agent.wrap_crew(crew)
+```
+
+## Learn More
+
+- [GitHub](https://github.com/risjai/rewind)
+- [Changelog](https://github.com/risjai/rewind/blob/main/CHANGELOG.md)
+- [Examples](https://github.com/risjai/rewind/tree/main/examples)

rewind_agent-0.1.0/README.md

@@ -0,0 +1,64 @@
+# rewind-agent
+
+**Python SDK for [Rewind](https://github.com/risjai/rewind) — the time-travel debugger for AI agents.**
+
+Record every LLM call. See the exact context window. Fork, fix, replay — without re-running.
+
+## Install
+
+```bash
+pip install rewind-agent
+```
+
+Requires the Rewind CLI for recording. Install with:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/risjai/rewind/main/install.sh | sh
+```
+
+## Quick Start
+
+```python
+import rewind_agent
+
+# Auto-patches OpenAI/Anthropic clients to route through the Rewind proxy
+rewind_agent.init()
+
+# Your existing agent code runs unchanged — all LLM calls are recorded
+client = openai.OpenAI()
+client.chat.completions.create(model="gpt-4o", messages=[...])
+```
+
+## Agent Hooks
+
+Enrich recordings with semantic labels:
+
+```python
+@rewind_agent.step("search")
+def search(query: str) -> str:
+    return client.chat.completions.create(...)
+
+@rewind_agent.tool("calculator")
+def calculate(expr: str) -> float:
+    return eval(expr)
+
+with rewind_agent.trace("analysis"):
+    rewind_agent.annotate("confidence", 0.92)
+    result = search("Tokyo population")
+```
+
+## Framework Adapters
+
+```python
+# LangGraph
+graph = rewind_agent.wrap_langgraph(compiled_graph)
+
+# CrewAI
+crew = rewind_agent.wrap_crew(crew)
+```
+
+## Learn More
+
+- [GitHub](https://github.com/risjai/rewind)
+- [Changelog](https://github.com/risjai/rewind/blob/main/CHANGELOG.md)
+- [Examples](https://github.com/risjai/rewind/tree/main/examples)

rewind_agent-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rewind-agent"
+version = "0.1.0"
+description = "Chrome DevTools for AI agents — record, inspect, fork, replay, diff."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    {name = "Rewind Contributors"},
+]
+keywords = [
+    "ai",
+    "agents",
+    "debugging",
+    "observability",
+    "time-travel",
+    "llm",
+    "openai",
+    "anthropic",
+    "langgraph",
+    "crewai",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.18"]
+all = ["openai>=1.0", "anthropic>=0.18"]
+
+[project.urls]
+Homepage = "https://github.com/risjai/rewind"
+Repository = "https://github.com/risjai/rewind"
+Issues = "https://github.com/risjai/rewind/issues"
+Changelog = "https://github.com/risjai/rewind/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rewind_agent"]

rewind_agent-0.1.0/rewind_agent/__init__.py

@@ -0,0 +1,45 @@
+"""
+Rewind Agent SDK — Chrome DevTools for AI agents.
+
+Usage:
+    import rewind_agent
+
+    # Auto-patch OpenAI/Anthropic to route through the proxy
+    rewind_agent.init()
+
+    # Decorate agent steps for richer traces
+    @rewind_agent.step("search")
+    def search(query):
+        return client.chat.completions.create(...)
+
+    # Wrap LangGraph / CrewAI for automatic instrumentation
+    graph = rewind_agent.wrap_langgraph(graph)
+    crew = rewind_agent.wrap_crew(crew)
+"""
+
+from .patch import init, uninit, session
+from .hooks import (
+    step,
+    node,
+    tool,
+    trace,
+    annotate,
+    get_annotations,
+    wrap_langgraph,
+    wrap_crew,
+)
+
+__all__ = [
+    "init",
+    "uninit",
+    "session",
+    "step",
+    "node",
+    "tool",
+    "trace",
+    "annotate",
+    "get_annotations",
+    "wrap_langgraph",
+    "wrap_crew",
+]
+__version__ = "0.1.0"

rewind_agent-0.1.0/rewind_agent/hooks.py

@@ -0,0 +1,273 @@
+"""
+Rewind Hooks — Framework-agnostic decorators for enriching agent recordings.
+
+These decorators work with ANY Python agent framework. They annotate
+the LLM calls captured by the Rewind proxy with semantic metadata:
+node names, agent state, step descriptions.
+
+Works with LangGraph, CrewAI, OpenAI Agents SDK, or plain functions.
+"""
+
+import functools
+import json
+import os
+import time
+import urllib.request
+from contextlib import contextmanager
+from typing import Any, Callable
+
+REWIND_PROXY = os.environ.get("REWIND_PROXY", "http://127.0.0.1:8443")
+
+_step_counter = 0
+_annotations: list[dict] = []
+
+
+def step(name: str | None = None, metadata: dict | None = None):
+    """
+    Decorator that records a function as a named agent step.
+
+    Usage:
+        @rewind.step("search")
+        def search_web(query: str) -> str:
+            return client.chat.completions.create(...)
+
+        @rewind.step("plan", metadata={"agent": "planner"})
+        def plan_task(goal: str) -> dict:
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        step_name = name or func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            global _step_counter
+            _step_counter += 1
+            step_id = _step_counter
+
+            start = time.perf_counter()
+            error = None
+            result = None
+
+            _annotate("step_start", {
+                "step_id": step_id,
+                "step_name": step_name,
+                "metadata": metadata or {},
+                "args_preview": _safe_preview(args, kwargs),
+            })
+
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = str(e)
+                raise
+            finally:
+                elapsed_ms = (time.perf_counter() - start) * 1000
+                _annotate("step_end", {
+                    "step_id": step_id,
+                    "step_name": step_name,
+                    "duration_ms": round(elapsed_ms, 2),
+                    "error": error,
+                    "result_preview": _safe_str(result)[:200] if result else None,
+                })
+
+        return wrapper
+    return decorator
+
+
+def node(name: str):
+    """
+    Decorator for LangGraph-style graph nodes.
+
+    Usage:
+        @rewind.node("researcher")
+        def researcher(state: dict) -> dict:
+            ...
+    """
+    return step(name=name, metadata={"type": "graph_node"})
+
+
+def tool(name: str | None = None):
+    """
+    Decorator for tool/function calls.
+
+    Usage:
+        @rewind.tool("web_search")
+        def search(query: str) -> str:
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        tool_name = name or func.__name__
+        return step(name=tool_name, metadata={"type": "tool"})(func)
+    return decorator
+
+
+@contextmanager
+def trace(name: str, metadata: dict | None = None):
+    """
+    Context manager for tracing a block of agent execution.
+
+    Usage:
+        with rewind.trace("research_phase"):
+            result1 = search(query)
+            result2 = analyze(result1)
+    """
+    global _step_counter
+    _step_counter += 1
+    step_id = _step_counter
+    start = time.perf_counter()
+
+    _annotate("trace_start", {
+        "step_id": step_id,
+        "trace_name": name,
+        "metadata": metadata or {},
+    })
+
+    error = None
+    try:
+        yield
+    except Exception as e:
+        error = str(e)
+        raise
+    finally:
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        _annotate("trace_end", {
+            "step_id": step_id,
+            "trace_name": name,
+            "duration_ms": round(elapsed_ms, 2),
+            "error": error,
+        })
+
+
+def annotate(key: str, value: Any):
+    """
+    Add a custom annotation to the current recording.
+
+    Usage:
+        rewind.annotate("confidence", 0.85)
+        rewind.annotate("decision", "retry with different prompt")
+    """
+    _annotate("custom", {"key": key, "value": _safe_str(value)})
+
+
+def get_annotations() -> list[dict]:
+    """Return all annotations recorded in this session."""
+    return list(_annotations)
+
+
+# ── LangGraph adapter ──────────────────────────────────────────
+
+def wrap_langgraph(graph, recorder_name: str = "langgraph"):
+    """
+    Wrap a LangGraph compiled graph to record all node executions.
+
+    Usage:
+        from langgraph.graph import StateGraph
+        graph = builder.compile()
+        graph = rewind.wrap_langgraph(graph)
+        result = graph.invoke({"input": "..."})
+
+    This wraps each node's function with @rewind.node() automatically.
+    """
+    try:
+        nodes = graph.nodes
+    except AttributeError:
+        return graph  # not a LangGraph, return unchanged
+
+    for node_name, node_fn in list(nodes.items()):
+        if node_name in ("__start__", "__end__"):
+            continue
+        wrapped = step(name=f"{recorder_name}/{node_name}", metadata={"type": "graph_node", "graph": recorder_name})(node_fn)
+        nodes[node_name] = wrapped
+
+    return graph
+
+
+# ── CrewAI adapter ─────────────────────────────────────────────
+
+def wrap_crew(crew, recorder_name: str = "crewai"):
+    """
+    Instrument a CrewAI Crew to record task and step execution.
+
+    Usage:
+        from crewai import Crew
+        crew = Crew(agents=[...], tasks=[...])
+        crew = rewind.wrap_crew(crew)
+        result = crew.kickoff()
+
+    Hooks into step_callback and task_callback if available.
+    """
+    # Install step callback
+    original_step_cb = getattr(crew, 'step_callback', None)
+
+    def _step_callback(output):
+        _annotate("crew_step", {
+            "recorder": recorder_name,
+            "output_preview": _safe_str(output)[:300],
+        })
+        if original_step_cb:
+            original_step_cb(output)
+
+    # Install task callback
+    original_task_cb = getattr(crew, 'task_callback', None)
+
+    def _task_callback(output):
+        _annotate("crew_task_complete", {
+            "recorder": recorder_name,
+            "output_preview": _safe_str(output)[:300],
+        })
+        if original_task_cb:
+            original_task_cb(output)
+
+    try:
+        crew.step_callback = _step_callback
+        crew.task_callback = _task_callback
+    except (AttributeError, TypeError):
+        pass  # older CrewAI versions may not support this
+
+    return crew
+
+
+# ── Internal ───────────────────────────────────────────────────
+
+def _annotate(event_type: str, data: dict):
+    """Record an annotation locally and optionally POST to the proxy."""
+    entry = {
+        "type": event_type,
+        "timestamp": time.time(),
+        "data": data,
+    }
+    _annotations.append(entry)
+
+    # Best-effort POST to proxy side-channel (non-blocking)
+    try:
+        payload = json.dumps(entry).encode()
+        req = urllib.request.Request(
+            f"{REWIND_PROXY}/_rewind/annotate",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=0.5)
+    except Exception:
+        pass  # proxy may not be running, that's fine
+
+
+def _safe_preview(args, kwargs) -> str:
+    """Safely preview function arguments."""
+    parts = []
+    for a in args[:3]:
+        parts.append(_safe_str(a)[:100])
+    for k, v in list(kwargs.items())[:3]:
+        parts.append(f"{k}={_safe_str(v)[:100]}")
+    return ", ".join(parts)
+
+
+def _safe_str(obj) -> str:
+    """Safely convert any object to string."""
+    try:
+        if isinstance(obj, (dict, list)):
+            return json.dumps(obj, default=str)[:500]
+        return str(obj)[:500]
+    except Exception:
+        return "<unserializable>"

rewind_agent-0.1.0/rewind_agent/patch.py

@@ -0,0 +1,108 @@
+"""
+Monkey-patching layer for OpenAI clients.
+
+When `init()` is called, it patches the OpenAI client to route
+all API calls through the local Rewind proxy, which records them.
+"""
+
+import os
+import contextlib
+from functools import wraps
+
+_original_base_url = None
+_initialized = False
+
+REWIND_PROXY_URL = "http://127.0.0.1:8443"
+
+
+def init(proxy_url: str | None = None, auto_patch: bool = True):
+    """
+    Initialize Rewind recording.
+
+    This patches the OPENAI_BASE_URL environment variable so that
+    all OpenAI client instances route through the Rewind proxy.
+
+    Args:
+        proxy_url: Override the default proxy URL (http://127.0.0.1:8443)
+        auto_patch: If True, also monkey-patch already-imported OpenAI clients
+    """
+    global _original_base_url, _initialized
+
+    if _initialized:
+        return
+
+    url = proxy_url or REWIND_PROXY_URL
+
+    # Save original
+    _original_base_url = os.environ.get("OPENAI_BASE_URL")
+
+    # Set proxy URL — new OpenAI() clients will pick this up automatically
+    os.environ["OPENAI_BASE_URL"] = f"{url}/v1"
+
+    # Also patch Anthropic if available
+    os.environ["ANTHROPIC_BASE_URL"] = f"{url}/anthropic"
+
+    _initialized = True
+
+    if auto_patch:
+        _patch_existing_clients(url)
+
+    _print_banner(url)
+
+
+def uninit():
+    """Restore original base URLs and remove patches."""
+    global _original_base_url, _initialized
+
+    if not _initialized:
+        return
+
+    if _original_base_url is not None:
+        os.environ["OPENAI_BASE_URL"] = _original_base_url
+    else:
+        os.environ.pop("OPENAI_BASE_URL", None)
+
+    os.environ.pop("ANTHROPIC_BASE_URL", None)
+    _initialized = False
+
+
+@contextlib.contextmanager
+def session(name: str = "default", proxy_url: str | None = None):
+    """
+    Context manager for a Rewind recording session.
+
+    Usage:
+        with rewind_agent.session("my-agent"):
+            client = openai.OpenAI()
+            client.chat.completions.create(...)
+    """
+    # TODO: Start a named session via the proxy API
+    init(proxy_url=proxy_url)
+    try:
+        yield
+    finally:
+        uninit()
+
+
+def _patch_existing_clients(proxy_url: str):
+    """Patch already-instantiated OpenAI clients if the module is loaded."""
+    try:
+        import openai
+        # Patch the module-level default client if it exists
+        if hasattr(openai, '_client'):
+            openai._client.base_url = f"{proxy_url}/v1"
+    except ImportError:
+        pass
+
+
+def _print_banner(proxy_url: str):
+    """Print a nice startup banner."""
+    print()
+    print("  \033[36m\033[1m⏪ Rewind\033[0m — Recording active")
+    print()
+    print(f"  \033[90mProxy:\033[0m  {proxy_url}")
+    print(f"  \033[90mOpenAI:\033[0m {proxy_url}/v1")
+    print()
+    print("  \033[33mAll LLM calls are being recorded.\033[0m")
+    print("  Run \033[32mrewind show latest\033[0m to see the trace.")
+    print()