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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: post-graph
-Version: 0.1.2
+Version: 0.1.4
 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.4/demo_vector.py

@@ -0,0 +1,90 @@
+"""Demo script verifying pgvector support and vector similarity search in post-graph across main and data tables."""
+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 (MAIN & DATA TABLE SEARCH)")
+    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}_data_audit", realm)
+    audit_table_main = 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_main} 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 for main & data tables")
+    except Exception as e:
+        print(f"    [SKIP] pgvector extension not installed in Postgres: {e}")
+        await client.close()
+        return
+
+    print("\n[+] Inserting document chunk vertices into MAIN table 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}")
+
+    print("\n[+] Adding historical data records to DATA table with 4D embeddings for V1 & V2...")
+    d1 = await v1.add_data(
+        payload={"version": "v1.1", "note": "PostgreSQL 16 release notes"},
+        embedding=[0.0, 1.0, 0.0, 0.0]
+    )
+    print(f"    Added V1 DataRecord ID={d1.data_id}, embedding={d1.embedding}")
+
+    d2 = await v2.add_data(
+        payload={"version": "v1.2", "note": "Post-graph pgvector extension release"},
+        embedding=[0.0, 0.95, 0.05, 0.0]
+    )
+    print(f"    Added V2 DataRecord ID={d2.data_id}, embedding={d2.embedding}")
+
+    query_vec_main = [1.0, 0.05, 0.0, 0.0]
+    print(f"\n[+] 1. Vector Search [Scope: MAIN] for query {query_vec_main}...")
+    results_main = await client.vector_search(table_name, realm=realm, query_vector=query_vec_main, top_k=2, search_scope="main")
+    for rank, (vertex, dist) in enumerate(results_main, 1):
+        print(f"    Rank {rank}: Vertex ID={vertex.id}, Distance={dist:.4f}, Text='{vertex.payload['text']}'")
+
+    query_vec_data = [0.0, 1.0, 0.0, 0.0]
+    print(f"\n[+] 2. Vector Search [Scope: DATA] for query {query_vec_data}...")
+    results_data = await client.vector_search(table_name, realm=realm, query_vector=query_vec_data, top_k=2, search_scope="data")
+    for rank, (vertex, dist) in enumerate(results_data, 1):
+        print(f"    Rank {rank}: Vertex ID={vertex.id}, Distance={dist:.4f}, Text='{vertex.payload['text']}'")
+
+    print(f"\n[+] 3. Vector Search [Scope: BOTH] for query {query_vec_data}...")
+    results_both = await client.vector_search(table_name, realm=realm, query_vector=query_vec_data, top_k=2, search_scope="both")
+    for rank, (vertex, dist) in enumerate(results_both, 1):
+        print(f"    Rank {rank}: Vertex ID={vertex.id}, Distance={dist:.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_main} 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.4}/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.4"
 
 __all__ = [
     "__version__",

{post_graph-0.1.2 → post_graph-0.1.4}/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,16 @@ 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);')
+                await self._execute(f"ALTER TABLE {data_table_ref} ADD COLUMN IF NOT EXISTS embedding vector({vector_dim});")
+                await self._execute(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_data_embedding" ON {data_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 +432,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 +452,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 +490,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 +508,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 +528,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 +568,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 +580,163 @@ 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)
-        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)
+        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",
+        search_data_table: bool = False,
+        search_scope: str = "main"
+    ) -> List[Tuple[Vertex, float]]:
+        """Perform vector similarity search on vertex embeddings using pgvector.
+        
+        Parameters:
+          - search_data_table: If True and search_scope is 'main', searches the associated data table.
+          - search_scope: 'main' (search main vertex table), 'data' (search associated data table), or 'both' (search both tables).
+        
+        Distance metrics:
+          - 'cosine': <=> (cosine distance)
+          - 'l2': <-> (Euclidean distance)
+          - 'inner_product': <#> (negative inner product)
         """
