Metadata-Version: 2.4
Name: farol-sdk
Version: 0.1.4
Summary: Agent observability for builders
Project-URL: Homepage, https://usefarol.dev
Author: Farol
License: MIT
Keywords: agents,llm,observability,supabase,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: resend>=2.0.0; extra == 'all'
Requires-Dist: supabase>=2.0.0; extra == 'all'
Provides-Extra: resend
Requires-Dist: resend>=2.0.0; extra == 'resend'
Provides-Extra: supabase
Requires-Dist: supabase>=2.0.0; extra == 'supabase'
Description-Content-Type: text/markdown

# farol-sdk

Agent observability for builders. Wrap a function with `@trace`, pass token counts on the `run` dict, and Farol syncs runs to your dashboard—cost anomalies, alerts, the lot.

**[usefarol.dev](https://usefarol.dev)**

---

## Install

```bash
pip install farol-sdk
```

Sync to Supabase and email alerts need extras (zero required deps otherwise):

```bash
pip install 'farol-sdk[supabase,resend]'
```

Set environment variables: `SUPABASE_URL`, `SUPABASE_KEY`, optionally `SUPABASE_SERVICE_KEY` for writes + API key resolution; `RESEND_API_KEY` and `ALERT_EMAIL` for anomaly emails.

---

## Usage

```python
from farol import trace

@trace("research-agent", farol_key="frl_your_key_here", model="claude-3-5-haiku-latest")
def my_agent(task: str, *, run):
    run["input_tokens"] = 100
    run["output_tokens"] = 50
    return "done"
```

The wrapped function receives `run` with `steps`, token fields, and timing; Farol computes cost from `cost_per_1k_tokens` (default suits many providers—override as needed).

---

## License

MIT
