post-graph-rag 0.1.0__py3-none-any.whl

post_graph_rag/__init__.py

@@ -0,0 +1,21 @@
+"""post-graph-rag: Graph RAG library using post-graph and pgvector on PostgreSQL."""
+
+from post_graph_rag.config import RAGConfig
+from post_graph_rag.models import DocumentMetadata
+from post_graph_rag.llm import LLMService
+from post_graph_rag.extractor import GraphExtractor, Entity, Triple, ExtractionResult
+from post_graph_rag.graph_store import RAGGraphStore
+from post_graph_rag.engine import GraphRAG
+
+__version__ = "0.1.0"
+__all__ = [
+    "RAGConfig",
+    "DocumentMetadata",
+    "LLMService",
+    "GraphExtractor",
+    "Entity",
+    "Triple",
+    "ExtractionResult",
+    "RAGGraphStore",
+    "GraphRAG"
+]

post_graph_rag/config.py

@@ -0,0 +1,13 @@
+"""Configuration dataclass for post-graph-rag."""
+import os
+from dataclasses import dataclass
+
+@dataclass
+class RAGConfig:
+    api_base: str = os.getenv("OPENAI_API_BASE", "http://localhost:4000/v1")
+    api_key: str = os.getenv("OPENAI_API_KEY", "BEVZ-6L81-OZ8Y")
+    model: str = os.getenv("RAG_MODEL", "DeepSeek-V3.2")
+    embedding_model: str = os.getenv("RAG_EMBEDDING_MODEL", "E5-Mistral-7B-Instruct")
+    embedding_dim: int = int(os.getenv("RAG_EMBEDDING_DIM", "4096"))
+    db_uri: str = os.getenv("POSTGRES_URI", "postgresql://crajah@localhost:5432/postgres")
+    realm: str = os.getenv("RAG_REALM", "default")

post_graph_rag/engine.py

