ladybug-rag

KO | EN

gitlite — search

#javascript #ai #typescript #llm #go #machine-learning #deep-learning #linux #java #cli #kubernetes #security #pytorch #open-source

(★ 9)

No description available.

ladybug-rag Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Hybrid Graph RAG with LadybugDB

**When Vectors Meet Graphs** --- a hybrid Retrieval-Augmented Generation system that combines vector search, graph traversal, PageRank ranking, and community detection in a single embedded database.

> This project is a companion to the book [**LadybugDB: Graph Memory for AI Agents**](https://leanpub.com/ladybugdb).

---

## Why Hybrid Graph RAG?

Standard vector RAG treats every document chunk as an isolated island. It works for simple lookups but fails when questions require:

- **Multi-hop reasoning** --- connecting facts across multiple documents
- **Structural context** --- understanding *why* something is relevant, not just that it's similar
- **Global questions** --- "What are the main themes?" requires corpus-wide awareness

Hybrid Graph RAG solves this by combining four retrieval modes in one query:

| Stage | Method | What it does |
|-------|--------|-------------|
| Semantic Entry | HNSW Vector Search | Find semantically similar seed nodes |
| Structural Expansion | Cypher Graph Traversal | Follow relationships to gather connected context |
| Importance Ranking | PageRank | Prioritize structurally central entities |
| Topic Scoping | Louvain Communities | Scope retrieval to relevant knowledge clusters |

All four stages run inside a single LadybugDB `.lbug` file. No external services, no glue code.

---

## Quick Start

### Install

```bash
pip install real_ladybug sentence-transformers
```

### Run the demo

```bash
python demo.py
```

The demo ingests three sample documents (auth system, rate limiting, data pipeline), builds a knowledge graph with entities and relationships, computes PageRank and community scores, then runs hybrid queries with RRF fusion.

### Use in your project

```python
from hybrid_graph_rag import HybridGraphRAG

# Initialize (creates a single .lbug file)
rag = HybridGraphRAG("knowledge.lbug")

# Ingest documents
rag.ingest_documents(["doc1.md", "doc2.md", "doc3.md"])

# Compute graph scores (run once after ingestion)
rag.compute_graph_scores()
rag.compute_similar_chunks()

# Hybrid query: vector search + graph traversal + RRF fusion
results = rag.query("How does authentication interact with rate limiting?")

# Build LLM-ready context
context = rag.build_context(results)
```

---

## Architecture

```
INDEXING                              RETRIEVAL
--------                              ---------
Documents                             Query
  |                                     |
  v                                     v
Chunking (2048 chars, 200 overlap)    Embed query
  |                                     |
  v                                     +---> Vector Search (HNSW)
Entity Extraction                       |         |
  |                                     +---> Entity Seed Search
  v                                     |         |
Knowledge Graph (Cypher)                |         v
  |                                     +---> Graph Traversal (1-2 hops)
  +---> HNSW Vector Indexes             |         |
  |                                     v         v
  +---> PageRank scores              RRF Fusion (k=60)
  |                                     |
  +---> Louvain communities             v
  |                                  Ranked Context
  +---> SIMILAR edges (KNN)             |
                                        v
                                     LLM Generation
```

## How It Works

### Reciprocal Rank Fusion (RRF)

Vector search and graph traversal produce separate ranked lists. RRF merges them:

```
score(item) = sum over each list: 1 / (rank + 60)
```

Items ranked high in *both* lists get the highest combined scores. This avoids the need for score normalization across heterogeneous retrieval methods.

### PageRank for Importance

Not all entities are equal. `Database` mentioned by 20 other entities is more important than `TempVar42` mentioned once. PageRank captures structural importance and breaks ties when multiple entities are equally similar by vector distance.

### Louvain Communities for Scoping

Louvain detects densely-connected clusters in the entity graph. These correspond to topics or domains. For scoped queries, retrieval stays within the relevant community. For global questions, community-level aggregation provides corpus-wide answers.

---

## LadybugDB Features Used

| Feature | LadybugDB Capability | Role in RAG |
|---------|---------------------|-------------|
| Vector indexes | HNSW (cosine/L2) | Semantic similarity search |
| Graph queries | Cypher with variable-length paths | Structural context expansion |
| PageRank | `algo` extension | Importance-weighted ranking |
| Louvain | `algo` extension | Topic clustering & scoping |
| Full-text search | BM25 via `fts` extension | Keyword fallback (optional) |
| MERGE queries | Idempotent upserts | Safe re-ingestion |
| Typed schemas | Mandatory node/rel tables | Data integrity |

Everything runs in a single embedded `.lbug` file --- no servers, no Docker, no infrastructure.

---

## Project Structure

```
ladybug-rag/
  hybrid_graph_rag.py   # Core implementation (~300 lines)
  demo.py               # Self-contained demo with sample documents
  README.md             # This file
```

---

## Learn More

This project demonstrates concepts from the book:

### [LadybugDB: Graph Memory for AI Agents](https://leanpub.com/ladybugdb)

The book covers everything you need to build production AI memory systems with LadybugDB:

- **Property graph fundamentals** --- Cypher queries, schema design, traversal patterns
- **Vector indexes** --- HNSW configuration, multi-index search, semantic entry points
- **Graph algorithms** --- PageRank, Louvain, connected components for knowledge scoring
- **Memory ontology** --- a complete schema for AI agent memory with entities, facts, events, and temporal reasoning
- **Hybrid retrieval** --- combining vector search with graph traversal for powerful RAG systems

[**Get the book on Leanpub**](https://leanpub.com/ladybugdb)

---

## License

MIT

ladybug-rag

ladybug-rag Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ladybug-rag

ladybug-rag Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README