Internal Architecture

The package is intentionally layered so that public LangChain behavior can stay explicit and testable.

Read the codebase from top to bottom in this order:

1. public entry points connection.py, resources.py, vectorstores.py, embeddings.py, space_embedders.py, and errors.py

2. validators local input validation that rejects malformed values before the SDK is touched

3. behavior layer memory-operation helpers that normalize batch writes and streamed retrieval

4. transport layer the only layer that talks directly to the official GoodMem SDK

5. internal normalized types dataclasses and protocols that keep the layers decoupled

That split is what lets the repository test most edge cases without requiring a live GoodMem deployment for every change.

The embeddings bootstrap path follows the same layering rule:

• embeddings.py owns the public GoodMemEmbeddings.ensure(...) and ensure_from_env(...) entry points

• resources.py owns the public GoodMemResources facade for embedders, spaces, memories, and vector-store bootstrap

• _internal.providers owns bootstrap matching, request normalization, server-side embedder resolution, and local embeddings readiness checks

• _internal.transport owns the SDK calls needed by the resource facade and LangChain-facing classes

• _internal.types owns the package-local bootstrap request and the narrow transport protocols used by upper layers

Private GoodMem memory-operation helpers built on the transport boundary.

This module implements the behavior layer between the public vector-store API and the transport adapter.

Responsibilities:

• turn normalized write requests into stable batch outcomes

• preserve request ordering even when the backend returns explicit request_index values

• decode streamed retrieval events into flat GoodMemSearchHit values

• normalize duplicate-ID and partial-success behavior into package-owned errors

create_space(transport, request)

Create a GoodMem space through the transport boundary.

Parameters:

• transport (SupportsMemoryOperationsTransport) – Transport implementation exposing create-space behavior.

• request (GoodMemSpaceCreateRequest) – Normalized create-space payload.

Returns:

str – The non-empty space_id string extracted from the transport response for the newly created GoodMem space.

Raises:

GoodMemAPIError – If GoodMem does not return a usable space_id.

add_memories(transport, *, space_id, writes)

Create one batch of GoodMem memories.

Parameters:

• transport (SupportsMemoryOperationsTransport) – Transport implementation exposing batch-create behavior.

• space_id (str) – Target GoodMem space ID.

• writes (list[GoodMemWriteRequest]) – Normalized write payloads in caller order.

Returns:

list[str] – Memory IDs in the original request order.

Raises:

• GoodMemDuplicateIDError – If GoodMem reports duplicate IDs.

• GoodMemBatchPartialFailureError – If only part of the batch succeeds.

• GoodMemAPIError – If the response shape is invalid or the backend rejects the batch.

delete_memories(transport, *, memory_ids)

Delete a batch of GoodMem memories.

Parameters:

• transport (SupportsMemoryOperationsTransport) – Transport implementation exposing batch-delete behavior.

• memory_ids (list[str]) – GoodMem memory IDs to delete.

Raises:

GoodMemAPIError – If the response is missing, malformed, reports failed selectors, or does not match the requested delete count.

Return type:

None

search_memories(transport, *, space_id, query, k, filter_expression=None)

Run chunk-level semantic retrieval and flatten the streamed response.

Parameters:

• transport (SupportsMemoryOperationsTransport) – Transport implementation exposing retrieval behavior.

• space_id (str) – Target GoodMem space ID.

• query (str) – Semantic retrieval query.

• k (int) – Maximum number of hits to collect.

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

Returns:

list[GoodMemSearchHit] – Flat GoodMemSearchHit values in retrieval order.

Private helpers for the GoodMem embeddings path.

This module owns the provider-facing logic behind GoodMemEmbeddings.

Responsibilities:

• normalize the GoodMem embedder response into GoodMemEmbedderConfig

• validate that the selected embedder can back an OPENAI-compatible LangChain embeddings adapter

• normalize and validate bootstrap requests used by embedder bootstrap helpers

• find compatible existing embedders before create-once bootstrap falls back to provisioning a new one

