post-graph 0.1.2__tar.gz → 0.1.3__tar.gz

{post_graph-0.1.2 → post_graph-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: post-graph
-Version: 0.1.2
+Version: 0.1.3
 Summary: High-performance PostgreSQL-backed graph database library supporting multi-tenant realms, schema-per-realm, shadow auditing, and append-only data history.
 Project-URL: Homepage, https://github.com/crajah/post-graph
 Project-URL: Repository, https://github.com/crajah/post-graph

post_graph-0.1.3/demo_vector.py

@@ -0,0 +1,73 @@
+"""Demo script verifying pgvector support and vector similarity search in post-graph."""
+import asyncio
+import os
+from post_graph import AsyncPostGraph, TableNotFoundError
+
+DB_URI = os.getenv("POSTGRES_URI", "postgresql://crajah@localhost:5432/postgres")
+
+async def main():
+    print("=" * 60)
+    print("POST-GRAPH PGVECTOR DEMO")
+    print("=" * 60)
+
+    client = AsyncPostGraph(dsn=DB_URI)
+    await client.connect()
+
+    table_name = "doc_chunks"
+    realm = "rag_demo"
+
+    table_ref = client._get_table_ref(table_name, realm)
+    audit_table_ref = client._get_table_ref(f"{table_name}_audit", realm)
+    data_table_ref = client._get_table_ref(f"{table_name}_data", realm)
+
+    await client._execute(f"DROP TABLE IF EXISTS {data_table_ref} CASCADE;")
+    await client._execute(f"DROP TABLE IF EXISTS {audit_table_ref} CASCADE;")
+    await client._execute(f"DROP TABLE IF EXISTS {table_ref} CASCADE;")
+
+    print("\n[+] Creating vertex table 'doc_chunks' with vector_dim=4...")
+    try:
+        await client.create_vertex_table(table_name, realm=realm, vector_dim=4)
+        print("    [OK] Table created successfully with vector_dim=4")
+    except Exception as e:
+        print(f"    [SKIP] pgvector extension not installed in Postgres: {e}")
+        await client.close()
+        return
+
+    print("\n[+] Inserting document chunk vertices with 4D embeddings...")
+    v1 = await client.add_vertex(
+        table_name, realm=realm,
+        payload={"text": "PostgreSQL is a relational database system."},
+        embedding=[1.0, 0.0, 0.0, 0.0]
+    )
+    print(f"    Inserted V1 ID={v1.id}, embedding={v1.embedding}")
+
+    v2 = await client.add_vertex(
+        table_name, realm=realm,
+        payload={"text": "Post-graph enables graph storage on PostgreSQL."},
+        embedding=[0.9, 0.1, 0.0, 0.0]
+    )
+    print(f"    Inserted V2 ID={v2.id}, embedding={v2.embedding}")
+
+    v3 = await client.add_vertex(
+        table_name, realm=realm,
+        payload={"text": "Deep Learning models extract knowledge graphs."},
+        embedding=[0.0, 0.0, 1.0, 0.0]
+    )
+    print(f"    Inserted V3 ID={v3.id}, embedding={v3.embedding}")
+
+    print("\n[+] Performing Cosine Vector Similarity Search for query [1.0, 0.05, 0.0, 0.0]...")
+    query_vec = [1.0, 0.05, 0.0, 0.0]
+    results = await client.vector_search(table_name, realm=realm, query_vector=query_vec, top_k=3, distance_metric="cosine")
+
+    for rank, (vertex, distance) in enumerate(results, 1):
+        print(f"    Rank {rank}: ID={vertex.id}, Cosine Distance={distance:.4f}, Text='{vertex.payload['text']}'")
+
+    print("\n[+] Cleaning up demo table...")
+    await client._execute(f"DROP TABLE IF EXISTS {data_table_ref} CASCADE;")
+    await client._execute(f"DROP TABLE IF EXISTS {audit_table_ref} CASCADE;")
+    await client._execute(f"DROP TABLE IF EXISTS {table_ref} CASCADE;")
+    await client.close()
+    print("[+] Done!")
+
+if __name__ == "__main__":
+    asyncio.run(main())

{post_graph-0.1.2 → post_graph-0.1.3}/post_graph/__init__.py

@@ -10,7 +10,7 @@ from post_graph.models import Vertex, Edge, TraversalStep
 from post_graph.client_asyncpg import AsyncPostGraph
 from post_graph.client_sqlalchemy import SQLAlchemyPostGraph
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
     "__version__",

{post_graph-0.1.2 → post_graph-0.1.3}/post_graph/client_asyncpg.py

@@ -129,7 +129,12 @@ class AsyncPostGraph:
             row = await self._fetchrow(query, table_name)
         return row is not None
 
-    async def create_vertex_table(self, table_name: str, realm: Optional[str] = None):
+    async def create_vertex_table(
+        self,
+        table_name: str,
+        realm: Optional[str] = None,
+        vector_dim: Optional[int] = None
+    ):
         """Create a new vertex table and its associated shadow audit table, indexes, and triggers."""
         self._validate_identifier(table_name)
         if self.schema_per_realm:
@@ -212,6 +217,14 @@ class AsyncPostGraph:
         await self._execute(query)
         await self._execute(f"ALTER TABLE {table_ref} ADD COLUMN IF NOT EXISTS fqid TEXT GENERATED ALWAYS AS (realm || '/' || '{table_name}' || '/' || id::text) STORED;")
 
+        if vector_dim and vector_dim > 0:
+            try:
+                await self._execute("CREATE EXTENSION IF NOT EXISTS vector;")
+                await self._execute(f"ALTER TABLE {table_ref} ADD COLUMN IF NOT EXISTS embedding vector({vector_dim});")
+                await self._execute(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_embedding" ON {table_ref} USING hnsw (embedding vector_cosine_ops);')
+            except Exception as e:
+                raise PostGraphError(f"Failed to initialize pgvector extension or embedding column for table '{table_name}': {e}")
+
         # 2. Create shadow audit table
         audit_query = f"""
         CREATE TABLE IF NOT EXISTS {audit_table_ref} (
@@ -417,12 +430,14 @@ class AsyncPostGraph:
         realm: str,
         vertex_id: Optional[Union[str, int]] = None,
         payload: Optional[Dict[str, Any]] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> Vertex:
         """Add a new vertex. Raises TableExistsError if it already exists."""
         self._validate_identifier(table_name)
         payload_json = json.dumps(payload or {})
         table_ref = self._get_table_ref(table_name, realm)
+        vec_str = f"[{','.join(str(x) for x in embedding)}]" if embedding else None
 
         async def _op(conn):
             nonlocal vertex_id
@@ -435,17 +450,36 @@ class AsyncPostGraph:
 
             v_id_str = str(v_id_int)
 
-            query = f"""
-            INSERT INTO {table_ref} (realm, id, payload)
-            VALUES ($1, $2, $3::jsonb)
-            RETURNING realm, id, fqid, payload, created_at, updated_at
-            """
-            try:
+            has_emb = False
+            if vec_str:
+                if self.schema_per_realm:
+                    has_emb = await conn.fetchval("SELECT 1 FROM information_schema.columns WHERE table_schema = $1 AND table_name = $2 AND column_name = 'embedding'", realm, table_name) is not None
+                else:
+                    has_emb = await conn.fetchval("SELECT 1 FROM information_schema.columns WHERE table_name = $1 AND column_name = 'embedding'", table_name) is not None
+
+            if vec_str and has_emb:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload, embedding)
+                VALUES ($1, $2, $3::jsonb, $4::vector)
+                RETURNING realm, id, fqid, payload, created_at, updated_at, embedding::text AS embedding_text
+                """
+                row = await conn.fetchrow(query, realm, v_id_int, payload_json, vec_str)
+            else:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload)
+                VALUES ($1, $2, $3::jsonb)
+                RETURNING realm, id, fqid, payload, created_at, updated_at
+                """
                 row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+
+            try:
                 if vertex_id is not None:
                     await conn.execute(
                         f"SELECT setval(pg_get_serial_sequence('{table_ref_pg}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM {table_ref}))"
                     )
+                emb = None
+                if 'embedding_text' in row and row['embedding_text']:
+                    emb = [float(x) for x in row['embedding_text'].strip('[]').split(',') if x.strip()]
                 return Vertex(
                     realm=row['realm'],
                     id=str(row['id']),
@@ -454,6 +488,7 @@ class AsyncPostGraph:
                     created_at=row['created_at'],
                     updated_at=row['updated_at'],
                     table_name=table_name,
+                    embedding=emb,
                     _client=self
                 )
             except asyncpg.UniqueViolationError:
@@ -471,12 +506,14 @@ class AsyncPostGraph:
         realm: str,
         vertex_id: Optional[Union[str, int]] = None,
         payload: Optional[Dict[str, Any]] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> Vertex:
         """Upsert a vertex (merges payload JSONB on conflict)."""
         self._validate_identifier(table_name)
         payload_json = json.dumps(payload or {})
         table_ref = self._get_table_ref(table_name, realm)
+        vec_str = f"[{','.join(str(x) for x in embedding)}]" if embedding else None
 
         async def _op(conn):
             nonlocal vertex_id
@@ -489,16 +526,38 @@ class AsyncPostGraph:
 
             v_id_str = str(v_id_int)
 
-            query = f"""
-            INSERT INTO {table_ref} (realm, id, payload)
-            VALUES ($1, $2, $3::jsonb)
-            ON CONFLICT (realm, id) DO UPDATE
-            SET payload = {table_ref}.payload || EXCLUDED.payload,
-                updated_at = CURRENT_TIMESTAMP
-            RETURNING realm, id, fqid, payload, created_at, updated_at
-            """
-            try:
+            has_emb = False
+            if vec_str:
+                if self.schema_per_realm:
+                    has_emb = await conn.fetchval("SELECT 1 FROM information_schema.columns WHERE table_schema = $1 AND table_name = $2 AND column_name = 'embedding'", realm, table_name) is not None
+                else:
+                    has_emb = await conn.fetchval("SELECT 1 FROM information_schema.columns WHERE table_name = $1 AND column_name = 'embedding'", table_name) is not None
+
+            if vec_str and has_emb:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload, embedding)
+                VALUES ($1, $2, $3::jsonb, $4::vector)
+                ON CONFLICT (realm, id) DO UPDATE
+                SET payload = {table_ref}.payload || EXCLUDED.payload,
+                    embedding = EXCLUDED.embedding,
+                    updated_at = CURRENT_TIMESTAMP
+                RETURNING realm, id, fqid, payload, created_at, updated_at, embedding::text AS embedding_text
+                """
+                row = await conn.fetchrow(query, realm, v_id_int, payload_json, vec_str)
+            else:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload)
+                VALUES ($1, $2, $3::jsonb)
+                ON CONFLICT (realm, id) DO UPDATE
+                SET payload = {table_ref}.payload || EXCLUDED.payload,
+                    updated_at = CURRENT_TIMESTAMP
+                RETURNING realm, id, fqid, payload, created_at, updated_at
+                """
                 row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+            try:
+                emb = None
+                if 'embedding_text' in row and row['embedding_text']:
+                    emb = [float(x) for x in row['embedding_text'].strip('[]').split(',') if x.strip()]
                 return Vertex(
                     realm=row['realm'],
                     id=str(row['id']),
@@ -507,6 +566,7 @@ class AsyncPostGraph:
                     created_at=row['created_at'],
                     updated_at=row['updated_at'],
                     table_name=table_name,
+                    embedding=emb,
                     _client=self
                 )
             except asyncpg.UndefinedTableError:
@@ -518,28 +578,112 @@ class AsyncPostGraph:
         """Fetch a vertex by realm and id."""
         self._validate_identifier(table_name)
         table_ref = self._get_table_ref(table_name, realm)
-        v_str = str(vertex_id)
+        v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+
+        async def _op(conn):
+            query = f"""
+            SELECT t.realm, t.id, t.fqid, t.payload, t.created_at, t.updated_at,
+                   to_jsonb(t)->>'embedding' AS embedding_text
+            FROM {table_ref} t
+            WHERE t.realm = $1 AND t.id = $2
+            """
+            try:
+                row = await conn.fetchrow(query, realm, v_id_int)
+                if not row:
+                    return None
+
+                emb = None
+                if 'embedding_text' in row and row['embedding_text']:
+                    emb = [float(x) for x in row['embedding_text'].strip('[]').split(',') if x.strip()]
+
+                return Vertex(
+                    realm=row['realm'],
+                    id=str(row['id']),
+                    fqid=row['fqid'],
+                    payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                    created_at=row['created_at'],
+                    updated_at=row['updated_at'],
+                    table_name=table_name,
+                    embedding=emb,
+                    _client=self
+                )
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                return await _op(conn)
+        else:
+            return await _op(self.connection)
+
+    async def vector_search(
+        self,
+        table_name: str,
+        realm: str,
+        query_vector: List[float],
+        top_k: int = 5,
+        distance_metric: str = "cosine"
+    ) -> List[Tuple[Vertex, float]]:
+        """Perform vector similarity search on vertex embeddings using pgvector.
+        
+        Distance metrics:
+          - 'cosine': <=> (cosine distance)
+          - 'l2': <-> (Euclidean distance)
+          - 'inner_product': <#> (negative inner product)
+        """
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        vec_str = f"[{','.join(str(x) for x in query_vector)}]"
+        
+        op = "<=>"
+        if distance_metric == "l2":
+            op = "<->"
+        elif distance_metric == "inner_product":
+            op = "<#>"
+
         query = f"""
