steplot 0.1.0__tar.gz

steplot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint with ruff
+        run: ruff check steplot tests examples
+      - name: Format check with ruff
+        run: ruff format --check steplot tests examples
+      - name: Type check with mypy
+        run: mypy steplot tests
+      - name: Test with pytest
+        run: pytest

steplot-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  id-token: write # Required for trusted publishing (OIDC) to PyPI.
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

steplot-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# steplot runtime artifacts
+steplot/runs/
+.steplot/
+*.log

steplot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammadamin Albooyeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

steplot-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: steplot
+Version: 0.1.0
+Summary: Lightweight observability for AI agents
+Project-URL: Homepage, https://github.com/MohammadaminAlbooyeh/steplot
+Project-URL: Repository, https://github.com/MohammadaminAlbooyeh/steplot
+Project-URL: Issues, https://github.com/MohammadaminAlbooyeh/steplot/issues
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# steplot
+
+Lightweight agent step tracker with decorator and logging support.
+
+`steplot` helps you visualize and persist the execution flow of your AI agents,
+scripts, or any multi-step pipeline. Wrap functions with `@track`, emit log
+events with `log_event`, and render a tree of steps to the terminal or to a
+JSON file.
+
+## Features
+
+- `@track` decorator -- wraps any function in a timed `Step`.
+- `run_context` / `step_context` -- context managers for nesting.
+- `log_event` -- emit structured events into the current step.
+- `display_run` -- pretty-print a run tree to the terminal.
+- `save_run` / `load_run` -- persist runs as JSON.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from steplot import track, run_context, display_run
+
+@track
+def research(topic: str) -> str:
+    return f"papers about {topic}"
+
+@track
+def summarize(papers: str) -> str:
+    return papers.upper()
+
+with run_context("my-agent") as run:
+    papers = research("transformers")
+    summary = summarize(papers)
+
+display_run(run)
+```
+
+Output:
+
+```
+╔══ Run: my-agent  [0.02s] ═══
+║
+║  ├─ research  [0.01s]
+║  └─ summarize  [0.00s]
+╚════════════════════════════╝
+```
+
+## Nested steps
+
+```python
+from steplot import run_context, step_context
+
+with run_context("pipeline") as run:
+    with step_context("fetch"):
+        ...
+    with step_context("process"):
+        with step_context("validate"):
+            with step_context("score"):
+                ...
+```
+
+## Persisting runs
+
+```python
+from steplot import save_run, load_run
+
+save_run(run, "steplot/runs/run-1.json")
+loaded = load_run("steplot/runs/run-1.json")
+```
+
+## API reference
+
+### `track`
+
+```python
+@track
+def my_step(): ...
+
+@track(step_name="custom", capture_args=True)
+def another_step(x, y): ...
+```
+
+### `run_context`, `step_context`
+
+Context managers that create and automatically finish a `Run` or `Step`.
+
+### `log_event`
+
+```python
+import logging
+from steplot import log_event
+
+log_event(logging.INFO, "processing item", item_id=42)
+```
+
+### `display_run`
+
+Prints a tree of steps and events to stdout.
+
+## License
+
+MIT

steplot-0.1.0/README.md

@@ -0,0 +1,108 @@
+# steplot
+
+Lightweight agent step tracker with decorator and logging support.
+
+`steplot` helps you visualize and persist the execution flow of your AI agents,
+scripts, or any multi-step pipeline. Wrap functions with `@track`, emit log
+events with `log_event`, and render a tree of steps to the terminal or to a
+JSON file.
+
+## Features
+
+- `@track` decorator -- wraps any function in a timed `Step`.
+- `run_context` / `step_context` -- context managers for nesting.
+- `log_event` -- emit structured events into the current step.
+- `display_run` -- pretty-print a run tree to the terminal.
+- `save_run` / `load_run` -- persist runs as JSON.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+from steplot import track, run_context, display_run
+
+@track
+def research(topic: str) -> str:
+    return f"papers about {topic}"
+
+@track
+def summarize(papers: str) -> str:
+    return papers.upper()
+
+with run_context("my-agent") as run:
+    papers = research("transformers")
+    summary = summarize(papers)
+
+display_run(run)
+```
+
+Output:
+
+```
+╔══ Run: my-agent  [0.02s] ═══
+║
+║  ├─ research  [0.01s]
+║  └─ summarize  [0.00s]
+╚════════════════════════════╝
+```
+
+## Nested steps
+
+```python
+from steplot import run_context, step_context
+
+with run_context("pipeline") as run:
+    with step_context("fetch"):
+        ...
+    with step_context("process"):
+        with step_context("validate"):
+            with step_context("score"):
+                ...
+```
+
+## Persisting runs
+
+```python
+from steplot import save_run, load_run
+
+save_run(run, "steplot/runs/run-1.json")
+loaded = load_run("steplot/runs/run-1.json")
+```
+
+## API reference
+
+### `track`
+
+```python
+@track
+def my_step(): ...
+
+@track(step_name="custom", capture_args=True)
+def another_step(x, y): ...
+```
+
+### `run_context`, `step_context`
+
+Context managers that create and automatically finish a `Run` or `Step`.
+
+### `log_event`
+
+```python
+import logging
+from steplot import log_event
+
+log_event(logging.INFO, "processing item", item_id=42)
+```
+
+### `display_run`
+
+Prints a tree of steps and events to stdout.
+
+## License
+
+MIT

