C🦎langoMagia

Assistente Multimodal – Tecnologias utilizadas

Backend do assistente multimodal desenvolvido em Python. O presente documento fornece uma visão geral do projeto e o passo a passo completo para qualquer pessoa configurar o ambiente do zero, incluindo a instalação das dependências de IA (torch, diffusers, transformers), com foco em versões estáveis e menores.

---

📦 Visão geral

Esse projeto implementa a base de um Back-End multimodal e do Front-End capaz de lidar com:

• Processamento de texto (via Transformers)
• Geração e manipulação de imagens (via Diffusers)
• Orquestração multimodal (decisão inteligente entre texto, imagem ou ambos)
• Lógica central da aplicação (validações, filtros, utilitários)
• API REST (via FastAPI)

A arquitetura foi organizada para manter os módulos desacoplados e facilitar expansão, testes e integração com uma API.

---

🌐 FrontEnd

O front do projeto está na pasta front/ e foi desenvolvido em React (Vite).

Instalar dependências

cd front
npm install

Rodar em desenvolvimento

cd front
npm run dev

---

🎥 Demonstração (vídeo)

Em breve: link do vídeo demonstrando o site rodando.

---

🗂 Estrutura do projeto

backend/
├── api/        # API REST (FastAPI)
├── core/       # Lógica central: validações, filtros, orchestrator
├── text/       # Pipeline de texto (Transformers)
├── image/      # Pipeline de imagem (Diffusers)
├── dtos/       # Data Transfer Objects (Pydantic)
├── tests/      # Testes unitários e manuais
└── .venv/      # Ambiente virtual Python

Cada pasta é independente e possui seu próprio __init__.py para permitir importação modular.

---

🔧 1. Pré-requisitos

• Python 3.12+
• pip atualizado
• venv habilitado (python3.12-venv no Ubuntu)
• Git

---

🚀 2. Configuração do ambiente (do zero)

2.1 Clonar o repositório

git clone <https://gitlab.com/jala-university1/cohort-2/PT.CSAI-353.GA.T2.25.M2/SB/calangomagia/backend.git>
cd backend

---

2.2 Criar o ambiente virtual

python3 -m venv .venv
source .venv/bin/activate

O terminal deve exibir:

(.venv)

---

⚙️ 3. Instalação das dependências

3.1 Instalação rápida (recomendado)

pip install -r requirements.txt

⚠️ Nota: O PyTorch no requirements.txt é a versão CPU. Se você tem GPU NVIDIA, veja a seção 3.2.

---

3.2 Instalação manual (alternativa)

Se preferir instalar manualmente ou precisar de versões específicas:

PyTorch (CPU)

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

PyTorch (GPU NVIDIA com CUDA)

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

HuggingFace (Transformers + Diffusers)

pip install diffusers transformers accelerate

Dependências auxiliares

pip install fastapi uvicorn pillow numpy python-dotenv pydantic nltk pytest

---

3.3 Recursos do NLTK

O módulo de pré-processamento de texto usa NLTK. Na primeira execução, os recursos são baixados automaticamente, mas você pode baixar manualmente:

python -c "import nltk; nltk.download('punkt'); nltk.download('punkt_tab'); nltk.download('stopwords')"

---

🧪 4. Testar instalação

4.1 Verificar dependências

python -c "import torch, transformers, diffusers, nltk; print('OK')"

Se imprimir OK, o ambiente está configurado.

4.2 Rodar testes unitários

pytest tests/ -v

4.3 Rodar testes manuais

export PYTHONPATH=$(pwd)

# Teste do filtro de segurança
python tests/manual/test_safety_filter.py

# Teste do orchestrator multimodal
python tests/manual/test_orchestrator.py

---

🖥️ 5. Rodar a API

uvicorn api.main:app --reload --port 8008

A API estará disponível em: http://localhost:8008

Documentação interativa (Swagger): http://localhost:8008/docs

---

🛡️ 6. Filtro ético de prompts

O projeto possui um módulo de segurança (core/safety.py) que valida prompts antes do processamento. O filtro bloqueia automaticamente conteúdo inadequado.

6.1 Categorias bloqueadas

Categoria	Descrição
Sexual	Nudez, pornografia, conteúdo erótico
Violência	Gore, tortura, massacre, conteúdo violento
Dados sensíveis	CPF, senhas, dados bancários

6.2 Como usar no código

from core.safety import validate_prompt

is_safe, error_msg = validate_prompt(prompt)

if not is_safe:
    raise ValueError(error_msg)

6.3 Onde já está integrado

• api/main.py → rotas /generate e /generate-image
• image/image_generator.py → método generate_image()

6.4 Adicionar novas palavras bloqueadas

Editar as listas no arquivo core/safety.py:

BLOCKED_SEXUAL = ["nude", "nua", ...]
BLOCKED_VIOLENCE = ["gore", "tortura", ...]
BLOCKED_SENSITIVE = ["cpf", "senha", ...]

6.5 Testar o filtro

pytest tests/core/test_safety.py -v

---

🎭 7. Orquestrador Multimodal

O projeto inclui um MultimodalOrchestrator (core/orchestrator.py) que decide automaticamente entre geração de texto, imagem ou ambos.

7.1 Como funciona

O orchestrator analisa o prompt e detecta a intenção do usuário:

Intenção	Exemplos de triggers
Texto	"escreva", "explique", "conte", "descreva"
Imagem	"imagem", "desenhe", "ilustração", "crie uma imagem"
Multimodal	"mostre e explique", "imagem e texto"

7.2 Como usar no código

from core.orchestrator import MultimodalOrchestrator, IntentType

# Inicializar (após carregar os geradores)
orchestrator = MultimodalOrchestrator(
    text_generator=text_generator,
    image_generator=image_generator,
    preprocessor=preprocessor
)

# Orquestrar automaticamente
result = orchestrator.orchestrate(prompt="Desenhe um gato")

print(result.intent)        # IntentType.IMAGE_ONLY
print(result.image_base64)  # Imagem em base64
print(result.text_response) # None (só pediu imagem)

7.3 Fallback automático

Em caso de erro, o orchestrator tenta automaticamente gerar apenas texto como fallback.

---

👥 Time

👩🏻‍💻 Gabriela Diniz Santos;

👨🏻‍💻 Gelsinha da Silva Alves;

👨🏻‍💻 João do Nascimento.