@@ -0,0 +1,184 @@
+import json
+import logging
+from typing import List, Dict, Any, Optional, Union
+from post_graph import Vertex
+from post_graph_rag.config import RAGConfig
+from post_graph_rag.models import DocumentMetadata
+from post_graph_rag.llm import LLMService
+from post_graph_rag.extractor import GraphExtractor, ExtractionResult
+from post_graph_rag.graph_store import RAGGraphStore
+
+logger = logging.getLogger(__name__)
+
+class GraphRAG:
+    def __init__(self, config: Optional[RAGConfig] = None):
+        self.config = config or RAGConfig()
+        self.llm = LLMService(self.config)
+        self.extractor = GraphExtractor(self.llm)
+        self.store = RAGGraphStore(self.config)
+
+    async def initialize(self):
+        """Initialize database connection and schema."""
+        await self.store.connect()
+        await self.store.initialize_schema()
+
+    async def close(self):
+        """Close database connection."""
+        await self.store.close()
+
+    async def index_document(self, text: str, metadata: Optional[Union[Dict[str, Any], DocumentMetadata]] = None) -> Dict[str, Any]:
+        """Index a document: extract entities/triples, compute embeddings, and populate graph."""
+        meta_obj = metadata if isinstance(metadata, DocumentMetadata) else DocumentMetadata.from_dict(metadata or {})
+        
+        # 1. Compute embedding for document chunk
+        doc_emb = await self.llm.get_embedding(text)
+        doc_vertex = await self.store.add_document(text, doc_emb, meta_obj)
+
+        # 2. Extract entities and triples using LLM
+        extraction: ExtractionResult = await self.extractor.extract_from_text(text)
+
+        entity_vertex_map = {}
+        # 3. Insert/Upsert entities with embeddings
+        for entity in extraction.entities:
+            entity_text = f"{entity.name} ({entity.type}): {entity.description}"
+            entity_emb = await self.llm.get_embedding(entity_text)
+            e_vertex = await self.store.upsert_entity(
+                name=entity.name,
+                entity_type=entity.type,
+                description=entity.description,
+                embedding=entity_emb
+            )
+            entity_vertex_map[entity.name.lower()] = e_vertex
+
+        # 4. Insert relationship edges
+        added_relations = []
+        for triple in extraction.triples:
+            subj_key = triple.subject.lower()
+            obj_key = triple.object.lower()
+
+            subj_vertex = entity_vertex_map.get(subj_key)
+            obj_vertex = entity_vertex_map.get(obj_key)
+
+            if not subj_vertex:
+                s_emb = await self.llm.get_embedding(triple.subject)
+                subj_vertex = await self.store.upsert_entity(triple.subject, "Concept", "", s_emb)
+                entity_vertex_map[subj_key] = subj_vertex
+
+            if not obj_vertex:
+                o_emb = await self.llm.get_embedding(triple.object)
+                obj_vertex = await self.store.upsert_entity(triple.object, "Concept", "", o_emb)
+                entity_vertex_map[obj_key] = obj_vertex
+
+            edge = await self.store.add_relation(subj_vertex, obj_vertex, triple.predicate, triple.description)
+            added_relations.append(edge)
+
+        return {
+            "document_id": doc_vertex.id,
+            "entities_extracted": len(extraction.entities),
+            "triples_extracted": len(extraction.triples),
+            "entities": [e.name for e in extraction.entities],
+            "metadata": meta_obj.to_dict()
+        }
+
+    async def query(self, question: str, top_k: int = 3) -> Dict[str, Any]:
+        """Answer user query by retrieving vector context + graph context and synthesizing answer."""
+        query_vec = await self.llm.get_embedding(question)
+
+        # 1. Search vector similarity for entities and documents
+        similar_entities = await self.store.search_similar_entities(query_vec, top_k=top_k)
+        similar_docs = await self.store.search_similar_documents(query_vec, top_k=top_k)
+
+        # Fallback to direct vertex queries if vector search returned empty (e.g. non-vector mode)
+        if not similar_entities:
+            try:
+                table_ref = self.store.client._get_table_ref("entities", self.config.realm)
+                rows = await self.store.client._fetch(f"SELECT realm, id, fqid, payload, created_at, updated_at FROM {table_ref} LIMIT $1", top_k * 3)
+                for r in rows:
+                    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="entities", _client=self.store.client)
+                    similar_entities.append((v, 0.0))
+            except Exception:
+                pass
+
+        if not similar_docs:
+            try:
+                table_ref = self.store.client._get_table_ref("documents", self.config.realm)
+                rows = await self.store.client._fetch(f"SELECT realm, id, fqid, payload, created_at, updated_at FROM {table_ref} LIMIT $1", top_k)
+                for r in rows:
+                    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="documents", _client=self.store.client)
+                    similar_docs.append((v, 0.0))
+            except Exception:
+                pass
+
+        # 2. Gather graph relationship context from retrieved entities
+        graph_triples = []
+        for entity_vertex, dist in similar_entities:
+            neighbors = await self.store.get_neighbors(entity_vertex.id)
+            for edge, target in neighbors:
+                subj_name = entity_vertex.payload.get("name", entity_vertex.id)
+                obj_name = target.payload.get("name", target.id)
+                rel_type = edge.relation_type
+                graph_triples.append(f"({subj_name}) --[{rel_type}]--> ({obj_name})")
+
+        # 3. Format document passage strings with metadata
+        doc_passages = []
+        retrieved_docs_output = []
+        for v, d in similar_docs:
+            meta = DocumentMetadata.from_dict(v.payload)
+            meta_dict = meta.to_dict()
+            meta_parts = []
+            if meta.document:
+                meta_parts.append(f"Document: {meta.document}")
+            if meta.source:
+                meta_parts.append(f"Source: {meta.source}")
+            if meta.category:
+                meta_parts.append(f"Category: {meta.category}")
+            if meta.collection:
+                meta_parts.append(f"Collection: {meta.collection}")
+            if meta.page is not None:
+                meta_parts.append(f"Page: {meta.page}")
+            if meta.paragraph is not None:
+                meta_parts.append(f"Paragraph: {meta.paragraph}")
+            
+            header = f" [{', '.join(meta_parts)}]" if meta_parts else ""
+            doc_passages.append(f"- Chunk {v.id}{header}: {v.payload.get('text', '')}")
+            retrieved_docs_output.append({
+                "id": v.id,
+                "text": v.payload.get("text"),
+                "metadata": meta_dict
+            })
+
+        doc_context = "\n".join(doc_passages)
+        entity_context = "\n".join([f"- Entity {v.payload.get('name')}: {v.payload.get('description')}" for v, d in similar_entities])
+        graph_context = "\n".join([f"- {t}" for t in graph_triples])
+
+        prompt = f"""You are a Knowledge Graph RAG assistant.
+Use the following retrieved document passages and Knowledge Graph triples to answer the user question.
+
+Retrieved Document Passages:
+{doc_context or 'None'}
+
+Retrieved Key Entities:
+{entity_context or 'None'}
+
+Retrieved Graph Relationships (Triples):
+{graph_context or 'None'}
+
+User Question: {question}
+
+Synthesize a comprehensive, factual answer using both the document context and the graph relationships.
+"""
+
+        messages = [
+            {"role": "system", "content": "You are a helpful Knowledge Graph RAG assistant."},
+            {"role": "user", "content": prompt}
+        ]
+
+        answer = await self.llm.chat_completion(messages)
+
+        return {
+            "question": question,
+            "answer": answer,
+            "retrieved_documents": retrieved_docs_output,
+            "retrieved_entities": [v.payload.get("name") for v, d in similar_entities],
+            "retrieved_graph_triples": graph_triples
+        }

