# AGENTS.md ## Преглед пројекта Ово је **Машинско учење за почетнике**, свеобухватан 12-недељни, 26-лекцијски програм који покрива класичне концепте машинског учења користећи Python (првенствено са Scikit-learn) и R. Репозиторијум је осмишљен као ресурс за самостално учење са практичним пројектима, квизовима и задацима. Свака лекција истражује концепте машинског учења кроз податке из стварног света из различитих култура и региона широм света. Кључне компоненте: - **Едукативни садржај**: 26 лекција које покривају увод у машинско учење, регресију, класификацију, кластерисање, NLP, временске серије и учење путем појачања - **Апликација за квизове**: Квиз апликација заснована на Vue.js са проценама пре и после лекције - **Подршка за више језика**: Аутоматизовани преводи на 40+ језика путем GitHub Actions - **Двојезична подршка**: Лекције доступне и на Python-у (Jupyter бележнице) и на R-у (R Markdown датотеке) - **Учење кроз пројекте**: Свака тема укључује практичне пројекте и задатке ## Структура репозиторијума ``` 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 ``` Свака фасцикла лекције обично садржи: - `README.md` - Главни садржај лекције - `notebook.ipynb` - Python Jupyter бележница - `solution/` - Код решења (Python и R верзије) - `assignment.md` - Вежбе за праксу - `images/` - Визуелни ресурси ## Команде за подешавање ### За Python лекције Већина лекција користи Jupyter бележнице. Инсталирајте потребне зависности: ```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 ``` ### За R лекције R лекције се налазе у фасциклама `solution/R/` као `.rmd` или `.ipynb` датотеке: ```bash # Install R and required packages # In R console: install.packages(c("tidyverse", "tidymodels", "caret")) ``` ### За апликацију за квизове Апликација за квизове је Vue.js апликација која се налази у фасцикли `quiz-app/`: ```bash cd quiz-app npm install ``` ### За сајт документације Да бисте покренули документацију локално: ```bash # Install Docsify npm install -g docsify-cli # Serve from repository root docsify serve # Access at http://localhost:3000 ``` ## Радни ток развоја ### Рад са бележницама лекција 1. Идите у фасциклу лекције (нпр. `2-Regression/1-Tools/`) 2. Отворите Jupyter бележницу: ```bash jupyter notebook notebook.ipynb ``` 3. Прођите кроз садржај лекције и вежбе 4. Проверите решења у фасцикли `solution/` ако је потребно ### Python развој - Лекције користе стандардне Python библиотеке за науку о подацима - Jupyter бележнице за интерактивно учење - Код решења доступан у фасцикли `solution/` сваке лекције ### R развој - R лекције су у `.rmd` формату (R Markdown) - Решeња се налазе у подфасциклама `solution/R/` - Користите RStudio или Jupyter са R језгром за покретање R бележница ### Развој апликације за квизове ```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 ``` ## Упутства за тестирање ### Тестирање апликације за квизове ```bash cd quiz-app # Lint code npm run lint # Build to verify no errors npm run build ``` **Напомена**: Ово је првенствено репозиторијум за едукативни програм. Не постоје аутоматизовани тестови за садржај лекција. Валидација се врши кроз: - Завршавање вежби лекција - Успешно покретање ћелија у бележницама - Провера резултата у односу на очекиване у решењима ## Упутства за стил кодирања ### Python код - Пратите смернице за стил PEP 8 - Користите јасна, описна имена променљивих - Укључите коментаре за сложене операције - Jupyter бележнице треба да имају markdown ћелије које објашњавају концепте ### JavaScript/Vue.js (Апликација за квизове) - Прати смернице за стил Vue.js - ESLint конфигурација у `quiz-app/package.json` - Покрените `npm run lint` за проверу и аутоматско исправљање проблема ### Документација - Markdown датотеке треба да буду јасне и добро структуриране - Укључите примере кода у ограђеним блоковима кода - Користите релативне линкове за унутрашње референце - Пратите постојеће конвенције форматирања ## Изградња и распоређивање ### Распоређивање апликације за квизове Апликација за квизове може се распоредити на Azure Static Web Apps: 1. **Предуслови**: - Azure налог - GitHub репозиторијум (већ форкован) 2. **Распоређивање на Azure**: - Креирајте Azure Static Web App ресурс - Повежите се са GitHub репозиторијумом - Поставите локацију апликације: `/quiz-app` - Поставите локацију излазних датотека: `dist` - Azure аутоматски креира GitHub Actions радни ток 3. **GitHub Actions радни ток**: - Радни ток креиран у `.github/workflows/azure-static-web-apps-*.yml` - Аутоматски се гради и распоређује при сваком push-у на главну грану ### PDF документација Генеришите PDF из документације: ```bash npm install npm run convert ``` ## Радни ток превођења **Важно**: Преводи се аутоматски врше путем GitHub Actions користећи Co-op Translator. - Преводи се аутоматски генеришу када се промене пошаљу на `main` грану - **НЕ преводите садржај ручно** - систем то обавља - Радни ток дефинисан у `.github/workflows/co-op-translator.yml` - Користи Azure AI/OpenAI услуге за превођење - Подржава 40+ језика ## Упутства за допринос ### За доприносиоце садржаја 1. **Fork-ујте репозиторијум** и креирајте грану за функцију 2. **Измените садржај лекције** ако додајете/ажурирате лекције 3. **Не модификујте преведене датотеке** - оне се аутоматски генеришу 4. **Тестирајте свој код** - уверите се да све ћелије у бележницама раде успешно 5. **Проверите линкове и слике** да ли исправно функционишу 6. **Пошаљите pull request** са јасним описом ### Упутства за pull request - **Формат наслова**: `[Секција] Кратак опис промена` - Пример: `[Регресија] Исправка грешке у лекцији 5` - Пример: `[Апликација за квизове] Ажурирање зависности` - **Пре слања**: - Уверите се да све ћелије у бележницама раде без грешака - Покрените `npm run lint` ако мењате апликацију за квизове - Проверите форматирање markdown-а - Тестирајте све нове примере кода - **PR мора да садржи**: - Опис промена - Разлог за промене - Снимке екрана ако постоје промене у корисничком интерфејсу - **Кодекс понашања**: Пратите [Microsoft Open Source Code of Conduct](CODE_OF_CONDUCT.md) - **CLA**: Мораћете да потпишете Уговор о лиценци за доприносиоце ## Структура лекције Свака лекција прати конзистентан образац: 1. **Квиз пре предавања** - Тестирање почетног знања 2. **Садржај лекције** - Писана упутства и објашњења 3. **Демонстрације кода** - Практични примери у бележницама 4. **Провере знања** - Верификација разумевања током лекције 5. **Изазов** - Примена концепата самостално 6. **Задатак** - Продужена пракса 7. **Квиз после предавања** - Процена резултата учења ## Референтне команде ```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 ``` ## Додатни ресурси - **Microsoft Learn колекција**: [Модули за машинско учење за почетнике](https://learn.microsoft.com/en-us/collections/qrqzamz1nn2wx3?WT.mc_id=academic-77952-bethanycheum) - **Апликација за квизове**: [Онлајн квизови](https://ff-quizzes.netlify.app/en/ml/) - **Дискусиони форум**: [GitHub Discussions](https://github.com/microsoft/ML-For-Beginners/discussions) - **Видео упутства**: [YouTube плејлиста](https://aka.ms/ml-beginners-videos) ## Кључне технологије - **Python**: Примарни језик за лекције машинског учења (Scikit-learn, Pandas, NumPy, Matplotlib) - **R**: Алтернативна имплементација користећи tidyverse, tidymodels, caret - **Jupyter**: Интерактивне бележнице за Python лекције - **R Markdown**: Документи за R лекције - **Vue.js 3**: Оквир за апликацију за квизове - **Flask**: Оквир за веб апликације за распоређивање ML модела - **Docsify**: Генератор сајта документације - **GitHub Actions**: CI/CD и аутоматизовани преводи ## Безбедносни аспекти - **Нема тајни у коду**: Никада не додајте API кључеве или акредитиве у код - **Зависности**: Ажурирајте npm и pip пакете - **Кориснички унос**: Примери Flask веб апликација укључују основну валидацију уноса - **Осећајни подаци**: Пример скупови података су јавни и неосетљиви ## Решавање проблема ### Jupyter бележнице - **Проблеми са језгром**: Поново покрените језгро ако се ћелије заглаве: Kernel → Restart - **Грешке при увозу**: Уверите се да су све потребне библиотеке инсталиране помоћу pip-а - **Проблеми са путевима**: Покрените бележнице из њихове фасцикле ### Апликација за квизове - **npm install не успева**: Очистите npm кеш: `npm cache clean --force` - **Конфликти портова**: Промените порт помоћу: `npm run serve -- --port 8081` - **Грешке при изградњи**: Обришите `node_modules` и поново инсталирајте: `rm -rf node_modules && npm install` ### R лекције - **Пакет није пронађен**: Инсталирајте помоћу: `install.packages("package-name")` - **Рендеровање RMarkdown-а**: Уверите се да је инсталиран пакет rmarkdown - **Проблеми са језгром**: Можда ће бити потребно инсталирати IRkernel за Jupyter ## Напомене специфичне за пројекат - Ово је првенствено **курикулум за учење**, а не продукцијски код - Фокус је на **разумевању концепата машинског учења** кроз практичну примену - Примери кода приоритетно истичу **јасноћу уместо оптимизације** - Већина лекција је **самостална** и може се завршити независно - **Решења су доступна**, али ученици треба прво да покушају сами - Репозиторијум користи **Docsify** за веб документацију без корака изградње - **Скетч белешке** пружају визуелне резимеје концепата - **Подршка за више језика** чини садржај глобално доступним --- **Одрицање од одговорности**: Овај документ је преведен коришћењем услуге за превођење помоћу вештачке интелигенције [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да обезбедимо тачност, молимо вас да имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални превод од стране људи. Не преузимамо одговорност за било каква погрешна тумачења или неспоразуме који могу настати услед коришћења овог превода.