# Clone the repo
git clone https://github.com/Veloce-AI/sqlmind.git
cd sqlmind

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate        # Linux / Mac
.venv\Scripts\activate           # Windows

# Install with all extras
pip install -e ".[all]"

# Or just the core + database + graph
pip install -e ".[db,graph]"

cp .env.example .env
# Edit .env — add your key:
# ANTHROPIC_API_KEY=sk-ant-...

# 1. Inspect a schema file
python sqlmind_graph.py inspect examples/schema.sqlmind.yaml

# 2. Find a join path between two tables
python sqlmind_graph.py join-path examples/schema.sqlmind.yaml orders products

# 3. Schema-link a natural language question
python sqlmind_graph.py link examples/schema.sqlmind.yaml "revenue by customer region"

# 4. Export a Mermaid ERD
python sqlmind_graph.py erd examples/schema.sqlmind.yaml > schema.mmd

# 5. Generate SQL from natural language (calls Anthropic API)
python sqlmind_graph.py generate examples/schema.sqlmind.yaml \
  "top 10 customers by total revenue last month" \
  --dialect postgresql

sqlmind/
├── sqlmind_graph.py              ← Property graph engine (SchemaGraph, DialectRegistry, CLI)
├── sqlmind_mcp_server.py         ← MCP server (8 tools)
├── sqlmind.py                    ← Standalone Python ADK agent
├── dialects.yaml                 ← User-editable dialect config (10 engines)
├── SKILL.md                      ← Claude Code skill (phase-locked protocol)
├── CLAUDE.md                     ← Drop in project root to activate skill
├── docs/
│   ├── sqlmind_hero.svg          ← Wide hero image (1360×680) for GitHub README top
│   └── logo.svg                  ← Standalone icon (200×200) for favicon / social preview
├── integrations/
│   ├── sqlmind_google_adk.py     ← Google ADK agent
│   ├── sqlmind_openai_agents.py  ← OpenAI Agents SDK agent
│   └── sqlmind_langgraph.py      ← LangGraph agent + FastAPI server
├── tests/
│   ├── test_graph.py             ← Graph engine tests (14 tests)
│   └── test_dialects.py          ← Dialect registry tests
├── examples/
│   └── schema.sqlmind.yaml       ← Example schema (orders/customers/products)
├── pyproject.toml
├── .env.example
├── CONTRIBUTING.md
└── .github/workflows/ci.yml      ← GitHub Actions CI (pytest on push)

from sqlmind_graph import SchemaGraph

# Load from .sqlmind.yaml
graph = SchemaGraph().load_from_yaml("examples/schema.sqlmind.yaml")

# Load from a live database (requires sqlalchemy)
graph = SchemaGraph().load_from_db("postgresql://user:pass@localhost/mydb")

# Load from DDL
graph = SchemaGraph().load_from_ddl("""
    CREATE TABLE orders (
        id          SERIAL PRIMARY KEY,
        customer_id INTEGER REFERENCES customers(id),
        amount      NUMERIC(10,2)
    );
""")

# BFS join path discovery
path = graph.find_join_path("orders", "products")
print(path.to_sql())
# orders
# INNER JOIN order_items ON orders.id = order_items.order_id
# INNER JOIN products ON order_items.product_id = products.id

# Alias-aware column validation
errors = graph.validate_sql_columns("SELECT o.bad_col FROM orders o")
# → [{"type": "COLUMN_NOT_FOUND", "table": "orders", "column": "bad_col", ...}]

tables:
  orders:
    name: orders
    description: "Customer purchase orders"
    row_count: 2500000
    columns:
      - { name: id,          type: INT,       pk: true }
      - { name: customer_id, type: INT,       fk: true, references: customers.id, indexed: true }
      - { name: amount,      type: DECIMAL }
      - { name: status,      type: VARCHAR,   enum: [pending, confirmed, shipped, cancelled] }
      - { name: created_at,  type: TIMESTAMP, indexed: true }
edges:
  - { from_table: orders, from_col: customer_id, to_table: customers, to_col: id }

TABLE orders (
  id          INT     PK
  customer_id INT     FK→customers.id  IDX
  amount      DECIMAL
  status      VARCHAR [pending, confirmed, shipped, cancelled]
  created_at  TIMESTAMP IDX
)

# Add to Claude Code (stdio mode — works in any directory)
claude mcp add sqlmind --command python --args /path/to/sqlmind_mcp_server.py

# Or drop CLAUDE.md in your project root — Claude Code auto-discovers it

Run sqlmind_introspect on postgresql://localhost/mydb, then use
sqlmind_generate to write SQL for "monthly revenue by customer tier".

{
  "mcp": {
    "servers": {
      "sqlmind": {
        "command": "python",
        "args": ["sqlmind_mcp_server.py"],
        "cwd": "/path/to/sqlmind"
      }
    }
  }
}

# Start in HTTP mode
python sqlmind_mcp_server.py --transport http --port 8765

# Point any HTTP-based MCP client to:
# http://localhost:8765

from integrations.sqlmind_google_adk import create_sqlmind_agent

agent = create_sqlmind_agent(
    schema_path="examples/schema.sqlmind.yaml",
    dialect="bigquery",
)
result = await agent.run("top 5 products by revenue last quarter")
print(result.sql)

gcloud ai agents deploy sqlmind-agent \
  --region=us-central1 \
  --source=integrations/sqlmind_google_adk.py

from integrations.sqlmind_openai_agents import build_sql_agent

agent = build_sql_agent(schema_yaml="examples/schema.sqlmind.yaml")
result = agent.run("monthly revenue by region")
print(result.final_output)

# Start the streaming FastAPI server
uvicorn integrations.sqlmind_langgraph:app --reload --port 8000

# POST a query
curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"query": "orders placed last week", "dialect": "postgresql"}'

# Install dev dependencies
pip install -e ".[db,graph,dev]"

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=sqlmind_graph --cov-report=term-missing

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -e ".[db,graph]"
EXPOSE 8765
CMD ["python", "sqlmind_mcp_server.py", "--transport", "http", "--port", "8765"]

docker build -t sqlmind-mcp .
docker run -p 8765:8765 -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY sqlmind-mcp

# railway.toml
[build]
builder = "NIXPACKS"

[deploy]
startCommand = "python sqlmind_mcp_server.py --transport http --port $PORT"
healthcheckPath = "/"
restartPolicyType = "ON_FAILURE"

python sqlmind_graph.py <command> [options]

Commands:
  inspect    <file>              Print schema stats + DSL
  join-path  <file> <t1> <t2>   Find shortest join path between two tables
  link       <file> <query>      Schema-link a natural language query
  erd        <file>              Export Mermaid ERD to stdout
  generate   <file> <query>      Generate SQL via Anthropic API
               --dialect         Target SQL dialect (default: postgresql)
               --model           Model ID (default: claude-sonnet-4-6)