VeriSound

Editoras, gravadoras independentes e plataformas de streaming perdem milhões de dólares em royalties não distribuídos porque os metadados das faixas não batem com os contratos ou com as exigências dos órgãos de controle. Auditar isso manualmente demanda dezenas de horas.

Rodando localmente

O backend usa UV com Python 3.12 para manter compatibilidade com as dependências de IA:

uv sync --project backend --dev --python 3.12
uv run --project backend uvicorn app.main:app --reload

Abra http://127.0.0.1:8000/docs para a API. O frontend Vue fica em frontend/ e usa o proxy Vite para encaminhar /api ao backend:

cd frontend
npm.cmd install
npm.cmd run dev

O frontend requer Node.js LTS. Em PowerShell, use npm.cmd caso a política de execução bloqueie npm.ps1.

As bibliotecas CrewAI, LangChain e ChromaDB estão disponíveis na extra opcional ai. Algumas versões exigem compiladores nativos no Windows:

uv sync --project backend --extra ai --dev --python 3.12

Para validar o MVP do backend:

uv run --project backend pytest

Entradas e saídas do produto

Chroma Cloud (RAG) — operação e monitoramento

O VeriSound inclui integração RAG opcional usando Chroma (ChromaDB). Por padrão o projeto cria um vectorstore local em backend/.chroma. Para usar Chroma Cloud em vez do armazenamento local, defina as variáveis no .env da raiz:

AI_ENABLED=true
OPENROUTER_API_KEY=seu_openrouter_api_key
OPENROUTER_MODEL=openai/gpt-4o-mini
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
CHROMA_HOST=api.trychroma.com
CHROMA_API_KEY=seu_chroma_api_key
CHROMA_TENANT=seu_chroma_tenant
CHROMA_DATABASE=VeriSound

Com essas variáveis o backend tentará usar o SDK Chroma Cloud (recomendado). Se o SDK não estiver instalado ou as variáveis não estiverem presentes, o sistema faz fallback para o Chroma local (diretório backend/.chroma).

Como o backend cria/atualiza coleções

• Ao executar POST /api/audits com use_ai=true e com AI_ENABLED=true, o serviço:
  1. Chunka o texto do contrato (por padrão chunk_size=800, overlap=120).
  2. Gera embeddings por chunk (modelo configurado em OPENROUTER_MODEL / embeddings model configurável).
  3. Persiste os chunks como documentos na coleção Chroma (cloud ou local).

Monitoramento e controle de custos — recomendações práticas

1. Entenda a métrica que custa: embeddings por chunk. Cada chunk gera 1 embedding. Estime: embeddings ≈ sum(ceil(len(document)/chunk_size)).
2. Preferir chunk_size maior reduz número de embeddings, mas reduz precisão do RAG. Ajuste entre 400–1200 dependendo do contrato médio.
3. Batch embeddings quando possível (SDK/cliente permite batch) — reduz latência e pode ser mais econômico.
4. Escolha de modelo de embeddings impacta custo: modelos maiores (mais custosos) melhoram qualidade, mas nem sempre são necessários para contratos curtos.
5. Use deduplicação por metadata (GroupBy) para evitar múltiplos chunks da mesma seção aparecerem repetidos nas respostas.
6. Defina retenção e políticas de limpeza: arquivos antigos podem ser removidos ou exportados para arquivamento offline.
7. Use ambientes separados (staging/prod) e coleções por tenant (CHROMA_TENANT/CHROMA_DATABASE) para controlar uso e auditing.
8. Configure alertas de uso no painel Chroma Cloud (billing/usage) e limite de quota quando disponível.
9. Para documentos muito longos: dividir por seções (line-based chunking) e incluir source_id + chunk_index no metadata para GroupBy e dedupe.

Comandos rápidos de verificação

• Testar o health da API (backend):

Invoke-RestMethod http://127.0.0.1:8000/health

• Executar auditoria e acionar a indexação (use_ai checkbox no frontend ou use_ai=true no form-data):

curl -X POST http://127.0.0.1:8000/api/audits -F "contract=@contrato.txt" -F "catalog=@catalogo.csv" -F "use_ai=true"

• Verificar se o diretório local foi criado (fallback):

Test-Path .\backend\.chroma
Get-ChildItem -Recurse .\backend\.chroma

Migração local → Chroma Cloud (visão geral)

1. Criar credenciais CHROMA_* no .env (CHROMA_HOST, CHROMA_API_KEY, CHROMA_TENANT, CHROMA_DATABASE).
2. Rodar um script de migração que: abre o vectorstore local, lê documentos/chunks e faz upsert na coleção Cloud via SDK, preservando metadados (source_id, chunk_index).
3. Verificar contagem de vetores na cloud e testar buscas. Remover local ou mantê-lo como backup.

Observações finais

• O Chroma Cloud oferece funcionalidades extras (sparse vectors, RRF, GroupBy, schemas) — para projetos de produção, ajuste a schema e use hybrid search.
• Se precisar, eu posso gerar o script de migração automático e uma rotina de verificação pós-migração (ver passo 1 no plano posterior).

Entradas

A auditoria recebe dois arquivos obrigatórios pelo endpoint POST /api/audits:

1. Contrato de direitos

   • Formatos aceitos: .pdf ou .txt.
   • Deve conter as faixas, compositores e respectivos splits.
   • Formato textual esperado:

   Aurora | Ana Silva, Bruno Lima | split: 100%
   Maré: Carla Souza | split: 80%
   
   

2. Catálogo musical

   • Formato aceito: .csv.
   • Pode usar vírgula ou ponto e vírgula como separador.
   • Deve conter uma coluna de título, com um destes nomes: title, titulo, track ou faixa.
   • Pode conter também: isrc, composers, compositores, writers ou autores