Quick Start¶

1. Install Dependencies¶

pip install uv
uv sync

2. Configure Graph Database¶

Graffold supports Neo4j, Memgraph, and FalkorDB as graph database backends, selectable via the DATABASE_TYPE env var.

Option A: Neo4j (default)

DATABASE_TYPE=neo4j
# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

# Or use Memgraph (no auth required)
# DATABASE_TYPE=memgraph
# NEO4J_URI=bolt://localhost:7687

Option B: Memgraph

DATABASE_TYPE=memgraph
# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=
NEO4J_PASSWORD=

Start Memgraph via Docker Compose:

docker compose -f docker-compose.yml -f docker-compose.memgraph.yml --profile memgraph up -d

3. Enable Redis Caching (Optional)¶

docker-compose --profile api up -d redis

Configure in .env:

REDIS_HOST=redis
REDIS_PORT=6379
DISABLE_REDIS=false

See Redis Integration for details.

4. Environment Variables¶

Add to .env:

AUDIT_LOG_FILE=audit.log
RATE_LIMIT_QUERY=60/minute
RATE_LIMIT_DEFAULT=120/minute
API_AUTH_TOKEN=your_secret_token

5. Build Your Knowledge Graph¶

uv run python pipeline_main.py \
  --csv-dir data/csv \
  --pubmed-queries data/queries.txt \
  --database olink1 \
  --service local

See Knowledge Graph Creation Guide for the full workflow.

6. Generate Embeddings¶

uv run python ingest_main.py --add-graph-embeddings --database olink1 --service bedrock

7. Start the API¶

uv run granian --interface asgi api.app:app --host 127.0.0.1 --port 8000 --reload

8. Query¶

# Create a session
curl -X POST "http://localhost:8000/v1/sessions" \
  -H "Content-Type: application/json" \
  -d '{"llm_service": "llama3-instruct", "database_name": "neo4j", "database_type": "neo4j"}'

# Query
curl -X POST "http://localhost:8000/v1/sessions/{session_id}/query" \
  -H "Content-Type: application/json" \
  -d '{"question": "What proteins are associated with heart disease?"}'

Docker (Development)¶

# Neo4j backend (default)
docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev up --build

# Memgraph backend
docker compose -f docker-compose.yml -f docker-compose.memgraph.yml --profile memgraph up --build

This starts FastAPI on :8000, Redis, and optionally Grafana monitoring with --profile monitoring.