Stop sending your sensitive documents to third-party services. Get enterprise-grade semantic search running locally in minutes, not days.
# One command. Three minutes. Done.
docker run -d -p 8000:8000 -e GEMINI_API_KEY="your_key" flamehaven-filesearch:1.4.1|
Production deployment in 3 minutes |
100% self-hosted |
Free tier: 1,500 queries/month |
- 🔍 Smart Search Modes - Keyword, semantic, and hybrid search with automatic typo correction
- 📄 Multi-Format Support - PDF, DOCX, TXT, MD, and common image formats
- ⚡ Ultra-Fast Vectors - DSP v2.0 algorithm generates embeddings in <1ms without ML frameworks
- 🎯 Source Attribution - Every answer includes links back to source documents
- Usage Tracking & Quotas - Per-API-key request/token tracking with daily/monthly limits
- Admin Usage APIs - Detailed usage stats, quota management, and alert monitoring
- pgvector Maintenance - HNSW reindexing, VACUUM ANALYZE, and index statistics
- pgvector Tuning Guide - Comprehensive production tuning and optimization documentation
- Circuit Breaker - Automatic failure recovery for database connections
- Performance Monitoring - Complete observability with health checks and metrics
- Multimodal Search - Text + image search endpoint (optional)
- HNSW Vector Index - High-performance similarity search with pgvector
- OAuth2/OIDC Support - JWT validation alongside API keys
- PostgreSQL Backend - Enterprise-grade persistence and vector store
- Vision Processing - Image metadata extraction with size limits and timeouts
- 🔐 API Key Authentication - Fine-grained permission system
- ⚡ Rate Limiting - Configurable per-user quotas
- 📊 Audit Logging - Complete request history
- 📦 Batch Processing - Process 1-100 queries per request
- 📈 Admin Dashboard - Real-time metrics and management
The fastest path to production:
docker run -d \
-p 8000:8000 \
-e GEMINI_API_KEY="your_gemini_api_key" \
-e FLAMEHAVEN_ADMIN_KEY="secure_admin_password" \
-v $(pwd)/data:/app/data \
flamehaven-filesearch:1.4.1✅ Server running at http://localhost:8000
Perfect for integrating into existing applications:
from flamehaven_filesearch import FlamehavenFileSearch, FileSearchConfig
# Initialize
config = FileSearchConfig(google_api_key="your_gemini_key")
fs = FlamehavenFileSearch(config)
# Upload and search
fs.upload_file("company_handbook.pdf", store="docs")
result = fs.search("What is our remote work policy?", store="docs")
print(result['answer'])
# Output: "Employees can work remotely up to 3 days per week..."For language-agnostic integration:
# 1. Generate API key
curl -X POST http://localhost:8000/api/admin/keys \
-H "X-Admin-Key: your_admin_key" \
-d '{"name":"production","permissions":["upload","search"]}'
# 2. Upload document
curl -X POST http://localhost:8000/api/upload/single \
-H "Authorization: Bearer sk_live_abc123..." \
-F "[email protected]" \
-F "store=my_docs"
# 3. Search
curl -X POST http://localhost:8000/api/search \
-H "Authorization: Bearer sk_live_abc123..." \
-H "Content-Type: application/json" \
-d
'{
"query": "What are the main findings?",
"store": "my_docs",
"search_mode": "hybrid"
}'# Core package
pip install flamehaven-filesearch
# With API server
pip install flamehaven-filesearch[api]
# With HNSW vector index
pip install flamehaven-filesearch[vector]
# With PostgreSQL backend (metadata + vector store)
pip install flamehaven-filesearch[postgres]
# With vision delegate support
pip install flamehaven-filesearch[vision]
# Development setup
pip install flamehaven-filesearch[all]
# Build from source
git clone https://github.com/flamehaven01/Flamehaven-Filesearch.git
cd Flamehaven-Filesearch
docker build -t flamehaven-filesearch:1.4.1 .export GEMINI_API_KEY="your_google_gemini_api_key"
export FLAMEHAVEN_ADMIN_KEY="your_secure_admin_password"export HOST="0.0.0.0" # Bind address
export PORT="8000" # Server port
export REDIS_HOST="localhost" # Distributed caching
export REDIS_PORT="6379" # Redis portCreate a config.yaml for fine-tuned control:
vector_store:
quantization: int8
compression: gravitas_pack
search:
default_mode: hybrid
typo_correction: true
max_results: 10
security:
rate_limit: 100 # requests per minute
max_file_size: 52428800 # 50MB| Metric | Value | Notes |
|---|---|---|
| Vector Generation | <1ms |
DSP v2.0, zero ML dependencies |
| Memory Footprint | 75% reduced |
Int8 quantization vs float32 |
| Metadata Size | 90% smaller |
Gravitas-Pack compression |
| Test Suite | 0.33s |
19/19 tests passing |
| Cold Start | 3 seconds |
Docker container ready |
Environment: Docker on Apple M1 Mac, 16GB RAM
Document Set: 500 PDFs, ~2GB total
Health Check: 8ms
Search (cache hit): 9ms
Search (cache miss): 1,250ms (includes Gemini API call)
Batch Search (10): 2,500ms (parallel processing)
Upload (50MB file): 3,200ms (with indexing)
┌─────────────────┐
│ Your Documents │
└────────┬────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ REST API Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ Upload │ │ Search │ │ Admin │ │
│ │ Endpoint │ │ Endpoint │ │ Dashboard │ │
│ └──────┬───────┘ └──────┬───────┘ └─────┬─────┘ │
└─────────┼──────────────────┼─────────────────┼──────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────┐
│ File Parser │ │ Semantic Search │ │ Metrics │
│ (PDF/DOCX/TXT) │ │ DSP v2.0 │ │ Logger │
└────────┬─────────┘ └────────┬─────────┘ └──────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Store Manager │ │ Gemini API │
│ (SQLite + Vec) │ │ (Reasoning) │
└────────┬─────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ Redis Cache │
│ (Optional) │
└──────────────────┘
FLAMEHAVEN takes security seriously:
- ✅ API Key Hashing - SHA256 with salt
- ✅ Rate Limiting - Per-key quotas (default: 100/min)
- ✅ Permission System - Granular access control
- ✅ Audit Logging - Complete request history
- ✅ OWASP Headers - Security headers enabled by default
- ✅ Input Validation - Strict file type and size checks
# Use strong admin keys
export FLAMEHAVEN_ADMIN_KEY=$(openssl rand -base64 32)
# Enable HTTPS in production
# (use nginx/traefik as reverse proxy)
# Rotate API keys regularly
curl -X DELETE http://localhost:8000/api/admin/keys/old_key_id \
-H "X-Admin-Key: $FLAMEHAVEN_ADMIN_KEY"Full roadmap lives in ROADMAP.md. Summary below:
- Multimodal search (image + text)
- HNSW vector indexing for faster search
- OAuth2/OIDC integration
- PostgreSQL backend option (metadata + vector store)
- Usage-budget controls and reporting
- pgvector tuning and reliability hardening
- Multi-language support (15+ languages)
- XLSX, PPTX, RTF format support
- WebSocket streaming for real-time results
- Kubernetes Helm charts
See ROADMAP.md for backlog curation and request intake.
❌ 401 Unauthorized Error
Problem: API returns 401 when making requests.
Solutions:
- Verify
FLAMEHAVEN_ADMIN_KEYenvironment variable is set - Check
Authorization: Bearer sk_live_...header format - Ensure API key hasn't expired (check admin dashboard)
# Debug: Check if admin key is set
echo $FLAMEHAVEN_ADMIN_KEY
# Regenerate API key
curl -X POST http://localhost:8000/api/admin/keys \
-H "X-Admin-Key: $FLAMEHAVEN_ADMIN_KEY" \
-d '{"name":"debug","permissions":["search"]}'🐌 Slow Search Performance
Problem: Searches taking >5 seconds.
Solutions:
- Check cache hit rate:
FLAMEHAVEN_METRICS_ENABLED=1 curl http://localhost:8000/metrics - Enable Redis for distributed caching
- Verify Gemini API latency (should be <1.5s)
# Enable Redis caching
docker run -d --name redis redis:7-alpine
export REDIS_HOST=localhost💾 High Memory Usage
Problem: Container using >2GB RAM.
Solutions:
- Enable Redis with LRU eviction policy
- Reduce max file size in config
- Monitor with Prometheus endpoint
# Configure Redis memory limit
docker run -d \
-p 6379:6379 \
redis:7-alpine \
--maxmemory 512mb \
--maxmemory-policy allkeys-lruMore solutions in our Wiki Troubleshooting Guide.
Use the links below to jump to the most relevant guide.
| Topic | Description |
|---|---|
| Troubleshooting | Step-by-step debugging playbook |
| Configuration Reference | Full list of environment variables and config fields |
| Production Deployment | Docker, systemd, reverse proxy, scaling tips |
| API Reference | REST endpoints, payloads, rate limits |
| Architecture | How the FastAPI, cache, metrics, and validation layers fit together |
| Benchmarks | Performance measurements and methodology |
These Markdown files live inside the repository so they stay versioned alongside the code. Feel free to contribute improvements via pull requests.
- Interactive API Docs - OpenAPI/Swagger interface (when server is running)
- CHANGELOG - Version history and breaking changes
- CONTRIBUTING - How to contribute code
- Examples - Sample integrations and use cases
We love contributions! FLAMEHAVEN is better because of developers like you.
- 🟢 [Easy] Add dark mode to admin dashboard (1-2 hours)
- 🟡 [Medium] Implement XLSX file support (2-3 hours)
- 🔴 [Advanced] Add HNSW vector indexing (4-6 hours)
See CONTRIBUTING.md for development setup and guidelines.
- 💬 Discussions: GitHub Discussions
- 🐛 Bug Reports: GitHub Issues
- 🔒 Security: [email protected]
- 📧 General: [email protected]
Distributed under the MIT License. See LICENSE for more information.
Built with amazing open source tools:
- FastAPI - Modern Python web framework
- Google Gemini - Semantic understanding and reasoning
- SQLite - Lightweight, embedded database
- Redis - In-memory caching (optional)
⭐ Star us on GitHub • 📖 Read the Docs • 🚀 Deploy Now
Built with 🔥 by the Flamehaven Core Team
Last updated: December 28, 2025 • Version 1.4.1
