API Reference

The pages below are generated from the package’s exported modules.

Reading tips:

• start with langchain_goodmem.vectorstores if you want the main LangChain workflow

• read langchain_goodmem.embeddings only if you need local embedding calls

• read langchain_goodmem.resources if you need the GoodMem embedders, spaces, and memories used by a normal LangChain RAG workflow

• use langchain_goodmem.space_embedders to understand the embedders= path of GoodMemVectorStore.create(...)

• read langchain_goodmem.errors if you need to catch and distinguish package errors precisely

langchain_goodmem.connection	Public GoodMem connection configuration.
langchain_goodmem.resources	GoodMem resource helpers for normal LangChain RAG workflows.
langchain_goodmem.vectorstores	LangChain vector-store integration backed by GoodMem semantic retrieval.
langchain_goodmem.embeddings	LangChain embeddings adapter for GoodMem-managed embedders.
langchain_goodmem.space_embedders	Create-time embedder declarations for GoodMemVectorStore.create.
langchain_goodmem.errors	Package-local exceptions exported by langchain_goodmem.

Public GoodMem connection configuration.

GoodMemConnection is the caller-facing transport configuration shared by the vector-store and embeddings entry points.

Use GoodMemConnection(...) when you want to pass credentials and TLS settings explicitly in code. Use GoodMemConnection.from_env() when your process already provides:

• GOODMEM_API_KEY

• GOODMEM_BASE_URL

GOODMEM_VERIFY is intentionally not read by this module. Pass verify= explicitly when you need a custom TLS setting.

class GoodMemConnection(api_key, base_url, verify=True)

Normalized GoodMem transport configuration.

Parameters:

• api_key (str) – GoodMem API key used for all SDK-backed requests.

• base_url (str) – Base URL for the GoodMem API or deployment.

• verify (bool | str) – TLS verification setting forwarded to the GoodMem SDK client. Use True or False for standard verification behavior, or a non-empty string path when the SDK should use a custom CA bundle.

api_key

Trimmed GoodMem API key.

base_url

Trimmed GoodMem base URL.

verify

Validated TLS verification setting.

Raises:

GoodMemConfigurationError – If any field is missing, blank, or uses an unsupported verify shape.

classmethod from_env(*, verify=True)

Build a connection from GoodMem process environment variables.

Parameters:

verify (bool | str) – TLS verification setting forwarded to the constructor after GOODMEM_API_KEY and GOODMEM_BASE_URL are loaded.

Returns:

GoodMemConnection – A validated GoodMemConnection instance.

Raises:

GoodMemConfigurationError – If either required environment variable is missing or blank.

GoodMem resource helpers for normal LangChain RAG workflows.

GoodMemResources is the public GoodMem-specific companion to the LangChain-facing GoodMemVectorStore and GoodMemEmbeddings classes. It covers the resources needed to get from a clean GoodMem instance to a first query without asking users to import the GoodMem SDK directly:

• embedders used by LangChain embedding and retrieval flows

• spaces that scope writes and searches

• memories written and deleted through LangChain workflows

The facade intentionally stops at the RAG/search boundary. It does not expose broader GoodMem platform administration such as API key lifecycle management, server initialization, migrations, system operations, or LLM/reranker/OCR administration.

class GoodMemEmbedderInfo(embedder_id, display_name, provider_type, endpoint_url, model_identifier, dimensionality, supported_modalities)

Stable public summary of a GoodMem embedder.

Parameters:

• embedder_id (str | None) – GoodMem embedder identifier, or None if missing from an unexpected backend response.

• display_name (str | None) – User-facing embedder name.

• provider_type (str | None) – Provider type such as OPENAI.

• endpoint_url (str | None) – Upstream embeddings endpoint URL.

• model_identifier (str | None) – Upstream embeddings model identifier.

• dimensionality (int | None) – Embedding vector dimensionality.

• supported_modalities (tuple[str, ...]) – Supported content modalities.

class GoodMemSpaceInfo(space_id, name, labels, embedder_ids)

Stable public summary of a GoodMem space.

Parameters:

