{"id":34693652,"url":"https://github.com/woliveiras/cql-agent","last_synced_at":"2025-12-24T22:07:45.440Z","repository":{"id":319439817,"uuid":"1078317959","full_name":"woliveiras/cql-agent","owner":"woliveiras","description":"Agente de IA especializado em ajudar com pequenos reparos residenciais, construído com LangChain, FastAPI e modelos locais com Ollama","archived":false,"fork":false,"pushed_at":"2025-10-26T08:21:19.000Z","size":6760,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-26T10:06:24.248Z","etag":null,"topics":["ai-agent","ai-agents","docker","fastapi","llm","nodejs","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/woliveiras.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"woliveiras","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2025-10-17T14:41:05.000Z","updated_at":"2025-10-26T08:21:22.000Z","dependencies_parsed_at":"2025-10-19T05:17:11.229Z","dependency_job_id":"daaf7452-a1cb-4c22-a7b2-76270a5e067b","html_url":"https://github.com/woliveiras/cql-agent","commit_stats":null,"previous_names":["woliveiras/cql-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/woliveiras/cql-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woliveiras%2Fcql-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woliveiras%2Fcql-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woliveiras%2Fcql-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woliveiras%2Fcql-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/woliveiras","download_url":"https://codeload.github.com/woliveiras/cql-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woliveiras%2Fcql-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28010389,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-agents","docker","fastapi","llm","nodejs","python"],"created_at":"2025-12-24T22:07:44.570Z","updated_at":"2025-12-24T22:07:45.425Z","avatar_url":"https://github.com/woliveiras.png","language":"Python","funding_links":["https://github.com/sponsors/woliveiras"],"categories":[],"sub_categories":[],"readme":"# 🔧 Agente de IA para Reparos Residenciais\n\nAgente de IA especializado em ajudar com pequenos reparos residenciais, construído com LangChain e Python. Suporta múltiplos provedores de LLM: Ollama (local), OpenAI, Google Gemini e Anthropic.\n\n[![on_push_to_main](https://github.com/woliveiras/cql-agent/actions/workflows/on_push_to_main.yml/badge.svg)](https://github.com/woliveiras/cql-agent/actions/workflows/on_push_to_main.yml)\n\n\n## ✨ Funcionalidades\n\n- 🤖 Chat interativo para perguntas sobre reparos\n- 🏠 Especializado em problemas residenciais\n- ⚠️ Alertas de segurança quando necessário\n- 💡 Instruções passo a passo\n- 🎯 **Múltiplos provedores de LLM suportados:**\n  - 🔒 **Ollama** - 100% local e privado (padrão)\n  - 🌐 **OpenAI** - GPT-4, GPT-3.5-turbo, etc\n  - ✨ **Google Gemini** - Gemini 1.5 Flash/Pro\n  - 🧠 **Anthropic** - Claude 3.5 Sonnet\n- 🔄 Sistema de tentativas (até 3 tentativas antes de sugerir profissional)\n- ✅ Validação de feedback com respostas \"sim\" ou \"não\"\n- 📝 Histórico de conversação mantido para contexto\n- 🎯 Detecção automática de sucesso/falha\n- 📚 Base de conhecimento a partir de PDFs\n- 🔍 Busca semântica em documentos\n- 💾 Armazenamento vetorial com ChromaDB\n- 🎯 Respostas baseadas em manuais específicos\n- ⚡ Embeddings com múltiplos provedores\n- 🌐 Busca web com DuckDuckGo\n- 🔄 Fallback automático: RAG → Web → LLM\n- 🇧🇷 Resultados em português (região br-pt)\n- 🌐 API REST com FastAPI\n- 📖 Documentação Swagger e ReDoc automáticas\n- 🔌 Pipe Function para OpenWebUI\n- 🐳 Docker Compose para deploy completo\n- 🔄 Gerenciamento de sessões\n- 🎨 Interface web moderna\n- 🔒 Privacidade mantida (DuckDuckGo não rastreia)\n- 🛡️ Segurança reforçada com sanitização e guardrails\n- ✅ Validação rigorosa de entrada (Pydantic nativo)\n- 🚫 Proteção contra injection (SQL, XSS, Command)\n- 🎯 Guardrails de conteúdo (apenas reparos residenciais)\n- ⚡ Performance otimizada (async/await)\n- 🔐 Autenticação anônima (sem necessidade de login)\n- ⏱️ Rate limiting inteligente (proteção contra abuso)\n- 🎫 Tokens JWT temporários (gestão automática)\n\n## 🗄️ Gerenciamento de Sessões com Redis\n\nO agente suporta persistência de sessões via Redis, permitindo escalabilidade e recuperação de sessões após reinício. O backend detecta automaticamente se o Redis está habilitado via `.env`:\n\n- Para usar Redis, defina no `.env`:\n\n```bash\nUSE_REDIS=true\nREDIS_URL=redis://localhost:6379/0  # Ou configure manualmente REDIS_HOST, REDIS_PORT, etc.\n```\n\n- Para usar apenas memória (desenvolvimento):\n\n```bash\nUSE_REDIS=false\n```\n\nSe o Redis não estiver disponível, o sistema faz fallback automático para armazenamento em memória, sem perder funcionalidade.\n\nNo Docker Compose, o Redis já está configurado e integrado. Veja detalhes e exemplos avançados em [`docs/REDIS_SESSIONS.md`](docs/REDIS_SESSIONS.md).\n\n**Exemplo de configuração mínima no .env:**\n\n```bash\nUSE_REDIS=true\nREDIS_URL=redis://localhost:6379/0\n```\n\n**Exemplo de uso no código:**\n\n```python\nfrom api.session_manager import SessionManager\nmanager = SessionManager(use_redis=True)\nagent = manager.get_or_create_agent(session_id=\"user-123\")\nmanager.update_agent(\"user-123\", agent)\n```\n\n\u003e Para TTL, prefixo de chave e outras opções, consulte o guia completo em [`docs/REDIS_SESSIONS.md`](docs/REDIS_SESSIONS.md).\n\n## 🔐 Autenticação e Rate Limiting\n\nO sistema implementa **autenticação anônima** e **rate limiting** de forma **100% transparente** para o usuário - sem necessidade de login ou criação de conta!\n\n### Como Funciona\n\n1. **Fingerprinting**: Identifica usuários por IP + User-Agent\n2. **JWT Anônimo**: Gera tokens temporários automaticamente\n3. **Rate Limiting**: Limita requests por período (ex: 100/hora)\n4. **Redis Support**: Escalável e distribuído\n\n### Configuração Básica\n\n```bash\n# .env\nAUTH_ENABLED=true\nRATE_LIMIT_ENABLED=true\nRATE_LIMIT=100          # 100 requests\nRATE_WINDOW=3600        # por hora\nJWT_SECRET_KEY=sua_chave_secreta_forte\n```\n\n### Uso no Frontend\n\n```javascript\n// O token é gerenciado automaticamente!\nconst response = await fetch('/api/v1/chat/message', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${localStorage.getItem('anonymous_token')}`,\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({ message: 'Como consertar torneira?' })\n});\n\n// Salvar novo token (se fornecido)\nconst newToken = response.headers.get('X-Anonymous-Token');\nif (newToken) localStorage.setItem('anonymous_token', newToken);\n```\n\n**Vantagens:**\n- ✅ Usuário nunca faz login\n- ✅ Proteção contra abuso\n- ✅ Experiência fluida\n- ✅ Escalável com Redis\n\n📖 **Documentação completa:** [docs/AUTH_RATE_LIMITING.md](docs/AUTH_RATE_LIMITING.md)\n\n\n## 🏗️ Arquitetura\n\nO projeto é dividido em três componentes principais:\n\n1. **Backend (Python + FastAPI)**: API REST com agente de IA, RAG e ferramentas\n2. **Frontend (React + TypeScript)**: Interface web moderna para interação\n3. **Ollama (Docker)**: Servidor LLM local para processamento\n\n```text\n┌─────────────┐      ┌─────────────┐      ┌─────────────┐\n│   Frontend  │─────▶│   Backend   │─────▶│   Ollama    │\n│  React/Vite │ HTTP │ FastAPI/LLM │ HTTP │  LLM Local  │\n└─────────────┘      └─────────────┘      └─────────────┘\n                            │\n                            ├──▶ ChromaDB (RAG)\n                            └──▶ DuckDuckGo (Web Search)\n```\n\n## 🚀 Como usar\n\n### 1. Pré-requisitos\n\n**Backend:**\n\n- Python 3.12+\n- UV (gerenciador de pacotes Python)\n- Docker e Docker Compose\n\n**Frontend (Opcional):**\n\n- Node.js 22.20.0+ (versão especificada em `.nvmrc`)\n- pnpm 10+\n\n### 2. Configurar Provedor de LLM\n\nCopie o arquivo de exemplo e configure seu provedor:\n\n```bash\ncp .env.example .env\n```\n\nEdite o arquivo `.env` e escolha seu provedor:\n\n#### Opção A: Ollama (Local - Gratuito) ⭐ Padrão\n\n```bash\nLLM_PROVIDER=ollama\nOLLAMA_BASE_URL=http://localhost:11434\nOLLAMA_MODEL=qwen2.5:3b\nOLLAMA_EMBEDDING_MODEL=nomic-embed-text\n```\n\nDepois, inicie o Ollama:\n\nSe estiver usando o Ollama diretamente em seu S.O., lembre-se de executar o app.\n\nEm seguida, baixe os modelos através do terminal:\n\n```bash\n# Baixar os modelos (primeira vez)\nollama pull qwen2.5:3b\nollama pull nomic-embed-text\n```\n\nSe estiver usando via Docker, execute:\n\n```bash\n# Subir o container do Ollama\ndocker-compose up -d\n\n# Baixar os modelos (primeira vez)\ndocker exec -it ollama ollama pull qwen2.5:3b\ndocker exec -it ollama ollama pull nomic-embed-text\n```\n\n#### Opção B: OpenAI\n\n```bash\nLLM_PROVIDER=openai\nOPENAI_API_KEY=sk-...  # Sua chave da API OpenAI\nOPENAI_MODEL=gpt-4o-mini\nOPENAI_EMBEDDING_MODEL=text-embedding-3-small\n```\n\nObtenha sua chave em: \u003chttps://platform.openai.com/api-keys\u003e\n\n**Para instalar o suporte OpenAI:**\n\n```bash\nuv sync --extra openai\n```\n\n#### Opção C: Google Gemini\n\n```bash\nLLM_PROVIDER=gemini\nGEMINI_API_KEY=...  # Sua chave da API Gemini\nGEMINI_MODEL=gemini-1.5-flash\nGEMINI_EMBEDDING_MODEL=models/embedding-001\n```\n\nObtenha sua chave em: \u003chttps://makersuite.google.com/app/apikey\u003e\n\n**Para instalar o suporte Gemini:**\n\n```bash\nuv sync --extra google\n```\n\n#### Opção D: Anthropic (Claude)\n\n```bash\nLLM_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-...  # Sua chave da API Anthropic\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022\n\n# Para embeddings, use um dos outros provedores:\nEMBEDDING_PROVIDER=openai  # ou ollama\n```\n\nObtenha sua chave em: \u003chttps://console.anthropic.com/settings/keys\u003e\n\n**Para instalar o suporte Anthropic:**\n\n```bash\nuv sync --extra anthropic\n```\n\n#### Instalar Todos os Provedores\n\n```bash\nuv sync --extra all-providers\n```\n\n### 3. Configurar RAG\n\n```bash\n# 1. Adicionar PDFs na pasta pdfs/\n# Coloque manuais sobre reparos residenciais\n\n# 2. Processar PDFs e criar base de conhecimento\nuv run scripts/setup_rag.py\n\n# Isso irá criar o banco vetorial em chroma_db/\n```\n\n### 3. Instalar dependências\n\n```bash\nuv sync\n```\n\n### 4. Executar o agente\n\n#### Opção 1: CLI (Linha de Comando)\n\n```bash\n# Ativar o ambiente virtual (opcional, uv faz isso automaticamente)\nsource .venv/bin/activate\n\n# Executar o agente\nuv run agent.py\n```\n\n#### Opção 2: API REST (FastAPI)\n\n```bash\n# Desenvolvimento (com auto-reload)\nuv run uvicorn api.app:app --host 0.0.0.0 --port 5000 --reload\n\n# Produção (com múltiplos workers)\nuv run uvicorn api.app:app --host 0.0.0.0 --port 5000 --workers 4\n\n# Acessar documentação Swagger\n# http://localhost:5000/docs\n\n# Acessar documentação ReDoc\n# http://localhost:5000/redoc\n\n# Testar API (script automatizado)\n./test_api.sh\n\n# Ou testar manualmente\nuv run python test_api.py\n```\n\n\u003e 📚 **Guia completo:** Veja [GUIA_DEPLOY.md](docs/GUIA_DEPLOY.md) para mais opções de execução\n\n#### Opção 3: Frontend Web (React)\n\n```bash\n# Navegar para a pasta do frontend\ncd web\n\n# Instalar dependências (primeira vez)\npnpm install\n\n# Iniciar servidor de desenvolvimento\npnpm dev\n\n# Acessar interface web\n# http://localhost:5173\n```\n\n\u003e 💡 **Nota:** O frontend requer que a API REST esteja rodando na porta 5000\n\n#### Opção 4: Docker Compose (Deploy Completo)\n\n```bash\n# Iniciar todos os serviços (Ollama + API + OpenWebUI)\ndocker-compose up -d\n\n# Acessar OpenWebUI\n# http://localhost:8080\n```\n\nEm ambiente local, você pode usar a Pipe Function integrada ao OpenWebUI e desabilitar a autenticação para facilitar os testes.\n\nPara desabilitar autenticação, edite o arquivo `docker-compose.yml` e defina:\n\n```yaml\n  - WEBUI_AUTH=false\n```\n\nOs detalhes de uso de Pipe Function estão na documentação: [Integração com OpenWebUI](docs/INTEGRACAO_OPENWEBUI.md)\n\n## 💬 Exemplo de uso\n\nExemplo de interação com o agente via CLI:\n\n```bash\n============================================================\n🔧 CQL AI Agent - Assistente de Reparos Residenciais\n============================================================\n\nInicializando o agente...\n\n\n✅ Agente inicializado com sucesso!\n\n💡 Dica: O agente tentará ajudá-lo até 3 vezes antes de sugerir um profissional\n\n📝 Comandos: 'sair' para encerrar | 'novo' para um novo problema\n\n👤 Você: Como posso consertar uma torneira que está pingando?\n\n🤖 Agente: Para consertar uma torneira pingando, siga estes passos:\n\n1. **Feche o registro de água** da torneira\n2. Abra a torneira para liberar pressão restante\n3. Remova o cabo da torneira\n4. Desatarraxe a peça de vedação\n5. Substitua o anel de borracha (O-ring) ou a válvula\n6. Remonte tudo na ordem inversa\n7. Abra o registro novamente\n\n⚠️ **Segurança**: Se não se sentir confortável, chame um encanador!\n\nO problema foi resolvido? Responda com 'sim' ou 'não'.\n\n👤 Você: \n```\n\n## 🛠️ Tecnologias Utilizadas\n\n**Backend:**\n\n- **Python** - Linguagem de programação\n- **UV** - Gerenciador de pacotes e ambientes virtuais\n- **LangChain** - Framework para construção de aplicações com LLMs\n- **Múltiplos provedores LLM:**\n  - **LangChain-Ollama** - Modelos locais com Ollama\n  - **LangChain-OpenAI** - GPT-4, GPT-3.5-turbo (opcional)\n  - **LangChain-Google-GenAI** - Gemini 1.5 Flash/Pro (opcional)\n  - **LangChain-Anthropic** - Claude 3.5 Sonnet (opcional)\n- **Pydantic** - Validação de dados\n- **Docker** - Containerização\n- **FastAPI** - Framework web moderno para API REST\n- **Uvicorn** - Servidor ASGI de alta performance\n- **ChromaDB** - Banco de dados vetorial para RAG\n- **DuckDuckGo** - Busca web gratuita e privada\n\n**Frontend:**\n\n- **React** - Biblioteca para interfaces de usuário\n- **TypeScript** - JavaScript tipado\n- **Vite** - Build tool moderna\n- **EmotionCSS** - Styling CSS-in-JS\n- **Zustand** - State management\n- **React Query** - Data fetching e cache\n- **React Router** - Roteamento\n- **Vitest** - Framework de testes\n- **Biome.js** - Linting e formatação\n\n## 💡 Boas Práticas do Código\n\nEste projeto segue boas práticas de desenvolvimento:\n\n- ✅ **Código limpo**: Comentários apenas onde agregam valor real\n- ✅ **Type hints**: Tipagem estática com Pydantic\n- ✅ **Documentação**: Docstrings significativas em funções principais\n- ✅ **Modularização**: Código organizado em módulos (prompts, rag, tools, api, llm)\n- ✅ **Factory Pattern**: Abstração de provedores LLM através de factories\n- ✅ **Validação**: Validação de entrada/saída com Pydantic\n- ✅ **Logging**: Sistema de logs estruturado\n- ✅ **Testes automatizados**: Suíte completa com 136+ testes (unit + integration)\n- ✅ **Coverage**: Cobertura de código com pytest-cov\n- ✅ **CI/CD**: GitHub Actions com testes automáticos\n- ✅ **Containerização**: Deploy completo com Docker Compose\n\n## 🔌 Provedores de LLM Suportados\n\nO projeto suporta múltiplos provedores através de uma camada de abstração:\n\n### Arquitetura de Provedores\n\n```text\n┌──────────────────────────────────────────────┐\n│           RepairAgent / VectorStore          │\n└──────────────────┬───────────────────────────┘\n                   │\n         ┌─────────▼──────────┐\n         │   LLMFactory /     │\n         │ EmbeddingsFactory  │\n         └─────────┬──────────┘\n                   │\n     ┌─────────────┼─────────────┬─────────────┐\n     ▼             ▼             ▼             ▼\n┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐\n│ Ollama  │  │ OpenAI  │  │ Gemini  │  │Anthropic│\n│ (Local) │  │   API   │  │   API   │  │   API   │\n└─────────┘  └─────────┘  └─────────┘  └─────────┘\n```\n\n### Comparação de Provedores\n\n| Provedor | Custo | Privacidade | Velocidade | Qualidade | Embeddings |\n|----------|-------|-------------|------------|-----------|------------|\n| **Ollama** | 🟢 Gratuito | 🟢 100% Local | 🟡 Média | 🟢 Boa | ✅ Sim |\n| **OpenAI** | 🔴 Pago | 🔴 Cloud | 🟢 Rápida | 🟢 Excelente | ✅ Sim |\n| **Gemini** | 🟡 Free Tier | 🔴 Cloud | 🟢 Rápida | 🟢 Excelente | ✅ Sim |\n| **Anthropic** | 🔴 Pago | 🔴 Cloud | 🟢 Rápida | 🟢 Excelente | ❌ Não* |\n\n*\\* Anthropic não possui embeddings próprios. Use outro provedor para embeddings.*\n\n### Configuração via Variáveis de Ambiente\n\nToda a configuração é feita através do arquivo `.env`:\n\n```bash\n# Escolher provedor principal\nLLM_PROVIDER=ollama  # ou openai, gemini, anthropic\n\n# Embeddings podem usar provedor diferente\nEMBEDDING_PROVIDER=ollama  # ou openai, gemini\n\n# Configurações específicas do provedor escolhido\nOLLAMA_MODEL=qwen2.5:3b\nOPENAI_MODEL=gpt-4o-mini\nGEMINI_MODEL=gemini-1.5-flash\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022\n```\n\n### Custos Estimados (APIs Pagas)\n\n**OpenAI (Novembro 2024):**\n\n- GPT-4o-mini: ~$0.15/$0.60 por 1M tokens (input/output)\n- text-embedding-3-small: ~$0.02 por 1M tokens\n\n**Google Gemini:**\n\n- Gemini 1.5 Flash: Gratuito até 15 req/min\n- Acima: ~$0.35/$1.05 por 1M tokens\n\n**Anthropic:**\n\n- Claude 3.5 Sonnet: ~$3/$15 por 1M tokens\n\n💡 **Dica:** Para uso pessoal/experimental, Ollama (gratuito) ou Gemini Free Tier são ótimas opções!\n\n## 📁 Estrutura do Projeto\n\n```text\ncql-agent/\n├── agents/                    # 🤖 Agentes de IA\n│   ├── llm/                   # 🔌 Gerenciamento de provedores LLM\n│   │   ├── __init__.py        # Enums e configurações\n│   │   ├── factory.py         # Factory para criar LLMs\n│   │   └── embeddings_factory.py  # Factory para embeddings\n│   ├── repair_agent/          # Agente principal de reparos\n│   │   ├── __init__.py\n│   │   ├── agent.py           # Código principal do agente\n│   │   └── prompts/           # Módulo de prompts organizados\n│   │       ├── __init__.py\n│   │       ├── base.py        # Prompts base do sistema\n│   │       ├── states.py      # Estados da conversação\n│   │       ├── messages.py    # Templates de mensagens\n│   │       └── README.md\n│   ├── rag/                   # 📚 Módulo RAG (Retrieval-Augmented Generation)\n│   │   ├── __init__.py\n│   │   ├── loader.py          # Carrega e processa PDFs\n│   │   ├── vectorstore.py     # Gerencia ChromaDB\n│   │   ├── retriever.py       # Busca documentos semânticos\n│   │   └── pdfs/              # PDFs de exemplo\n│   └── tools/                 # 🔧 Ferramentas do agente\n│       ├── __init__.py\n│       └── web_search.py      # Busca web (DuckDuckGo)\n├── api/                       # 🌐 API REST\n│   ├── __init__.py\n│   ├── app.py                 # FastAPI + Swagger automático\n│   ├── gunicorn.conf.py       # Configuração Gunicorn (produção)\n│   ├── README.md\n│   ├── security/              # 🛡️ Módulo de segurança\n│   │   ├── __init__.py\n│   │   ├── sanitizer.py       # Sanitização de entrada\n│   │   ├── guardrails.py      # Validação de conteúdo com SpaCy\n│   │   ├── ner_repair.py      # Named Entity Recognition\n│   │   ├── context_analyzer.py  # Análise de contexto sintático\n│   │   ├── intention_analyzer.py  # Análise de intenção comunicativa\n│   │   └── README.md          # Documentação de segurança\n│   └── tests/                 # 🧪 Testes automatizados\n│       ├── conftest.py        # Fixtures compartilhadas\n│       ├── unit/              # Testes unitários\n│       │   └── security/      # Testes de segurança\n│       ├── integration/       # Testes de integração\n│       └── README.md          # Documentação de testes\n├── web/                       # 🎨 Frontend React\n│   ├── src/\n│   │   ├── components/        # Componentes reutilizáveis\n│   │   ├── containers/        # Componentes agregadores\n│   │   ├── pages/             # Páginas da aplicação\n│   │   ├── hooks/             # Custom React hooks\n│   │   ├── services/          # API clients\n│   │   ├── store/             # Zustand stores\n│   │   ├── styles/            # Theme e estilos globais\n│   │   └── test/              # Setup de testes\n│   ├── public/                # Arquivos estáticos\n│   ├── package.json\n│   ├── vite.config.ts\n│   ├── biome.json             # Configuração Biome.js\n│   └── README.md              # Documentação do frontend\n├── openwebui/                 # 🔌 Integração OpenWebUI\n│   └── pipe.py                # Pipe Function\n├── scripts/                   # 📜 Scripts auxiliares\n│   └── setup_rag.py           # Processa PDFs e cria base\n├── docs/                      # 📖 Documentação detalhada\n│   ├── GUIA_DEPLOY.md         # Deploy e execução (dev + prod)\n│   ├── GUIA_SWAGGER.md        # Documentação Swagger\n│   ├── INTEGRACAO_OPENWEBUI.md  # Integração com OpenWebUI\n│   └── QUICK_START_RAG.md     # Guia rápido RAG\n├── pdfs/                      # 📄 PDFs de conhecimento (adicionar aqui)\n│   └── README.md\n├── chroma_db/                 # 💾 Base vetorial (gerado automaticamente)\n│   └── chroma.sqlite3\n├── docker-compose.yml         # 🐳 Deploy completo (Ollama + API)\n├── Dockerfile                 # 🐳 Docker para API\n├── setup.sh                   # 🚀 Script de setup inicial\n├── test_api.sh                # 🧪 Script de testes da API\n├── test_security.sh           # 🛡️ Script de testes de segurança\n├── pyproject.toml             # 📦 Dependências Python\n└── README.md                  # 📘 Este arquivo\n```\n\n## 🛡️ Segurança\n\nO projeto implementa múltiplas camadas de segurança:\n\n### 1. Validação de Schema (Pydantic)\n\n- Mensagens: 1-4096 caracteres\n- Session ID: alfanumérico com _ e -\n- Validação rigorosa de tipos\n\n### 2. Sanitização de Entrada\n\n- Remove caracteres nulos (`\\x00`)\n- Detecta SQL injection\n- Detecta XSS (Cross-Site Scripting)\n- Detecta command injection\n- Previne DoS por repetição\n\n### 3. Guardrails de Conteúdo\n\n- Valida se mensagem é sobre reparos residenciais\n- Bloqueia conteúdo proibido (ilegal, adulto, jailbreak)\n- Score de relevância (0.0 a 1.0)\n- Validação adicional com LLM\n\n### 4. Tratamento de Erros\n\n- Retorna 400 Bad Request para entrada inválida\n- Não vaza detalhes internos\n- Logs detalhados para auditoria\n\n### Testes Automatizados\n\nO projeto possui uma suíte completa de testes organizados por tipo:\n\n```bash\n# Executar todos os testes\npytest\n\n# Testes unitários (136 testes)\npytest api/tests/unit/ -v\n\n# Testes de integração (API deve estar rodando)\npytest api/tests/integration/ -v\n\n# Testes com cobertura\npytest --cov=api --cov=agents --cov-report=html\n\n# Ver relatório de cobertura\nopen htmlcov/index.html\n```\n\n**Estrutura de testes:**\n- **Unit**: Testes de componentes isolados (sanitização, NER, análise de contexto, etc.)\n- **Integration**: Testes de fluxos completos da API e segurança\n\nVeja [api/tests/README.md](api/tests/README.md) para documentação completa.\n\n## 🐛 Troubleshooting\n\n### Erro de conexão com Ollama\n\n```bash\n❌ Erro: Connection refused\n```\n\n**Solução**: Certifique-se que o Ollama está rodando:\n\n```bash\ndocker-compose ps\ndocker-compose up -d\n```\n\n### Modelo não encontrado\n\n```bash\n❌ Erro: model 'qwen2.5:3b' not found\n```\n\n**Solução**: Baixe o modelo:\n\n```bash\ndocker exec -it ollama ollama pull qwen2.5:3b\n```\n\n## 📝 Licença\n\nEste projeto é de código aberto e está disponível sob a licença MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoliveiras%2Fcql-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwoliveiras%2Fcql-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoliveiras%2Fcql-agent/lists"}