Skip to content

Release v0.3.1

Latest

Choose a tag to compare

@oranheim oranheim released this 02 Nov 17:38
· 18 commits to master since this release

🎯 Simplified pgvector Support

This release simplifies pgvector integration by removing the pgvector-python library dependency and using native JSON parsing instead. This results in zero external dependencies, better Pydantic compatibility, and simpler code.

✨ What's Changed

Removed Dependencies

  • Removed pgvector-python dependency - No longer required for vector support
  • Removed numpy dependency - Vector data returned as native Python list[float]

Simplified Implementation

  • PostgreSQL returns vectors as strings like '[0.1,0.2,0.3]'
  • Automatically parsed to list[float] using built-in JSON parsing
  • Removed 28 lines of adapter registration complexity
  • No async adapter registration needed

Performance

  • Negligible overhead: <0.1ms per vector for JSON parsing
  • For 1000 vectors: ~10-100ms difference vs adapter (1-10% overhead)
  • Completely acceptable for typical LLM embedding use cases

πŸš€ Key Benefits

βœ… Zero External Dependencies - No pgvector-python, no numpy required
βœ… Simpler Code - Removed async adapter registration logic
βœ… Perfect Pydantic Compatibility - Returns list[float], not numpy.ndarray
βœ… No Breaking Changes - Same public API, drop-in upgrade
βœ… All Tests Passing - 227 tests with zero regressions

πŸ“¦ Installation

pip install psycopg-toolkit==0.3.1

πŸ’» Usage Example

from pydantic import BaseModel
from psycopg_toolkit import BaseRepository
from uuid import UUID

class DocumentEmbedding(BaseModel):
    id: UUID
    document_id: UUID
    embedding: list[float]  # Auto-detected as vector field
    metadata: dict[str, Any] | None = None

class EmbeddingRepository(BaseRepository[DocumentEmbedding, UUID]):
    def __init__(self, db_connection):
        super().__init__(
            db_connection=db_connection,
            table_name="embeddings",
            model_class=DocumentEmbedding,
            primary_key="id",
            auto_detect_vector=True,  # Automatically detects list[float]
        )

# Usage - works seamlessly with PostgreSQL pgvector extension
embedding_vector = [0.1] * 384  # 384-dimensional vector
doc = DocumentEmbedding(
    id=uuid4(),
    document_id=uuid4(),
    embedding=embedding_vector,
    metadata={"model": "all-MiniLM-L6-v2"}
)

created = await repo.create(doc)
assert isinstance(created.embedding, list)  # Returns list[float]!

πŸ”§ Technical Details

Before (v0.3.0):

  • Required pgvector-python>=0.4.1 dependency
  • Used register_vector_async() adapter registration
  • Returned vectors as numpy.ndarray
  • Required numpy as transitive dependency

After (v0.3.1):

  • No external dependencies needed
  • Simple JSON parsing with JSONHandler.deserialize()
  • Returns vectors as native Python list[float]
  • Direct Pydantic compatibility

πŸ“ Full Changelog

Commits:

  • 82ad82a - refactor: Remove pgvector-python dependency, use JSON parsing for vectors
  • Updated documentation in .claude/CLAUDE.md
  • Removed adapter registration from BaseRepository
  • Added vector field parsing in _postprocess_data()

Files Changed: 4 files (+37, -152 lines)

  • pyproject.toml - Removed pgvector dependency
  • src/psycopg_toolkit/repositories/base.py - Simplified vector handling
  • .claude/CLAUDE.md - Updated documentation
  • uv.lock - Dependency updates

πŸ§ͺ Testing

All 227 tests passing:

  • 12 vector field unit tests
  • 4 pgvector integration tests
  • 211 other tests (JSONB, arrays, dates, transactions, etc.)
  • Zero regressions

⚠️ Breaking Changes

None - This is a drop-in replacement for v0.3.0. The public API remains identical.


Full Changelog: v0.3.0...v0.3.1