• space_id (str | None) – GoodMem space identifier, or None if missing from an unexpected backend response.

• name (str | None) – User-facing space name.

• labels (dict[str, str]) – Space labels normalized to a plain dictionary.

• embedder_ids (tuple[str, ...]) – GoodMem embedder IDs attached to the space.

class GoodMemMemoryInfo(memory_id, space_id, metadata, content, processing_status)

Stable public summary of a GoodMem memory.

Parameters:

• memory_id (str | None) – GoodMem memory identifier, or None if missing from an unexpected backend response.

• space_id (str | None) – Parent GoodMem space identifier.

• metadata (dict[str, Any]) – Memory metadata normalized to a plain dictionary.

• content (str | bytes | None) – Original content when the backend response includes it.

• processing_status (str | None) – GoodMem processing status when available.

class GoodMemResources(connection)

Facade for GoodMem resources used by LangChain RAG workflows.

Parameters:

connection (GoodMemConnection) – Shared GoodMem transport configuration.

classmethod from_env(*, verify=True)

Build a resources facade from GOODMEM_API_KEY and GOODMEM_BASE_URL.

Parameters:

verify (bool | str) – TLS verification setting forwarded to GoodMemConnection.from_env.

Returns:

GoodMemResources – A resources facade using environment-provided GoodMem credentials.

create_embedder(*, endpoint_url, model_identifier, dimensionality, upstream_api_key=None, display_name=None)

Create one OPENAI-compatible GoodMem embedder.

Parameters:

• 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 the embedder.

• display_name (str | None) – Optional user-facing name. A stable package default is used when omitted.

Returns:

GoodMemEmbedderInfo – A package-owned embedder summary.

Raises:

• ValueError – If local inputs are malformed.

• GoodMemDuplicateIDError – If GoodMem reports that the embedder already exists.

• GoodMemAPIError – If GoodMem rejects the create request.

get_embedder(embedder_id)

Return one GoodMem embedder by ID.

Parameters:

embedder_id (str) – GoodMem embedder identifier to load.

Returns:

GoodMemEmbedderInfo – A package-owned embedder summary.

Raises:

• ValueError – If embedder_id is blank or not a string.

• GoodMemAPIError – If GoodMem rejects the lookup.

list_embedders(*, label=None, owner_id=None, provider_type=None)

List embedders visible to the current GoodMem credentials.

Parameters:

• label (Mapping[str, str] | None) – Optional GoodMem label filter.

• owner_id (str | None) – Optional GoodMem owner ID filter.

• provider_type (str | None) – Optional GoodMem provider type filter such as OPENAI.

Returns:

list[GoodMemEmbedderInfo] – Package-owned embedder summaries.

Raises:

• ValueError – If local filter inputs have invalid shapes.

• GoodMemAPIError – If GoodMem rejects the listing.

delete_embedder(embedder_id)

Delete one GoodMem embedder by ID.

Parameters:

embedder_id (str) – GoodMem embedder identifier to delete.

Raises:

• ValueError – If embedder_id is blank or not a string.

• GoodMemAPIError – If GoodMem rejects the delete.

Return type:

None

create_space(name, embedders=None, embedding=None, labels=None)

Create one GoodMem space for LangChain writes and retrieval.

Exactly one embedder source is accepted: explicit embedders or a single GoodMemEmbeddings instance.

Parameters:

• name (str) – Requested GoodMem space name.

• embedders (list[GoodMemSpaceEmbedder] | None) – Explicit GoodMem space-embedder declarations.

• embedding (GoodMemEmbeddings | None) – Existing GoodMemEmbeddings instance whose embedder ID should be attached to the new space.

• labels (Mapping[str, str] | None) – Optional GoodMem labels for the new space.

Returns:

GoodMemSpaceInfo – A package-owned space summary.

Raises:

• ValueError – If name or labels are invalid.

• GoodMemConfigurationError – If embedder inputs are missing, mixed, or incompatible.

• GoodMemAPIError – If GoodMem rejects the create request.

get_space(space_id)

Return one GoodMem space by ID.

Parameters:

space_id (str) – GoodMem space identifier to load.