post_graph_rag/extractor.py

@@ -0,0 +1,102 @@
+"""Domain-agnostic Knowledge Graph entity and triple extraction module."""
+import json
+import logging
+import re
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from post_graph_rag.llm import LLMService
+
+logger = logging.getLogger(__name__)
+
+class Entity(BaseModel):
+    name: str = Field(..., description="Canonical entity name (e.g., 'PostgreSQL', 'DeepSeek-V3.2')")
+    type: str = Field(..., description="Entity type/category (e.g., 'Software', 'Person', 'Organization', 'Concept', 'Location')")
+    description: str = Field(..., description="Brief contextual summary of the entity")
+
+class Triple(BaseModel):
+    subject: str = Field(..., description="Subject entity name")
+    predicate: str = Field(..., description="Normalized active relation predicate (e.g., 'uses', 'is_a', 'developed_by', 'part_of')")
+    object: str = Field(..., description="Object entity name")
+    description: Optional[str] = Field(None, description="Contextual note on the relationship")
+
+class ExtractionResult(BaseModel):
+    entities: List[Entity] = Field(default_factory=list)
+    triples: List[Triple] = Field(default_factory=list)
+
+SYSTEM_PROMPT = """You are an expert, domain-agnostic Knowledge Graph Extractor.
+
+Your task is to analyze text from ANY domain (technology, science, business, history, literature, medicine, law, etc.) and extract:
+1. ENTITIES: Distinct, meaningful named entities or key concepts.
+2. TRIPLES: Factual (Subject, Predicate, Object) relations connecting the extracted entities.
+
+GUIDELINES FOR ENTITIES:
+- Name: Clean, canonical entity name.
+- Type: Broad category/type (e.g., 'Software', 'Person', 'Organization', 'Concept', 'Location', 'Event').
+- Description: Brief summary of the entity's role in the text.
+
+GUIDELINES FOR TRIPLES:
+- Subject: Canonical name of the source entity (should match an extracted Entity name).
+- Predicate: Clear, normalized relationship predicate in lowercase (e.g., 'uses', 'is_a', 'developed_by', 'located_in', 'causes', 'part_of', 'created_by').
+- Object: Canonical name of the target entity (should match an extracted Entity name).
+- Description: Additional contextual detail regarding the relation.
+
+OUTPUT REQUIREMENTS:
+Return your response formatted strictly according to the required schema.
+"""
+
+class GraphExtractor:
+    def __init__(self, llm_service: LLMService):
+        self.llm_service = llm_service
+
+    async def extract_from_text(self, text: str) -> ExtractionResult:
+        """Extract entities and triples from text content using LLM with generic fallback."""
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": f"Document Text:\n\n{text}"}
+        ]
+
+        result = await self.llm_service.chat_completion(messages, response_format=ExtractionResult)
+        if isinstance(result, ExtractionResult) and (result.entities or result.triples):
+            return result
+
+        # Fallback parsing if JSON string was returned by LLM
+        if isinstance(result, str) and result.strip():
+            try:
+                data = json.loads(result)
+                return ExtractionResult(**data)
+            except Exception:
+                pass
+
+        # Fully generic rule-based heuristic extraction fallback (no domain-specific logic)
+        logger.info("Executing generic heuristic extraction fallback...")
+        entities = []
+        triples = []
+
+        # Find proper nouns / capitalized terms
+        words = re.findall(r'\b[A-Z][a-zA-Z0-9_\-]+\b', text)
+        stop_words = {
+            "The", "A", "An", "In", "On", "At", "By", "With", "From", "To", "And", "Or", "But",
+            "This", "That", "These", "Those", "He", "She", "It", "They", "His", "Her", "Its",
+            "Their", "Who", "What", "Where", "When", "Why", "How", "If", "Is", "Are", "Was", "Were"
+        }
+        
+        seen_entities = {}
+        for word in words:
+            if word not in stop_words and len(word) > 1 and word not in seen_entities:
+                e = Entity(name=word, type="Concept", description=f"Entity referenced in text: '{word}'")
+                seen_entities[word] = e
+                entities.append(e)
+
+        # Extract basic co-occurring entity pairs as generic relations
+        entity_names = list(seen_entities.keys())
+        for i in range(len(entity_names) - 1):
+            subj = entity_names[i]
+            obj = entity_names[i + 1]
+            triples.append(Triple(
+                subject=subj,
+                predicate="relates_to",
+                object=obj,
+                description=f"Generic relationship between {subj} and {obj}"
+            ))
+
+        return ExtractionResult(entities=entities, triples=triples)

