Metadata-Version: 2.4
Name: intencion
Version: 0.1.0
Summary: Durable, dependency-free Python SDK for capturing AI-agent runs and shipping them to Intencion.
Project-URL: Homepage, https://intencion.io
Project-URL: Repository, https://github.com/las7/intent-analysis
Author: Intencion
License: MIT
License-File: LICENSE
Keywords: agents,ai,ai-agents,analytics,intencion,llm,observability,telemetry,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.8
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
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# intencion

Durable, dependency-free Python SDK for capturing AI-agent runs and shipping them to [Intencion](https://intencion.io). Pure stdlib, Python 3.8+, non-blocking background transport.

## Install

```bash
pip install intencion
```

## Quickstart

```python
import intencion

intencion.init(api_key="in_pk_...")           # call once at startup

with intencion.run(intent="support", input=user_msg, user="u_123",
                   session="s_1", model="gpt-4o") as run:
    run.step(name="lookup_order", tool="db", status="success", ms=42)
    result = my_agent(user_msg)               # your agent work
    # outcome defaults to "success"; override with run.fail("...")/run.abandon()

# decorator form
@intencion.trace(intent="classify")
def classify(msg): ...

intencion.flush()                             # force send queued runs
```

If the wrapped code raises, the run is recorded as `failure` and the exception is re-raised unchanged.

## Short-lived processes

The worker flushes on an interval, on `atexit`, and on `SIGTERM`/`SIGINT`. For a script, a serverless function, or any process that exits quickly, call `flush()` before the process ends to ensure queued runs are sent:

```python
intencion.flush()      # block until queued runs are sent (or timeout)
intencion.shutdown()   # flush + stop the worker thread
```

## Configuration

| Option           | Default                           | Meaning                                           |
| ---------------- | --------------------------------- | ------------------------------------------------- |
| `api_key`        | — (required)                      | Sent as `Authorization: Bearer <api_key>`.        |
| `endpoint`       | `https://intencion.io/api/ingest` | Ingest URL.                                       |
| `flush_interval` | `5.0`                             | Seconds between timed flushes.                    |
| `max_batch`      | `100`                             | Max runs per request (hard-capped at 500).        |
| `max_queue`      | `1000`                            | Bounded queue size; drop-oldest when full.        |
| `sample_rate`    | `1.0`                             | Fraction of runs captured (0.0 to 1.0).           |
| `disabled`       | `False`                           | Disable all capture.                              |
| `debug`          | `False`                           | Enable debug logging on the `intencion` logger.   |

## API

```python
intencion.init(api_key, endpoint=None, flush_interval=5.0, max_batch=100,
               max_queue=1000, sample_rate=1.0, disabled=False, debug=False)

intencion.run(intent, input=None, user=None, session=None, model=None)
# use as a context manager (with statement)

intencion.trace(intent, user=None, session=None, model=None, capture_input=False)
# use as a function decorator

intencion.flush(timeout=None)
intencion.shutdown(timeout=2.0)
```

A `run` object exposes: `step(name, status="success", tool=None, ms=None, error=None)`, `ok()`, `fail(reason=None)`, `abandon(reason=None)`, `set_tokens(tokens_in, tokens_out)`, `set_model(model)`.

## License

MIT. See [LICENSE](./LICENSE).

https://intencion.io
