chore(ai): run Ollama outside Docker

.env.example

@@ -25,6 +25,8 @@ N8N_API_KEY=
 # --- Runtime de IA e Embeddings Locais (Ollama) ---
 OLLAMA_PORT=11434
 OLLAMA_BASE_URL=http://localhost:11434
+# URL usada pelo ai-service quando ele é executado dentro do Docker Compose.
+OLLAMA_DOCKER_BASE_URL=http://host.docker.internal:11434
 # Modelos recomendados no PRD (Qwen 2.5 / Llama 3.1 para LLM, bge-m3 para embeddings)
 OLLAMA_LLM_MODEL=qwen2.5:1.5b
 OLLAMA_NUM_PREDICT=1024

AGENTS.md

@@ -117,7 +117,7 @@ The application is structured into conteinerized, local microservices:
 | **Frontend** | React 19 / Vite / TS | `5173` | SPA for POs (requirements hierarchy, quality indicators, acervo search, chat). |
 | **AI Service** | Python 3.11+ / FastAPI | `8000` | Chunking source of truth, RAG retrieval, `bge-m3` embedding calculation, PRO4TECH Harness. |
 | **n8n** | n8n `latest` | `5678` | Asynchronous file ingestion workflow (`/files`), GitOps versioned via `n8n-local-sync`. |
-| **Ollama** | Ollama Container | `11434` | Local LLM (`qwen2.5:1.5b`) and Embedding (`bge-m3`) runtime. |
+| **Ollama** | Host runtime | `11434` | Local LLM (`qwen2.5:1.5b`) and Embedding (`bge-m3`) runtime, executed outside Docker. |
 
 ---
 
@@ -229,10 +229,10 @@ cp .env.example .env
 # 2. Start core docker services
 docker compose up -d
 
-# 3. Pull Ollama models (optional)
+# 3. Start the optional AI service and pull host Ollama models separately
 docker compose --profile local-ai up -d
-docker compose --profile local-ai exec ollama ollama pull bge-m3
-docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b
+ollama pull bge-m3
+ollama pull qwen2.5:1.5b
 ```
 
 ### Verification & Testing Commands:

docker-compose.yml

@@ -47,26 +47,6 @@ services:
     networks:
       - sinapse-network
 
-  ollama:
-    profiles: [local-ai]
-    image: ollama/ollama:latest
-    container_name: sinapse-ollama
-    restart: unless-stopped
-    ports:
-      - "${OLLAMA_PORT:-11434}:11434"
-    volumes:
-      - ollama_data:/root/.ollama
-    environment:
-      - OLLAMA_KEEP_ALIVE=${OLLAMA_KEEP_ALIVE:-24h}
-    healthcheck:
-      test: ["CMD-SHELL", "ollama list || exit 1"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 10s
-    networks:
-      - sinapse-network
-
   backend:
     build:
       context: .
@@ -108,12 +88,14 @@ services:
     restart: unless-stopped
     ports:
       - "${AI_SERVICE_PORT:-8000}:8000"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     volumes:
       - repo_analysis_data:/app/workspace_analyzer
     environment:
       - AI_SERVICE_PORT=8000
       - AI_SERVICE_HOST=0.0.0.0
-      - OLLAMA_BASE_URL=http://ollama:11434
+      - OLLAMA_BASE_URL=${OLLAMA_DOCKER_BASE_URL:-http://host.docker.internal:11434}
       - OLLAMA_LLM_MODEL=${OLLAMA_LLM_MODEL:-qwen2.5:1.5b}
       - OLLAMA_NUM_PREDICT=${OLLAMA_NUM_PREDICT:-1024}
       - OLLAMA_NUM_CTX=${OLLAMA_NUM_CTX:-8192}
@@ -131,8 +113,6 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
-      ollama:
-        condition: service_healthy
     networks:
       - sinapse-network
 
@@ -152,8 +132,6 @@ volumes:
     name: sinapse_postgres_data
   n8n_data:
     name: sinapse_n8n_data
-  ollama_data:
-    name: sinapse_ollama_data
   documents_data:
     name: sinapse_documents_data
   repo_analysis_data:

docs/Architecture/README.md

@@ -22,7 +22,7 @@ flowchart LR
 | Backend | `backend/`, Express + TypeScript | API, sessões, autorização por perfil, validações, regras de domínio, acesso ao Postgres, storage de documentos e histórico de conversa. |
 | Banco | `database/init.sql` + `database/migrations/`, PostgreSQL 16 e extensão pgvector | Persistência do domínio, índices e estruturas para conteúdo de conhecimento. O backend aplica migrations pendentes ao iniciar o container. |
 | Serviço Python | `ai-service/`, FastAPI | Endpoints de saúde, chunking, embeddings, consulta RAG e execução/consulta de análises de repositório. É executado no perfil Docker `local-ai`. |
-| Ollama | container opcional | Provedor local de modelos de embedding e geração. Os modelos são baixados pelo operador; não vêm no build da imagem. |
+| Ollama | runtime no host | Provedor local de modelos de embedding e geração, executado fora do Docker para melhor acesso aos recursos de CPU/GPU. Os modelos são baixados pelo operador; não vêm no build da imagem. |
 | n8n | container padrão, integrações opcionais | Consumidor de eventos/integrador. O evento de remoção pode ser enviado por `DOCUMENT_EVENTS_WEBHOOK_URL`; sem URL, é retido e reprocessado. |
 
 **Diretriz de dados:** o backend é a autoridade de negócio para autenticação, regras, autorização e mutações do domínio. Os clientes web e modelos não devem contornar essas validações. Configure acesso ao PostgreSQL apenas para serviços confiáveis na rede privada.

docs/SETUP_GUIDE.md

@@ -39,15 +39,29 @@ O primeiro acesso à aplicação começa pela tela de autenticação. Cadastre u
 
 ### Habilitar IA local (opcional)
 
-Ollama e o serviço Python usam o perfil `local-ai`:
+O Ollama roda diretamente no host, fora do Docker. Essa configuração evita a camada adicional de virtualização do runtime de modelos e permite que ele use melhor os recursos de CPU/GPU disponíveis na máquina.
+
+Instale o Ollama pelo [site oficial](https://ollama.com/download) e confirme que o comando está disponível:
+
+```bash
+ollama --version
+ollama serve
+```
+
+Em outro terminal, baixe os modelos usados pelo projeto:
+
+```bash
+ollama pull bge-m3
+ollama pull qwen2.5:1.5b
+```
+
+Com o Ollama em execução no host, inicie o serviço Python pelo perfil `local-ai`:
 
 ```bash
 docker compose --profile local-ai up --build -d
