Flamehaven FileSearch — mecanismo de busca de documentos RAG open source com self-hosting

 (github.com/flamehaven01)
29 pontos por flamehaven01 2025-11-13 | 4 comentários | Compartilhar no WhatsApp

🔥Flamehaven FileSearch

  • Flamehaven FileSearch é um mecanismo de busca semântica open source com self-hosting que permite a qualquer pessoa montar, em 5 minutos, um sistema RAG (Retrieval-Augmented Generation) baseado em documentos.
  • Ele funciona com base em Python, FastAPI e SQLite, e usa Google Gemini Embedding para realizar perguntas e respostas em linguagem natural em vários tipos de documentos, como PDF/DOCX/TXT/MD.

Por que foi criado?

  • A maioria das implementações open source de RAG funciona bem em ambientes como Colab ou Jupyter, mas, na hora de colocar em um servidor real para operar, a estrutura costuma ser complexa ou falta estabilidade.
  • O Flamehaven FileSearch foi projetado com o objetivo de ser uma “stack RAG leve que realmente funciona”, para que pesquisadores, startups e desenvolvedores independentes possam experimentar imediatamente busca semântica com seus próprios dados.

Por que vale a atenção?

  • Autonomia total: não depende de servidores externos nem de nuvem, e todos os dados são armazenados localmente.
  • Estrutura centrada no desenvolvedor: Python SDK + REST API, com documentação Swagger gerada automaticamente com base em FastAPI.
  • Distribuição como pacote PyPI: instalação imediata em PyPI — instalação totalmente automática com uma única linha: pip install flamehaven-filesearch[api].
  • Execução imediata: após instalar, basta iniciar o servidor com o comando flamehaven-api, e no navegador é possível testar a API em /docs.
  • Escalabilidade: armazenamento em SQLite, arquitetura de plugins e suporte a implantação com Docker.
  • Adequado para educação e pesquisa: usa embeddings do Gemini, sendo ideal para práticas de busca semântica baseadas em LLMs modernos.

O que está incluído? (destaques)

  • Python SDK: from flamehaven_filesearch import FlamehavenFileSearch

    → oferece todas as funções de upload de documentos / busca / gerenciamento de stores.

  • REST API: endpoints /upload, /search, /stores + Swagger UI.

  • Suporte a Docker: docker run -e GEMINI_API_KEY=... -p 8000:8000 flamehaven/filesearch:latest

  • Estrutura: core(engine) / api(FastAPI) / data(SQLite) / examples / docs

Teste rápido

1️⃣ Pacote PyPI

O Flamehaven FileSearch pode ser instalado diretamente via PyPI.

Ver a versão mais recente: https://pypi.org/project/flamehaven-filesearch

pip install flamehaven-filesearch[api]

2️⃣ Instalação

pip install flamehaven-filesearch[api]  
export GEMINI_API_KEY="your-google-gemini-key"  
flamehaven-api

3️⃣ Upload de documento e busca

curl -X POST "http://localhost:8000/upload"; -F "file=@handbook.pdf"  
curl "http://localhost:8000/search?q=vacation+policy";

4️⃣ Exemplo de uso do SDK

from flamehaven_filesearch import FlamehavenFileSearch  
fs = FlamehavenFileSearch()  
fs.upload_file("handbook.pdf")  
print(fs.search("vacation policy")["answer"])

Desempenho e especificações

  • Ambiente: Ubuntu 22.04 / 2vCPU / 4GB RAM / SSD
  • Upload de PDF de 10MB → cerca de 5 segundos
  • Tempo médio de resposta da busca → 2 segundos (ao citar 5 fontes)
  • Exclusão/criação de store → menos de 1 segundo
  • Overhead de armazenamento → cerca de 5% do tamanho do documento

Roadmap

  • v1.1 : cache e gerenciamento de cotas
  • v1.2 : busca em lote + streaming via WebSocket
  • v2.0 : suporte a documentos multilíngues, dashboard de análise
  • Futuro : integração com vector DBs Pinecone/Weaviate, OCR, stores colaborativos

Licença

  • MIT License (totalmente open source)

🛡️ Aviso de segurança e conta do Flamehaven no Github

Recentemente, após a detecção de tentativas suspeitas de login na conta do Flamehaven no GitHub (esta conta principal), a conta foi colocada em estado de suspensão. No momento, a equipe está verificando o problema em cooperação com o time de segurança do GitHub.

Por causa deste incidente, contas que incluem dir2md, flashrecord, crom-efficient, Arr-medic-cyp3a4 e outras permanecerão temporariamente sem uso.

Pedimos sinceras desculpas pelo inconveniente aos usuários e agradecemos pela compreensão até que a verificação de segurança seja concluída.

Leituras relacionadas

4 comentários

 
flamehaven01 2025-12-09

Atualização: lançamento da v1.2.2

Depois de publicar o post original, até hoje já chegamos à v1.2.2.
Resumindo apenas as mudanças de forma breve:

Reforço em testes/estabilidade

Serviço de criptografia: round trip de encrypt/decrypt com chave env + teste do caminho de token inválido

