Metadata-Version: 2.4
Name: goodmem-client
Version: 1.5.3
Summary: API for interacting with the GoodMem service, providing vector-based memory storage and retrieval with multiple embedder support.
Home-page: https://github.com/PAIR-Systems-Inc/goodmem
Author: GoodMem API Support
Author-email: support@goodmem.io
License: Apache 2.0
Project-URL: Bug Reports, https://github.com/PAIR-Systems-Inc/goodmem/issues
Project-URL: Source, https://github.com/PAIR-Systems-Inc/goodmem/tree/main/clients/python
Project-URL: PyPI, https://pypi.org/project/goodmem-client/
Keywords: OpenAPI,OpenAPI-Generator,GoodMem API,vector,embeddings,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >= 3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# goodmem-client

[![PyPI version](https://img.shields.io/pypi/v/goodmem-client.svg)](https://pypi.org/project/goodmem-client/)
Python client for GoodMem - a vector-based memory storage and retrieval service. Provides APIs for creating memory spaces, storing memories with vector embeddings, and performing semantic search with streaming retrieval. Supports multiple embedding providers and advanced metadata handling.

This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:

- API version: v1
- Package version: 1.5.3
- Generator version: 7.13.0
- Build package: org.openapitools.codegen.languages.PythonClientCodegen
For more information, please visit [https://goodmem.io/support](https://goodmem.io/support)

## Requirements.

Python 3.9+

## Installation & Usage
### pip install

You can install the package directly from PyPI:

```sh
pip install goodmem-client
```

If you prefer uv:

```sh
uv pip install goodmem-client
```

Then import the package:
```python
import goodmem_client
```

### Setuptools

Install via [Setuptools](http://pypi.python.org/pypi/setuptools).

```sh
python setup.py install --user
```
(or `sudo python setup.py install` to install the package for all users)

Then import the package:
```python
import goodmem_client
```

### Tests

Execute `pytest` to run the tests.

## Getting Started

Please follow the [installation procedure](#installation--usage) and then run the following:

```python

# Import required modules
from goodmem_client.api import APIKeysApi, SpacesApi
from goodmem_client.configuration import Configuration
from goodmem_client.api_client import ApiClient
from goodmem_client.models import CreateApiKeyRequest
from goodmem_client.streaming import MemoryStreamClient
from goodmem_client.rest import ApiException
from pprint import pprint

# Configure the API client
configuration = Configuration()
configuration.host = "http://localhost:8080"  # Use your server URL

# Create API client
api_client = ApiClient(configuration=configuration)

# Set authentication
api_client.default_headers["x-api-key"] = "your-api-key"  # Your API key here

# Create an instance of the API class
api_instance = APIKeysApi(api_client=api_client)

# Prepare a create request with labels
create_request = CreateApiKeyRequest(
    labels={
        "environment": "development",
        "service": "chat-ui"
    }
)

try:
    # Create a new API key
    api_response = api_instance.create_api_key(create_api_key_request=create_request)
    print("API Key created successfully:")
    print(f"API Key ID: {api_response.api_key_metadata.api_key_id}")
    print(f"Raw API Key: {api_response.raw_api_key}")
except ApiException as e:
    print(f"Exception when calling APIKeysApi->create_api_key: {e}")
```

### Streaming Memory Retrieval

For memory retrieval operations, use the streaming client which is the primary way to search and retrieve memories:

```python
from goodmem_client.api import SpacesApi
from goodmem_client.streaming import MemoryStreamClient
from goodmem_client.configuration import Configuration
from goodmem_client.api_client import ApiClient

# Configure client
configuration = Configuration()
configuration.host = "http://localhost:8080"
api_client = ApiClient(configuration=configuration)
api_client.default_headers["x-api-key"] = "your-api-key"

# Create streaming client
spaces_api = SpacesApi(api_client=api_client)
stream_client = MemoryStreamClient(api_client)

# Get space ID (first available space)
spaces = spaces_api.list_spaces()
space_id = spaces.spaces[0].space_id if spaces.spaces else None

# Stream memory retrieval using advanced POST endpoint with custom post-processor
for event in stream_client.retrieve_memory_stream(
    message="your search query",
    space_ids=[space_id] if space_id else None,
    requested_size=5,
    fetch_memory=True,
    fetch_memory_content=False,
    format="ndjson",
    post_processor_name="com.goodmem.retrieval.postprocess.ChatPostProcessorFactory",
    post_processor_config={
        "llm_id": "your-llm-uuid",
        "reranker_id": "your-reranker-uuid",
        "relevance_threshold": 0.5,
        "max_results": 10
    }
):
    if event.abstract_reply:
        print(f"Abstract: {event.abstract_reply.text}")
    elif event.retrieved_item and event.retrieved_item.memory:
        memory = event.retrieved_item.memory
        print(f"Memory: {memory.get('memoryId')}")
        if 'metadata' in memory:
            print(f"Metadata: {memory['metadata']}")

# Alternative: Use convenience method for ChatPostProcessor with simple parameters
for event in stream_client.retrieve_memory_stream_chat(
    message="your search query",
    space_ids=[space_id] if space_id else None,
    requested_size=5,
    fetch_memory=True,
    format="ndjson",
    pp_llm_id="your-llm-uuid",
    pp_reranker_id="your-reranker-uuid",
    pp_relevance_threshold=0.5,
    pp_max_results=10
):
    if event.abstract_reply:
        print(f"Abstract: {event.abstract_reply.text}")
```

For comprehensive examples, see the `samples` directory:
- `apikey_sample.py` - API key CRUD operations
- `streaming_sample.py` - Memory retrieval with streaming
- `reproduce_issue_71.py` - Memory creation with metadata

## Documentation for API Endpoints

All URIs are relative to *http://localhost:8080*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*APIKeysApi* | [**create_api_key**](docs/APIKeysApi.md#create_api_key) | **POST** /v1/apikeys | Create a new API key
*APIKeysApi* | [**delete_api_key**](docs/APIKeysApi.md#delete_api_key) | **DELETE** /v1/apikeys/{id} | Delete an API key
*APIKeysApi* | [**list_api_keys**](docs/APIKeysApi.md#list_api_keys) | **GET** /v1/apikeys | List API keys
*APIKeysApi* | [**update_api_key**](docs/APIKeysApi.md#update_api_key) | **PUT** /v1/apikeys/{id} | Update an API key
*EmbeddersApi* | [**create_embedder**](docs/EmbeddersApi.md#create_embedder) | **POST** /v1/embedders | Create a new embedder
*EmbeddersApi* | [**delete_embedder**](docs/EmbeddersApi.md#delete_embedder) | **DELETE** /v1/embedders/{id} | Delete an embedder
*EmbeddersApi* | [**get_embedder**](docs/EmbeddersApi.md#get_embedder) | **GET** /v1/embedders/{id} | Get an embedder by ID
*EmbeddersApi* | [**list_embedders**](docs/EmbeddersApi.md#list_embedders) | **GET** /v1/embedders | List embedders
*EmbeddersApi* | [**update_embedder**](docs/EmbeddersApi.md#update_embedder) | **PUT** /v1/embedders/{id} | Update an embedder
*MemoriesApi* | [**batch_create_memory**](docs/MemoriesApi.md#batch_create_memory) | **POST** /v1/memories/batch | Create multiple memories in a batch
*MemoriesApi* | [**batch_delete_memory**](docs/MemoriesApi.md#batch_delete_memory) | **POST** /v1/memories/batch/delete | Delete multiple memories by ID
*MemoriesApi* | [**batch_get_memory**](docs/MemoriesApi.md#batch_get_memory) | **POST** /v1/memories/batch/get | Get multiple memories by ID
*MemoriesApi* | [**create_memory**](docs/MemoriesApi.md#create_memory) | **POST** /v1/memories | Create a new memory
*MemoriesApi* | [**delete_memory**](docs/MemoriesApi.md#delete_memory) | **DELETE** /v1/memories/{id} | Delete a memory
*MemoriesApi* | [**get_memory**](docs/MemoriesApi.md#get_memory) | **GET** /v1/memories/{id} | Get a memory by ID
*MemoriesApi* | [**list_memories**](docs/MemoriesApi.md#list_memories) | **GET** /v1/spaces/{spaceId}/memories | List memories in a space
*MemoriesApi* | [**retrieve_memory**](docs/MemoriesApi.md#retrieve_memory) | **GET** /v1/memories/retrieve | Stream semantic memory retrieval
*MemoriesApi* | [**retrieve_memory_advanced**](docs/MemoriesApi.md#retrieve_memory_advanced) | **POST** /v1/memories/retrieve | Advanced semantic memory retrieval with JSON
*RerankersApi* | [**create_reranker**](docs/RerankersApi.md#create_reranker) | **POST** /v1/rerankers | Create a new reranker
*RerankersApi* | [**delete_reranker**](docs/RerankersApi.md#delete_reranker) | **DELETE** /v1/rerankers/{id} | Delete a reranker
*RerankersApi* | [**get_reranker**](docs/RerankersApi.md#get_reranker) | **GET** /v1/rerankers/{id} | Get a reranker by ID
*RerankersApi* | [**list_rerankers**](docs/RerankersApi.md#list_rerankers) | **GET** /v1/rerankers | List rerankers
*RerankersApi* | [**update_reranker**](docs/RerankersApi.md#update_reranker) | **PUT** /v1/rerankers/{id} | Update a reranker
*SpacesApi* | [**create_space**](docs/SpacesApi.md#create_space) | **POST** /v1/spaces | Create a new Space
*SpacesApi* | [**delete_space**](docs/SpacesApi.md#delete_space) | **DELETE** /v1/spaces/{id} | Delete a space
*SpacesApi* | [**get_space**](docs/SpacesApi.md#get_space) | **GET** /v1/spaces/{id} | Get a space by ID
*SpacesApi* | [**list_spaces**](docs/SpacesApi.md#list_spaces) | **GET** /v1/spaces | List spaces
*SpacesApi* | [**update_space**](docs/SpacesApi.md#update_space) | **PUT** /v1/spaces/{id} | Update a space
*SystemApi* | [**initialize_system**](docs/SystemApi.md#initialize_system) | **POST** /v1/system/init | Initialize the system
*UsersApi* | [**get_user**](docs/UsersApi.md#get_user) | **GET** /v1/users/{id} | Get a user by ID


## Documentation For Models

 - [AbstractReply](docs/AbstractReply.md)
 - **[ApiKeyResponse](docs/ApiKeyResponse.md)** - API key metadata and information
 - **[BatchMemoryCreationRequest](docs/BatchMemoryCreationRequest.md)** - Request for creating multiple memories
 - **[BatchMemoryDeletionRequest](docs/BatchMemoryDeletionRequest.md)** - Request for deleting multiple memories
 - **[BatchMemoryRetrievalRequest](docs/BatchMemoryRetrievalRequest.md)** - Request for retrieving multiple memories
 - [BinaryContent](docs/BinaryContent.md)
 - [ChunkReference](docs/ChunkReference.md)
 - [ChunkingConfiguration](docs/ChunkingConfiguration.md)
 - [ContextItem](docs/ContextItem.md)
 - **[CreateApiKeyRequest](docs/CreateApiKeyRequest.md)** - Request for creating a new API key
 - **[CreateApiKeyResponse](docs/CreateApiKeyResponse.md)** - Response containing new API key details
 - [DistributionType](docs/DistributionType.md)
 - **[EmbedderCreationRequest](docs/EmbedderCreationRequest.md)** - Request for creating a new embedder
 - **[EmbedderResponse](docs/EmbedderResponse.md)** - Embedder configuration and metadata
 - [EmbedderWeight](docs/EmbedderWeight.md)
 - [GoodMemStatus](docs/GoodMemStatus.md)
 - [LengthMeasurement](docs/LengthMeasurement.md)
 - **[ListApiKeysResponse](docs/ListApiKeysResponse.md)** - Response containing list of API keys
 - **[ListEmbeddersResponse](docs/ListEmbeddersResponse.md)** - Response containing list of embedders
 - [ListRerankersResponse](docs/ListRerankersResponse.md)
 - **[ListSpacesResponse](docs/ListSpacesResponse.md)** - Response containing list of spaces
 - **[Memory](docs/Memory.md)** - Memory object with content and metadata
 - [MemoryChunkResponse](docs/MemoryChunkResponse.md)
 - **[MemoryCreationRequest](docs/MemoryCreationRequest.md)** - Request for creating a new memory
 - **[MemoryListResponse](docs/MemoryListResponse.md)** - Response containing list of memories
 - **[Modality](docs/Modality.md)** - Enumeration of supported modalities (TEXT, IMAGE, etc.)
 - [PostProcessor](docs/PostProcessor.md)
 - **[ProviderType](docs/ProviderType.md)** - Enumeration of embedding providers (OPENAI, etc.)
 - [RecursiveChunkingConfiguration](docs/RecursiveChunkingConfiguration.md)
 - [RerankerCreationRequest](docs/RerankerCreationRequest.md)
 - [RerankerResponse](docs/RerankerResponse.md)
 - [ResultSetBoundary](docs/ResultSetBoundary.md)
 - [RetrieveMemoryEvent](docs/RetrieveMemoryEvent.md)
 - [RetrieveMemoryRequest](docs/RetrieveMemoryRequest.md)
 - [RetrievedItem](docs/RetrievedItem.md)
 - [SentenceChunkingConfiguration](docs/SentenceChunkingConfiguration.md)
 - [SeparatorKeepStrategy](docs/SeparatorKeepStrategy.md)
 - **[Space](docs/Space.md)** - Space object for organizing memories
 - **[SpaceCreationRequest](docs/SpaceCreationRequest.md)** - Request for creating a new space
 - **[SpaceEmbedder](docs/SpaceEmbedder.md)** - Associates an embedder with a space, including retrieval configuration
 - **[SpaceEmbedderConfig](docs/SpaceEmbedderConfig.md)** - Configuration for associating an embedder with a space
 - [SpaceKey](docs/SpaceKey.md)
 - **[SystemInitResponse](docs/SystemInitResponse.md)** - Response from system initialization
 - **[UpdateApiKeyRequest](docs/UpdateApiKeyRequest.md)** - Request for updating an API key
 - **[UpdateEmbedderRequest](docs/UpdateEmbedderRequest.md)** - Request for updating an embedder
 - [UpdateRerankerRequest](docs/UpdateRerankerRequest.md)
 - **[UpdateSpaceRequest](docs/UpdateSpaceRequest.md)** - Request for updating a space
 - **[UserResponse](docs/UserResponse.md)** - User account information


<a id="documentation-for-authorization"></a>
## Documentation For Authorization


Authentication schemes defined for the API:
<a id="BearerAuth"></a>
### BearerAuth

- **Type**: Bearer authentication

<a id="ApiKeyAuth"></a>
### ApiKeyAuth

- **Type**: API key
- **API key parameter name**: x-api-key
- **Location**: HTTP header



## Contact & Support

For questions or issues with the Python client, please visit:
- GitHub repository: https://github.com/PAIR-Systems-Inc/goodmem
- PyPI package: https://pypi.org/project/goodmem-client/


## Author

support@goodmem.io


