ragleap-graph 0.1.0__tar.gz

ragleap_graph-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Environment
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+venv/
+.venv/
+
+# Node
+node_modules/
+
+# Docker
+docker-compose.override.yml
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+.env
+
+# Package build artifacts
+dist/
+build/

ragleap_graph-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `ragleap-graph` are documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial implementation: `GraphConfig` and `GraphIndex`, knowledge-graph-augmented retrieval for RAG systems via Neo4j.
+- Ported from a real, production `GraphService` (Neo4j-backed, regex entity extraction, co-occurrence graph construction), with deliberate adaptations for standalone open-source use:
+  - `workspace_id` (required, Django multi-tenant SaaS concept) generalized to an optional `namespace=` parameter, defaulting to `None` — mirrors `ragleap-rag`'s own `metadata_filter=` convention.
+  - Django `settings` coupling replaced with an explicit `GraphConfig` dataclass — zero framework dependency, same pattern as `ragleap-rag`'s `EmbeddingConfig`/`ProviderConfig`.
+  - A hardcoded, deployment-specific domain vocabulary list (radiation-safety/medical-physics terms) found in the source was **not** carried over as a hardcoded default — it's now an optional `domain_terms=` parameter instead, since shipping someone else's internal business vocabulary as a public library default would be inappropriate and actively wrong for other domains.
+- 5 core methods: `upsert_document`, `find_documents_by_entities`, `search_related_entities`, `document_entities`, `health_check`.
+- **Real security fix vs. the source this was ported from**: `search_related_entities()`'s `max_depth` parameter is validated as a bounded integer (1-10) before being used in Cypher query construction. The source interpolated this value into the query string unvalidated (`.format(max_depth=max_depth)`) — necessary because Neo4j's Cypher can't parameterize variable-length path bounds normally, but that means unvalidated input would be a real injection vector in a public library API accepting arbitrary caller input.
+- **Real bug found and fixed during implementation** (not just written and assumed correct): `GraphDatabase.driver()` is lazy — it does not attempt a real connection at construction time. Without an explicit `verify_connectivity()` call, a bad URI/credentials would silently leave `self.driver` set to a non-functional object instead of `None`, breaking the documented "driver is None means unavailable" contract. Caught by a real test failure, not assumed correct — see the test suite for the exact scenario.
+- 26 tests: pure-logic tests (entity normalization, extraction, `max_depth` validation) requiring no live Neo4j, driver-unavailable graceful-degradation tests for every public method, and one live end-to-end integration test (write, query three ways, verified self-cleanup — 0 nodes left behind) that runs automatically when real `NEO4J_URI`/`NEO4J_USER`/`NEO4J_PASSWORD` credentials are present, and skips cleanly otherwise.
+- CI: dedicated `ragleap-graph-tests` job with a real Neo4j service container, mirroring `ragleap-rag-tests`' pattern — confirmed passing in GitHub's own CI environment, not just locally.
+- **This is the first package in the ragleap ecosystem with genuine, complete live verification from day one** — unlike several `ragleap-rag` vector backends, which shipped honestly labeled "code-complete but unverified" due to no account access. Real Neo4j access was already available, so every method here has actually been proven to work end-to-end, not just tested in isolation.
+
+- **Second real bug found and fixed during implementation**: `search_related_entities()` originally validated `max_depth` *after* checking driver availability, so invalid `max_depth` input silently returned `[]` instead of raising — when it should raise regardless of connection state. Caught by a real test failure. Fixed by validating `max_depth` first, before any driver-availability check.

ragleap_graph-0.1.0/HANDOFF.md

