intencion 0.1.0

Durable, dependency-free Python SDK for capturing AI-agent runs and shipping them to Intencion.

intencion

Durable, dependency-free Python SDK for capturing AI-agent runs and shipping them to Intencion. Pure stdlib, Python 3.8+, non-blocking background transport.

Install

pip install intencion

Quickstart

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:

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

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.

https://intencion.io