AI Provider Integrations
Relevant source files
The following files were used as context for generating this wiki page:
AI Provider Integrations in KamehaDB enable a schema-aware assistant that assists users in generating SQL, MongoDB aggregation pipelines, and Redis commands. The system supports multiple providers, including OpenAI, Ollama (local and cloud), and 9Router, allowing users to choose between local-first privacy or high-performance cloud models.
The architecture relies on a "Sidecar" (Hono server) to handle communication with AI APIs, schema context extraction, and vector-based retrieval via Qdrant for large schemas. The frontend provides a dedicated chat interface and a settings management page to configure provider credentials and active models.
Sources: README.md:10-15, apps/sidecar/src/routes/ai.ts:160-180, apps/desktop/src/components/api-settings-page.tsx:14-45
Architecture and Data Flow
The AI integration follows a request-response cycle where the desktop application sends user prompts along with connection metadata to the Sidecar. The Sidecar enriches the request with database schema context before forwarding it to the configured AI provider.
AI Communication Flow
The following diagram illustrates how a user request is processed, enriched with schema data, and streamed back to the UI.
The system utilizes Server-Sent Events (SSE) for real-time response rendering, allowing users to see the assistant's output as it is generated.
Sources: apps/sidecar/src/routes/ai.ts:153-270, apps/desktop/src/lib/api.ts:175-200, apps/sidecar/src/db/metadata-store.ts:470-495
Supported AI Providers
KamehaDB implements a flexible provider system where each provider shares a common configuration schema while maintaining specific endpoint requirements.
| Provider | Description | Configuration Requirements |
|---|---|---|
| OpenAI | Direct access to GPT models | API Key, Model |
| Ollama Local | Local execution via Ollama daemon | Model (Base URL defaults to localhost) |
| Ollama Cloud | Remote Ollama-compatible endpoints | Base URL, API Key, Model |
| 9Router | OpenAI-compatible router | Base URL, API Key, Model |
Sources: apps/desktop/src/components/api-settings-page.tsx:14-45, packages/shared/src/index.ts:413-421
Configuration Logic
The Sidecar validates provider configurations before attempting to initiate a chat. Specifically, it checks for enabled status, model presence, and required credentials based on the provider type.
// Validation logic snippet for AI settings
function getProviderStatus(provider: AIProvider, config: AIProviderConfig) {
if (!config.enabled) return 'Not configured';
if (!config.model.trim()) return 'Needs model';
if (providerNeedsApiKey(provider) && !config.apiKey?.trim()) return 'Missing API key';
if (providerNeedsBaseUrl(provider) && !config.baseUrl?.trim()) return 'Needs base URL';
return 'Configured';
}
Sources: apps/desktop/src/components/api-settings-page.tsx:90-96
Schema Context Injection
A critical feature of the integration is "Schema-Aware Context." The Sidecar dynamically builds a system prompt containing the DDL or collection structure of the active database.
SQL Context Generation
For relational databases (PostgreSQL, MySQL, SQLite), the Sidecar attempts to retrieve relevant table definitions. If Qdrant is configured, it uses vector similarity to find only the most relevant tables for the user's specific query; otherwise, it falls back to a full schema context.
Sources: apps/sidecar/src/routes/ai.ts:205-235
MongoDB Context Generation
For MongoDB, the system samples documents from collections to identify field types and structures, providing the LLM with a representation of the BSON data.
Sources: apps/sidecar/src/routes/ai.ts:28-85
Database Assistant Rules
The system prompt enforces strict rules to ensure the assistant behaves as a technical tool:
- Conciseness: No unnecessary commentary outside of code blocks.
- Code Fencing: SQL must use
sql, MongoDBjavascript, and Redisredis. - Read-Only focus: Default to read-only queries, warning users if they request destructive actions.
Sources: apps/sidecar/src/routes/ai.ts:98-120
Management and Persistence
The metadata-store.ts handles the persistence of AI settings and chat history within a local SQLite database.
Data Models
Chat history is scoped to specific connection profiles, ensuring that context from a PostgreSQL connection does not interfere with a Redis or MongoDB connection.
Sources: apps/sidecar/src/db/metadata-store.ts:130-165, apps/sidecar/src/db/metadata-store.ts:468-510
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/ai/chat | POST | Main chat endpoint (SSE stream) |
/ai/settings | GET/POST | Retrieve or update AI configurations |
/ai/chat-history/:id | GET | Fetch historical messages for a connection |
/ai/embed | POST | Generate vector embeddings for text |
/ai/clear-schema-cache/:id | POST | Force refresh of the database schema context |
Sources: apps/sidecar/src/routes/ai.ts:153-350, apps/desktop/src/lib/api.ts:50-125
Conclusion
The AI Provider Integration system provides a robust bridge between local database metadata and LLM intelligence. By abstracting multiple providers and automating schema context injection, KamehaDB enables developers to interact with complex data structures using natural language while maintaining local-first data privacy.
Sources: README.md:10-20, apps/sidecar/src/routes/ai.ts:98-120