vibe.assistant.services.vector_store_manager

VectorStoreManager - manages OpenAI vector stores for reference document grounding.

This service handles: - Creating vector stores for template reference documents - Uploading PDF files to vector stores - Caching vector store IDs to avoid redundant uploads - Cache invalidation when source files change

Vector stores are keyed by template_id + hash of file contents, allowing automatic invalidation when reference documents are modified.

OpenAIClientProtocol

Protocol for OpenAI client to enable testing without real API.

vector_stores 

vector_stores: VectorStoresProtocol

Access the vector_stores namespace for creating and managing stores.

VectorStoresProtocol

Protocol for vector_stores namespace.

files 

files: VectorStoreFilesProtocol

Access the files namespace for uploading documents.

create 

create(*, name: str) -> VectorStoreProtocol

Create a new vector store with the given name.

retrieve 

retrieve(vector_store_id: str) -> VectorStoreProtocol

Retrieve an existing vector store by ID.

VectorStoreProtocol

Protocol for a vector store object.

id 

id: str

Unique identifier for this vector store.

VectorStoreFilesProtocol

Protocol for vector_stores.files namespace.

upload_and_poll 

upload_and_poll(*, vector_store_id: str, file: object) -> None

Upload file to vector store and wait for processing to complete.

VectorStoreManager

Manages vector store creation, caching, and file uploads.

Vector stores are keyed by template_id + hash of file contents, allowing automatic invalidation when reference documents change.

The manager uses a two-level cache: 1. In-memory cache for fast repeated lookups within a process 2. Persistent file-based cache for cross-process/restart persistence

__init__ 

__init__(client: OpenAIClientProtocol, cache_dir: Path) -> None

Initialize the vector store manager.

Parameters:
  • client (OpenAIClientProtocol) –

    OpenAI client instance (or protocol-compatible mock)

  • cache_dir (Path) –

    Directory for persistent cache storage

get_or_create_store 

get_or_create_store(template_id: str, file_paths: list[Path]) -> str

Get existing vector store or create new one for template files.

This method: 1. Computes a cache key from template_id and file content hashes 2. Checks in-memory cache for existing store ID 3. Checks persistent cache for existing store ID 4. Validates the store still exists in OpenAI 5. Creates new store if needed

Parameters:
  • template_id (str) –

    Unique identifier for the template

  • file_paths (list[Path]) –

    List of PDF file paths to include in the store
Returns:
  • str –

    vector_store_id for use in file_search tool
Raises:
  • FileNotFoundError –

    If any of the file_paths don't exist

  • APIError –

    If OpenAI API call fails

clear_cache 

clear_cache() -> int

Clear all cached vector store mappings.

Note: This does NOT delete the vector stores from OpenAI, only the local cache. Useful for forcing re-creation.

Returns:
  • int –

    Number of cache entries cleared