grip-protocol 0.1.0__py3-none-any.whl

grip_protocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: grip-protocol
+Version: 0.1.0
+Summary: Universal GraphRAG Interoperability Protocol (GRIP) — 27-tool MCP server, verifiable provenance, and standard contracts for knowledge graph RAG
+Author: graphrag-protocol contributors
+License: MIT
+Keywords: graphrag,knowledge-graph,mcp,retrieval,graph,protocol,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv
+Requires-Dist: mcp>=2
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: httpx
+Provides-Extra: tigergraph
+Requires-Dist: pyTigerGraph; extra == "tigergraph"
+Provides-Extra: llm
+Requires-Dist: google-genai; extra == "llm"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: rag
+Requires-Dist: chromadb; extra == "rag"
+Provides-Extra: eval
+Requires-Dist: bert-score; extra == "eval"
+Provides-Extra: all
+Requires-Dist: pyTigerGraph; extra == "all"
+Requires-Dist: google-genai; extra == "all"
+Requires-Dist: chromadb; extra == "all"
+Requires-Dist: bert-score; extra == "all"
+
+# GraphRAG Protocol
+
+**Universal GraphRAG Interoperability Protocol** — standard contracts + MCP server + adapters so *any agent can query any GraphRAG backend uniformly*.
+
+Every GraphRAG engine (TigerGraph, Neo4j, LightRAG, LlamaIndex, FalkorDB, Microsoft GraphRAG) reinvents retrieval, subgraph serialization, provenance, and evaluation with incompatible interfaces. This protocol fills the missing middle layer between **GQL** (graph query standard at the bottom) and **MCP** (agent connectivity standard at the top): a uniform retrieval contract any backend can implement and any agent can call.
+
+## Quick Start
+
+```bash
+# 1. Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+
+# 2. Install the package (with dev dependencies)
+pip install -e ".[dev]"
+
+# 3. Copy the env template and fill in your backend credentials
+cp .env.example .env
+# E.g. TIGERGRAPH_HOST, TIGERGRAPH_GSQL_SECRET, GOOGLE_API_KEY
+
+# 4. Inspect the protocol types
+python -c "from mcp_server.protocol import SubgraphContext, RetrievalRequest; print('protocol OK')"
+
+# 5. Start the MCP server (stdio transport — what agents launch)
+python -m mcp_server.mcp_server      # or the `graphrag-mcp` entrypoint
+
+# 6. Start the HTTP dashboard server (FastAPI, binds 127.0.0.1:8000)
+python -m mcp_server.server          # or the `graphrag-server` entrypoint
+```
+
+Requires Python 3.10+. Optional extras: `pip install -e ".[server,tigergraph,llm]"`.
+
+## Backends
+
+**TigerGraph (Savanna) is the only backend this project targets.** The adapter
+(`mcp_server/adapters/tigergraph_adapter.py`) talks to a live workspace over
+pyTigerGraph REST++ and installs its GSQL queries idempotently on first use.
+`mcp_server/adapters/fallback_adapter.py` is a clearly-labeled in-memory adapter
+for tests and offline development — it is read-only, never presented as
+TigerGraph, and never used to fabricate an answer.
+
+## Ingesting documents (Contract 4)
+
+Writes are real TigerGraph upserts and every counter in the report is measured
+from the backend (`getVertexCount` before/after, existence probes per entity):
+
+```bash
+# Self-test: ingest a document, read it back, delete it again
+.venv/bin/python scripts/smoke_construction.py
+```
+
+Write operations (ingest / update / delete) require the admin token
+(Contract 10, `GRAPHRAG_ADMIN_TOKEN`); without it they fail closed with 403.
+Ingestion also publishes Contract 7 events at the mutation point, which the
+dashboard consumes over SSE at `/stream/events`.
+
+## Running the tests
+
+```bash
+pytest                    # hermetic unit suite (no creds, no network)
+pytest -m integration     # live TigerGraph + Gemini tests (self-skip without creds)
+ruff check mcp_server/ hackathon/ tests/
+```
+
+
+## The 10 Contracts
+
+| # | Contract | What it standardizes | Implementation |
+|---|----------|----------------------|----------------|
+| 1 | **Retrieval** | Standard request envelope + 7 operations (`local_search`, `global_search`, `hybrid_search`, `entity_lookup`, `path_search`, `neighborhood`, `community_members`) | `contracts/retrieval.py` — done, real |
+| 2 | **Subgraph Context** | Uniform response: entities, relationships, paths, communities, text chunks | `protocol.py` — done, real |
+| 3 | **Schema Discovery** | Backend-agnostic schema introspection for LLM planning | `contracts/schema_discovery.py` — done, real |
+| 4 | **Construction** | Document → knowledge-graph ingestion pipeline | `contracts/construction.py` — done, real writes |
+| 5 | **Provenance** | Citation & audit trail, incl. entities *visited but not cited* | `contracts/provenance.py` — done, real |
+| 6 | **Federation** | Query multiple graphs + transparent result merging | `contracts/federation.py` — done, real fan-out |
+| 7 | **Streaming** | Real-time graph change events | `contracts/streaming.py` — done, real pub/sub + SSE |
+| 8 | **Prompt Formatting** | Context → LLM-ready, token-bounded text | `formatters/` — done (`PromptFormatConfig` model + schema) |
+| 9 | **Evaluation** | Standard, backend-comparable metrics | `contracts/evaluation.py` — done; judge/BERTScore `null` when unavailable |
+| 10 | **Authorization** | Per-operation permission model | `contracts/authorization.py` — done, enforced on writes |
+
+JSON Schemas for all 10 contracts live in `schemas/`; `tests/test_schemas.py`
+fails if any schema drifts from its Pydantic model.
+
+## Repo Layout
+
+```
+graphrag-protocol/
+├── SPEC.md                      # Full protocol specification
+├── schemas/                     # JSON Schema definitions (language-agnostic)
+│   ├── retrieval-request.json   # Contract 1
+│   ├── subgraph-context.json    # Contract 2
+│   ├── graph-schema.json        # Contract 3
+│   ├── ingestion-config.json    # Contract 4 (+ IngestionReport, Triple)
+│   ├── provenance.json          # Contract 5
+│   ├── federation-config.json   # Contract 6
+│   ├── stream-event.json        # Contract 7
+│   ├── prompt-format-config.json# Contract 8
+│   ├── evaluation-report.json   # Contract 9
+│   └── access-policy.json       # Contract 10
+├── mcp_server/                  # Reference implementation
+│   ├── protocol.py              # Canonical Pydantic v2 models (contracts 1-5, 8)
+│   ├── protocol_extensions.py   # Models for contracts 4, 6, 7, 9, 10
+│   ├── contracts/               # Contract layer: retrieval, schema, provenance,
+│   │                            # construction, federation, streaming, evaluation, authorization
+│   ├── adapters/                # TigerGraph (real) + labeled in-memory demo adapter
+│   ├── formatters/              # Contract 8: Markdown / structured, token-bounded
+│   ├── pipelines.py             # Shared 3-pipeline runner (server + eval harness)
+│   ├── mcp_server.py            # MCP stdio server (27 tools)
+│   └── server.py                # FastAPI dashboard server (+ SSE event feed)
+├── frontend/                    # Next.js 14 dashboard (query lab, graph, benchmark, ingest & stream)
+├── hackathon/                   # TigerGraph dataset, GSQL loaders, evaluation harness
+├── scripts/                     # Live smoke tests (construction, connection)
+├── tests/                       # Hermetic unit suite + `integration` live tests
+└── pyproject.toml
+```
+
+
+## License
+
+MIT