-        SELECT realm, id, fqid, payload, created_at, updated_at 
-        FROM {table_ref} 
-        WHERE realm = $1 AND ((CASE WHEN $2 ~ '^[0-9]+$' THEN id = $2::bigint ELSE FALSE END) OR fqid = $2)
+        SELECT realm, id, fqid, payload, created_at, updated_at, embedding::text AS embedding_text,
+               (embedding {op} $2::vector) AS distance
+        FROM {table_ref}
+        WHERE realm = $1 AND embedding IS NOT NULL
+        ORDER BY embedding {op} $2::vector ASC
+        LIMIT $3
         """
-        try:
-            row = await self._fetchrow(query, realm, v_str)
-            if not row:
-                return None
-            return Vertex(
-                realm=row['realm'],
-                id=str(row['id']),
-                fqid=row['fqid'] or f"{row['realm']}/{table_name}/{row['id']}",
-                payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
-                created_at=row['created_at'],
-                updated_at=row['updated_at'],
-                table_name=table_name,
-                _client=self
-            )
-        except asyncpg.UndefinedTableError:
-            raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+
+        async def _op(conn):
+            try:
+                rows = await conn.fetch(query, realm, vec_str, top_k)
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+            except asyncpg.UndefinedColumnError:
+                logger.warning(f"Table '{table_name}' does not have a vector embedding column.")
+                return []
+
+            results = []
+            for r in rows:
+                emb = None
+                if r['embedding_text']:
+                    emb = [float(x) for x in r['embedding_text'].strip('[]').split(',') if x.strip()]
+                v = Vertex(
+                    realm=r['realm'],
+                    id=str(r['id']),
+                    fqid=r['fqid'],
+                    payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
+                    created_at=r['created_at'],
+                    updated_at=r['updated_at'],
+                    table_name=table_name,
+                    embedding=emb,
+                    _client=self
+                )
+                dist = float(r['distance'])
+                results.append((v, dist))
+            return results
+
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                return await _op(conn)
+        else:
+            return await _op(self.connection)
 
     async def delete_vertex(self, table_name: str, realm: str, vertex_id: str, user_id: Optional[str] = None) -> bool:
         """Delete a vertex. Cascading foreign keys will automatically delete referencing edges."""

{post_graph-0.1.2 → post_graph-0.1.3}/post_graph/client_sqlalchemy.py

@@ -98,7 +98,12 @@ class SQLAlchemyPostGraph:
             row = await self._fetchrow(conn, query, table_name=table_name)
         return row is not None
 
-    async def create_vertex_table(self, table_name: str, realm: Optional[str] = None):
+    async def create_vertex_table(
+        self,
+        table_name: str,
+        realm: Optional[str] = None,
+        vector_dim: Optional[int] = None
+    ):
         """Create a new vertex table and its associated shadow audit table, indexes, and triggers."""
         self._validate_identifier(table_name)
         if self.schema_per_realm:
@@ -184,6 +189,14 @@ class SQLAlchemyPostGraph:
             await conn.execute(text(query))
             await conn.execute(text(f"ALTER TABLE {table_ref} ADD COLUMN IF NOT EXISTS fqid TEXT GENERATED ALWAYS AS (realm || '/' || '{table_name}' || '/' || id::text) STORED;"))
 
+            if vector_dim and vector_dim > 0:
+                try:
+                    await conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector;"))
+                    await conn.execute(text(f"ALTER TABLE {table_ref} ADD COLUMN IF NOT EXISTS embedding vector({vector_dim});"))
+                    await conn.execute(text(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_embedding" ON {table_ref} USING hnsw (embedding vector_cosine_ops);'))
+                except Exception as e:
+                    raise PostGraphError(f"Failed to initialize pgvector extension or embedding column for table '{table_name}': {e}")
+
             # 2. Create shadow audit table
             audit_query = f"""
             CREATE TABLE IF NOT EXISTS {audit_table_ref} (
@@ -381,12 +394,14 @@ class SQLAlchemyPostGraph:
         realm: str,
         vertex_id: Optional[Union[str, int]] = None,
         payload: Optional[Dict[str, Any]] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> Vertex:
         """Add a new vertex. Raises TableExistsError if it already exists."""
         self._validate_identifier(table_name)
         payload_json = json.dumps(payload or {})
         table_ref = self._get_table_ref(table_name, realm)
+        vec_str = f"[{','.join(str(x) for x in embedding)}]" if embedding else None
 
         async def _op(conn):
             nonlocal vertex_id
@@ -399,17 +414,30 @@ class SQLAlchemyPostGraph:
 
             v_id_str = str(v_id_int)
 
-            query = f"""
-            INSERT INTO {table_ref} (realm, id, payload)
-            VALUES (:realm, :id, CAST(:payload AS JSONB))
-            RETURNING realm, id, fqid, payload, created_at, updated_at
-            """
+            if vec_str:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload, embedding)
+                VALUES (:realm, :id, CAST(:payload AS JSONB), CAST(:vec AS vector))
+                RETURNING realm, id, fqid, payload, created_at, updated_at, CAST(embedding AS TEXT) AS embedding_text
+                """
+                kwargs = {"realm": realm, "id": v_id_int, "payload": payload_json, "vec": vec_str}
+            else:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload)
+                VALUES (:realm, :id, CAST(:payload AS JSONB))
+                RETURNING realm, id, fqid, payload, created_at, updated_at
+                """
+                kwargs = {"realm": realm, "id": v_id_int, "payload": payload_json}
+
             try:
