Metadata-Version: 2.4
Name: tracegc
Version: 0.6.0
Summary: Deterministic, receipt-preserving context compaction library for LLM agents
Author: Athish M, Bavithiran V, Kamalesh T, Rohinth K V
License: Apache-2.0
Project-URL: Homepage, https://github.com/tracegc/tracegc
Project-URL: Issues, https://github.com/tracegc/tracegc/issues
Project-URL: Web App, https://tracegc.vercel.app
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Dynamic: license-file

<div align="center">
  <a href="https://tracegc.vercel.app">
    <picture>
      <source media="(prefers-color-scheme: dark)"
              srcset="docs/assets/tracegc-logo-horizontal-dark.svg">
      <source media="(prefers-color-scheme: light)"
              srcset="docs/assets/tracegc-logo-horizontal-light.svg">
      <img
        src="docs/assets/tracegc-logo-horizontal-light.png"
        alt="TraceGC"
        width="500">
    </picture>
  </a>
</div>

> **TraceGC** is a deterministic, zero-LLM-call context compaction library for AI agents that prunes superseded state, dead branches, and redundant actions while keeping history fully recoverable via audit receipts.

<p align="center">
  <a href="https://pypi.org/project/tracegc/"><img src="https://img.shields.io/pypi/v/tracegc.svg" alt="PyPI Version"></a>
  <a href="https://pypi.org/project/tracegc/"><img src="https://img.shields.io/pypi/pyversions/tracegc.svg" alt="Python Versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://github.com/tracegc/tracegc/actions/workflows/tests.yml"><img src="https://github.com/tracegc/tracegc/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
  <a href="https://tracegc.vercel.app"><img src="https://img.shields.io/badge/Live-Web%20App-blueviolet" alt="Live Web App"></a>
  <a href="https://colab.research.google.com/github/tracegc/tracegc/blob/main/demo/colab_demo.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
</p>

<p align="center">
  <a href="https://tracegc.vercel.app">Playground</a> •
  <a href="SPEC.md">Specification</a> •
  <a href="WRITEUP.md">Writeup</a> •
  <a href="tracegc/benchmark/benchmark_report.md">Benchmarks</a> •
  <a href="https://github.com/tracegc/tracegc/issues">Issues</a>
</p>

---

## Why This Exists

As autonomous AI agents execute tasks over multiple turns, their interaction logs expand linearly. Every turn accumulates superseded variable assignments, failed tool attempts, duplicated searches, and abandoned execution branches.

Existing solutions force developers into a flawed tradeoff:
- **Naive Window Truncation**: Drops the oldest history once token limits are reached, destroying initial instructions, system constraints, and early architectural decisions (causing 0% decision accuracy on medium/long traces).
- **LLM-Driven Summarization**: Adds 5–50 seconds of latency per turn, burns API tokens, outputs non-deterministic summaries, and consistently erases critical decision rationale ("context rot").

**TraceGC operates at the structural layer**: It compiles execution traces into a directed multigraph and mathematically prunes provably-dead elements in **< 2ms locally** with zero model calls. When an event is pruned, TraceGC leaves an inline audit receipt stub (`[RECEIPT node_id]`), guaranteeing that any pruned payload remains 100% restorable on-demand.

---

## Installation

```bash
pip install tracegc
```

To install with storage persistence backends:
```bash
pip install tracegc tracegc-storage
```

---

## Quick Start (~10 Lines)

The `TraceGC` client records events incrementally and compacts on demand:

```python
from tracegc import TraceGC

client = TraceGC()

# 1. Record structured events as they occur
client.add_event({
    "id": "e001",
    "type": "decision",
    "timestamp": 1000,
    "parent_id": None,
    "content": "Start configuration"
})
client.add_event({
    "id": "e002",
    "type": "set_var",
    "timestamp": 1010,
    "parent_id": "e001",
    "key": "x",
    "value": 10
})
client.add_event({
    "id": "e003",
    "type": "set_var",
    "timestamp": 1020,
    "parent_id": "e002",
    "key": "x",
    "value": 20  # Supersedes x=10
})

# 2. Compact context history deterministically
result = client.compact()
print(result["prompt"])
# Output:
# Start configuration
# [RECEIPT e002]
# x = 20

# 3. Recover full original payload for any pruned event
receipt = client.get_receipt("e002")
assert receipt["value"] == 10 and receipt["pruned"] is True
```

---

## Ecosystem & Integration Packages

TraceGC provides official, first-class adapter packages across the agent ecosystem:

| Package | Purpose | Primary Entry Point |
| :--- | :--- | :--- |
| **[`tracegc-langgraph`](tracegc-langgraph/)** | LangGraph StateGraph & CompiledStateGraph | `wrap_graph(graph)` |
| **[`tracegc-crewai`](tracegc-crewai/)** | CrewAI Agents, Crews, and Tasks | `create_step_callback()` |
| **[`tracegc-mcp`](tracegc-mcp/)** | Model Context Protocol server (Claude Code, Cursor) | `tracegc-mcp --db-path ./sessions.db` |
| **[`tracegc-storage`](tracegc-storage/)** | Pluggable persistence (Memory & SQLite) | `SQLiteStore("sessions.db")` |

---

## Benchmarks

TraceGC is continuously evaluated against synthetic and natural agent execution logs. The table below summarizes compaction and probe accuracy across short, medium, and long traces:

| Trace Size | Compaction Method | Average Tokens | Recall Accuracy | Artifact Accuracy | Continuation Accuracy | Decision Accuracy | Deterministic |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Short** | full_history | 121.0 | 100% | 100% | 100% | 100% | n/a |
| | truncate_by_event_count | 116.3 | 100% | 100% | 100% | 100% | n/a |
| | ai_summarize_single | 90.7 | 100% | 33.3% | 55.6% | 0.0% | No |
| | **tracegc_pipeline** | **75.3** | **100%** | **100%** | **100%** | **100%** | **Yes** |
| **Medium** | full_history | 379.7 | 100% | 100% | 100% | 100% | n/a |
| | truncate_by_event_count | 133.3 | 0.0% | 100% | 0.0% | 0.0% | n/a |
| | ai_summarize_single | 146.7 | 66.7% | 88.9% | 100% | 0.0% | No |
| | ai_summarize_recursive | 131.0 | 0.0% | 66.7% | 100% | 0.0% | No |
| | **tracegc_pipeline** | **299.0** | **100%** | **100%** | **100%** | **100%** | **Yes** |
| **Long** | full_history | 1301.0 | 100% | 100% | 100% | 100% | n/a |
| | truncate_by_event_count | 104.3 | 0.0% | 0.0% | 0.0% | 0.0% | n/a |
| | ai_summarize_single | 243.4 | 100% | 0.0% | 100% | 0.0% | No |
| | ai_summarize_recursive | 219.2 | 100% | 0.0% | 100% | 0.0% | No |
| | **tracegc_pipeline** | **1028.3** | **100%** | **100%** | **100%** | **100%** | **Yes** |

> **Key Finding**: TraceGC is the only method that achieves **100% accuracy across all four evaluation probes** at every trace length while executing deterministically in < 2ms without API costs.
> Full details and reproducibility steps are in the [Benchmark Report](tracegc/benchmark/benchmark_report.md).

---

## How It Compares

- **Provider-Native Compaction (Anthropic `compact`, OpenAI Codex-Max)**: Provider compaction is model-driven summarization integrated into the provider's API. TraceGC is structure-driven and runs *upstream* as a deterministic pre-filter. Pruning dead branches and overwritten state before calling provider compaction reduces input tokens and prevents the model from summarizing away crucial decision rationale.
- **Content Compression (Headroom)**: Headroom compresses incoming message content (using heuristics and trained ML) while keeping conversation history intact to optimize KV-cache hits. TraceGC operates on accumulated history, pruning dead state and obsolete tool executions. The two are complementary.
- **OS-Inspired Memory (MemGPT / Letta)**: MemGPT manages context through virtual paging and LLM-driven self-editing functions. TraceGC is an offline, sub-millisecond graph compilation pipeline that runs without background LLM loops.
- **Knowledge Graphs (Cognee)**: Cognee structures facts into entity-relation graphs for semantic search. TraceGC focuses on execution trace compaction for prompt optimization.

---

## How It Works: The 5-Stage Pipeline

TraceGC processes execution traces through five deterministic compilation stages:

```
Agent Trace ──► State Graph ──► Deterministic Pruning ──► Receipt Generation ──► Compact Context
```

1. **Dead-Branch Sweeper**: Traces and removes failed executions and abandoned branches originating from `abandon` events.
2. **Override Engine**: Identifies state updates (`set_var`) and retains only the latest active value per key.
3. **Deduplication Engine**: Deduplicates consecutive identical tool calls (`tool_call`/`tool_result`).
4. **Topological Sampler**: Detects structural dependency cycles and collapses them into deterministic receipt clusters.
5. **Semantic Pruning**: Resolves semantic equivalents, obsolete file reads, error traces, and redundant verifications.

---

## Development Setup

To develop across the monorepo locally, install all packages in editable mode:

```bash
git clone https://github.com/tracegc/tracegc.git
cd tracegc

# Install core and all integration packages
pip install -e .
pip install -e ./tracegc-storage
pip install -e ./tracegc-crewai
pip install -e ./tracegc-langgraph
pip install -e ./tracegc-mcp

# Run the test suite (170+ tests)
pytest
```

---

## License

TraceGC is licensed under the [Apache License 2.0](LICENSE).