• resolve credentials and optional dimensions overrides

• verify that bootstrap-resolved embedders are immediately usable by the current embeddings path

• resolve server-side embedders without local provider initialization for resource bootstrap

• build the upstream provider Embeddings implementation lazily

load_embedder_config(transport, *, embedder_id)

Load and validate one GoodMem embedder configuration.

Parameters:

• transport (SupportsEmbedderTransport) – Transport implementation exposing embedder lookup.

• embedder_id (str) – GoodMem embedder ID to resolve.

Returns:

GoodMemEmbedderConfig – A normalized, validated embedder configuration.

Raises:

• GoodMemConfigurationError – If the embedder shape is incompatible with GoodMemEmbeddings.

• GoodMemAPIError – If GoodMem lookup fails.

create_provider_embeddings(embedder, *, upstream_api_key_override=None)

Build the upstream LangChain embeddings provider for one embedder.

Parameters:

• embedder (GoodMemEmbedderConfig) – Normalized GoodMem embedder configuration.

• upstream_api_key_override (str | None) – Optional explicit upstream API key that takes precedence over inline or environment-based resolution.

Returns:

Embeddings – An Embeddings implementation backed by langchain_openai.OpenAIEmbeddings.

Raises:

• GoodMemConfigurationError – If optional dependencies or upstream credentials are missing.

• GoodMemAPIError – If provider initialization fails.

ensure_embedder(transport, *, request, upstream_api_key_override=None)

Find or create one compatible embedder and verify it is usable.

Parameters:

• transport (SupportsEmbedderTransport) – Transport implementation exposing embedder bootstrap operations.

• request (GoodMemEmbedderBootstrapRequest) – Normalized bootstrap request describing the target embedder.

• upstream_api_key_override (str | None) – Optional explicit upstream API key used during readiness validation when the resolved embedder does not expose a readable inline secret.

Returns:

GoodMemEmbedderConfig – The validated embedder configuration that satisfies GoodMemEmbeddings requirements. Existing matches are revalidated for compatibility and readiness before they are reused.

Raises:

• GoodMemConfigurationError – If the bootstrap request is invalid, if more than one compatible embedder exists, or if the resolved embedder is unusable.

• GoodMemAPIError – If GoodMem list, create, or get operations fail.

ensure_server_side_embedder(transport, *, request)

Find or create one compatible GoodMem embedder for server-side retrieval.

This helper resolves the GoodMem resource needed to create a searchable space without importing or initializing any local LangChain embeddings provider. It is intentionally narrower than ensure_embedder(...): existing matches are reused based on provider shape, and newly created embedders receive the explicit API key from request or the GOODMEM_EMBEDDINGS_API_KEY fallback.

Parameters:

• transport (SupportsEmbedderTransport) – Transport implementation exposing embedder bootstrap operations.

• request (GoodMemEmbedderBootstrapRequest) – Bootstrap request describing the target server-side embedder.

Returns:

GoodMemEmbedderConfig – The validated embedder configuration that can be attached to a GoodMem space for server-side add/search workflows.

Raises:

• GoodMemConfigurationError – If the bootstrap request is invalid, if more than one compatible embedder exists, or if the resolved embedder is not attachable to a text-search space.

• GoodMemAPIError – If GoodMem list or create operations fail.

default_bootstrap_display_name()

Return the fixed default display name for bootstrap-created embedders.

Return type:

str

validate_bootstrap_request(request, *, operation_name='GoodMemEmbeddings.ensure')

Validate and normalize one bootstrap request.

Parameters:

• request (GoodMemEmbedderBootstrapRequest) – Candidate bootstrap request supplied by the public entry point.

• operation_name (str) – Public operation name used in validation errors.

Returns:

GoodMemEmbedderBootstrapRequest – A normalized bootstrap request.

Raises:

GoodMemConfigurationError – If any field is unsupported, blank, or invalid for the selected bootstrap flow.

find_matching_embedders(transport, *, request)

