v1.4.1 - Usage Tracking & pgvector Hardening

Production-hardening release with comprehensive usage tracking, quota management, and pgvector reliability enhancements.

Full Changelog: CHANGELOG.md

Key Features

Usage Tracking & Quota Management

• Per-API-key request/token tracking with SQLite backend
• Daily and monthly quota enforcement
• Alert system with configurable thresholds
• Automatic cleanup of old records

Admin APIs

• Detailed usage statistics
• Quota status and configuration
• Usage alerts monitoring

pgvector Maintenance

• HNSW index rebuilding
• VACUUM ANALYZE operations
• Index statistics export
• Comprehensive tuning guide

Installation

pip install flamehaven-filesearch==1.4.1

Upgrade

pip install --upgrade flamehaven-filesearch

Documentation

• CHANGELOG.md
• pgvector Tuning Guide
• Implementation Summary

v1.3.1

Added - Phase 2 & 3: Semantic Search + Gravitas-Pack Integration

• Gravitas Vectorizer v2.0: Custom Deterministic Semantic Projection (DSP) algorithm
  • Zero ML dependencies (removed sentence-transformers 500MB+)
  • Instant initialization (<1ms vs 2min+ before)
  • Hybrid feature extraction: word tokens (2.0x weight) + char n-grams (3-5)
  • Signed feature hashing for collision mitigation
  • 384-dimensional unit-normalized vectors
  • LRU caching with 16.7%+ hit rate
• GravitasPacker: Symbolic compression integrated into cache layer
  • 90%+ compression ratio on metadata
  • Deterministic lore scroll generation
  • Instant decompression (<1ms)
• Vector Quantizer: int8 quantization for 75% memory reduction
  • Asymmetric quantization (per-vector min/max calibration)
  • 30%+ speedup on cosine similarity calculations
  • Backward compatible with float32 vectors
• Search Modes: keyword, semantic, hybrid via search_mode parameter
• API Schema Enhancement: Added refined_query, corrections, search_mode, search_intent, semantic_results to SearchResponse
• Chronos-Grid Integration: Vector storage and similarity search
• Intent-Refiner: Typo correction and query optimization
• unittest Migration: Replaced pytest with Python stdlib unittest
  • 19/19 tests passing in 0.33s
  • Zero timeout issues
  • Master test suite: tests/run_all_tests.py
• Performance Benchmarks: Dedicated benchmark suite for DSP v2.0
• Documentation: README, CHANGELOG, TOMB files updated

Performance

• Vector generation: <1ms per text
• Memory: 1536 bytes → 384 bytes per vector (75% reduction)
• Metadata compression: 90%+ ratio
• Search speed: 30% faster on quantized vectors
• Similar text similarity: 0.787 (78.7%)
• Differentiation ratio: 2.36x
• Cache efficiency: 16.7%+ hit rate
• Search 1000 vectors: <100ms
• Precision loss: <0.1% (negligible for file search)

Changed

• EmbeddingGenerator completely rewritten with DSP algorithm
• cache.py: Integrated GravitasPacker compression/decompression
• chronos_grid.py: Optional quantization support
• Test infrastructure migrated from pytest to unittest
• Docker metadata updated to v1.3.1
• README badges and features updated
• Version bumped to 1.3.1

Fixed

• Critical: pytest timeout issue resolved via unittest migration
• Critical: sentence-transformers blocking eliminated
• ASCII safety enforced across all output (no Unicode in cp949 environment)

Tests

• python tests/run_all_tests.py (19/19 passed, 0.33s)
• All semantic search features verified
• Performance benchmarks included

Breaking Changes

• None (fully backward compatible)
• search_mode parameter is optional with default behavior preserved

v1.2.2 - 2025/12/9

Highlights

• Expanded test coverage: encryption service round-trips/invalid tokens, batch search sequential/parallel flows, and Redis cache backend with in-memory fake client.
• Coverage config now includes Redis cache backend; package metadata updated to v1.2.2 across code, metrics, and docs.

What changed

• Added tests:
  • tests/test_encryption_service.py for env-key round trips, disabled mode, and invalid token handling.
  • tests/test_batch_routes_unit.py for parallel priority ordering, uninitialized service (503), and error paths.
  • tests/test_cache_redis.py for RedisCache/SearchResultCacheRedis get/set/delete/clear and get_redis_cache availability.
