Ora Documentation

import ora

db = ora.connect("postgresql://localhost/mydb")
result = db.query("Show me top 10 customers by revenue")

# result.dataframe → pandas DataFrame
# result.sql       → the generated SQL
# result.summary   → plain-English explanation

# Core install
pip install ora-sql

# With database extras
pip install ora-sql[postgres]     # asyncpg
pip install ora-sql[snowflake]    # snowflake-connector
pip install ora-sql[bigquery]     # google-cloud-bigquery
pip install ora-sql[all]          # everything

# With Langfuse tracing
pip install ora-sql[langfuse]

import ora
from ora.config import OraConfig

# Anthropic Claude
db = ora.connect("postgresql://...", model="claude-sonnet-4")

# Local Ollama — no API key
db = ora.connect("sqlite:///mydb.db", model="ollama/llama3.3")

# Via env vars
# ORA_LLM_MODEL=gpt-4o-mini ORA_LLM_PROVIDER=openai

# Schema pruning happens automatically — but you can inspect it:
result = db.query("top customers by revenue")
print(result.schema_used)
# → SchemaSnapshot(tables=['customers','orders'], columns=8, pruned_from=347)

# Add business context to improve linking accuracy:
db.add_description("customers.lifetime_value", "Total revenue from customer since sign-up")
db.add_metric("revenue", "SUM(orders.total_amount) WHERE status = 'paid'")

# Configure correction depth
db = ora.connect("postgresql://...",
    max_corrections=5,         # default: 3
    strategy="accurate",        # fast | balanced | accurate
)

with ora.connect(
    sales="postgresql://prod/sales",
    inventory="snowflake://warehouse/inventory",
    staff="headcount.csv",
) as db:
    result = db.ask("which stores have highest revenue per employee?")
    print(result.dataframe)
    # → One DataFrame. Three databases. Zero manual join keys.

# Train a specific pair (thumbs-up equivalent)
await db.train_sql(
    question="top 10 stores by revenue last quarter",
    sql="SELECT store, SUM(total) FROM sales WHERE ...",
)

# Bootstrap from real query logs
from ora.integrations.query_log import SnowflakeHarvester
result = await SnowflakeHarvester(db).harvest(lookback_days=30)
# → HarvestResult(queries_scanned=847, examples_added=312, duplicates_skipped=535)

# Inspect what SOUL has inferred
profile = await db.get_soul(user_id="ash")
print(profile.cadence)      # "weekly"
print(profile.entity_focus) # ["store", "revenue", "employee"]
print(profile.vocabulary)  # {"revenue": "SUM(total_amount)", ...}

from ora.integrations.dbt import load_dbt_docs

result = await load_dbt_docs(db, dbt_project_path="/path/to/dbt")
print(result.models_loaded)      # 47
print(result.columns_described)  # 284
print(result.examples_added)    # 47 (auto-generated questions)

pip install ora-sql
ora serve --mcp --db postgresql://localhost/mydb --port 8080

{
  "mcpServers": {
    "ora": {
      "command": "ora",
      "args": ["serve", "--mcp", "--db", "postgresql://localhost/mydb"]
    }
  }
}

ora serve --db postgresql://localhost/mydb --port 8080
# Open http://localhost:8080

from ora.eval import Evaluator

eval = Evaluator(engine=db, dataset="bird")
results = eval.run(model="gpt-4o", n=100)

print(results.execution_accuracy)  # 0.67
print(results.latency_p95)         # 2.4s
print(results.cost_per_query)      # $0.006
results.save_benchmark_card()      # → benchmark.md (README-ready)

ora.connect(
    connection_string: str,         # or named kwargs for multi-source
    model: str = "gpt-4o-mini",
    strategy: str = "balanced",    # fast | balanced | accurate
    max_rows: int = 1000,
    timeout_seconds: int = 30,
    max_corrections: int = 3,
    trace: bool = False,
    mask_pii: bool = False,
) → OraEngine

result = db.query(
    question: str,
    strategy: str | None = None,  # overrides engine default
) → PipelineResult

# PipelineResult attributes:
result.dataframe    # pandas DataFrame
result.sql          # generated SQL string
result.summary      # plain-English answer
result.follow_ups   # list[str] — suggested next questions
result.chart_config # Chart.js config if applicable
result.trace        # PipelineTrace — timing per stage
result.succeeded    # bool
result.row_count    # int
result.cost_usd     # float — LLM cost for this query

from ora import ask

result = ask("top customers by revenue", db="postgresql://localhost/mydb")
print(result.dataframe)

await db.train_sql(question="...", sql="...")
await db.train_docs(documentation="...")  # free-text business context