# Installation

## Requirements

- **Python** 3.11–3.14. On Python 3.10, pip installs 0.2.0 instead, without an error, and
  these pages do not describe it.
- A running **AgensGraph** 2.17 or later. The driver refuses an older server when it connects.
- The **pgvector** extension (for vector search and entity embeddings)
- **LlamaIndex** itself (`llama-index`)

The integration depends on `llama-index-core` (0.12–0.14), the
[`agensgraph-python`](https://pypi.org/project/agensgraph-python/) 2.0 driver, and
`psycopg[binary]` 3.3.4 or later. All three are installed with it.

## Install

```bash
pip install llama-index llama-index-agensgraph
```

Or through the `agensgraph-ai` umbrella package, which installs the same thing:

```bash
pip install llama-index "agensgraph-ai[llama-index]"
```

This documentation covers **0.3.1**. 0.3.1 is a documentation release; its code is 0.3.0's.
The examples that call a model use OpenAI, so they also need `llama-index-llms-openai` and
`llama-index-embeddings-openai` (both come with `llama-index`) and `OPENAI_API_KEY`.

> **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. Upgrade with `pip install -U llama-index-agensgraph`, then drop
> the graph and ingest again with 0.3. Vector-store graphs need no change. Two smaller
> changes: pass string parameters to `structured_query` as a plain `str`, because 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"`).

## Set up the pgvector extension

AgensGraph does not bundle [pgvector](https://github.com/pgvector/pgvector). Build it once
against your AgensGraph install and enable it in your database:

```bash
git clone https://github.com/pgvector/pgvector.git
export PG_CONFIG=/path/to/agens/bin/pg_config
cd pgvector && make && make install
```

```sql
-- in your AgensGraph database:
CREATE EXTENSION IF NOT EXISTS vector;
```

The stores also run `CREATE EXTENSION IF NOT EXISTS vector` themselves: the vector store
always, and the property graph store when it is given a `vector_dimension`. Creating the
extension needs a privileged role, so create it beforehand as a superuser, as above, when
the stores connect as an ordinary role. If the extension is missing and cannot be created,
the vector store raises `ValueError("Vector extension not supported ...")`. The property
graph store only logs a warning, and from then on `vector_query` returns no results. No
functions or tables of the package's own are installed; the graph store reads the schema
from the catalogs.

## Connecting

Connect the stores as an application role rather than a superuser.
`SafeTextToCypherRetriever` refuses a superuser or a member of `pg_execute_server_program`
unless `allow_server_programs=True` (see [Usage](usage.md#text2cypher-retrieval)).
As a superuser, after creating the `vector` extension:

```sql
CREATE ROLE app LOGIN PASSWORD 'app';
GRANT CREATE ON DATABASE mydb TO app;   -- lets the stores create their graphs
```

The **property graph store** takes a `conf` dictionary of `psycopg` connection keyword
arguments, passed to the driver's `Connection.connect`:

```python
conf = {
    "dbname": "mydb",
    "user": "app",
    "password": "app",
    "host": "localhost",
    "port": 5432,
}
```

The **vector store** takes a libpq `url` such as
`postgresql://user:password@localhost:5432/mydb`. Both stores accept a `vector_dimension`
(graph store) / `embedding_dimension` (vector store) that must match your embedding model —
1536 for OpenAI `text-embedding-3-small`, for example. Settings the connection leaves out,
such as the password, are read from the standard libpq environment variables (`PGPASSWORD`
and the like).

Opening a store is enough to check the connection. Each store creates its graph if it does
not exist yet:

```python
from llama_index_agensgraph.graph_stores.agensgraph import AgensPropertyGraphStore
from llama_index_agensgraph.vector_stores.agensgraph import AgensgraphVectorStore

graph_store = AgensPropertyGraphStore(graph_name="li_kg", conf=conf, vector_dimension=1536)
vector_store = AgensgraphVectorStore(
    url="postgresql://app:app@localhost:5432/mydb", embedding_dimension=1536
)
print(graph_store.structured_query("RETURN 1 AS ok"))
```

Each store holds one connection of its own. To share a pool across stores, pass
`engine=AgensEngine.from_url(...)` or `engine=AgensEngine.from_conf(conf)` to both; see
[Usage](usage.md) for that and for full examples. `statement_timeout=` (in seconds) on the
graph store or on `AgensEngine` limits every statement they run.