Return compatible embedders visible to the current client.

Parameters:

• transport (SupportsEmbedderTransport) – Transport implementation exposing embedder listing.

• request (GoodMemEmbedderBootstrapRequest) – Normalized bootstrap request describing the desired embedder.

Returns:

list[GoodMemEmbedderConfig] – Compatible embedder configurations in transport-provided order.

find_server_side_matching_embedders(transport, *, request)

Return compatible embedders for server-side GoodMem retrieval.

Return type:

list[GoodMemEmbedderConfig]

embedder_matches_bootstrap_request(embedder, *, request)

Check whether one embedder satisfies the requested bootstrap target.

Return type:

bool

format_provider_failure_message(prefix, exc)

Format one provider failure message with bounded detail text.

Parameters:

• prefix (str) – Stable message prefix that identifies the failing operation.

• exc (Exception) – Original exception raised by the provider or setup path.

Returns:

str – A human-readable error string that includes bounded exception detail text when any detail is available.

resolve_upstream_api_key(embedder, *, upstream_api_key_override=None)

Resolve the upstream provider API key for one embedder configuration.

Parameters:

• embedder (GoodMemEmbedderConfig) – Normalized GoodMem embedder configuration.

• upstream_api_key_override (str | None) – Optional explicit upstream API key that takes precedence over inline or environment-based resolution.

Returns:

str – The API key that should be forwarded to the upstream embeddings provider.

Raises:

GoodMemConfigurationError – If neither inline credentials nor the environment fallback can satisfy the selected embedder.

resolve_upstream_dimensions(embedder)

Resolve the optional dimensions override for the upstream provider.

Parameters:

embedder (GoodMemEmbedderConfig) – Normalized GoodMem embedder configuration.

Returns:

int | None – The configured dimensions override, or None when the environment variable is unset.

Raises:

GoodMemConfigurationError – If the environment value is invalid or does not match the GoodMem embedder dimensionality.

validate_compatible_embedder_config(embedder)

Validate that a GoodMem embedder can back GoodMemEmbeddings.

Parameters:

embedder (GoodMemEmbedderConfig) – Normalized GoodMem embedder configuration.

Returns:

None – None when the embedder configuration satisfies all provider compatibility requirements.

Raises:

GoodMemConfigurationError – If provider type, modality, endpoint, model, dimensions, or API path assumptions are not satisfied.

validate_server_side_embedder_config(embedder)

Validate that an embedder can be attached for server-side text search.

Unlike validate_compatible_embedder_config(...), this does not require local credential forwarding or a LangChain OpenAI-compatible API path.

Return type:

None

build_provider_base_url(embedder)

Build the upstream provider base URL from endpoint and API path.

Parameters:

embedder (GoodMemEmbedderConfig) – Normalized GoodMem embedder configuration.

Returns:

str – The upstream provider base URL expected by langchain_openai.OpenAIEmbeddings after removing any terminal /embeddings path segment.

Shared private validators used by public entry points.

This module keeps local input validation in package-owned code so public entry points can reject malformed values before transport code or the GoodMem SDK is invoked.

require_non_empty_trimmed_string(value, *, error_message, exception_type)

Require one strict string input to be present and non-blank.

Parameters:

• value (str | None) – Candidate string value to validate.

• error_message (str) – Message used when validation fails.

• exception_type (type[Exception]) – Exception class raised for invalid input.

Returns:

str – The trimmed string value.

Raises:

Exception – An instance of exception_type when value is missing, not a string, or blank after trimming.

require_verify_value(verify)

Validate the verify shape accepted by GoodMemConnection.

Parameters:

verify (bool | str) – TLS verification value supplied by the caller.

Returns:

bool | str – Either the original boolean value or a validated non-empty string path.

Raises:

GoodMemConfigurationError – If verify is neither a boolean nor a non-empty string.

require_space_id(space_id)

Validate one existing-space identifier.

Parameters:

space_id (str) – Existing GoodMem space identifier supplied by the caller.

