# Biblioteca Sophia

Sistema local de biblioteca RAG (ChromaDB) para uso com o **Claude Desktop** via MCP, com interface gráfica para gerenciar bibliotecas e processar PDFs escaneados via OCR.

- Guarde seus próprios livros/PDFs em bibliotecas separadas
- Pesquise o conteúdo deles diretamente dentro de conversas com o Claude, via MCP
- Interface gráfica para criar bibliotecas, adicionar documentos e acompanhar o progresso
- Detecção automática de PDFs escaneados (sem texto digital) + OCR em lote (Tesseract)

## Requisitos

- Windows 10/11
- Python 3.10+ — [python.org/downloads](https://python.org/downloads) (marque "Add Python to PATH" durante a instalação)
- Claude Desktop instalado
- (Opcional, só para OCR de PDFs escaneados) Tesseract OCR — [github.com/UBMannheim/tesseract/wiki](https://github.com/UBMannheim/tesseract/wiki)

## Instalação

1. Baixe/clone este repositório para uma pasta, ex: `D:\BibliotecaSophia`
2. Dê dois cliques em **`instalar.bat`**. Ele:
   - Verifica se há um Python funcional instalado (e avisa se for só o atalho falso da Microsoft Store)
   - Cria um ambiente virtual isolado (`.venv`)
   - Instala todas as dependências automaticamente
   - Cria as pastas `dados/` e `chromadb_storage/`
   - Verifica se o Tesseract OCR está presente (avisa se não estiver)
   - **Registra automaticamente o servidor no Claude Desktop** (edita o `claude_desktop_config.json` por você, sem apagar outros servidores MCP que você já tenha configurado — faz backup automático antes)
3. Feche e abra o Claude Desktop completamente
4. Pronto — a instalação não se repete depois da primeira vez

## Interface web (busca via navegador, sem IA)

Rode `python web_interface.py` (dentro do `.venv`) e acesse **http://localhost:5000**. Página simples para escolher uma biblioteca e buscar, usando a mesma busca híbrida (BM25 + vetorial + re-ranking) do servidor MCP — sem depender de nenhuma IA.

## Uso do dia a dia (interface gráfica)

Dê dois cliques em **`Abrir_Sophia.vbs`** — abre o painel direto, sem terminal.

O painel tem duas abas:

- **Bibliotecas** — criar biblioteca nova, adicionar documentos, deletar, ver progresso
- **OCR em Lote** — aponte uma pasta de PDFs, ele detecta sozinho quais precisam de OCR (PDFs escaneados/fotografados) e gera os `.txt` prontos para indexar

> **Nomes de biblioteca:** o ChromaDB não aceita acento, espaço ou símbolo no nome interno da coleção. Se você digitar um nome como "Biblioteca Nórdica", a interface ajusta automaticamente para algo como `biblioteca_nordica` e mostra o resultado antes de confirmar.

## Como o conteúdo é processado (chunking)

Cada PDF/TXT é dividido em blocos de aproximadamente **1800 caracteres**, respeitando parágrafos, com **20% de sobreposição (overlap)** entre blocos consecutivos — isso preserva contexto que ficaria cortado no meio se a divisão fosse rígida. Esse comportamento é o mesmo tanto na indexação via interface gráfica quanto via servidor MCP.

## Conectar ao Claude Desktop (MCP)

O `instalar.bat` já faz esse passo automaticamente. Se precisar rodar de novo manualmente (ex: depois de mover a pasta do projeto):

```
.venv\Scripts\python.exe configurar_mcp.py
```

Para remover o registro (ex: antes de desinstalar):

```
.venv\Scripts\python.exe configurar_mcp.py --remover
```

Isso edita o arquivo `claude_desktop_config.json` (normalmente em `%APPDATA%\Claude\claude_desktop_config.json`), adicionando:

```json
{
  "mcpServers": {
    "biblioteca-sophia": {
      "command": "D:\\BibliotecaSophia\\.venv\\Scripts\\python.exe",
      "args": ["D:\\BibliotecaSophia\\server_chromadb.py"]
    }
  }
}
```

Sempre mantendo qualquer outro servidor MCP que já esteja configurado, e criando um backup (`claude_desktop_config.json.bak`) antes de qualquer alteração.

Depois de rodar, feche o Claude Desktop **completamente** (não só minimizar) e abra de novo. No campo de mensagem, deve aparecer um ícone de ferramentas (martelo) — clique nele para confirmar que o servidor "Biblioteca Sophia" está conectado.

## Avançado (opcional): servidor HTTP em segundo plano

Por padrão, o Claude Desktop já funciona via conexão direta (stdio), configurada automaticamente pelo `instalar.bat` — **isso não precisa dessa seção**.

Essa parte é útil se você quiser conectar a Biblioteca Sophia em **outras ferramentas que falam MCP via HTTP** (Qwen, GPT, Grok, AnythingLLM, Mistral, Manus, etc.), mantendo um servidor sempre ativo em segundo plano, sem precisar abrir nada manualmente.

**Ativar**

1. Clique com o botão direito em **`registrar_tarefa_sophia.bat`** → **Executar como administrador**
2. Isso registra uma tarefa agendada do Windows que sobe o servidor em modo HTTP automaticamente ~30 segundos após o login, sem nenhuma janela visível
3. O endpoint local fica disponível em: `http://localhost:8765/mcp`
4. Em cada ferramenta (Qwen, GPT, AnythingLLM, etc.), siga a documentação específica dela sobre como adicionar um servidor MCP/ferramenta customizado via HTTP, usando esse endereço local

**Desativar**

```
schtasks /delete /tn "BibliotecaSophia" /f
```

### Expor o servidor HTTP pela internet (opcional, avançado)

Por padrão, o servidor HTTP (seção acima) só responde em `localhost` — funciona apenas na mesma máquina. Se você quiser acessá-lo de fora (por exemplo, de outro computador, ou para conectar ferramentas que não rodam localmente), uma forma comum é usar um túnel do **Cloudflare** (`cloudflared`).

Isso é opcional, avançado, e requer uma conta gratuita na Cloudflare e um domínio próprio. Passo básico, generalista:

1. Instale o `cloudflared` ([developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads))
2. Autentique com sua conta Cloudflare: `cloudflared tunnel login`
3. Crie um túnel: `cloudflared tunnel create biblioteca-sophia`
4. Configure a rota do túnel para apontar para `http://localhost:8765` (via arquivo `config.yml` do cloudflared, associando um subdomínio seu ao serviço local)
5. Rode o túnel: `cloudflared tunnel run biblioteca-sophia`
6. O endereço público (ex: `https://sophia.seudominio.com/mcp`) passa a responder o que está rodando localmente na porta 8765

> **Atenção:** expor esse servidor publicamente significa que qualquer pessoa com o endereço pode consultar suas bibliotecas (não há autenticação embutida no servidor MCP). Se for expor publicamente, considere adicionar autenticação na camada do túnel (a Cloudflare oferece isso via **Cloudflare Access**) antes de divulgar o endereço. Este README cobre só o básico para você começar — os detalhes finos de configuração de DNS, Access, e segurança ficam por sua conta.

## Estrutura de pastas

```
BibliotecaSophia/
├── instalar.bat                  <- rode uma vez, no início
├── Abrir_Sophia.vbs              <- atalho do dia a dia (sem terminal)
├── configurar_mcp.py             <- registra o servidor no Claude Desktop (roda sozinho no instalar.bat)
├── registrar_tarefa_sophia.bat   <- (opcional) ativa o servidor HTTP em segundo plano
├── iniciar_sophia.vbs            <- (opcional) launcher silencioso do modo HTTP
├── requirements.txt
├── server_chromadb.py            <- servidor MCP (usado pelo Claude Desktop)
├── sophia_unificado.py           <- interface gráfica (Bibliotecas + OCR)
├── gerenciar_bibliotecas.py
├── dados/                        <- seus PDFs/TXTs organizados por biblioteca
└── chromadb_storage/             <- banco de dados vetorial (gerado automaticamente)
```

> **Sobre o conteúdo das bibliotecas:** este repositório distribui apenas a ferramenta. Os livros/PDFs de cada biblioteca não estão incluídos — cada pessoa monta sua própria coleção de acordo com seu próprio acervo e direitos de uso sobre esse material.

## Licença

Este projeto é distribuído sob licença **MIT** (veja [LICENSE](LICENSE)) — uso livre, inclusive comercial, **desde que o aviso de copyright/crédito original seja mantido** nas cópias e distribuições.

> Nota: não sou advogado, e isso não é aconselhamento jurídico. A licença MIT é um padrão amplamente usado no mundo open-source justamente porque é simples e permissiva, mas se você quiser uma condição de atribuição mais específica ou restrições adicionais (ex: proibir revenda), vale conversar com um profissional antes de publicar, para redigir os termos exatos que você deseja.

## Créditos

Desenvolvido por **Rafael** — sinta-se livre para usar, adaptar e redistribuir, mantendo o crédito original conforme a licença.