Embeddings Workflow

GoodMemEmbeddings is the right tool only for the workflows that truly need a local LangChain Embeddings object.

Use it when:

  • your application explicitly calls embed_query(...) or embed_documents(...)

  • you want GoodMemVectorStore.create(..., embedding=...) to retain that embeddings object on the returned store

You do not need GoodMemEmbeddings just to search an existing GoodMem space. GoodMemVectorStore(space_id=..., ...) can retrieve directly from GoodMem without any local embeddings adapter.

There are two embeddings startup paths:

  • Existing-resource path: use GoodMemEmbeddings(embedder_id=..., connection=...) when you already know the compatible GoodMem embedder ID you want.

  • Clean-slate bootstrap path: use GoodMemEmbeddings.ensure(...) or GoodMemEmbeddings.ensure_from_env(...) when you need the package to find or create one compatible OPENAI embedder first. When you reuse GOODMEM_EMBEDDER_ID through ensure_from_env(...), the bootstrap environment must still be present and must match that embedder exactly.

For a broader clean-slate workflow, use GoodMemResources. It can resolve an embedder, create a space, and return a ready-to-use GoodMemVectorStore while keeping broader GoodMem platform administration out of this package. That path is server-side only; it does not retain a local Embeddings object.

The examples below show both clean-slate bootstrap and the direct embeddings-driven path, and the API section after them explains the exact setup and failure behavior.

Clean-slate bootstrap workflow with GoodMemResources.

This example shows how to start from a GoodMem deployment that may not already have a suitable embedder configured for LangChain use.

The resources facade covers the GoodMem pieces needed by the normal LangChain RAG/search path:

  • it finds one compatible GoodMem embedder when one already exists

  • it creates one compatible GoodMem embedder when none exists

  • it creates a space using that embedder

  • it returns a ready-to-use GoodMemVectorStore

This helper is not a full GoodMem admin surface. API keys, server init, migrations, system operations, and LLM/reranker/OCR/extension administration remain in GoodMem’s SDK, CLI, and UI.

Required environment:

  • GOODMEM_API_KEY

  • GOODMEM_BASE_URL

  • GOODMEM_EMBEDDINGS_BASE_URL

  • GOODMEM_EMBEDDINGS_MODEL_IDENTIFIER

  • GOODMEM_EMBEDDINGS_DIMENSIONS

Optional environment:

  • GOODMEM_EMBEDDINGS_API_KEY when the upstream API key must be stored on a newly created embedder

Run the example with:

./.venv/bin/python examples/goodmem_embeddings_bootstrap_workflow.py

Embeddings-driven create workflow for GoodMemEmbeddings.

This example shows how to expose a GoodMem-managed embedder as a LangChain Embeddings object, use it as the create-time source for GoodMemVectorStore.create(...), and then run both direct embedding and semantic retrieval calls.

Choose this workflow when the same GoodMem embedder should serve two roles:

  • it should be attached to the newly created GoodMem space

  • it should remain available locally for direct LangChain embedding calls

If you only need server-side retrieval for a new space, the lighter-weight GoodMemSpaceEmbedder path is usually simpler.

Prerequisites:

  • install the optional embeddings dependency with pip install -e '.[openai]'

  • provide GOODMEM_API_KEY and GOODMEM_BASE_URL

  • identify a compatible GoodMem embedder ID

Credential resolution:

  • preferred path: the selected GoodMem embedder already stores a readable inline API key

  • fallback path: set GOODMEM_EMBEDDINGS_API_KEY when the embedder does not expose a readable inline secret or uses another credential form

If your upstream endpoint expects an explicit dimensions field, also export GOODMEM_EMBEDDINGS_DIMENSIONS with the same value declared on the GoodMem embedder.

Run the example with:

./.venv/bin/python examples/goodmem_embeddings_workflow.py

Search visibility is eventually consistent. A fresh write may need time before semantic retrieval returns the new chunk, and the returned Document.id value will be the matching chunk ID rather than the parent memory ID.