grip_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+mcp_server/__init__.py,sha256=kpMwSBnU1MmywFOuYzWxuO82eybX1WpdDOebSUDSuQU,94
+mcp_server/mcp_server.py,sha256=xCYU2GUkMneHHvHhlCKA3fd-nijTVYy3P-VXhabHbaY,24177
+mcp_server/pipelines.py,sha256=mVFJYsl1AYi911DE3gLsU_RL4HbO6gFxda2067DfErU,7999
+mcp_server/protocol.py,sha256=KnbOuqby_wMGvggFY4Nwi2CL6GrRug45TzYDDQD0bKU,13787
+mcp_server/protocol_extensions.py,sha256=U53EljUeUjjLBTb_4hrHw9SZQ4rwbKnmnJvUnVfhvyc,10826
+mcp_server/server.py,sha256=gKpqluEZzIkFJBaarsWD75KpHCtiX9NvKmLhDj-CTDM,12971
+mcp_server/adapters/__init__.py,sha256=boO8TkJwBHEv1209ppF6P2IAN-tmJqVVcQClvZD9YvU,267
+mcp_server/adapters/base.py,sha256=jjg_Kg53X388KVGqaxmljFswBLqtD2hu3Vv1S80Q7dQ,3580
+mcp_server/adapters/fallback_adapter.py,sha256=CDcz82f37hvkM4f5X1VvEWGiXYsfzTGnv9g7rNv2FUo,13387
+mcp_server/adapters/tigergraph_adapter.py,sha256=mrSu59f_aV2BmNKDSBDWIxV8rkTZaV0XYrjKPnvq470,44193
+mcp_server/adapters/tigergraph_queries.py,sha256=CYN6IvV06CS70QwtXqVa_fmQtxeOK--2VSuzZfscQmE,9942
+mcp_server/contracts/__init__.py,sha256=U7JJV7niqf8D9QyjoEqbOcOMM9y56KpfmD5LJbIwC9A,1226
+mcp_server/contracts/authorization.py,sha256=6bPJen-Dk8cNmKhvPZvUZU4bxzHw9WtIYBw9qxMxIb0,5483
+mcp_server/contracts/base.py,sha256=9ah8F_-hYnMSsaYhcuJHnSWLy93Hbr_cwkXNd215dwE,6464
+mcp_server/contracts/construction.py,sha256=ahxzruDEbZjJbroSSNjxqKY0dVcgbyD2r33LO0GJk6M,23159
+mcp_server/contracts/evaluation.py,sha256=fv9JsA_KJcySrCE6yB4I0raR_9Y1yLwQ7jvxB6rip7A,14779
+mcp_server/contracts/federation.py,sha256=V759uY_bWmkLAXO67mUbPMcaO4JHOj0cPziGWFwP5e8,16433
+mcp_server/contracts/provenance.py,sha256=iHFxWPOEnsjgIs5cvqrXR6qP0bzwv3cS_OCFfo4oimo,10253
+mcp_server/contracts/retrieval.py,sha256=7klYU3gl738-tewd9A2SEp3omi2bXwa1M6z-k2ABRBY,18922
+mcp_server/contracts/schema_discovery.py,sha256=vIDFAdsDLkdfhhm0PkRUEkb1lrTfRkdjvpr-1ECXSS4,7939
+mcp_server/contracts/streaming.py,sha256=IRX3iiICndZeVk0tBEM7VAPrRzYc_cfx3a3KGqhY5Ew,9129
+mcp_server/formatters/__init__.py,sha256=vF-GVHPa9nPU599Tnr1DqlbixWGSiStfoNZ95r1XeaY,275
+mcp_server/formatters/base.py,sha256=LsgTtVBQx601NyYSgDagm2LVBGgAEDIJLz7udrwziZI,1414
+mcp_server/formatters/markdown_formatter.py,sha256=AKQQvbIGLHM3Qg5F1Ei7ZTx2jgWkgK9T01wgVh3Mvi0,7410
+mcp_server/formatters/structured_formatter.py,sha256=QGepnWF_aa9EU5gU1VgAbh0o-eP3JFsg-KUwW4LV0Ss,7621
+grip_protocol-0.1.0.dist-info/METADATA,sha256=9hwNaMzG6or98FuVC0bIjmWqas4-qkPMgvdjvqO5_hw,8037
+grip_protocol-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+grip_protocol-0.1.0.dist-info/entry_points.txt,sha256=CHzLXBNV52hovbeZEUjQYLWRPV1gOygsBTkPdzPSpEo,210
+grip_protocol-0.1.0.dist-info/top_level.txt,sha256=R49ZBwHkJvJ-AJ8o9wy6MuCs0rvZpyCEuvdwhI4PpHs,11
+grip_protocol-0.1.0.dist-info/RECORD,,

