Maia/README.md

# MAIA — Meeting AI Assistant

<p align="center">
  <img src="frontend/public/maia-logo.png" alt="MAIA Logo" width="120"/>
</p>

<p align="center">
  <strong>Grave, transcreva e analise suas reuniões com Inteligência Artificial</strong>
</p>

<p align="center">
  <a href="#-instalação">Instalação</a> •
  <a href="#-arquitetura">Arquitetura</a> •
  <a href="#-configuração">Configuração</a> •
  <a href="#-deploy">Deploy</a> •
  <a href="#-endpoints-da-api">API</a>
</p>

---

## 📖 Sobre o Projeto

O **MAIA** (Meeting AI Assistant) é uma plataforma desenvolvida pela **ASAP Telecom** para gravar, transcrever e analisar reuniões automaticamente usando Inteligência Artificial.

### ✨ Funcionalidades Principais

- 🎙️ **Gravação contínua** de reuniões via navegador (sem gaps, usando MediaRecorder API com timeslice)
- 📝 **Transcrição automática** com Whisper.cpp na GPU (modelo large-v3, alta precisão)
- 👥 **Diarização de speakers** — identifica quem falou o quê (SpeechBrain ECAPA-TDNN, ~85% precisão)
- 🤖 **Análise com IA** — resumo, pontos de ação e insights com LLM (deepseek-v3.1)
- 🔐 **Autenticação SSO** via Keycloak
- 📱 **PWA instalável** em Android e iOS
- 🔎 **Histórico** com busca de reuniões passadas
- 👤 **Identificação de speakers** por enrollment de voz

---

## 🏗️ Arquitetura

```
┌─────────────────────────────────────────────────────────────────┐
│                        CLIENTE                                  │
│   Browser / PWA (React 18 + Vite + TypeScript)                  │
│   MediaRecorder API → chunks de áudio → upload automático       │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTPS
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                  APP SERVER (5.0.0.181)                         │
│  ┌─────────────┐  ┌──────────────────┐  ┌──────────────────┐   │
│  │  Nginx :80  │  │ Backend API :8090 │  │ Diarization :5060│   │
│  │  (Frontend) │  │ FastAPI + Celery  │  │ FastAPI+SpeechBr.│   │
│  └─────────────┘  └────────┬─────────┘  └────────┬─────────┘   │
│                            │                      │             │
│  ┌─────────────┐  ┌────────▼─────────┐           │             │
│  │  PostgreSQL │  │  Redis (Celery)   │           │             │
│  └─────────────┘  └──────────────────┘           │             │
└────────────────────────────┬──────────────────────┼────────────┘
                             │                      │
              ┌──────────────▼──────┐    ┌──────────▼───────────┐
              │   GPU SERVER        │    │   LLM Server         │
              │ 10.100.16.13 :5003  │    │ asapai.asaptelecom.  │
              │ Whisper.cpp GPU     │    │ com.br/ollama        │
              │ AMD GPU, large-v3   │    │ deepseek-v3.1:671b   │
              └─────────────────────┘    └──────────────────────┘

              ┌─────────────────────┐
              │   Keycloak SSO      │
              │ Autenticação/Authz  │
              └─────────────────────┘
```

### 📁 Estrutura do Monorepo

```
Maia/
├── frontend/          # PWA React 18 + Vite + TypeScript
├── backend/           # API FastAPI + Celery + PostgreSQL
├── diarization/       # API de Diarização com SpeechBrain
├── README.md
└── CHANGELOG.md
```

---

## ⚙️ Requisitos

| Componente | Requisito |
|------------|-----------|
| Node.js    | 18+ |
| Python     | 3.11+ |
| PostgreSQL  | 14+ |
| Redis      | 7+ |
| GPU        | AMD/NVIDIA (para Whisper GPU) |
| RAM        | 16 GB mínimo (32 GB recomendado) |
| VRAM       | 8 GB mínimo para Whisper large-v3 |

---

## 🚀 Instalação

### Frontend

```bash
cd frontend
npm install
cp .env.example .env
# Edite o .env com as variáveis necessárias
npm run dev          # desenvolvimento
npm run build        # produção
```

### Backend

```bash
cd backend
python -m venv venv
source venv/bin/activate   # Linux/Mac
venv\Scripts\activate      # Windows
pip install -r requirements.txt
cp .env.example .env
# Edite o .env com as variáveis necessárias
alembic upgrade head       # aplicar migrações
uvicorn app.main:app --host 0.0.0.0 --port 8090
```

### Diarization API

```bash
cd diarization
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn main:app --host 0.0.0.0 --port 5060
```

---

## 🔧 Configuração

### Variáveis de Ambiente — Backend (`backend/.env`)