Returns:

GoodMemSpaceInfo – A package-owned space summary.

Raises:

• ValueError – If space_id is blank or not a string.

• GoodMemAPIError – If GoodMem rejects the lookup.

list_spaces(*, label=None, name_filter=None, max_items=None)

List spaces visible to the current GoodMem credentials.

Parameters:

• label (Mapping[str, str] | None) – Optional GoodMem label filter.

• name_filter (str | None) – Optional GoodMem name filter.

• max_items (int | None) – Optional positive result limit.

Returns:

list[GoodMemSpaceInfo] – Package-owned space summaries. When GoodMem returns a paginated SDK list object, this method follows subsequent pages automatically until all visible results are collected or max_items is reached.

Raises:

• ValueError – If local filter inputs have invalid shapes.

• GoodMemAPIError – If GoodMem rejects the listing.

delete_space(space_id)

Delete one GoodMem space by ID.

Parameters:

space_id (str) – GoodMem space identifier to delete.

Raises:

• ValueError – If space_id is blank or not a string.

• GoodMemAPIError – If GoodMem rejects the delete.

Return type:

None

create_memory(space_id, content, metadata=None, memory_id=None)

Create one GoodMem memory in a space.

Parameters:

• space_id (str) – Target GoodMem space identifier.

• content (str) – Non-empty memory content. The original text is preserved after validation.

• metadata (Mapping[str, Any] | None) – Optional memory metadata mapping.

• memory_id (str | None) – Optional caller-supplied GoodMem memory ID.

Returns:

GoodMemMemoryInfo – A package-owned memory summary.

Raises:

• ValueError – If inputs are malformed or blank where required.

• GoodMemDuplicateIDError – If GoodMem reports that memory_id already exists.

• GoodMemAPIError – If GoodMem rejects the create request.

get_memory(memory_id, *, include_content=False)

Return one GoodMem memory by ID.

Parameters:

• memory_id (str) – GoodMem memory identifier to load.

• include_content (bool) – Whether to request original memory content from GoodMem when the backend supports it.

Returns:

GoodMemMemoryInfo – A package-owned memory summary.

Raises:

• ValueError – If memory_id or include_content is invalid.

• GoodMemAPIError – If GoodMem rejects the lookup.

list_memories(space_id, filter=None, max_items=None)

List memories in one GoodMem space.

Parameters:

• space_id (str) – GoodMem space identifier to list memories from.

• filter (str | None) – Optional raw GoodMem memory filter expression.

• max_items (int | None) – Optional positive result limit.

Returns:

list[GoodMemMemoryInfo] – Package-owned memory summaries. When GoodMem returns a paginated SDK list object, this method follows subsequent pages automatically until all visible results are collected or max_items is reached.

Raises:

• ValueError – If local filter inputs have invalid shapes.

• GoodMemAPIError – If GoodMem rejects the listing.

delete_memory(memory_id)

Delete one GoodMem memory by ID.

Parameters:

memory_id (str) – GoodMem memory identifier to delete.

Raises:

• ValueError – If memory_id is blank or not a string.

• GoodMemAPIError – If GoodMem rejects the delete.

Return type:

None

delete_memories(memory_ids)

Delete multiple GoodMem memories by ID.

Parameters:

memory_ids (list[str]) – Non-empty GoodMem memory IDs to delete.

Raises:

• ValueError – If memory_ids is empty or contains invalid values.

• GoodMemDuplicateIDError – If duplicate memory IDs are supplied after trimming.

• GoodMemAPIError – If GoodMem rejects the delete request or returns a malformed batch-delete response.

Return type:

None

bootstrap_vector_store(space_name, endpoint_url, model_identifier, dimensionality, upstream_api_key=None, embedder_display_name=None)

Create or reuse an embedder, create a space, and return a vector store.

Parameters:

• space_name (str) – Requested GoodMem space name.

• endpoint_url (str) – Upstream embeddings endpoint URL.

• model_identifier (str) – Upstream embeddings model identifier.

• dimensionality (int) – Required embedding dimensionality.

