Metadata-Version: 2.5
Name: kitaru-logfire-importer
Version: 0.4.0
Summary: Logfire records-query importer for Kitaru.
Project-URL: Homepage, https://kitaru.ai
Project-URL: Documentation, https://docs.zenml.io/kitaru/guides/import-logfire-traces
Project-URL: Repository, https://github.com/zenml-io/kitaru
Project-URL: Issues, https://github.com/zenml-io/kitaru/issues
Project-URL: Changelog, https://github.com/zenml-io/kitaru/blob/develop/plugins/packages/logfire-importer/CHANGELOG.md
Author-email: ZenML GmbH <info@zenml.io>
License-Expression: Apache-2.0
Keywords: ai-agents,kitaru,logfire,observability,traces
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: kitaru>=0.27.0
Provides-Extra: adapter
Requires-Dist: httpx<1,>=0.27; extra == 'adapter'
Requires-Dist: kitaru>=0.27.0; extra == 'adapter'
Requires-Dist: logfire<6,>=4.35; extra == 'adapter'
Provides-Extra: api
Requires-Dist: httpx<1,>=0.27; extra == 'api'
Requires-Dist: kitaru>=0.27.0; extra == 'api'
Requires-Dist: logfire<6,>=4.35; extra == 'api'
Description-Content-Type: text/markdown

# Kitaru Logfire importer

Import Logfire records-query JSON and NDJSON exports as Kitaru sessions. This package backs the built-in `kitaru/logfire` importer and runs on a Kitaru worker, so the export is parsed in your environment.

Most users do not install or call this package directly. Start a Kitaru worker, then select the built-in importer:

```bash
kitaru session import logfire-records.jsonl \
  --importer kitaru/logfire@latest \
  --agent support-agent@latest \
  --wait
```

The importer rebuilds span hierarchy and conservatively identifies model and tool calls from OpenTelemetry attributes. Source identity uses `source_instance`, then the `project_id` parameter alias, then the embedded record `project_id`. Values must be strings; surrounding whitespace is removed, and empty values are absent. If none is available, the affected trace fails: retry with `--params '{"source_instance":"my-logfire-project"}'`. Conflicting embedded project IDs remain errors even with an override. File and API imports use the same identity rules; API credentials do not supply a project identity. Keep the identity stable across imports to preserve deduplication.

See the [Logfire import guide](https://docs.zenml.io/kitaru/guides/import-logfire-traces) for accepted formats, parameters, deduplication behavior, and fidelity limits.

Nested span paths support up to 64 levels, counting a root as level 1. Invalid costs, token counts, embedded JSON, and text that cannot serialize reject the affected grouped session; unrelated sessions continue. A trace rejected before grouping does not prevent a valid sibling trace from importing into the same session.

## Adapter

Install the package with the `adapter` extra to use the adapter, which adds the provider SDK it needs:

```bash
uv add "kitaru-logfire-importer[adapter]"
```

The package also ships an adapter that imports Logfire traces of wrapped agent runs. The adapter uses the Logfire SDK already configured in your process and the Kitaru connection from your environment. Set `LOGFIRE_TOKEN` to the write token the SDK records traces with.

The trace fetch goes through the Logfire Query API, which authenticates with a read token, a separate credential from the SDK's write token. Create one under your Logfire project settings and set it as `LOGFIRE_READ_TOKEN`. Then wrap your agent entrypoint in a `LogfireAdapter` and run it through the adapter.

```python
from kitaru_logfire_importer.adapter import LogfireAdapter

adapter = LogfireAdapter()
result = adapter.run(my_agent, "Hello")
```

The adapter runs the function inside a Logfire trace, waits for Logfire to finish ingesting the trace, fetches it, and imports it as one Kitaru session. Use `run_async` for async functions. When the trace does not complete within the completeness timeout, the adapter creates a failed session carrying the trace id.

## Links

- [Kitaru documentation](https://docs.zenml.io/kitaru)
- [Source code](https://github.com/zenml-io/kitaru)
- [Issue tracker](https://github.com/zenml-io/kitaru/issues)

Licensed under Apache-2.0.