• Service readiness: default store is created at startup and seeded with a tiny fallback document so /search works in offline/fallback mode without prior uploads.
• Version bumps:
  • pyproject.toml, flamehaven_filesearch/__init__.py, metrics/logging metadata, README/UPGRADING badges.
• Coverage config:
  • flamehaven_filesearch/cache_redis.py is no longer omitted from coverage reporting.

Validation

• python -m pytest → 22 passed, 2 skipped.

Upgrade notes

• No breaking API changes.
• Redis remains optional; tests use an in-memory fake client to keep local runs dependency-light.

[1.2.1] - 2025-11-27

Added

• Admin cache controls: /api/admin/cache/stats and /api/admin/cache/flush (admin-only).
• Admin permission enforcement on API keys (403 if admin perm missing).
• IAMProvider hook for future OIDC/IAM backends.
• Metrics payload now includes cache, health_status, prometheus placeholders for dashboard use.
• Frontend cache/metrics pages wired to backend endpoints; upload/admin pages wired with token inputs.
• Tests: tests/test_admin_cache.py for cache stats/flush admin routes.
• Frontend dashboard pages added/updated: landing, search, upload, admin (keys), cache, metrics (wired to backend APIs with token inputs).

Changed

• Default new API keys include admin in permissions.
• README version/tag bumped to v1.2.1; added FLAMEHAVEN_ENC_KEY env guidance; SECURITY updated for admin/encryption notes.

Fixed

• Prevent admin access with non-admin API keys (returns 403).

FLAMEHAVEN FileSearch v1.2.0 Release Notes

FLAMEHAVEN FileSearch v1.2.0 Release Notes

Release Date: November 16, 2025
Version: 1.2.0
Status: PRODUCTION READY

Executive Summary

FLAMEHAVEN FileSearch v1.2.0 is an enterprise-ready release that transforms the service from an open public API to a secure, authenticated platform with advanced features for multi-worker deployments and high-throughput batch processing.

Key Achievements:

• Secure API authentication with fine-grained permissions
• Admin dashboard for key management and monitoring
• Batch search API for processing 1-100 queries per request
• Redis cache backend for multi-worker deployment support
• 100% backward compatible with existing file formats

---

What's New in v1.2.0

[*] API Authentication & Authorization

Breaking Change Alert: All protected endpoints now require API key authentication.

Features

• Bearer Token Authentication: OAuth2-compatible Bearer token scheme
• API Key Management: Create, list, revoke, and track API keys
• Fine-Grained Permissions: Per-key permission control (upload, search, stores, delete)
• Rate Limiting: Per-API-key customizable rate limits (default 100/min)
• Audit Logging: Complete request audit trail with request IDs
• SHA256 Hashing: Plain keys never stored in database

Protected Endpoints

POST   /api/upload/single          - Requires "upload" permission
POST   /api/upload/multiple        - Requires "upload" permission
POST   /api/search                 - Requires "search" permission
GET    /api/search                 - Requires "search" permission
POST   /api/stores                 - Requires "stores" permission
GET    /api/stores                 - Requires "stores" permission
DELETE /api/stores/{name}          - Requires "delete" permission

Public Endpoints (No Auth Required)

GET    /                           - Root endpoint
GET    /health                     - Health check
GET    /prometheus                 - Prometheus metrics
GET    /docs                       - API documentation
GET    /admin/dashboard            - Admin dashboard UI

Example: Using API Keys

# Generate API key via admin endpoint
curl -X POST http://localhost:8000/api/admin/keys \
  -H "X-Admin-Key: your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","permissions":["upload","search"]}'

# Use API key in requests
curl -X POST http://localhost:8000/api/search \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query":"my search"}'

---

[+] Admin Dashboard

Endpoint: GET /admin/dashboard

Features

• Web UI for API key management
• Statistics Cards: Total requests, active keys, top endpoints
• Key Management Table: View, revoke, and manage API keys
• Request Distribution: Visual analytics of endpoint usage
• API Reference: Built-in API documentation
• No External Dependencies: Self-contained HTML/CSS/JavaScript

Admin Endpoints

• POST /api/admin/keys - Create new API key
• GET /api/admin/keys - List user's API keys
• DELETE /api/admin/keys/{key_id} - Revoke API key
• GET /api/admin/usage?days=7 - Usage statistics
• GET /admin/dashboard - Dashboard UI