```env
DATABASE_URL=postgresql://user:password@localhost:5432/maia
REDIS_URL=redis://localhost:6379/0
KEYCLOAK_URL=https://seu-keycloak.exemplo.com
KEYCLOAK_REALM=seu-realm
KEYCLOAK_CLIENT_ID=maia-backend
OLLAMA_URL=https://llm.exemplo.com/ollama
OLLAMA_MODEL=deepseek-v3.1:671b-cloud
WHISPER_URL=http://gpu-server:5003
```

### Variáveis de Ambiente — Diarization API (`diarization/.env`)

```env
WHISPER_ORIGIN=http://gpu-server:5003
VOICE_DB_PATH=/data/voice_db
SPEAKER_CONFIDENCE_THRESHOLD=0.75
HF_TOKEN=seu_token_huggingface
SPEECHBRAIN_CACHE=/data/speechbrain_cache
```

### Variáveis de Ambiente — Frontend (`frontend/.env`)

```env
VITE_API_URL=http://seu-backend:8090
VITE_KEYCLOAK_URL=https://seu-keycloak.exemplo.com
VITE_KEYCLOAK_REALM=seu-realm
VITE_KEYCLOAK_CLIENT_ID=maia-frontend
```

---

## 🐳 Deploy

### Com Podman/Docker Compose

```bash
# Na raiz do projeto
podman-compose up -d
```

### Deploy Manual

#### Backend (systemd)
```bash
# /etc/systemd/system/maia-backend.service
[Unit]
Description=MAIA Backend API
After=network.target postgresql.service redis.service

[Service]
User=maia
WorkingDirectory=/opt/Backend/meeting-assistant-api
ExecStart=/opt/Backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8090
Restart=always

[Install]
WantedBy=multi-user.target
```

#### Celery Worker
```bash
celery -A app.celery_app worker --loglevel=info -Q transcription,analysis
```

#### Frontend (Nginx)
```nginx
server {
    listen 80;
    root /var/www/maia;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://localhost:8090/;
    }
}
```

---

## 🔌 Endpoints Principais da API

### Backend API (`http://server:8090`)

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/meetings/` | Criar nova reunião |
| `GET` | `/meetings/` | Listar reuniões |
| `GET` | `/meetings/{id}` | Detalhes da reunião |
| `DELETE` | `/meetings/{id}` | Deletar reunião |
| `POST` | `/meetings/{id}/upload-chunk` | Upload de chunk de áudio |
| `POST` | `/meetings/{id}/finalize` | Finalizar e processar reunião |
| `GET` | `/meetings/{id}/transcript` | Transcrição completa |
| `GET` | `/meetings/{id}/analysis` | Análise da IA |
| `POST` | `/speakers/enroll` | Enrollar speaker com voz |
| `GET` | `/speakers/` | Listar speakers |
| `GET` | `/admin/users` | (Admin) Listar usuários |

### Diarization API (`http://server:5060`)

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/transcribe` | Transcrever + diarizar áudio |
| `POST` | `/enroll` | Enrollar voz de speaker |
| `GET` | `/speakers` | Listar speakers cadastrados |
| `DELETE` | `/speakers/{name}` | Remover speaker |
| `GET` | `/health` | Health check |

---

## 🛠️ Tecnologias

### Frontend
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| React | 18 | Framework UI |
| Vite | 5 | Build tool |
| TypeScript | 5 | Tipagem estática |
| Zustand | 4 | Gerenciamento de estado |
| Axios | 1.x | Cliente HTTP |
| Workbox | 7 | PWA / Service Worker |
| MediaRecorder API | — | Gravação de áudio |

### Backend
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| FastAPI | 0.110+ | Framework API |
| SQLAlchemy | 2.x | ORM |
| Alembic | 1.x | Migrações de banco |
| PostgreSQL | 14+ | Banco de dados |
| Celery | 5.x | Processamento assíncrono |
| Redis | 7+ | Broker/Cache |
| httpx | 0.27+ | Cliente HTTP assíncrono |

### Diarização & IA
| Tecnologia | Uso |
|------------|-----|
| Whisper.cpp | Transcrição de áudio (GPU) |
| SpeechBrain ECAPA-TDNN | Diarização de speakers |
| pyannote.audio | Diarização (fallback) |
| librosa | Processamento de áudio |
| deepseek-v3.1 | Análise e resumo de reuniões |

### Infraestrutura
| Tecnologia | Uso |
|------------|-----|
| Podman | Containerização |
| Nginx | Reverse proxy / Servir frontend |
| systemd | Gerenciamento de serviços |
| Keycloak | SSO / Autenticação |

---

## 📄 Licença

Proprietário — ASAP Telecom. Todos os direitos reservados.

---

<p align="center">Desenvolvido com ❤️ pela equipe ASAP Telecom</p>