• upstream_api_key (str | None) – Optional upstream API key used when a compatible embedder must be created. When omitted, GOODMEM_EMBEDDINGS_API_KEY is used as a creation fallback.

• embedder_display_name (str | None) – Optional display name used when creating a new compatible embedder.

Returns:

GoodMemVectorStore – A GoodMemVectorStore bound to the newly created space. This server-side bootstrap path does not retain a local embeddings object, so store.embeddings is None.

Raises:

• ValueError – If space_name is malformed.

• GoodMemConfigurationError – If embedder bootstrap inputs are malformed, if no compatible embedder can be used, or if the created space response is missing a usable ID.

• GoodMemAPIError – If GoodMem rejects an embedder or space request.

LangChain vector-store integration backed by GoodMem semantic retrieval.

This module is the main public workflow surface for the repository.

Two primary usage modes are supported:

• bind to an existing GoodMem space with GoodMemVectorStore(...)

• create a new GoodMem space with GoodMemVectorStore.create(...)

GoodMem uses three related concepts that map differently to LangChain:

• a space is the search scope

• a memory is one stored item of source content plus metadata

• a chunk is a searchable fragment produced by GoodMem from a memory

Write methods in this module create memories. Retrieval methods return chunks. One memory can therefore produce multiple search results over time.

Write behavior is intentionally explicit:

• caller-provided IDs are treated as memory IDs with strict create-if-absent semantics

• Document.id is used as a fallback memory ID source in add_documents(...)

• duplicate IDs in a single call raise GoodMemDuplicateIDError before any backend call

Search behavior is chunk-level:

• Document.id in search results is the GoodMem chunk_id

• the parent memory ID is preserved in Document.metadata as _goodmem_memory_id

• the originating space ID is preserved in Document.metadata as _goodmem_space_id

• scored results also expose _goodmem_score in metadata

Metadata filters are passed through to GoodMem unchanged. They operate on the memory-level metadata JSON attached to each stored memory, not on LangChain Document.metadata after conversion and not on chunk text. The documented GoodMem filter language uses helpers such as val('$.field') and exists('$.array[*]'). A minimal equality example is val('$.lang') = 'en'.

GoodMem processes new memories asynchronously before they become searchable, so fresh writes may not appear in retrieval results immediately.

The create helper intentionally keeps a minimal LangChain-facing surface. If you need GoodMem resource helpers around the normal RAG/search path, use GoodMemResources. Broader platform administration remains outside this LangChain integration.

class GoodMemVectorStore(space_id, connection)

LangChain vector store for GoodMem-managed semantic add/search.

Each instance is bound to exactly one GoodMem space. add_documents(...) and add_texts(...) write memories into that space. Search methods return chunk-level LangChain Document values derived from GoodMem retrieval hits, which means the returned Document.id identifies the matching chunk, not the original written memory.

Parameters:

• space_id (str) – Existing GoodMem space identifier to bind to.

• connection (GoodMemConnection) – Shared GoodMem transport configuration.

space_id

Trimmed GoodMem space identifier.

embeddings

Optional retained embeddings object. Existing-space stores expose None because retrieval happens on the GoodMem side.

Raises:

GoodMemConfigurationError – If space_id is blank.

property embeddings

Return the retained embeddings object when one exists.

Returns:

The GoodMemEmbeddings instance retained by GoodMemVectorStore.create(..., embedding=...), or None for existing-space stores, stores created with explicit embedders=[GoodMemSpaceEmbedder(...)], and from_texts(...) compatibility stores.

classmethod create(*, name, embedders=None, connection, embedding=None)

Create a new GoodMem space and return a bound vector store.

Exactly one create-time embedder source is allowed:

• embedders=[GoodMemSpaceEmbedder(...)]

• embedding=GoodMemEmbeddings(...)

Choose embedders=... when you already know the GoodMem embedder ID or IDs that should be attached to the new space and you only need server-side retrieval behavior.

Choose embedding=... when you want the same GoodMem embedder to serve both roles:

• attach its embedder_id to the new space

• remain available locally as store.embeddings for LangChain code that also calls embed_query(...) or embed_documents(...)

