AI面试代理

🧠 Projeto: AI Interview Agent — Executável Local com MCP e ElevenLabs

Versão: 1.0 Stack: Python + Palabra AI + OpenAI GPT-4 / Local LLM + ElevenLabs TTS + MCP Server Deploy: Docker (recomendado) + Executável (PyInstaller)

⚠️ Windows: Use Docker para evitar problemas com uvloop (veja seção 4)

1. Objetivo

Criar um agente local inteligente que:

1. Ouve e traduz fala em tempo real via SDK Palabra AI.
2. Envia o conteúdo traduzido a um MCP server (executando um modelo LLM local ou remoto).
3. O agente gera uma resposta adequada em inglês técnico, com tom profissional e conciso.
4. A resposta é falada em voz natural via ElevenLabs TTS.
5. Todo o sistema pode ser empacotado em um executável Python, isolado por Docker, para uso local.

2. Arquitetura

Microfone → Palabra AI → MCP Server → LLM (GPT-4/Ollama) → ElevenLabs → Alto-falante

3. Componentes Técnicos

3.1 Palabra AI (Speech-to-Text + Translation) Captura áudio e traduz em tempo real usando SDK Python.

3.2 MCP Server (Middleware Cognitivo) Responsável por receber a transcrição, gerar contexto e enviar ao LLM e TTS.

3.3 LLM Integration Modelos compatíveis:

• Online: GPT-4o, GPT-4o-mini (OpenAI)
• Offline: Ollama (Mistral, Llama3)

3.4 ElevenLabs (Text-to-Speech) Transforma texto em fala natural.

3.5 Empacotamento como Executável Usar PyInstaller para gerar .exe: pyinstaller --onefile src/main.py

4. Deploy via Docker (RECOMENDADO para Windows)

⚠️ IMPORTANTE: uvloop não funciona no Windows nativamente. ✅ SOLUÇÃO: Use Docker! O container roda Linux e uvloop funciona perfeitamente.

Estrutura do projeto: /ai_interview_agent ├── docker-compose.yml ├── Dockerfile ├── requirements-docker.txt (com uvloop para Linux) ├── requirements.txt (sem uvloop para Windows) ├── src/ │ ├── main.py │ ├── llm.py │ ├── mcp_server.py │ ├── palabra_bridge.py │ └── tts_elevenlabs.py └── .env

🐳 Guia de Uso com Docker

Por que usar Docker?

✅ uvloop funciona perfeitamente - Docker roda Linux, então todas as dependências funcionam
✅ Ambiente isolado - Não polui seu sistema Windows
✅ Fácil de configurar - Uma linha de comando e está pronto
✅ Reproduzível - Mesmo ambiente em qualquer máquina

📋 Pré-requisitos

• Docker Desktop instalado e rodando
• Arquivo .env configurado (veja .env.example)

🚀 Como Usar

1. Configurar variáveis de ambiente

Copie o arquivo de exemplo e preencha com suas chaves:

cp .env.example .env

Edite o .env com suas chaves de API:

• PALABRA_API_KEY
• OPENAI_API_KEY (ou configure Ollama)
• ELEVENLABS_API_KEY

2. Build da imagem Docker

docker-compose build

Ou usando Docker diretamente:

docker build -t ai-interview-agent .

3. Executar o container

docker-compose up

Ou em modo detached (background):

docker-compose up -d

4. Ver logs

docker-compose logs -f

5. Parar o container

docker-compose down

6. Ver todos os container que estão rodando

docker ps

📦 Como Instalar Dependências no Container Docker

Existem 3 formas de instalar dependências no container:

1. ⚡ Instalação Temporária (Container Rodando)

Para testar uma dependência rapidamente sem rebuild:

# Instalar uma dependência específica
docker-compose exec ai-interview-agent pip install nome-do-pacote

# Exemplo: instalar requests
docker-compose exec ai-interview-agent pip install requests

# Instalar múltiplas dependências
docker-compose exec ai-interview-agent pip install requests beautifulsoup4

⚠️ Atenção: Essas instalações são temporárias e serão perdidas se o container for recriado!

2. ✅ Instalação Permanente (Recomendado)

Para adicionar dependências permanentemente ao projeto:

Passo 1: Adicionar ao requirements-docker.txt

Edite o arquivo requirements-docker.txt e adicione a nova dependência:

# Sua nova dependência
requests>=2.31.0
beautifulsoup4>=4.12.0

Passo 2: Rebuild do container

# Parar o container atual
docker-compose down

# Rebuild com as novas dependências
docker-compose up --build -d

# Ver logs para confirmar
docker-compose logs -f

🎯 Recomendação

• Para desenvolvimento/testes rápidos: Use método 1 (temporário)
• Para dependências do projeto: Use método 2 (permanente)
• Para explorar/testar: Use método 3 (bash interativo)

⚠️ Importante

• Dependências instaladas temporariamente serão perdidas ao recriar o container
• Sempre adicione dependências importantes ao requirements-docker.txt
• Faça commit do requirements-docker.txt atualizado no Git

📦 Como Criar Venv no Container

Opção 1: Criar e Usar Manualmente

# Entrar no container
docker-compose exec ai-interview-agent bash

# Dentro do container, criar o venv
python -m venv /app/venv

# Ativar o venv
source /app/venv/bin/activate

# Instalar dependências no venv
pip install -r requirements-docker.txt

# Verificar que está usando o venv
which python
# Deve mostrar: /app/venv/bin/python

# Sair do container
exit

Opção 2: Criar no Dockerfile (Permanente)

Se você quer que o venv seja criado automaticamente:

# No Dockerfile, adicione:
RUN python -m venv /app/venv
ENV PATH="/app/venv/bin:$PATH"

Opção 3: Script de Setup

Criar um script que configura o venv:

#!/bin/bash
# setup-venv.sh
python -m venv /app/venv
source /app/venv/bin/activate
pip install -r requirements-docker.txt

🎯 Recomendações para Docker

✅ Melhor Prática: Usar o Python do Container Diretamente

Para a maioria dos casos, é melhor usar o Python do container diretamente:

# No Dockerfile
RUN pip install --no-cache-dir -r requirements.txt

5. Segurança

• Chaves de API em .env
• MCP local (porta 5050)
• Suporte offline via Whisper + Ollama + Piper TTS

6. Workflow

1. Microfone inicia captura
2. Palabra traduz áudio
3. MCP recebe texto e envia ao LLM
4. LLM gera resposta
5. ElevenLabs transforma texto em fala
6. Resposta é falada ou exibida

7. Extensões Futuras

• Sugestões múltiplas de resposta
• Cache contextual
• Controle por voz ("repeat", "shorter")
• Modo de prática com simulação
• Interface GUI (React/Tkinter)

8. Conclusão

Sistema local, modular e extensível. Combina tradução, raciocínio e fala em tempo real. Ideal para entrevistas em inglês com suporte de IA.