Returns:

str – The trimmed GoodMem space identifier.

Raises:

GoodMemConfigurationError – If space_id is missing, not a string, or blank.

require_embedder_id(embedder_id)

Validate one explicit GoodMem embedder identifier.

Parameters:

embedder_id (str) – Explicit GoodMem embedder identifier supplied by the caller.

Returns:

str – The trimmed GoodMem embedder identifier.

Raises:

GoodMemConfigurationError – If embedder_id is missing, not a string, or blank.

validate_text_inputs(texts, *, label, exception_type, field_name=None)

Validate one list of text inputs and preserve original ordering.

Parameters:

• texts (list[Any]) – Candidate text values to validate.

• label (str) – Logical collection name used in validation errors.

• exception_type (type[Exception]) – Exception class raised when validation fails.

• field_name (str | None) – Optional field label appended to error messages for nested sources such as Document.page_content.

Returns:

list[str] – The validated string values in original order, preserving their original text content.

Raises:

Exception – An instance of exception_type when any value is not a string or is blank after trimming.

validate_lengths(label, expected_length, *, metadatas=None, ids=None)

Validate metadata and ID list lengths against one text/document count.

Parameters:

• label (str) – Logical collection name used in validation errors.

• expected_length (int) – Required number of entries.

• metadatas (list[Any] | None) – Optional metadata list aligned to the source collection.

• ids (list[str | None] | None) – Optional ID list aligned to the source collection.

Returns:

None – None when both optional lists match expected_length.

Raises:

ValueError – If either optional list length does not match expected_length.

normalize_metadatas(metadatas)

Normalize metadata mappings into plain dictionaries.

Parameters:

metadatas (list[Mapping[str, Any] | None] | None) – Optional metadata values aligned to a write input collection.

Returns:

list[dict[str, Any]] | None – None when metadatas is None; otherwise one plain-dictionary metadata value per input item, with None entries converted to empty dictionaries.

Raises:

ValueError – If any non-None metadata value is not a mapping.

normalize_space_embedders(embedders)

Validate and normalize create-time space-embedder declarations.

Parameters:

embedders (list[GoodMemSpaceEmbedder]) – Candidate create-time GoodMem space-embedder declarations.

Returns:

list[GoodMemSpaceEmbedder] – A validated list of GoodMemSpaceEmbedder values.

Raises:

GoodMemConfigurationError – If embedders is empty or contains values other than GoodMemSpaceEmbedder instances.

normalize_optional_ids(ids, *, source, exception_type)

Normalize one aligned list of optional strict-create memory IDs.

Parameters:

• ids (list[str | None] | None) – Optional aligned memory ID list.

• source (str) – Logical source name used in validation errors.

• exception_type (type[Exception]) – Exception class raised when validation fails.

Returns:

list[str | None] | None – None when ids is None; otherwise a normalized list whose entries are either None or non-empty strings.

Raises:

Exception – An instance of exception_type when any value is neither None nor a non-empty string.

validate_duplicate_ids(ids)

Reject repeated non-None memory IDs in one local write call.

Parameters:

ids (list[str | None] | None) – Optional aligned memory ID list to inspect.

Returns:

None – None when ids is None or when all non-None IDs are unique.

Raises:

GoodMemDuplicateIDError – If the same non-None memory ID appears more than once.

validate_similarity_search_inputs(*, query, k, filter_expression)

Validate the public similarity-search input shape.

Parameters:

• query (str) – Candidate semantic retrieval query text.

• k (int) – Requested result count.

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

Returns:

str – The validated query string.

Raises:

ValueError – If query is blank, k is not a positive integer, or filter_expression is neither None nor a string.

raise_for_unexpected_kwargs(operation, kwargs)

Reject service-specific keyword arguments that the package does not support.

Parameters:

• operation (str) – Operation name used in the error message.

• kwargs (dict[str, Any]) – Keyword arguments provided by the caller.

Returns:

None – None when kwargs is empty.

