seamless-rag 0.1.0__tar.gz

seamless_rag-0.1.0/.claude/commands/autorun.md

@@ -0,0 +1,243 @@
+# Seamless-RAG Autonomous Development Loop
+
+You are an autonomous agent building a championship-winning RAG toolkit for the MariaDB Hackathon MY 2026. Execute this loop INDEFINITELY until the user explicitly stops you with Ctrl+C.
+
+**NEVER stop to ask the user anything. NEVER say "shall I continue". Just keep going.**
+
+## Startup Checklist
+
+1. Run `conda run -n seamless-rag python -m pytest tests/unit --co -q 2>&1 | tail -3` to verify env works
+2. Run `conda run -n seamless-rag python scripts/score.py` to see current dashboard
+3. Read `TODO.md` for what needs doing
+4. Read `docs/SPECIFICATION.md` for current state
+5. Begin the main loop at Phase 1
+
+## Main Loop (repeat forever)
+
+### Phase 1: ASSESS — What's the next task?
+
+```
+conda run -n seamless-rag python scripts/score.py
+```
+
+Read `TODO.md`. Pick the **first unchecked item** in priority order.
+If all are checked, look for quality improvements (coverage gaps, flaky tests, missing edge cases, docs).
+
+### Phase 2: RESEARCH — Understand before coding
+
+**RULE: Never guess. Always verify. Use these tools:**
+
+**For understanding a library API or TOON spec detail:**
+```
+Use Agent tool with subagent_type="Explore" to search the reference code:
+  prompt: "Find how the TypeScript TOON encoder handles tabular arrays.
+           Look in /Users/sunfl/Documents/study/MSrag/references/p0-core/toon-official/packages/toon/src/encode/"
+```
+
+**For current best practices or library docs:**
+```
+Use WebSearch tool:
+  query: "mariadb-connector-python array.array vector insert example 2026"
+```
+
+**For complex technical questions requiring deep research:**
+```
+Use Agent tool (general-purpose, background):
+  prompt: "Research how to implement exponential backoff retry in Python for a database
+           polling loop. Find production-grade patterns. Return code examples."
+```
+
+**For reading specific documentation pages:**
+```
+Use WebFetch tool:
+  url: "https://mariadb.com/kb/en/vector-overview/"
+```
+
+**For multi-faceted investigation (spawn a team):**
+```
+Launch multiple Agent tools in parallel:
+  Agent 1: "Research TOON v3 spec Section 7.2 quoting rules by reading /references/p0-core/toon-spec/SPEC.md"
+  Agent 2: "Search web for Python regex patterns for TOON numeric detection"
+  Agent 3: "Read the TypeScript reference encoder at /references/p0-core/toon-official/packages/toon/src/encode/primitives.ts"
+```
+
+### Phase 3: IMPLEMENT — TDD cycle
+
+1. **Read the failing test** carefully — understand exactly what it expects
+2. **Read reference code** if the implementation requires specific API knowledge
+3. **Write the minimum code** to pass the test
+4. **Let the PostToolUse hook** run tests automatically after each edit
+5. If tests pass: move to next failing test
+6. If tests fail: read the error, fix the implementation (NOT the test)
+7. Repeat until all tests in the current component pass
+
+### Phase 4: VERIFY — Broader checks
+
+After a component passes its unit tests:
+```bash
+conda run -n seamless-rag python -m pytest tests/unit -v --tb=short   # all unit tests
+conda run -n seamless-rag ruff check src/seamless_rag/                # lint
+conda run -n seamless-rag python scripts/score.py                     # score dashboard
+```
+
+### Phase 5: CODEX REVIEW — Quality gate
+
+**Before any commit of a new feature or significant refactor, get a Codex review:**
+
+```
+Use Agent tool with subagent_type="codex:codex-rescue":
+  prompt: "Review the TOON v3 tabular encoder implementation at
+           /Users/sunfl/Documents/study/MSrag/workspace/src/seamless_rag/toon/encoder.py
+
+           Check for:
+           1. Correctness against TOON v3 spec (quoting rules, escape sequences, number canonicalization)
+           2. Edge cases: null, empty string, commas in values, newlines, unicode, negative zero
+           3. Code quality: type hints, readability, no unnecessary complexity
+           4. Performance: no quadratic algorithms for large datasets
+
+           Rate the code A/B/C/D and list specific issues to fix."
+```
+
+**Fix ALL issues Codex identifies before committing.** If Codex rates B or lower on critical code (TOON encoder, RAG engine), iterate until it's an A.
+
+### Phase 6: COMMIT & DOCUMENT
+
+```bash
+# Stage specific files (NEVER git add . or git add -A)
+git add src/seamless_rag/toon/encoder.py tests/unit/test_toon_encoder.py
+
+# Atomic commit with conventional prefix
+git commit -m "feat: implement TOON v3 tabular encoder with value quoting and number canonicalization"
+
+# Push
+git push origin main
+```
+
+Then update live docs:
+- Mark the item as `[x]` in `TODO.md`
+- Update `docs/SPECIFICATION.md` with what's now implemented
+- Update `docs/HANDOFF.md` milestones
+
+### Phase 7: ANTI-IDLE & RETRY — Never get stuck, never stop
+
+**Retry policy per failing test (3 escalating attempts):**
+1. Read the error message carefully, fix the obvious issue
+2. Read reference code (TOON spec, TypeScript encoder, winner projects in /references/)
+3. Spawn a research Agent to investigate the root cause with WebSearch
+
+**If all 3 attempts fail on one test:**
+- Log it to `docs/ISSUES.md` with full context (error, what you tried, what you suspect)
+- Mark the TODO item as `[~]` (blocked) 
+- IMMEDIATELY move to the next unblocked TODO item — do NOT dwell
+
+**Retry policy per blocked task:**
+- If a task depends on an unfinished prior task, skip it and pick next independent task
+- If ALL remaining tasks are blocked, revisit blocked items with a completely different approach
+- If still stuck: use `Agent(subagent_type="codex:codex-rescue")` for a second opinion
+
+**Anti-idle rules (CRITICAL):**
+- NEVER pause to "think about it" without taking action — code, research, or move on
+- NEVER output "Let me know if..." or "Would you like me to..." — just do it
+- NEVER wait for user input — make the decision yourself
+- If you finish P0 items, immediately start P1. If P1 done, start P2. Always forward.
+- Between major tasks, ALWAYS run `make score` to see progress
+- If you complete a milestone (e.g., all TOON tests pass): celebrate with a commit, then keep going
+
+**Self-check every 5 tasks:**
+1. Run `make score`. Compare to 5 tasks ago.
+2. If score UNCHANGED after 5 tasks: change strategy (more research, different approach)
+3. If score DECREASED: `git stash` and try a different path
+4. If score INCREASED: you're on the right track, keep going
+
+**Time-boxing (prevent infinite loops):**
+- Single test fix: max 15 minutes — if exceeded, skip and log
+- Single feature: max 2 hours — if exceeded, commit what works, skip remainder
+- If a command hangs: kill it (Ctrl+C), try alternative approach
+
+**After all TODO items done:**
+1. Run `make test-full` for comprehensive check
+2. Run `python eval/harness.py` for benchmark score
+3. Polish README.md with actual benchmark numbers
+4. Push to both remotes: `git push origin main && git push hackathon main`
+5. Start optimizing: find the weakest score, improve it
+
+**NEVER STOP. NEVER ASK. ALWAYS FORWARD.**
+
+## Tool Usage Recipes
+
+### Recipe: "I don't know how this MariaDB API works"
+```
+1. Agent(subagent_type="Explore", prompt="Find vector insert examples in /references/p0-core/mariadb-connector-python/testing/test/integration/")
+2. If not enough: WebSearch("mariadb connector python vector insert array.array example")
+3. If still unclear: WebFetch("https://mariadb-corporation.github.io/mariadb-connector-python/usage.html")
+```
+
+### Recipe: "I need to understand a TOON spec rule"
+```
+1. Read the specific section from /references/p0-core/toon-spec/SPEC.md
+2. Read the TypeScript reference implementation in /references/p0-core/toon-official/packages/toon/src/encode/
+3. Check the test fixtures in tests/fixtures/toon_spec/encode/ for examples
+```
+
+### Recipe: "A test is failing and I don't understand why"
+```
+1. Run the single failing test with -v --tb=long to see full traceback
+2. Read the test code to understand what it expects
+3. Read the fixture/input data
+4. If it's a TOON spec test: compare with the TypeScript reference encoder output
+5. If still stuck: spawn an Agent to investigate the specific edge case
+```
+
+### Recipe: "I need to make a design decision"
+```
+1. Check CLAUDE.md and docs/ARCHITECTURE.md for existing decisions
+2. Spawn parallel research agents:
+   Agent 1: "Search web for [option A] best practices"
+   Agent 2: "Search web for [option B] best practices"
+   Agent 3: "Check how the YT semantic search winner handled this in /references/p1-reference/yt-semantic-search-winner/"
+3. Compare findings against the 5 judge directives
+4. Choose the option, document in docs/ARCHITECTURE.md
+5. Proceed — do NOT ask the user
+```
+
+### Recipe: "Integration test needs Docker MariaDB"
+```bash
+# Start test MariaDB
+docker compose -f docker-compose.test.yml up -d --wait
+# Run integration tests
+conda run -n seamless-rag python -m pytest tests/integration -v --tb=short
+# Clean up
+docker compose -f docker-compose.test.yml down -v
+```
+
+### Recipe: "Final delivery push to hackathon remote"
+```bash
+# Ensure all tests pass
+conda run -n seamless-rag python -m pytest tests/ -v --tb=short -m "not eval"
+# Push to personal
+git push origin main
+# Push to hackathon
+git push hackathon main
+```
+
+## Quality Gates
+
+Before marking any feature "done":
+- [ ] All related unit tests pass (not just the new ones)
+- [ ] `ruff check` passes on changed files
+- [ ] `make score` shows improvement or no regression
+- [ ] Codex review is A-grade (for critical components)
+- [ ] Commit is atomic with conventional message prefix
+- [ ] `docs/SPECIFICATION.md` and `TODO.md` are updated
+
+## Completion Criteria (the project is "done" when ALL are true)
+
+1. `make score` → 100% unit + 100% spec + 95%+ props
+2. `make test-full` → all pass including Docker integration
+3. `python eval/harness.py` → composite score >= 80
+4. `docker compose up -d && conda run -n seamless-rag seamless-rag ask "test question"` → works end-to-end
+5. README.md → judge-ready with architecture, benchmarks, quick start
+6. JUDGES_TESTING_GUIDE.md → exists with 4 evaluation tiers
+7. All critical code Codex-reviewed at A grade
+8. Pushed to both `origin` and `hackathon` remotes
+9. `docs/HANDOFF.md` → all milestones marked complete

