Overview
========

**llama-index-agensgraph** is the `LlamaIndex <https://www.llamaindex.ai/>`_ integration for
`AgensGraph <https://github.com/skaiworldwide-oss/agensgraph>`_. It provides two storage
backends — a property graph store and a vector store — so you can run LlamaIndex's
``PropertyGraphIndex`` and ``VectorStoreIndex`` directly on AgensGraph, with hybrid search,
metadata filtering, and AgensGraph-tuned Text2Cypher.

**Components**

.. list-table::
   :header-rows: 1
   :widths: 32 68

   * - Class
     - What it does
   * - ``AgensPropertyGraphStore``
     - ``PropertyGraphIndex`` store — upsert nodes/relations, Cypher, vector queries, Text2Cypher.
   * - ``AgensgraphVectorStore``
     - ``VectorStoreIndex`` store (pgvector) — add/query/delete, metadata filters, hybrid search.
   * - ``SafeTextToCypherRetriever``
     - ``TextToCypherRetriever`` that runs the generated Cypher in a read-only transaction.
   * - ``AgensEngine``
     - Optional driver connection pool (sync + async), shared by both stores.

**What you get**

- Property-graph and vector indexing over a single AgensGraph database, on the
  ``agensgraph-python`` 2.0 driver, with the async methods implemented natively
  (``aquery``, ``async_add``, ``aupsert_nodes``, ``avector_query``, …).
- Each node stored on a label named after its type, with its embedding in a column of its
  own, so ``MATCH (n:"Person")`` reads only that type's storage.
- **Metadata-filtered vector search** honoring LlamaIndex ``MetadataFilters`` (all 14
  filter operators plus ``AND`` / ``OR`` / ``NOT`` and nested groups), translated to
  parameterized, injection-safe Cypher.
- **Hybrid search** that fuses HNSW semantic search with full-text keyword search via
  reciprocal rank fusion, plus text-search and MMR modes. The mode a query asks for is the
  one that runs.
- **AgensGraph-dialect Text2Cypher** that matches the storage model, avoiding Neo4j-only
  syntax, with generated Cypher run read-only through ``SafeTextToCypherRetriever``.

.. note::

   This documentation covers **version 0.3.1**, on PyPI. 0.3.1 is a documentation release;
   its code is 0.3.0's. 0.3.0 moved every statement onto the ``agensgraph-python`` 2.0 driver,
   stores each node on a label named after its type with the embedding in its own column,
   runs the search mode a query asks for, and shortens a label name over 63 bytes with a
   hash of the whole name. It installs no functions or tables of its own (0.2.0 created three
   plpgsql functions); the schema is read from the catalogs. It needs AgensGraph 2.17 or later
   and Python 3.11–3.14 (see :doc:`installation`).

   **Upgrading from 0.1 or 0.2:** those versions kept every node on the single ``"__Node__"``
   label, with the type in a ``labels`` property. 0.3 cannot read that layout. Every node
   comes back labelled ``__Node__``, ``MATCH (n:"Person")`` finds nothing, and upserting an
   existing entity writes a second copy. Drop the graph and ingest again with 0.3.
   Vector-store graphs need no change. Also, pass string parameters to ``structured_query``
   as a plain ``str``: a ``json.dumps``'d value now matches nothing. And
   ``AgensQueryException.details`` now carries the server's message (0.2 raised it under a
   ``detail`` key, so ``details`` read ``"unknown"``).

   The old ``AgensGraphStore`` (the ``KnowledgeGraphIndex`` store) was
   removed in 0.2.0 — use ``AgensPropertyGraphStore`` with ``PropertyGraphIndex``.