Internal Types

These types are not public API, but they are important to the internal design.

Why they exist:

• they keep upper layers from depending directly on raw GoodMem SDK models

• they give validators, behavior helpers, and transport adapters a shared package-owned vocabulary

• they make unit tests easier to write because protocols can be faked without recreating the whole SDK surface

Pay special attention to:

• GoodMemWriteRequest for normalized write inputs

• GoodMemSearchHit for the chunk-level shape that eventually becomes a LangChain Document

• GoodMemSpaceCreateRequest, GoodMemMemoryCreateRequest, GoodMemEmbedderBootstrapRequest, and GoodMemEmbedderConfig for the resource, bootstrap, and embeddings paths

• the transport protocols for the smallest callable surface each upper layer actually needs

Private normalized request and response models.

The dataclasses and protocols in this module are package-owned internal contracts. They keep validation, behavior, and transport concerns separated without exposing raw GoodMem SDK model classes to upper layers.

class GoodMemWriteRequest(page_content, metadata=<factory>, memory_id=None, content_type=None)

Normalized write payload used by the vector store.

Parameters:

• page_content (str) – Validated text content that will be stored as the memory body.

• metadata (dict[str, Any]) – Normalized metadata dictionary attached to the memory.

• memory_id (str | None) – Optional strict-create memory ID supplied by the caller.

• content_type (str | None) – Optional transport-level content type override.

page_content

Validated text content that will be stored as the memory body.

metadata

Normalized metadata dictionary attached to the memory.

memory_id

Optional strict-create memory ID supplied by the caller.

content_type

Optional transport-level content type override.

class GoodMemSearchHit(chunk_id, memory_id, space_id, page_content, metadata, score)

Normalized semantic search hit returned to the vector store.

Parameters:

• chunk_id (str) – GoodMem chunk identifier that becomes Document.id.

• memory_id (str) – Parent memory identifier preserved in metadata.

• space_id (str) – Originating GoodMem space identifier.

• page_content (str) – Retrieved chunk text.

• metadata (dict[str, Any]) – Merged memory-level and chunk-level metadata.

• score (float) – Retrieval relevance score.

chunk_id

GoodMem chunk identifier that becomes Document.id.

memory_id

Parent memory identifier preserved in metadata.

space_id

Originating GoodMem space identifier.

page_content

Retrieved chunk text.

metadata

Merged memory-level and chunk-level metadata.

score

Retrieval relevance score.

class GoodMemSpaceCreateRequest(name, space_embedders, labels=None)

Normalized create-space request passed through the transport boundary.

Parameters:

• name (str) – Requested GoodMem space name.

• space_embedders (list[GoodMemSpaceEmbedder]) – Package-owned embedder declarations to attach to the created space.

• labels (dict[str, str] | None) – Optional GoodMem labels attached to the created space.

name

Requested GoodMem space name.

space_embedders

Package-owned embedder declarations to attach to the created space.

labels

Optional GoodMem labels attached to the created space.

class GoodMemEmbedderConfig(embedder_id, provider_type, endpoint_url, api_path, model_identifier, dimensionality, supported_modalities, credential_kind=None, inline_api_key=None)

Normalized embedder metadata used by GoodMemEmbeddings.

Parameters:

• embedder_id (str) – GoodMem embedder identifier.

• provider_type (str) – Normalized provider type such as OPENAI.

• endpoint_url (str) – Upstream provider endpoint URL.

• api_path (str | None) – Optional provider-specific embeddings path segment.

• model_identifier (str) – Upstream embedding model identifier.

• dimensionality (int) – Configured embedding dimensionality.

• supported_modalities (tuple[str, ...]) – Normalized modality list exposed by GoodMem.

• credential_kind (str | None) – Credential mechanism reported by GoodMem, when any.

• inline_api_key (str | None) – Readable inline API key exposed by GoodMem, when any.

embedder_id

GoodMem embedder identifier.

provider_type

Normalized provider type such as OPENAI.

endpoint_url

Upstream provider endpoint URL.

api_path

Optional provider-specific embeddings path segment.

model_identifier

Upstream embedding model identifier.

dimensionality

Configured embedding dimensionality.

supported_modalities

Normalized modality list exposed by GoodMem.

credential_kind

Credential mechanism reported by GoodMem, when any.

inline_api_key

Readable inline API key exposed by GoodMem, when any.