@@ -0,0 +1,159 @@
+# ragleap-graph — Build Handoff Document
+
+**Purpose:** continuity doc for a new chat session to resume building
+`ragleap-graph`. Scoping is done; implementation hasn't started.
+
+---
+
+## Current state
+
+- **Package skeleton created** at `~/ragleap-core/packages/ragleap-graph/`
+  on the VPS (`srv1477778`)
+- `pyproject.toml` written and matches `ragleap-rag`'s exact conventions
+  (hatchling build backend, same author/license/classifiers pattern).
+  Verified complete via direct `cat` inspection (not `tomllib` — that
+  module wasn't available in the system Python being used; real
+  validation will happen when `hatchling` actually builds the package)
+- Directory structure: `src/ragleap_graph/` and `tests/` both exist,
+  currently empty
+- **Nothing has been coded yet** — no `GraphConfig`, no `GraphIndex`,
+  no tests
+
+## Where the real production code lives (read this first, don't guess)
+
+`cdprod` → `/var/www/ragleap/backends/claude_backend` (the private
+production Django backend — NOT the `ragleap-core` public monorepo,
+don't confuse the two, this has bitten this session before).
+
+Core files, already reviewed this session:
+- `retrieval/graph_service.py` — 563 lines, the real `GraphService` class
+- `retrieval/neo4j_startup.py` — 293 lines, connection/startup logic
+
+28 files across 8 Django apps reference Neo4j/graph in some way, but
+match-density analysis (`grep -c`) confirmed these two files are where
+the actual logic lives — everything else is either a consumer calling
+into `GraphService` or a passing reference (settings flag, migration
+field). Full file list and match counts are in this session's history
+if needed again, but the two files above are the ones that matter.
+
+## The 5 real methods to port (verified via direct code review)
+
+| Production method (Django-coupled) | Target public API | What it does |
+|---|---|---|
+| `upsert_document_graph(document_id, workspace_id, document_title, chunks, language=None, max_entities=80, max_pairs=150)` | `graph.upsert_document(...)` | Regex-based entity extraction per chunk, builds co-occurrence edges between entities in the same chunk, `MERGE`-based idempotent Neo4j writes |
+| `find_documents_by_entities(entity_names, workspace_id, limit=25)` | `graph.find_documents_by_entities(...)` | Given entity names, returns documents connected to them, ranked by matched-entity count + summed edge weight |
+| `search_related_entities(entity_names, workspace_id, max_depth=2, limit=10)` | `graph.search_related_entities(...)` | Graph traversal — finds entities related via N-hop paths |
+| `find_document_entities(document_id, workspace_id, entity_types=None)` | `graph.document_entities(...)` | Per-document entity lookup, optional type filter |
+| `health_check()` | `graph.health_check()` | Already generic, minimal changes needed |
+
+Full method bodies (Cypher queries, exact logic) were reviewed line by
+line this session — if this handoff doc is being read fresh without
+that history, re-fetch them from the production file directly rather
+than guessing at the Cypher:
+
+```bash
+cdprod
+sed -n '1,60p' ./retrieval/graph_service.py      # class init, entity normalization
+sed -n '163,326p' ./retrieval/graph_service.py   # upsert_document_graph, full body
+sed -n '326,548p' ./retrieval/graph_service.py   # find_documents_by_entities, search_related_entities, find_document_entities, health_check
+```
+
+## Two required adaptations — decided, not open questions
+
+### 1. `workspace_id` → optional `namespace=`
+
+**Decision made and confirmed this session**: production code requires
+`workspace_id` on every method (Django multi-tenant SaaS assumption).
+For the open-source package, this becomes an **optional** `namespace=`
+parameter, defaulting to `None`:
+
+```python
+graph.upsert_document(document_id="...", title="...", chunks=[...])                    # single global graph
+graph.upsert_document(document_id="...", title="...", chunks=[...], namespace="acme")  # multi-tenant isolated
+```
+
+This mirrors `ragleap-rag`'s own `metadata_filter=` pattern — optional,
+generic, doesn't force one usage model onto every user. This is the
+established, deliberate convention for this ecosystem; don't relitigate
+it without a real reason.
+
+### 2. Django `settings` coupling → explicit `GraphConfig`
+
+Production code does `from django.conf import settings` and
+`getattr(settings, 'NEO4J_URI', ...)`. The package needs a config
+dataclass instead, matching `ragleap-rag`'s `EmbeddingConfig`/
+`ProviderConfig` pattern:
+
+```python
+from ragleap_graph import GraphIndex, GraphConfig
+
+graph = GraphIndex(config=GraphConfig(
+    uri="bolt://localhost:7687",
+    user="neo4j",
+    password="...",
+))
+```
+
+## One real security fix required before shipping
+
+`search_related_entities()` builds its Cypher query using
+**`.format(max_depth=max_depth)`** to inject the traversal depth
+directly into the query string (`[*1..{max_depth}]`), rather than using
+parameterized query args like every other method in the file. This is
+likely a genuine Neo4j limitation (Cypher can't parameterize
+variable-length path bounds normally) — but as a **public library API**
+accepting `max_depth` from any caller, this needs explicit validation
+(`isinstance(max_depth, int)` and a sane upper bound, e.g. reject
+values > 10) before string formatting, or it's a real Cypher injection
+vector. Don't carry this over unguarded.
+
+## Package conventions to follow (from `ragleap-rag`, don't reinvent)
+
+- `pyproject.toml`: hatchling build backend, same classifiers/license
+  pattern, `[project.optional-dependencies]` with a `test` extra
+- Version bumps go in both `pyproject.toml` and
+  `src/ragleap_graph/__init__.py`'s `__version__` — grep-check both
+- CHANGELOG.md discipline: never rewrite past entries, add corrections
+  as new entries
+- For any third-party SDK usage (the `neo4j` Python driver), verify
+  exact method signatures via `inspect.signature()` against the real
+  installed package before writing code — don't trust memory or docs.
+  This caught a real pre-ship bug in `PineconeBackend` before; apply the
+  same discipline here.
+- Full test suite must pass before any commit is considered done — this
+  project's standard, demonstrated repeatedly (238/238 for `ragleap-rag`)
+- Live-verification advantage specific to this package: **you have real,
+  working Neo4j access already** (it's live in production) — meaning
+  `ragleap-graph` can be fully live-verified from day one, unlike several
+  `ragleap-rag` vector backends that shipped honestly labeled
+  "code-complete but unverified" due to no account access. Don't skip
+  the live verification just because it's more available this time —
+  make sure it actually happens.
+
+## Immediate next steps for the new session
+
+1. Write `src/ragleap_graph/__init__.py` with `GraphConfig` and
+   `GraphIndex` classes, porting the 5 methods above with the two
+   adaptations (namespace, config) and the `max_depth` fix applied
+2. Write a real `README.md` for the package (required — `pyproject.toml`
+   already references `readme = "README.md"` and will fail to build
+   without it)
+3. Write tests — mirror `ragleap-rag`'s test structure (constructor
+   validation, pure logic tests where possible without a live Neo4j,
+   then real integration tests against your actual working Neo4j
+   instance)
+4. Verify build: `python3 -m build` inside
+   `~/ragleap-core/packages/ragleap-graph/`
+5. Only after tests pass and a real Neo4j round-trip is verified: decide
+   whether to publish to PyPI or keep it in-repo longer
+
+## Session artifacts also produced today (separate from this task)
+
+- `ragleap-rag` v0.11.2 published to PyPI (README diagram fixes,
+  benchmark DB isolation bug fixed)
+- Full 9-page GitHub wiki written and pushed
+  (`github.com/antonyrag/ragleap-core/wiki`)
+- Marketing/launch copy prepared in a separate handoff doc (Product
+  Hunt, LinkedIn, Dev.to) — for `ragleap-rag` specifically, not
+  `ragleap.com` the commercial platform (these are different products,
+  don't mix their messaging)

ragleap_graph-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: ragleap-graph
+Version: 0.1.0
+Summary: Knowledge-graph-augmented retrieval for RAG systems — entity extraction, co-occurrence graphs, and graph-based document retrieval via Neo4j. Framework-agnostic, optional multi-tenant namespacing.
+Project-URL: Homepage, https://github.com/antonyrag/ragleap-core
+Project-URL: Repository, https://github.com/antonyrag/ragleap-core
+Project-URL: Issues, https://github.com/antonyrag/ragleap-core/issues
+Author-email: Antony <antony@ragleap.com>
+License-Expression: MIT
+Keywords: entity-extraction,graph-retrieval,knowledge-graph,neo4j,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.10
+Requires-Dist: neo4j>=5.0.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ragleap-graph
+
+Knowledge-graph-augmented retrieval for RAG systems — entity extraction, co-occurrence graphs, and graph-based document retrieval via Neo4j.
+
+```bash
+pip install ragleap-graph
+```
+
+## Quickstart
+
+```python
+from ragleap_graph import GraphConfig, GraphIndex
+
+graph = GraphIndex(config=GraphConfig(
+    uri="bolt://localhost:7687",
+    user="neo4j",
+    password="...",
+))
+
+graph.upsert_document(
+    document_id="doc-1",
+    title="Q3 Report",
+    chunks=[{"text": "Acme Corp reported strong Q3 revenue growth."}],
+)
+
+docs = graph.find_documents_by_entities(["Acme Corp"])
+related = graph.search_related_entities(["Acme Corp"], max_depth=2)
+```
+
+## Status
+
+Early alpha (v0.1.0). Ported from a real production `GraphService`, adapted for standalone open-source use — see `HANDOFF.md` for the full design history.
+
+## License
+
+MIT

ragleap_graph-0.1.0/README.md

@@ -0,0 +1,36 @@
+# ragleap-graph
+
+Knowledge-graph-augmented retrieval for RAG systems — entity extraction, co-occurrence graphs, and graph-based document retrieval via Neo4j.
+
+```bash
+pip install ragleap-graph
+```
+
+## Quickstart
+
+```python
+from ragleap_graph import GraphConfig, GraphIndex
+
+graph = GraphIndex(config=GraphConfig(
+    uri="bolt://localhost:7687",
+    user="neo4j",
+    password="...",
+))
+
+graph.upsert_document(
+    document_id="doc-1",
+    title="Q3 Report",
+    chunks=[{"text": "Acme Corp reported strong Q3 revenue growth."}],
+)
+
+docs = graph.find_documents_by_entities(["Acme Corp"])
+related = graph.search_related_entities(["Acme Corp"], max_depth=2)
+```
+
+## Status
+
+Early alpha (v0.1.0). Ported from a real production `GraphService`, adapted for standalone open-source use — see `HANDOFF.md` for the full design history.
+
+## License
+
+MIT

ragleap_graph-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ragleap-graph"
+version = "0.1.0"
+description = "Knowledge-graph-augmented retrieval for RAG systems — entity extraction, co-occurrence graphs, and graph-based document retrieval via Neo4j. Framework-agnostic, optional multi-tenant namespacing."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Antony", email = "antony@ragleap.com" }
+]
+keywords = ["knowledge-graph", "rag", "neo4j", "entity-extraction", "graph-retrieval"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "neo4j>=5.0.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0"]
+
+[project.urls]
+Homepage = "https://github.com/antonyrag/ragleap-core"
+Repository = "https://github.com/antonyrag/ragleap-core"
+Issues = "https://github.com/antonyrag/ragleap-core/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragleap_graph"]

