minix 0.3.2__tar.gz → 0.3.3__tar.gz

{minix-0.3.2 → minix-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minix
-Version: 0.3.2
+Version: 0.3.3
 Summary: A modular Python framework for backend, AI, and data projects
 Author: AmirHossein Advari
 Author-email: amiradvari@gmail.com
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: ai
 Provides-Extra: clickhouse
 Provides-Extra: mysql
+Provides-Extra: pgvector
 Provides-Extra: postgresql
 Provides-Extra: rag
 Provides-Extra: vdb
@@ -37,6 +38,8 @@ Requires-Dist: mlflow (>=2.0) ; extra == "ai"
 Requires-Dist: numpy (>=1.24) ; extra == "ai"
 Requires-Dist: numpy (>=1.24) ; extra == "vdb"
 Requires-Dist: pdf2image (>=1.17.0) ; extra == "rag"
+Requires-Dist: pgvector (>=0.4) ; extra == "pgvector"
+Requires-Dist: psycopg[binary] (>=3.1) ; extra == "pgvector"
 Requires-Dist: psycopg[binary] (>=3.1) ; extra == "postgresql"
 Requires-Dist: psycopg[binary] (>=3.1) ; extra == "rag"
 Requires-Dist: pydantic-settings (>=2.0,<3.0)
@@ -78,10 +81,12 @@ Description-Content-Type: text/markdown
     - [Entities](#entities)
       - [SQL Entity](#sql-entity)
       - [Qdrant Entity (Vector DB)](#qdrant-entity-vector-db)
+      - [PGVector Entity (PostgreSQL vectors)](#pgvector-entity-postgresql-vectors)
       - [Redis Entity](#redis-entity)
     - [Repositories](#repositories)
       - [SQL Repository](#sql-repository)
       - [Qdrant Repository](#qdrant-repository)
+      - [PGVector Repository](#pgvector-repository)
     - [Services](#services)
     - [Controllers](#controllers)
     - [Connectors](#connectors)
@@ -112,6 +117,7 @@ Description-Content-Type: text/markdown
     - [SQL drivers](#sql-drivers)
     - [AI Capabilities](#ai-capabilities)
     - [Vector DB (Qdrant)](#vector-db-qdrant)
+    - [Vector DB (pgvector)](#vector-db-pgvector)
     - [ClickHouse Support](#clickhouse-support)
     - [Install All Extras](#install-all-extras)
   - [Registry Usage](#registry-usage)
@@ -290,6 +296,24 @@ class DocumentEntity(QdrantEntity):
         return "documents"
 ```
 
+#### PGVector Entity (PostgreSQL vectors)
+
+Requires the `pgvector` extra and a PostgreSQL server with the `vector` extension.
+
+```python
+from sqlalchemy import Text
+from sqlalchemy.orm import Mapped, mapped_column
+from minix.core.entity import PGVectorEntity
+
+class DocumentEmbeddingEntity(PGVectorEntity):
+    vector_size = 1536
+
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+```
+
+PGVector entities are SQL entities: they include `id`, `created_at` and
+`updated_at`, plus a `vector` column of type `VECTOR(vector_size)`.
+
 #### Redis Entity
 
 ```python
@@ -360,6 +384,27 @@ class DocumentRepository(QdrantRepository[DocumentEntity]):
 - `query(entity, top_k)` - Similarity search
 - `delete(entity_ids)` - Delete vectors
 
+#### PGVector Repository
+
+```python
+from minix.core.repository import PGVectorRepository
+
+class DocumentEmbeddingRepository(PGVectorRepository[DocumentEmbeddingEntity]):
+    def get_distance(self) -> str:
+        return 'Cosine'  # or 'Euclid', 'Dot', 'Manhattan'
+```
+
+It extends `SqlRepository` (all SQL methods above, `sql_transaction()`
+included) and uses the registered `SqlConnector`, which must point at PostgreSQL.
+
+**Additional methods:**
+- `create_extension()` - Run `CREATE EXTENSION IF NOT EXISTS vector`
+- `search(vector, top_k, max_distance=None, **kwargs)` - Nearest neighbours, closest first; `kwargs` filter like `get_by`
+- `search_with_distance(vector, top_k, max_distance=None, **kwargs)` - Same, as `(entity, distance)` pairs
+
+`PGVectorService` exposes the same `search` / `search_with_distance` methods,
+plus `get_knn(entity, top_k)`, on top of `SqlService`.
+
 ### Services
 
 Services contain business logic:
@@ -940,6 +985,12 @@ pip install "minix[ai]"
 pip install "minix[vdb]"
 ```
 
+### Vector DB (pgvector)
+
+```bash
+pip install "minix[pgvector]"
+```
+
 ### ClickHouse Support
 
 ```bash
@@ -958,7 +1009,7 @@ pip install "minix[rag]"
 ### Install All Extras
 
 ```bash
-pip install "minix[postgresql,mysql,ai,vdb,clickhouse,rag]"
+pip install "minix[postgresql,pgvector,mysql,ai,vdb,clickhouse,rag]"
 ```
 
 ---

{minix-0.3.2 → minix-0.3.3}/README.md

@@ -25,10 +25,12 @@
     - [Entities](#entities)
       - [SQL Entity](#sql-entity)
       - [Qdrant Entity (Vector DB)](#qdrant-entity-vector-db)
+      - [PGVector Entity (PostgreSQL vectors)](#pgvector-entity-postgresql-vectors)
       - [Redis Entity](#redis-entity)
     - [Repositories](#repositories)
       - [SQL Repository](#sql-repository)
       - [Qdrant Repository](#qdrant-repository)
+      - [PGVector Repository](#pgvector-repository)
     - [Services](#services)
     - [Controllers](#controllers)
     - [Connectors](#connectors)
@@ -59,6 +61,7 @@
     - [SQL drivers](#sql-drivers)
     - [AI Capabilities](#ai-capabilities)
     - [Vector DB (Qdrant)](#vector-db-qdrant)
+    - [Vector DB (pgvector)](#vector-db-pgvector)
     - [ClickHouse Support](#clickhouse-support)
     - [Install All Extras](#install-all-extras)
   - [Registry Usage](#registry-usage)
@@ -237,6 +240,24 @@ class DocumentEntity(QdrantEntity):
         return "documents"
 ```
 
+#### PGVector Entity (PostgreSQL vectors)
+
+Requires the `pgvector` extra and a PostgreSQL server with the `vector` extension.
+
+```python
+from sqlalchemy import Text
+from sqlalchemy.orm import Mapped, mapped_column
+from minix.core.entity import PGVectorEntity
+
+class DocumentEmbeddingEntity(PGVectorEntity):
+    vector_size = 1536
+
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+```
+
+PGVector entities are SQL entities: they include `id`, `created_at` and
+`updated_at`, plus a `vector` column of type `VECTOR(vector_size)`.
+
 #### Redis Entity
 
 ```python
@@ -307,6 +328,27 @@ class DocumentRepository(QdrantRepository[DocumentEntity]):
 - `query(entity, top_k)` - Similarity search
 - `delete(entity_ids)` - Delete vectors
 
+#### PGVector Repository
+
+```python
+from minix.core.repository import PGVectorRepository
+
+class DocumentEmbeddingRepository(PGVectorRepository[DocumentEmbeddingEntity]):
+    def get_distance(self) -> str:
+        return 'Cosine'  # or 'Euclid', 'Dot', 'Manhattan'
+```
+
+It extends `SqlRepository` (all SQL methods above, `sql_transaction()`
+included) and uses the registered `SqlConnector`, which must point at PostgreSQL.
+
+**Additional methods:**
+- `create_extension()` - Run `CREATE EXTENSION IF NOT EXISTS vector`
+- `search(vector, top_k, max_distance=None, **kwargs)` - Nearest neighbours, closest first; `kwargs` filter like `get_by`
+- `search_with_distance(vector, top_k, max_distance=None, **kwargs)` - Same, as `(entity, distance)` pairs
+
+`PGVectorService` exposes the same `search` / `search_with_distance` methods,
+plus `get_knn(entity, top_k)`, on top of `SqlService`.
+
 ### Services
 
 Services contain business logic:
@@ -887,6 +929,12 @@ pip install "minix[ai]"
 pip install "minix[vdb]"
 ```
 
+### Vector DB (pgvector)
+
+```bash
+pip install "minix[pgvector]"
+```
+
 ### ClickHouse Support
 
 ```bash
@@ -905,7 +953,7 @@ pip install "minix[rag]"
 ### Install All Extras
 
 ```bash
-pip install "minix[postgresql,mysql,ai,vdb,clickhouse,rag]"
+pip install "minix[postgresql,pgvector,mysql,ai,vdb,clickhouse,rag]"
 ```
 
 ---

{minix-0.3.2 → minix-0.3.3}/minix/core/cli/commands/init.py

@@ -179,7 +179,7 @@ def init(
         "--extras",
         help=(
             "Comma-separated Minix PyPI extras for Docker and compose "
-            "(postgresql, mysql, vdb, clickhouse, ai, rag). "
+            "(postgresql, pgvector, mysql, vdb, clickhouse, ai, rag). "
             "SQL extras are also set from --db-driver / the SQL prompt. "
             "Default for non-SQL extras: infer from this environment."
         ),

{minix-0.3.2 → minix-0.3.3}/minix/core/cli/commands/init_scaffold.py

@@ -6,12 +6,13 @@ import importlib.util
 import re
 from typing import Iterable
 
-VALID_MINIX_EXTRAS = frozenset({"postgresql", "mysql", "vdb", "clickhouse", "ai", "rag"})
-_EXTRA_ORDER = ("postgresql", "mysql", "vdb", "clickhouse", "ai", "rag")
+VALID_MINIX_EXTRAS = frozenset({"postgresql", "pgvector", "mysql", "vdb", "clickhouse", "ai", "rag"})
+_EXTRA_ORDER = ("postgresql", "pgvector", "mysql", "vdb", "clickhouse", "ai", "rag")
 # Template feature blocks may use shorter aliases (e.g. BEGIN_POSTGRES).
 _FEATURE_TO_PIP_EXTRA = {
     "postgresql": "postgresql",
     "postgres": "postgresql",
+    "pgvector": "pgvector",
     "mysql": "mysql",
     "vdb": "vdb",
     "clickhouse": "clickhouse",
@@ -30,6 +31,8 @@ def detect_installed_minix_extras() -> set[str]:
     extras: set[str] = set()
     if importlib.util.find_spec("psycopg") is not None:
         extras.add("postgresql")
+    if importlib.util.find_spec("pgvector") is not None:
+        extras.add("pgvector")
     if importlib.util.find_spec("pymysql") is not None:
         extras.add("mysql")
     if importlib.util.find_spec("qdrant_client") is not None:

{minix-0.3.2 → minix-0.3.3}/minix/core/entity/__init__.py

@@ -1,4 +1,9 @@
+import importlib.util
+
 from .entity import Entity
 from .sql_entity import SqlEntity
 from .redis_entity import RedisEntity
 from .qdrant_entity import QdrantEntity
+
+if importlib.util.find_spec('pgvector'):
+    from .pgvector_entity import PGVectorEntity

minix-0.3.3/minix/core/entity/pgvector_entity.py

@@ -0,0 +1,22 @@
+from typing import ClassVar, List
+
+from pgvector.sqlalchemy import VECTOR
+from sqlalchemy.orm import Mapped, mapped_column, declared_attr
+
+from minix.core.entity import SqlEntity
+
+
+class PGVectorEntity(SqlEntity):
+    """SQL entity stored in PostgreSQL with a pgvector ``vector`` column.
+
+    Subclasses set ``vector_size`` to the embedding dimension; it becomes the
+    column type ``VECTOR(<vector_size>)``. ``None`` leaves the dimension
+    unbounded, which pgvector accepts but cannot index.
+    """
+    __abstract__ = True
+
+    vector_size: ClassVar[int | None] = None
+
+    @declared_attr
+    def vector(cls) -> Mapped[List[float]]:
+        return mapped_column(VECTOR(cls.vector_size), nullable=False)

{minix-0.3.2 → minix-0.3.3}/minix/core/repository/__init__.py

@@ -4,4 +4,6 @@ from .redis import RedisRepository
 import importlib.util
 if importlib.util.find_spec('qdrant_client'):
     from minix.core.repository.qdrant import QdrantRepository
+if importlib.util.find_spec('pgvector'):
+    from minix.core.repository.pgvector import PGVectorRepository
 

minix-0.3.3/minix/core/repository/pgvector/__init__.py

@@ -0,0 +1 @@
+from .pgvector_repository import PGVectorRepository

minix-0.3.3/minix/core/repository/pgvector/pgvector_repository.py

@@ -0,0 +1,64 @@
+from typing import TypeVar, Type, List, Tuple
+
+from sqlalchemy import text
+from sqlalchemy.sql.elements import ColumnElement
+
+from minix.core.entity import PGVectorEntity
+from minix.core.connectors.sql_connector import SqlConnector
+from minix.core.repository import SqlRepository
+
+T = TypeVar('T', bound=PGVectorEntity)
+
+
+class PGVectorRepository(SqlRepository[T]):
+    # Distance names follow Qdrant's, mapped to pgvector's comparator methods.
+    DISTANCES = {
+        'Cosine': 'cosine_distance',
+        'Euclid': 'l2_distance',
+        'Dot': 'max_inner_product',
+        'Manhattan': 'l1_distance',
+    }
+
+    def __init__(self, entity: Type[T], sql_connector: SqlConnector):
+        super().__init__(entity, sql_connector)
+        self.entity = entity
+
+    def create_extension(self) -> None:
+        with self.get_session() as session:
+            session.execute(text('CREATE EXTENSION IF NOT EXISTS vector'))
+            session.commit()
+
+    def get_distance(self) -> str:
+        return 'Cosine'
+
+    def distance_to(self, vector: List[float]) -> ColumnElement[float]:
+        distance = self.get_distance()
+        if distance not in self.DISTANCES:
+            raise ValueError(f'Distance not supported: {distance!r}')
+        return getattr(self.entity.vector, self.DISTANCES[distance])(vector)
+
+    def search_with_distance(
+            self,
+            vector: List[float],
+            top_k: int = 10,
+            max_distance: float | None = None,
+            **kwargs
+    ) -> List[Tuple[T, float]]:
+        # `max_distance` bounds the pgvector distance; for 'Dot' that is the
+        # negative inner product.
+        distance = self.distance_to(vector)
+        with self.get_session() as session:
+            query = session.query(self.entity, distance.label('distance')).filter_by(**kwargs)
+            if max_distance is not None:
+                query = query.filter(distance <= max_distance)
+            rows = query.order_by(distance).limit(top_k).all()
+        return [(entity, value) for entity, value in rows]
+
+    def search(
+            self,
+            vector: List[float],
+            top_k: int = 10,
+            max_distance: float | None = None,
+            **kwargs
+    ) -> List[T]:
+        return [entity for entity, _ in self.search_with_distance(vector, top_k, max_distance, **kwargs)]

{minix-0.3.2 → minix-0.3.3}/minix/core/service/__init__.py

@@ -8,4 +8,6 @@ from minix.core.service.redis.redis_service import RedisService
 
 if importlib.util.find_spec('qdrant_client'):
     from minix.core.service.qdrant.qdrant_service import QdrantService
+if importlib.util.find_spec('pgvector'):
+    from minix.core.service.pgvector.pgvector_service import PGVectorService
 

minix-0.3.3/minix/core/service/pgvector/__init__.py

@@ -0,0 +1 @@
+from .pgvector_service import PGVectorService

minix-0.3.3/minix/core/service/pgvector/pgvector_service.py

@@ -0,0 +1,37 @@
+from typing import TypeVar, List, Tuple
+
+from minix.core.entity import PGVectorEntity
+from minix.core.repository.pgvector.pgvector_repository import PGVectorRepository
+from minix.core.service import SqlService
+
+T = TypeVar('T', bound=PGVectorEntity)
+
+
+class PGVectorService(SqlService[T]):
+    def __init__(self, repository: PGVectorRepository[T]):
+        super().__init__(repository)
+        self.repository = repository
+
+    def get_repository(self) -> PGVectorRepository[T]:
+        return self.repository
+
+    def get_knn(self, entity: T, top_k: int = 10) -> List[T]:
+        return self.get_repository().search(entity.vector, top_k)
+
+    def search(
+            self,
+            vector: List[float],
+            top_k: int = 10,
+            max_distance: float | None = None,
+            **kwargs
+    ) -> List[T]:
+        return self.get_repository().search(vector, top_k, max_distance, **kwargs)
+
+    def search_with_distance(
+            self,
+            vector: List[float],
+            top_k: int = 10,
+            max_distance: float | None = None,
+            **kwargs
+    ) -> List[Tuple[T, float]]:
+        return self.get_repository().search_with_distance(vector, top_k, max_distance, **kwargs)

{minix-0.3.2 → minix-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "minix"
-version = "0.3.2"
+version = "0.3.3"
 description = "A modular Python framework for backend, AI, and data projects"
 authors = [
     { name = "AmirHossein Advari", email = "amiradvari@gmail.com" }
@@ -27,6 +27,10 @@ dependencies = [
 postgresql = [
     "psycopg[binary]>=3.1",
 ]
+pgvector = [
+    "psycopg[binary]>=3.1",
+    "pgvector>=0.4",
+]
 mysql = [
     "pymysql>=1.1.1",
 ]