grip_protocol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

grip_protocol-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+graphrag-mcp = mcp_server.mcp_server:main
+graphrag-server = mcp_server.server:main
+grip = mcp_server.mcp_server:main
+grip-mcp = mcp_server.mcp_server:main
+grip-server = mcp_server.server:main

grip_protocol-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server

mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""graphrag-protocol: Universal GraphRAG Interoperability Protocol."""
+
+__version__ = "0.1.0"

mcp_server/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Backend adapters for the GraphRAG Protocol."""
+
+from .base import BaseGraphRAGAdapter
+from .fallback_adapter import DemoGraphRAGAdapter
+from .tigergraph_adapter import TigerGraphAdapter
+
+__all__ = ["BaseGraphRAGAdapter", "DemoGraphRAGAdapter", "TigerGraphAdapter"]

mcp_server/adapters/base.py

@@ -0,0 +1,128 @@
+"""Abstract GraphRAG backend adapter interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from mcp_server.protocol import (
+    GraphSchema,
+    Provenance,
+    SubgraphContext,
+)
+
+
+class BaseGraphRAGAdapter(ABC):
+    """Abstract adapter every GraphRAG backend must implement.
+
+    Extends the retrieval contract with schema discovery, provenance
+    extraction, and health reporting. Concrete adapters (TigerGraph,
+    Neo4j, LightRAG, vector stores, ...) translate these standard
+    operations onto their native query APIs.
+    """
+
+    @abstractmethod
+    def local_search(
+        self,
+        query: str,
+        entity_hints: list[str] | None = None,
+        depth: int = 2,
+        top_k: int = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> SubgraphContext:
+        """Precise, entity-centric retrieval around matched entities.
+
+        Seeds from ``entity_hints`` (or entities matched from ``query``),
+        expands up to ``depth`` hops, and returns the most relevant
+        entities, relationships, and supporting text chunks.
+        """
+        ...
+
+    @abstractmethod
+    def global_search(
+        self,
+        query: str,
+        community_level: int = 2,
+        top_communities: int = 10,
+    ) -> SubgraphContext:
+        """Broad, corpus-level retrieval via community summaries."""
+        ...
+
+    @abstractmethod
+    def hybrid_search(
+        self,
+        query: str,
+        vector_weight: float = 0.5,
+        graph_weight: float = 0.5,
+        top_k: int = 10,
+        depth: int = 2,
+    ) -> SubgraphContext:
+        """Combined vector-similarity + graph-structure retrieval."""
+        ...
+
+    @abstractmethod
+    def entity_lookup(
+        self,
+        entity_id: str | None = None,
+        entity_name: str | None = None,
+        entity_type: str | None = None,
+        depth: int = 1,
+    ) -> SubgraphContext:
+        """Fetch a specific entity and its immediate context."""
+        ...
+
+    @abstractmethod
+    def path_search(
+        self,
+        source: str,
+        target: str,
+        max_hops: int = 4,
+    ) -> SubgraphContext:
+        """Find paths between two entities."""
+        ...
+
+    @abstractmethod
+    def neighborhood(
+        self,
+        entity_id: str,
+        depth: int = 2,
+        edge_types: list[str] | None = None,
+    ) -> SubgraphContext:
+        """Expand outward from an entity within ``depth`` hops."""
+        ...
+
+    @abstractmethod
+    def community_members(
+        self,
+        community_id: str,
+        include_summary: bool = True,
+    ) -> SubgraphContext:
+        """List member entities of a community (optionally with summary)."""
+        ...
+
+    @abstractmethod
+    def get_schema(self, graph_id: str | None = None) -> GraphSchema:
+        """Introspect the graph schema.
+
+        Returns vertex/edge types, attributes, cardinalities, and
+        graph-level statistics in the standard GraphSchema form.
+        """
+        ...
+
+    @abstractmethod
+    def get_provenance(self, context: SubgraphContext) -> Provenance:
+        """Extract the citation and audit trail for a retrieval context.
+
+        Reconstructs source documents, traversal steps, and visited-but-
+        not-cited entities from the adapter's internal execution state.
+        """
+        ...
+
+    @abstractmethod
+    def health_check(self) -> dict:
+        """Report backend connectivity and health.
+
+        Returns a dict with at least ``status`` ("ok"/"error"), and
+        typically ``backend`` and ``version`` keys.
+        """
+        ...