README.md

# cypher4sql

Neo4j-enhanced context engineering for SQL generation.

## Overview

cypher4sql uses Neo4j schema graphs to provide rich context for text-to-SQL models:

- **Semantic table retrieval** via vector embeddings
- **FK statistics** (fanout, cardinality, risk tags)
- **Join path finding** for multi-hop queries
- **Planner hints** for complex joins

## Architecture

```
User Question
     ↓
┌─────────────────────────────────────┐
│  Neo4j Schema Graph (cypher4sql)    │
│  - Vector search → relevant tables  │
│  - FK stats → join risk/hints       │
│  - Path finding → join options      │
└─────────────────────────────────────┘
     ↓
Enhanced Context + FK Stats
     ↓
SQL Model → Query
```

## Usage

### Training
- FK stats for reward shaping
- Mutation validation (Phase 3.5)
- Context engineering for training data

### Production
- Live schema retrieval
- Semantic table ranking
- FK stats for query planning

## FK Stats Format (v4)

```
Join Options:
  1. orders.customer_id -> customers.id [1:N, fk_u=0.85, n=50000, fanout=3.2, risk=MED]
  2. order_items.order_id -> orders.id [1:N, fk_u=1.00, n=150000, fanout=2.8, risk=LOW]

Safe (no-dup) joins: order_items->orders
```

## License

MIT