seamless_rag-0.1.0/.claude/settings.json

@@ -0,0 +1,52 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(conda run -n seamless-rag *)",
+      "Bash(docker compose *)",
+      "Bash(make *)",
+      "Bash(git *)",
+      "Bash(gh *)",
+      "Bash(pip install *)",
+      "Bash(python -m pytest *)",
+      "Bash(python eval/*)",
+      "Bash(python scripts/*)",
+      "Bash(ruff *)",
+      "WebSearch",
+      "WebFetch(domain:mariadb.org)",
+      "WebFetch(domain:toonformat.dev)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:docs.python.org)",
+      "WebFetch(domain:mariadb.com)",
+      "WebFetch(domain:mariadb-corporation.github.io)",
+      "WebFetch(domain:huggingface.co)",
+      "WebFetch(domain:sdk.vercel.ai)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // empty' 2>/dev/null); MOD=$(basename \"$(dirname \"$FILE\")\"); if echo \"$FILE\" | grep -q 'src/seamless_rag/toon'; then conda run -n seamless-rag python -m pytest tests/unit/test_toon_encoder.py tests/unit/test_toon_properties.py -x -q --tb=line --no-header 2>&1 | tail -10; elif echo \"$FILE\" | grep -q 'src/seamless_rag/benchmark'; then conda run -n seamless-rag python -m pytest tests/unit/test_token_benchmark.py -x -q --tb=line --no-header 2>&1 | tail -10; elif echo \"$FILE\" | grep -q 'src/seamless_rag/pipeline'; then conda run -n seamless-rag python -m pytest tests/unit/test_rag_pipeline.py -x -q --tb=line --no-header 2>&1 | tail -10; elif echo \"$FILE\" | grep -q 'src/seamless_rag/providers'; then conda run -n seamless-rag python -m pytest tests/unit/test_embedding_provider.py -x -q --tb=line --no-header -m 'not slow' 2>&1 | tail -10; elif echo \"$FILE\" | grep -q 'tests/'; then conda run -n seamless-rag python -m pytest \"$FILE\" -x -q --tb=line --no-header 2>&1 | tail -10; else conda run -n seamless-rag python -m pytest tests/unit -x -q --tb=line --no-header -m 'not slow' -o addopts= 2>&1 | tail -10; fi",
+            "timeout": 30000
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command // empty' 2>/dev/null); if echo \"$CMD\" | grep -q 'git commit'; then cd \"$CLAUDE_PROJECT_DIR\" && conda run -n seamless-rag python -m pytest tests/unit -x -q --tb=no 2>&1 | tail -3; fi; exit 0",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}