In other words, embedding=GoodMemEmbeddings(...) is the single-embedder shorthand that also preserves a usable LangChain Embeddings object on the returned store.

Parameters:

• name (str) – Requested GoodMem space name.

• embedders (list[GoodMemSpaceEmbedder] | None) – Explicit GoodMem space-embedder declarations. Use this when you want to declare one or more existing GoodMem embedder IDs directly.

• connection (GoodMemConnection) – Shared GoodMem transport configuration.

• embedding (GoodMemEmbeddings | None) – GoodMem-managed embeddings adapter whose embedder ID should be attached to the new space and then retained on the returned store as store.embeddings.

Returns:

GoodMemVectorStore – A vector store bound to the created space.

Raises:

• GoodMemConfigurationError – If embedder inputs are missing, mixed, or incompatible with the create helper.

• GoodMemAPIError – If GoodMem rejects the create request.

add_documents(documents, ids=None, **kwargs)

Add LangChain documents to the bound GoodMem space.

Each input document becomes one GoodMem memory. GoodMem may later split that memory into one or more searchable chunks during asynchronous processing.

Parameters:

• documents (list[Document]) – Documents whose page_content becomes GoodMem memory content.

• ids (list[str | None] | None) – Optional explicit memory IDs. When omitted, the method falls back to Document.id values.

• **kwargs (Any) – No service-specific keyword arguments are supported.

Returns:

list[str] – Created or accepted memory IDs in request order. These are memory IDs, not chunk IDs. Empty input returns an empty list without contacting GoodMem.

Raises:

• ValueError – If document text, IDs, or unexpected keyword arguments fail local validation.

• GoodMemDuplicateIDError – If duplicate strict-create IDs are supplied or the backend reports duplicate IDs.

• GoodMemBatchPartialFailureError – If a batch partially succeeds.

• GoodMemAPIError – If GoodMem rejects the write.

add_texts(texts, metadatas=None, *, ids=None, **kwargs)

Add raw texts to the bound GoodMem space.

Each input text becomes one GoodMem memory. GoodMem may later split that memory into one or more searchable chunks during asynchronous processing.

Parameters:

• texts (list[str] | tuple[str, ...] | Any) – Iterable of non-empty strings. Passing one plain string is rejected because it is ambiguous with an iterable of characters.

• metadatas (list[Mapping[str, Any] | None] | None) – Optional metadata mappings aligned to texts.

• ids (list[str | None] | None) – Optional explicit memory IDs aligned to texts.

• **kwargs (Any) – No service-specific keyword arguments are supported.

Returns:

list[str] – Created or accepted memory IDs in request order. These are memory IDs, not chunk IDs. Empty input returns an empty list without contacting GoodMem.

Raises:

• ValueError – If input shapes, text values, metadata values, IDs, or unexpected keyword arguments fail local validation.

• GoodMemDuplicateIDError – If duplicate strict-create IDs are supplied or the backend reports duplicate IDs.

• GoodMemBatchPartialFailureError – If a batch partially succeeds.

• GoodMemAPIError – If GoodMem rejects the write.

similarity_search(query, k=4, filter=None, **kwargs)

Return semantic matches for query.

Parameters:

• query (str) – Non-empty semantic query string.

• k (int) – Maximum number of chunk-level Document values to return.

• filter (str | None) – Optional GoodMem memory-metadata filter expression string. The expression is passed to GoodMem unchanged and is evaluated before chunk results are returned. Use the documented GoodMem filter language, for example val('$.lang') = 'en' or exists('$.tags[*]').

• **kwargs (Any) – No additional search keyword arguments are supported.

Returns:

list[Document] – Chunk-level Document values. Document.id is the GoodMem chunk ID. Document.metadata includes _goodmem_chunk_id, _goodmem_memory_id, and _goodmem_space_id so callers can trace the hit back to the parent memory and space.

Raises:

• ValueError – If the query shape, k, filter, or keyword arguments fail local validation.

• GoodMemAPIError – If GoodMem rejects the retrieval request.

similarity_search_with_score(query, k=4, filter=None, **kwargs)

