Metadata-Version: 2.4
Name: langfuse-tracing-adapter
Version: 0.1.1
Summary: Env-only Langfuse tracing adapter for LangChain/LangGraph; callback handler as primary integration.
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: langfuse>=2.0
Requires-Dist: langchain-core>=0.1
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# langfuse-tracing-adapter

Env-only Langfuse tracing adapter for LangChain/LangGraph. Callback handler is the primary integration; no `@observe` decorator required.

## Install

```bash
pip install langfuse-tracing-adapter langfuse
```

## Env

Set before running your app:

- `LANGFUSE_BASE_URL` — Langfuse server URL (e.g. `http://localhost:3011`)
- `LANGFUSE_PUBLIC_KEY` — Project public key (from Langfuse UI)
- `LANGFUSE_SECRET_KEY` — Project secret key
- `LANGFUSE_PROJECT` — Project name (optional, default `"default"`)

## Usage

1. **Startup:** `init_client()` once (e.g. FastAPI lifespan).
2. **LLM runs:** Pass `get_callback_handler()` in config: `config["callbacks"] = [get_callback_handler()]`.
3. **Optional:** `run_metadata_for_org(org_id, extra_tags=..., custom_metadata=...)` in config for org isolation and custom metadata.
4. **After run:** `get_context().update_current_trace(input=..., output=..., metadata=...)` then `flush()`.
5. **Shutdown:** `flush()` then `shutdown()`.

## Using the adapter in another project

1. **Install:** `pip install langfuse-tracing-adapter langfuse`
2. **Env:** Set `LANGFUSE_BASE_URL`, `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_PROJECT` (optional).
3. **Startup:** Call `init_client()` once (e.g. FastAPI lifespan, Django `AppConfig.ready`, or main).
4. **LLM entry points:** Pass `get_callback_handler()` into LangChain/LangGraph config (e.g. `config["callbacks"] = [get_callback_handler()]` when not None). One trace per run; no observe decorator required.
5. **Optional:** Use `run_metadata_for_org(org_id, extra_tags=..., custom_metadata=...)` in config for org isolation and custom metadata. After the run, call `get_context().update_current_trace(input=..., output=..., metadata=...)`.
6. **After request / shutdown:** Call `flush()` so traces are sent; on shutdown call `shutdown()`.

## Publishing to PyPI

The package is **universal** (env-only; use in any project). To publish so others can `pip install langfuse-tracing-adapter`:

1. **Prerequisites:** PyPI account, API token (PyPI → Account settings → API tokens), and `pip install build twine`.
2. **Bump version** in `pyproject.toml` (e.g. `0.1.0` → `0.1.1`).
3. **Build:** From repo root: `python -m build langfuse_tracing_adapter/` — or from this dir: `python -m build`.
4. **Upload:** `cd langfuse_tracing_adapter && twine upload dist/*` (use `TWINE_USERNAME=__token__`, `TWINE_PASSWORD=<pypi-token>`). Test first with `twine upload --repository testpypi dist/*`.

Full step-by-step: see **[PUBLISH_TO_PYPI.md](PUBLISH_TO_PYPI.md)** in this directory.
