stepline 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. stepline/__init__.py +28 -0
  2. stepline/_util.py +98 -0
  3. stepline/cli/__init__.py +375 -0
  4. stepline/cli/render.py +511 -0
  5. stepline/config.py +86 -0
  6. stepline/demo/__init__.py +19 -0
  7. stepline/demo/mock_api.py +238 -0
  8. stepline/demo/weather_agent.py +158 -0
  9. stepline/py.typed +0 -0
  10. stepline/recorder/__init__.py +54 -0
  11. stepline/recorder/anthropic_adapter.py +517 -0
  12. stepline/recorder/base.py +167 -0
  13. stepline/recorder/pricing.py +246 -0
  14. stepline/recorder/recorder.py +423 -0
  15. stepline/recorder/redact.py +66 -0
  16. stepline/recorder/streaming.py +121 -0
  17. stepline/replay.py +496 -0
  18. stepline/server/__init__.py +5 -0
  19. stepline/server/app.py +401 -0
  20. stepline/server/schemas.py +272 -0
  21. stepline/server/security.py +185 -0
  22. stepline/server/static/assets/index-BWeF02Jm.js +49 -0
  23. stepline/server/static/assets/index-CCBg99Nd.css +2 -0
  24. stepline/server/static/assets/inter-cyrillic-ext-wght-normal-BOeWTOD4.woff2 +0 -0
  25. stepline/server/static/assets/inter-cyrillic-wght-normal-DqGufNeO.woff2 +0 -0
  26. stepline/server/static/assets/inter-greek-ext-wght-normal-DlzME5K_.woff2 +0 -0
  27. stepline/server/static/assets/inter-greek-wght-normal-CkhJZR-_.woff2 +0 -0
  28. stepline/server/static/assets/inter-latin-ext-wght-normal-DO1Apj_S.woff2 +0 -0
  29. stepline/server/static/assets/inter-latin-wght-normal-Dx4kXJAl.woff2 +0 -0
  30. stepline/server/static/assets/inter-vietnamese-wght-normal-CBcvBZtf.woff2 +0 -0
  31. stepline/server/static/assets/jetbrains-mono-cyrillic-ext-wght-normal-EocZY2iu.woff2 +0 -0
  32. stepline/server/static/assets/jetbrains-mono-cyrillic-wght-normal-D73BlboJ.woff2 +0 -0
  33. stepline/server/static/assets/jetbrains-mono-greek-wght-normal-Bw9x6K1M.woff2 +0 -0
  34. stepline/server/static/assets/jetbrains-mono-latin-ext-wght-normal-DBQx-q_a.woff2 +0 -0
  35. stepline/server/static/assets/jetbrains-mono-latin-wght-normal-B9CIFXIH.woff2 +0 -0
  36. stepline/server/static/assets/jetbrains-mono-vietnamese-wght-normal-Bt-aOZkq.woff2 +0 -0
  37. stepline/server/static/favicon.svg +1 -0
  38. stepline/server/static/index.html +15 -0
  39. stepline/storage/__init__.py +13 -0
  40. stepline/storage/db.py +149 -0
  41. stepline/storage/digest.py +121 -0
  42. stepline/storage/models.py +142 -0
  43. stepline/storage/store.py +575 -0
  44. stepline-0.1.0.dist-info/METADATA +274 -0
  45. stepline-0.1.0.dist-info/RECORD +48 -0
  46. stepline-0.1.0.dist-info/WHEEL +4 -0
  47. stepline-0.1.0.dist-info/entry_points.txt +2 -0
  48. stepline-0.1.0.dist-info/licenses/LICENSE +21 -0
