agentstep 0.1.1__tar.gz → 0.1.2__tar.gz

{agentstep-0.1.1 → agentstep-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentstep
-Version: 0.1.1
+Version: 0.1.2
 Summary: Time-travel debugger and branch explorer for LangGraph AI agents. Capture execution traces, inspect LLM and tool calls, and branch from any point with overridden outputs.
 Project-URL: Homepage, https://github.com/vanshvisariya/agentstep
 Project-URL: Repository, https://github.com/vanshvisariya/agentstep

agentstep-0.1.2/docs/USAGE.md

@@ -0,0 +1,145 @@
+# AgentStep Usage Guide
+
+AgentStep is a time-travel debugger for LangGraph agents. It records LLM and tool calls into a SQLite trace, lets you inspect the run in a web UI, and lets you branch from any step with an overridden output.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install agentstep
+```
+
+Install from a local checkout during development:
+
+```bash
+git clone https://github.com/vanshvisariya/agentstep
+cd agentstep
+pip install -e .
+```
+
+AgentStep requires Python 3.13 or newer.
+
+## Instrument your graph
+
+Use the tracing context manager from `agentstep.sdk.tracer` when you run your LangGraph graph. The context manager writes spans to a SQLite file.
+
+```python
+from agentstep.sdk.tracer import replay_trace
+
+config = {"configurable": {"thread_id": "user-42"}}
+
+with replay_trace(config, sqlite_path="trace.sqlite") as cfg:
+    result = graph.stream(inputs, cfg, stream_mode="values")
+    for chunk in result:
+        print(chunk)
+```
+
+What this does:
+
+1. Hooks OpenTelemetry into the graph run.
+2. Stores LLM and tool spans in `trace.sqlite`.
+3. Adds the callback handler to the LangGraph config in place.
+
+## Run the debugger
+
+After you have a trace file, launch the debugger with the `replay-debugger` command:
+
+```bash
+replay-debugger trace.sqlite --app sample:graph
+```
+
+The `--app` argument should point at your compiled graph:
+
+- `my_module:graph` for a graph object
+- `my_module.graph` for dotted import syntax
+- `my_module:make_graph` for a callable that returns a compiled graph
+
+Open `http://localhost:7337` in your browser.
+
+### Development UI mode
+
+When editing the frontend or backend, start the server without the bundled UI:
+
+```bash
+replay-debugger trace.sqlite --app sample:graph --dev-ui
+```
+
+Then run the Vite dev server from `ui/`:
+
+```bash
+cd ui
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173` instead.
+
+## Branch from a step
+
+In the UI:
+
+1. Click a span in the timeline.
+2. Click **branch from here**.
+3. Edit the override output.
+4. Run the branch replay.
+
+The original trace stays unchanged and the branch is added as a new replay path.
+
+## Programmatic branch replay
+
+If you want to branch from code, use `replay_branch`:
+
+```python
+from agentstep.server.replayer import replay_branch
+
+result = replay_branch(
+    thread_id="user-42",
+    checkpoint_id="1efb...",
+    node_name="tools",
+    span_type="tool_call",
+    tool_call_id="get_weather",
+    new_output="It's snowing in San Francisco.",
+    db_path="trace.sqlite",
+)
+
+print(result)
+```
+
+## Demo app
+
+This repository includes `sample.py`, a fake-weather LangGraph demo that runs without API keys.
+
+```bash
+python sample.py
+replay-debugger trace.sqlite --app sample:graph
+```
+
+## API endpoints
+
+The debugger server exposes these endpoints:
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/threads` | List thread ids |
+| `GET` | `/api/traces/{thread_id}` | Get spans grouped by branch |
+| `GET` | `/api/traces/{thread_id}/checkpoints` | Get checkpoints for a thread |
+| `POST` | `/api/branch` | Create a replay branch from a checkpoint |
+
+## Troubleshooting
+
+- If the UI 404s, build the frontend first with `cd ui && npm run build`.
+- If port `7337` is already in use, stop the old debugger process or pass `--port`.
+- If the debugger cannot find your graph, double-check the import path passed to `--app`.
+
+## Package layout
+
+Key entry points in this repo:
+
+```text
+src/agentstep/sdk/tracer.py    replay_trace()
+src/agentstep/server/cli.py    replay-debugger command
+src/agentstep/server/api.py    FastAPI routes
+src/agentstep/server/replayer.py branch replay logic
+sample.py                      local demo graph
+```

{agentstep-0.1.1 → agentstep-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentstep"
-version = "0.1.1"
+version = "0.1.2"
 description = "Time-travel debugger and branch explorer for LangGraph AI agents. Capture execution traces, inspect LLM and tool calls, and branch from any point with overridden outputs."
 readme = "README.md"
 license = "MIT"

{agentstep-0.1.1 → agentstep-0.1.2}/src/agentstep/server/cli.py

@@ -15,14 +15,13 @@ from langgraph.checkpoint.sqlite import SqliteSaver
 
 
 def _resolve_ui_build() -> Path | None:
-    """Walk up from the package dir looking for ui/dist, then try CWD."""
-    # The package lives at <repo>/src/agentstep/server/cli.py
-    # We want <repo>/ui/dist — three levels up from this file.
+    """Find the bundled React UI. Checks package-local first, then source repo layout."""
     here = Path(__file__).resolve().parent
     candidates = [
-        here.parents[2] / "ui" / "dist",   # repo-rooted: src/agentstep/server -> src/agentstep -> src -> repo
-        Path.cwd() / "ui" / "dist",
-        Path.cwd() / "dist",
+        here / "ui_dist",                                          # bundled inside installed package
+        here.parents[2] / "ui" / "dist",                           # source repo layout
+        Path.cwd() / "ui" / "dist",                                # CWD fallback
+        Path.cwd() / "dist",                                       # CWD fallback
     ]
     for p in candidates:
         if (p / "index.html").is_file():

agentstep-0.1.2/src/agentstep/server/ui_dist/assets/index-CFWPmmyX.css

@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.1 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-rotate-x:initial;--tw-rotate-y:initial;--tw-rotate-z:initial;--tw-skew-x:initial;--tw-skew-y:initial;--tw-space-y-reverse:0;--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial}}}@layer theme{:root,:host{--font-sans:ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--spacing:.25rem;--font-weight-semibold:600;--tracking-wide:.025em;--tracking-wider:.05em;--leading-relaxed:1.625;--animate-spin:spin 1s linear infinite;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono);--color-ink:#0d1117;--color-ink-2:#161b22;--color-ink-3:#21262d;--color-ink-4:#30363d;--color-ink-5:#484f58;--color-mute:#7d8590;--color-text:#c9d1d9;--color-text-dim:#8b949e;--color-orig:#f0883e;--color-b0:#a371f7;--color-b1:#3fb950;--color-b2:#db61a2;--color-b3:#39c5cf;--color-b4:#e3b341}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring{outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab, red, red)){::placeholder{color:color-mix(in oklab, currentcolor 50%, transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}}@layer components;@layer utilities{.absolute{position:absolute}.fixed{position:fixed}.relative{position:relative}.inset-0{inset:0}.top-0{top:0}.bottom-0{bottom:0}.-left-\[24px\]{left:-24px}.left-\[7px\]{left:7px}.z-10{z-index:10}.z-50{z-index:50}.mt-0\.5{margin-top:calc(var(--spacing) * .5)}.mt-16{margin-top:calc(var(--spacing) * 16)}.mr-2{margin-right:calc(var(--spacing) * 2)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.ml-2{margin-left:calc(var(--spacing) * 2)}.ml-auto{margin-left:auto}.block{display:block}.flex{display:flex}.inline-block{display:inline-block}.h-1\.5{height:calc(var(--spacing) * 1.5)}.h-7{height:calc(var(--spacing) * 7)}.h-8{height:calc(var(--spacing) * 8)}.h-10{height:calc(var(--spacing) * 10)}.h-12{height:calc(var(--spacing) * 12)}.h-56{height:calc(var(--spacing) * 56)}.h-\[16px\]{height:16px}.h-\[18px\]{height:18px}.h-full{height:100%}.h-screen{height:100vh}.max-h-64{max-height:calc(var(--spacing) * 64)}.w-1\.5{width:calc(var(--spacing) * 1.5)}.w-3{width:calc(var(--spacing) * 3)}.w-\[220px\]{width:220px}.w-\[400px\]{width:400px}.w-full{width:100%}.w-px{width:1px}.max-w-\[560px\]{max-width:560px}.max-w-\[860px\]{max-width:860px}.min-w-0{min-width:0}.flex-1{flex:1}.shrink-0{flex-shrink:0}.transform{transform:var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,)}.animate-spin{animation:var(--animate-spin)}.cursor-pointer{cursor:pointer}.resize-none{resize:none}.flex-col{flex-direction:column}.items-baseline{align-items:baseline}.items-center{align-items:center}.justify-between{justify-content:space-between}.justify-center{justify-content:center}.justify-end{justify-content:flex-end}.gap-1{gap:var(--spacing)}.gap-1\.5{gap:calc(var(--spacing) * 1.5)}.gap-2{gap:calc(var(--spacing) * 2)}.gap-3{gap:calc(var(--spacing) * 3)}:where(.space-y-1>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(var(--spacing) * var(--tw-space-y-reverse));margin-block-end:calc(var(--spacing) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-2>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 2) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 2) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-3>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 3) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 3) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-5>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 5) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 5) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-7>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 7) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 7) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-px>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(1px * var(--tw-space-y-reverse));margin-block-end:calc(1px * calc(1 - var(--tw-space-y-reverse)))}.truncate{text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.overflow-hidden{overflow:hidden}.overflow-y-auto{overflow-y:auto}.border{border-style:var(--tw-border-style);border-width:1px}.border-t{border-top-style:var(--tw-border-style);border-top-width:1px}.border-r{border-right-style:var(--tw-border-style);border-right-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-l{border-left-style:var(--tw-border-style);border-left-width:1px}.p-1{padding:var(--spacing)}.p-2{padding:calc(var(--spacing) * 2)}.p-3{padding:calc(var(--spacing) * 3)}.p-4{padding:calc(var(--spacing) * 4)}.p-5{padding:calc(var(--spacing) * 5)}.px-1{padding-inline:var(--spacing)}.px-1\.5{padding-inline:calc(var(--spacing) * 1.5)}.px-2{padding-inline:calc(var(--spacing) * 2)}.px-3{padding-inline:calc(var(--spacing) * 3)}.px-4{padding-inline:calc(var(--spacing) * 4)}.px-5{padding-inline:calc(var(--spacing) * 5)}.px-8{padding-inline:calc(var(--spacing) * 8)}.py-1\.5{padding-block:calc(var(--spacing) * 1.5)}.py-2{padding-block:calc(var(--spacing) * 2)}.py-6{padding-block:calc(var(--spacing) * 6)}.py-12{padding-block:calc(var(--spacing) * 12)}.pt-4{padding-top:calc(var(--spacing) * 4)}.pr-3{padding-right:calc(var(--spacing) * 3)}.pb-2{padding-bottom:calc(var(--spacing) * 2)}.pl-6{padding-left:calc(var(--spacing) * 6)}.text-center{text-align:center}.text-left{text-align:left}.align-top{vertical-align:top}.text-\[9\.5px\]{font-size:9.5px}.text-\[10\.5px\]{font-size:10.5px}.text-\[10px\]{font-size:10px}.text-\[11\.5px\]{font-size:11.5px}.text-\[11px\]{font-size:11px}.text-\[12\.5px\]{font-size:12.5px}.text-\[12px\]{font-size:12px}.text-\[14px\]{font-size:14px}.leading-\[16px\]{--tw-leading:16px;line-height:16px}.leading-\[18px\]{--tw-leading:18px;line-height:18px}.leading-relaxed{--tw-leading:var(--leading-relaxed);line-height:var(--leading-relaxed)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.tracking-\[0\.12em\]{--tw-tracking:.12em;letter-spacing:.12em}.tracking-\[0\.14em\]{--tw-tracking:.14em;letter-spacing:.14em}.tracking-wide{--tw-tracking:var(--tracking-wide);letter-spacing:var(--tracking-wide)}.tracking-wider{--tw-tracking:var(--tracking-wider);letter-spacing:var(--tracking-wider)}.break-words{overflow-wrap:break-word}.break-all{word-break:break-all}.whitespace-nowrap{white-space:nowrap}.whitespace-pre-wrap{white-space:pre-wrap}.uppercase{text-transform:uppercase}.italic{font-style:italic}.filter{filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition-colors{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.outline-none{--tw-outline-style:none;outline-style:none}.select-none{-webkit-user-select:none;user-select:none}}html,body,#root{background:var(--color-ink);height:100%;color:var(--color-text);-webkit-font-smoothing:antialiased;margin:0;font-family:Inter,system-ui,-apple-system,sans-serif;font-size:13px}.mono{font-family:JetBrains Mono,ui-monospace,Menlo,Consolas,monospace}::-webkit-scrollbar{width:8px;height:8px}::-webkit-scrollbar-track{background:0 0}::-webkit-scrollbar-thumb{background:var(--color-ink-3);border-radius:0}::-webkit-scrollbar-thumb:hover{background:var(--color-ink-4)}::selection{background:var(--color-orig);color:var(--color-ink)}html{scroll-behavior:smooth}@keyframes draw{0%{stroke-dashoffset:240px;opacity:0}to{stroke-dashoffset:0;opacity:1}}.fork-rail{stroke-dasharray:240;stroke-dashoffset:240px;fill:none;stroke-width:1.25px;animation:.36s cubic-bezier(.22,1,.36,1) forwards draw}@media (prefers-reduced-motion:reduce){.fork-rail{stroke-dashoffset:0;opacity:1;animation:none}html{scroll-behavior:auto}}@property --tw-rotate-x{syntax:"*";inherits:false}@property --tw-rotate-y{syntax:"*";inherits:false}@property --tw-rotate-z{syntax:"*";inherits:false}@property --tw-skew-x{syntax:"*";inherits:false}@property --tw-skew-y{syntax:"*";inherits:false}@property --tw-space-y-reverse{syntax:"*";inherits:false;initial-value:0}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@keyframes spin{to{transform:rotate(360deg)}}