-docker compose --profile local-ai exec ollama ollama pull bge-m3
-docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b
 ```
 
-Os modelos são baixados separadamente e ocupam espaço significativo. O healthcheck do container Ollama confirma que o serviço iniciou, não que cada modelo já foi baixado. A integração de IA deve ser validada no fluxo desejado; o app possui comportamento de fallback quando o assistente está indisponível.
+O `ai-service` containerizado acessa o Ollama por `http://host.docker.internal:11434` (ou pelo valor de `OLLAMA_DOCKER_BASE_URL`). Para executar o serviço Python no próprio host, use `OLLAMA_BASE_URL=http://localhost:11434`. Os modelos são baixados separadamente e ocupam espaço significativo. Valide a integração no fluxo desejado; o app possui comportamento de fallback quando o assistente está indisponível.
 
 ## Opção B — Frontend/backend no host
 
@@ -60,7 +74,7 @@ cp .env.example .env
 docker compose up -d postgres
 ```
 
-Se também precisar das integrações locais, inicie `n8n` ou o perfil `local-ai` separadamente. Os containers acessam PostgreSQL pelo hostname `postgres` na porta `5432`; processos no host usam `localhost` e a porta publicada `POSTGRES_PORT` (padrão `55432`).
+Se também precisar das integrações locais, inicie `n8n` ou o perfil `local-ai` separadamente. Os containers acessam PostgreSQL pelo hostname `postgres` na porta `5432`; processos no host usam `localhost` e a porta publicada `POSTGRES_PORT` (padrão `55432`). O Ollama permanece no host e deve estar iniciado antes do `ai-service`.
 
 ### 2. Instale dependências e aplique as migrations
 
@@ -122,7 +136,8 @@ O serviço lê sua configuração a partir de `ai-service/config.py`. O serviço
 | `N8N_PORT` | `5678` | Porta publicada do n8n. |
 | `DOCUMENT_MAX_SIZE_MB` | `20` | Tamanho máximo de upload aceito pela API. |
 | `DOCUMENT_EVENTS_WEBHOOK_URL` | vazio | Destino HTTP dos eventos de remoção de documento. Sem consumidor configurado, o evento permanece pendente e é tentado novamente. |
-| `OLLAMA_PORT` | `11434` | Porta publicada quando o perfil `local-ai` está ativo. |
+| `OLLAMA_PORT` | `11434` | Porta do Ollama executado no host. |
+| `OLLAMA_DOCKER_BASE_URL` | `http://host.docker.internal:11434` | URL do Ollama vista pelo `ai-service` dentro do Docker. |
 | `OLLAMA_LLM_MODEL` | `qwen2.5:1.5b` | Modelo de geração local. |
 | `OLLAMA_EMBEDDING_MODEL` | `bge-m3` | Modelo de embedding local. |
 
@@ -184,7 +199,7 @@ docker compose config --quiet
 - **Alteração de schema não aparece:** confira `_schema_migrations` e os logs do backend. Criar novamente um container não reaplica `init.sql` num volume já existente; crie uma migration versionada.
 - **Upload falha:** verifique o healthcheck `/health`, espaço no volume de documentos e o limite configurado em `DOCUMENT_MAX_SIZE_MB`.
 - **Busca ou chat sem trechos:** a busca depende de conteúdo/chunks disponíveis e isolados por projeto; um arquivo armazenado não implica, por si só, que foi extraído e indexado.
-- **IA indisponível:** confirme perfil `local-ai`, healthchecks, URLs entre containers, download dos modelos e configuração Ollama.
+- **IA indisponível:** confirme que o Ollama está em execução no host, teste `ollama list`, verifique o download dos modelos e confirme `OLLAMA_BASE_URL`. Para o `ai-service` em Docker, o endereço padrão é `http://host.docker.internal:11434`.
 
 ## Documentos relacionados