stepline/__init__.py ADDED
@@ -0,0 +1,28 @@
1
+ """Stepline: a time-travel debugger for AI agents.
2
+
3
+ Two lines to start recording::
4
+
5
+ import stepline
6
+ client = stepline.wrap(Anthropic())
7
+
8
+ Then run ``stepline ui`` to inspect every step and replay from any of them.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from .config import configure
14
+ from .recorder import register_adapter, run, wrap
15
+ from .recorder.recorder import get_recorder
16
+
17
+ __version__ = "0.1.0"
18
+
19
+
20
+ def flush(timeout: float | None = None) -> bool:
21
+ """Block until all recorded calls are written to disk. Returns False on timeout.
22
+
23
+ Not normally needed: pending records are flushed automatically at interpreter exit.
24
+ """
25
+ return get_recorder().flush(timeout)
26
+
27
+
28
+ __all__ = ["__version__", "configure", "flush", "register_adapter", "run", "wrap"]
stepline/_util.py ADDED
@@ -0,0 +1,98 @@
1
+ """Small helpers shared across the package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import logging
7
+ import secrets
8
+ import time
9
+ from collections.abc import Mapping
10
+ from typing import Any
11
+
12
+ logger = logging.getLogger("stepline")
13
+ logger.addHandler(logging.NullHandler())
14
+
15
+ _warned: set[str] = set()
16
+
17
+
18
+ def new_id(prefix: str) -> str:
19
+ """Short, sortable-enough random id like ``run_3f9a1c0b7e2d``."""
20
+ return f"{prefix}_{secrets.token_hex(6)}"
21
+
22
+
23
+ def now() -> float:
24
+ return time.time()
25
+
26
+
27
+ def warn_once(key: str, message: str, exc: BaseException | None = None) -> None:
28
+ """Log an internal failure: a warning the first time per ``key``, debug afterwards."""
29
+ if key in _warned:
30
+ logger.debug(message, exc_info=exc)
31
+ return
32
+ _warned.add(key)
33
+ logger.warning(
34
+ "stepline: %s (recording continues; your app is unaffected)", message, exc_info=exc
35
+ )
36
+
37
+
38
+ def snapshot_containers(value: Any) -> Any:
39
+ """Copy dicts/lists/tuples recursively, keeping leaves as-is.
40
+
41
+ This runs on the caller's thread and must be cheap. It protects the recorded request
42
+ against the very common pattern of appending to ``messages`` after the call returns.
43
+ Leaves (strings, numbers, SDK model objects) are immutable in practice, so they are shared
44
+ and only converted to JSON later, on the background writer thread.
45
+ """
46
+ if isinstance(value, dict):
47
+ return {k: snapshot_containers(v) for k, v in value.items()}
48
+ if isinstance(value, (list, tuple)):
49
+ return [snapshot_containers(v) for v in value]
50
+ return value
51
+
52
+
53
+ def to_jsonable(value: Any, _depth: int = 0) -> Any:
54
+ """Best-effort conversion of SDK objects (pydantic models etc.) into plain JSON data."""
55
+ if _depth > 64:
56
+ return repr(value)
57
+ if value is None or isinstance(value, (bool, int, float, str)):
58
+ return value
59
+ if isinstance(value, Mapping):
60
+ return {str(k): to_jsonable(v, _depth + 1) for k, v in value.items()}
61
+ if isinstance(value, (list, tuple, set, frozenset)):
62
+ return [to_jsonable(v, _depth + 1) for v in value]
63
+ if isinstance(value, bytes):
64
+ return f"<{len(value)} bytes>"
65
+ model_dump = getattr(value, "model_dump", None)
66
+ if callable(model_dump):
67
+ try:
68
+ try:
69
+ dumped = model_dump(mode="json", exclude_none=True, warnings=False)
70
+ except TypeError: # older pydantic without the `warnings` flag
71
+ dumped = model_dump(mode="json", exclude_none=True)
72
+ return to_jsonable(dumped, _depth + 1)
73
+ except Exception:
74
+ pass
75
+ to_dict = getattr(value, "to_dict", None)
76
+ if callable(to_dict):
77
+ try:
78
+ return to_jsonable(to_dict(), _depth + 1)
79
+ except Exception:
80
+ pass
81
+ if hasattr(value, "__dict__"):
82
+ return {
83
+ k: to_jsonable(v, _depth + 1) for k, v in vars(value).items() if not k.startswith("_")
84
+ }
85
+ return repr(value)
86
+
87
+
88
+ def dumps(value: Any) -> str:
89
+ return json.dumps(value, ensure_ascii=False, separators=(",", ":"), default=repr)
90
+
91
+
92
+ def loads(value: str | None, default: Any = None) -> Any:
93
+ if value is None:
94
+ return default
95
+ try:
96
+ return json.loads(value)
97
+ except (TypeError, ValueError):
98
+ return default
@@ -0,0 +1,375 @@
1
+ """The ``stepline`` command-line interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import sys
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ import click
11
+ from rich import box
12
+ from rich.console import Console
13
+ from rich.table import Table
14
+ from rich.text import Text
15
+
16
+ from .. import __version__
17
+ from ..config import resolve_db_path
18
+ from ..storage import AmbiguousRunId, RunHasForks, RunNotFound, TraceStore
19
+ from . import render
20
+
21
+
22
+ class Ctx:
23
+ def __init__(self, db: Path | None) -> None:
24
+ self.db_path = resolve_db_path(db)
25
+ self.console = Console(highlight=False, soft_wrap=False)
26
+
27
+ def open_store(self) -> TraceStore:
28
+ if not self.db_path.exists():
29
+ self.console.print(
30
+ Text.assemble(
31
+ ("No traces yet ", "bold"),
32
+ (f"({self.db_path})\n", "dim"),
33
+ "Record some by wrapping your client:\n\n",
34
+ (" import stepline\n", "cyan"),
35
+ (" client = stepline.wrap(Anthropic())\n", "cyan"),
36
+ )
37
+ )
38
+ raise SystemExit(1)
39
+ return TraceStore(self.db_path)
40
+
41
+ def resolve(self, store: TraceStore, run_id: str | None) -> str:
42
+ if run_id is None:
43
+ latest = store.list_runs(limit=1)
44
+ if not latest:
45
+ raise click.ClickException("no runs recorded yet")
46
+ return latest[0].run.id
47
+ try:
48
+ return store.resolve_run_id(run_id)
49
+ except RunNotFound:
50
+ by_name = store.find_run_by_name(run_id)
51
+ if by_name:
52
+ return by_name
53
+ raise click.ClickException(
54
+ f"no run id or name matches {run_id!r} (see `stepline ls`)"
55
+ ) from None
56
+ except AmbiguousRunId as exc:
57
+ raise click.ClickException(str(exc)) from None
58
+
59
+
60
+ pass_ctx = click.make_pass_decorator(Ctx)
61
+
62
+
63
+ @click.group(context_settings={"help_option_names": ["-h", "--help"]})
64
+ @click.option(
65
+ "--db",
66
+ type=click.Path(dir_okay=False, path_type=Path),
67
+ envvar="STEPLINE_DB",
68
+ help="Trace database (default: ./.stepline/traces.db).",
69
+ )
70
+ @click.version_option(__version__, "-V", "--version", prog_name="stepline")
71
+ @click.pass_context
72
+ def cli(ctx: click.Context, db: Path | None) -> None:
73
+ """Stepline: a time-travel debugger for AI agents."""
74
+ ctx.obj = Ctx(db)
75
+
76
+
77
+ @cli.command("ls")
78
+ @click.option("-n", "--limit", default=20, show_default=True, help="Number of runs to show.")
79
+ @click.option("--no-forks", is_flag=True, help="Hide forked (replayed) runs.")
80
+ @click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
81
+ @pass_ctx
82
+ def ls_command(obj: Ctx, limit: int, no_forks: bool, as_json: bool) -> None:
83
+ """List recorded runs, newest first."""
84
+ with obj.open_store() as store:
85
+ summaries = store.list_runs(limit=limit, include_forks=not no_forks)
86
+ total = store.count_runs()
87
+ if as_json:
88
+ click.echo(json.dumps([s.to_dict() for s in summaries], indent=2))
89
+ return
90
+ if not summaries:
91
+ obj.console.print("No runs recorded yet.", style="dim")
92
+ return
93
+ obj.console.print(render.runs_table(summaries, width=obj.console.width))
94
+ if total > len(summaries):
95
+ obj.console.print(
96
+ f"showing {len(summaries)} of {total} runs · use -n to see more", style="dim"
97
+ )
98
+
99
+
100
+ @cli.command("show")
101
+ @click.argument("run_id", required=False)
102
+ @click.option("-s", "--step", "step_idx", type=int, help="Show one step in full (by index).")
103
+ @click.option("--full", is_flag=True, help="Don't truncate message previews.")
104
+ @click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
105
+ @pass_ctx
106
+ def show_command(
107
+ obj: Ctx, run_id: str | None, step_idx: int | None, full: bool, as_json: bool
108
+ ) -> None:
109
+ """Print a run as a step tree.
110
+
111
+ RUN_ID is a run id, a unique id prefix, or a run name (latest run with that name).
112
+ Defaults to the most recent run.
113
+ """
114
+ console = obj.console
115
+ with obj.open_store() as store:
116
+ resolved = obj.resolve(store, run_id)
117
+ summary = store.summarize(resolved)
118
+ assert summary is not None
119
+ steps = store.get_lineage(resolved)
120
+ forks = [s for s in (store.summarize(f.id) for f in store.list_forks(resolved)) if s]
121
+ forked_from = None
122
+ if summary.run.parent_run_id:
123
+ parent = store.get_run(summary.run.parent_run_id)
124
+ fork_step = (
125
+ store.get_step(summary.run.forked_from_step_id)
126
+ if summary.run.forked_from_step_id
127
+ else None
128
+ )
129
+ if parent is not None:
130
+ forked_from = (parent, fork_step)
131
+
132
+ if as_json:
133
+ payload: dict[str, Any] = summary.to_dict()
134
+ payload["steps"] = [s.to_dict() for s in steps]
135
+ payload["forks"] = [f.to_dict() for f in forks]
136
+ click.echo(json.dumps(payload, indent=2, ensure_ascii=False))
137
+ return
138
+
139
+ if step_idx is not None:
140
+ matches = [s for s in steps if s.idx == step_idx]
141
+ if not matches:
142
+ raise click.ClickException(f"run {resolved} has no step #{step_idx}")
143
+ render.step_detail(matches[-1], console)
144
+ return
145
+
146
+ console.print(render.run_header(summary, forked_from))
147
+ console.print(render.run_tree(summary, steps, forks, width=console.width, full=full))
148
+ if steps:
149
+ console.print(
150
+ Text.assemble(
151
+ (" stepline show ", "dim"),
152
+ (resolved, "dim cyan"),
153
+ (" --step N", "dim"),
154
+ (" for full messages · ", "dim"),
155
+ ("stepline ui", "dim cyan"),
156
+ (" to browse and replay", "dim"),
157
+ )
158
+ )
159
+
160
+
161
+ @cli.command("rm")
162
+ @click.argument("run_ids", nargs=-1, required=True)
163
+ @click.option("-y", "--yes", is_flag=True, help="Don't ask for confirmation.")
164
+ @click.option("--cascade", is_flag=True, help="Also delete runs forked from these runs.")
165
+ @pass_ctx
166
+ def rm_command(obj: Ctx, run_ids: tuple[str, ...], yes: bool, cascade: bool) -> None:
167
+ """Delete runs (and their steps)."""
168
+ with obj.open_store() as store:
169
+ resolved = [obj.resolve(store, r) for r in run_ids]
170
+ if not yes:
171
+ click.confirm(f"Delete {len(resolved)} run(s): {', '.join(resolved)}?", abort=True)
172
+ for run_id in resolved:
173
+ try:
174
+ store.delete_run(run_id, cascade_forks=cascade)
175
+ except RunHasForks as exc:
176
+ raise click.ClickException(f"{exc}. Use --cascade to delete them too.") from None
177
+ obj.console.print(f"Deleted {len(resolved)} run(s).", style="green")
178
+
179
+
180
+ @cli.command("prices")
181
+ @click.option("-m", "--model", help="Show the price that applies to this model id.")
182
+ @pass_ctx
183
+ def prices_command(obj: Ctx, model: str | None) -> None:
184
+ """Show the price table used for cost estimates (USD per million tokens)."""
185
+ from ..recorder.pricing import effective_prices, lookup, prices_path
186
+
187
+ console = obj.console
188
+ path = prices_path()
189
+ if model:
190
+ price = lookup(model)
191
+ if price is None:
192
+ raise click.ClickException(
193
+ f"no price for {model!r}; add it to {path} (see `stepline prices`)"
194
+ )
195
+ console.print(Text.assemble((model, "bold cyan"), f" {price}"))
196
+ return
197
+ table = Table(header_style="bold", box=box.SIMPLE_HEAD)
198
+ table.add_column("Model (prefix)", style="cyan")
199
+ for col in ("Input", "Output", "Cache read"):
200
+ table.add_column(col, justify="right")
201
+ table.add_column("Source", style="dim")
202
+ for key, (price, source) in sorted(effective_prices().items()):
203
+ cache = price.cache_read if price.cache_read is not None else price.input * 0.1
204
+ table.add_row(
205
+ key,
206
+ f"${price.input:g}",
207
+ f"${price.output:g}",
208
+ f"${cache:g}",
209
+ source if source == "built-in" else Text(source, style="yellow"),
210
+ )
211
+ console.print(table)
212
+ state = "found" if path.exists() else "not found"
213
+ console.print(
214
+ Text.assemble(
215
+ ("Overrides: ", "dim"),
216
+ (str(path), "cyan"),
217
+ (f" ({state}) · cache writes cost 1.25x input (5m) or 2x (1h)", "dim"),
218
+ )
219
+ )
220
+
221
+
222
+ @cli.command("ui")
223
+ @click.option("--host", default="127.0.0.1", show_default=True, help="Interface to bind.")
224
+ @click.option(
225
+ "-p", "--port", type=int, default=None, help="Port (default: 7777, or the next free one)."
226
+ )
227
+ @click.option("--open/--no-open", "open_browser", default=True, help="Open a browser tab.")
228
+ @click.option(
229
+ "--mock",
230
+ is_flag=True,
231
+ help="Send replays to the bundled offline mock API (no key, nothing sent or billed).",
232
+ )
233
+ @click.option(
234
+ "--allow-origin",
235
+ "allow_origins",
236
+ multiple=True,
237
+ envvar="STEPLINE_ALLOW_ORIGINS",
238
+ help="Extra exact origin allowed to call the API, e.g. a Vite dev server "
239
+ "(http://localhost:5173). Repeatable. No wildcards.",
240
+ )
241
+ @pass_ctx
242
+ def ui_command(
243
+ obj: Ctx,
244
+ host: str,
245
+ port: int | None,
246
+ open_browser: bool,
247
+ mock: bool,
248
+ allow_origins: tuple[str, ...],
249
+ ) -> None:
250
+ """Start the local web UI (http://127.0.0.1:7777)."""
251
+ import threading
252
+ import webbrowser
253
+
254
+ import uvicorn
255
+
256
+ from ..server import create_app
257
+ from ..server.security import LOOPBACK_HOSTS, is_loopback
258
+
259
+ console = obj.console
260
+ origins = [o for value in allow_origins for o in value.replace(",", " ").split()]
261
+ if any("*" in o for o in origins):
262
+ raise click.ClickException("--allow-origin takes exact origins; wildcards are not allowed")
263
+ allowed_hosts = set(LOOPBACK_HOSTS)
264
+ if not is_loopback(host):
265
+ console.print(
266
+ Text.assemble(
267
+ ("Warning: ", "bold red"),
268
+ f"binding to {host} exposes your recorded prompts and responses (and replay, "
269
+ "which spends API credits) to anyone who can reach this address.",
270
+ )
271
+ )
272
+ allowed_hosts.add(host)
273
+ chosen = _pick_port(host, port)
274
+ url_host = "127.0.0.1" if host in ("0.0.0.0", "::") else host
275
+ if ":" in url_host:
276
+ url_host = f"[{url_host}]"
277
+ url = f"http://{url_host}:{chosen}"
278
+
279
+ try:
280
+ app = create_app(
281
+ obj.db_path, allowed_hosts=allowed_hosts, allowed_origins=origins, replay_mock=mock
282
+ )
283
+ except ValueError as exc:
284
+ raise click.ClickException(str(exc)) from None
285
+ console.print(
286
+ Text.assemble(
287
+ ("Stepline UI ", "bold"),
288
+ (url, "bold cyan underline"),
289
+ (f" · {obj.db_path}", "dim"),
290
+ ("\nReplays use the offline mock API (--mock).", "yellow") if mock else "",
291
+ ("\nPress Ctrl+C to stop.", "dim"),
292
+ )
293
+ )
294
+ if open_browser:
295
+ threading.Timer(0.8, lambda: webbrowser.open(url)).start()
296
+ uvicorn.run(app, host=host, port=chosen, log_level="warning", server_header=False)
297
+
298
+
299
+ def _pick_port(host: str, requested: int | None) -> int:
300
+ """The requested port (must be free), else 7777 or the next free port after it."""
301
+ import socket
302
+
303
+ def free(port: int) -> bool:
304
+ family = socket.AF_INET6 if ":" in host else socket.AF_INET
305
+ with socket.socket(family, socket.SOCK_STREAM) as sock:
306
+ # Same option uvicorn uses, so sockets lingering in TIME_WAIT after a restart
307
+ # don't make a free port look busy. A port with a live listener still fails.
308
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
309
+ try:
310
+ sock.bind((host, port))
311
+ sock.listen(1)
312
+ except OSError:
313
+ return False
314
+ return True
315
+
316
+ if requested is not None:
317
+ if requested and not free(requested):
318
+ raise click.ClickException(f"port {requested} is already in use")
319
+ return requested
320
+ for port in range(7777, 7797):
321
+ if free(port):
322
+ return port
323
+ raise click.ClickException("no free port between 7777 and 7796; pass --port")
324
+
325
+
326
+ @cli.command("demo")
327
+ @pass_ctx
328
+ def demo_command(obj: Ctx) -> None:
329
+ """Record the example agent offline (mock API: no key, no cost), then try `stepline ui`."""
330
+ import runpy
331
+
332
+ from .. import config
333
+ from ..demo import example_path
334
+
335
+ path = example_path()
336
+ config.configure(db_path=obj.db_path)
337
+ obj.console.print(
338
+ Text.assemble(
339
+ ("Running the example agent against the offline mock API", "bold"),
340
+ (f" ({path.name}; no API key, nothing billed)\n", "dim"),
341
+ )
342
+ )
343
+ argv = sys.argv
344
+ sys.argv = [str(path), "--mock"]
345
+ try:
346
+ runpy.run_path(str(path), run_name="__main__")
347
+ except SystemExit as exc:
348
+ if exc.code not in (0, None):
349
+ raise
350
+ finally:
351
+ sys.argv = argv
352
+ obj.console.print(
353
+ Text.assemble(
354
+ ("\nNext: ", "bold"),
355
+ ("stepline ui", "bold cyan"),
356
+ (" to open the timeline, or ", "dim"),
357
+ ("stepline show", "bold cyan"),
358
+ (" for the terminal view.", "dim"),
359
+ )
360
+ )
361
+
362
+
363
+ @cli.command("openapi")
364
+ def openapi_command() -> None:
365
+ """Print the API's OpenAPI schema (used to generate the frontend's types)."""
366
+ from ..server import openapi_schema
367
+
368
+ click.echo(json.dumps(openapi_schema(), indent=2, sort_keys=True))
369
+
370
+
371
+ def main(argv: list[str] | None = None) -> None:
372
+ try:
373
+ cli.main(args=argv, prog_name="stepline")
374
+ except BrokenPipeError: # e.g. `stepline ls | head`
375
+ sys.exit(0)