Skip to content

README.md

Latest commit

 

History

History
498 lines (390 loc) · 21.3 KB

README.md

File metadata and controls

498 lines (390 loc) · 21.3 KB

ThemisDB Documentation Index

📝 Note on Documentation Language
This is a translation of the ThemisDB documentation. The authoritative and most up-to-date documentation is maintained in German (docs/de/).
Translations may lag behind the German version. For the latest information, please refer to the German documentation.

Last Updated: January 5, 2026
Version: 1.4.0-alpha (Advanced LLM Features)
Type: Documentation Index
Language: English (Translation)

🚀 NEW in v1.4.0-alpha: Advanced LLM Features ✅

AI directly in the database with advanced capabilities - no external API costs!

Advanced LLM Features (v1.4.0-alpha)

  • 📝 Grammar-Constrained Generation - EBNF/GBNF support for guaranteed valid outputs (95-99% reliability vs 60-70%)
    • Built-in grammars: JSON, XML, CSV, ReAct Agent
    • Thread-safe grammar cache with LRU eviction
    • Zero post-processing required
  • 🔭 RoPE Scaling - Extended context window from 4K → 32K tokens (8x increase)
    • Linear, NTK-aware, YaRN scaling methods
    • Process entire research papers and codebases
  • 🖼️ Vision Support - Multi-modal LLMs with CLIP-based image encoding
    • LLaVA integration for image analysis
    • Single and multiple image support
  • ⚡ Flash Attention - CUDA kernels for 15-25% speedup, 30% memory reduction
    • Optimized attention mechanism
    • Backward pass for training support
  • 🎯 Speculative Decoding - 2-3x faster inference with draft+target models
  • 🔄 Continuous Batching - 2x+ throughput with dynamic request batching

Documentation (v1.4.0-alpha)

🚀 LLM Integration (Optional Feature) - v1.3.0 Base

Important: LLM Integration is an optional feature in v1.3.0+:

  • Requires build flag: -DTHEMIS_ENABLE_LLM=ON
  • Requires external dependency: llama.cpp (clone separately)
  • See Build Guide for setup instructions

ThemisDB can be extended as the first multi-model database with an embedded LLM engine:

Core Features (v1.3.0)

  • 🧠 Embedded llama.cpp - SLMs/LLMs (1B-70B parameters) directly on GPU ✅
  • ⚡ GPU Acceleration - Significant speedup with NVIDIA CUDA support ✅
  • 💾 PagedAttention - Optimized memory management ✅
  • 🎯 Continuous Batching - Multiple concurrent requests ✅
  • 🔧 Kernel Fusion - CUDA kernels for additional speedup ✅
  • 📊 Production Monitoring - Grafana/Prometheus integration ✅
  • 🔌 Plugin Architecture - Extensible LLM backend system ✅
  • 🌐 RPC Framework - Inter-shard communication for distributed LLM ops ✅
  • 🖼️ Image Analysis Plugins - Multi-backend AI (llama.cpp Vision, ONNX CLIP, OpenCV DNN) ✅

Network Protocol Enhancements (v1.3.0)

  • 🌐 HTTP/2 with Server Push - CDC/Changefeed with proactive event delivery (~0ms latency) ✅
  • 🔌 WebSocket Support - CDC streaming with bidirectional real-time communication ✅
  • 📡 MQTT Broker - WebSocket transport, rate limiting, monitoring metrics ✅
  • 🚀 HTTP/3 Base - QUIC-based implementation (ngtcp2 + nghttp3) 🚧
  • 🐘 PostgreSQL Wire Protocol - SQL-to-Cypher translation for BI tool compatibility ✅
  • 🤖 MCP Server - Model Context Protocol with cross-platform support ✅

Performance Metrics (with GPU)

  • Significant speedup with GPU vs CPU-only
  • Memory savings with PagedAttention
  • Additional optimization with kernel fusion
  • Comprehensive test coverage with unit tests

GPU Tier Recommendations

GPU Tier Hardware Model Use Case Cost/1M Tokens vs. GPT-4
Entry RTX 4060 Ti (16GB) Phi-3-Mini (3.8B) FAQ, simple RAG €0.02 1500x cheaper
Mid-Range RTX 4090 (24GB) Mistral-7B Production RAG €0.05 600x cheaper
High-End A100 (80GB) Llama-3-70B Enterprise Scale €0.15 200x cheaper

Break-Even vs. Hyperscaler: 2-7 months depending on hardware tier

Documentation (v1.3.0)

📁 Documentation Structure (Newly Organized)

The documentation has been restructured for better clarity:

Root Documents (essentials only):

  • README.md - Main documentation
  • index.md - Documentation index
  • glossary.md - Terminology

Organized Folders:

  • aql/ - AQL Grammar (EBNF) ⭐ v1.3.0
  • build/ - Build system documentation (BUILD-SYSTEM.md, BUILDGUIDE.md, etc.)
  • development/ - Development documentation (IMPLEMENTATION-.md, CODE_REVIEW-.md)
  • guides/ - User and developer guides (RAILWAY_COMPLETE_GUIDE.md, etc.)
  • architecture/ - Architecture documentation (ARCHITECTURE_OVERVIEW.md, etc.)
  • stakeholder/ - Stakeholder documentation
  • releases/ - Release notes (v1.3.0.md, v1.2.0.md, v1.1.0.md, etc.)
  • llm/ - LLM & AI Integration ⭐ v1.3.0 RELEASED
  • plugins/ - RPC Framework ⭐ v1.3.0
  • archive/ - Old/historical documentation

