traceact 0.1.1__tar.gz → 0.2.1__tar.gz

traceact-0.2.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: traceact
+Version: 0.2.1
+Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
+Author: Mohammed Shehu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/traceact/traceact
+Project-URL: Repository, https://github.com/traceact/traceact
+Project-URL: Documentation, https://github.com/traceact/traceact/blob/main/USAGE.md
+Project-URL: Changelog, https://github.com/traceact/traceact/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/traceact/traceact/issues
+Project-URL: Author, https://mohammedshehu.com
+Keywords: tracing,observability,debugging,devtools,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# TraceAct
+
+[![PyPI version](https://img.shields.io/pypi/v/traceact.svg)](https://pypi.org/project/traceact/)
+[![Python versions](https://img.shields.io/pypi/pyversions/traceact.svg)](https://pypi.org/project/traceact/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+X-ray vision for Python code.
+
+TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs — every step taken, resource touched, event recorded, and failure encountered — so you or your agent can understand what actually happened.
+
+## Install
+
+```bash
+pip install traceact
+```
+
+## Quick start
+
+```python
+from traceact import traced_action, configure, TraceConfig, JsonlSink
+
+configure(
+    config=TraceConfig(sink_mode="blocking"),
+    sinks=[JsonlSink("data/traces.jsonl")],
+)
+
+@traced_action(action="note.create", kind="app", actor="user")
+def create_note(title, body):
+    ...
+```
+
+Each traced function call produces one JSON object appended to the JSONL file. Open the viewer to explore it live.
+
+## Manual tracing
+
+```python
+from traceact import ActionTrace
+
+with ActionTrace.start(action="note.create", kind="app") as trace:
+    trace.input({"title": "Hello"})
+    trace.step("Validated input")
+    trace.event(kind="db", operation="insert", target="notes")
+    trace.output({"note_id": "note_123"})
+```
+
+## The viewer
+
+TraceAct includes a local web viewer. No extra install — it ships with the package.
+
+```bash
+traceact view data/traces.jsonl
+```
+
+This starts a server at `http://127.0.0.1:8765` and opens your browser. The viewer tails the file live: traces appear as your app writes them.
+
+### Source types
+
+| What you pass | What happens |
+|---|---|
+| A `.jsonl` file | Tails that file live |
+| A folder | Merges all `.jsonl` files inside (e.g. per-process shards) |
+| Nothing | Opens empty; use the in-app modal to add a source |
+
+### CLI flags
+
+```bash
+traceact view [SOURCE] [--port N] [--host HOST] [--no-browser] [--new]
+traceact show [SOURCE] ...   # identical alias of view
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--port N` | `8765` | Port to serve on |
+| `--host HOST` | `127.0.0.1` | Interface to bind (localhost only by default) |
+| `--no-browser` | off | Start the server without opening a browser tab |
+| `--new` | off | Force a fresh instance even if one is already running |
+
+### Port selection
+
+The viewer auto-increments the port if the requested one is taken. If you ask for `8765` and it's in use, it tries `8766`, `8767`, and so on up to 20 times before giving up. Pass `--port` to start from a different base.
+
+### Single-instance behaviour
+
+Running `traceact view` a second time reuses an already-running viewer rather than starting a second server. The new source (if given) is added to the running viewer and a browser tab is opened on it. This means you can call `traceact view path/to/new-file.jsonl` from multiple terminal tabs during a session and they all feed into one viewer.
+
+Pass `--new` to bypass this and force a second independent instance.
+
+### macOS launcher
+
+Double-click `launch.command` in the repo root to open TraceAct from Finder without a terminal. It checks for a running instance first, then creates a `.venv/`, installs or upgrades `traceact`, and opens the browser.
+
+### Adding sources in the app
+
+The source modal (click the source name in the header) lets you:
+
+- **Choose file / Choose folder** — opens a native macOS picker; returns the real filesystem path for live tailing
+- **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
+- **Type a path** — collapsible fallback for pasting an absolute path
+
+## Concepts
+
+| Concept | Meaning |
+|---|---|
+| `Trace` | The full record of one action (function call) |
+| `Step` | A human-readable timeline marker within a trace |
+| `Event` | A structured operation: db, http, file, model, job, etc. |
+| `Touch` | A resource involved in the trace (auto-derived from events) |
+| `Sink` | Where completed traces are written (`JsonlSink`, `ConsoleSink`) |
+
+## Wiring into a web app
+
+If your app has its own UI, add a backend route to launch or connect to the viewer, then call it from a button:
+
+```python
+# FastAPI — launch_or_connect is blocking, so use run_in_executor
+import asyncio
+from traceact.viewer.instance import launch_or_connect
+
+@router.get("/api/launch-viewer")
+async def launch_viewer():
+    loop = asyncio.get_event_loop()
+    url = await loop.run_in_executor(None, launch_or_connect,
+                                     "data/traces/traces.jsonl")
+    return {"url": url}
+```
+
+```javascript
+// Frontend button
+document.getElementById("btn-viewer").addEventListener("click", async () => {
+    const btn = document.getElementById("btn-viewer");
+    btn.disabled = true;
+    try {
+        const { url } = await fetch("/api/launch-viewer").then(r => r.json());
+        window.open(url, "_blank", "noopener");
+    } finally {
+        btn.disabled = false;
+    }
+});
+```
+
+`launch_or_connect` checks for a running viewer first (via `~/.traceact/viewer.json` + a health probe). If one is found, it adds your source to it and returns the URL immediately — no new process. If nothing is running, it spawns the viewer as a background subprocess and waits up to 3 s for it to be ready.
+
+## Requirements
+
+Python 3.9+. No runtime dependencies.
+
+## Full reference
+
+See [USAGE.md](USAGE.md) for complete API documentation: all decorator and context manager parameters, helper methods (`trace.db`, `trace.http`, `trace.file`, `trace.model`), input capture, parent/child traces, sinks, budget configuration, the trace record schema, test isolation, and the full viewer server API.
+
+## License
+
+MIT
+
+---
+
+Built by [Mo Shehu](https://mohammedshehu.com).

traceact-0.2.1/README.md

@@ -0,0 +1,157 @@
+# TraceAct
+
+[![PyPI version](https://img.shields.io/pypi/v/traceact.svg)](https://pypi.org/project/traceact/)
+[![Python versions](https://img.shields.io/pypi/pyversions/traceact.svg)](https://pypi.org/project/traceact/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+X-ray vision for Python code.
+
+TraceAct is a lightweight Python package for action-level tracing. It records the full story of what happens when a function runs — every step taken, resource touched, event recorded, and failure encountered — so you or your agent can understand what actually happened.
+
+## Install
+
+```bash
+pip install traceact
+```
+
+## Quick start
+
+```python
+from traceact import traced_action, configure, TraceConfig, JsonlSink
+
+configure(
+    config=TraceConfig(sink_mode="blocking"),
+    sinks=[JsonlSink("data/traces.jsonl")],
+)
+
+@traced_action(action="note.create", kind="app", actor="user")
+def create_note(title, body):
+    ...
+```
+
+Each traced function call produces one JSON object appended to the JSONL file. Open the viewer to explore it live.
+
+## Manual tracing
+
+```python
+from traceact import ActionTrace
+
+with ActionTrace.start(action="note.create", kind="app") as trace:
+    trace.input({"title": "Hello"})
+    trace.step("Validated input")
+    trace.event(kind="db", operation="insert", target="notes")
+    trace.output({"note_id": "note_123"})
+```
+
+## The viewer
+
+TraceAct includes a local web viewer. No extra install — it ships with the package.
+
+```bash
+traceact view data/traces.jsonl
+```
+
+This starts a server at `http://127.0.0.1:8765` and opens your browser. The viewer tails the file live: traces appear as your app writes them.
+
+### Source types
+
+| What you pass | What happens |
+|---|---|
+| A `.jsonl` file | Tails that file live |
+| A folder | Merges all `.jsonl` files inside (e.g. per-process shards) |
+| Nothing | Opens empty; use the in-app modal to add a source |
+
+### CLI flags
+
+```bash
+traceact view [SOURCE] [--port N] [--host HOST] [--no-browser] [--new]
+traceact show [SOURCE] ...   # identical alias of view
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--port N` | `8765` | Port to serve on |
+| `--host HOST` | `127.0.0.1` | Interface to bind (localhost only by default) |
+| `--no-browser` | off | Start the server without opening a browser tab |
+| `--new` | off | Force a fresh instance even if one is already running |
+
+### Port selection
+
+The viewer auto-increments the port if the requested one is taken. If you ask for `8765` and it's in use, it tries `8766`, `8767`, and so on up to 20 times before giving up. Pass `--port` to start from a different base.
+
+### Single-instance behaviour
+
+Running `traceact view` a second time reuses an already-running viewer rather than starting a second server. The new source (if given) is added to the running viewer and a browser tab is opened on it. This means you can call `traceact view path/to/new-file.jsonl` from multiple terminal tabs during a session and they all feed into one viewer.
+
+Pass `--new` to bypass this and force a second independent instance.
+
+### macOS launcher
+
+Double-click `launch.command` in the repo root to open TraceAct from Finder without a terminal. It checks for a running instance first, then creates a `.venv/`, installs or upgrades `traceact`, and opens the browser.
+
+### Adding sources in the app
+
+The source modal (click the source name in the header) lets you:
+
+- **Choose file / Choose folder** — opens a native macOS picker; returns the real filesystem path for live tailing
+- **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
+- **Type a path** — collapsible fallback for pasting an absolute path
+
+## Concepts
+
+| Concept | Meaning |
+|---|---|
+| `Trace` | The full record of one action (function call) |
+| `Step` | A human-readable timeline marker within a trace |
+| `Event` | A structured operation: db, http, file, model, job, etc. |
+| `Touch` | A resource involved in the trace (auto-derived from events) |
+| `Sink` | Where completed traces are written (`JsonlSink`, `ConsoleSink`) |
+
+## Wiring into a web app
+
+If your app has its own UI, add a backend route to launch or connect to the viewer, then call it from a button:
+
+```python
+# FastAPI — launch_or_connect is blocking, so use run_in_executor
+import asyncio
+from traceact.viewer.instance import launch_or_connect
+
+@router.get("/api/launch-viewer")
+async def launch_viewer():
+    loop = asyncio.get_event_loop()
+    url = await loop.run_in_executor(None, launch_or_connect,
+                                     "data/traces/traces.jsonl")
+    return {"url": url}
+```
+
+```javascript
+// Frontend button
+document.getElementById("btn-viewer").addEventListener("click", async () => {
+    const btn = document.getElementById("btn-viewer");
+    btn.disabled = true;
+    try {
+        const { url } = await fetch("/api/launch-viewer").then(r => r.json());
+        window.open(url, "_blank", "noopener");
+    } finally {
+        btn.disabled = false;
+    }
+});
+```
+
+`launch_or_connect` checks for a running viewer first (via `~/.traceact/viewer.json` + a health probe). If one is found, it adds your source to it and returns the URL immediately — no new process. If nothing is running, it spawns the viewer as a background subprocess and waits up to 3 s for it to be ready.
+
+## Requirements
+
+Python 3.9+. No runtime dependencies.
+
+## Full reference
+
+See [USAGE.md](USAGE.md) for complete API documentation: all decorator and context manager parameters, helper methods (`trace.db`, `trace.http`, `trace.file`, `trace.model`), input capture, parent/child traces, sinks, budget configuration, the trace record schema, test isolation, and the full viewer server API.
+
+## License
+
+MIT
+
+---
+
+Built by [Mo Shehu](https://mohammedshehu.com).

{traceact-0.1.1 → traceact-0.2.1}/USAGE.md

@@ -1,6 +1,32 @@
 # TraceAct Usage Reference
 
-Full API documentation for TraceAct v0.1.0.
+Full API and CLI documentation for TraceAct.
+
+## Package layout
+
+```
+traceact/
+  __init__.py     — public exports
+  trace.py        — ActionTrace class, core lifecycle
+  decorators.py   — @traced_action decorator (sync + async)
+  config.py       — TraceConfig, configure(), reset_config()
+  budget.py       — TraceBudget, TraceBudget.production() preset
+  context.py      — ContextVar for active trace, SKIP sentinel
+  sinks.py        — JsonlSink (thread-safe), ConsoleSink, AsyncSink (not yet public)
+  helpers.py      — TraceHelpersMixin (trace.db, trace.http, trace.file, trace.model)
+  ids.py          — ID generation (trc_, evt_, stp_, corr_ prefixes)
+
+  viewer/
+    cli.py        — `traceact view` / `traceact show` CLI entry point; --new flag
+    server.py     — stdlib ThreadingHTTPServer; SPA + REST + SSE
+    reader.py     — SourceReader: JSONL snapshot + live byte-offset tail
+    instance.py   — single-instance coordination (state file + HTTP probe);
+                    launch_or_connect() for embedding in app backends
+    static/
+      index.html  — single-page app shell
+      styles.css  — design system (dark theme, CSS custom properties)
+      app.js      — all frontend logic (no framework, no build step)
+```
 
 ## Contents
 
@@ -21,6 +47,8 @@ Full API documentation for TraceAct v0.1.0.
 15. [TraceConfig fields](#traceconfig-fields)
 16. [Test isolation](#test-isolation)
 17. [Trace record schema](#trace-record-schema)
+18. [Viewing traces](#viewing-traces)
+19. [Integrating the viewer into your app](#integrating-the-viewer-into-your-app)
 
 ---
 
@@ -486,6 +514,24 @@ def run_agent():
     ...
 ```
 
+### Production preset
+
+The package default records every trace (`sample_rate=1.0`), which is right for development and first-run — you trace a function, run it once, and the trace is there. For high-volume production, `TraceBudget.production()` opts into a lighter footprint:
+
+```python
+from traceact import configure, TraceBudget
+
+configure(budget=TraceBudget.production())
+# equivalent to TraceBudget(sample_rate=0.1, always_trace_errors=True)
+```
+
+It records roughly 10% of successful traces while never dropping a failure. Only `sample_rate` and `always_trace_errors` are set; every other field inherits from the package default or a parent trace. Override a single field on top of the preset if needed:
+
+```python
+budget = TraceBudget.production()
+budget.sample_rate = 0.25   # record 25% instead of 10%
+```
+
 ---
 
 ## TraceConfig fields
@@ -619,6 +665,186 @@ The full JSON object written to the JSONL sink:
 
 ---
 
+## Viewing traces
+
+TraceAct ships with a local, dependency-free web viewer. Installing the package gives you both the SDK and the `traceact` command — there is no separate viewer package to install.
+
+```bash
+pip install traceact
+traceact view data/traces/traces.jsonl
+```
+
+This opens a browser at `http://127.0.0.1:8765` showing a live trace log, a trace map, and an inspector. The viewer tails the source, so traces appear as your app writes them.
+
+### Command
+
+```bash
+traceact view [SOURCE]     # open the viewer
+traceact show [SOURCE]     # alias of view (identical)
+```
+
+`view` and `show` are interchangeable aliases of the same command.
+
+`SOURCE` is optional and may be:
+
+- a `.jsonl` file — `traceact view data/traces.jsonl`
+- a folder of `.jsonl` files — `traceact view data/traces/` (merges every file inside, e.g. per-process shards or several apps' files)
+- omitted — `traceact view` opens empty and prompts you to add a source
+
+The viewer reads any line that parses as JSON and looks like a trace; malformed entries are skipped, so files being appended to concurrently are safe to read.
+
+### Flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--port N` | `8765` | Port to serve on. Auto-increments if the port is taken. |
+| `--host HOST` | `127.0.0.1` | Interface to bind. Localhost only by default. |
+| `--no-browser` | off | Start the server without opening a browser tab. |
+| `--new` | off | Force a new viewer instance even if one is already running. |
+
+You can also run it as a module: `python -m traceact.viewer.cli view SOURCE`.
+
+### Single-instance behaviour
+
+Running `traceact view` a second time — even for a different source — reuses a viewer that is already running rather than spawning a second server. The new source is added to the running viewer and a browser tab is opened on it. This avoids accumulating background processes across repeated launches during a dev session.
+
+The coordination mechanism is a state file at `~/.traceact/viewer.json` that records the host and port of the running viewer. On each launch, TraceAct probes that address with a health check before deciding whether to reuse or start fresh. A stale state file (crashed or stopped viewer) is ignored and a new server starts normally.
+
+Pass `--new` to bypass this and force a second instance — useful when you want two viewers side-by-side with different sources.
+
+### Adding sources in the viewer
+
+The "Add source" modal supports three ways to load a source:
+
+- **Choose file / Choose folder buttons** — opens a native macOS file or folder picker. The picker runs on the server side via AppleScript (`osascript`), so it returns the real filesystem path and the viewer can tail it live. (Falls back to a `tkinter` dialog on non-macOS platforms.)
+- **Drag and drop** — drop a `.jsonl` file onto the drop zone. The browser reads the file contents and posts them to the server, which saves a copy to `~/.traceact/imports/` and adds it as a source. Because the server holds a copy (not the original), this is a **static snapshot** — new writes to the original file won't appear. The viewer labels imported sources accordingly.
+- **Type a path** — a collapsible text input for pasting or typing an absolute path. This gives live tailing just like the command-line argument.
+
+### macOS launcher (`launch.command`)
+
+`launch.command` is a double-clickable shell script in the repo root. Opening it from Finder:
+
+1. Probes port 8765 — if a viewer is already running, opens it immediately and exits.
+2. Finds Python 3.9+ on the machine (checks pyenv shims, Homebrew, system Python).
+3. Creates (or reuses) a `.venv/` virtual environment in the same directory.
+4. Installs or upgrades `traceact` inside that venv.
+5. Runs `traceact view`, waits for the server to be ready, then opens the browser.
+
+The Terminal window stays open so Ctrl+C stops the viewer cleanly. To pass a source file at launch from a script: `open launch.command path/to/traces.jsonl`.
+
+### What the viewer shows
+
+- **Trace log** — a live, newest-first table of traces (time, action, status, duration, and touch/error/budget counts). A search box filters by action, kind, status, or touched target. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view.
+- **Trace inspector** — selecting a trace shows its own ID, its parent and root trace IDs (when it is a child trace), kind, duration, and touch/error counts. "Copy JSON" copies the full record.
+- **Trace map** — a visual of one trace: the action as origin, its events and resources as connected nodes, with per-node status and a red marker on failures. Plays as a sequential step-through replay, with a speed slider (1×–10×, live, persisted) and pause/play.
+- **Settings** — accent colour, display density, default trace view, row count, and default replay speed — all persisted to `localStorage`.
+
+### Viewer server API
+
+These endpoints are available while a viewer is running. Apps and scripts can call them directly.
+
+| Method | Path | Request | Response |
+|---|---|---|---|
+| `GET` | `/api/health` | — | `{"status":"ok","version":"0.2.1","sources":N}` |
+| `GET` | `/api/sources` | — | `[{"name":"...","path":"..."}]` |
+| `POST` | `/api/sources` | `{"path":"..."}` | `{"name":"...","path":"..."}` |
+| `GET` | `/api/pick?type=file\|folder` | — | `{"path":"...","cancelled":bool}` |
+| `POST` | `/api/import` | `{"name":"file.jsonl","content":"..."}` | `{"name":"...","path":"...","imported":true}` |
+| `GET` | `/api/stream?source=NAME&limit=N` | — | SSE stream: `snapshot` then `append` events |
+
+The SSE stream delivers one `snapshot` message (the last N traces as a JSON array) then `append` messages for each newly-written trace. A `": keepalive"` comment is sent every 0.5 s when nothing new arrives, to keep the connection alive through proxies.
+
+### Notes
+
+- The viewer is a **local, single-node development tool**. It reads files on the machine it runs on. Exposing one machine's traces to another over the network (`traceact serve`) is planned for a later version.
+- The viewer server binds to localhost by default. Only pass `--host 0.0.0.0` if you understand that it exposes trace data (which may contain sensitive payloads) to your network.
+
+---
+
+## Integrating the viewer into your app
+
+If your app has its own web UI, you can add a "traceact viewer" button that opens the viewer in a new tab — starting it automatically if it isn't already running.
+
+### Backend route
+
+Add a route that calls `launch_or_connect()`. It checks for a running viewer (via `~/.traceact/viewer.json` + health probe), adds your trace source to it, and returns the URL. If no viewer is running it spawns one as a background subprocess and waits up to 3 seconds for it to be ready.
+
+**FastAPI** (`launch_or_connect` does blocking I/O, so run it in a thread pool):
+```python
+import asyncio
+from traceact.viewer.instance import launch_or_connect
+
+@router.get("/api/launch-viewer")
+async def launch_viewer():
+    loop = asyncio.get_event_loop()
+    url = await loop.run_in_executor(None, launch_or_connect,
+                                     "data/traces/traces.jsonl")
+    return {"url": url}
+```
+
+**Flask:**
+```python
+from traceact.viewer.instance import launch_or_connect
+from flask import jsonify
+
+@app.get("/api/launch-viewer")
+def launch_viewer():
+    url = launch_or_connect(source="data/traces/traces.jsonl")
+    return jsonify({"url": url})
+```
+
+`launch_or_connect` signature:
+
+```python
+launch_or_connect(
+    source=None,      # path to .jsonl file or folder; added to running viewer if given
+    host="127.0.0.1", # host to bind if starting a new viewer
+    port=8765,        # port to try if starting a new viewer
+    open_browser=False,
+    timeout=3.0,      # seconds to wait for a freshly started server to be ready
+) -> str              # returns the viewer URL, e.g. "http://127.0.0.1:8765/"
+```
+
+### Frontend button
+
+The button should be a `<button>` (not an `<a href>`), so you can disable it and show a loading state while the backend starts the viewer:
+
+```javascript
+document.getElementById("btn-traceact-viewer").addEventListener("click", async () => {
+    const btn = document.getElementById("btn-traceact-viewer");
+    btn.disabled = true;
+    btn.textContent = "opening…";
+    try {
+        const { url } = await fetch("/api/launch-viewer").then(r => r.json());
+        window.open(url, "_blank", "noopener");
+    } catch {
+        window.open("http://127.0.0.1:8765/", "_blank", "noopener");
+    } finally {
+        btn.disabled = false;
+        btn.textContent = "traceact viewer";
+    }
+});
+```
+
+The fallback `window.open` in the `catch` block handles the case where the backend route doesn't exist yet (e.g. during development), so the button always does something useful.
+
+### Direct API access (no backend route)
+
+If adding a backend route isn't practical, the frontend can probe the viewer directly:
+
+```javascript
+async function openViewer() {
+    try {
+        await fetch("http://127.0.0.1:8765/api/health", { mode: "no-cors" });
+    } catch { /* not running — tell the user to start it */ }
+    window.open("http://127.0.0.1:8765/", "_blank", "noopener");
+}
+```
+
+Note: cross-origin `fetch` to the viewer will always be blocked by CORS unless the viewer adds an `Access-Control-Allow-Origin` header (it doesn't, by design). Use `mode: "no-cors"` only to warm up the connection; don't try to read the response. The backend-route approach above is cleaner because it doesn't depend on the client being on the same machine as the viewer.
+
+---
+
 ## Quick reference
 
 ```python

{traceact-0.1.1 → traceact-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.1.1"
+version = "0.2.1"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -41,9 +41,19 @@ dev = [
 Homepage = "https://github.com/traceact/traceact"
 Repository = "https://github.com/traceact/traceact"
 Documentation = "https://github.com/traceact/traceact/blob/main/USAGE.md"
+Changelog = "https://github.com/traceact/traceact/blob/main/CHANGELOG.md"
 Issues = "https://github.com/traceact/traceact/issues"
 Author = "https://mohammedshehu.com"
 
+# The `traceact` command line. Both `traceact view` and `traceact show` are
+# handled inside cli:main.
+[project.scripts]
+traceact = "traceact.viewer.cli:main"
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["traceact*"]
+
+# Ship the viewer's static frontend (HTML/CSS/JS) inside the wheel.
+[tool.setuptools.package-data]
+"traceact.viewer" = ["static/*"]

{traceact-0.1.1 → traceact-0.2.1}/traceact/__init__.py

@@ -25,6 +25,8 @@
 #
 #   ConsoleSink   — prints traces to stdout.
 
+__version__ = "0.2.1"
+
 from traceact.config import configure, reset_config, TraceConfig
 from traceact.budget import TraceBudget
 from traceact.trace import ActionTrace
@@ -32,6 +34,7 @@ from traceact.decorators import traced_action
 from traceact.sinks import JsonlSink, ConsoleSink
 
 __all__ = [
+    "__version__",
     "ActionTrace",
     "TraceConfig",
     "TraceBudget",

{traceact-0.1.1 → traceact-0.2.1}/traceact/budget.py

@@ -84,6 +84,39 @@ class TraceBudget:
         self.sample_rate = sample_rate
         self.always_trace_errors = always_trace_errors
 
+    @classmethod
+    def production(cls) -> "TraceBudget":
+        """
+        A preset budget tuned for high-volume production use.
+
+        The package default records every trace (sample_rate=1.0), which is the
+        right behaviour for development and first-run: you trace a function, run
+        it once, and the trace is there. That default is deliberately NOT changed
+        globally, because a developer who wired TraceAct in and then found nothing
+        recorded would be justifiably confused.
+
+        In production, though, an app might run hundreds or thousands of traced
+        actions per second. Recording all of them can strain the sink and the
+        viewer. This preset opts into a lighter footprint:
+
+            sample_rate=0.1          record roughly 10% of successful traces
+            always_trace_errors=True never drop a failed trace, even when sampled
+
+        So you keep a representative sample of healthy traffic while still
+        capturing every failure — which is the part you most need when debugging.
+
+        Only sample_rate and always_trace_errors are set here. Every other field
+        is left as None so it inherits from the package default or a parent trace.
+
+        Usage:
+            configure(budget=TraceBudget.production())
+
+            # or override a single field on top of the preset:
+            budget = TraceBudget.production()
+            budget.sample_rate = 0.25   # record 25% instead of 10%
+        """
+        return cls(sample_rate=0.1, always_trace_errors=True)
+
 
 # ---------------------------------------------------------------------------
 # Package-level defaults