steplot-0.1.0/examples/simple_agent.py

@@ -0,0 +1,37 @@
+"""Simple example demonstrating steplot with a fake agent."""
+
+import asyncio
+import logging
+
+from steplot import display_run, log_event, run_context, save_run, step_context, track
+
+
+@track
+async def fetch_data(query: str) -> dict:
+    await asyncio.sleep(0.1)
+    return {"result": f"data for {query}"}
+
+
+@track
+async def process_data(data: dict) -> str:
+    await asyncio.sleep(0.1)
+    if not data:
+        raise ValueError("empty data")
+    return f"processed: {data['result']}"
+
+
+async def main():
+    with run_context("simple-agent", agent="demo") as run:
+        with step_context("fetch"):
+            log_event(logging.INFO, "fetching data", query="test query")
+            data = await fetch_data("test query")
+        with step_context("process"):
+            log_event(logging.INFO, "processing data")
+            result = await process_data(data)
+            print(f"agent result: {result}")
+
+    display_run(run)
+    save_run(run, "steplot/runs/example-run.json")
+
+
+asyncio.run(main())

steplot-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "steplot"
+version = "0.1.0"
+description = "Lightweight observability for AI agents"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/MohammadaminAlbooyeh/steplot"
+Repository = "https://github.com/MohammadaminAlbooyeh/steplot"
+Issues = "https://github.com/MohammadaminAlbooyeh/steplot/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5", "mypy>=1.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["steplot"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"steplot/py.typed" = "steplot/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v"
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+src = ["steplot", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.12"
+check_untyped_defs = true
+disallow_untyped_defs = false
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+no_implicit_optional = true
+packages = ["steplot"]

steplot-0.1.0/steplot/__init__.py

@@ -0,0 +1,20 @@
+"""steplot — lightweight agent step tracker with decorator and logging support."""
+
+from .display import display_run
+from .storage import load_run, save_run
+from .tracker import get_current_run, get_current_step, log_event, reset, run_context, step_context, track
+
+__all__ = [
+    "track",
+    "run_context",
+    "step_context",
+    "log_event",
+    "get_current_run",
+    "get_current_step",
+    "reset",
+    "display_run",
+    "save_run",
+    "load_run",
+]
+
+__version__ = "0.1.0"

steplot-0.1.0/steplot/display.py

@@ -0,0 +1,71 @@
+"""Terminal display for steplot runs — renders the run tree to stdout."""
+
+from __future__ import annotations
+
+from .models import Event, Run, Step, StepStatus
+
+
+def _status_annotation(step: Step) -> str:
+    """Return a short status suffix for a step when it isn't a clean success."""
+    if step.status == StepStatus.FAILED:
+        return "  ✗"
+    if step.status == StepStatus.RUNNING:
+        return "  ..."
+    return ""
+
+
+def _format_duration(seconds: float | None) -> str:
+    return f"[{seconds:.2f}s]" if seconds is not None else ""
+
+
+def _render_step(step: Step, prefix: str, is_last: bool, lines: list[str]) -> None:
+    """Recursively append a step and its events/children to ``lines``."""
+    branch = "└─ " if is_last else "├─ "
+    line = f"{prefix}{branch}{step.name}  {_format_duration(step.duration)}{_status_annotation(step)}"
+    lines.append(line)
+
+    # Continuation prefix for events and children beneath this branch.
+    child_prefix = prefix + ("   " if is_last else "│  ")
+
+    for event in step.events:
+        _render_event(event, child_prefix, lines)
+
+    for i, child in enumerate(step.children):
+        _render_step(child, child_prefix, i == len(step.children) - 1, lines)
+
+    if step.error:
+        lines.append(f"{child_prefix}  error: {step.error}")
+
+
+def _render_event(event: Event, prefix: str, lines: list[str]) -> None:
+    lines.append(f"{prefix}  • {event.message}")
+
+
+def display_run(run: Run) -> None:
+    """Pretty-print a Run tree to stdout.
+
+    Renders the run name, total duration, and each step (including nested
+    children and structured events) as a boxed tree.
+    """
+    title = f"Run: {run.name}"
+    duration = _format_duration(run.duration)
+    if duration:
+        title += f"  {duration}"
+
+    lines: list[str] = []
+
+    for i, step in enumerate(run.steps):
+        _render_step(step, "  ", i == len(run.steps) - 1, lines)
+
+    for event in run.events:
+        lines.append(f"  • {event.message}")
+
+    top = f"╔══ {title} ═══"
+    width = max([len(line) for line in lines] + [len(top) - 2])
+    bottom = "╚" + "═" * width + "╝"
+
+    print(top)
+    print("║")
+    for line in lines:
+        print(f"║{line}")
+    print(bottom)