KAI

Knowledge Agent for Intelligence Query

Transform natural language into powerful data insights

Documentation • Getting Started • Contributing • Architecture

Overview
Key Features
Quickstart
Web UI
Development Setup
Architecture
CLI Usage & Tutorial
Environment Configuration
Testing
Contributing
License

Overview

KAI (Knowledge Agent for Intelligence Query) is an AI-powered data agent that transforms how you interact with databases. Using natural language, you can:

Query databases without writing SQL
Generate insights with advanced analytics (forecasting, anomaly detection, statistical analysis)
Create dashboards from natural language descriptions
Search documents across large datasets
Remember context across sessions with long-term memory

Built with FastAPI, LangGraph, and LangChain, KAI supports multiple LLM providers (OpenAI, Google Gemini, Ollama, OpenRouter) and integrates seamlessly with your existing data infrastructure.

Access Options:

Web UI - Modern Next.js interface for visual interaction
REST API - 40+ endpoints for programmatic access
CLI - Command-line tool for terminal-based workflows

Key Features

Natural Language Querying

Ask questions in plain English—no SQL knowledge required. KAI translates your intent into optimized database queries.

Advanced Analytics

Statistical analysis (correlation, regression)
Time series forecasting
Anomaly detection
Automated insights generation

Dashboard Creation

Generate interactive dashboards from natural language descriptions using natural language.

Long-term Memory

Persistent memory across sessions using Typesense or Letta backends to maintain context.

Multi-LLM Support

Flexible LLM provider support:

OpenAI (GPT-4, GPT-3.5)
Google Gemini
Ollama (local models)
OpenRouter

Production-Ready

LangGraph-based agent architecture
FastAPI for high-performance APIs
Docker deployment support
Comprehensive testing suite

Quickstart

Get KAI running in 5 minutes with Docker Compose!

Prerequisites

Docker & Docker Compose (Install Docker)
API Key from OpenAI, Google, or other LLM provider

Setup

1. Clone the repository

git clone https://github.com/mta-tech/KAI.git
cd kai

2. Create environment configuration

cp .env.example .env

3. Configure your LLM provider

Edit .env and set your LLM configuration:

# Choose your LLM provider
CHAT_FAMILY=openai  # or: google, ollama, openrouter
CHAT_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-api-key-here

# Required: Generate encryption key for database credentials
ENCRYPT_KEY=  # See below

4. Generate encryption key

uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Copy the output and paste it as ENCRYPT_KEY in your .env file.

Running with Docker

Start all services:

docker compose up -d

Verify services are running:

docker compose ps

Expected output:

NAME         IMAGE                      STATUS          PORTS
kai_engine   kai-kai_engine             Up 2 minutes    0.0.0.0:8015->8015/tcp
typesense    typesense/typesense:26.0   Up 2 minutes    0.0.0.0:8108->8108/tcp

Access the application:

API Documentation: http://localhost:8015/docs
Typesense: http://localhost:8108

Test the API:

curl http://localhost:8015/health
# Expected: {"status":"healthy"}

Stopping Services

docker compose down

Note: Data in ./app/data/dbdata persists across restarts.

Next Steps

Now that KAI is running, explore these options:

Web UI - Visual interface with dashboard builder
Dashboard Tutorial - Create dashboards from natural language
CLI Tutorial - Terminal-based workflows
API Documentation - Programmatic access

Web UI

KAI includes a modern web interface built with Next.js for visual, interactive data analysis.

Features

Interactive Chat - Natural language conversations with your data
Dashboard Builder - Create visual dashboards from text descriptions
SQL Query Interface - Write and execute queries with visual results
Analytics Visualizations - View forecasts, trends, and statistical analysis
Database Management - Configure connections and settings through UI

Quick Start

1. Ensure the backend is running

docker compose up -d
# Backend available at http://localhost:8015

2. Navigate to UI directory

cd ui

3. Install dependencies

npm install
# or
yarn install

4. Configure environment

Create ui/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8015
NEXT_PUBLIC_API_BASE_PATH=/api/v1

5. Start the UI

npm run dev

6. Open in browser

Visit http://localhost:3000

Using the Web UI

Create a session:

Navigate to "New Session"
Select your database connection
Start asking questions in natural language

Example interactions:

"Show me total sales by month"
"Create a dashboard with revenue trends and top products"
"What are the customer demographics?"
"Forecast sales for next quarter"

View results:

