Migrating from v1.x to v2.x#

This guide describes the breaking changes and required updates to migrate from 1.x to 2.x.

🔴 Breaking Changes#

BaseDocument

The following methods have been removed in favor of direct property access:

❌ Removed Method	✅ Replacement
`get_metadata()`	`document.metadata`
`get_embedding()`	`document.embedding`

DocumentWithScore

The following methods have been removed:

❌ Removed Method	✅ Replacement
`get_score()`	`document_with_score.normalized_score`
`get_content()`	`document_with_score.content`
`get_metadata()`	`document_with_score.metadata`

embed_text

Before:

embedding = embed_text("hello world")  # could return a single vector

After:

embeddings = embed_text("hello world")  # always returns a list
embedding = embeddings[0]

⚠️ Important: Update any code that assumes a single embedding vector is returned.

Removed

Renamed

❌ Old Name	✅ New Name
`WatsonxMetric`	`WatsonxMetricSpec`

Module paths have been updated to reflect the new naming conventions.

❌ Old Import	✅ New Import
`beekeeper.readers`	`beekeeper.loaders`
`beekeeper.monitors`	`beekeeper.observability`

You can use these patterns to accelerate migration: