langchain-coordinode 0.4.0__tar.gz

langchain_coordinode-0.4.0/.gitignore

@@ -0,0 +1,23 @@
+# Generated proto stubs — run `make proto` to regenerate
+coordinode/_proto/
+
+# Build artifacts
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Version files generated by hatch-vcs
+coordinode/_version.py
+langchain-coordinode/langchain_coordinode/_version.py
+llama-index-coordinode/llama_index/graph_stores/coordinode/_version.py
+GAPS.md

langchain_coordinode-0.4.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: langchain-coordinode
+Version: 0.4.0
+Summary: LangChain integration for CoordiNode — GraphStore backed by graph + vector + full-text
+Project-URL: Homepage, https://github.com/structured-world/coordinode
+Project-URL: Repository, https://github.com/structured-world/coordinode-python
+Author-email: "structured.world" <dev@structured.world>
+License: Apache-2.0
+Keywords: coordinode,graph,graphrag,langchain,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: coordinode>=0.3.0a1
+Requires-Dist: langchain-community>=0.2.0
+Description-Content-Type: text/markdown
+
+# langchain-coordinode
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-coordinode)](https://pypi.org/project/langchain-coordinode/)
+[![Python](https://img.shields.io/pypi/pyversions/langchain-coordinode)](https://pypi.org/project/langchain-coordinode/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/structured-world/coordinode-python/blob/main/LICENSE)
+[![CI](https://github.com/structured-world/coordinode-python/actions/workflows/ci.yml/badge.svg)](https://github.com/structured-world/coordinode-python/actions/workflows/ci.yml)
+
+[LangChain](https://python.langchain.com/) integration for [CoordiNode](https://github.com/structured-world/coordinode) — `GraphStore` implementation and `GraphCypherQAChain` support for GraphRAG pipelines.
+
+## Installation
+
+```bash
+pip install langchain-coordinode
+```
+
+```bash
+uv add langchain-coordinode
+```
+
+## Requirements
+
+- Python 3.11+
+- Running CoordiNode instance
+
+## Quick Start
+
+### GraphCypherQAChain — Question Answering over a Knowledge Graph
+
+```python
+from langchain_coordinode import CoordinodeGraph
+from langchain.chains import GraphCypherQAChain
+from langchain_openai import ChatOpenAI
+
+# Connect to CoordiNode
+graph = CoordinodeGraph("localhost:7080")
+
+# Build a QA chain that generates and executes Cypher queries
+chain = GraphCypherQAChain.from_llm(
+    ChatOpenAI(model="gpt-4o-mini"),
+    graph=graph,
+    verbose=True,
+)
+
+result = chain.invoke({"query": "What concepts are related to attention mechanisms?"})
+print(result["result"])
+```
+
+### Schema Inspection
+
+```python
+from langchain_coordinode import CoordinodeGraph
+
+graph = CoordinodeGraph("localhost:7080")
+
+# Refresh schema from database
+graph.refresh_schema()
+
+# Schema string used by the LLM to generate Cypher
+print(graph.schema)
+# Node properties: Person (name: String, age: Integer), Concept (name: String) ...
+# Relationships: (Person)-[:KNOWS]->(Person), (Document)-[:ABOUT]->(Concept) ...
+```
+
+### Direct Cypher Queries
+
+```python
+from langchain_coordinode import CoordinodeGraph
+
+graph = CoordinodeGraph("localhost:7080")
+
+# Returns List[Dict[str, Any]]
+result = graph.query(
+    "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = $name RETURN m.name AS colleague",
+    params={"name": "Alice"},
+)
+for row in result:
+    print(row["colleague"])
+```
+
+### LLMGraphTransformer — Extract Knowledge from Text
+
+```python
+from langchain_community.graphs.graph_document import GraphDocument
+from langchain_openai import ChatOpenAI
+from langchain_experimental.graph_transformers import LLMGraphTransformer
+from langchain_coordinode import CoordinodeGraph
+from langchain_core.documents import Document
+
+graph = CoordinodeGraph("localhost:7080")
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
+transformer = LLMGraphTransformer(llm=llm)
+
+docs = [Document(page_content="Alice knows Bob. Bob works at Acme Corp.")]
+graph_docs = transformer.convert_to_graph_documents(docs)
+
+# Store extracted entities and relationships
+graph.add_graph_documents(graph_docs)
+```
+
+## Connection Options
+
+```python
+# host:port string
+graph = CoordinodeGraph("localhost:7080")
+
+# TLS
+graph = CoordinodeGraph("db.example.com:7443", tls=True)
+
+# Custom timeout
+graph = CoordinodeGraph("localhost:7080", timeout=60.0)
+```
+
+## API Reference
+
+### `CoordinodeGraph`
+
+| Method | Description |
+|--------|-------------|
+| `query(query, params)` | Execute Cypher, returns `List[Dict[str, Any]]` |
+| `refresh_schema()` | Reload node/relationship schema from database |
+| `add_graph_documents(docs)` | Batch MERGE nodes + relationships from `GraphDocument` list |
+| `schema` | Schema string for LLM context |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`coordinode`](https://pypi.org/project/coordinode/) | Core gRPC client |
+| [`llama-index-graph-stores-coordinode`](https://pypi.org/project/llama-index-graph-stores-coordinode/) | LlamaIndex `PropertyGraphStore` |
+
+## Links
+
+- [Source](https://github.com/structured-world/coordinode-python)
+- [CoordiNode server](https://github.com/structured-world/coordinode)
+- [LangChain docs](https://python.langchain.com/docs/integrations/graphs/)
+- [Issues](https://github.com/structured-world/coordinode-python/issues)
+
+## Support
+
+<div align="center">
+
+[![USDT TRC-20](https://raw.githubusercontent.com/structured-world/coordinode-python/main/assets/usdt-qr.svg)](https://github.com/sponsors/structured-world)
+
+**USDT (TRC-20):** `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
+
+[GitHub Sponsors](https://github.com/sponsors/structured-world) · [Open Collective](https://opencollective.com/structured-world)
+
+</div>
+
+## License
+
+Apache-2.0

langchain_coordinode-0.4.0/README.md

@@ -0,0 +1,153 @@
+# langchain-coordinode
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-coordinode)](https://pypi.org/project/langchain-coordinode/)
+[![Python](https://img.shields.io/pypi/pyversions/langchain-coordinode)](https://pypi.org/project/langchain-coordinode/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/structured-world/coordinode-python/blob/main/LICENSE)
+[![CI](https://github.com/structured-world/coordinode-python/actions/workflows/ci.yml/badge.svg)](https://github.com/structured-world/coordinode-python/actions/workflows/ci.yml)
+
+[LangChain](https://python.langchain.com/) integration for [CoordiNode](https://github.com/structured-world/coordinode) — `GraphStore` implementation and `GraphCypherQAChain` support for GraphRAG pipelines.
+
+## Installation
+
+```bash
+pip install langchain-coordinode
+```
+
+```bash
+uv add langchain-coordinode
+```
+
+## Requirements
+
+- Python 3.11+
+- Running CoordiNode instance
+
+## Quick Start
+
+### GraphCypherQAChain — Question Answering over a Knowledge Graph
+
+```python
+from langchain_coordinode import CoordinodeGraph
+from langchain.chains import GraphCypherQAChain
+from langchain_openai import ChatOpenAI
+
+# Connect to CoordiNode
+graph = CoordinodeGraph("localhost:7080")
+
+# Build a QA chain that generates and executes Cypher queries
+chain = GraphCypherQAChain.from_llm(
+    ChatOpenAI(model="gpt-4o-mini"),
+    graph=graph,
+    verbose=True,
+)
+
+result = chain.invoke({"query": "What concepts are related to attention mechanisms?"})
+print(result["result"])
+```
+
+### Schema Inspection
+
+```python
+from langchain_coordinode import CoordinodeGraph
+
+graph = CoordinodeGraph("localhost:7080")
+
+# Refresh schema from database
+graph.refresh_schema()
+
+# Schema string used by the LLM to generate Cypher
+print(graph.schema)
+# Node properties: Person (name: String, age: Integer), Concept (name: String) ...
+# Relationships: (Person)-[:KNOWS]->(Person), (Document)-[:ABOUT]->(Concept) ...
+```
+
+### Direct Cypher Queries
+
+```python
+from langchain_coordinode import CoordinodeGraph
+
+graph = CoordinodeGraph("localhost:7080")
+
+# Returns List[Dict[str, Any]]
+result = graph.query(
+    "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = $name RETURN m.name AS colleague",
+    params={"name": "Alice"},
+)
+for row in result:
+    print(row["colleague"])
+```
+
+### LLMGraphTransformer — Extract Knowledge from Text
+
+```python
+from langchain_community.graphs.graph_document import GraphDocument
+from langchain_openai import ChatOpenAI
+from langchain_experimental.graph_transformers import LLMGraphTransformer
+from langchain_coordinode import CoordinodeGraph
+from langchain_core.documents import Document
+
+graph = CoordinodeGraph("localhost:7080")
+llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
+transformer = LLMGraphTransformer(llm=llm)
+
+docs = [Document(page_content="Alice knows Bob. Bob works at Acme Corp.")]
+graph_docs = transformer.convert_to_graph_documents(docs)
+
+# Store extracted entities and relationships
+graph.add_graph_documents(graph_docs)
+```
+
+## Connection Options
+
+```python
+# host:port string
+graph = CoordinodeGraph("localhost:7080")
+
+# TLS
+graph = CoordinodeGraph("db.example.com:7443", tls=True)
+
+# Custom timeout
+graph = CoordinodeGraph("localhost:7080", timeout=60.0)
+```
+
+## API Reference
+
+### `CoordinodeGraph`
+
+| Method | Description |
+|--------|-------------|
+| `query(query, params)` | Execute Cypher, returns `List[Dict[str, Any]]` |
+| `refresh_schema()` | Reload node/relationship schema from database |
+| `add_graph_documents(docs)` | Batch MERGE nodes + relationships from `GraphDocument` list |
+| `schema` | Schema string for LLM context |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`coordinode`](https://pypi.org/project/coordinode/) | Core gRPC client |
+| [`llama-index-graph-stores-coordinode`](https://pypi.org/project/llama-index-graph-stores-coordinode/) | LlamaIndex `PropertyGraphStore` |
+
+## Links
+
+- [Source](https://github.com/structured-world/coordinode-python)
+- [CoordiNode server](https://github.com/structured-world/coordinode)
+- [LangChain docs](https://python.langchain.com/docs/integrations/graphs/)
+- [Issues](https://github.com/structured-world/coordinode-python/issues)
+
+## Support
+
+<div align="center">
+
+[![USDT TRC-20](https://raw.githubusercontent.com/structured-world/coordinode-python/main/assets/usdt-qr.svg)](https://github.com/sponsors/structured-world)
+
+**USDT (TRC-20):** `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
+
+[GitHub Sponsors](https://github.com/sponsors/structured-world) · [Open Collective](https://opencollective.com/structured-world)
+
+</div>
+
+## License
+
+Apache-2.0

langchain_coordinode-0.4.0/langchain_coordinode/__init__.py

@@ -0,0 +1,6 @@
+"""LangChain integration for CoordiNode."""
+
+from langchain_coordinode.graph import CoordinodeGraph
+
+__version__ = "0.3.0a1"
+__all__ = ["CoordinodeGraph"]

langchain_coordinode-0.4.0/langchain_coordinode/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
+
+__commit_id__ = commit_id = None

langchain_coordinode-0.4.0/langchain_coordinode/graph.py

@@ -0,0 +1,185 @@
+"""CoordinodeGraph — LangChain GraphStore backed by CoordiNode."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from langchain_community.graphs.graph_store import GraphStore
+
+from coordinode import CoordinodeClient
+
+
+class CoordinodeGraph(GraphStore):
+    """LangChain `GraphStore` backed by CoordiNode.
+
+    Supports ``GraphCypherQAChain`` and any LangChain component that works
+    with a ``GraphStore``.
+
+    Example::
+
+        from langchain_coordinode import CoordinodeGraph
+        from langchain.chains import GraphCypherQAChain
+        from langchain_openai import ChatOpenAI
+
+        graph = CoordinodeGraph("localhost:7080")
+        chain = GraphCypherQAChain.from_llm(
+            ChatOpenAI(model="gpt-4o-mini"),
+            graph=graph,
+            verbose=True,
+        )
+        result = chain.invoke("What concepts are related to machine learning?")
+
+    Args:
+        addr: CoordiNode gRPC address, e.g. ``"localhost:7080"``.
+        database: Database name (reserved for future multi-db support).
+        timeout: Per-request gRPC deadline in seconds.
+    """
+
+    def __init__(
+        self,
+        addr: str = "localhost:7080",
+        *,
+        database: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = CoordinodeClient(addr, timeout=timeout)
+        self._schema: str | None = None
+        self._structured_schema: dict[str, Any] | None = None
+
+    # ── GraphStore interface ──────────────────────────────────────────────
+
+    @property
+    def schema(self) -> str:
+        """Return cached schema string (refreshed by `refresh_schema`)."""
+        if self._schema is None:
+            self.refresh_schema()
+        return self._schema or ""
+
+    @property
+    def structured_schema(self) -> dict[str, Any]:
+        """Return structured schema dict (refreshed by `refresh_schema`)."""
+        if self._structured_schema is None:
+            self.refresh_schema()
+        return self._structured_schema or {}
+
+    def refresh_schema(self) -> None:
+        """Fetch current schema from CoordiNode."""
+        text = self._client.get_schema_text()
+        self._schema = text
+        structured = _parse_schema(text)
+        # Augment with relationship triples (start_label, type, end_label) via
+        # Cypher — get_schema_text() only lists edge types without direction.
+        try:
+            rows = self._client.cypher(
+                "MATCH (a)-[r]->(b) RETURN DISTINCT labels(a)[0] AS src, type(r) AS rel, labels(b)[0] AS dst"
+            )
+            structured["relationships"] = [
+                {"start": row["src"], "type": row["rel"], "end": row["dst"]}
+                for row in rows
+                if row.get("src") and row.get("rel") and row.get("dst")
+            ]
+        except Exception:  # noqa: BLE001
+            pass  # Graph may have no relationships yet; structured["relationships"] stays []
+        self._structured_schema = structured
+
+    def query(
+        self,
+        query: str,
+        params: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Run a Cypher query and return rows as dicts.
+
+        Args:
+            query: OpenCypher query string.
+            params: Optional query parameters.
+
+        Returns:
+            List of row dicts (column name → value).
+        """
+        # cypher() returns List[Dict[str, Any]] directly — column name → value.
+        return self._client.cypher(query, params=params or {})
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Close the underlying gRPC connection."""
+        self._client.close()
+
+    def __enter__(self) -> CoordinodeGraph:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+# ── Schema parser ─────────────────────────────────────────────────────────
+
+
+def _parse_schema(schema_text: str) -> dict[str, Any]:
+    """Convert CoordiNode schema text into LangChain's structured format.
+
+    LangChain's ``GraphCypherQAChain`` expects::
+
+        {
+            "node_props": {"Label": [{"property": "name", "type": "STRING"}, ...]},
+            "rel_props":  {"TYPE":  [{"property": "weight", "type": "FLOAT"}, ...]},
+            "relationships": [{"start": "A", "type": "REL", "end": "B"}, ...],
+        }
+
+    CoordiNode's schema text format (from ``get_schema_text()``)::
+
+        Node labels:
+          - Person (properties: name: STRING, age: INT64)
+          - Company
+
+        Edge types:
+          - KNOWS (properties: since: INT64)
+          - WORKS_FOR
+
+    We parse inline ``(properties: ...)`` lists on each bullet line.
+    For reliable structured access use the gRPC ``SchemaService`` directly.
+    """
+    node_props: dict[str, list[dict[str, str]]] = {}
+    rel_props: dict[str, list[dict[str, str]]] = {}
+    relationships: list[dict[str, str]] = []
+
+    in_nodes = False
+    in_rels = False
+
+    for line in schema_text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        if stripped.lower().startswith("node labels"):
+            in_nodes, in_rels = True, False
+            continue
+        # Accept both "Edge types:" (current format) and "Relationship types:" (legacy)
+        if stripped.lower().startswith("edge types") or stripped.lower().startswith("relationship types"):
+            in_nodes, in_rels = False, True
+            continue
+
+        if (in_nodes or in_rels) and (stripped.startswith("-") or stripped.startswith("*")):
+            # Extract name (part before optional "(properties: ...)")
+            name = stripped.lstrip("-* ").split("(")[0].strip()
+            if not name:
+                continue
+            # Parse inline properties: "- Label (properties: prop1: TYPE, prop2: TYPE)"
+            props: list[dict[str, str]] = []
+            m = re.search(r"\(properties:\s*([^)]+)\)", stripped)
+            if m:
+                for prop_str in m.group(1).split(","):
+                    kv = prop_str.strip().split(":", 1)
+                    if len(kv) == 2:
+                        props.append({"property": kv[0].strip(), "type": kv[1].strip()})
+            if in_nodes:
+                node_props[name] = props
+            else:
+                rel_props[name] = props
+
+    return {
+        "node_props": node_props,
+        "rel_props": rel_props,
+        "relationships": relationships,
+    }

langchain_coordinode-0.4.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-coordinode"
+dynamic = ["version"]
+description = "LangChain integration for CoordiNode — GraphStore backed by graph + vector + full-text"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "structured.world", email = "dev@structured.world" }]
+keywords = ["langchain", "graph", "rag", "graphrag", "coordinode"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "coordinode>=0.3.0a1",
+    "langchain-community>=0.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/structured-world/coordinode"
+Repository = "https://github.com/structured-world/coordinode-python"
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = "v(?P<version>.*)"
+fallback-version = "0.0.0"
+raw-options = {root = ".."}
+
+[tool.hatch.build.hooks.vcs]
+version-file = "langchain_coordinode/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_coordinode"]