ragleap_graph-0.1.0/src/ragleap_graph/__init__.py

@@ -0,0 +1,536 @@
+"""
+ragleap-graph: knowledge-graph-augmented retrieval for RAG systems.
+
+Ported from a real, production GraphService (Neo4j-backed, regex entity
+extraction, co-occurrence graph construction) with two deliberate
+adaptations for standalone open-source use:
+
+1. `workspace_id` (required, Django multi-tenant SaaS concept) becomes
+   an optional `namespace=` parameter, defaulting to None — mirrors
+   ragleap-rag's own `metadata_filter=` convention.
+2. Django `settings` coupling becomes an explicit `GraphConfig`
+   dataclass — zero framework dependency, same pattern as ragleap-rag's
+   `EmbeddingConfig`/`ProviderConfig`.
+
+A real security fix vs. the source this was ported from: `max_depth` in
+`search_related_entities()` is validated as a bounded integer before
+being used in Cypher query construction (the underlying Neo4j
+variable-length-path syntax can't be parameterized normally, so the
+depth value has to be validated before string formatting, not just
+trusted).
+"""
+from __future__ import annotations
+
+import logging
+import re
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    from neo4j import GraphDatabase
+except ImportError:
+    GraphDatabase = None
+
+logger = logging.getLogger(__name__)
+
+__version__ = "0.1.0"
+
+# Hard ceiling on traversal depth — prevents both runaway queries and,
+# since max_depth is string-interpolated into Cypher (see note above),
+# guards against malformed/malicious input reaching the query text.
+MAX_ALLOWED_DEPTH = 10
+
+
+@dataclass
+class GraphConfig:
+    """Connection config for a Neo4j-backed GraphIndex.
+
+    No framework dependency — pass values directly rather than relying
+    on ambient settings (Django, env vars, etc.). Callers who want
+    env-var-driven config can build one with `GraphConfig(uri=os.environ[...])`
+    themselves.
+    """
+    uri: str = "bolt://localhost:7687"
+    user: str = "neo4j"
+    password: str = ""
+
+
+class GraphIndex:
+    """
+    Neo4j-backed knowledge graph index for entity-augmented retrieval.
+
+    Gracefully degrades if the `neo4j` package isn't installed or the
+    driver can't connect — `self.driver` will be None and all query
+    methods return empty results rather than raising, matching the
+    behavior of the production service this was ported from. Always
+    safe to construct; check `health_check()` if you need to confirm
+    connectivity before relying on it.
+    """
+
+    def __init__(self, config: Optional[GraphConfig] = None):
+        self.config = config or GraphConfig()
+        self.driver = None
+
+        if GraphDatabase is None:
+            logger.warning(
+                "neo4j package not installed. Install with: pip install ragleap-graph[neo4j] "
+                "(or just `pip install neo4j`). Graph queries will be unavailable."
+            )
+            return
+
+        try:
+            self.driver = GraphDatabase.driver(
+                self.config.uri,
+                auth=(self.config.user, self.config.password),
+            )
+            # GraphDatabase.driver() is lazy - it does not attempt a real
+            # connection until first use. Without an explicit check here,
+            # a bad URI/credentials would silently leave self.driver set
+            # to a non-functional object instead of None, breaking the
+            # "always safe to construct, check driver is None" contract
+            # documented on this class.
+            self.driver.verify_connectivity()
+            logger.info("Neo4j driver initialized successfully")
+        except Exception as e:
+            logger.warning(f"Failed to initialize Neo4j driver: {e}")
+            if self.driver is not None:
+                try:
+                    self.driver.close()
+                except Exception:
+                    pass
+            self.driver = None
+
+    def close(self) -> None:
+        """Close the Neo4j driver connection."""
+        if self.driver:
+            self.driver.close()
+
+    def __enter__(self) -> "GraphIndex":
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Entity extraction (regex/heuristic-based, not LLM-based — cheap
+    # and deterministic, matching the production approach this was
+    # ported from)
+    # ------------------------------------------------------------------
+
+    def _normalize_entity_name(self, raw_name: str) -> str:
+        """Normalize extracted entity text into a stable graph key.
+
+        Ported verbatim from the production implementation this package
+        is based on (verified via direct source review).
+        """
+        if not raw_name:
+            return ""
+        name = re.sub(r"\s+", " ", str(raw_name)).strip(" \t\r\n.,;:!?()[]{}'\"")
+        if len(name) < 3:
+            return ""
+        # Keep acronyms uppercase (e.g., ALARA, IAEA), title-case normal phrases.
+        if name.isupper():
+            normalized = name
+        else:
+            normalized = " ".join(part.capitalize() for part in name.split())
+        if len(normalized) > 120:
+            normalized = normalized[:120]
+        return normalized
+
+    def _extract_entity_candidates_from_text(
+        self,
+        text: str,
+        max_entities: int = 12,
+        domain_terms: Optional[List[str]] = None,
+    ) -> List[str]:
+        """
+        Lightweight, deterministic entity extraction from free text.
+
+        Ported from the production implementation this package is based
+        on, with one deliberate change: the source had a hardcoded list
+        of domain-specific terms (radiation-safety/medical-physics
+        vocabulary specific to that deployment's customer). That's not
+        appropriate as a hardcoded default in a general-purpose
+        open-source package — it would leak deployment-specific business
+        context and be irrelevant (or actively wrong) for any other
+        domain. Here, `domain_terms=` is an optional parameter instead —
+        pass your own domain vocabulary if useful, or omit it entirely
+        for fully generic acronym/capitalized-phrase extraction.
+        """
+        if not text:
+            return []
+
+        candidates: List[str] = []
+        # 1) Acronyms and all-caps entities.
+        candidates.extend(re.findall(r"\b[A-Z]{2,}(?:-[A-Z0-9]+)?\b", text))
+        # 2) Capitalized word sequences (person/org/concept-like phrases).
+        candidates.extend(
+            re.findall(r"\b(?:[A-Z][a-z]{2,})(?:\s+[A-Z][a-z]{2,}){0,2}\b", text)
+        )
+        # 3) Optional caller-supplied domain terms that may appear lowercase.
+        if domain_terms:
+            text_lower = text.lower()
+            for term in domain_terms:
+                if term.lower() in text_lower:
+                    candidates.append(term)
+
+        seen = set()
+        final: List[str] = []
+        for cand in candidates:
+            normalized = self._normalize_entity_name(cand)
+            if not normalized:
+                continue
+            key = normalized.lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            final.append(normalized)
+            if len(final) >= max_entities:
+                break
+        return final
+
+    def extract_query_entities(
+        self, query: str, max_entities: int = 10, domain_terms: Optional[List[str]] = None
+    ) -> List[str]:
+        """Extract entity candidates from a user query string."""
+        return self._extract_entity_candidates_from_text(
+            query, max_entities=max_entities, domain_terms=domain_terms
+        )
+
+    # ------------------------------------------------------------------
+    # Core graph operations
+    # ------------------------------------------------------------------
+
+    def upsert_document(
+        self,
+        document_id: str,
+        title: str,
+        chunks: List[Dict[str, Any]],
+        namespace: Optional[str] = None,
+        max_entities: int = 80,
+        max_pairs: int = 150,
+        domain_terms: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Index one document and its extracted entities into Neo4j.
+
+        Builds co-occurrence edges between entities found in the same
+        chunk, weighted by how often each entity/pair appears across
+        the document. Writes are idempotent (MERGE-based) — safe to
+        re-run on the same document.
+
+        `namespace=` is optional; omit it for a single global graph, or
+        pass a tenant/project identifier to keep graphs isolated.
+
+        `domain_terms=` is an optional list of lowercase-matchable terms
+        specific to your content (e.g. industry jargon) that the default
+        acronym/capitalized-phrase heuristic wouldn't catch on its own.
+
+        Returns an indexing summary so callers can log/monitor coverage.
+        """
+        summary: Dict[str, Any] = {
+            "success": False,
+            "document_id": str(document_id),
+            "entities_indexed": 0,
+            "relationships_indexed": 0,
+            "error": None,
+        }
+
+        if not self.driver:
+            summary["error"] = "Neo4j driver not available"
+            return summary
+
+        entity_counter: Counter = Counter()
+        pair_counter: Counter = Counter()
+
+        for chunk in chunks or []:
+            text = (chunk.get("text") or "").strip()
+            if not text:
+                continue
+
+            entities = self._extract_entity_candidates_from_text(
+                text, max_entities=12, domain_terms=domain_terms
+            )
+            if not entities:
+                continue
+
+            unique_entities = []
+            seen_local = set()
+            for ent in entities:
+                key = ent.lower()
+                if key in seen_local:
+                    continue
+                seen_local.add(key)
+                unique_entities.append(ent)
+                entity_counter[ent] += 1
+
+            for i in range(len(unique_entities)):
+                for j in range(i + 1, len(unique_entities)):
+                    a, b = unique_entities[i], unique_entities[j]
+                    if a == b:
+                        continue
+                    pair = tuple(sorted((a, b), key=lambda s: s.lower()))
+                    pair_counter[pair] += 1
+
+        top_entities = entity_counter.most_common(max_entities)
+        top_pairs = pair_counter.most_common(max_pairs)
+        ns = namespace or ""
+
+        try:
+            with self.driver.session() as session:
+                session.run(
+                    """
+                    MERGE (d:Document {id: $document_id, namespace: $namespace})
+                    ON CREATE SET d.created_at = datetime()
+                    SET d.title = $title
+                    """,
+                    document_id=str(document_id),
+                    namespace=ns,
+                    title=title or "",
+                )
+
+                for entity_name, weight in top_entities:
+                    session.run(
+                        """
+                        MATCH (d:Document {id: $document_id, namespace: $namespace})
+                        MERGE (e:Entity {name: $name_lower, namespace: $namespace})
+                        ON CREATE SET e.display_name = $name
+                        MERGE (d)-[r:CONTAINS]->(e)
+                        ON CREATE SET r.weight = $weight
+                        ON MATCH SET r.weight = coalesce(r.weight, 0) + $weight
+                        """,
+                        document_id=str(document_id),
+                        namespace=ns,
+                        name_lower=entity_name.lower(),
+                        name=entity_name,
+                        weight=float(weight),
+                    )
+                    summary["entities_indexed"] += 1
+
+                for (a, b), weight in top_pairs:
+                    session.run(
+                        """
+                        MATCH (ea:Entity {name: $a, namespace: $namespace})
+                        MATCH (eb:Entity {name: $b, namespace: $namespace})
+                        MERGE (ea)-[r:CO_OCCURS_WITH]-(eb)
+                        ON CREATE SET r.weight = $weight
+                        ON MATCH SET r.weight = coalesce(r.weight, 0) + $weight
+                        """,
+                        a=a.lower(),
+                        b=b.lower(),
+                        namespace=ns,
+                        weight=float(weight),
+                    )
+                    summary["relationships_indexed"] += 1
+
+            summary["success"] = True
+            return summary
+
+        except Exception as e:
+            logger.error(f"Graph upsert error: {e}", exc_info=True)
+            summary["error"] = str(e)
+            return summary
+
+    def find_documents_by_entities(
+        self,
+        entity_names: List[str],
+        namespace: Optional[str] = None,
+        limit: int = 25,
+    ) -> List[Dict[str, Any]]:
+        """Retrieve documents connected to the given entity names, ranked
+        by matched-entity count and summed edge weight."""
+        if not self.driver:
+            return []
+
+        normalized = self._normalize_entity_list(entity_names)
+        if not normalized:
+            return []
+
+        ns = namespace or ""
+
+        try:
+            with self.driver.session() as session:
+                result = session.run(
+                    """
+                    MATCH (e:Entity)<-[r:CONTAINS]-(d:Document)
+                    WHERE e.namespace = $namespace
+                      AND d.namespace = $namespace
+                      AND e.name IN $entity_names
+                    RETURN d.id AS document_id,
+                           coalesce(d.title, '') AS document_name,
+                           count(DISTINCT e) AS matched_entities,
+                           sum(coalesce(r.weight, 1.0)) AS graph_score,
+                           collect(DISTINCT e.display_name)[0..10] AS matched_entity_names
+                    ORDER BY matched_entities DESC, graph_score DESC
+                    LIMIT $limit
+                    """,
+                    namespace=ns,
+                    entity_names=normalized,
+                    limit=max(1, int(limit)),
+                )
+
+                docs = []
+                for row in result:
+                    docs.append({
+                        "document_id": str(row["document_id"]) if row["document_id"] is not None else "",
+                        "document_name": row["document_name"] or "",
+                        "matched_entities": int(row["matched_entities"] or 0),
+                        "graph_score": float(row["graph_score"] or 0.0),
+                        "matched_entity_names": list(row["matched_entity_names"] or []),
+                    })
+                return docs
+
+        except Exception as e:
+            logger.error(f"Graph document lookup error: {e}", exc_info=True)
+            return []
+
+    def search_related_entities(
+        self,
+        entity_names: List[str],
+        namespace: Optional[str] = None,
+        max_depth: int = 2,
+        limit: int = 10,
+    ) -> List[Dict[str, Any]]:
+        """
+        Find entities related to the given entity names via graph
+        traversal, up to `max_depth` hops.
+
+        `max_depth` is validated as a bounded integer (1-10) before use
+        — Neo4j's Cypher can't parameterize variable-length path bounds
+        normally, so this value gets string-formatted into the query.
+        Unvalidated input here would be a real injection vector.
+        """
+        # Validate first, regardless of driver state - invalid input is
+        # invalid input whether or not Neo4j happens to be reachable.
+        try:
+            max_depth = int(max_depth)
+        except (TypeError, ValueError):
+            raise ValueError(f"max_depth must be an integer, got {max_depth!r}")
+        if not (1 <= max_depth <= MAX_ALLOWED_DEPTH):
+            raise ValueError(
+                f"max_depth must be between 1 and {MAX_ALLOWED_DEPTH}, got {max_depth}"
+            )
+
+        if not self.driver:
+            logger.warning("Neo4j driver not available")
+            return []
+
+        normalized = self._normalize_entity_list(entity_names)
+        if not normalized:
+            return []
+
+        ns = namespace or ""
+
+        try:
+            with self.driver.session() as session:
+                # max_depth is validated above (bounded int) before
+                # being formatted in — Cypher variable-length path
+                # bounds can't be passed as query parameters.
+                query = """
+                    MATCH (start:Entity)
+                    WHERE start.name IN $entity_names
+                      AND start.namespace = $namespace
+                    MATCH path = (start)-[*1..{max_depth}]-(related:Entity)
+                    WHERE related.namespace = $namespace
+                    RETURN DISTINCT related.name AS entity_id,
+                           related.display_name AS entity_name,
+                           type(relationships(path)[0]) AS relationship,
+                           length(path) AS depth
+                    ORDER BY depth ASC
+                    LIMIT $limit
+                """.format(max_depth=max_depth)
+
+                result = session.run(
+                    query,
+                    entity_names=normalized,
+                    namespace=ns,
+                    limit=max(1, int(limit)),
+                )
+
+                related = []
+                for row in result:
+                    related.append({
+                        "entity_id": row["entity_id"],
+                        "entity_name": row["entity_name"],
+                        "relationship": row["relationship"],
+                        "depth": int(row["depth"]),
+                    })
+                return related
+
+        except ValueError:
+            raise
+        except Exception as e:
+            logger.error(f"Related-entity search error: {e}", exc_info=True)
+            return []
+
+    def document_entities(
+        self,
+        document_id: str,
+        namespace: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Find all entities linked to a specific document."""
+        if not self.driver:
+            logger.warning("Neo4j driver not available")
+            return []
+
+        ns = namespace or ""
+
+        try:
+            with self.driver.session() as session:
+                result = session.run(
+                    """
+                    MATCH (d:Document {id: $document_id, namespace: $namespace})
+                    MATCH (d)-[:CONTAINS]->(e:Entity)
+                    RETURN e.name AS entity_id,
+                           e.display_name AS entity_name
+                    LIMIT 50
+                    """,
+                    document_id=str(document_id),
+                    namespace=ns,
+                )
+
+                entities = []
+                for row in result:
+                    entities.append({
+                        "entity_id": row["entity_id"],
+                        "entity_name": row["entity_name"],
+                    })
+                return entities
+
+        except Exception as e:
+            logger.error(f"Document entity lookup error: {e}", exc_info=True)
+            return []
+
+    def health_check(self) -> bool:
+        """Return True if the Neo4j driver is connected and responsive."""
+        if not self.driver:
+            return False
+        try:
+            with self.driver.session() as session:
+                session.run("RETURN 1")
+            return True
+        except Exception as e:
+            logger.warning(f"Graph health check failed: {e}")
+            return False
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _normalize_entity_list(self, entity_names: List[str]) -> List[str]:
+        normalized = []
+        seen = set()
+        for name in entity_names or []:
+            norm = self._normalize_entity_name(name)
+            if not norm:
+                continue
+            key = norm.lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            normalized.append(key)
+        return normalized
+
+
+__all__ = ["GraphConfig", "GraphIndex", "__version__"]

ragleap_graph-0.1.0/tests/test_ragleap_graph.py

@@ -0,0 +1,251 @@
+"""
+Tests for ragleap_graph.
+
+Three tiers, mirroring ragleap-rag's own test discipline:
+1. Pure logic tests — no Neo4j needed (normalization, extraction, validation)
+2. Driver-unavailable safety tests — confirm graceful degradation
+3. Live integration test — real Neo4j round-trip, skipped automatically
+   unless NEO4J_URI/NEO4J_USER/NEO4J_PASSWORD are set in the environment.
+   Cleans up its own test data via namespace-scoped delete, same pattern
+   manually verified during development.
+"""
+import os
+
+import pytest
+
+from ragleap_graph import GraphConfig, GraphIndex, MAX_ALLOWED_DEPTH
+
+
+# ---------------------------------------------------------------------------
+# GraphConfig
+# ---------------------------------------------------------------------------
+
+def test_graph_config_defaults():
+    config = GraphConfig()
+    assert config.uri == "bolt://localhost:7687"
+    assert config.user == "neo4j"
+    assert config.password == ""
+
+
+def test_graph_config_custom_values():
+    config = GraphConfig(uri="bolt://example.com:7687", user="admin", password="secret")
+    assert config.uri == "bolt://example.com:7687"
+    assert config.user == "admin"
+    assert config.password == "secret"
+
+
+# ---------------------------------------------------------------------------
+# Entity normalization (pure logic, no driver needed)
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def graph_no_driver():
+    """A GraphIndex whose driver never connects (bad URI) — safe for
+    testing pure logic methods without touching a real database."""
+    config = GraphConfig(uri="bolt://localhost:1", user="x", password="x")
+    g = GraphIndex(config=config)
+    assert g.driver is None
+    return g
+
+
+def test_normalize_entity_name_empty(graph_no_driver):
+    assert graph_no_driver._normalize_entity_name("") == ""
+    assert graph_no_driver._normalize_entity_name(None) == ""
+
+
+def test_normalize_entity_name_too_short(graph_no_driver):
+    assert graph_no_driver._normalize_entity_name("ab") == ""
+
+
+def test_normalize_entity_name_collapses_whitespace(graph_no_driver):
+    result = graph_no_driver._normalize_entity_name("Acme   Corp\n\tInc")
+    assert result == "Acme Corp Inc"
+
+
+def test_normalize_entity_name_strips_punctuation(graph_no_driver):
+    result = graph_no_driver._normalize_entity_name("  (Acme Corp).  ")
+    assert result == "Acme Corp"
+
+
+def test_normalize_entity_name_keeps_acronyms_uppercase(graph_no_driver):
+    assert graph_no_driver._normalize_entity_name("ALARA") == "ALARA"
+    assert graph_no_driver._normalize_entity_name("IAEA") == "IAEA"
+
+
+def test_normalize_entity_name_title_cases_normal_phrases(graph_no_driver):
+    assert graph_no_driver._normalize_entity_name("acme corp") == "Acme Corp"
+    assert graph_no_driver._normalize_entity_name("ACME corp") == "Acme Corp"
+
+
+def test_normalize_entity_name_truncates_long_names(graph_no_driver):
+    long_name = "A" * 200
+    result = graph_no_driver._normalize_entity_name(long_name)
+    assert len(result) == 120
+
+
+# ---------------------------------------------------------------------------
+# Entity extraction (pure logic, no driver needed)
+# ---------------------------------------------------------------------------
+
+def test_extract_entities_empty_text(graph_no_driver):
+    assert graph_no_driver._extract_entity_candidates_from_text("") == []
+
+
+def test_extract_entities_finds_acronyms(graph_no_driver):
+    result = graph_no_driver._extract_entity_candidates_from_text(
+        "The IAEA published new guidelines."
+    )
+    assert "IAEA" in result
+
+
+def test_extract_entities_finds_capitalized_phrases(graph_no_driver):
+    result = graph_no_driver._extract_entity_candidates_from_text(
+        "Acme Corp signed a deal with Globex Industries."
+    )
+    assert "Acme Corp" in result
+    assert "Globex Industries" in result
+
+
+def test_extract_entities_respects_max_entities(graph_no_driver):
+    text = " ".join(f"Company{i} Corp" for i in range(20))
+    result = graph_no_driver._extract_entity_candidates_from_text(text, max_entities=5)
+    assert len(result) <= 5
+
+
+def test_extract_entities_deduplicates(graph_no_driver):
+    result = graph_no_driver._extract_entity_candidates_from_text(
+        "Acme Corp is great. Acme Corp is really great."
+    )
+    assert result.count("Acme Corp") == 1
+
+
+def test_extract_entities_domain_terms_optional_and_off_by_default(graph_no_driver):
+    """A term that only matches via domain_terms shouldn't appear unless
+    domain_terms is explicitly passed — no hardcoded vocabulary leaks in."""
+    text = "we discussed radiation safety protocols today"
+    without = graph_no_driver._extract_entity_candidates_from_text(text)
+    assert not any("radiation" in e.lower() for e in without)
+
+    with_terms = graph_no_driver._extract_entity_candidates_from_text(
+        text, domain_terms=["radiation safety"]
+    )
+    assert any("radiation safety" in e.lower() for e in with_terms)
+
+
+def test_extract_query_entities_delegates_correctly(graph_no_driver):
+    result = graph_no_driver.extract_query_entities("What does Acme Corp do?")
+    assert "Acme Corp" in result
+
+
+# ---------------------------------------------------------------------------
+# max_depth validation (the security fix — real Cypher-injection guard)
+# ---------------------------------------------------------------------------
+
+def test_max_depth_rejects_non_integer(graph_no_driver):
+    with pytest.raises(ValueError):
+        graph_no_driver.search_related_entities(["x"], max_depth="1; DROP")
+
+
+def test_max_depth_rejects_too_large(graph_no_driver):
+    with pytest.raises(ValueError):
+        graph_no_driver.search_related_entities(["x"], max_depth=MAX_ALLOWED_DEPTH + 1)
+
+
+def test_max_depth_rejects_zero_or_negative(graph_no_driver):
+    with pytest.raises(ValueError):
+        graph_no_driver.search_related_entities(["x"], max_depth=0)
+    with pytest.raises(ValueError):
+        graph_no_driver.search_related_entities(["x"], max_depth=-1)
+
+
+def test_max_depth_accepts_valid_range(graph_no_driver):
+    # driver is None, so this returns [] rather than raising — the point
+    # here is only that validation itself doesn't reject valid input.
+    result = graph_no_driver.search_related_entities(["x"], max_depth=3)
+    assert result == []
+
+
+# ---------------------------------------------------------------------------
+# Driver-unavailable safety (every public method must degrade gracefully)
+# ---------------------------------------------------------------------------
+
+def test_health_check_false_without_driver(graph_no_driver):
+    assert graph_no_driver.health_check() is False
+
+
+def test_upsert_document_returns_error_without_driver(graph_no_driver):
+    result = graph_no_driver.upsert_document(
+        document_id="d1", title="t", chunks=[{"text": "Acme Corp"}]
+    )
+    assert result["success"] is False
+    assert "not available" in result["error"]
+
+
+def test_find_documents_empty_without_driver(graph_no_driver):
+    assert graph_no_driver.find_documents_by_entities(["Acme Corp"]) == []
+
+
+def test_document_entities_empty_without_driver(graph_no_driver):
+    assert graph_no_driver.document_entities("doc-1") == []
+
+
+def test_context_manager_closes_cleanly(graph_no_driver):
+    with graph_no_driver as g:
+        assert g is graph_no_driver
+
+
+# ---------------------------------------------------------------------------
+# Live integration test — real Neo4j, real round-trip, self-cleaning.
+# ---------------------------------------------------------------------------
+
+NEO4J_URI = os.environ.get("NEO4J_URI")
+NEO4J_USER = os.environ.get("NEO4J_USER")
+NEO4J_PASSWORD = os.environ.get("NEO4J_PASSWORD")
+HAS_LIVE_NEO4J = bool(NEO4J_URI and NEO4J_USER and NEO4J_PASSWORD)
+
+TEST_NAMESPACE = "ragleap_graph_pytest"
+
+
+@pytest.mark.skipif(not HAS_LIVE_NEO4J, reason="No live Neo4j credentials in environment")
+def test_live_full_roundtrip():
+    """
+    Real end-to-end test against a real Neo4j instance: connect, write,
+    query three ways, then clean up every node this test created —
+    never leaves data behind in a real database.
+    """
+    config = GraphConfig(uri=NEO4J_URI, user=NEO4J_USER, password=NEO4J_PASSWORD)
+    graph = GraphIndex(config=config)
+
+    try:
+        assert graph.health_check() is True
+
+        result = graph.upsert_document(
+            document_id="pytest-live-doc-1",
+            title="Pytest Live Test Document",
+            chunks=[{"text": "Acme Corp announced a partnership with Globex Industries."}],
+            namespace=TEST_NAMESPACE,
+        )
+        assert result["success"] is True
+        assert result["entities_indexed"] > 0
+
+        docs = graph.find_documents_by_entities(["Acme Corp"], namespace=TEST_NAMESPACE)
+        assert len(docs) == 1
+        assert docs[0]["document_id"] == "pytest-live-doc-1"
+
+        related = graph.search_related_entities(
+            ["Acme Corp"], namespace=TEST_NAMESPACE, max_depth=2
+        )
+        assert any(r["entity_name"] == "Globex Industries" for r in related)
+
+        entities = graph.document_entities("pytest-live-doc-1", namespace=TEST_NAMESPACE)
+        entity_names = {e["entity_name"] for e in entities}
+        assert "Acme Corp" in entity_names
+        assert "Globex Industries" in entity_names
+
+    finally:
+        with graph.driver.session() as session:
+            session.run(
+                "MATCH (n) WHERE n.namespace = $ns DETACH DELETE n",
+                ns=TEST_NAMESPACE,
+            )
+        graph.close()