Overview
========

`LightRAG <https://github.com/HKUDS/LightRAG>`_ is a graph-based Retrieval-Augmented
Generation framework: it builds a knowledge graph from your documents and retrieves over it
at both the entity and the relationship level. **lightrag-agensgraph** implements **all four**
of LightRAG's pluggable storage roles on top of a single
`AgensGraph <https://github.com/skaiworldwide-oss/agensgraph>`_ database.

Importing ``lightrag_agensgraph`` registers four storage backends with LightRAG:

.. list-table::
   :header-rows: 1
   :widths: 30 30 40

   * - Storage role
     - Class name
     - Backed by
   * - Graph (entities + relationships)
     - ``AgensgraphStorage``
     - An AgensGraph property graph: ``base`` nodes, ``DIRECTED`` edges
   * - Vectors (entity / relation / chunk embeddings)
     - ``AgensgraphVectorStorage``
     - Three `pgvector <https://github.com/pgvector/pgvector>`_ tables with HNSW indexes
   * - Key-value (documents, chunks, LLM cache)
     - ``AgensgraphKVStorage``
     - One JSONB table
   * - Doc-status (ingestion pipeline state)
     - ``AgensgraphDocStatusStorage``
     - One typed table, a column per status field

You can mix and match — use all four, or pair one or two with LightRAG's other backends.

**What you get**

- One AgensGraph database for the whole LightRAG pipeline: graph, vectors, key-value, and
  document status.
- **Dual-level retrieval** — entity-centric *and* relationship-centric reasoning across
  documents — plus naive vector RAG, all selectable per query.
- **Workspace multi-tenancy**: isolate independent knowledge bases inside one database with
  a single ``workspace`` parameter.
- Incremental ingestion with a document-status pipeline. The doc-status store implements the
  scheduling API that LightRAG 1.5.6 drives it through.
- Every statement goes through the
  `agensgraph-python <https://github.com/skaiworldwide-oss/agensgraph-python>`_ driver, async
  throughout, with one connection pool per graph shared by every store of a workspace.

**How the data is kept**

- **Graph.** Every entity is a ``base`` node keyed by its name under a uniqueness constraint.
  LightRAG treats a relation as undirected, so each relation is stored once per pair of
  entities, as a ``DIRECTED`` edge under a unique index on the pair. Reads that involve edges
  are answered by graph id.
- **Vectors.** Records are embedded in batches and written in binary, one statement per batch.
  A nearest-neighbour search runs on the HNSW index, and ``bulk_ingest()`` loads a large dataset
  with the indexes rebuilt afterwards (see :doc:`usage`).
- **Key-value.** One table for every namespace, written one statement per batch.
- **Document status.** Every field of a status record is a column, so the pipeline's counts
  and lookups are index reads.

.. note::

   This page describes ``lightrag-agensgraph`` 0.3.1, which is on PyPI. It requires
   ``lightrag-hku`` 1.5.6 (``>=1.5.6,<1.6``), AgensGraph 2.17 or later, and Python 3.11 to 3.13.
   Tables written by 0.2.0 are upgraded in place; a 0.2.0 graph must be dropped, with its
   documents' rows, and ingested again (see :doc:`installation`).