Metadata-Version: 2.3
Name: etaoi
Version: 0.1.5
Summary: ETAOI Flow SDK — agent-native tracing for LangChain / LangGraph / deepagents and LiveKit voice agents
Keywords: langchain,langgraph,deepagents,tracing,observability,agents
Author: ETAOI contributors
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: etaoi-schema>=0.3,<1
Requires-Dist: langchain-core>=1.0,<2
Requires-Dist: anyio>=4
Requires-Dist: msgpack>=1.1.2
Requires-Dist: tenacity>=9
Requires-Dist: websockets>=13,<17
Requires-Dist: livekit-agents>=1.2,<2 ; extra == 'livekit'
Requires-Dist: opentelemetry-sdk>=1.20 ; extra == 'otel'
Requires-Dist: deepagents>=0.6.1,<0.7 ; extra == 'test'
Requires-Dist: langgraph>=1.1.0,<2 ; extra == 'test'
Requires-Dist: pytest>=8 ; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24 ; extra == 'test'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/etaoi/etaoi
Project-URL: Repository, https://github.com/etaoi/etaoi
Provides-Extra: livekit
Provides-Extra: otel
Provides-Extra: test
Description-Content-Type: text/markdown

# etaoi

The Python SDK for **ETAOI Flow** — an agent-native trace visualizer for the
LangChain ecosystem and LiveKit voice agents. Attach it to your agent, run a
conversation, and watch the full reasoning unfold as a navigable, drill-down
node graph.

```bash
pip install etaoi             # core SDK
pip install "etaoi[livekit]"  # + LiveKit voice agent tap
```

## Quick start — LangChain / LangGraph / deepagents

```python
import etaoi

etaoi.attach(my_agent)  # streams telemetry to a local ETAOI Flow server
# … now `my_agent.invoke(...)` shows up as a trace.
```

One callback adapter covers LangChain, LangGraph, and deepagents.

## Quick start — LiveKit voice agents

```python
from livekit.agents import AgentSession
import etaoi

session = AgentSession(...)
etaoi.attach_session(session)
```

Captures voice turns (mic → STT → LLM → TTS → speaker), tool calls, sub-agent
handoffs, scores/outcomes, errors, and — if the host enabled LiveKit recording
— synced audio for replay alongside the trace.

## ETAOI Flow Cloud (project API keys)

To stream to the hosted ingest instead of a local self-host server, pass a
`host` plus your project's API keys:

```python
import etaoi

etaoi.attach(
    my_agent,
    host="ingest.etaoi.dev",         # bare host → wss://, default path /ingest
    public_key="pk_live_…",
    secret_key="sk_live_…",
)
```

Or via environment (explicit params take precedence):

```bash
export ETAOI_HOST=ingest.etaoi.dev
export ETAOI_PUBLIC_KEY=pk_live_…
export ETAOI_SECRET_KEY=sk_live_…
```

```python
etaoi.attach(my_agent)  # picks up ETAOI_HOST / ETAOI_PUBLIC_KEY / ETAOI_SECRET_KEY
```

The keys are sent as `X-Etaoi-Public-Key` / `X-Etaoi-Secret-Key` headers on
every (re)connect — and only when **both** are set, so self-host stays
key-less. If the server rejects them (WS close code `4401`), the SDK logs a
clear error and stops reconnecting. It never raises into or blocks your agent.

## Design constraints

- **Never blocks your agent.** Async background flush via `anyio`, bounded
  in-memory queue with drop-oldest on overflow, transparent reconnect with
  backoff. All callbacks return immediately.
- **Schema-versioned wire format.** MessagePack with `permessage-deflate` over
  WebSocket; schema version is negotiated at the handshake (MAJOR mismatch =
  fast fail, close code `4400`).
- **No vendor lock-in.** Self-host the server with `docker compose up`, or
  stream to ETAOI Flow Cloud. Same SDK.

For the wire schema this package depends on, see
[`etaoi-schema`](https://pypi.org/project/etaoi-schema/).

## Links

- Source: <https://github.com/etaoi/etaoi>
- Changelog: see the project's `CHANGELOG.md` (per-version what's-new / what's-fixed)
- License: MIT