Busca em lote: fila de prioridade paralela, serviço não inicializado → 503, separação de exceções por consulta

Cache Redis: testes de get/set/delete/clear + verificação de disponibilidade com cliente fake em memória

O cache_redis.py, que até então estava fora da cobertura, passou a ser incluído na cobertura

Prontidão do serviço (Service readiness)

Na primeira inicialização do servidor, o store padrão e um pequeno documento de fallback são criados automaticamente

Mesmo sem fazer upload de nada, /search e /health já respondem 200 imediatamente
→ pode ser usado direto para checks de saúde de demo/CI/inicialização de agentes

Ajustes operacionais

String de versão, metadados de log, labels do Prometheus e título do OpenAPI foram alinhados para v1.2.2

O Redis continua opcional e, se não estiver presente, faz fallback naturalmente para um cache LRU in-process

Sem breaking changes; usuários atuais podem fazer o upgrade normalmente.
Estou ajustando aos poucos para ficar cada vez mais “pronto para uso em produção”.
 
flamehaven01 2025-11-29

🚀 Lançamento do Flamehaven Filesearch v1.2.1!

Apresentamos a versão mais recente, v1.2.1, do Flamehaven Filesearch, que vem sendo continuamente aprimorado desde a última atualização. Esta release focou no reforço da segurança, na expansão das ferramentas de administração e na melhoria da praticidade operacional.

🔐 Principais atualizações
🔺Adição de Admin Cache Controls
Agora é possível consultar o status do cache e executar flush pelos caminhos /api/admin/cache/stats e /api/admin/cache/flush (somente para Admin)

🔺Reforço das permissões de API Key
Chaves sem permissão de Admin retornam 403 ao usar funções administrativas
Novas API Keys incluem permissão de admin por padrão

🔺Introdução do hook IAMProvider
Estrutura preparada para futura integração com backends OIDC/IAM

🔺Expansão de Metrics
Adição de cache, health_status e prometheus placeholder para melhorar o uso em dashboards

🔺Atualizações no frontend
Páginas de Cache / Metrics integradas ao backend
Função de entrada de Token conectada nas páginas Upload / Admin
Revisão das novas páginas Landing e Dashboard

🔺Reforço nos testes
Adição de test_admin_cache.py para introduzir testes da API administrativa relacionados a cache

🔺Atualização da documentação
Atualização da versão no README e reforço do guia de segurança, incluindo a variável de ambiente FLAMEHAVEN_ENC_KEY

🐛 Correções

Bloqueio de acesso (403) ao solicitar funções administrativas sem permissão de Admin

🔗 GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch

Esta versão também estabeleceu a base para a futura integração com IAM e para o avanço do dashboard.
 
flamehaven01 2025-11-19

Lancei ontem o Flamehaven FileSearch v1.2.0. Esta versão se concentrou em transformar todo o serviço de uma “API pública” em uma plataforma de nível enterprise voltada para segurança e escalabilidade.

As principais mudanças são as seguintes:

Adição de sistema de autenticação e permissões da API
Todos os endpoints protegidos agora exigem autenticação via Bearer Token.
As API Keys oferecem suporte a permissões granulares, como upload/busca/store/exclusão, e incluem rate limit por chave, logs de auditoria e armazenamento em hash SHA256 (sem armazenar a chave original).

Adição do Admin Dashboard
É uma interface web onde é possível criar/consultar/revogar API Keys, ver estatísticas de requisições e a distribuição de uso por endpoint.
É totalmente autocontido em HTML/CSS/JS, sem dependências externas.

Batch Search API
Processa de 1 a 100 consultas em uma única requisição.
Oferece modos de execução paralela/sequencial, ordenação baseada em prioridade, isolamento de erros por consulta e métricas detalhadas de tempo.

Backend de cache Redis
É uma opção de cache distribuído para ambientes com múltiplos workers.
Tem latência de consulta <10ms, fallback LRU automático e reduz em 40–60% o volume de chamadas ao LLM.

Modelos de deploy incluídos (Docker/Kubernetes)
Inclui exemplos de Docker, Docker Compose e Kubernetes (ConfigMap/Secret/Deployment) para deploy imediato.

Resumo de performance:

Cache hit: <10ms

Cache miss (chamada ao LLM): ~0.5–3s

Batch Search (10 itens): ~2–5s

GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch

Sugestões de melhoria sobre o design de segurança, usabilidade da API ou estrutura de deploy são bem-vindas.
A v1.2.1 (melhorias na autenticação do admin, UI de configuração do Redis) e a v1.3.0 (rotação de chaves + OAuth2/OIDC) também estão em preparação.
 
flamehaven01 2025-11-13

Lançamos hoje a v1.1.0.

Esta versão inclui principalmente correção de vulnerabilidade de path traversal, atualizações de segurança do FastAPI/Starlette, rastreamento de ID de requisição, rate limiting, cache (hit em <10ms), adição de métricas do Prometheus e outros pontos. Ela funciona de forma muito mais estável do que a versão anterior.

Esta atualização também continua focada em uma arquitetura leve e self-hostable. Obrigado.