ragleap-graph

Install

Requires a running Neo4j instance. Works standalone with regex extraction (zero LLM dependency), or with method="llm" for higher-quality extraction.

pip install ragleap-graph
# or, with uv
uv add ragleap-graph

Quick start

from ragleap_graph import GraphConfig, GraphIndex, ExtractionConfig

graph = GraphIndex(
    config=GraphConfig(uri="bolt://localhost:7687", user="neo4j", password="..."),
    extraction=ExtractionConfig(method="llm", provider=my_provider_config),
)
graph.upsert_document(document_id="doc-1", title="Q3 report", chunks=chunks)
related = graph.search_related_entities(["Acme Corp"], max_depth=2)

Version history

Every release this session was published to PyPI and live-tested before moving to the next — real Gemini calls, real Neo4j reads/writes, never mocked at the boundary that matters.

Architecture

flowchart TD
    classDef write fill:#1e3a5f,stroke:#4a90d9,color:#fff
    classDef read fill:#1a4d3a,stroke:#22c55e,color:#fff
    classDef hybrid fill:#3d2645,stroke:#a855f7,color:#fff
    classDef store fill:#4d3319,stroke:#f59e0b,color:#fff

    subgraph Write["Write path"]
        Doc["graph.upsert_document(...)"]:::write --> Extract["Entity/relation extraction
regex default, LLM via method='llm'"]:::write
        Extract --> Dedup["EntityDeduplicator (optional)
dedup_enabled=True"]:::write
    end

    Dedup --> Neo4j["Neo4j graph
Entity, Document,
PairWeight, RelationWeight"]:::store
    Neo4j --> Edges["CONTAINS, CO_OCCURS_WITH,
RELATES_AS edges"]:::store

    subgraph Read["Read path"]
        FindDocs["find_documents_by_entities()"]:::read
        SearchRel["search_related_entities()"]:::read
        FindRel["find_relations()"]:::read
        FindType["find_entities_by_type()"]:::read
        Lineage["find_lineage()
per-document contribution lookup"]:::read
    end
    Neo4j --> FindDocs
    Neo4j --> SearchRel
    Neo4j --> FindRel
    Neo4j --> FindType
    Neo4j --> Lineage

    subgraph HybridRet["Hybrid retrieval"]
        Retriever["GraphRetriever(graph, rag)"]:::hybrid --> VectorChunks["Vector chunks (ragleap-rag)"]:::hybrid
        Retriever --> GraphContext["Graph context
related_documents, related_entities"]:::hybrid
        VectorChunks --> Combined["Combined result
already_in_vector_results flag"]:::hybrid
        GraphContext --> Combined
    end
    

Full public API

from ragleap_graph import (
    GraphConfig, GraphIndex,
    ExtractionConfig, ExtractedEntity, EntityDeduplicator, LLMEntityExtractor,
    ExtractedRelation, LLMRelationExtractor,
    GraphRetriever, GraphRetrievalConfig,
)

graph = GraphIndex(
    config=GraphConfig(uri="bolt://localhost:7687", user="neo4j", password="..."),
    extraction=ExtractionConfig(
        method="regex" | "llm",              # default "regex", zero deps
        provider=ProviderConfig(...),          # required if method="llm"
        dedup_enabled=False,                   # v0.2.0
        dedup_threshold=0.92,                  # empirically tuned
        extract_relations=False,               # v0.4.0, requires method="llm"
        entity_types=None,                     # v0.5.0, e.g. ["Customer","Product"]
    ),
)

Core (v0.1.0)

Relations (v0.4.0)

Entity typing (v0.5.0)

GraphRetriever (v0.3.0)

Separate from GraphIndex — composes a GraphIndex with an existing RagLeap instance via ragleap-rag's retrieve() method.

retriever = GraphRetriever(graph=graph, rag=rag, config=GraphRetrievalConfig(mode="hybrid"|"graph_only"))
result = retriever.retrieve(query, top_k=5, namespace=None, metadata_filter=None)
# -> {"chunks":[...], "query_entities":[...], "graph_context":{...}, "citations":[...], "retrieval_method":...}
# graph_context.related_documents entries include already_in_vector_results (v0.6.1) -
# flags rather than removes documents also present in chunks, so graph-relationship
# context (matched entities, graph score) is never silently discarded.

Real bugs & design decisions this session

Not fabricated wins — each of these was caught by a real test failure or a real live-verification step.

• ✓ fixed
  Dedup threshold false-positive (v0.2.0). Default 0.85 incorrectly merged "Neo4j" and "Neo 4j." Tested against 0.85/0.90/0.92/0.95 — 0.92 clears the false positive without breaking true positives ("T.C. Antony" / "TC Antony").
• ✓ fixed
  Test-harness bug (v0.2.0). Mock cache-busting was keyed to the wrong module path — five LLM-extraction tests were silently making real network calls instead of using the mock. Fixed, with a canary assertion added so this can't recur silently.
• documented, not hidden
  Regex extraction fragments "ACME Corp." into disconnected candidates ("ACME" + "Corp") alongside the correct "Acme Corp" elsewhere. Dedup correctly declines to merge these (similarity ~0.67, below 0.92) — a real side-by-side test confirms method="llm" avoids this at the source.
• ✓ shipped
  GraphRetriever design decision. Built on RagLeap.retrieve() (new public method added to ragleap-rag specifically for this) rather than reaching into RagLeap's private internals.
• ✓ shipped
  Relation hallucination filtering (v0.4.0). LLMRelationExtractor defensively drops any relation referencing an entity outside the caller-supplied known_entities list, and drops self-relations, even though the prompt already constrains this.
• ✓ fixed
  Entity typing gap closed (v0.5.0). LLMEntityExtractor computed a per-entity type field since v0.2.0, but GraphIndex discarded it before it reached Neo4j. Now actually used.
• ✓ shipped
  Re-upsert type-downgrade guard (v0.5.0). A later regex-only upsert of the same document won't overwrite an already-recorded LLM-derived entity_type with "UNKNOWN," via a coalesce(NULLIF(...)) pattern in the write query.
• ✓ fixed
  Sentence-initial stopword bug (v0.5.2). Regex extraction picked up capitalized sentence-initial words ("What," "Who," "The") as spurious entities, since English capitalizes a sentence's first word regardless of whether it's a proper noun. "What did Acme Corp launch?" previously returned ['What', 'Acme Corp'] instead of just ['Acme Corp']. Fixed with a narrow stopword filter applied only to exact single-word matches — multi-word entities unaffected. Reproduced live before fixing, regression test written and confirmed failing first.
• ✓ fixed
  find_relations() reverse-lookup gap (v0.5.3). Only ever searched outgoing relations — searching from the object side silently returned [] even when the entity was clearly involved in a real relation. Added direction= parameter ("outgoing" default, "incoming", "both"). Zero prior test coverage existed for this method at all; backfilled alongside the fix. Reproduced live, regression test confirmed failing first.
• ✓ fixed
  upsert_document() CONTAINS idempotency bugs (v0.5.4). Docstring claimed writes were "idempotent — safe to re-run," which was false: re-upserting identical content doubled CONTAINS weight every call, and re-upserting changed content left stale entity links in place forever. Fixed by deleting a document's CONTAINS edges before rewriting them per upsert. Both bugs reproduced live before any code changed.
• ✓ fixed
  CO_OCCURS_WITH/RELATES_AS idempotency, the harder half (v0.6.0). These edges deliberately aggregate weight across multiple documents by design, so the simple CONTAINS-style fix would have broken that aggregation. Added PairWeight/RelationWeight node types to track each document's contribution separately, recomputing the shared edge's weight as a sum whenever it changes. Three behaviors verified live: identical re-upsert doesn't double weight, a genuinely different document sharing the pair correctly aggregates, and removing a document's contribution correctly drops the total.
• ✓ fixed
  GraphRetriever vector/graph overlap gap (v0.6.1). A document could surface through both vector search and graph traversal with no way for the caller to know — real overlap information silently discarded. Added already_in_vector_results to each related_documents entry rather than removing overlaps outright, so graph-relationship context is never lost. Test-first with the existing fake-object test doubles, no live services needed.
• ✓ fixed
  find_entities_by_type() case-sensitivity (v0.6.2). Did exact-string-match only — "Customer" and "customer" were treated as different types even though entity_type is stored exactly as the model produced it with no casing normalization at write time. Now case-insensitive. Reproduced live before fixing, regression test confirmed failing first.
• ✓ fixed
  entity_types= enforcement (v0.6.3). Was guidance only — a model returning a type outside the caller-supplied list was accepted as-is. Now enforced: any out-of-vocabulary type is coerced to "UNKNOWN", the same value regex-extracted entities already use. Only applies when entity_types= is actually set; without it, behavior is unchanged.
• ✓ fixed
  CO_OCCURS_WITH relationship-MERGE race (v0.6.8). The v0.6.7 fix closed four node-level concurrency races (Document/Entity/PairWeight/RelationWeight) but deliberately left this one open, noted as a separate known risk at the time. MERGE (ea)-[r:CO_OCCURS_WITH]-(eb) matched only the two Entity endpoints, not atomic against concurrent writers. Fixed via the same composite_key pattern used for the four node types, with entity-pair order canonicalized (sorted) since the relationship is undirected. Live-verified via an 8-thread concurrency test using 8 different documents sharing the same entity pair — exactly 1 relationship resulted.

Known limitations

From the package's own CHANGELOG.md, current as of v0.6.7.

• No relationship-type ontology constraints — relation types and entity types aren't cross-validated against each other.
• Relation extraction runs once per chunk — relations spanning multiple chunks of the same document aren't identified.