Metadata-Version: 2.4
Name: freesolo
Version: 0.1.2
Summary: Decorator-based LLM tracing package with OpenAI and Anthropic client instrumentation.
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: ruff>=0.11.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: anthropic>=0.40.0; extra == 'examples'
Requires-Dist: openai>=1.0.0; extra == 'examples'
Description-Content-Type: text/markdown

# freesolo

`freesolo` is a Python tracing package for LLM apps.

It is built for the lowest-friction integration possible:

1. Install the package
2. Set `FREESOLO_API_KEY`
3. Start a trace once
4. Add `@trace()` to your functions
5. Optionally wrap your OpenAI or Anthropic client for automatic provider spans

## Current provider support

`freesolo` currently supports automatic client instrumentation for:

- OpenAI
- Anthropic

## Install

Install the package plus the provider SDK you use:

```bash
pip install freesolo openai
```

or

```bash
pip install freesolo anthropic
```

## Environment

- `FREESOLO_API_KEY`

## Quickstart

```python
from openai import OpenAI
from freesolo import instrument_openai, start_trace, trace

client = instrument_openai(OpenAI())

@trace()
def run_agent(question: str) -> str:
    result = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=[
            {"role": "user", "content": question},
        ],
    )
    return result.choices[0].message.content or ""


with start_trace("support-agent-run"):
    print(run_agent("How do I reset my password?"))
```

## What Gets Stored

- Trace metadata if you explicitly pass it to `start_trace(..., metadata=...)`
- Decorator spans from `@trace()`
- OpenAI and Anthropic request + response payloads
- Token usage when available
- Image inputs summarized safely instead of storing full base64 blobs

## Notes

- If you only add `@trace()`, you still get useful spans.
- Use `start_trace(trace_id=...)` when you want multiple decorated functions to land in one trace.
- If you also wrap the LLM client, you get automatic provider/model spans.
- Delivery is best-effort by default. Trace ingestion failures do not break your app.