SQL queries are shown with syntax highlighting
Results displayed in interactive tables
Charts auto-generated for time series and distributions
Download results as CSV or JSON

Creating Dashboards Tutorial

KAI can automatically generate interactive dashboards from natural language descriptions.

Step 1: Access Dashboard Builder

Navigate to the "Dashboards" section in the Web UI.

Step 2: Describe your dashboard

Enter a natural language description of what you want to see:

Create a sales dashboard showing:
- Total revenue this month
- Top 5 products by sales
- Revenue trend over the last 12 months
- Customer distribution by region

Step 3: Select database

Choose the database connection to query from.

Step 4: Generate

Click "Generate Dashboard" and KAI will:

Analyze your description
Generate appropriate SQL queries
Execute queries against your database
Create visualizations (charts, tables, KPIs)
Arrange components in a responsive layout

Step 5: Customize

Rearrange dashboard components via drag-and-drop
Adjust chart types (bar, line, pie, etc.)
Modify time ranges and filters
Save dashboard for future use

Via API:

You can also create dashboards programmatically:

curl -X POST http://localhost:8015/api/v1/dashboards \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Overview",
    "description": "Show total revenue, top products, and monthly trends",
    "db_connection_id": "your-connection-id"
  }'

Via CLI:

uv run kai create-dashboard \
  "Sales dashboard with revenue trends and top products" \
  --db sales

For detailed UI documentation and advanced features, see ui/README.md.

Development Setup

For local development without Docker:

Prerequisites

Python 3.11+ (Download)
uv package manager (Install uv)

Installation

1. Install dependencies

uv sync

2. Start Typesense (required)

docker compose up typesense -d

3. Configure environment

cp .env.example .env
# Edit .env with your settings (use TYPESENSE_HOST=localhost for local dev)

4. Run the development server

uv run python -m app.main

Or with hot reload:

APP_ENABLE_HOT_RELOAD=1 uv run python -m app.main

5. Access the API

API: http://localhost:8015
API Docs: http://localhost:8015/docs

LangGraph Development

For working with LangGraph agents:

uv run langgraph dev

This starts the LangGraph Studio interface for debugging agent workflows.

Architecture

KAI follows a modular, layered architecture:

┌─────────────────────────────────────────────────────┐
│                 FastAPI REST API                     │
│                  (app/api/)                          │
├─────────────────────────────────────────────────────┤
│                 Service Layer                        │
│  ┌──────────┬──────────┬──────────┬──────────┐     │
│  │ Session  │   SQL    │Analytics │Dashboard │     │
│  │  Module  │ Module   │  Module  │  Module  │     │
│  └──────────┴──────────┴──────────┴──────────┘     │
├─────────────────────────────────────────────────────┤
│             Repository Layer                         │
│        (Data Access via Typesense)                   │
├─────────────────────────────────────────────────────┤
│      LangGraph Agents & LLM Adapters                │
│   ┌────────────────┬──────────────────┐            │
│   │ Session Graph  │  SQL Agent Graph │            │
│   └────────────────┴──────────────────┘            │
├─────────────────────────────────────────────────────┤
│            Storage & External Services               │
│   ┌──────────┬───────────┬──────────────┐          │
│   │Typesense │  Database │  LLM APIs    │          │
│   │ (Vector) │ (User DB) │ (OpenAI/etc) │          │
│   └──────────┴───────────┴──────────────┘          │
└─────────────────────────────────────────────────────┘

Key Components

FastAPI Server: REST API with 40+ endpoints
LangGraph Agents: Conversational session management and SQL generation
Service Modules: Domain-specific business logic (analytics, dashboards, visualization)
Typesense: Vector search and document storage
LLM Adapters: Unified interface for multiple LLM providers

For detailed architecture documentation, see ARCHITECTURE.md.

Testing

Run the test suite:

# All tests
uv run pytest

# With coverage
uv run pytest --cov=app

# Specific module
uv run pytest tests/modules/session/

# Single test
uv run pytest tests/unit/test_deep_agent_adapter.py::test_function_name

Note: Tests require a running Typesense instance. Start it with:
docker compose up typesense -d

CLI Usage

KAI provides a powerful command-line interface organized into logical command groups for database management, knowledge curation, and natural language analysis.

Quick CLI Tutorial

Here's a complete workflow from connecting to your database to running queries:

Step 1: Connect to your database

