Overview
========

**langchain-agensgraph** is the `LangChain <https://www.langchain.com/>`_ integration for
`AgensGraph <https://github.com/skaiworldwide-oss/agensgraph>`_. It provides a full set of
production components — a graph store, a pgvector-backed vector store, retrievers, a
Text2Cypher QA chain, chat-message history, a LangGraph checkpointer and long-term memory
store, an LLM graph transformer, and a shareable connection pool — each with synchronous
**and** asynchronous APIs, built for LangChain 1.x. Every statement goes through the
`agensgraph-python <https://github.com/skaiworldwide-oss/agensgraph-python>`_ 2.0 driver.

**Components**

.. list-table::
   :header-rows: 1
   :widths: 34 66

   * - Class
     - What it does
   * - ``AgensGraph``
     - Graph store — run Cypher, introspect the schema, write graph documents.
   * - ``AgensgraphVector``
     - Vector store (pgvector) — semantic and hybrid search, with add/delete/get.
   * - ``AgensVectorRetriever``
     - Retriever — vector (or hybrid) search.
   * - ``AgensGraphContextRetriever``
     - Retriever — search plus each hit's graph neighbourhood.
   * - ``AgensText2CypherRetriever``
     - Retriever — model-written Cypher run under server-side limits.
   * - ``AgensCypherQAChain``
     - Answers a question with generated Cypher run read-only.
   * - ``create_cypher_tool``
     - ``AgensCypherQAChain`` as an agent tool.
   * - ``AgensEngine``
     - The driver's connection pool (sync + async), shareable by multiple stores.
   * - ``AgensChatMessageHistory``
     - Chat-message history stored as an ordered chain of graph vertices.
   * - ``AgensSaver`` / ``AsyncAgensSaver``
     - LangGraph checkpointer — persists agent state so threads resume.
   * - ``AgensStore``
     - LangGraph ``BaseStore`` — cross-thread long-term memory, with optional semantic search.
   * - ``LLMGraphTransformer``
     - Extracts a graph from text via an LLM; feeds ``add_graph_documents``.

The data structures ``GraphDocument``, ``Node``, and ``Relationship`` are also exported, as is
``log_queries()``, which reports every statement a block of code ran and how long each took.

**What you get**

- A graph store and vector store that share one AgensGraph database, with full async
  surfaces (``aquery``, ``asimilarity_search``, ``aadd_texts``, ``adelete``, …).
- Query results as the driver's ``Vertex``, ``Edge``, and ``Path`` values, with the label,
  the id, and the properties kept apart.
- Production vector-store ergonomics: ``delete``, ``get_by_ids``, ``effective_search_ratio``
  over-fetch for recall, indexed metadata filters (``filter_properties``), and
  ``batch_size`` / ``embed_batch_size`` tuning.
- Hybrid (semantic + keyword) search via reciprocal rank fusion.
- Generated Cypher that is not trusted: writes refused by default, an ``EXPLAIN`` check before
  it runs, a read-only transaction, and a timeout. Because a read-only transaction is not a
  boundary for a role that can run a program on the server host, the Text2Cypher components
  refuse to run as a superuser or a member of ``pg_execute_server_program`` unless you pass
  ``allow_server_programs=True``; connect them as an ordinary role with read access.
- Connection pooling, per-query timeouts, schema caching, and ``enhanced_schema`` sampling
  for better Text2Cypher prompts.

.. note::

   **Version 0.3** moves every component onto the ``agensgraph-python`` 2.0 driver and adds
   the three retrievers, ``AgensCypherQAChain``, ``AgensStore``, and ``log_queries()``. It
   changes behaviour that 0.2.0 code relied on: ``query()`` returns ``Vertex`` / ``Edge`` /
   ``Path`` values, a ``str`` parameter is sent as text (so ``json.dumps(...)`` around it must
   be removed), AgensGraph older than 2.17 is refused at connect, and Python 3.10 is no
   longer supported. 0.3.1 is a documentation release; its code is 0.3.0's.
   See :doc:`installation`.