---

[=] Batch Search API

Endpoint: POST /api/batch-search

Features

• Process 1-100 queries in a single request
• Sequential or Parallel execution modes
• Query Prioritization: Sort by priority before execution
• Per-Query Error Handling: Failures don't affect other queries
• Detailed Metrics: Timing and result statistics per query
• Optimized for Throughput: Ideal for high-volume search scenarios

Example Request

{
  "queries": [
    {
      "query": "first search",
      "store": "documents",
      "priority": 5,
      "max_results": 3
    },
    {
      "query": "second search",
      "store": "documents",
      "priority": 3,
      "max_results": 5
    }
  ],
  "mode": "parallel",
  "max_results": 10
}

Example Response

{
  "request_id": "req_abc123...",
  "batch_size": 2,
  "successful_queries": 2,
  "failed_queries": 0,
  "total_duration_ms": 1250,
  "results": [
    {
      "query": "first search",
      "status": "success",
      "duration_ms": 625,
      "result_count": 3,
      "answer": "...",
      "sources": [...]
    },
    {
      "query": "second search",
      "status": "success",
      "duration_ms": 625,
      "result_count": 5,
      "answer": "...",
      "sources": [...]
    }
  ]
}

---

[&] Redis Cache Backend

Optional Feature: Requires redis>=4.0.0

Features

• Distributed Caching for multi-worker deployments
• Automatic Fallback: Gracefully reverts to LRU cache if Redis unavailable
• Namespace Isolation: Keys prefixed with flamehaven: namespace
• Cache Statistics: Monitor hits, misses, and size
• TTL Support: Configurable cache expiration
• Zero Configuration: Works with default environment variables

Configuration

# Environment Variables
REDIS_HOST=localhost        # Default: localhost
REDIS_PORT=6379           # Default: 6379
REDIS_PASSWORD=secret     # Optional
REDIS_DB=0               # Optional: database number

Performance Impact

• Cache Hit Latency: <10ms (99% faster than API calls)
• Expected Cost Reduction: 40-60% reduction in Gemini API calls
• Typical Hit Rate: 40-60% on repeated queries

---

Migration Guide for v1.1.0 Users

Step 1: Update Dependencies

pip install -U flamehaven-filesearch[api]

Step 2: Generate Admin Key

Set an admin key for managing API keys:

export FLAMEHAVEN_ADMIN_KEY="your_secure_admin_key_here"

Step 3: Create First API Key

curl -X POST http://localhost:8000/api/admin/keys \
  -H "X-Admin-Key: your_secure_admin_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Key",
    "permissions": ["upload", "search", "stores", "delete"],
    "rate_limit_per_minute": 100
  }'

Step 4: Update Application Code

Old (v1.1.0):

import requests

response = requests.post("http://localhost:8000/api/search", json={
    "query": "test query"
})

New (v1.2.0):

import requests

api_key = "sk_live_abc123..."  # Your API key from Step 3

response = requests.post(
    "http://localhost:8000/api/search",
    json={"query": "test query"},
    headers={"Authorization": f"Bearer {api_key}"}
)

Step 5: (Optional) Enable Redis Cache

pip install flamehaven-filesearch[api,redis]

# Configure Redis
export REDIS_HOST=localhost
export REDIS_PORT=6379

---

Deployment Guide

Docker Deployment

Build Image

docker build -t flamehaven-filesearch:1.2.0 .

Run Container

docker run \
  -e GEMINI_API_KEY="your_gemini_key" \
  -e FLAMEHAVEN_ADMIN_KEY="your_admin_key" \
  -e REDIS_HOST="redis-server" \
  -p 8000:8000 \
  flamehaven-filesearch:1.2.0

Docker Compose

version: '3.8'

services:
  api:
    image: flamehaven-filesearch:1.2.0
    environment:
      GEMINI_API_KEY: ${GEMINI_API_KEY}
      FLAMEHAVEN_ADMIN_KEY: ${FLAMEHAVEN_ADMIN_KEY}
      REDIS_HOST: redis
    ports:
      - "8000:8000"
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Kubernetes Deployment

ConfigMap for Settings

apiVersion: v1
kind: ConfigMap
metadata:
  name: flamehaven-config
data:
  ENVIRONMENT: production
  FLAMEHAVEN_API_KEYS_DB: /data/api_keys.db