Return semantic matches and scores for query.

Parameters:

• query (str) – Non-empty semantic query string.

• k (int) – Maximum number of scored chunk-level matches to return.

• filter (str | None) – Optional GoodMem memory-metadata filter expression string. The expression is passed to GoodMem unchanged and is evaluated before chunk results are returned. Use the documented GoodMem filter language, for example val('$.lang') = 'en' or exists('$.tags[*]').

• **kwargs (Any) – No additional search keyword arguments are supported.

Returns:

list[tuple[Document, float]] – Tuples of (Document, score) where the returned document metadata also includes _goodmem_score. Document.id is still the GoodMem chunk ID rather than the parent memory ID.

Raises:

• ValueError – If the query shape, k, filter, or keyword arguments fail local validation.

• GoodMemAPIError – If GoodMem rejects the retrieval request.

delete(ids=None, **kwargs)

Delete GoodMem memories by memory ID.

Parameters:

• ids (list[str] | None) – GoodMem memory IDs to delete. None is rejected because it would imply deleting an entire space, which this LangChain adapter does not expose implicitly.

• **kwargs (Any) – No service-specific keyword arguments are supported.

Returns:

bool – True when the delete request succeeds. Empty ID lists return True without contacting GoodMem.

Raises:

• ValueError – If ids is None, contains blank values, contains invalid values, or if unexpected keyword arguments are passed.

• GoodMemDuplicateIDError – If duplicate memory IDs are supplied.

• GoodMemAPIError – If GoodMem rejects the delete request or returns a malformed batch-delete response.

classmethod from_texts(texts, embedding, metadatas=None, *, connection, space_id, ids=None, **kwargs)

Write texts into an existing GoodMem space and return a bound store.

This compatibility helper matches the LangChain VectorStore convention, but it does not create a new GoodMem space. The provided embedding argument is accepted only because LangChain expects it in this constructor shape; this package neither uses it for the write nor retains it on the returned store.

Parameters:

• texts (list[str]) – Texts to write into an existing GoodMem space.

• embedding (Embeddings) – Accepted for LangChain compatibility only. GoodMem retrieval for this helper still runs on the GoodMem side, so the argument is ignored for both the write and the returned store.

• metadatas (list[Mapping[str, Any] | None] | None) – Optional metadata mappings aligned to texts.

• connection (GoodMemConnection) – Shared GoodMem transport configuration.

• space_id (str) – Existing GoodMem space identifier.

• ids (list[str | None] | None) – Optional explicit memory IDs aligned to texts.

• **kwargs (Any) – No service-specific keyword arguments are supported.

Returns:

GoodMemVectorStore – A vector store bound to the existing GoodMem space after the write.

Raises:

• ValueError – If the write inputs or keyword arguments fail validation.

• GoodMemConfigurationError – If space_id is blank.

• GoodMemDuplicateIDError – If duplicate strict-create IDs are supplied or the backend reports duplicate IDs.

• GoodMemBatchPartialFailureError – If a batch partially succeeds.

• GoodMemAPIError – If GoodMem rejects the write.

LangChain embeddings adapter for GoodMem-managed embedders.

GoodMemEmbeddings turns one existing GoodMem embedder resource into a LangChain Embeddings implementation, but only when that GoodMem embedder is compatible with an OPENAI-style upstream embeddings endpoint.

Use this adapter when you need local LangChain embedding calls such as embed_query(...) or embed_documents(...), or when you want GoodMemVectorStore.create(..., embedding=...) to both create a space and retain a LangChain 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 object.

Credential resolution order:

1. readable inline API key stored on the GoodMem embedder

2. GOODMEM_EMBEDDINGS_API_KEY

For clean-slate onboarding, GoodMemEmbeddings.ensure(...) and GoodMemEmbeddings.ensure_from_env(...) can find or create one compatible GoodMem embedder before returning a normal GoodMemEmbeddings instance. ensure_from_env(...) also supports GOODMEM_EMBEDDER_ID reuse, but when that path is used the bootstrap environment must still be present and must match the selected embedder so configuration drift stays explicit. For broader RAG-resource setup such as spaces, memories, and one-shot vector-store bootstrap, use GoodMemResources.