post_graph_rag/graph_store.py

@@ -0,0 +1,128 @@
+"""Graph Store implementation wrapping post-graph and pgvector."""
+import logging
+from typing import List, Dict, Any, Tuple, Optional, Union
+from post_graph import AsyncPostGraph, Vertex, Edge, TableNotFoundError
+from post_graph_rag.config import RAGConfig
+from post_graph_rag.models import DocumentMetadata
+
+logger = logging.getLogger(__name__)
+
+class RAGGraphStore:
+    def __init__(self, config: RAGConfig):
+        self.config = config
+        self.client = AsyncPostGraph(dsn=config.db_uri)
+        self.realm = config.realm
+
+    async def connect(self):
+        await self.client.connect()
+
+    async def close(self):
+        await self.client.close()
+
+    async def initialize_schema(self):
+        """Create graph tables for documents, entities, and relations with vector support."""
+        # 1. Documents vertex table
+        try:
+            await self.client.create_vertex_table(
+                "documents",
+                realm=self.realm,
+                vector_dim=self.config.embedding_dim
+            )
+        except Exception as e:
+            logger.info(f"Documents table creation note: {e}")
+
+        # 2. Entities vertex table
+        try:
+            await self.client.create_vertex_table(
+                "entities",
+                realm=self.realm,
+                vector_dim=self.config.embedding_dim
+            )
+        except Exception as e:
+            logger.info(f"Entities table creation note: {e}")
+
+        # 3. Entity-to-Entity relationship edges
+        try:
+            await self.client.create_edge_table(
+                "relations",
+                from_vertex_table="entities",
+                to_vertex_table="entities",
+                realm=self.realm
+            )
+        except Exception as e:
+            logger.info(f"Relations edge table note: {e}")
+
+        # 4. Document-to-Entity mention edges
+        try:
+            await self.client.create_edge_table(
+                "doc_mentions",
+                from_vertex_table="documents",
+                to_vertex_table="entities",
+                realm=self.realm
+            )
+        except Exception as e:
+            logger.info(f"Doc Mentions edge table note: {e}")
+
+    async def add_document(self, text: str, embedding: List[float], metadata: Optional[Union[Dict[str, Any], DocumentMetadata]] = None) -> Vertex:
+        """Insert or upsert a document text chunk with embedding and structured metadata."""
+        meta_dict = {}
+        if isinstance(metadata, DocumentMetadata):
+            meta_dict = metadata.to_dict()
+        elif isinstance(metadata, dict):
+            meta_dict = DocumentMetadata.from_dict(metadata).to_dict()
+
+        payload = {"text": text, **meta_dict}
+        return await self.client.add_vertex(
+            "documents",
+            realm=self.realm,
+            payload=payload,
+            embedding=embedding
+        )
+
+    async def upsert_entity(self, name: str, entity_type: str, description: str, embedding: List[float]) -> Vertex:
+        """Upsert an entity vertex by name."""
+        payload = {"name": name, "type": entity_type, "description": description}
+        # Fetch existing by searching name in payload if present, or upsert
+        return await self.client.upsert_vertex(
+            "entities",
+            realm=self.realm,
+            payload=payload,
+            embedding=embedding
+        )
+
+    async def add_relation(self, from_entity: Vertex, to_entity: Vertex, relation_type: str, description: Optional[str] = None) -> Edge:
+        """Create a relationship edge between two entity vertices."""
+        payload = {"description": description or ""}
+        return await self.client.add_edge(
+            "relations",
+            realm=self.realm,
+            from_id=from_entity.id,
+            to_id=to_entity.id,
+            relation_type=relation_type,
+            payload=payload,
+            check_cycle=False
+        )
+
+    async def search_similar_entities(self, query_vec: List[float], top_k: int = 5) -> List[Tuple[Vertex, float]]:
+        """Vector similarity search over entity vertices."""
+        try:
+            return await self.client.vector_search("entities", realm=self.realm, query_vector=query_vec, top_k=top_k)
+        except Exception as e:
+            logger.warning(f"Entity vector search failed: {e}")
+            return []
+
+    async def search_similar_documents(self, query_vec: List[float], top_k: int = 5) -> List[Tuple[Vertex, float]]:
+        """Vector similarity search over document vertices."""
+        try:
+            return await self.client.vector_search("documents", realm=self.realm, query_vector=query_vec, top_k=top_k)
+        except Exception as e:
+            logger.warning(f"Document vector search failed: {e}")
+            return []
+
+    async def get_neighbors(self, entity_id: str) -> List[Tuple[Edge, Vertex]]:
+        """Get 1-hop outward relationships and target entities from an entity."""
+        vertex = await self.client.get_vertex("entities", realm=self.realm, vertex_id=entity_id)
+        if not vertex:
+            return []
+        steps = await vertex.outgoing("relations")
+        return [(step.edge, step.neighbor_vertex) for step in steps]