Secret for Credentials

apiVersion: v1
kind: Secret
metadata:
  name: flamehaven-secrets
type: Opaque
stringData:
  GEMINI_API_KEY: your_api_key
  FLAMEHAVEN_ADMIN_KEY: your_admin_key
  REDIS_PASSWORD: your_redis_password

Deployment Manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flamehaven-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: flamehaven-api
  template:
    metadata:
      labels:
        app: flamehaven-api
    spec:
      containers:
      - name: api
        image: flamehaven-filesearch:1.2.0
        ports:
        - containerPort: 8000
        env:
        - name: ENVIRONMENT
          valueFrom:
            configMapKeyRef:
              name: flamehaven-config
              key: ENVIRONMENT
        - name: GEMINI_API_KEY
          valueFrom:
            secretKeyRef:
              name: flamehaven-secrets
              key: GEMINI_API_KEY
        - name: FLAMEHAVEN_ADMIN_KEY
          valueFrom:
            secretKeyRef:
              name: flamehaven-secrets
              key: FLAMEHAVEN_ADMIN_KEY
        - name: REDIS_HOST
          value: "redis.default.svc.cluster.local"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 10

---

Known Limitations

v1.2.0 Limitations

1. Admin Authentication: Uses environment variable (improved in v1.2.1)
2. Redis Configuration: No web UI for Redis settings (planned v1.2.1)
3. Key Rotation: Not yet implemented (v1.3.0)
4. OAuth2/OIDC: Not yet supported (v1.3.0)

Deprecations

• FastAPI on_event decorators (migrate to lifespan in v1.2.1)
• Pydantic v2 __fields__ attribute (remove in v1.3.0)

---

Performance Benchmarks

Response Times

• Health Check: <10ms
• Search (cache hit): <10ms
• Search (cache miss): 500ms - 3s (depends on Gemini API)
• Batch Search (10 queries): 2-5s
• File Upload: 1-5s (depends on file size)
  ...

🚀 Major Upgrade V1.1.0 - Security, Performance, and Production Readiness

Release Notes - FLAMEHAVEN FileSearch v1.1.0

Release Date: November 13, 2025
Type: Major Upgrade - Production-Ready Release
SIDRCE Score: 0.94 (CERTIFIED) ✅

---

🚀 Overview

v1.1.0 transforms FLAMEHAVEN FileSearch from a functional prototype into a production-ready enterprise solution with critical security fixes, intelligent caching, comprehensive monitoring, and complete automation.

Key Improvements

• ⚡ 99% faster response times on cache hits (<10ms vs 2-3s)
• 💰 40-60% reduction in Gemini API costs
• 🔒 Zero CRITICAL vulnerabilities (all CVEs patched)
• 📊 17 Prometheus metrics for observability
• 🛡️ OWASP-compliant security headers
• ✅ 96 automated tests (90% coverage)

---

🔒 Security Enhancements

Critical Vulnerability Fixes

CVE-2025-XXXX: Path Traversal Protection

• Severity: CRITICAL
• Impact: Prevented arbitrary file write and information disclosure
• Fix: os.path.basename() sanitization in upload endpoints
• Blocked attacks: ../../etc/passwd, .env, hidden files

CVE-2024-47874 & CVE-2025-54121: Starlette DoS

• Severity: CRITICAL
• Impact: Prevented denial-of-service via malformed multipart requests
• Fix: FastAPI 0.104.0 → 0.121.1, Starlette 0.38.6 → 0.49.3

New Security Features

• Rate Limiting (per IP address):

  • Single file upload: 10 requests/minute
  • Multiple file upload: 5 requests/minute
  • Search queries: 100 requests/minute
  • Store management: 20 requests/minute

• OWASP Security Headers:

  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
  Strict-Transport-Security: max-age=31536000
  Content-Security-Policy: default-src 'self'
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: geolocation=(), microphone=(), camera=()
  

• Input Validation:

  • FilenameValidator: Path traversal and hidden file detection
  • SearchQueryValidator: XSS and SQL injection prevention
  • FileSizeValidator: Configurable size limits (50MB default)
  • MimeTypeValidator: Whitelist enforcement

• Request Tracing:

  • X-Request-ID header for distributed tracing
  • Request ID in all logs and error responses
  • UUID v4 generation for audit trails

---

⚡ Performance Optimization

