tomo-sdk 1.0.0

Python SDK for Apache AGE + pgvector — graph and vector queries on PostgreSQL

Piggie

One PostgreSQL instance replaces your graph database, your vector database, and your ETL pipeline.

Piggie is a Python SDK for Apache AGE + pgvector on PostgreSQL. Cypher graph queries, vector similarity search, and hybrid graph+vector operations — all through a single connection string, with no vendor lock-in.

┌──────────────────────────────────────────────────┐
│                  Your Application                 │
├──────────────────────────────────────────────────┤
│              Piggie SDK (Python)                  │
│  Cypher │ SQL │ Vector Search │ Hybrid │ KM API  │
├──────────────────────────────────────────────────┤
│                  PostgreSQL                       │
│  Apache AGE     │  pgvector    │  Core SQL       │
│  (graphs)       │  (vectors)   │  (relational)   │
└──────────────────────────────────────────────────┘

Quick Start

# Start the database (Docker, any platform, ARM + x86)
git clone https://github.com/gregfelice/tomo.git && cd piggie
docker compose up -d

# Install the SDK
pip install piggie

import piggie

db = piggie.connect("postgresql://piggie:piggie@localhost:5488/piggie", graph="my_graph")

# Cypher queries → DataFrames
df = db.cypher("MATCH (n:Person) RETURN n.name, n.age").to_df()

# Vector search
results = db.vector_search("documents", "embedding", query_vec, k=10).to_df()

# Hybrid: graph traversal + vector similarity
results = db.hybrid_search(
    cypher="MATCH (p:Paper)-[:CITES]->(cited) RETURN cited",
    vector_table="papers",
    vector_column="abstract_embedding",
    query_vector=query_vec,
    k=10,
).to_df()

Installation

pip install piggie

# With pandas support
pip install piggie[pandas]

# With all optional dependencies
pip install piggie[all]

Database Setup

Piggie requires PostgreSQL with Apache AGE (graph) and pgvector (vectors).

Docker (recommended) — multi-arch image (ARM + x86), hardened config, everything pre-configured:

docker compose up -d

Verify the stack:

python docker/smoke-test.py

Other platforms: See the Install Database guide for Ubuntu, macOS, Fedora, and from-source instructions.

Cloud deployment: Terraform modules for AWS, GCP, Azure, DigitalOcean, and Hetzner — one terraform apply and you're running.

Docker Image

The piggie/db image ships PostgreSQL 18 + Apache AGE 1.7.0 + pgvector 0.8.2 with:

• Multi-arch: linux/amd64 + linux/arm64 (native on Apple M-series, AWS Graviton)
• scram-sha-256 authentication (no trust or md5)
• TLS enabled with self-signed cert (replace for production)
• Audit logging for connections, disconnections, and DDL
• Minimal attack surface — multi-stage build, no build tools in runtime

Benchmarks

We benchmarked AGE + pgvector against Neo4j, Kuzu, and NebulaGraph across 12 workloads at three scales (10K, 100K, 1M). AGE won all 12 workloads at every scale. At 1M nodes:

Workload	AGE	Neo4j	Speedup
Point Lookup	0.29ms	0.97ms	3x
Pattern Match	0.14ms	1.8ms	13x
VLE Traversal	0.18ms	0.62ms	3x
Concurrent Queries	52ms	1,323ms	25x
Bulk Load	59ms	133ms	2x

The Piggie SDK also won 14/16 algorithm benchmarks against Neo4j GDS, using igraph (C) and networkit (C++) backends.

Read the full analysis: Can One PostgreSQL Replace Your Graph Database and Your Vector Database?

Graph Algorithms

19 algorithms across 7 categories with automatic backend selection:

# Auto-selects igraph C backend
df = db.centrality(measure="betweenness")

# Auto-selects networkit C++ backend
df = db.centrality(measure="closeness")

# Community detection
df = db.communities(method="louvain")

Backends: igraph (C), networkit (C++), NetworkX (Python). The SDK detects installed backends and routes each algorithm to the fastest available implementation.

Integrations

• LangChain — PiggieVectorStore and PiggieGraphStore for RAG pipelines
• LlamaIndex — PiggieGraphStore (triplets) and PiggiePropertyGraphStore (labeled property graph)
• NetworkX — to_networkx() conversion + built-in PageRank, community detection, shortest path, centrality
• PyTorch Geometric — FeatureStore and GraphStore for GNN training on AGE data

Notebooks

Notebook	Description
Quickstart	Getting started with Piggie
Hybrid Search	Graph + vector search combined
Bulk Load	Bulk load and export
Algorithms	Graph algorithms with igraph/networkit backends
RAG Pipeline	RAG with LlamaIndex and LangChain
GNN Training	GNN training with PyTorch Geometric

Documentation

• Quick Start — 5-minute getting-started guide
• Install Database — Docker, Ubuntu, macOS, Fedora, from source
• API Reference — full method signatures and parameters
• Graph Algorithms — algorithm catalog and backend selection
• Integrations — LangChain, LlamaIndex, NetworkX, PyG
• Compatibility — tested version matrix
• Cloud Deployment — Terraform for AWS, GCP, Azure, DO, Hetzner
• Troubleshooting — common issues and fixes
• Security — TLS, authentication, credential handling
• Hardening — CIS benchmark alignment

Security

See SECURITY.md for vulnerability disclosure policy and security model.

Community

• GitHub Discussions — questions, ideas, show and tell
• Issue Tracker — bug reports and feature requests
• Contributing Guide — how to set up and contribute

Requirements

• Python 3.10+
• PostgreSQL 16–18 with Apache AGE and pgvector extensions (or use the Docker image)

License

Apache 2.0