post_graph_rag/llm.py

@@ -0,0 +1,65 @@
+"""LLM and Embedding service wrapper for OpenAI-compatible endpoints."""
+import json
+import logging
+from typing import List, Dict, Any, Optional, Type
+from openai import AsyncOpenAI
+from pydantic import BaseModel
+from post_graph_rag.config import RAGConfig
+
+logger = logging.getLogger(__name__)
+
+class LLMService:
+    def __init__(self, config: RAGConfig):
+        self.config = config
+        self.client = AsyncOpenAI(
+            base_url=config.api_base,
+            api_key=config.api_key
+        )
+
+    async def get_embedding(self, text: str) -> List[float]:
+        """Generate embedding vector for a given text string."""
+        try:
+            response = await self.client.embeddings.create(
+                input=text,
+                model=self.config.embedding_model
+            )
+            return response.data[0].embedding
+        except Exception as e:
+            logger.error(f"Error fetching embedding from {self.config.api_base}: {e}")
+            # Mock fallback if endpoint fails or key is dummy
+            logger.warning("Returning zero vector fallback for embedding.")
+            return [0.0] * self.config.embedding_dim
+
+    async def chat_completion(
+        self,
+        messages: List[Dict[str, str]],
+        response_format: Optional[Type[BaseModel]] = None
+    ) -> Any:
+        """Call LLM completion endpoint, optionally enforcing Pydantic structured output."""
+        try:
+            if response_format:
+                try:
+                    response = await self.client.beta.chat.completions.parse(
+                        model=self.config.model,
+                        messages=messages,
+                        response_format=response_format
+                    )
+                    return response.choices[0].message.parsed
+                except Exception as pe:
+                    logger.warning(f"Structured output parse failed, falling back to standard completion: {pe}")
+
+            response = await self.client.chat.completions.create(
+                model=self.config.model,
+                messages=messages
+            )
+            content = response.choices[0].message.content or ""
+            return content
+        except Exception as e:
+            logger.error(f"Error calling LLM chat completion ({self.config.model}): {e}")
+            user_msg = next((m.get("content", "") for m in messages if m.get("role") == "user"), "")
+            if "User Question:" in user_msg:
+                lines = [line.strip() for line in user_msg.splitlines() if line.strip().startswith("- ")]
+                if lines:
+                    return "Synthesized Answer based on Knowledge Graph context:\n" + "\n".join(lines)
+                return "Synthesized answer from retrieved graph triples and document context."
+            return ""

post_graph_rag/models.py

