Metadata-Version: 2.5
Name: kitaru-phoenix-importer
Version: 0.3.0
Summary: Arize Phoenix trace importer for Kitaru.
Project-URL: Homepage, https://kitaru.ai
Project-URL: Documentation, https://docs.zenml.io/kitaru/getting-started/import-your-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/phoenix-importer/CHANGELOG.md
Author-email: ZenML GmbH <info@zenml.io>
License-Expression: Apache-2.0
Keywords: ai-agents,arize-phoenix,kitaru,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.24.0
Provides-Extra: adapter
Requires-Dist: arize-phoenix-client<4,>=2.0; extra == 'adapter'
Requires-Dist: httpx<1,>=0.27; extra == 'adapter'
Requires-Dist: kitaru>=0.26.0; extra == 'adapter'
Requires-Dist: opentelemetry-api>=1.12; extra == 'adapter'
Requires-Dist: opentelemetry-sdk>=1.12; extra == 'adapter'
Provides-Extra: api
Requires-Dist: arize-phoenix-client<4,>=2.0; extra == 'api'
Requires-Dist: httpx<1,>=0.27; extra == 'api'
Requires-Dist: kitaru>=0.26.0; extra == 'api'
Description-Content-Type: text/markdown

# Kitaru Arize Phoenix importer

Import Arize Phoenix JSON and JSONL trace exports as Kitaru sessions. This package backs the built-in `kitaru/phoenix` 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 phoenix-traces.jsonl \
  --importer kitaru/phoenix@latest \
  --agent support-agent@latest \
  --params '{"project":"my-project"}' \
  --wait
```

The importer accepts Phoenix UI and CLI export shapes, preserves trace hierarchy and source evidence, and maps model and tool spans to Kitaru node types. Each Phoenix trace becomes one Kitaru session. Session external IDs are `<source_instance>:<trace_id>`. Identity comes from `params.source_instance`, then `params.project`, then an embedded top-level `project` field on a trace envelope or span. Strings are trimmed; null, empty, and whitespace-only values are absent. Other types and conflicting embedded projects within a trace fail that trace, including when an explicit parameter is supplied. Exports without project identity require an explicit parameter; filenames are never used.

API imports retain the queried project, or the Phoenix environment project, in the parser payload. The adapter retains its configured environment project in the same way. Reuse that exact project identifier for file imports: project names and project IDs are not resolved to one another. This changes external IDs from earlier importer versions, which used bare trace IDs; reimporting an older trace can create a second session.

See [Import your traces](https://docs.zenml.io/kitaru/getting-started/import-your-traces) for the live import workflow. The [provider-specific guide in the Kitaru repository](https://github.com/zenml-io/kitaru/blob/develop/docs/book/guides/import-phoenix-traces.md) documents accepted Phoenix formats, 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 trace; unrelated traces continue. Malformed indexed message keys are ignored while valid indexed messages remain available.

## Adapter

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

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

The package also ships an adapter that imports Arize Phoenix traces of wrapped agent runs. The adapter uses the OTel tracer provider Phoenix tracing already configured in your process, for example via `phoenix.otel.register()`, and the Kitaru connection from your environment.

The trace fetch goes through the Phoenix client, which reads `PHOENIX_ENDPOINT` (or `PHOENIX_COLLECTOR_ENDPOINT`), `PHOENIX_API_KEY`, and the project name from `PHOENIX_PROJECT` from your environment. Fetching by trace id requires a Phoenix server >= 13.9.0. Then wrap your agent entrypoint in a `PhoenixAdapter` and run it through the adapter.

```python
from kitaru_phoenix_importer.adapter import PhoenixAdapter

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

The adapter runs the function inside an OTel trace, waits for Phoenix 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.
