Metadata-Version: 2.4
Name: retrack-ai
Version: 0.1.1
Summary: Retrack builds experience for AI agents: capture, verify, learn and recall for LangGraph agents.
Keywords: ai-agents,langgraph,agent-memory,llm,evaluation
Author: Gokulakrishnan Jawahar
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: httpx>=0.28.1
Requires-Dist: langchain-core>=1.6.12
Requires-Python: >=3.10
Project-URL: Homepage, https://retrack-ai.online
Description-Content-Type: text/markdown

# retrack-ai

**Retrack builds experience for AI agents.**

![Install retrack-ai, run your agent with the Retrack callback, and its runs become playbooks, warnings and recalls in the Retrack dashboard (sample data)](https://retrack-ai.online/readme/quickstart.svg)

Your agent runs the same kinds of tasks every day, and starts each one from scratch. Retrack watches every run, checks whether it worked, turns what worked into **playbooks** and what failed into **warnings**, and hands the right ones to your agent before its next similar task.

This package is the connector for [Retrack](https://retrack-ai.online), a hosted service. It works with LangGraph and LangChain agents in Python.

## Quickstart (5 minutes)

**1. Get an API key.** Sign up at [retrack-ai.online](https://retrack-ai.online), create a project and copy its key.

**2. Install and set the key.**

```bash
pip install retrack-ai
export RETRACK_API_KEY="rtk_live_..."
```

**3. Capture every run.** Add one callback to your graph:

```python
from retrack import Retrack

rt = Retrack("support-agent")  # one name per agent

result = graph.invoke(inputs, config={"callbacks": [rt.callback()]})
```

Retrack records the task, each tool call and its result, the final answer, tokens and the model. Obvious secrets (API keys, tokens, passwords) are stripped on your machine before anything is sent, and the server redacts again.

**4. Recall before each task.**

```python
memory = rt.recall(task)  # never raises; returns empty memory on any problem

result = graph.invoke(
    {"messages": [("system", memory.as_prompt()), ("user", task)]},
    config={"callbacks": [rt.callback()]},
)
```

Or as a LangGraph node: `graph.add_node("memory", rt.recall_node(task_key="task"))`.

**5. Tell Retrack what worked.** Playbooks are only trusted when there's real evidence. Send a result whenever you know it, such as a passing test, a resolved ticket or a user's thumbs-up:

```python
import uuid

run_id = uuid.uuid4()
graph.invoke(inputs, config={"callbacks": [rt.callback()], "run_id": run_id})

rt.feedback(run_id, outcome="success", source="test")  # or source="event" / "feedback"
```

Without a signal, Retrack's AI judge scores the run. Judged runs support playbooks, but only real signals (or your approval in the dashboard) make a playbook active.

## What you get

- **Playbooks:** steps that worked for a kind of task, recalled only when they clearly match (a confidence gate decides).
- **Warnings:** failures your agent has hit before, with the fix that worked, if one exists.
- **Protection:** `tools = memory.protect(tools)` adds known-fix hints to failing tools and stops your agent from repeating a failure it can't recover from.
- **Memory firewall:** runs fed by untrusted input never become memory without a check or your review.
- **Proof:** a small holdout group gets no memory, so the dashboard shows the measured difference memory makes.
- **Regression tests:** `retrack test --entry my_agent:run_task --agent support-agent` replays your playbooks and known failures as tests (good in CI).
- **Model migration:** `retrack migrate --entry my_agent:run_task --agent support-agent --to <new-model>` replays memory on a new model before you switch.

## Never in your agent's way

Capture runs in the background with bounded memory and never raises into your code. Recall gives up after 1.5 seconds (`rt.recall(task, timeout=...)`) and returns empty memory, so your agent always runs.

## Configuration

| Setting | Default |
|---|---|
| `RETRACK_API_KEY` | required (without it, capture and recall are off) |
| `RETRACK_BASE_URL` | `https://api.retrack-ai.online` |

`Retrack("agent", model_id="...", tool_versions={"stripe": "2026-09"}, trusted_tools=["orders_api"])` records the model and tool versions (memory is matched to them) and marks tools whose output you trust.

## Status

Early access (alpha). Requires Python 3.10+. Feedback is very welcome.

## License

This connector is MIT licensed. The Retrack service it connects to is a hosted product, not open source.