Additional environment support:

• GOODMEM_EMBEDDINGS_DIMENSIONS remains optional, but when set it must match the dimensionality declared on the selected GoodMem embedder

• GOODMEM_EMBEDDINGS_BASE_URL, GOODMEM_EMBEDDINGS_MODEL_IDENTIFIER, and GOODMEM_EMBEDDINGS_DIMENSIONS are required by GoodMemEmbeddings.ensure_from_env(...) even when that helper reuses an existing GOODMEM_EMBEDDER_ID

Common setup failures covered by this module include:

• missing optional langchain-openai dependency

• unsupported provider type or modality

• upstream credential forwarding that GoodMem cannot perform directly

• provider initialization or request failures, which normalize to GoodMemAPIError

class GoodMemEmbeddings(embedder_id, connection)

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)

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)

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)

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)

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.

Create-time embedder declarations for GoodMemVectorStore.create.

This module is the direct-space-configuration counterpart to langchain_goodmem.embeddings:

• use GoodMemSpaceEmbedder when you only need to attach one or more existing GoodMem embedder IDs to a newly created space

• use GoodMemEmbeddings when you also need a local LangChain Embeddings object

class GoodMemSpaceEmbedder(embedder_id, default_retrieval_weight=None)

Public create-time embedder declaration.

Use this dataclass when GoodMemVectorStore.create(...) should create a new space from one or more explicit GoodMem embedder IDs instead of inferring a single embedder from GoodMemEmbeddings.

This is the right choice when you already know which GoodMem embedder IDs the space should use for retrieval and you do not need a retained local LangChain Embeddings object on the returned store.

Parameters:

• embedder_id (str) – Non-empty GoodMem embedder identifier.

• default_retrieval_weight (float | None) – Optional retrieval weight attached to this embedder in the created space. GoodMem uses these weights when a space has multiple embedders and retrieval needs to blend their results. Omit the value to let GoodMem apply its default weight.

embedder_id

Trimmed GoodMem embedder identifier.

default_retrieval_weight

Retrieval weight normalized to float when provided.

Raises:

GoodMemConfigurationError – If embedder_id is blank or default_retrieval_weight is not numeric.

Package-local exceptions exported by langchain_goodmem.

The package keeps a small, explicit error model:

• configuration errors for local validation or missing setup

• operational errors for backend, transport, or duplicate-ID failures

• batch-partial-failure details so callers can reconcile successful writes

exception LangChainGoodMemError

Base class for all package-specific exceptions.

exception GoodMemConfigurationError

Raised when required GoodMem configuration is missing or invalid.

exception GoodMemOperationError

Raised when a GoodMem-backed operation fails.

exception GoodMemDuplicateIDError

Raised when a memory ID collides with an existing or repeated ID.

exception GoodMemAPIError

Raised when the GoodMem backend returns an API or transport failure.

class GoodMemBatchWriteResultItem(request_index, success, memory_id, error_code, error_message)

Stable per-item batch write result surfaced to callers.

Parameters:

• request_index (int) – Input position for the original write request.

• success (bool) – Whether the corresponding write succeeded.

• memory_id (str | None) – Created or caller-provided memory ID when available.

• error_code (int | None) – Backend error code for failures, when exposed.

• error_message (str | None) – Backend error message for failures, when exposed.

request_index

Input position for the original write request.

success

Whether the corresponding write succeeded.

memory_id

Created or caller-provided memory ID when available.

error_code

Backend error code for failures, when exposed.

error_message

Backend error message for failures, when exposed.

exception GoodMemBatchPartialFailureError(message, *, created_ids, results)

Raised when a batch write partially succeeds and partially fails.

Parameters:

• message (str) – Summary of the partial-failure condition.

• created_ids (list[str]) – Successfully created memory IDs from the same batch.

• results (list[GoodMemBatchWriteResultItem]) – Per-item batch result details in request order.

created_ids

Successfully created memory IDs from the same batch.

results

Per-item batch result details in request order.