# Piggie

FOSS data integration platform anchored on Apache AGE (PostgreSQL graph extension) — graph-native CRM and unified DB for modern AI workloads.

## Quick Reference

```bash
# Connect to database
psql -p 5433 -d piggie

# Setup SDK dev environment
uv venv .venv && source .venv/bin/activate && uv pip install -e ".[dev]"

# Run all tests (requires PG18 with AGE + pgvector)
pytest tests/ -v

# Run unit tests only (no DB needed)
pytest tests/test_types.py tests/test_result.py tests/test_cypher_wrapper.py tests/test_agtype_parser.py

# Run integration tests only
pytest tests/ -m integration

# Lint + type check
ruff check src/ tests/
mypy src/piggie --exclude 'src/piggie/_agtype/gen'
```

## Architecture

The core thesis is that AGE + pgvector in a single PostgreSQL instance replaces the need for separate graph (Neo4j) and vector (Pinecone) databases. The platform layers:

1. **Storage engines** — AGE (graph), pgvector (embeddings), TimescaleDB (time-series), PostGIS (geo), JSONB (documents), star schema (financial measures) — all in PostgreSQL
2. **SDK layer** — Python SDK (priority), JS/TS SDK, Rust SDK (future)
3. **Governance layer** — AGE Unity (catalog, RBAC, lineage, audit) — later phase
4. **Application layer** — LegalFlow (legal tech), Quanta (ROI tools), compliance dashboards — later phase

Key boundary rule: graph for structure, star schema for measures — never mix these.

**SDK package structure** (`src/piggie/`):

- `driver.py` — PiggieDriver: main entry point (cypher, sql, vector_search, hybrid_search)
- `connection.py` — AGE setup (LOAD, search_path, agtype registration)
- `result.py` — Result/Record: to_df(), to_dicts(), to_arrow(), expand=True
- `types.py` — Vertex, Edge, Path frozen dataclasses
- `_cypher/` — Cypher-to-SQL translation (two-step AGE execution pattern)
- `_agtype/` — ANTLR4 parser + psycopg3 Loader for agtype wire format
- `_vector/` — pgvector k-NN search and index management
- `_hybrid/` — graph_then_vector / vector_then_graph combined queries
- `_schema/` — Graph schema + vector index discovery

**Dev environment:**

- PostgreSQL 18.2 on port **5433** (PG16 remains on 5432)
- Apache AGE 1.7.0 — built from source at `~/development/apache-age` (branch `release/PG18/1.7.0`)
- pgvector 0.8.1 installed alongside AGE
- Database: `piggie` (owner: `gregf`, superuser)
- Python 3.12+ for SDK and tooling work
- `uv` for Python package management (not pip)

## Conventions

- AGE contributions follow [apache/age contributor guidelines](https://github.com/apache/age)
- Python code: ruff for linting/formatting, pytest for tests, type hints enforced via mypy
- All FOSS work is Apache 2.0 licensed
- ADRs go in `docs/adr/` (use `/adr` command)
- Research goes in `docs/research/` (use `/research` command)

## Key Documentation

| Document | Path |
|---|---|
| Vision and execution plan | `PIGGIE_VISION_AND_PLAN.md` |
| SDK product vision | `docs/SDK-VISION.md` |
| Engineering backlog | `docs/BACKLOG.md` |
| AGE feature prioritization | `docs/research/age-feature-prioritization.md` |
| Neo4j Python SDK analysis | `docs/research/neo4j-python-sdk-analysis.md` |

## Status

**Phase 0 (Foundation)** — Blocked on IP addendum. Forgejo/Woodpecker CI provisioned (git.ooxo.io). 8 AGE PRs submitted upstream (4 merged), MERGE ON SET feature implementation complete locally. See `docs/BACKLOG.md` for P0-P3 prioritized work items.
