🔭 Kepler
An AI-powered data agent that lets you query databases using natural language. Ask questions in plain English and get SQL queries, validated results, and auto-generated visualizations.
⚙️ How It Works
- 💬 You ask a question in natural language
- 🔍 Kepler discovers relevant tables and recalls past learnings
- 🧠 The AI agent writes SQL, executes it read-only, and validates the results
- 📊 Results are displayed with suggested charts when appropriate
✨ Features
- 💬 Natural language querying — Ask questions in plain English, get SQL + results
- 🔍 Schema discovery — Automatic introspection of tables, columns, types, and sample data
- ✅ Smart validation — Checks for zero rows, high NULL rates, suspicious aggregations
- 🧠 Persistent memory — Learns corrections, schema notes, and patterns across sessions
- 📂 Query inference — Upload historical SQL files for the agent to learn from
- 🏠 ClickHouse support — Connect to ClickHouse via
CLICKHOUSE_URL; SQLite used when unset - 📤 CSV upload — Import CSV files with automatic type inference (into SQLite or ClickHouse)
- 📊 Auto-generated charts — Bar, line, pie, and area charts via Recharts
- 🔎 Semantic search (RAG) — Qdrant + Ollama embeddings for finding relevant context
- 📝 Annotations — Domain experts can annotate tables and columns with business meaning
🛠️ Tech Stack
- Frontend: Next.js 16, React 19, Tailwind CSS 4, Recharts
- Backend: Next.js API routes, Better-sqlite3, ClickHouse, Vercel AI SDK
- AI: OpenAI GPT-4o with tool-based agentic workflow
- Vector search: Qdrant + Ollama (nomic-embed-text)
- Infrastructure: Docker Compose
🚀 Quick Start
Prerequisites
- 📦 Node.js 20+
- 📦 pnpm
- 🔑 An OpenAI API key
Local Development
# Install dependencies pnpm install # Configure environment cp .env.example .env # Edit .env and add your OPENAI_API_KEY # Start the dev server pnpm dev
The app will be available at http://localhost:3000. By default it runs in demo mode with sample e-commerce data (customers, products, orders).
🐳 Docker Compose
# Set your API key export OPENAI_API_KEY=sk-... # Start all services (app + Qdrant + Ollama) docker compose up -d # Optional: run the enrichment sidecar for semantic search docker compose --profile enrich up -d
This starts three services:
| Service | Port | Purpose |
|---|---|---|
| 🔭 kepler | 3000 | Next.js application |
| 🗄️ qdrant | 6333 | Vector database |
| 🤖 ollama | 11434 | Local embedding model |
🔧 Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
OPENAI_API_KEY |
✅ | — | OpenAI API key |
KEPLER_MODE |
❌ | demo |
demo seeds sample data, service uses existing DB |
QDRANT_URL |
❌ | http://localhost:6333 |
Qdrant vector database URL |
OLLAMA_URL |
❌ | http://localhost:11434 |
Ollama embedding service URL |
EMBEDDING_MODEL |
❌ | nomic-embed-text |
Embedding model name |
CLICKHOUSE_URL |
❌ | — | ClickHouse HTTP URL (enables ClickHouse mode) |
CLICKHOUSE_DATABASE |
❌ | default |
ClickHouse database name |
CLICKHOUSE_USER |
❌ | default |
ClickHouse username |
CLICKHOUSE_PASSWORD |
❌ | — | ClickHouse password |
When CLICKHOUSE_URL is set, data queries run against ClickHouse. Internal tables (memories, query history, annotations) always stay in SQLite. Semantic search is optional — if Qdrant/Ollama are unavailable, Kepler falls back to keyword-based schema matching.
🧰 Makefile
Run make help to see all available commands.
make setup # 🏗️ Full first-time setup: install deps, start infra, pull embedding model make up # 🚀 Start infra + dev server with ClickHouse make dev # 💻 Dev server with SQLite only make dev-ch # 🏠 Dev server with ClickHouse make infra # 🐳 Start infra services (ClickHouse, Qdrant, Ollama) make infra-stop # ⏹️ Stop infra services make pull-model # 📥 Pull the embedding model into Ollama make enrich # 🔎 Run the RAG enrichment sidecar make build # 📦 Production build make start # ▶️ Production server (SQLite) make start-ch # ▶️ Production server (ClickHouse) make clean # 🧹 Stop infra and remove volumes
🏁 One-click from scratch
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
make setup
make up📁 Project Structure
src/
├── app/
│ ├── page.tsx # 🏠 Landing page
│ ├── demo/page.tsx # 💬 Chat interface
│ ├── docs/ # 📖 Documentation pages
│ └── api/
│ ├── chat/route.ts # 🧠 AI agent (streaming, tools)
│ ├── schema/route.ts # 🔍 Table schema endpoint
│ ├── upload/route.ts # 📤 CSV upload
│ ├── queries/route.ts # 📂 Query history
│ ├── memories/route.ts # 🧠 Memory CRUD
│ └── annotations/ # 📝 Annotation CRUD
├── components/ # 🧩 React components
├── lib/
│ ├── db.ts # 🗄️ Database operations (SQLite + ClickHouse delegation)
│ ├── clickhouse.ts # 🏠 ClickHouse client + data functions
│ ├── rag.ts # 🔎 Qdrant vector search
│ ├── enrichment.ts # ✨ Table context builder
│ ├── schema.ts # 📋 Schema formatting & scoring
│ └── types.ts # 📐 TypeScript interfaces
scripts/
└── enrich.ts # 🔄 Enrichment pipeline
data/
└── kepler.db # 💾 SQLite database
📜 Scripts
pnpm dev # 💻 Start development server pnpm build # 📦 Production build pnpm start # ▶️ Start production server pnpm lint # 🔍 Run ESLint pnpm enrich # 🔄 Run the enrichment pipeline
📄 License
Private