steplight 0.1.0__tar.gz

steplight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riccardo Merenda
+
+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.

steplight-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: steplight
+Version: 0.1.0
+Summary: Local-first trace inspector for LLM agents and tool-driven workflows.
+Author: Riccardo Merenda
+License-Expression: MIT
+Keywords: llm,agents,tracing,observability,tui,cli,debugging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pygments>=2.17
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.76
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# Steplight
+
+Local-first trace inspector for LLM agents and tool-driven workflows.
+
+> Load a trace. See what happened. Understand why.
+
+Steplight is a terminal-native tool for inspecting LLM runs, tool calls, retries, token usage, errors, and execution bottlenecks without sending trace data to a third-party platform.
+
+It is designed for developers building with OpenAI-style workflows, LangChain, MCP tooling, or custom JSON/YAML traces who want a fast local debugging loop and a shareable HTML report.
+
+## Why Steplight
+
+- Understand what your agent actually did, step by step
+- Spot slow tools, retry loops, and cost spikes quickly
+- Keep sensitive traces on your own machine
+- Stay in the terminal instead of digging through raw JSON by hand
+- Share a polished HTML report when you need feedback from teammates
+
+## Features
+
+- Interactive Textual inspector for timelines, details, and diagnostics
+- Rich terminal summary for quick debugging and CI-friendly output
+- Static HTML export for sharing a run with other people
+- Built-in diagnostics for common agent failure patterns
+- Support for OpenAI-style traces, LangChain callbacks, MCP logs, and generic JSON/YAML
+- Extensible adapters and rules so you can grow it with your workflow
+
+## Install
+
+```bash
+pip install steplight
+```
+
+The package installs both `steplight` and the shorter `slt` alias. The examples below use `slt` to avoid PowerShell's reserved `sl` alias.
+
+## Quick Start
+
+```bash
+slt summary sample_traces/agent_with_tools.json
+slt validate sample_traces/simple_qa.json
+slt export sample_traces/expensive_run.json -o report.html
+slt inspect sample_traces/agent_with_tools.json
+```
+
+## Example Summary Output
+
+```text
++------------------------ Steplight Summary ------------------------+
+| Run: Find compliance gaps in policy                               |
+| Source: openai                                                    |
+| Overview: Duration: 14.0s | Steps: 4 | Tool calls: 2 | Retries: 0 |
+| Tokens: 4,230 in / 670 out | Est. cost: $0.0028                   |
++-------------------------------------------------------------------+
+
+Diagnostics
+- WARNING: Step 'web_search' took 68.6% of total runtime.
+- WARNING: Tool 'web_search' took 9.6s. Check timeouts, caching, or external latency.
+- INFO: Input tokens grew 4.2x between 'Draft plan' and 'Final answer'.
+Bottleneck: web_search (68.6% of total runtime)
+```
+
+## Supported Trace Formats
+
+- OpenAI-style step traces
+- LangChain callback event exports
+- MCP tool call logs
+- Generic JSON or YAML with an optional `steplight.yaml` mapping file
+
+## Diagnostics
+
+Steplight currently flags:
+
+- bottlenecks
+- retry loops
+- context growth
+- repeated tool calls
+- silent errors
+- slow tools
+- high-cost runs
+- empty completions
+
+## Custom Mapping Example
+
+```yaml
+mapping:
+  steps_path: "$.events"
+  timestamp_field: "ts"
+  type_field: "event_type"
+  type_values:
+    prompt: "llm_start"
+    completion: "llm_end"
+    tool_call: "tool_start"
+    tool_result: "tool_end"
+```
+
+## Commands
+
+- `slt inspect <file>` opens the interactive Textual UI
+- `slt summary <file>` prints a non-interactive terminal summary
+- `slt export <file> -o report.html` creates a static HTML report
+- `slt validate <file>` checks whether a trace can be parsed successfully
+
+## Docs
+
+- [Roadmap](docs/ROADMAP.md)
+- [Versioning and Releases](docs/VERSIONING.md)
+- [Release Process](RELEASING.md)
+
+## Repository Layout
+
+```text
+steplight/
+  cli/
+  core/
+  adapters/
+  tui/
+  export/
+sample_traces/
+tests/
+```
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+pytest
+python -m steplight.cli.main --help
+```
+
+## Release Checklist
+
+- Run `pytest`
+- Build the distribution with `python -m build`
+- Update `CHANGELOG.md`
+- Review the generated wheel and sdist
+- Publish the repository to GitHub
+- Publish the package to PyPI when ready
+
+## Status
+
+Steplight is currently an alpha-stage project focused on a clean local-first inspection experience, a solid parser surface, and practical diagnostics.
+
+## License
+
+MIT

steplight-0.1.0/README.md

@@ -0,0 +1,145 @@
+# Steplight
+
+Local-first trace inspector for LLM agents and tool-driven workflows.
+
+> Load a trace. See what happened. Understand why.
+
+Steplight is a terminal-native tool for inspecting LLM runs, tool calls, retries, token usage, errors, and execution bottlenecks without sending trace data to a third-party platform.
+
+It is designed for developers building with OpenAI-style workflows, LangChain, MCP tooling, or custom JSON/YAML traces who want a fast local debugging loop and a shareable HTML report.
+
+## Why Steplight
+
+- Understand what your agent actually did, step by step
+- Spot slow tools, retry loops, and cost spikes quickly
+- Keep sensitive traces on your own machine
+- Stay in the terminal instead of digging through raw JSON by hand
+- Share a polished HTML report when you need feedback from teammates
+
+## Features
+
+- Interactive Textual inspector for timelines, details, and diagnostics
+- Rich terminal summary for quick debugging and CI-friendly output
+- Static HTML export for sharing a run with other people
+- Built-in diagnostics for common agent failure patterns
+- Support for OpenAI-style traces, LangChain callbacks, MCP logs, and generic JSON/YAML
+- Extensible adapters and rules so you can grow it with your workflow
+
+## Install
+
+```bash
+pip install steplight
+```
+
+The package installs both `steplight` and the shorter `slt` alias. The examples below use `slt` to avoid PowerShell's reserved `sl` alias.
+
+## Quick Start
+
+```bash
+slt summary sample_traces/agent_with_tools.json
+slt validate sample_traces/simple_qa.json
+slt export sample_traces/expensive_run.json -o report.html
+slt inspect sample_traces/agent_with_tools.json
+```
+
+## Example Summary Output
+
+```text
++------------------------ Steplight Summary ------------------------+
+| Run: Find compliance gaps in policy                               |
+| Source: openai                                                    |
+| Overview: Duration: 14.0s | Steps: 4 | Tool calls: 2 | Retries: 0 |
+| Tokens: 4,230 in / 670 out | Est. cost: $0.0028                   |
++-------------------------------------------------------------------+
+
+Diagnostics
+- WARNING: Step 'web_search' took 68.6% of total runtime.
+- WARNING: Tool 'web_search' took 9.6s. Check timeouts, caching, or external latency.
+- INFO: Input tokens grew 4.2x between 'Draft plan' and 'Final answer'.
+Bottleneck: web_search (68.6% of total runtime)
+```
+
+## Supported Trace Formats
+
+- OpenAI-style step traces
+- LangChain callback event exports
+- MCP tool call logs
+- Generic JSON or YAML with an optional `steplight.yaml` mapping file
+
+## Diagnostics
+
+Steplight currently flags:
+
+- bottlenecks
+- retry loops
+- context growth
+- repeated tool calls
+- silent errors
+- slow tools
+- high-cost runs
+- empty completions
+
+## Custom Mapping Example
+
+```yaml
+mapping:
+  steps_path: "$.events"
+  timestamp_field: "ts"
+  type_field: "event_type"
+  type_values:
+    prompt: "llm_start"
+    completion: "llm_end"
+    tool_call: "tool_start"
+    tool_result: "tool_end"
+```
+
+## Commands
+
+- `slt inspect <file>` opens the interactive Textual UI
+- `slt summary <file>` prints a non-interactive terminal summary
+- `slt export <file> -o report.html` creates a static HTML report
+- `slt validate <file>` checks whether a trace can be parsed successfully
+
+## Docs
+
+- [Roadmap](docs/ROADMAP.md)
+- [Versioning and Releases](docs/VERSIONING.md)
+- [Release Process](RELEASING.md)
+
+## Repository Layout
+
+```text
+steplight/
+  cli/
+  core/
+  adapters/
+  tui/
+  export/
+sample_traces/
+tests/
+```
+
+## Development
+
+```bash
+python -m pip install -e .[dev]
+pytest
+python -m steplight.cli.main --help
+```
+
+## Release Checklist
+
+- Run `pytest`
+- Build the distribution with `python -m build`
+- Update `CHANGELOG.md`
+- Review the generated wheel and sdist
+- Publish the repository to GitHub
+- Publish the package to PyPI when ready
+
+## Status
+
+Steplight is currently an alpha-stage project focused on a clean local-first inspection experience, a solid parser surface, and practical diagnostics.
+
+## License
+
+MIT

steplight-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "steplight"
+version = "0.1.0"
+description = "Local-first trace inspector for LLM agents and tool-driven workflows."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Riccardo Merenda" }
+]
+keywords = [
+  "llm",
+  "agents",
+  "tracing",
+  "observability",
+  "tui",
+  "cli",
+  "debugging",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Testing",
+  "Topic :: Terminals",
+]
+dependencies = [
+  "jinja2>=3.1",
+  "pygments>=2.17",
+  "pydantic>=2.7",
+  "pyyaml>=6.0",
+  "rich>=13.7",
+  "textual>=0.76",
+  "typer>=0.12"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.2",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+  "twine>=5.1"
+]
+
+[project.scripts]
+steplight = "steplight.cli.main:app"
+slt = "steplight.cli.main:app"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -p no:cacheprovider"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["steplight*"]
+
+[tool.setuptools.package-data]
+steplight = ["export/templates/*.jinja"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "F",
+  "I",
+  "B",
+  "UP",
+]

steplight-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steplight-0.1.0/steplight/__init__.py

@@ -0,0 +1,5 @@
+"""Steplight package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

steplight-0.1.0/steplight/adapters/__init__.py

@@ -0,0 +1 @@
+"""Trace format adapters."""

steplight-0.1.0/steplight/adapters/common.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def parse_dt(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    if value is None:
+        return datetime.now(timezone.utc)
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value, tz=timezone.utc)
+
+    normalized = str(value).replace("Z", "+00:00")
+    return datetime.fromisoformat(normalized)
+
+
+def compact_text(value: Any, *, limit: int = 240, keep_empty: bool = False) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        text = value.strip()
+    else:
+        text = str(value).strip()
+    if not text:
+        return "" if keep_empty else None
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3] + "..."

steplight-0.1.0/steplight/adapters/generic.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from steplight.adapters.common import compact_text, parse_dt
+from steplight.core.models import Step, StepType, Trace
+
+
+DEFAULT_MAPPING = {
+    "steps_path": "$.steps",
+    "timestamp_field": "timestamp",
+    "type_field": "type",
+    "name_field": "name",
+    "duration_field": "duration_ms",
+    "input_field": "input",
+    "output_field": "output",
+    "model_field": "model",
+    "tokens_in_field": "tokens_in",
+    "tokens_out_field": "tokens_out",
+    "error_field": "error",
+    "metadata_field": "metadata",
+    "type_values": {},
+}
+
+
+def load_mapping(config_path: Path | None) -> dict[str, Any]:
+    mapping = dict(DEFAULT_MAPPING)
+    if not config_path or not config_path.exists():
+        return mapping
+
+    payload = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    mapping.update(payload.get("mapping") or {})
+    return mapping
+
+
+def parse_generic_trace(payload: dict[str, Any], mapping: dict[str, Any] | None = None) -> Trace:
+    active_mapping = dict(DEFAULT_MAPPING)
+    if mapping:
+        active_mapping.update(mapping)
+
+    raw_steps = _extract_path(payload, active_mapping["steps_path"])
+    if not isinstance(raw_steps, list):
+        raise ValueError("Generic mapping did not resolve to a list of steps.")
+
+    steps: list[Step] = []
+    type_values = active_mapping.get("type_values") or {}
+
+    for index, raw_step in enumerate(raw_steps):
+        if not isinstance(raw_step, dict):
+            raise ValueError(f"Generic step at index {index} is not an object.")
+        raw_type = _get_field(raw_step, active_mapping["type_field"])
+        normalized_type = _normalize_type(raw_type, type_values)
+        metadata = _get_field(raw_step, active_mapping["metadata_field"]) or {}
+        steps.append(
+            Step(
+                id=str(raw_step.get("id") or f"{payload.get('id', 'generic')}:step:{index}"),
+                type=normalized_type,
+                name=_get_field(raw_step, active_mapping["name_field"]),
+                timestamp=parse_dt(_get_field(raw_step, active_mapping["timestamp_field"])),
+                duration_ms=_maybe_float(_get_field(raw_step, active_mapping["duration_field"])),
+                input=compact_text(_get_field(raw_step, active_mapping["input_field"])),
+                output=compact_text(_get_field(raw_step, active_mapping["output_field"]), keep_empty=True),
+                model=_get_field(raw_step, active_mapping["model_field"]),
+                tokens_in=_maybe_int(_get_field(raw_step, active_mapping["tokens_in_field"])),
+                tokens_out=_maybe_int(_get_field(raw_step, active_mapping["tokens_out_field"])),
+                error=compact_text(_get_field(raw_step, active_mapping["error_field"])),
+                metadata=metadata if isinstance(metadata, dict) else {"value": metadata},
+            )
+        )
+
+    started_at = parse_dt(payload.get("started_at") or (steps[0].timestamp if steps else None))
+    ended_at = parse_dt(payload.get("ended_at")) if payload.get("ended_at") else _infer_ended_at(steps)
+
+    return Trace(
+        id=str(payload.get("id") or "generic-trace"),
+        name=payload.get("name"),
+        started_at=started_at,
+        ended_at=ended_at,
+        steps=steps,
+        total_tokens=_maybe_int(payload.get("total_tokens")),
+        total_cost_usd=_maybe_float(payload.get("total_cost_usd") or payload.get("cost_usd")),
+        source="generic",
+        status=payload.get("status"),
+        metadata={"raw": payload, "mapping": active_mapping},
+    )
+
+
+def _extract_path(payload: dict[str, Any], json_path: str) -> Any:
+    current: Any = payload
+    path = json_path.strip()
+    if path in {"$", ""}:
+        return current
+    if path.startswith("$."):
+        path = path[2:]
+    for part in path.split("."):
+        if not part:
+            continue
+        if "[" in part and part.endswith("]"):
+            key, index_text = part[:-1].split("[", maxsplit=1)
+            if key:
+                current = current[key]
+            current = current[int(index_text)]
+        else:
+            current = current[part]
+    return current
+
+
+def _get_field(item: dict[str, Any], field_name: str | None) -> Any:
+    if not field_name:
+        return None
+    current: Any = item
+    for part in str(field_name).split("."):
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+    return current
+
+
+def _normalize_type(raw_type: Any, type_values: dict[str, str]) -> StepType:
+    value = str(raw_type or "").strip().lower()
+    for normalized, external in type_values.items():
+        if value == str(external).strip().lower():
+            return StepType(normalized)
+    if value in {member.value for member in StepType}:
+        return StepType(value)
+    if "tool" in value and "result" in value:
+        return StepType.TOOL_RESULT
+    if "tool" in value:
+        return StepType.TOOL_CALL
+    if "retry" in value:
+        return StepType.RETRY
+    if "error" in value:
+        return StepType.ERROR
+    if "start" in value:
+        return StepType.CHAIN_START
+    if "end" in value:
+        return StepType.CHAIN_END
+    return StepType.COMPLETION
+
+
+def _maybe_int(value: Any) -> int | None:
+    return int(value) if value is not None else None
+
+
+def _maybe_float(value: Any) -> float | None:
+    return float(value) if value is not None else None
+
+
+def _infer_ended_at(steps: list[Step]):
+    if not steps:
+        return None
+    latest = max(steps, key=lambda item: item.timestamp)
+    return latest.timestamp