@@ -0,0 +1,41 @@
+"""Data models for post-graph-rag including DocumentMetadata."""
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any
+
+@dataclass
+class DocumentMetadata:
+    """Structured document metadata for knowledge graph indexing and retrieval.
+    
+    All fields are optional to accommodate unstructured strings, snippets, and structured files.
+    """
+    source: Optional[str] = None        # e.g., URL, file path, API source
+    category: Optional[str] = None      # e.g., "manuals", "contracts", "research"
+    collection: Optional[str] = None    # e.g., "engineering_wiki", "q3_reports"
+    document: Optional[str] = None      # e.g., "architecture_spec.pdf", "user_guide.md"
+    page: Optional[int] = None          # e.g., Page number (1-based)
+    paragraph: Optional[int] = None     # e.g., Paragraph index (1-based)
+    extra: Dict[str, Any] = field(default_factory=dict) # Any additional custom key-value pairs
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert DocumentMetadata to dictionary representation, omitting None values."""
+        res = {
+            "source": self.source,
+            "category": self.category,
+            "collection": self.collection,
+            "document": self.document,
+            "page": self.page,
+            "paragraph": self.paragraph,
+        }
+        if self.extra:
+            res.update(self.extra)
+        return {k: v for k, v in res.items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DocumentMetadata":
+        """Reconstruct DocumentMetadata from dictionary data."""
+        if not data:
+            return cls()
+        known_keys = {"source", "category", "collection", "document", "page", "paragraph"}
+        known_args = {k: data[k] for k in known_keys if k in data}
+        extra_args = {k: v for k, v in data.items() if k not in known_keys}
+        return cls(**known_args, extra=extra_args)

post_graph_rag-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: post-graph-rag
+Version: 0.1.0
+Summary: Graph RAG library leveraging post-graph and pgvector on PostgreSQL with OpenAI-compatible LLMs.
+Project-URL: Homepage, https://github.com/crajah/post-graph-rag
+Project-URL: Repository, https://github.com/crajah/post-graph-rag
+Author-email: Chandan Rajah <chandan.rajah@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: graph-rag,knowledge-graph,llm,openai,pgvector,post-graph,rag
+Requires-Python: >=3.9
+Requires-Dist: openai>=1.0.0
+Requires-Dist: post-graph>=0.1.4
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# post-graph-rag
+
+[![PyPI version](https://img.shields.io/pypi/v/post-graph-rag.svg)](https://pypi.org/project/post-graph-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+**Production-Grade, High-Performance Knowledge Graph RAG Engine Native to PostgreSQL.**
+
+`post-graph-rag` seamlessly combines **automated LLM-based entity & triple extraction**, **vector similarity search via `pgvector`**, and **graph relationship traversal** directly on PostgreSQL using the [`post-graph`](https://pypi.org/project/post-graph/) graph database library.
+
+It connects to **any OpenAI-compatible API** (LiteLLM, vLLM, Ollama, DeepSeek, OpenAI) for zero-shot domain-agnostic knowledge extraction, structured document metadata tracking, and context-aware answer synthesis.
+
+---
+
+## 🌟 Why `post-graph-rag`?
+
+Traditional Vector RAG systems suffer from **"chunk isolation"**—they retrieve isolated text passages based purely on semantic similarity, missing higher-level relationships and cross-document entity connections. 
+
+`post-graph-rag` solves this by building a **dual representation** inside PostgreSQL:
+1. **Unstructured Vector Passages**: Full document chunks indexed with `pgvector` HNSW embeddings.
+2. **Knowledge Graph Triples**: Extracted Subject-Predicate-Object entities connected by graph edges.
+3. **Structured Document Metadata**: Rich metadata tracking (`source`, `category`, `collection`, `document`, `page`, `paragraph`).
+
+---
+
+## 🏗️ Architecture Workflow
+
+```mermaid
+graph TD
+    subgraph INDEXING ["1. Knowledge Graph & Vector Indexing"]
+        A[Document Text + Metadata] --> B[Embedding Service]
+        A --> C[LLM GraphExtractor]
+        
+        B -->|Vectors| D[post-graph Store]
+        C -->|Entities & Triples| D
+        
+        D --> E[(PostgreSQL + pgvector)]
+        E -->|Tables| E1[documents]
+        E -->|Tables| E2[entities]
+        E -->|Edges| E3[relations]
+        E -->|Edges| E4[doc_mentions]
+    end
+
+    subgraph RETRIEVAL ["2. Hybrid Retrieval & Synthesis"]
+        Q[User Question] --> R[GraphRAG Query Engine]
+        R -->|Embedding| S[pgvector Similarity Search]
+        E1 & E2 -->|Top-K Passages & Entities| S
+        S --> T[1-Hop Graph Relationship Traversal]
+        E3 -->|Subject-Predicate-Object| T
+        
+        S & T --> U[LLM Answer Synthesis]
+        U --> V[Final Answer + Citations + Graph Triples]
+    end
+```
+
+---
+
+## 📦 Installation
+
+Install `post-graph-rag` via `pip` or `uv`:
+
+```bash
+pip install post-graph-rag
+```
+
+Or using `uv`:
+
+```bash
+uv add post-graph-rag
+```
+
+### PostgreSQL Requirements
+Ensure PostgreSQL is running with the `pgvector` extension installed:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Basic Indexing & Querying
+
+```python
+import asyncio
+from post_graph_rag import GraphRAG, RAGConfig, DocumentMetadata
+
+async def main():
+    # 1. Configure GraphRAG engine
+    config = RAGConfig(
+        api_base="http://localhost:4000/v1",       # OpenAI-compatible router endpoint
+        api_key="BEVZ-6L81-OZ8Y",                 # Master or OpenAI API Key
+        model="DeepSeek-V3.2",                    # LLM model for extraction & synthesis
+        embedding_model="text-embedding-3-small", # Embedding model
+        embedding_dim=1536,                       # Vector dimensionality
+        db_uri="postgresql://user:password@localhost:5432/postgres",
+        realm="enterprise_kb"
+    )
+
+    rag = GraphRAG(config)
+    
+    # 2. Connect & initialize PostgreSQL graph schema
+    await rag.initialize()
+
+    # 3. Index unstructured documents
+    doc_text = (
+        "Zeus is the king of the Olympian gods, ruling sky and thunder from Mount Olympus. "
+        "He is the son of Cronus and Rhea, and married to Hera. "
+        "Zeus defeated the Titans in the Titanomachy to establish his rule."
+    )
+    
+    result = await rag.index_document(doc_text, metadata={"source": "greek_mythology.txt"})
+    print(f"Indexed document {result['document_id']}: Extracted {result['entities_extracted']} entities.")
+
+    # 4. Perform Hybrid RAG Query
+    response = await rag.query("Who are the parents of Zeus and what did he defeat?")
+    
+    print("\n=== SYNTHESIZED ANSWER ===")
+    print(response["answer"])
+
+    print("\n=== RETRIEVED GRAPH TRIPLES ===")
+    for triple in response["retrieved_graph_triples"]:
+        print(f"  - {triple}")
+
+    # 5. Clean up
+    await rag.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 📋 Document Metadata (`DocumentMetadata`)
+
+`post-graph-rag` includes structured document metadata tracking via the `DocumentMetadata` model:
+
+```python
+from post_graph_rag import DocumentMetadata
+
+metadata = DocumentMetadata(
+    source="https://mythology.org/zeus.html",  # Document origin (URL, filepath, API)
+    category="greek_mythology",               # Document category/topic
+    collection="olympian_deities",             # Collection namespace
+    document="zeus_overview.pdf",              # Title or filename
+    page=1,                                    # 1-based page number
+    paragraph=2,                               # 1-based paragraph index
+    extra={"author": "Homer", "year": -700}    # Custom metadata key-value pairs
+)
+
+await rag.index_document(chunk_text, metadata=metadata)
+```
+
+### Design Rationale: Optional vs. Required
+- **All metadata fields are optional** with default `None`. This allows seamless indexing of raw strings, short code snippets, webhooks, or unformatted text, while offering rich structural provenance tracking when indexing multi-page PDFs or categorized enterprise documents.
+
+---
+
+## ⚙️ Configuration Reference (`RAGConfig`)
+
+`RAGConfig` can be configured explicitly or automatically loaded from environment variables:
+
+| Option | Environment Variable | Default Value | Description |
+| :--- | :--- | :--- | :--- |
+| `api_base` | `OPENAI_API_BASE` | `http://localhost:4000/v1` | Base URL for OpenAI-compatible LLM endpoint |
+| `api_key` | `OPENAI_API_KEY` | `BEVZ-6L81-OZ8Y` | API Key for authorization |
+| `model` | `RAG_MODEL` | `DeepSeek-V3.2` | Primary LLM model for triple extraction & synthesis |
+| `embedding_model` | `RAG_EMBEDDING_MODEL` | `text-embedding-3-small` | Model for vector embedding generation |
+| `embedding_dim` | `RAG_EMBEDDING_DIM` | `1536` | Dimensionality of embedding vectors |
+| `db_uri` | `POSTGRES_URI` | `postgresql://crajah@localhost:5432/postgres` | PostgreSQL connection DSN |
+| `realm` | `RAG_REALM` | `default` | Multi-tenant graph namespace |
+
+---
+
+## 📖 API Reference
+
+### `GraphRAG`
+The main orchestrator class for indexing and querying.
+
+- `await initialize()`: Connects to PostgreSQL and creates necessary graph tables (`documents`, `entities`, `relations`, `doc_mentions`).
+- `await index_document(text: str, metadata: Optional[Union[Dict[str, Any], DocumentMetadata]] = None) -> Dict[str, Any]`: Computes document embeddings, extracts entity/triple structures via LLM, and persists graph nodes/edges into PostgreSQL.
+- `await query(question: str, top_k: int = 5) -> Dict[str, Any]`: Executes hybrid vector similarity search over documents and entities, traverses 1-hop graph relationship edges, and synthesizes a comprehensive answer. Returns dictionary with `question`, `answer`, `retrieved_documents`, `retrieved_entities`, and `retrieved_graph_triples`.
+- `await close()`: Closes database connection pools.
+
+### `DocumentMetadata`
+Data container for structured document metadata.
+
+- `source: Optional[str]`: Document URL, path, or origin.
+- `category: Optional[str]`: Document category or domain.
+- `collection: Optional[str]`: Document collection or folder.
+- `document: Optional[str]`: File title or filename.
+- `page: Optional[int]`: 1-based page number.
+- `paragraph: Optional[int]`: 1-based paragraph index.
+- `extra: Dict[str, Any]`: Custom user metadata.
+- `to_dict() -> Dict[str, Any]`: Serializes non-None fields to dictionary representation.
+- `from_dict(data: Dict[str, Any]) -> DocumentMetadata`: Deserializes dictionary data.
+
+### `RAGGraphStore`
+Database layer wrapping `post-graph`.
+
+- `add_document(text, embedding, metadata)`: Inserts a document vertex into the `documents` table.
+- `upsert_entity(name, entity_type, description, embedding)`: Upserts an entity vertex into the `entities` table.
+- `add_relation(from_entity, to_entity, relation_type, description)`: Connects entity vertices with a directed relation edge.
+- `search_similar_entities(query_vec, top_k)`: Executes `pgvector` HNSW similarity search over `entities`.
+- `search_similar_documents(query_vec, top_k)`: Executes `pgvector` HNSW similarity search over `documents`.
+
+---
+
+## 🗄️ PostgreSQL Database Schema
+
+`post-graph-rag` automatically provisions and manages the following graph schema in PostgreSQL powered by `post-graph`:
+
+| Table Name | Type | Key Columns | Description |
+| :--- | :--- | :--- | :--- |
+| `{realm}_documents` | Vertex Table | `id`, `payload`, `embedding` (`vector`) | Stores raw text chunks and `DocumentMetadata` payloads |
+| `{realm}_entities` | Vertex Table | `id`, `payload`, `embedding` (`vector`) | Canonical entity nodes (`name`, `type`, `description`) |
+| `{realm}_relations` | Edge Table | `from_id`, `to_id`, `relation_type`, `payload` | Directed edges representing entity-to-entity triples |
+| `{realm}_doc_mentions` | Edge Table | `from_id`, `to_id`, `relation_type` | Directed edges connecting document chunks to mentioned entities |
+| `{table}_audit` | Audit Table | `audit_id`, `action`, `changed_by`, `changed_at` | Automatic shadow audit logging for all graph mutations |
+| `{table}_data` | History Table | `data_id`, `payload`, `timestamp`, `embedding` | Append-only historical records for vertices and edges |
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Developed by **Chandan Rajah** (<chandan.rajah@gmail.com>).

post_graph_rag-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+post_graph_rag/__init__.py,sha256=zHVq43SytgMEBxnfcD9cKAtO2szkNdXywdZs-xr1xcs,611
+post_graph_rag/config.py,sha256=O7YMMOoKUQKN9MDQH1RLp7DygMX4WicF_IenGoB9n10,619
+post_graph_rag/engine.py,sha256=CqPFKQzVsFisFANkNQeya9oB2WltjjjJa3Vq_CYItiM,8440
+post_graph_rag/extractor.py,sha256=zE_wnesnYIfK6dHe_RurSwRhatAabMmSmvLgylJtHE4,4713
+post_graph_rag/graph_store.py,sha256=iPuJ3rz3W8P5BIJ1Lf-AnzFLcTmDUBzpVDqLggX7Jc0,5179
+post_graph_rag/llm.py,sha256=MVX6mD0A47jWlolvinY96CK5y-XBBnxuvDoVz5BGkm8,2797
+post_graph_rag/models.py,sha256=Zj4L_YPybHTDdZkXw2y4utbCB9SQHrRJX5nkvUvgiMg,1929
+post_graph_rag-0.1.0.dist-info/METADATA,sha256=lKtXY8vQZtlZHPDi-hxLnaOwutFKp_wwKSJKjRokx24,10673
+post_graph_rag-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+post_graph_rag-0.1.0.dist-info/licenses/LICENSE,sha256=JEdo9qnu7wdGIr5FHYju6FMZngUsjeWl6gZwGZSQxJE,1070
+post_graph_rag-0.1.0.dist-info/RECORD,,

post_graph_rag-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

post_graph_rag-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chandan Rajah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.