-        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
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+        vec_str = f"[{','.join(str(x) for x in query_vector)}]"
+        
+        op = "<=>"
+        if distance_metric == "l2":
+            op = "<->"
+        elif distance_metric == "inner_product":
+            op = "<#>"
+
+        scope = search_scope.lower()
+        if search_data_table and scope == "main":
+            scope = "data"
+
+        if scope == "data":
+            query = f"""
+            SELECT v.realm, v.id, v.fqid, v.payload, v.created_at, v.updated_at,
+                   to_jsonb(v)->>'embedding' AS embedding_text,
+                   MIN(d.embedding {op} $2::vector) AS distance
+            FROM {data_table_ref} d
+            JOIN {table_ref} v ON d.realm = v.realm AND d.id = v.id
+            WHERE d.realm = $1 AND d.embedding IS NOT NULL
+            GROUP BY v.realm, v.id, v.fqid, v.payload, v.created_at, v.updated_at, to_jsonb(v)
+            ORDER BY distance ASC
+            LIMIT $3
+            """
+        elif scope == "both":
+            query = f"""
+            WITH combined AS (
+                SELECT realm, id, (embedding {op} $2::vector) AS distance
+                FROM {table_ref}
+                WHERE realm = $1 AND embedding IS NOT NULL
+
+                UNION ALL
+
+                SELECT realm, id, (embedding {op} $2::vector) AS distance
+                FROM {data_table_ref}
+                WHERE realm = $1 AND embedding IS NOT NULL
+            ),
+            best AS (
+                SELECT realm, id, MIN(distance) AS distance
+                FROM combined
+                GROUP BY realm, id
             )
-        except asyncpg.UndefinedTableError:
-            raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+            SELECT v.realm, v.id, v.fqid, v.payload, v.created_at, v.updated_at,
+                   to_jsonb(v)->>'embedding' AS embedding_text,
+                   b.distance
+            FROM best b
+            JOIN {table_ref} v ON b.realm = v.realm AND b.id = v.id
+            ORDER BY b.distance ASC
+            LIMIT $3
+            """
+        else:
+            query = f"""
+            SELECT t.realm, t.id, t.fqid, t.payload, t.created_at, t.updated_at,
+                   to_jsonb(t)->>'embedding' AS embedding_text,
+                   (t.embedding {op} $2::vector) AS distance
+            FROM {table_ref} t
+            WHERE t.realm = $1 AND t.embedding IS NOT NULL
+            ORDER BY t.embedding {op} $2::vector ASC
+            LIMIT $3
+            """
+
+        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}' or data table 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."""
@@ -1175,6 +1372,7 @@ class AsyncPostGraph:
         vertex_id: Union[str, int],
         payload: Dict[str, Any],
         timestamp: Optional[Any] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> DataRecord:
         """Append a historical record to {table_name}_data table for a vertex."""
@@ -1182,29 +1380,59 @@ class AsyncPostGraph:
         v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
         payload_json = json.dumps(payload or {})
         data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+        vec_str = f"[{','.join(str(x) for x in embedding)}]" if embedding is not None else None
 
         async def _op(conn):
-            if timestamp:
-                query = f"""
-                INSERT INTO {data_table_ref} (realm, id, payload, timestamp)
-                VALUES ($1, $2, $3::jsonb, $4)
-                RETURNING data_id, realm, id, payload, timestamp
-                """
-                row = await conn.fetchrow(query, realm, v_id_int, payload_json, timestamp)
+            has_emb = False
+            if vec_str:
+                data_t_name = f"{table_name}_data"
+                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, data_t_name) is not None
+                else:
+                    has_emb = await conn.fetchval("SELECT 1 FROM information_schema.columns WHERE table_name = $1 AND column_name = 'embedding'", data_t_name) is not None
+
+            if vec_str and has_emb:
+                if timestamp:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload, timestamp, embedding)
+                    VALUES ($1, $2, $3::jsonb, $4, $5::vector)
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await conn.fetchrow(query, realm, v_id_int, payload_json, timestamp, vec_str)
+                else:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload, embedding)
+                    VALUES ($1, $2, $3::jsonb, $4::vector)
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await conn.fetchrow(query, realm, v_id_int, payload_json, vec_str)
             else:
-                query = f"""
-                INSERT INTO {data_table_ref} (realm, id, payload)
-                VALUES ($1, $2, $3::jsonb)
-                RETURNING data_id, realm, id, payload, timestamp
-                """
-                row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+                if timestamp:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload, timestamp)
+                    VALUES ($1, $2, $3::jsonb, $4)
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await conn.fetchrow(query, realm, v_id_int, payload_json, timestamp)
+                else:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload)
+                    VALUES ($1, $2, $3::jsonb)
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+
+            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 DataRecord(
                 data_id=str(row['data_id']),
                 realm=row['realm'],
                 id=str(row['id']),
                 payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
-                timestamp=row['timestamp']
+                timestamp=row['timestamp'],
+                embedding=emb
             )
 
         return await self._run_in_tx(_op, user_id)