seamless_rag-0.1.0/.claude/skills/seamless-rag/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: seamless-rag
+description: "Work with the Seamless-RAG toolkit — MariaDB vector search, TOON encoding, auto-embedding, and RAG queries. Use this skill when the user works in the seamless-rag project, asks about MariaDB vector operations, TOON format encoding, embedding providers, or RAG pipeline tasks. Also trigger when the user wants to query databases via vector search, convert data to TOON format, or manage MariaDB embedding workflows."
+---
+
+# Seamless-RAG Agent Skill
+
+Seamless-RAG is a **thin bridging layer** between MariaDB and LLMs/agents. It does NOT replace SQL — it complements it with vector search for semantic queries, and provides TOON format for token-efficient data consumption.
+
+```
+Agent (intent, strategy, judgment)
+  ↕ CLI / Python API
+Seamless-RAG (embed rows, vector search, format as TOON)
+  ↕ mariadb-connector-python
+MariaDB (store, index, execute SQL + VEC_DISTANCE)
+```
+
+## When to Use What
+
+- **Precise query** ("Q3 revenue > 1M", aggregations, JOINs): use the **text-to-sql** skill → generates SQL → `export()` → TOON
+- **Semantic query** ("find similar products"): `rag.ask(question)` for vector search
+- **Hybrid** ("waterproof watches under $50"): `rag.ask(question, where="price < 50")`
+- **Any SQL result → LLM**: always use `export()` to convert to TOON before feeding to LLM
+
+> **Routing rule**: if the user's question involves numbers, aggregations, GROUP BY, or exact filters → route to `text-to-sql` skill. If it's fuzzy/semantic → use `ask`. If both → use `ask --where`.
+
+## Reading TOON Format
+
+When you receive TOON output from seamless-rag tools, read it like this:
+
+```
+[N,]{col1,col2,col3}:     ← header: N rows, column names in order
+  val1,val2,val3           ← row 1: values match column positions
+  val4,val5,val6           ← row 2
+```
+
+**Example — this TOON:**
+```
+[3,]{id,name,price,in_stock}:
+  1,Widget,29.99,true
+  2,"Smith, John",19.99,false
+  3,Gizmo,null,true
+```
+
+**Means the same as this JSON:**
+```json
+[{"id":1,"name":"Widget","price":29.99,"in_stock":true},
+ {"id":2,"name":"Smith, John","price":19.99,"in_stock":false},
+ {"id":3,"name":"Gizmo","price":null,"in_stock":true}]
+```
+
+**TOON rules:**
+- Header `[N,]{...}:` tells you row count and column names
+- Each indented line is one row, values in column order
+- `null` = no value, `true`/`false` = booleans
+- Quoted values (`"Smith, John"`) contain commas or special characters
+- Unquoted values are plain text, numbers, or booleans
+- Numbers are canonical: no scientific notation, no trailing zeros
+
+**Why TOON over JSON**: 10-55% fewer tokens vs compact JSON for structured data. Field names appear once in the header instead of repeating per row. Savings are highest with many rows and short values.
+
+## Project Location
+
+```
+/Users/sunfl/Documents/study/MSrag/workspace/
+```
+
+**Conda env**: `seamless-rag` — always prefix commands with `conda run -n seamless-rag`.
+
+## CLI Commands
+
+Global options: `--host`, `--port`, `--user`, `--password`, `--database`, `--provider`, `--model`, `--log-level`
+
+```bash
+# Core: data already in MariaDB → add vectors
+seamless-rag init                                            # VECTOR columns + HNSW index
+seamless-rag embed [--table chunks] [--column content]       # Bulk-embed single column
+seamless-rag embed --table products --columns "name,category,price"  # Multi-column embed
+seamless-rag watch [--table chunks] [--columns "name,desc"]  # Auto-embed new inserts
+
+# Query
+seamless-rag ask "question" [--top-k 5] [--where "price<50"] [--mmr] [--context-window 1]
+seamless-rag export "SELECT ... FROM ..."                    # Any SQL → TOON format
+
+# Tools
+seamless-rag benchmark [--rows 50] [--cols 6]                # JSON vs TOON comparison
+seamless-rag web [--port 7860] [--share]                     # Gradio web UI (localhost-only by default)
+seamless-rag demo                                            # End-to-end demo
+seamless-rag ingest <path> [--chunk-size 500] [--overlap 50] # Load text files for testing
+```
+
+## Python API
+
+```python
+from seamless_rag import SeamlessRAG
+
+with SeamlessRAG(host="127.0.0.1", database="seamless_rag") as rag:
+    rag.init()                                        # create schema
+
+    # Single-column embed (default)
+    rag.embed_table("articles", text_column="content")
+
+    # Multi-column embed — richer semantics
+    rag.embed_table("products", text_column=["name", "category", "price"])
+    # Internally: "Widget — Tools — 29.99" → searches match name AND price
+
+    # Semantic search with hybrid filter
+    result = rag.ask("waterproof watches", top_k=5, where="price < 500", mmr=True)
+    # result.answer           : str       — LLM answer
+    # result.context_toon     : str       — TOON context (feed to next LLM call)
+    # result.savings_pct      : float     — token savings vs compact JSON
+    # result.sources          : list[dict] — raw results
+
+    # SQL → TOON (for precise queries, agent tools)
+    toon = rag.export("SELECT region, SUM(revenue) FROM sales GROUP BY region")
+```
+
+## TOON Encoder (standalone)
+
+```python
+from seamless_rag.toon.encoder import encode_tabular
+
+toon = encode_tabular([
+    {"id": 1, "name": "Alice", "score": 95},
+    {"id": 2, "name": "Bob",   "score": 87},
+])
+# → [2,]{id,name,score}:
+#     1,Alice,95
+#     2,Bob,87
+```
+
+## Provider Configuration
+
+| Variable | Default | Options |
+|----------|---------|---------|
+| `EMBEDDING_PROVIDER` | `sentence-transformers` | `sentence-transformers`, `gemini`, `openai`, `ollama` |
+| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Model name for chosen provider |
+| `LLM_PROVIDER` | `ollama` | `ollama`, `gemini`, `openai` |
+| `LLM_MODEL` | `qwen3:8b` | Model name for chosen provider |
+| `EMBEDDING_API_KEY` | (empty) | Required for gemini/openai embedding |
+| `LLM_API_KEY` | (empty) | Required for gemini LLM |
+| `OPENAI_API_KEY` | (empty) | Required for openai LLM |
+| `LLM_BASE_URL` | (empty) | Custom Ollama endpoint |
+| `SEAMLESS_WEB_USER` | (empty) | Web UI auth username (required for --share) |
+| `SEAMLESS_WEB_PASSWORD` | (empty) | Web UI auth password (required for --share) |
+
+## Security
+
+- **SQL injection prevention**: WHERE filters validated via sqlglot AST — blocks writes, DDL, subqueries, dangerous functions
+- **Web UI**: localhost-only by default; `--share` requires auth env vars
+- **LLM**: context truncated to 20K chars; retry with jitter for transient errors
+
+## Testing
+
+```bash
+conda run -n seamless-rag make test-all    # lint + unit + spec (no Docker)
+conda run -n seamless-rag make test-full   # includes integration
+conda run -n seamless-rag make score       # quality dashboard
+```
+
+538/538 tests passing (100%). TOON spec: 166/166.
+
+## Agent Workflow Patterns
+
+### Pattern 1: SQL results as agent context
+```python
+# Agent generates SQL, seamless-rag formats as TOON
+toon = rag.export("SELECT product, revenue, margin FROM sales WHERE quarter='Q3'")
+# Feed toon to next LLM call — 60% fewer tokens than JSON
+```
+
+### Pattern 2: Semantic search on text columns
+```python
+# When the question is fuzzy, not expressible as SQL
+result = rag.ask("products customers complained about", top_k=10, mmr=True)
+```
+
+### Pattern 3: Hybrid filter + semantic
+```python
+# Combine SQL precision with vector semantics
+result = rag.ask("reliable laptops", where="price < 1000 AND category = 'electronics'")
+```
+
+### Pattern 4: Multi-column embedding for rich search
+```python
+# Embed multiple columns for searches that span fields
+rag.embed_table("products", text_column=["name", "category", "price", "rating"])
+# Internal: "Widget — Tools — 29.99 — 4.5"
+# Now "cheap high-rated tools" matches on ALL fields, not just description
+result = rag.ask("cheap high-rated tools", where="price < 50")
+```
+
+### Pattern 5: Multi-step agent with accumulated TOON context
+```python
+# Each step: query DB → TOON → feed to LLM → next decision
+# TOON saves 15-30% per step, compounding over 20 steps
+step1 = rag.export("SELECT region, SUM(revenue) FROM sales GROUP BY region")
+# LLM analyzes, decides to drill into worst region
+step2 = rag.export("SELECT product, units FROM sales WHERE region='EMEA' AND quarter='Q3'")
+```

