Music-Analyst-AI

Aplicação paralela em C com MPI para processar o conjunto de dados Spotify Million Song Dataset. O objetivo é acelerar tarefas de análise exploratória das letras das músicas e fornecer integração com um modelo local de linguagem para classificação de sentimento.

Funcionalidades

1. Contagem de palavras – o processo mestre separa o CSV original em colunas independentes (artistas e letras) e cada processo MPI analisa uma partição do arquivo de letras, mantendo contagens locais que posteriormente são agregadas para produzir o ranking global das palavras mais frequentes.
2. Artistas com mais músicas – em paralelo, os processos também percorrem o arquivo de artistas gerado na etapa anterior e reportam os artistas mais prolíficos.
3. Classificação de sentimento – script auxiliar em Python permite enviar as letras para um modelo local (por exemplo, via Ollama) e sumarizar o total de músicas Positivas, Neutras e Negativas.
4. Métricas de desempenho – o executável MPI exporta métricas de tempo de processamento e comunicação para análise comparativa entre diferentes números de processos.
5. Contagem serial detalhada – script independente permite gerar, sem uso de MPI, a contagem total de palavras e o detalhamento por música para consultas adicionais sem impactar as métricas do executável paralelo.

Pré-requisitos

• Compilador e runtime MPI (mpicc, mpirun).
• Python 3.9+ para a etapa de classificação com LLM.
• (Opcional) Pacote requests para chamadas HTTP ao servidor do modelo.
• (Opcional) Servidor Ollama ou outra solução que exponha um endpoint compatível com /api/generate.

Compilação

make

O binário principal será gerado em bin/parallel_spotify.

Execução da análise paralela

mpirun -np <processos> ./bin/parallel_spotify spotify_millsongdata.csv \
  [--word-limit N] [--artist-limit N] [--output-dir diretório]

Parâmetros opcionais:

• --word-limit: limita o número de palavras escritas em word_counts.csv (valor padrão: salvar todas; informe um número positivo para restringir).
• --artist-limit: controla a quantidade de artistas exportados (padrão: salvar todos; informe um número positivo para limitar).
• --output-dir: diretório onde os artefatos são gerados (padrão: output).

Ao final da execução são produzidos:

• word_counts.csv – ranking decrescente de palavras.
• top_artists.csv – artistas ordenados pela quantidade de músicas.
• performance_metrics.json – tempos mínimo, médio e máximo por processo.
• split_columns/ – diretório auxiliar contendo os arquivos artist.csv e text.csv, usados como insumos independentes para as contagens paralelas.

Classificação de sentimento com modelo local

O script Python scripts/sentiment_classifier.py consome o mesmo dataset e consulta um modelo via HTTP. Ele pode operar em dois modos:

1. Modo real (padrão) – envia requisições para um servidor compatível com Ollama em http://localhost:11434. Ajuste a variável de ambiente OLLAMA_ENDPOINT ou utilize --model para trocar o modelo.
2. Modo --mock – aplica uma heurística simples baseada em palavras-chave para facilitar testes sem LLM instalado.

Exemplo de uso (modo real):

python scripts/sentiment_classifier.py spotify_millsongdata.csv \
  --model llama3 --limit 200 --output-dir output

Modo simulado:

python scripts/sentiment_classifier.py spotify_millsongdata.csv --mock

Saídas geradas:

• sentiment_totals.json – contagem agregada por classe.
• sentiment_details.csv – detalhamento por música e tempo de inferência.

Medindo desempenho

O arquivo performance_metrics.json produzido pelo executável MPI contém estatísticas de tempo médio, mínimo e máximo para cada estágio (cômputo local e tempo total). Para facilitar a comparação entre diferentes tamanhos de cluster, utilize o script scripts/run_performance.sh:

scripts/run_performance.sh spotify_millsongdata.csv 2 4 8

O script não recompila o projeto automaticamente; execute make antes de realizar os experimentos para garantir que o binário esteja atualizado.

Contagem serial de palavras por música

Quando precisar analisar as letras de forma isolada, sem acionar o executável paralelo, utilize scripts/word_count_per_song.py. O script lê o CSV original, mantém as aspas e apóstrofos das letras e processa as músicas em paralelo com threads, gravando dois arquivos:

• word_counts_global.csv – frequência total de cada palavra com três ou mais caracteres.
• word_counts_by_song.csv – frequência das palavras por artista e por música.

Exemplo de uso:

python scripts/word_count_per_song.py spotify_millsongdata.csv \
  --output-dir output/serial_word_counts --workers 8

O parâmetro --workers é opcional; quando omitido ou definido como zero, o script usa automaticamente o número de CPUs disponíveis.

Os arquivos são gravados no diretório informado (padrão: output/serial_word_counts).

Estrutura do repositório

├── bin/parallel_spotify        # executável (gerado pelo make)
├── output/                     # resultados (criado em tempo de execução)
├── scripts/
│   ├── run_performance.sh      # facilita execuções com vários processos
│   ├── sentiment_classifier.py # classificação de sentimento com LLM local
│   ├── split_csv_columns.py    # utilitário para dividir CSV em arquivos por coluna
│   └── word_count_per_song.py  # contagem serial de palavras e detalhamento por música
└── src/parallel_spotify.c      # código-fonte principal em C/MPI

Histórico de versões

Versão	Descrição	Principais diferenças
v0.1 (bdde614)	Estrutura inicial do projeto.	Repositório criado com README mínimo e configuração base.
v0.2 (4f78f8e, 732a70c)	Detalhamento do enunciado.	README atualizado com os requisitos completos do trabalho prático.
v0.3 (293e8f8)	Inclusão do dataset.	Arquivo spotify_millsongdata.csv adicionado para possibilitar testes locais.
v1.0 (8cc21fe) – versão atual	Implementação paralela com MPI e pipeline de sentimento.	Código C distribuído, geração de métricas de desempenho, scripts auxiliares em Python e shell, documentação completa em português.

Observações

• Os arquivos CSV gerados podem ser grandes, pois por padrão incluem todos os artistas e todas as palavras; ajuste --word-limit e --artist-limit conforme necessário.
• Certifique-se de apontar o mpirun para o mesmo mpicc utilizado na compilação para evitar incompatibilidades de runtime.