@@ -1223,23 +1451,29 @@ class AsyncPostGraph:
 
         limit_clause = f"LIMIT {limit}" if limit and limit > 0 else ""
         query = f"""
-        SELECT data_id, realm, id, payload, timestamp
-        FROM {data_table_ref}
-        WHERE realm = $1 AND id = $2
-        ORDER BY timestamp DESC, data_id DESC
+        SELECT d.data_id, d.realm, d.id, d.payload, d.timestamp, to_jsonb(d)->>'embedding' AS embedding_text
+        FROM {data_table_ref} d
+        WHERE d.realm = $1 AND d.id = $2
+        ORDER BY d.timestamp DESC, d.data_id DESC
         {limit_clause}
         """
         rows = await self._fetch(query, realm, v_id_int)
-        return [
-            DataRecord(
-                data_id=str(r['data_id']),
-                realm=r['realm'],
-                id=str(r['id']),
-                payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
-                timestamp=r['timestamp']
+        results = []
+        for r in rows:
+            emb = None
+            if 'embedding_text' in r and r['embedding_text']:
+                emb = [float(x) for x in r['embedding_text'].strip('[]').split(',') if x.strip()]
+            results.append(
+                DataRecord(
+                    data_id=str(r['data_id']),
+                    realm=r['realm'],
+                    id=str(r['id']),
+                    payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
+                    timestamp=r['timestamp'],
+                    embedding=emb
+                )
             )
-            for r in rows
-        ]
+        return results
 
     async def add_edge_data(
         self,
@@ -1248,10 +1482,11 @@ class AsyncPostGraph:
         edge_id: Union[str, int],
         payload: Dict[str, Any],
         timestamp: Optional[Any] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> DataRecord:
         """Append a historical record to {table_name}_data table for an edge."""
-        return await self.add_vertex_data(table_name, realm, edge_id, payload, timestamp=timestamp, user_id=user_id)
+        return await self.add_vertex_data(table_name, realm, edge_id, payload, timestamp=timestamp, embedding=embedding, user_id=user_id)
 
     async def get_edge_data(
         self,

{post_graph-0.1.2 → post_graph-0.1.4}/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,16 @@ 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);'))
+                    await conn.execute(text(f"ALTER TABLE {data_table_ref} ADD COLUMN IF NOT EXISTS embedding vector({vector_dim});"))
+                    await conn.execute(text(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_data_embedding" ON {data_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 +396,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 +416,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 +448,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 +470,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 +490,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 +525,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 +539,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 +579,116 @@ 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",
+        search_data_table: bool = False,
+        search_scope: str = "main"
+    ) -> 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)
+        data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+        vec_str = f"[{','.join(str(x) for x in query_vector)}]"
+        
+        op = "<=>"
+        if distance_metric == "l2":
+            op = "<->"
+        elif distance_metric == "inner_product":
+            op = "<#>"
+
+        scope = search_scope.lower()
+        if search_data_table and scope == "main":
+            scope = "data"
+
+        if scope == "data":
+            query = f"""
+            SELECT v.realm, v.id, v.fqid, v.payload, v.created_at, v.updated_at,
+                   to_jsonb(v)->>'embedding' AS embedding_text,
+                   MIN(d.embedding {op} CAST(:vec AS vector)) AS distance
+            FROM {data_table_ref} d
+            JOIN {table_ref} v ON d.realm = v.realm AND d.id = v.id
+            WHERE d.realm = :realm AND d.embedding IS NOT NULL
+            GROUP BY v.realm, v.id, v.fqid, v.payload, v.created_at, v.updated_at, to_jsonb(v)
+            ORDER BY distance ASC
+            LIMIT :top_k
+            """
+        elif scope == "both":
+            query = f"""
+            WITH combined AS (
+                SELECT realm, id, (embedding {op} CAST(:vec AS vector)) AS distance
+                FROM {table_ref}
+                WHERE realm = :realm AND embedding IS NOT NULL
+
+                UNION ALL
+
+                SELECT realm, id, (embedding {op} CAST(:vec AS vector)) AS distance
+                FROM {data_table_ref}
+                WHERE realm = :realm AND embedding IS NOT NULL
+            ),
+            best AS (
+                SELECT realm, id, MIN(distance) AS distance
+                FROM combined
+                GROUP BY realm, id
+            )
+            SELECT v.realm, v.id, v.fqid, v.payload, v.created_at, v.updated_at,
+                   to_jsonb(v)->>'embedding' AS embedding_text,
+                   b.distance
+            FROM best b
+            JOIN {table_ref} v ON b.realm = v.realm AND b.id = v.id
+            ORDER BY b.distance ASC
+            LIMIT :top_k
+            """
+        else:
+            query = f"""
+            SELECT t.realm, t.id, t.fqid, t.payload, t.created_at, t.updated_at,
+                   CAST(t.embedding AS TEXT) AS embedding_text,
+                   (t.embedding {op} CAST(:vec AS vector)) AS distance
+            FROM {table_ref} t
+            WHERE t.realm = :realm AND t.embedding IS NOT NULL
+            ORDER BY t.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)
@@ -1209,6 +1377,7 @@ class SQLAlchemyPostGraph:
         vertex_id: Union[str, int],
         payload: Dict[str, Any],
         timestamp: Optional[Any] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> DataRecord:
         """Append a historical record to {table_name}_data table for a vertex."""
@@ -1216,29 +1385,63 @@ class SQLAlchemyPostGraph:
         v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
         payload_json = json.dumps(payload or {})
         data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+        vec_str = f"[{','.join(str(x) for x in embedding)}]" if embedding is not None else None
 
         async def _op(conn):
-            if timestamp:
-                query = f"""
-                INSERT INTO {data_table_ref} (realm, id, payload, timestamp)
-                VALUES (:realm, :id, CAST(:payload AS JSONB), :timestamp)
-                RETURNING data_id, realm, id, payload, timestamp
-                """
-                row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json, timestamp=timestamp)
+            has_emb = False
+            if vec_str:
+                data_t_name = f"{table_name}_data"
+                if self.schema_per_realm:
+                    check_q = "SELECT 1 FROM information_schema.columns WHERE table_schema = :schema AND table_name = :t_name AND column_name = 'embedding'"
+                    res = await conn.execute(text(check_q), {"schema": realm, "t_name": data_t_name})
+                    has_emb = res.scalar() is not None
+                else:
+                    check_q = "SELECT 1 FROM information_schema.columns WHERE table_name = :t_name AND column_name = 'embedding'"
+                    res = await conn.execute(text(check_q), {"t_name": data_t_name})
+                    has_emb = res.scalar() is not None
+
+            if vec_str and has_emb:
+                if timestamp:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload, timestamp, embedding)
+                    VALUES (:realm, :id, CAST(:payload AS JSONB), :timestamp, CAST(:vec AS vector))
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json, timestamp=timestamp, vec=vec_str)
+                else:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload, embedding)
+                    VALUES (:realm, :id, CAST(:payload AS JSONB), CAST(:vec AS vector))
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json, vec=vec_str)
             else:
-                query = f"""
-                INSERT INTO {data_table_ref} (realm, id, payload)
-                VALUES (:realm, :id, CAST(:payload AS JSONB))
-                RETURNING data_id, realm, id, payload, timestamp
-                """
-                row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json)
+                if timestamp:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload, timestamp)
+                    VALUES (:realm, :id, CAST(:payload AS JSONB), :timestamp)
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json, timestamp=timestamp)
+                else:
+                    query = f"""
+                    INSERT INTO {data_table_ref} (realm, id, payload)
+                    VALUES (:realm, :id, CAST(:payload AS JSONB))
+                    RETURNING data_id, realm, id, payload, timestamp, to_jsonb({data_table_ref})->>'embedding' AS embedding_text
+                    """
+                    row = await self._fetchrow(conn, query, realm=realm, id=v_id_int, payload=payload_json)
+
+            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 DataRecord(
                 data_id=str(row['data_id']),
                 realm=row['realm'],
                 id=str(row['id']),
                 payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
-                timestamp=row['timestamp']
+                timestamp=row['timestamp'],
+                embedding=emb
             )
 
         return await self._run_in_tx(_op, user_id)
@@ -1257,25 +1460,31 @@ class SQLAlchemyPostGraph:
 
         limit_clause = f"LIMIT {limit}" if limit and limit > 0 else ""
         query = f"""
-        SELECT data_id, realm, id, payload, timestamp
-        FROM {data_table_ref}
-        WHERE realm = :realm AND id = :id
-        ORDER BY timestamp DESC, data_id DESC
+        SELECT d.data_id, d.realm, d.id, d.payload, d.timestamp, to_jsonb(d)->>'embedding' AS embedding_text
+        FROM {data_table_ref} d
+        WHERE d.realm = :realm AND d.id = :id
+        ORDER BY d.timestamp DESC, d.data_id DESC
         {limit_clause}
         """
 
         async def _op(conn):
             rows = await self._fetch(conn, query, realm=realm, id=v_id_int)
-            return [
-                DataRecord(
-                    data_id=str(r['data_id']),
-                    realm=r['realm'],
-                    id=str(r['id']),
-                    payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
-                    timestamp=r['timestamp']
+            results = []
+            for r in rows:
+                emb = None
+                if 'embedding_text' in r and r['embedding_text']:
+                    emb = [float(x) for x in r['embedding_text'].strip('[]').split(',') if x.strip()]
+                results.append(
+                    DataRecord(
+                        data_id=str(r['data_id']),
+                        realm=r['realm'],
+                        id=str(r['id']),
+                        payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
+                        timestamp=r['timestamp'],
+                        embedding=emb
+                    )
                 )
-                for r in rows
-            ]
+            return results
 
         if isinstance(self.engine_or_connection, AsyncConnection):
             return await _op(self.engine_or_connection)
@@ -1290,10 +1499,11 @@ class SQLAlchemyPostGraph:
         edge_id: Union[str, int],
         payload: Dict[str, Any],
         timestamp: Optional[Any] = None,
+        embedding: Optional[List[float]] = None,
         user_id: Optional[str] = None
     ) -> DataRecord:
         """Append a historical record to {table_name}_data table for an edge."""
-        return await self.add_vertex_data(table_name, realm, edge_id, payload, timestamp=timestamp, user_id=user_id)
+        return await self.add_vertex_data(table_name, realm, edge_id, payload, timestamp=timestamp, embedding=embedding, user_id=user_id)
 
     async def get_edge_data(
         self,

{post_graph-0.1.2 → post_graph-0.1.4}/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']:
@@ -117,7 +119,13 @@ class Vertex:
             user_id=user_id
         )
 
-    async def add_data(self, payload: Dict[str, Any], timestamp: Optional[datetime] = None, user_id: Optional[str] = None) -> 'DataRecord':
+    async def add_data(
+        self,
+        payload: Dict[str, Any],
+        timestamp: Optional[datetime] = None,
+        embedding: Optional[List[float]] = None,
+        user_id: Optional[str] = None
+    ) -> 'DataRecord':
         """Append a data record to this vertex's {table_name}_data table."""
         if not self._client:
             from post_graph.errors import PostGraphError
@@ -128,6 +136,7 @@ class Vertex:
             vertex_id=self.id,
             payload=payload,
             timestamp=timestamp,
+            embedding=embedding,
             user_id=user_id
         )
 
@@ -189,7 +198,13 @@ class Edge:
             user_id=user_id
         )
 
-    async def add_data(self, payload: Dict[str, Any], timestamp: Optional[datetime] = None, user_id: Optional[str] = None) -> 'DataRecord':
+    async def add_data(
+        self,
+        payload: Dict[str, Any],
+        timestamp: Optional[datetime] = None,
+        embedding: Optional[List[float]] = None,
+        user_id: Optional[str] = None
+    ) -> 'DataRecord':
         """Append a data record to this edge's {table_name}_data table."""
         if not self._client:
             from post_graph.errors import PostGraphError
@@ -200,6 +215,7 @@ class Edge:
             edge_id=self.id,
             payload=payload,
             timestamp=timestamp,
+            embedding=embedding,
             user_id=user_id
         )
 
@@ -223,6 +239,7 @@ class DataRecord:
     id: str
     payload: Dict[str, Any] = field(default_factory=dict)
     timestamp: Optional[datetime] = None
+    embedding: Optional[List[float]] = None
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert DataRecord object to a dictionary."""
@@ -232,6 +249,7 @@ class DataRecord:
             "id": self.id,
             "payload": self.payload,
             "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+            "embedding": self.embedding
         }
 
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "post-graph"
-version = "0.1.2"
+version = "0.1.4"
 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"