seamless_rag-0.1.0/.claude/skills/text-to-sql/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: text-to-sql
+description: "Convert natural language questions into SQL, execute against MariaDB, and return results in TOON format. Use when the user asks a data question that needs a precise SQL query — revenue reports, aggregations, filtered lookups, JOINs — rather than semantic/vector search. Works with any MariaDB database the user has access to."
+---
+
+# Text-to-SQL Agent Skill
+
+Turn natural language into SQL → execute → return TOON-formatted results.
+
+This skill is the **precise query** complement to `seamless-rag ask` (semantic search). Use this when the user's question maps to exact SQL — numbers, aggregations, filters, JOINs.
+
+```
+User: "What's the average rating of comedy movies from the 2000s?"
+  ↓
+Agent: inspect schema → generate SQL → execute via seamless-rag export → TOON result
+```
+
+## When to Use This vs `seamless-rag ask`
+
+| Signal | Use text-to-sql | Use `seamless-rag ask` |
+|--------|----------------|----------------------|
+| Numbers, aggregations | "average revenue", "count of", "top 10 by" | - |
+| Exact filters | "where price > 100", "in Q3 2025" | - |
+| JOINs, GROUP BY | "revenue by region" | - |
+| Fuzzy / semantic | - | "movies similar to Inception" |
+| Hybrid | Generate SQL with WHERE, pass to `ask --where` | `ask "query" --where "price < 50"` |
+
+## Workflow
+
+### Step 1: Discover schema
+
+```bash
+# List databases
+conda run -n seamless-rag python -c "
+import mariadb
+conn = mariadb.connect(host='127.0.0.1', port=3306, user='root', password='seamless')
+cur = conn.cursor()
+cur.execute('SHOW DATABASES')
+for row in cur: print(row[0])
+cur.close(); conn.close()
+"
+
+# List tables in a database
+conda run -n seamless-rag python -c "
+import mariadb
+conn = mariadb.connect(host='127.0.0.1', port=3306, user='root', password='seamless', database='DATABASE_NAME')
+cur = conn.cursor()
+cur.execute('SHOW TABLES')
+for row in cur: print(row[0])
+cur.close(); conn.close()
+"
+
+# Get table schema
+conda run -n seamless-rag python -c "
+import mariadb
+conn = mariadb.connect(host='127.0.0.1', port=3306, user='root', password='seamless', database='DATABASE_NAME')
+cur = conn.cursor()
+cur.execute('DESCRIBE TABLE_NAME')
+for row in cur: print(f'{row[0]:20s} {row[1]:20s} {row[2] or \"\"}')
+cur.close(); conn.close()
+"
+
+# Sample data (first 3 rows)
+conda run -n seamless-rag seamless-rag --database DATABASE_NAME export "SELECT * FROM TABLE_NAME LIMIT 3"
+```
+
+### Step 2: Generate SQL
+
+Given the schema, write a SELECT query. Rules:
+- **SELECT only** — never generate INSERT, UPDATE, DELETE, DROP, ALTER
+- **Use LIMIT** — always add LIMIT unless the user asks for "all"
+- **Validate column names** against the schema — don't guess
+- **Use aliases** for readability: `AVG(price) AS avg_price`
+- **MariaDB dialect** — use `LIMIT` not `TOP`, backtick identifiers if needed
+
+### Step 3: Execute and return TOON
+
+```bash
+conda run -n seamless-rag seamless-rag --database DATABASE_NAME export "YOUR_SQL_HERE"
+```
+
+The `export` command:
+- Validates the SQL (rejects writes/DDL via sqlglot AST parsing)
+- Executes the query
+- Converts results to TOON tabular format
+- Prints to stdout
+
+### Step 4: Present results
+
+Show the TOON output directly. If the user needs analysis, feed the TOON to your next reasoning step — it's already token-efficient.
+
+## Examples
+
+### Simple aggregation
+```
+User: "What genres have the highest average rating?"
+
+→ Schema check: movielens.top_movies has (id, title, genres, year, avg_rating, num_ratings, tags)
+
+→ SQL: SELECT genres, ROUND(AVG(avg_rating), 2) AS avg_score, COUNT(*) AS count
+       FROM top_movies GROUP BY genres ORDER BY avg_score DESC LIMIT 10
+
+→ Execute: seamless-rag --database movielens export "SELECT genres, ..."
+```
+
+### Filtered lookup
+```
+User: "Show me high-risk restaurant violations in 94110"
+
+→ Schema check: restaurant.violations has (id, business_name, ..., postal_code, ..., risk_category)
+
+→ SQL: SELECT business_name, violation_description, inspection_score
+       FROM violations WHERE risk_category = 'High Risk' AND postal_code = '94110'
+       ORDER BY inspection_score ASC LIMIT 20
+
+→ Execute: seamless-rag --database restaurant export "SELECT ..."
+```
+
+### Multi-table JOIN
+```
+User: "Which documents have the most chunks?"
+
+→ SQL: SELECT d.title, COUNT(c.id) AS chunk_count
+       FROM documents d JOIN chunks c ON c.document_id = d.id
+       GROUP BY d.id ORDER BY chunk_count DESC LIMIT 10
+
+→ Execute: seamless-rag --database seamless_rag export "SELECT ..."
+```
+
+## Available Databases
+
+Check what's available by running `SHOW DATABASES`. Common ones in this project:
+
+| Database | Tables | Description |
+|----------|--------|-------------|
+| `seamless_rag` | documents, chunks | Default RAG database (demo data) |
+| `movielens` | movies, top_movies | 9.7K movies with ratings and tags |
+| `restaurant` | inspections, violations | 54K SF restaurant health inspections |
+
+## Security
+
+The `seamless-rag export` command validates all SQL via sqlglot AST parsing:
+- Only SELECT queries are allowed
+- INSERT/UPDATE/DELETE/DROP/ALTER are blocked
+- Subqueries with writes are blocked
+- Dangerous functions (SLEEP, BENCHMARK, LOAD_FILE) are blocked
+
+This means you can safely pass user-influenced queries through `export`.
+
+## Connection Config
+
+Default connection (from `.env` or CLI flags):
+- Host: `127.0.0.1`
+- Port: `3306`
+- User: `root`
+- Password: `seamless`
+
+Override with: `seamless-rag --host X --port Y --user Z --password W --database DB export "SQL"`