Metadata-Version: 2.4
Name: pgvector-zerodb
Version: 0.1.0
Summary: Drop-in pgvector wrapper with auto-provisioned Postgres. Zero config vector database.
Author-email: AINative Studio <support@ainative.studio>
License: MIT
Project-URL: Homepage, https://github.com/AINative-Studio/pgvector-zerodb
Project-URL: Documentation, https://docs.ainative.studio/pgvector-zerodb
Project-URL: Repository, https://github.com/AINative-Studio/pgvector-zerodb
Project-URL: Issues, https://github.com/AINative-Studio/pgvector-zerodb/issues
Keywords: pgvector,pgvector-alternative,vector-database,postgresql,postgres,auto-provisioning,zerodb,ainative,embeddings,semantic-search,similarity-search,ai-database,vector-search,pgvector-hosting,managed-postgres,serverless-postgres,free-database,free-vector-database,rag,retrieval-augmented-generation,claude,cursor,windsurf,pinecone-alternative,chromadb-alternative
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pgvector>=0.3.0
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: requests>=2.28
Dynamic: license-file

# pgvector-zerodb

Drop-in [`pgvector`](https://github.com/pgvector/pgvector-python) wrapper with auto-provisioned Postgres. Zero config vector database.

```bash
pip install pgvector-zerodb
```

## Quick Start

```python
from pgvector_zerodb import auto_connect

# Automatically provisions a free Postgres with pgvector if no DATABASE_URL is set
conn = auto_connect()

cur = conn.cursor()
cur.execute("CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3))")
cur.execute("INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]')")
conn.commit()

cur.execute("SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5")
print(cur.fetchall())
```

That's it. No database setup, no config files, no cloud console.

## How It Works

1. You call `auto_connect()`
2. It checks for `DATABASE_URL` or `PGVECTOR_ZERODB_URL` environment variable
3. If neither exists, it provisions a **free managed Postgres** with pgvector via AINative
4. Credentials are saved to `~/.ainative/pgvector-config.json` for reuse
5. Returns a standard `psycopg2` connection with pgvector types registered

## Use Your Own Postgres

If you already have a Postgres instance with pgvector:

```bash
export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
```

```python
from pgvector_zerodb import auto_connect
conn = auto_connect()  # Uses your DATABASE_URL, no provisioning
```

## Same pgvector API

Everything from `pgvector` is re-exported. Existing code works unchanged:

```python
from pgvector_zerodb import register_vector
import psycopg2

conn = psycopg2.connect("postgresql://...")
register_vector(conn)
```

## With SQLAlchemy

```python
from pgvector_zerodb import get_connection_string
from sqlalchemy import create_engine

engine = create_engine(get_connection_string())
```

## With Django

Add to `settings.py`:

```python
from pgvector_zerodb import get_connection_string
import dj_database_url

DATABASES = {"default": dj_database_url.parse(get_connection_string())}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `DATABASE_URL` | PostgreSQL connection string (highest priority) |
| `PGVECTOR_ZERODB_URL` | Alternative env var for connection string |
| `AINATIVE_API_KEY` | API key for provisioning (optional, enables higher limits) |
| `ZERODB_API_KEY` | Alternative API key env var |

## Free Tier

The auto-provisioned Postgres includes:
- pgvector extension pre-installed
- 256 MB storage
- Shared compute
- No credit card required

Upgrade at [ainative.studio](https://ainative.studio) for dedicated resources.

## License

MIT
