Metadata-Version: 2.4
Name: vectorgraph
Version: 0.1.3
Summary: Minimal Postgres stack combining Apache AGE graph + pgvector with simple async helpers.
Author: Eric Hartford
License: MIT
Project-URL: Homepage, https://github.com/QuixiAI/vectorgraph
Project-URL: Repository, https://github.com/QuixiAI/vectorgraph
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pgvector>=0.2.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: tiktoken>=0.5.1
Requires-Dist: openai>=1.3.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: pydantic>=2.4.2
Provides-Extra: dev
Requires-Dist: black>=23.11.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: pytest>=7.4.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.1; extra == "dev"
Requires-Dist: pytest-mock>=3.11.1; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"

# QuixiAI VectorGraph

A minimal, batteries-included PostgreSQL stack that pairs Apache AGE (graph) with pgvector. Spin it up with Docker, hit a couple of Python helpers, and you have graph + vector storage in one place.

## 60-second start
1. Install: `pipx install .` (or `pip install .` in a venv)
2. Bring up services: `vectorgraph up` (Docker compose stack with graph/vector)
3. Run tests: `pytest -q`
4. Tinker in Python (see below) or run `vectorgraph demo` then `python demo.py`.

Install options:
- `pipx install .` (recommended for CLI) or `pip install .` in a venv.
- CLI commands: `vectorgraph up`, `vectorgraph down`, `vectorgraph logs -f`, `vectorgraph ps`, `vectorgraph demo`.
  - Prefer async API for apps; sync helpers are available at `vectorgraph.sync` (see async/sync combined demo).

## Python quickstart
```python
import asyncio
from vectorgraph import create_db, delete_db, graph_create_entity, vector_add, vector_nearest_neighbors

async def main():
    db_id = await create_db()
    try:
        await graph_create_entity(db_id, "n1", "Hello", "Graph+Vector")
        await vector_add(db_id, "n1", [0.1]*768, {"label": "hello"})
        neighbors = await vector_nearest_neighbors(db_id, [0.1]*768, k=3)
        print(neighbors)
    finally:
        await delete_db(db_id)

asyncio.run(main())
```
Combined example: `python examples/demo.py` (async flow) and `python examples/demo.py --sync` (sync via `vectorgraph.sync`).

## Use as a library
Install into your app (no CLI needed if you already run Postgres/AGE/pgvector):
```
pip install vectorgraph
```
Minimal usage (async):
```python
import asyncio
from vectorgraph import vector_add, vector_nearest_neighbors, create_db

async def main():
    db_id = await create_db()
    await vector_add(db_id, "id1", [0.1]*768, {"tag": "demo"})
    print(await vector_nearest_neighbors(db_id, [0.1]*768, k=1))

asyncio.run(main())
```
Env vars respected by the helpers: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_HOST`, `POSTGRES_PORT`. If you’re pointing at an existing stack, set these to your running Postgres/AGE instance.

## Files
- `db.py` — public async API for graph + vector helpers (AGE + pgvector).
- `graph.py` / `vector.py` — thin wrappers if you prefer to import per-domain.
- `schema.sql` — enables extensions and embeds the TEI-friendly `get_embedding` function.
- `Dockerfile` — Postgres 16 image with AGE, pgvector, pgsql-http.
- `docker-compose.yml` — Postgres + HuggingFace TEI (embedding service).
- `tests/` — async end-to-end tests for graph and vector paths.
- `pyproject.toml` — package metadata (dependencies via pip/uv/pdm) and CLI entrypoint.
- `vectorgraph/stack/` — packaged `docker-compose.yml`, `Dockerfile`, `schema.sql` used by the CLI.

## Environment
Defaults are baked into the stack; you normally don’t need to touch `.env`. If a `.env` exists in your project root, `vectorgraph up` will copy it into its cache and use it; otherwise it uses the packaged defaults. The embedding container sits on a private Docker network (no host port) and is reachable from Postgres at `http://embeddings:80`.

## Typical flow
- `vectorgraph up`
- run Python code using the helpers (or `vectorgraph demo` then `python demo.py`)
- `pytest -q` to sanity check
- `vectorgraph down` when done

## Notes
- Vectors are fixed at 768-dim; the TEI model (`unsloth/embeddinggemma-300m`) matches that.
- Each call to `create_db()` makes a dedicated AGE graph + vector table keyed by UUID to keep tests isolated.
