Your documents. Searchable in minutes. No infrastructure needed.
Search your local documents with RAG instantly
Quick Start (3 min) • API Docs • Roadmap • Contributing
|
From zero to production in under 5 minutes. No complex infrastructure. |
100% self-hosted. Your data never leaves your servers. |
Leverages Gemini's generous free tier. Process thousands of docs free. |
| Feature | FLAMEHAVEN | Pinecone | Weaviate | Custom RAG |
|---|---|---|---|---|
| Setup Time | < 5 min | ~20 min | ~30 min | Days |
| Self-Hosted | [+] Yes | [-] No | [+] Yes | [+] Yes |
| Free Tier | Generous | Limited | Yes | N/A |
| Code Complexity | Low | Medium | High | Very High |
| Maintenance | Minimal | None | Medium | High |
| Best For | Quick POCs, SMBs | Enterprise scale | ML teams | Full control |
| Feature | Description |
|---|---|
| [*] Multi-Format Support | PDF, DOCX, TXT, MD files up to 50MB |
| [*] Semantic Search | Natural language queries with AI-powered answers |
| [*] Source Attribution | Every answer links back to source documents |
| [*] Store Management | Organize documents into separate collections |
| [*] Dual Interface | Python SDK + REST API with Swagger UI |
| [*] Docker Ready | One-command deployment with persistence |
| [*] Enterprise Auth | v1.2.0: API keys, audit logging, rate limiting |
| [*] Batch Processing | Process 1-100 queries per request |
âś— You have PDF, Word, and text documents scattered across your local drive
âś— You want to search them intelligently, not keyword-by-keyword
âś— You don't want to upload your data to external services (Pinecone, Cloudflare, etc.)
âś— You need production-ready security without complex setup
âś— You want zero infrastructure costs for prototype phase
âś“ Local RAG search engine in 5 minutes
âś“ 100% self-hosted (your data stays yours)
âś“ Single Docker command deployment
âś“ Free tier Google Gemini (up to 1500 queries/month)
âś“ v1.2.0: Enterprise-grade authentication & multi-user support
âś“ Batch search API for 1-100 queries per request
âś“ Optional Redis for distributed caching across workers
# Start with one command
docker run -d \
-e GEMINI_API_KEY="your_gemini_api_key" \
-p 8000:8000 \
-v $(pwd)/data:/app/data \
flamehaven-filesearch:1.2.0
# Available at http://localhost:8000 in 3 seconds# Step 1: Generate API key (v1.2.0 requirement)
curl -X POST http://localhost:8000/api/admin/keys \
-H "X-Admin-Key: your_admin_key" \
-H "Content-Type: application/json" \
-d '{
"name": "My First Key",
"permissions": ["upload", "search"]
}'
# Response: {"key_id": "...", "plain_key": "sk_live_abc123..."}
# SAVE this key - it won't be shown again!
# Step 2: Upload a document
curl -X POST http://localhost:8000/api/upload/single \
-H "Authorization: Bearer sk_live_abc123..." \
-F "[email protected]" \
-F "store=documents"
# Step 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 points in this document?",
"store": "documents"
}'
# Response:
# {
# "answer": "The main points are...",
# "sources": [
# {
# "file": "sample.pdf",
# "page": 3,
# "excerpt": "..."
# }
# ]
# }from flamehaven_filesearch import FlamehavenFileSearch, FileSearchConfig
# Configuration
config = FileSearchConfig(
google_api_key="your_gemini_api_key",
environment="offline" # or "remote" for online
)
# Initialize
searcher = FlamehavenFileSearch(config)
# Create document store
searcher.create_store("my_documents")
# Upload files
searcher.upload_file("path/to/document.pdf", "my_documents")
searcher.upload_file("path/to/document.docx", "my_documents")
# Search with RAG
result = searcher.search(
"Summarize the key findings",
store="my_documents"
)
print(f"Answer: {result['answer']}")
print(f"Sources: {result['sources']}")# Core functionality
pip install flamehaven-filesearch
# With API server
pip install flamehaven-filesearch[api]
# With Redis support
pip install flamehaven-filesearch[api,redis]
# Everything (for development)
pip install flamehaven-filesearch[all]# Build image
docker build -t flamehaven-filesearch:1.2.0 .
# Run standalone
docker run \
-e GEMINI_API_KEY="your_key" \
-e FLAMEHAVEN_ADMIN_KEY="your_admin_key" \
-p 8000:8000 \
flamehaven-filesearch:1.2.0
# With Docker Compose (includes Redis)
docker-compose up -dSee the Kubernetes deployment example above for complete manifests with StatefulSets, ConfigMaps, and Secrets.
# Google Gemini API key (get free tier at ai.google.dev)
export GEMINI_API_KEY="your_api_key"
# Admin key for creating API keys in v1.2.0
export FLAMEHAVEN_ADMIN_KEY="your_secure_admin_password"# Server settings
export HOST="0.0.0.0" # Default: 127.0.0.1
export PORT="8000" # Default: 8000
export ENVIRONMENT="production" # Default: development
# Database location
export FLAMEHAVEN_API_KEYS_DB="/path/to/api_keys.db"
# Redis (for multi-worker deployments)
export REDIS_HOST="localhost" # Default: localhost
export REDIS_PORT="6379" # Default: 6379
export REDIS_PASSWORD="password" # Optional
# API limits
export MAX_FILE_SIZE_MB="50" # Default: 50curl -X POST http://localhost:8000/api/admin/keys \
-H "X-Admin-Key: $FLAMEHAVEN_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production API Key",
"permissions": ["upload", "search", "stores", "delete"],
"rate_limit_per_minute": 100
}'curl http://localhost:8000/api/admin/keys \
-H "Authorization: Bearer sk_live_your_key..."curl -X DELETE http://localhost:8000/api/admin/keys/{key_id} \
-H "Authorization: Bearer sk_live_your_key..."curl "http://localhost:8000/api/admin/usage?days=7" \
-H "Authorization: Bearer sk_live_your_key..."| Operation | Response Time | Throughput |
|---|---|---|
| Health check | <10ms | - |
| Search (cache hit) | <10ms | >2 searches/sec |
| Search (cache miss) | 500ms - 3s | Depends on Gemini API |
| Batch search (10 queries) | 2-5s | >1 batch/sec |
| File upload | 1-5s | >1 file/sec |
- Memory: ~200MB baseline + 50MB per 1000 cached queries
- CPU: <5% idle, <50% under sustained load
- Disk: 10MB per 100,000 cached queries
- [#] API Key Encryption: SHA256 hashing (plain keys never stored)
- [#] Rate Limiting: Per-API-key customizable limits (default 100/min)
- [#] Permission Control: Fine-grained access (upload, search, stores, delete)
- [#] Audit Logging: Complete request trail with timestamps
- [#] OWASP Headers: Security headers on all responses
- [#] Request Tracking: Unique request IDs for debugging
- [#] Key Expiration: Optional time-limited API keys
- Improved admin authentication (IAM integration)
- Redis UI configuration in dashboard
- Encryption at rest for sensitive data
- Fix deprecated FastAPI
on_eventdecorators
- OAuth2/OIDC integration
- API key rotation
- Billing/metering system
- Advanced analytics dashboard
- Multi-language support
- Enhanced file type support (XLSX, PPTX, RTF)
- Export search results (JSON, CSV, PDF)
- WebSocket streaming support
Looking to contribute? Start with these issues:
-
Add XLSX Support (Difficulty: Medium)
- Extend file upload to handle Excel spreadsheets
- Reference:
flamehaven_filesearch/loaders.py - Estimated time: 2-3 hours
-
Implement Search Result Caching UI (Difficulty: Easy)
- Display cache hit rate in admin dashboard
- Reference:
flamehaven_filesearch/dashboard.py - Estimated time: 1-2 hours
-
Add Batch Search Progress Tracking (Difficulty: Medium)
- Implement WebSocket endpoint for real-time batch progress
- Reference:
flamehaven_filesearch/batch_routes.py - Estimated time: 3-4 hours
-
Create Integration Tests (Difficulty: Easy)
- Write end-to-end tests for common workflows
- Reference:
tests/test_api_integration.py - Estimated time: 2-3 hours
-
Add Dark Mode to Admin Dashboard (Difficulty: Easy)
- Extend dashboard.py with CSS dark theme toggle
- Reference:
flamehaven_filesearch/dashboard.py - Estimated time: 1-2 hours
See CONTRIBUTING.md for complete contribution guidelines.
Solution:
- Verify FLAMEHAVEN_ADMIN_KEY environment variable is set
- Check Authorization header format:
Authorization: Bearer sk_live_your_key - Ensure API key hasn't expired
Solution:
- Verify Redis is running:
redis-cli ping - Check REDIS_HOST and REDIS_PORT environment variables
- Remove Redis if not needed (system falls back to LRU cache)
Solution:
- Configure Redis eviction policy:
maxmemory-policy allkeys-lru - Reduce cache TTL in configuration
- Monitor cache metrics:
curl http://localhost:8000/prometheus | grep cache
Solution:
- Check if caching is working (view
cache_hits_totalmetric) - Verify Gemini API is responsive
- Check network latency to Redis instance
All protected endpoints now require API key authentication.
-
Update dependencies:
pip install -U flamehaven-filesearch[api]
-
Set admin key:
export FLAMEHAVEN_ADMIN_KEY="your_secure_admin_key"
-
Generate first API key:
curl -X POST http://localhost:8000/api/admin/keys \ -H "X-Admin-Key: your_admin_key" \ -H "Content-Type: application/json" \ -d '{"name":"Production","permissions":["upload","search","stores","delete"]}'
-
Update application code:
# Old (v1.1.0) requests.post("http://localhost:8000/api/search", json={"query": "test"}) # New (v1.2.0) api_key = "sk_live_your_key" requests.post( "http://localhost:8000/api/search", json={"query": "test"}, headers={"Authorization": f"Bearer {api_key}"} )
-
Test before production deployment
If issues occur, v1.1.0 remains available. No data loss on downgrade.
- Documentation: CHANGELOG | Release Notes
- Issues & Bugs: GitHub Issues
- Discussions: GitHub Discussions
- Security Issues: [email protected]
[Your Documents]
|
v
[File Upload Endpoint] ---> [File Parser] ---> [Store Manager]
| | |
+---- (REST API) --------+---- (SQLite DB)----+
|
[Search Endpoint] ---> [Semantic Search] ---> [Gemini API]
| |
+--- (Cache) -------+
|
[Prometheus Metrics] <--- [Audit Log]
Recent v1.2.0 benchmark (Docker on M1 Mac):
Health Check: 8ms
Search (cache hit): 9ms
Search (cache miss): 1250ms
Batch Search (10 queries, parallel): 2500ms
Upload (50MB file): 3200ms
FLAMEHAVEN FileSearch is released under the MIT License. See LICENSE file for details.
Built with:
- FastAPI - Modern Python web framework
- Google Gemini API - Semantic understanding
- SQLite - Lightweight database
- Redis (optional) - Distributed caching
Questions? Open an issue or email [email protected]
Last Updated: November 16, 2025 (v1.2.0)