# PostgreSQL
uv run kai connection create \
  "postgresql://user:password@localhost:5432/sales_db" \
  -a sales

# MySQL
uv run kai connection create \
  "mysql://user:password@localhost:3306/crm_db" \
  -a crm

# SQLite
uv run kai connection create \
  "sqlite:///path/to/database.db" \
  -a local_db

Step 2: Scan your database schema

Let KAI understand your database structure:

# Basic scan
uv run kai table scan-all sales

# With AI-generated descriptions (recommended)
uv run kai table scan-all sales -d

# With MDL semantic layer generation
uv run kai table scan-all sales -d --generate-mdl

This analyzes your tables, columns, and relationships, generating descriptions to help the AI understand your data model.

Step 3: Run your first query

Try these example queries:

# One-shot query
uv run kai query run "Show total sales by month for 2024" --db sales

# Another example
uv run kai query run "List top 10 customers by revenue" --db sales

# Complex analytics
uv run kai query run "Analyze correlation between price and quantity sold" --db sales

Step 4: Interactive mode

For back-and-forth conversations:

uv run kai query interactive --db sales

Then ask questions naturally:

> Show me total revenue this quarter
> Which products are underperforming?
> Create a forecast for next month's sales
> What's the average order value by customer segment?

Type exit or press Ctrl+D to quit.

Command Reference

The CLI is organized into 8 command groups:

kai
├── config              # Configuration and system utilities
├── connection          # Database connection management
├── table               # Table management and schema scanning
├── query               # Query execution and interactive sessions
├── session             # Session management and export
├── dashboard           # Dashboard creation and management
├── knowledge           # Knowledge management
│   ├── glossary        #   Business metric definitions
│   ├── instruction     #   SQL generation rules
│   ├── skill           #   Reusable analysis patterns
│   └── memory          #   Long-term memory store
└── mdl                 # Semantic layer (MDL) management

Connection management:

kai connection create <uri> -a <alias>     # Add database connection
kai connection list                        # List all connections
kai connection show <id_or_alias>          # Show connection details
kai connection test <uri>                  # Test without saving
kai connection update <id> --alias <name>  # Update connection
kai connection delete <id> [-f]            # Remove connection

Table management:

kai table list <connection_id>             # List tables
kai table show <table_id>                  # Show table details
kai table scan <connection_id> -d          # Scan with AI descriptions
kai table scan-all <connection_id> -d      # Scan all tables
kai table search <connection_id> "pattern" # Search tables/columns
kai table context <connection_id>          # Display database context

Query and analysis:

kai query run "<question>" --db <alias>    # One-shot analysis
kai query interactive --db <alias>         # Interactive session
kai query resume <session_id> "<prompt>" --db <alias>  # Resume session

Session management:

kai session list [--db <alias>]            # List sessions
kai session show <session_id>              # Show session details
kai session export <session_id> -f markdown -o chat.md  # Export session
kai session delete <session_id> [-f]       # Delete session

Dashboard management:

kai dashboard create "Sales overview" --db <alias>      # Create from NL
kai dashboard list --db <alias>                         # List dashboards
kai dashboard execute <dashboard_id> --save             # Run all widgets
kai dashboard render <dashboard_id> -f html -o report.html  # Render to HTML
kai dashboard refine <dashboard_id> "Add revenue chart" # Refine with NL

Knowledge management:

# Business glossary (metric definitions)
kai knowledge glossary add <conn_id> -m "Revenue" -s "SELECT SUM(amount) FROM orders"
kai knowledge glossary list <conn_id>

# Business instructions (SQL generation rules)
kai knowledge instruction add <conn_id> -c "General" -r "Exclude test accounts"
kai knowledge instruction list <conn_id>

# Skills (reusable analysis patterns)
kai knowledge skill discover <conn_id> --path ./skills
kai knowledge skill list <conn_id>

# Long-term memory
kai knowledge memory list <conn_id>
kai knowledge memory search "date format" -d <conn_id>
kai knowledge memory add <conn_id> user_preferences date_format "Use YYYY-MM-DD"

MDL (semantic layer):

kai mdl list [--db <alias>]                # List MDL manifests
kai mdl show <manifest_id> [--summary]     # Show manifest details
kai mdl show <manifest_id> -f json         # Export as JSON

Configuration:

kai config show [--json]                   # Show current settings
kai config check                           # Check environment/API keys
kai config version                         # Show version info

Help:

