Agent Traces

agent-traces

Parse multi-format agent session traces into Polars DataFrames and Parquet.

Reads JSONL files from **Pi**, **Claude Code**, **Codex**, and **ATIF** formats → normalized three-table layout (sessions, events, content) → Parquet. Designed for analytical workflows: behavioral analysis, cost tracking, error patterns, training data curation.

Install

pip install agent-traces @ git+https://github.com/davanstrien/agent-traces.git

Or with uv:

uv pip install "agent-traces @ git+https://github.com/davanstrien/agent-traces.git"

Quick Start

from agent_traces import TraceDataset

# Load from HuggingFace Hub
ds = TraceDataset.from_hub("badlogicgames/pi-mono")

# Three normalized tables
ds.sessions    # 1 row/session: model, counts, tokens, cost
ds.events      # 1 row/entry: type, role, tool_name, is_error
ds.content     # 1 row/entry with text

# Convenience views for common analyses
ds.user_messages       # turn, nTurns, model, msg + session metadata
ds.assistant_messages  # content_text, thinking, tool_calls
ds.tool_calls          # tool_name + session metadata

# Aggregates
ds.tool_counts(group_by="model")
ds.token_stats(group_by="model")
ds.error_rate(group_by="model")
ds.summary()

# Export
ds.to_parquet("output/")          # sessions.parquet + events.parquet + content.parquet
ds.to_flat_parquet("flat.parquet") # single 44-column table (backward compat)

Batch Loading

# Multiple datasets at once
ds = TraceDataset.from_hub_batch([
    "badlogicgames/pi-mono",
    "0xSero/pi-sessions",
    "moikapy/0xKobolds",
])

# Search Hub by tag
for repo_id, ds in TraceDataset.from_hub_search(limit=10):
    print(ds.summary())

# Merge datasets
combined = ds1 + ds2

Local Files

ds = TraceDataset.from_dir("path/to/sessions/")

Or use the parser directly for the raw 44-column flat table:

from agent_traces import parse_sessions

df = parse_sessions("path/to/*.jsonl")

CLI

`