-                row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json)
+                row = await self._fetchrow(conn, query, **kwargs)
                 if vertex_id is not None:
                     await conn.execute(
                         text(f"SELECT setval(pg_get_serial_sequence('{table_ref_pg}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM {table_ref}))")
                     )
+                emb = None
+                if 'embedding_text' in row and row['embedding_text']:
+                    emb = [float(x) for x in row['embedding_text'].strip('[]').split(',') if x.strip()]
                 return Vertex(
                     realm=row['realm'],
                     id=str(row['id']),
@@ -418,6 +446,7 @@ class SQLAlchemyPostGraph:
                     created_at=row['created_at'],
                     updated_at=row['updated_at'],
                     table_name=table_name,
+                    embedding=emb,
                     _client=self
                 )
             except IntegrityError as e:
@@ -439,12 +468,14 @@ class SQLAlchemyPostGraph:
         realm: str,
         vertex_id: Optional[Union[str, int]] = None,
         payload: Optional[Dict[str, Any]] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> Vertex:
         """Upsert a vertex (merges payload JSONB on conflict)."""
         self._validate_identifier(table_name)
         payload_json = json.dumps(payload or {})
         table_ref = self._get_table_ref(table_name, realm)
+        vec_str = f"[{','.join(str(x) for x in embedding)}]" if embedding else None
 
         async def _op(conn):
             nonlocal vertex_id