🔮 COMING SOON - v1.1.0 Optimization Release (Q1 2026):

Focus: Better utilize existing libraries + vLLM co-location
Highlights:

  • ✅ RocksDB TTL, Incremental Backup, Stats (no new lib!)
  • ✅ TBB Parallel Sort, Concurrent Containers (no new lib!)
  • ✅ Arrow Parquet Export (no new lib!)
  • ✅ CUDA as core (when GPU available, NOT Enterprise!)
  • ✅ 🆕 ThemisDB + vLLM Synergy (optimized CPU/GPU/RAM coordination)
  • ✅ mimalloc (only new dependency, 20-40% memory boost)

Engineering: 9-11 weeks | Impact: 3-10x performance
Details: v1.1.0 Variant Strategy

🚀 PLANNED - v1.2.0 Enterprise Features (Q2 2026):

Focus: vLLM AI Support (LoRA), Geo-Spatial (PostGIS), IoT/Timescale
Highlights:

  • ✅ LoRA Manager - Multi-tenant LoRA serving (HuggingFace PEFT)
  • ✅ FAISS Advanced - IVF+PQ vector search (already integrated, expand!)
  • ✅ GEOS + PROJ - PostGIS compatibility (topology + geography)
  • ✅ Hypertables - TimescaleDB-compatible via RocksDB CF (code only!)
  • ✅ cuSpatial - GPU geo ops (optional, uses Arrow + CUDA)

Engineering: 12-16 weeks | Impact: PostGIS + LoRA + TimescaleDB compatibility
Details: Enterprise Features Strategy

📚 Main Documentation

Overview Documents

🎯 By Target Audience

For Stakeholders & Management

For Developers

For DevOps & Operations

For Security & Compliance

🏗️ By Architecture Layer

Query & Analytics Layer

Storage & Index Layer

Distribution & Scaling Layer

Acceleration Layer

  • GPU Acceleration Plan - 10 GPU backends (173K LOC)
    • CUDA, Vulkan, FAISS, DirectX, HIP, OpenCL, OneAPI, ZLUDA

Content & Data Processing

Server & API Layer

Security & Governance Layer

🚀 Quick Start Guides

Installation & Deployment

Getting Started

📖 Reference Documentation

Client SDKs

Data Import/Export

Plugin Development

🔧 Administration & Operations

Admin Tools

Operations Guides

Performance & Monitoring

📊 Reports & Status

Development Reports

Status Reports

Roadmap & Planning

📦 Integration & Ingestion

Data Ingestion

Enterprise Integration

🔍 Source Code Documentation

Module Documentation (src/)

All 26 modules with detailed documentation in src/:

  • Acceleration - GPU/CPU backends (173K LOC)
  • Analytics - OLAP, CEP (57K LOC)
  • API - GraphQL, geo hooks
  • Auth - JWT validation
  • Cache - Semantic cache
  • CDC - Change data capture
  • Content - 15 file processors (256K LOC)
  • Exporters - Data export
  • Geo - Spatial operations
  • Governance - Policy engine
  • Importers - Data import
  • Index - Vector, graph, secondary (400K LOC)
  • LLM - LLM integration
  • Network - Wire protocol
  • Observability - Metrics, tracing
  • Plugins - Plugin system
  • Query - AQL engine (240K LOC)
  • Replication - Leader-follower, multi-master (12K LOC)
  • Security - Encryption, RBAC (187K LOC)
  • Server - HTTP, API handlers (164K LOC)
  • Sharding - VCC-URN, gossip (300K LOC)
  • Storage - RocksDB, MVCC (76K LOC)
  • Timeseries - Gorilla compression (39K LOC)
  • Transaction - MVCC, SAGA (42K LOC)
  • Updates - Schema migration
  • Utils - Utilities (120K LOC)

🎓 Additional Resources

External Links

Benchmarking & Performance

Release Documentation

📝 Documentation Standards

Format & Structure

  • Format: Markdown (.md)
  • Encoding: UTF-8
  • Line Endings: LF (Unix-style)
  • Code Blocks: Always specify language
  • Links: Use relative paths

Contributing

  1. Follow structure - Place docs in appropriate subdirectory
  2. Link properly - Use relative links to other documents
  3. Update README - Update relevant README.md files
  4. Markdown style - Follow Style Guide
  5. Keep current - Update docs when features change

Build Process

# Install dependencies
pip install -r requirements-docs.txt

# Build documentation
.\build-docs.ps1

# Test locally
mkdocs serve

Documentation is automatically deployed to GitHub Pages on merge to main.

📞 Support & Community

📊 Documentation Statistics

Metric Value
Documentation Files 456+
Documentation Folders 71
Source Code LOC 90,829
Source Files 191 (.cpp)
Header Files 132 (.h)
Modules 26 directories
Logical Components 16

Version: 1.3.0
Last Updated: December 20, 2025
License: See LICENSE