class GoodMemEmbeddings(embedder_id, connection)[source]

LangChain embeddings implementation backed by a GoodMem embedder.

This adapter loads the GoodMem embedder lazily on the first real embedding request, validates that the upstream provider shape is compatible, and then delegates to langchain_openai.OpenAIEmbeddings.

embedder_id is the identifier of a GoodMem embedder resource, not the raw upstream model name. GoodMem is responsible for storing the provider connection details that this adapter resolves on demand.

Parameters:

  • embedder_id (str) – Explicit GoodMem embedder ID to load on demand.

  • connection (GoodMemConnection) – Shared GoodMem transport configuration.

Raises:

GoodMemConfigurationError – If embedder_id is blank.

classmethod ensure(*, connection, endpoint_url, model_identifier, dimensionality, upstream_api_key=None, display_name=None)[source]

Find or create one compatible GoodMem embedder and return it.

This helper resolves one OPENAI-compatible embedder that can back GoodMemEmbeddings. Use GoodMemResources when you also need to manage spaces, memories, or one-shot vector-store bootstrap.

Parameters:

  • connection (GoodMemConnection) – Shared GoodMem transport configuration.

  • endpoint_url (str) – Upstream provider endpoint URL.

  • model_identifier (str) – Upstream embedding model identifier.

  • dimensionality (int) – Required embedding dimensionality.

  • upstream_api_key (str | None) – Optional upstream API key stored on a newly created embedder. When omitted, the helper falls back to GOODMEM_EMBEDDINGS_API_KEY for creation.

  • display_name (str | None) – Optional display name used only when a new embedder must be created.

Returns:

GoodMemEmbeddings – A ready-to-use GoodMemEmbeddings instance bound to the matched or created GoodMem embedder.

Raises:

  • GoodMemConfigurationError – If the bootstrap inputs are invalid, if multiple compatible embedders are found, or if the resolved embedder is incompatible with GoodMemEmbeddings.

  • GoodMemAPIError – If GoodMem rejects the bootstrap lookup or create operations.

classmethod ensure_from_env(*, connection=None, verify=True)[source]

Build one bootstrap-backed embeddings adapter from environment.

This helper reuses the current GOODMEM_EMBEDDINGS_* contract to resolve one compatible embedder without introducing a larger resource management surface. When GOODMEM_EMBEDDER_ID is set, the helper reuses that embedder only after confirming the bootstrap environment still matches the embedder’s endpoint, model, and dimensionality.

Parameters:

  • connection (GoodMemConnection | None) – Optional explicit GoodMem connection. When omitted, the helper uses GoodMemConnection.from_env().

  • verify (bool | str) – TLS verification setting used only when connection is omitted and a new connection must be built from environment.

Returns:

GoodMemEmbeddings – A ready-to-use GoodMemEmbeddings instance bound to the matched or created GoodMem embedder.

Raises:

  • GoodMemConfigurationError – If required bootstrap environment values are missing or invalid.

  • GoodMemAPIError – If GoodMem rejects the bootstrap lookup or create operations.

embed_documents(texts)[source]

Embed a list of texts through the resolved upstream provider.

Parameters:

texts (list[str]) – Non-empty text inputs to embed. These calls do not write any memories into GoodMem; they only use GoodMem as the source of embedder configuration.

Returns:

list[list[float]] – A list of embedding vectors. Empty input returns an empty list without contacting GoodMem or the upstream provider.

Raises:

  • GoodMemConfigurationError – If any text input is blank or if the selected embedder cannot be configured.

  • GoodMemAPIError – If the upstream provider initialization or request fails.

embed_query(text)[source]

Embed one query string through the resolved upstream provider.

Parameters:

text (str) – Non-empty query text. This call does not retrieve from or write to a GoodMem space; it only resolves the configured upstream embedder.

Returns:

list[float] – One embedding vector.

Raises:

  • GoodMemConfigurationError – If the query is blank or the embedder setup is invalid.

  • GoodMemAPIError – If provider initialization or the upstream request fails.