class GoodMemEmbedderBootstrapRequest(display_name, endpoint_url, model_identifier, dimensionality, provider_type='OPENAI', supported_modalities=('TEXT',), api_key=None)

Normalized bootstrap request used by embedder bootstrap helpers.

Parameters:

• display_name (str) – Display name assigned when a new embedder is created.

• endpoint_url (str) – Upstream provider endpoint URL.

• model_identifier (str) – Upstream embedding model identifier.

• dimensionality (int) – Required embedding dimensionality.

• provider_type (str) – Fixed provider type for the bootstrap flow.

• supported_modalities (tuple[str, ...]) – Required supported modalities for both matching and creation.

• api_key (str | None) – Optional upstream API key stored on a newly created embedder.

display_name

Display name assigned when a new embedder is created.

endpoint_url

Upstream provider endpoint URL.

model_identifier

Upstream embedding model identifier.

dimensionality

Required embedding dimensionality.

provider_type

Fixed provider type for the bootstrap flow.

supported_modalities

Required supported modalities for both matching and creation.

api_key

Optional upstream API key stored on a newly created embedder.

class GoodMemMemoryCreateRequest(space_id, content, metadata=<factory>, memory_id=None)

Normalized create-memory request used by the resource facade.

Parameters:

• space_id (str) – Target GoodMem space ID.

• content (str) – Text content stored as the GoodMem memory body.

• metadata (dict[str, Any]) – Normalized metadata dictionary attached to the memory.

• memory_id (str | None) – Optional strict-create memory ID supplied by the caller.

space_id

Target GoodMem space ID.

content

Text content stored as the GoodMem memory body.

metadata

Normalized metadata dictionary attached to the memory.

memory_id

Optional strict-create memory ID supplied by the caller.

class SupportsMemoryOperationsTransport(*args, **kwargs)

Narrow transport surface used by vector-store memory operations.

This protocol keeps the vector-store and memory-operation layers decoupled from the full GoodMem client surface.

create_space(request)

Create one GoodMem space from a normalized request payload.

Parameters:

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

Returns:

object – A transport-specific response object describing the created space.

batch_create_memories(*, space_id, writes)

Create one batch of GoodMem memories in the target space.

Parameters:

• space_id (str) – Target GoodMem space ID.

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

Returns:

object – A transport-specific batch response object containing one result per write request.

delete_memories(*, memory_ids)

Delete a batch of GoodMem memories by memory ID.

Parameters:

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

Returns:

object – A transport-specific batch-delete response object.

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

Return a context-managed stream of GoodMem retrieval events.

Parameters:

• space_id (str) – Target GoodMem space ID.

• query (str) – Semantic retrieval query text.

• k (int) – Maximum number of results requested from the transport.

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

Returns:

AbstractContextManager[Iterable[Any]] – A context manager that yields an iterable of transport-specific retrieval events.

class SupportsEmbedderTransport(*args, **kwargs)

Narrow transport surface used by embeddings/provider operations.

This protocol isolates embedder lookup from memory-operation behavior so tests can stub provider setup independently.

get_embedder(*, embedder_id)

Load one GoodMem embedder response by ID.

Parameters:

embedder_id (str) – GoodMem embedder identifier to resolve.

Returns:

object – A transport-specific embedder response object.

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

List GoodMem embedders visible to the current client.

Parameters:

• label (dict[str, str] | None) – Optional label filter forwarded to GoodMem.

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

• provider_type (str | None) – Optional provider type filter forwarded to GoodMem.

Returns:

Iterable[object] – An iterable of transport-specific embedder response objects.

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:

object – A transport-specific response object describing the created embedder.

class SupportsResourceOperationsTransport(*args, **kwargs)

Transport surface used by the public GoodMem resource facade.

delete_embedder(*, embedder_id)

Delete one GoodMem embedder by ID.

Return type:

object

get_space(*, space_id)

Load one GoodMem space by ID.

Return type:

object

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

List GoodMem spaces visible to the current client.

Return type:

Iterable[object]

delete_space(*, space_id)

Delete one GoodMem space by ID.

Return type:

object

create_memory(request)

Create one GoodMem memory from a normalized request.

Return type:

object

get_memory(*, memory_id, include_content=False)

Load one GoodMem memory by ID.

Return type:

object

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

List GoodMem memories in one space.

Return type:

Iterable[object]

delete_memory(*, memory_id)

Delete one GoodMem memory by ID.

Return type:

object