> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate from honeyhive-bundled to v1
> Move from honeyhive-bundled to the main HoneyHive Python SDK package.
`honeyhive-bundled` was a temporary distribution of the Python SDK with pre-release packaging. The stable v1 SDK is published as `honeyhive`.
Most imports stay the same because both packages expose the `honeyhive` Python module. The migration is mainly a dependency change plus cleanup of pre-release patterns.
Recent `honeyhive-bundled` releases and `honeyhive` v1 share the same top-level import style: `from honeyhive import HoneyHiveTracer, trace, evaluate`.
```text theme={null}
Use this HoneyHive migration guide: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/honeyhive-bundled-to-v1.md
Explore my codebase to find where HoneyHive Python SDK dependencies and tracing setup are configured. Ask me any questions needed to understand the project context, runtime, and migration constraints. Then present a concise migration plan for my confirmation. After I confirm the plan, implement the migration changes.
```
## What changes
| Area | `honeyhive-bundled` | `honeyhive>=1.0.0` |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ |
| Package name | `honeyhive-bundled` | `honeyhive` |
| Release channel | Pre-release / bundled distribution | Stable package |
| Default API URL | `https://api.honeyhive.ai` | `https://api.dp1.us.honeyhive.ai` |
| Project routing | Older examples may pass `project=` | `project=` still accepted but emits a `DeprecationWarning` and will be removed in v2 |
| `honeyhive.config` | Alias for the `TracerConfig` class (callable) | Submodule containing `TracerConfig`, `SessionConfig`, `EvaluationConfig`, etc. |
| `clear_baggage_context` | Exported from `honeyhive` | Removed from the public API |
| `honeyhive` CLI command | Registered as a console script | No console script registered |
| OpenTelemetry minimum | `>=1.20.0` | `>=1.41.0` |
If your deployment relies on the default API host (for example, when running through a corporate proxy or allow-list), set `HH_API_URL` to your existing host before upgrading. v1 changes the default host to `https://api.dp1.us.honeyhive.ai`.
***
## 1. Replace the dependency
```bash theme={null}
pip uninstall honeyhive-bundled -y
pip install "honeyhive>=1.0.0"
```
If you use extras, install the matching extras on `honeyhive`:
```bash OpenInference theme={null}
pip install "honeyhive[openinference-openai]"
pip install "honeyhive[openinference-anthropic]"
pip install "honeyhive[openinference-langchain]"
```
```bash OpenLLMetry / Traceloop theme={null}
pip install "honeyhive[traceloop-openai]"
pip install "honeyhive[traceloop-anthropic]"
pip install "honeyhive[traceloop-aws-bedrock]"
```
`honeyhive>=1.0.0` keeps every OpenInference and Traceloop extra that `honeyhive-bundled` shipped and adds new ones: LangChain, LiteLLM, OpenAI Agents, Claude Agent SDK, AWS Strands, and the `openinference-llm-providers` / `traceloop-llm-providers` multi-provider bundles. Run `pip check` after upgrading if your environment pins OpenTelemetry packages, because `honeyhive` v1 requires OpenTelemetry `>=1.41.0`.
The Google AI extra is renamed under the hood: bundled installed `openinference-instrumentation-google-generativeai`, but `honeyhive[openinference-google-ai]>=1.0.0` installs `openinference-instrumentation-google-genai` instead. If you import the instrumentor directly, update the import path.
Verify the install:
```python theme={null}
import honeyhive
print(honeyhive.__version__)
```
`honeyhive-bundled` reports its internal `honeyhive.__version__` as `1.0.0rc9.post2` even at PyPI version `1.1.1`. After migrating, `honeyhive.__version__` will report the published v1 version (for example `1.0.2`).
***
## 2. Update imports
A few symbols that `honeyhive-bundled` exported are no longer part of the public API in v1. Update or remove these imports:
| Import in `honeyhive-bundled` | Status in `honeyhive>=1.0.0` | What to do |
| --------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `from honeyhive import clear_baggage_context` | Removed | Delete the call. Baggage is managed automatically by `HoneyHiveTracer` during init and session creation. |
| `honeyhive.config(...)` (config alias for `TracerConfig`) | `honeyhive.config` is now a submodule, not a class | Import the class explicitly: `from honeyhive.config import TracerConfig`. |
| `honeyhive.__version_bundled__` | Removed | Read `honeyhive.__version__` instead. |
Everything else keeps the same top-level import style:
```python theme={null}
from honeyhive import HoneyHiveTracer, trace, evaluate
```
If your dependency file names the bundled package, update it:
```toml pyproject.toml before theme={null}
[project]
dependencies = [
"honeyhive-bundled[openinference-openai]>=1.0.1",
]
```
```toml pyproject.toml after theme={null}
[project]
dependencies = [
"honeyhive[openinference-openai]>=1.0.0",
]
```
The `honeyhive` console-script that `honeyhive-bundled` registered is not published by `honeyhive>=1.0.0`, and the underlying `honeyhive.cli` module is deprecated. Replace those calls with the official [HoneyHive CLI](/v2/cli-reference/getting-started) (`@honeyhive/cli`), which is a separate package that maps one-to-one to the HoneyHive REST API.
***
## 3. Initialize instrumentors separately
`HoneyHiveTracer.init()` does not consume an `instrumentors=` argument in either `honeyhive-bundled` or `honeyhive>=1.0.0`. Bundled accepted it silently via `**kwargs` and never called `instrumentor.instrument()`, so spans were never produced from that list. Initialize provider instrumentors yourself after `HoneyHiveTracer.init()` and pass `tracer.provider` so they emit spans into the HoneyHive tracer.
```python unsupported pattern theme={null}
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
project="support-bot",
instrumentors=[OpenAIInstrumentor()], # silently ignored
)
```
```python v1 SDK theme={null}
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor
tracer = HoneyHiveTracer.init(api_key="your-api-key")
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)
```
Initialize the tracer before any instrumentor. Instrumentors need the HoneyHive tracer provider to route spans correctly.
`evaluate()` is different: it still accepts an `instrumentors=` keyword and uses the factories per datapoint. See section 6.
See [OpenAI](/v2/integrations/openai), [Anthropic](/v2/integrations/anthropic), and [LangChain](/v2/integrations/langchain) for provider-specific setup.
***
## 4. Remove project routing from new code
v1 accepts `project=` for compatibility but emits a `DeprecationWarning` and will remove it in v2. Project context is inferred from the API key. `honeyhive-bundled` accepted `project=` silently, so after migrating, expect a warning on every initialization until you drop the argument.
```text theme={null}
DeprecationWarning: The 'project' argument to HoneyHiveTracer.init() is
deprecated; it will be removed in v2.0. Remove it from HoneyHiveTracer.init()
calls — the backend infers project context from the API key.
```
```python older pattern theme={null}
import os
from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(
api_key=os.environ["HH_API_KEY"],
project=os.environ["HH_PROJECT"],
source="production",
)
```
```python v1-compatible and v2-ready theme={null}
import os
from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(
api_key=os.environ["HH_API_KEY"],
source="production",
)
```
For existing v1 deployments, you can remove `project=` after confirming your API keys are scoped to the intended project.
***
## 5. Prefer tracer instance methods for enrichment
Free helpers such as `enrich_span()` and `enrich_session()` are still exported and still work in v1, but tracer instance methods are the primary pattern because they are explicit and behave correctly when multiple tracers are in play.
```python still works in v1 theme={null}
from honeyhive import enrich_span, trace
@trace(event_type="tool")
def retrieve(query):
docs = search(query)
enrich_span(metadata={"query": query}, outputs={"docs": docs})
return docs
```
```python v1 recommended theme={null}
from honeyhive import HoneyHiveTracer, trace
tracer = HoneyHiveTracer.init(api_key="your-api-key")
@trace(event_type="tool", tracer=tracer)
def retrieve(query):
docs = search(query)
tracer.enrich_span(metadata={"query": query}, outputs={"docs": docs})
return docs
```
See [Enriching Traces](/v2/tracing/enrich-traces).
***
## 6. Check `evaluate()` usage
The stable v1 experiment API expects datasets with `ground_truth` and functions that receive the full datapoint.
```python theme={null}
from honeyhive import evaluate
from openinference.instrumentation.openai import OpenAIInstrumentor
dataset = [
{
"inputs": {"question": "What is the capital of France?"},
"ground_truth": {"answer": "Paris"},
},
]
def run_pipeline(datapoint):
question = datapoint["inputs"]["question"]
return {"answer": answer(question)}
def exact_match(outputs, inputs, ground_truth):
return {"score": outputs["answer"] == ground_truth["answer"]}
evaluate(
function=run_pipeline,
dataset=dataset,
evaluators=[exact_match],
api_key="your-api-key",
instrumentors=[lambda: OpenAIInstrumentor()],
)
```
Use instrumentor factories in `evaluate()`, for example `lambda: OpenAIInstrumentor()`. The SDK creates a fresh tracer per datapoint and initializes instrumentors inside the evaluation runner, so pass a factory instead of a shared pre-initialized instrumentor.
***
## 7. Validate the migration
Run:
```bash theme={null}
pip check
PYTHONWARNINGS=default python your_app.py
```
Confirm:
* `pip show honeyhive-bundled` no longer finds an installed package
* `pip show honeyhive` shows version `1.0.0` or later
* No `from honeyhive import clear_baggage_context` imports remain
* Any `honeyhive.config(...)` callers use `from honeyhive.config import TracerConfig`
* No `HoneyHiveTracer.init(..., instrumentors=...)` calls remain
* `HH_API_URL` is set if you rely on a non-default host
* Traces appear in the expected project
* Provider spans appear after instrumentor initialization
* Experiments show `ground_truth` and evaluator scores
***
## Migration checklist
* [ ] Remove `honeyhive-bundled` from dependency files
* [ ] Add `honeyhive>=1.0.0` with matching or newer integration extras
* [ ] Confirm the default API host change is safe, or set `HH_API_URL`
* [ ] Remove `from honeyhive import clear_baggage_context`
* [ ] Replace `honeyhive.config(...)` calls with `from honeyhive.config import TracerConfig`
* [ ] Replace `honeyhive` console-script usage in CI or scripts with the official [HoneyHive CLI](/v2/cli-reference/getting-started) (`@honeyhive/cli`)
* [ ] Initialize instrumentors after `HoneyHiveTracer.init()`
* [ ] Remove `project=` from new initialization code after confirming project-scoped API keys
* [ ] Prefer `tracer.enrich_span()` and `tracer.enrich_session()`
* [ ] Confirm `evaluate()` uses `ground_truth` and datapoint-based functions
* [ ] Run `pip check` and your app's smoke tests
## Related
Upgrade older SDK code to stable v1 semantics.
Replace `honeyhive-logger` calls with SDK v1 tracing.
Choose the right SDK and integration path.
Install and initialize provider instrumentors.
Configure SDK runtime behavior.