Intelligent Caching (LRU + TTL)

Search Cache

• Algorithm: LRU (Least Recently Used) with Time-To-Live
• Capacity: 1000 items
• TTL: 3600 seconds (1 hour)
• Key Generation: SHA256 hash of query parameters
• Cache Hit Rate: 40-60% in typical workloads

Performance Impact

Metric	Before (v1.0.0)	After (v1.1.0)	Improvement
Cache Hit Response	N/A	<10ms	-
Cache Miss Response	2-3s	2-3s	Unchanged
Average Response (50% hit rate)	2-3s	~1s	50% faster
API Cost (50% hit rate)	$X	$X/2	50% reduction

Real-World Impact

• Repeated queries: 99% faster (<10ms vs 2-3s)
• Cost savings: 40-60% reduction in Gemini API costs
• User experience: Near-instant responses for cached queries

File Metadata Cache

• Capacity: 500 items
• Use case: Avoid redundant file metadata lookups
• Performance: Eliminates filesystem overhead

---

📊 Monitoring & Observability

Prometheus Metrics (17 metrics)

HTTP Metrics

• http_requests_total - Total HTTP requests by method/endpoint/status
• http_request_duration_seconds - Request duration histogram

Upload Metrics

• upload_total - Total file uploads by type/store/status
• upload_size_bytes - Upload size histogram
• upload_duration_seconds - Upload duration histogram

Search Metrics

• search_total - Total searches by store/status
• search_duration_seconds - Search duration histogram
• search_results_total - Search results count

Cache Metrics

• cache_hits_total - Cache hits by cache type
• cache_misses_total - Cache misses by cache type
• cache_size - Current cache size

Error Metrics

• errors_total - Total errors by type/endpoint
• rate_limit_exceeded_total - Rate limit violations

System Metrics

• system_cpu_usage_percent - CPU usage percentage
• system_memory_usage_percent - Memory usage percentage
• system_disk_usage_percent - Disk usage percentage
• uptime_seconds - Service uptime

Structured Logging

Production Mode (JSON format)

{
  "timestamp": "2025-11-13T12:00:00Z",
  "level": "INFO",
  "logger": "flamehaven_filesearch.api",
  "message": "Search request completed",
  "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "duration_ms": 8.5,
  "cache_hit": true,
  "service": "flamehaven-filesearch",
  "version": "1.1.0"
}

Development Mode (Human-readable)

2025-11-13 12:00:00 - INFO - flamehaven_filesearch.api - Search request completed (8.5ms, cache_hit=True)

New Endpoints

/prometheus - Prometheus metrics endpoint

• Format: Prometheus text exposition format
• Scrape interval: 15 seconds recommended
• No authentication (internal monitoring)

Enhanced /metrics - JSON metrics with cache statistics

{
  "cache": {
    "search_cache": {
      "hits": 1500,
      "misses": 500,
      "hit_rate_percent": 75.0,
      "size": 450
    }
  },
  "system": {
    "cpu_percent": 15.2,
    "memory_percent": 45.3,
    "disk_percent": 62.1
  }
}

---

🤖 Automation & CI/CD

GitHub Actions Workflows

Security Scanning (.github/workflows/security.yml)

• Bandit - SAST for Python code
• Safety - Dependency vulnerability scanner
• Trivy - Container image scanning
• CodeQL - Semantic code analysis
• Schedule: Daily at midnight
• Artifacts: SARIF reports uploaded to GitHub Security Dashboard

Secrets Scanning (.github/workflows/secrets.yml)

• Gitleaks - Full git history scanning
• TruffleHog - High-entropy secret detection
• Custom Patterns - API key detection
• Environment Validation - .env file checks

Pre-commit Hooks

Installed Hooks:

• black (code formatting)
• isort (import sorting)
• flake8 (linting)
• bandit (security)
• gitleaks (secrets)
• Custom security checks (path traversal, hidden files)

Usage:

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Test Infrastructure

Coverage: 90%+ (96 tests)

• Security Tests: 27 tests (path traversal, validation, authentication)
• Edge Case Tests: 34 tests (boundaries, concurrency, stability)
• Performance Tests: 15 tests (response time, throughput, scalability)
• Integration Tests: 20+ tests (API workflows, request tracing)

Test Markers:

pytest -v -m "not slow"           # Fast tests only
pytest -v -m security              # Security tests
pytest -v -m performance           # Performance tests
pytest --cov --cov-fail-under=90   # Coverage enforcement

---

📚 Documentation

New Documentation Files

SECURITY.md (600+ lines)

• Vulnerability fixes and enhancements
• Production deployment best practices
• Security monitoring and incident response
• Responsible disclosure guidelines
• Compliance (GDPR, OWASP Top 10)

UPGRADING.md (800+ lines)

• Complete migration guide (v1.0.0 → v1.1.0)
• 4 deployment scenarios (development, systemd, Docker, Kubernetes)
• Troubleshooting guide (5 common issues)
• FAQ (10 questions)
• Rollback procedure

Enhanced CHANGELOG.md

• Comprehensive v1.1.0 release notes
• Detailed feature breakdown
• Migration guide reference

Updated README.md

• v1.1.0 features table with impact metrics
• Performance benchmarks (before/after comparison)
• Enhanced configuration section
• /prometheus endpoint documentation
• Updated roadmap

Total Documentation

• Size: 321KB across 8 major files
• Quality: 0 broken links, comprehensive coverage
• Usability: Clear examples, troubleshooting, FAQs

---

🔧 Configuration Changes

New Environment Variables

Logging Configuration

export ENVIRONMENT=production      # JSON logs (default)
export ENVIRONMENT=development     # Human-readable logs

Server Configuration

export HOST=0.0.0.0               # Server host (default)
export PORT=8000                  # Server port (default)
export WORKERS=4                  # Number of workers (production)

Backward Compatibility

✅ Fully backward compatible with v1.0.0

• All existing configurations work without changes
• New variables are optional
• No breaking changes

---

📦 Installation & Upgrade

Fresh Installation

pip install flamehaven-filesearch[api]==1.1.0

Upgrade from v1.0.0

# 1. Backup data (optional)
cp -r ./data ./data_backup

# 2. Upgrade package
pip install -U flamehaven-filesearch[api]

# 3. Restart service
flamehaven-api

Downtime: ~10 seconds (restart only)

Docker

docker pull flamehaven/filesearch:1.1.0
docker-compose down && docker-compose up -d

---

🎯 Migration Guide

For Developers

No code changes required!

• v1.1.0 is fully backward compatible
• Existing API clients work without modification
• Data format unchanged

For DevOps

Optional enhancements:

1. Set up Prometheus scraping (15s interval)
2. Configure structured logging for ELK/Splunk
3. Adjust rate limits via reverse proxy (nginx)
4. Enable pre-commit hooks for team

Prometheus Configuration:

# prometheus.yml
scrape_configs:
  - job_name: 'flamehaven-filesearch'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: /prometheus
    scrape_interval: 15s

---

...

📦 Release v0.1.0

[1.0.0] - 2025-11-11

🎉 FLAMEHAVEN File Search Tool - Official Release!

Major Announcement: Initial release of FLAMEHAVEN FileSearch - the FLAMEHAVEN File Search Tool is now open source!

Added

• Core FlamehavenFileSearch class for file search and retrieval
• Support for PDF, DOCX, MD, TXT files
• File upload with basic validation (max 50MB in Lite tier)
• Search with automatic citation (max 5 sources)
• FastAPI-based REST API server
• Multiple endpoint support:
  • POST /upload - Single file upload
  • POST /upload-multiple - Batch file upload
  • POST /search - Search with full parameters
  • GET /search - Simple search queries
  • GET /stores - List all stores
  • POST /stores - Create new store
  • DELETE /stores/{name} - Delete store
  • GET /health - Health check
  • GET /metrics - Service metrics
• Configuration management via environment variables
• Docker support with Dockerfile and docker-compose.yml
• CI/CD pipeline with GitHub Actions
• Comprehensive test suite (pytest)
• Code quality tools (black, flake8, isort, mypy)
• PyPI packaging with pyproject.toml
• Full documentation and examples

Features

• Google Gemini 2.5 Flash integration
• Automatic grounding with source citations
• Driftlock validation (banned terms, length checks)
• Multiple store management
• Batch file operations
• Configurable model parameters
• Error handling and validation
• CORS support
• Health checks and metrics

Documentation

• Comprehensive README with quick start guide
• API documentation (OpenAPI/Swagger)
• Usage examples (library and API)
• Contributing guidelines
• License (MIT)