# AGENTS.md ## Visão Geral do Projeto Este é o **Machine Learning para Principiantes**, um currículo abrangente de 12 semanas e 26 lições que cobre conceitos clássicos de machine learning utilizando Python (principalmente com Scikit-learn) e R. O repositório foi concebido como um recurso de aprendizagem autodidata, com projetos práticos, questionários e tarefas. Cada lição explora conceitos de ML através de dados reais provenientes de várias culturas e regiões do mundo. Componentes principais: - **Conteúdo Educacional**: 26 lições que abrangem introdução ao ML, regressão, classificação, clustering, NLP, séries temporais e aprendizagem por reforço - **Aplicação de Questionários**: Aplicação de questionários baseada em Vue.js com avaliações antes e depois das lições - **Suporte Multilíngue**: Traduções automáticas para mais de 40 idiomas via GitHub Actions - **Suporte a Duas Linguagens**: Lições disponíveis tanto em Python (notebooks Jupyter) quanto em R (ficheiros R Markdown) - **Aprendizagem Baseada em Projetos**: Cada tópico inclui projetos práticos e tarefas ## Estrutura do Repositório ``` ML-For-Beginners/ ├── 1-Introduction/ # ML basics, history, fairness, techniques ├── 2-Regression/ # Regression models with Python/R ├── 3-Web-App/ # Flask web app for ML model deployment ├── 4-Classification/ # Classification algorithms ├── 5-Clustering/ # Clustering techniques ├── 6-NLP/ # Natural Language Processing ├── 7-TimeSeries/ # Time series forecasting ├── 8-Reinforcement/ # Reinforcement learning ├── 9-Real-World/ # Real-world ML applications ├── quiz-app/ # Vue.js quiz application ├── translations/ # Auto-generated translations └── sketchnotes/ # Visual learning aids ``` Cada pasta de lição geralmente contém: - `README.md` - Conteúdo principal da lição - `notebook.ipynb` - Notebook Jupyter em Python - `solution/` - Código de solução (versões em Python e R) - `assignment.md` - Exercícios práticos - `images/` - Recursos visuais ## Comandos de Configuração ### Para Lições em Python A maioria das lições utiliza notebooks Jupyter. Instale as dependências necessárias: ```bash # Install Python 3.8+ if not already installed python --version # Install Jupyter pip install jupyter # Install common ML libraries pip install scikit-learn pandas numpy matplotlib seaborn # For specific lessons, check lesson-specific requirements # Example: Web App lesson pip install flask ``` ### Para Lições em R As lições em R estão nas pastas `solution/R/` como ficheiros `.rmd` ou `.ipynb`: ```bash # Install R and required packages # In R console: install.packages(c("tidyverse", "tidymodels", "caret")) ``` ### Para a Aplicação de Questionários A aplicação de questionários é uma aplicação Vue.js localizada no diretório `quiz-app/`: ```bash cd quiz-app npm install ``` ### Para o Site de Documentação Para executar a documentação localmente: ```bash # Install Docsify npm install -g docsify-cli # Serve from repository root docsify serve # Access at http://localhost:3000 ``` ## Fluxo de Trabalho de Desenvolvimento ### Trabalhar com Notebooks de Lição 1. Navegue até ao diretório da lição (ex.: `2-Regression/1-Tools/`) 2. Abra o notebook Jupyter: ```bash jupyter notebook notebook.ipynb ``` 3. Trabalhe no conteúdo e nos exercícios da lição 4. Consulte as soluções na pasta `solution/` se necessário ### Desenvolvimento em Python - As lições utilizam bibliotecas padrão de ciência de dados em Python - Notebooks Jupyter para aprendizagem interativa - Código de solução disponível na pasta `solution/` de cada lição ### Desenvolvimento em R - As lições em R estão no formato `.rmd` (R Markdown) - Soluções localizadas em subdiretórios `solution/R/` - Utilize RStudio ou Jupyter com kernel R para executar os notebooks em R ### Desenvolvimento da Aplicação de Questionários ```bash cd quiz-app # Start development server npm run serve # Access at http://localhost:8080 # Build for production npm run build # Lint and fix files npm run lint ``` ## Instruções de Teste ### Teste da Aplicação de Questionários ```bash cd quiz-app # Lint code npm run lint # Build to verify no errors npm run build ``` **Nota**: Este é principalmente um repositório de currículo educacional. Não há testes automatizados para o conteúdo das lições. A validação é feita através de: - Conclusão dos exercícios das lições - Execução bem-sucedida das células dos notebooks - Verificação dos resultados contra as soluções esperadas ## Diretrizes de Estilo de Código ### Código em Python - Siga as diretrizes de estilo PEP 8 - Utilize nomes de variáveis claros e descritivos - Inclua comentários para operações complexas - Os notebooks Jupyter devem conter células markdown explicando os conceitos ### JavaScript/Vue.js (Aplicação de Questionários) - Siga o guia de estilo Vue.js - Configuração ESLint em `quiz-app/package.json` - Execute `npm run lint` para verificar e corrigir automaticamente problemas ### Documentação - Os ficheiros markdown devem ser claros e bem estruturados - Inclua exemplos de código em blocos de código delimitados - Utilize links relativos para referências internas - Siga as convenções de formatação existentes ## Construção e Implementação ### Implementação da Aplicação de Questionários A aplicação de questionários pode ser implementada no Azure Static Web Apps: 1. **Pré-requisitos**: - Conta Azure - Repositório GitHub (já bifurcado) 2. **Implementar no Azure**: - Crie um recurso Azure Static Web App - Conecte ao repositório GitHub - Defina a localização da aplicação: `/quiz-app` - Defina a localização de saída: `dist` - O Azure cria automaticamente o workflow do GitHub Actions 3. **Workflow do GitHub Actions**: - Ficheiro de workflow criado em `.github/workflows/azure-static-web-apps-*.yml` - Constrói e implementa automaticamente ao fazer push para a branch principal ### PDF da Documentação Gerar PDF a partir da documentação: ```bash npm install npm run convert ``` ## Fluxo de Trabalho de Tradução **Importante**: As traduções são automatizadas via GitHub Actions utilizando o Co-op Translator. - As traduções são geradas automaticamente quando alterações são feitas na branch `main` - **NÃO traduza o conteúdo manualmente** - o sistema trata disso - Workflow definido em `.github/workflows/co-op-translator.yml` - Utiliza serviços Azure AI/OpenAI para tradução - Suporta mais de 40 idiomas ## Diretrizes de Contribuição ### Para Contribuidores de Conteúdo 1. **Bifurque o repositório** e crie uma branch de funcionalidade 2. **Faça alterações no conteúdo das lições** se estiver a adicionar/atualizar lições 3. **Não modifique ficheiros traduzidos** - eles são gerados automaticamente 4. **Teste o seu código** - certifique-se de que todas as células dos notebooks são executadas com sucesso 5. **Verifique se os links e imagens** funcionam corretamente 6. **Submeta um pull request** com uma descrição clara ### Diretrizes para Pull Requests - **Formato do título**: `[Seção] Breve descrição das alterações` - Exemplo: `[Regression] Corrigir erro na lição 5` - Exemplo: `[Quiz-App] Atualizar dependências` - **Antes de submeter**: - Certifique-se de que todas as células dos notebooks são executadas sem erros - Execute `npm run lint` se estiver a modificar quiz-app - Verifique a formatação markdown - Teste quaisquer novos exemplos de código - **O PR deve incluir**: - Descrição das alterações - Razão para as alterações - Capturas de ecrã se houver alterações na interface - **Código de Conduta**: Siga o [Código de Conduta de Código Aberto da Microsoft](CODE_OF_CONDUCT.md) - **CLA**: Será necessário assinar o Acordo de Licença de Contribuidor ## Estrutura das Lições Cada lição segue um padrão consistente: 1. **Questionário pré-aula** - Testar conhecimento inicial 2. **Conteúdo da lição** - Instruções e explicações escritas 3. **Demonstrações de código** - Exemplos práticos em notebooks 4. **Verificações de conhecimento** - Confirmar compreensão ao longo da lição 5. **Desafio** - Aplicar conceitos de forma independente 6. **Tarefa** - Prática estendida 7. **Questionário pós-aula** - Avaliar resultados de aprendizagem ## Referência de Comandos Comuns ```bash # Python/Jupyter jupyter notebook # Start Jupyter server jupyter notebook notebook.ipynb # Open specific notebook pip install -r requirements.txt # Install dependencies (where available) # Quiz App cd quiz-app npm install # Install dependencies npm run serve # Development server npm run build # Production build npm run lint # Lint and fix # Documentation docsify serve # Serve documentation locally npm run convert # Generate PDF # Git workflow git checkout -b feature/my-change # Create feature branch git add . # Stage changes git commit -m "Description" # Commit changes git push origin feature/my-change # Push to remote ``` ## Recursos Adicionais - **Coleção Microsoft Learn**: [Módulos de ML para Principiantes](https://learn.microsoft.com/en-us/collections/qrqzamz1nn2wx3?WT.mc_id=academic-77952-bethanycheum) - **Aplicação de Questionários**: [Questionários online](https://ff-quizzes.netlify.app/en/ml/) - **Fórum de Discussão**: [Discussões no GitHub](https://github.com/microsoft/ML-For-Beginners/discussions) - **Tutoriais em Vídeo**: [Playlist no YouTube](https://aka.ms/ml-beginners-videos) ## Tecnologias Principais - **Python**: Linguagem principal para lições de ML (Scikit-learn, Pandas, NumPy, Matplotlib) - **R**: Implementação alternativa utilizando tidyverse, tidymodels, caret - **Jupyter**: Notebooks interativos para lições em Python - **R Markdown**: Documentos para lições em R - **Vue.js 3**: Framework da aplicação de questionários - **Flask**: Framework de aplicação web para implementação de modelos de ML - **Docsify**: Gerador de sites de documentação - **GitHub Actions**: CI/CD e traduções automatizadas ## Considerações de Segurança - **Sem segredos no código**: Nunca comprometa chaves de API ou credenciais - **Dependências**: Mantenha os pacotes npm e pip atualizados - **Entrada do utilizador**: Exemplos de aplicações web Flask incluem validação básica de entrada - **Dados sensíveis**: Os conjuntos de dados de exemplo são públicos e não sensíveis ## Resolução de Problemas ### Notebooks Jupyter - **Problemas com o kernel**: Reinicie o kernel se as células ficarem pendentes: Kernel → Reiniciar - **Erros de importação**: Certifique-se de que todos os pacotes necessários estão instalados com pip - **Problemas de caminho**: Execute os notebooks a partir do diretório onde estão localizados ### Aplicação de Questionários - **npm install falha**: Limpe a cache do npm: `npm cache clean --force` - **Conflitos de porta**: Altere a porta com: `npm run serve -- --port 8081` - **Erros de construção**: Elimine `node_modules` e reinstale: `rm -rf node_modules && npm install` ### Lições em R - **Pacote não encontrado**: Instale com: `install.packages("nome-do-pacote")` - **Renderização de RMarkdown**: Certifique-se de que o pacote rmarkdown está instalado - **Problemas com o kernel**: Pode ser necessário instalar IRkernel para Jupyter ## Notas Específicas do Projeto - Este é principalmente um **currículo de aprendizagem**, não código de produção - O foco está em **compreender conceitos de ML** através de prática prática - Os exemplos de código priorizam **clareza em vez de otimização** - A maioria das lições é **autossuficiente** e pode ser concluída de forma independente - **Soluções fornecidas**, mas os alunos devem tentar os exercícios primeiro - O repositório utiliza **Docsify** para documentação web sem etapa de construção - **Sketchnotes** fornecem resumos visuais dos conceitos - **Suporte multilíngue** torna o conteúdo acessível globalmente --- **Aviso**: Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, é importante notar que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes da utilização desta tradução.