kai --help                                 # Show all command groups
kai <group> --help                         # Group-specific help
kai <group> <command> --help               # Command-specific help

Common Workflows

Setup workflow (connection, scan, query):

uv run kai connection create "postgresql://user:pass@host:5432/db" -a mydb
uv run kai table scan-all mydb -d
uv run kai query run "Show top customers" --db mydb

Knowledge workflow (teach KAI your business context):

uv run kai knowledge glossary add mydb -m "MRR" -s "SELECT SUM(amount) FROM subscriptions WHERE status='active'"
uv run kai knowledge instruction add mydb -c "Revenue" -r "Always filter by active subscriptions"
uv run kai knowledge skill discover mydb --path ./skills
uv run kai query run "What's our MRR?" --db mydb  # Now uses business context

Dashboard workflow (create, execute, export):

uv run kai dashboard create "Sales performance dashboard" --db mydb --theme ocean
uv run kai dashboard execute <dashboard_id> --save
uv run kai dashboard render <dashboard_id> -f html -o dashboard.html

Advanced CLI Features

Session management:

# Resume a previous conversation
uv run kai query resume <session_id> "Break it down by region" --db sales

# Export session to markdown
uv run kai session export <session_id> -f markdown -o conversation.md

Search and exploration:

# Search tables and columns by pattern
uv run kai table search mydb "revenue"
uv run kai table search mydb "*_id" -i columns

# Display full database context
uv run kai table context mydb -s -d -f markdown -o context.md

Memory management:

# Store preferences the AI remembers across sessions
uv run kai knowledge memory add mydb user_preferences date_format "Use YYYY-MM-DD"
uv run kai knowledge memory search "preferences" -d mydb

Environment Configuration

Required Variables

Variable	Description	Example
`CHAT_FAMILY`	LLM provider	`openai`, `google`, `ollama`
`CHAT_MODEL`	Model name	`gpt-4o-mini`, `gemini-2.0-flash`
`OPENAI_API_KEY`	OpenAI API key	`sk-...`
`ENCRYPT_KEY`	Fernet encryption key	Generate with command above
`TYPESENSE_HOST`	Typesense server host	`localhost` (dev), `typesense` (Docker)

Optional Variables

Variable	Description	Default
`MEMORY_BACKEND`	Memory backend	`typesense`
`MCP_ENABLED`	Enable Model Context Protocol	`false`
`AGENT_LANGUAGE`	Agent language	`en`
`AGENT_MAX_ITERATIONS`	Max agent iterations	`20`
`DH_ENGINE_TIMEOUT`	Engine timeout (seconds)	`150`
`SQL_EXECUTION_TIMEOUT`	SQL timeout (seconds)	`60`
`UPPER_LIMIT_QUERY_RETURN_ROWS`	Max query rows	`50`

See .env.example for a complete configuration template.

Documentation

API Documentation - Complete REST API reference
Architecture Guide - System design and patterns
Getting Started - Detailed setup guide
Troubleshooting - Common issues and solutions
Deployment Guide - Production deployment
Tutorials - Step-by-step guides

Contributing

We welcome contributions! See our Contributing Guide for details on:

Development workflow
Code style guidelines
Testing requirements
Pull request process

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/your-username/kai.git
cd kai

# Create a feature branch
git checkout -b feature/amazing-feature

# Install dependencies
uv sync

# Make your changes and test
uv run pytest

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Open a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Star History

If you find KAI useful, please consider giving it a star on GitHub!

Acknowledgments

Built with:

FastAPI - Modern Python web framework
LangGraph - Agent orchestration
LangChain - LLM framework
Typesense - Vector search engine

Made with love by MTA

Report Bug • Request Feature • Join Discussion

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

KAI

Knowledge Agent for Intelligence Query

Table of Contents

Overview

Key Features

Natural Language Querying

Advanced Analytics

Dashboard Creation

Long-term Memory

Multi-LLM Support

Production-Ready

Quickstart

Prerequisites

Setup

Running with Docker

Stopping Services

Next Steps

Web UI

Features

Quick Start

Using the Web UI

Creating Dashboards Tutorial

Development Setup

Prerequisites

Installation

LangGraph Development

Architecture

Key Components

Testing

CLI Usage

Quick CLI Tutorial

Command Reference

Common Workflows

Advanced CLI Features

Environment Configuration

Required Variables

Optional Variables

Documentation

Contributing

Quick Start for Contributors

License

Star History

Acknowledgments