Raises:

ValueError – If any unsupported keyword arguments are present.

Official GoodMem SDK transport boundary with normalized exceptions.

This module is the only package layer that talks directly to the GoodMem SDK.

Responsibilities:

• construct the SDK client from GoodMemConnection

• map package-owned request shapes onto SDK request objects

• expose the narrow embedder list/get/create calls needed by the bootstrap embeddings path

• normalize SDK-specific exceptions into package-owned errors

• preserve consumer exceptions when retrieval streams are consumed lazily

class GoodMemTransport(connection)

Official GoodMem SDK backed transport implementation.

Parameters:

connection (GoodMemConnection) – Validated GoodMem transport configuration used to construct the underlying SDK client.

Raises:

GoodMemConfigurationError – If the optional goodmem dependency is not installed.

create_space(request)

Create a GoodMem space from one normalized request payload.

Parameters:

request (GoodMemSpaceCreateRequest) – Package-owned create-space payload.

Returns:

Any – The raw GoodMem SDK response object for the created space.

Raises:

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

• GoodMemAPIError – If the SDK rejects the request or raises any other backend failure.

get_space(*, space_id)

Load one GoodMem space response by ID.

Return type:

Any

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

List GoodMem spaces visible to the current client.

Return type:

Any

delete_space(*, space_id)

Delete one GoodMem space by ID.

Return type:

Any

batch_create_memories(*, space_id, writes)

Create one batch of GoodMem memories from normalized write payloads.

Parameters:

• space_id (str) – Target GoodMem space ID.

• writes (list[GoodMemWriteRequest]) – Package-owned memory-write payloads in request order.

Returns:

Any – The raw GoodMem SDK batch-create response.

Raises:

• GoodMemDuplicateIDError – If GoodMem reports duplicate memory IDs.

• GoodMemAPIError – If the SDK rejects the request or raises any other backend failure.

retrieve_memories(*, space_id, query, k, filter_expression=None)

Yield one GoodMem retrieval stream while normalizing setup failures.

Parameters:

• space_id (str) – Target GoodMem space ID.

• query (str) – Semantic retrieval query text.

• k (int) – Requested result count forwarded to GoodMem.

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

Yields:

The SDK-managed stream of retrieval events.

Raises:

GoodMemAPIError – If stream setup or stream teardown fails for a backend reason. Consumer exceptions raised while iterating the yielded events are preserved as-is.

Return type:

Iterator[Any]

create_memory(request)

Create one GoodMem memory from a normalized request.

Return type:

Any

get_memory(*, memory_id, include_content=False)

Load one GoodMem memory response by ID.

Return type:

Any

list_memories(*, space_id, filter_expression=None, max_items=None)

List GoodMem memories in one space.

Return type:

Any

delete_memory(*, memory_id)

Delete one GoodMem memory by ID.

Return type:

Any

delete_memories(*, memory_ids)

Delete one batch of GoodMem memories by ID.

Return type:

Any

get_embedder(*, embedder_id)

Load one GoodMem embedder response by ID.

Parameters:

embedder_id (str) – GoodMem embedder identifier to resolve.

Returns:

Any – The raw GoodMem SDK embedder response.

Raises:

GoodMemAPIError – If GoodMem rejects the lookup or any other backend failure occurs.

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

List GoodMem embedders visible to the current client.

Returns:

Any – The raw GoodMem SDK embedder listing response.

Raises:

GoodMemAPIError – If GoodMem rejects the listing or any other backend failure occurs.

create_embedder(request)

Create one GoodMem embedder from a normalized bootstrap request.

Parameters:

request (GoodMemEmbedderBootstrapRequest) – Package-owned bootstrap request describing the embedder to create.

Returns:

Any – The raw GoodMem SDK response object for the created embedder.

Raises:

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

• GoodMemAPIError – If the SDK rejects the request or raises any other backend failure.

delete_embedder(*, embedder_id)

Delete one GoodMem embedder by ID.

Return type:

Any