@@ -457,16 +488,33 @@ class SQLAlchemyPostGraph:
 
             v_id_str = str(v_id_int)
 
-            query = f"""
-            INSERT INTO {table_ref} (realm, id, payload)
-            VALUES (:realm, :id, CAST(:payload AS JSONB))
-            ON CONFLICT (realm, id) DO UPDATE
-            SET payload = {table_ref}.payload || EXCLUDED.payload,
-                updated_at = CURRENT_TIMESTAMP
-            RETURNING realm, id, fqid, payload, created_at, updated_at
-            """
+            if vec_str:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload, embedding)
+                VALUES (:realm, :id, CAST(:payload AS JSONB), CAST(:vec AS vector))
+                ON CONFLICT (realm, id) DO UPDATE
+                SET payload = {table_ref}.payload || EXCLUDED.payload,
+                    embedding = EXCLUDED.embedding,
+                    updated_at = CURRENT_TIMESTAMP
+                RETURNING realm, id, fqid, payload, created_at, updated_at, CAST(embedding AS TEXT) AS embedding_text
+                """
+                kwargs = {"realm": realm, "id": v_id_int, "payload": payload_json, "vec": vec_str}
+            else:
+                query = f"""
+                INSERT INTO {table_ref} (realm, id, payload)
+                VALUES (:realm, :id, CAST(:payload AS JSONB))
+                ON CONFLICT (realm, id) DO UPDATE
+                SET payload = {table_ref}.payload || EXCLUDED.payload,
+                    updated_at = CURRENT_TIMESTAMP
+                RETURNING realm, id, fqid, payload, created_at, updated_at
+                """
+                kwargs = {"realm": realm, "id": v_id_int, "payload": payload_json}
+
             try:
-                row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json)
+                row = await self._fetchrow(conn, query, **kwargs)
+                emb = None
+                if 'embedding_text' in row and row['embedding_text']:
+                    emb = [float(x) for x in row['embedding_text'].strip('[]').split(',') if x.strip()]
                 return Vertex(
                     realm=row['realm'],
                     id=str(row['id']),
@@ -475,6 +523,7 @@ class SQLAlchemyPostGraph:
                     created_at=row['created_at'],
                     updated_at=row['updated_at'],
                     table_name=table_name,
+                    embedding=emb,
                     _client=self
                 )
             except ProgrammingError as e:
@@ -488,26 +537,33 @@ class SQLAlchemyPostGraph:
         """Fetch a vertex by realm and id."""
         self._validate_identifier(table_name)
         table_ref = self._get_table_ref(table_name, realm)
-        v_str = str(vertex_id)
-        query = f"""
-        SELECT realm, id, fqid, payload, created_at, updated_at 
-        FROM {table_ref} 
-        WHERE realm = :realm AND ((CASE WHEN :id ~ '^[0-9]+$' THEN id = CAST(:id AS BIGINT) ELSE FALSE END) OR fqid = :id)
-        """
-        
+        v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+
         async def _op(conn):
+            query = f"""
+            SELECT t.realm, t.id, t.fqid, t.payload, t.created_at, t.updated_at,
+                   to_jsonb(t)->>'embedding' AS embedding_text
+            FROM {table_ref} t
+            WHERE t.realm = :realm AND t.id = :id
+            """
             try:
-                row = await self._fetchrow(conn, query, realm=realm, id=v_str)
+                row = await self._fetchrow(conn, query, realm=realm, id=v_id_int)
                 if not row:
                     return None
+
+                emb = None
+                if 'embedding_text' in row and row['embedding_text']:
+                    emb = [float(x) for x in row['embedding_text'].strip('[]').split(',') if x.strip()]
+
                 return Vertex(
                     realm=row['realm'],
                     id=str(row['id']),
-                    fqid=row['fqid'] or f"{row['realm']}/{table_name}/{row['id']}",
+                    fqid=row['fqid'],
                     payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
                     created_at=row['created_at'],
                     updated_at=row['updated_at'],
                     table_name=table_name,
+                    embedding=emb,
                     _client=self
                 )
             except ProgrammingError as e:
@@ -521,6 +577,69 @@ class SQLAlchemyPostGraph:
             async with self.engine_or_connection.connect() as conn:
                 return await _op(conn)
 
+    async def vector_search(
+        self,
+        table_name: str,
+        realm: str,
+        query_vector: List[float],
+        top_k: int = 5,
+        distance_metric: str = "cosine"
+    ) -> List[Tuple[Vertex, float]]:
+        """Perform vector similarity search on vertex embeddings using pgvector."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        vec_str = f"[{','.join(str(x) for x in query_vector)}]"
+        
+        op = "<=>"
+        if distance_metric == "l2":
+            op = "<->"
+        elif distance_metric == "inner_product":
+            op = "<#>"
+
+        query = f"""
+        SELECT realm, id, fqid, payload, created_at, updated_at, CAST(embedding AS TEXT) AS embedding_text,
+               (embedding {op} CAST(:vec AS vector)) AS distance
+        FROM {table_ref}
+        WHERE realm = :realm AND embedding IS NOT NULL
+        ORDER BY embedding {op} CAST(:vec AS vector) ASC
+        LIMIT :top_k
+        """
+
+        async def _op(conn):
+            try:
+                rows = await self._fetch(conn, query, realm=realm, vec=vec_str, top_k=top_k)
+            except ProgrammingError as e:
+                if "does not exist" in str(e).lower():
+                    raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+                logger.warning(f"Vector search failed: {e}")
+                return []
+
+            results = []
+            for r in rows:
+                emb = None
+                if r['embedding_text']:
+                    emb = [float(x) for x in r['embedding_text'].strip('[]').split(',') if x.strip()]
+                v = Vertex(
+                    realm=r['realm'],
+                    id=str(r['id']),
+                    fqid=r['fqid'],
+                    payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
+                    created_at=r['created_at'],
+                    updated_at=r['updated_at'],
+                    table_name=table_name,
+                    embedding=emb,
+                    _client=self
+                )
+                dist = float(r['distance'])
+                results.append((v, dist))
+            return results
+
+        if isinstance(self.engine_or_connection, AsyncConnection):
+            return await _op(self.engine_or_connection)
+        else:
+            async with self.engine_or_connection.connect() as conn:
+                return await _op(conn)
+
     async def delete_vertex(self, table_name: str, realm: str, vertex_id: str, user_id: Optional[str] = None) -> bool:
         """Delete a vertex. Cascading foreign keys will automatically delete referencing edges."""
         self._validate_identifier(table_name)

{post_graph-0.1.2 → post_graph-0.1.3}/post_graph/models.py

@@ -12,6 +12,7 @@ class Vertex:
     updated_at: Optional[datetime] = None
     table_name: Optional[str] = None
     fqid: Optional[str] = None
+    embedding: Optional[List[float]] = None
     _client: Optional[Any] = field(default=None, repr=False, compare=False)
 
     def __post_init__(self):
@@ -27,7 +28,8 @@ class Vertex:
             "payload": self.payload,
             "created_at": self.created_at.isoformat() if self.created_at else None,
             "updated_at": self.updated_at.isoformat() if self.updated_at else None,
-            "table_name": self.table_name
+            "table_name": self.table_name,
+            "embedding": self.embedding
         }
 
     async def to(self, edge_table: str, direction: str = 'out') -> List['TraversalStep']:

{post_graph-0.1.2 → post_graph-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "post-graph"
-version = "0.1.2"
+version = "0.1.3"
 description = "High-performance PostgreSQL-backed graph database library supporting multi-tenant realms, schema-per-realm, shadow auditing, and append-only data history."
 readme = "README.md"
 requires-python = ">=3.9"