{"id":38507209,"url":"https://github.com/hyperskill/ilt-reports-generator","last_synced_at":"2026-01-17T06:16:20.677Z","repository":{"id":319319050,"uuid":"1068377542","full_name":"hyperskill/ilt-reports-generator","owner":"hyperskill","description":"final reports generator fol Instructor lead trainings","archived":false,"fork":false,"pushed_at":"2025-10-17T15:48:53.000Z","size":811,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-18T18:14:56.128Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperskill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T09:42:48.000Z","updated_at":"2025-10-17T15:48:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"a2d2fe05-7d35-4d14-a88c-fe2201359e41","html_url":"https://github.com/hyperskill/ilt-reports-generator","commit_stats":null,"previous_names":["hyperskill/ilt-reports-generator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hyperskill/ilt-reports-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperskill%2Filt-reports-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperskill%2Filt-reports-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperskill%2Filt-reports-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperskill%2Filt-reports-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperskill","download_url":"https://codeload.github.com/hyperskill/ilt-reports-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperskill%2Filt-reports-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28502108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T06:16:19.976Z","updated_at":"2026-01-17T06:16:20.666Z","avatar_url":"https://github.com/hyperskill.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Performance Segmentation - Report Builder\n\nA comprehensive web application for analyzing student performance and dynamic activity patterns. Built with Next.js, Radix UI, and Chart.js.\n\n## Features\n\n### Two Analysis Modes\n\n1. **Performance Segmentation**\n   - Static performance profiles based on grades, attempts, persistence, and meeting attendance\n   - Activity-derived metrics (effort, consistency, struggle) computed from submissions\n   - Segments learners into categories like \"Leader efficient\", \"Balanced middle\", etc.\n   - Based on the algorithm in `docs/student-segment.md`\n\n2. **Dynamic/Easing Segmentation**\n   - Temporal activity analysis with CSS-like easing patterns\n   - Activity derived from submissions (correct=1.0, incorrect=0.25) + meetings\n   - Classifies cumulative behavior curves (linear, ease, ease-in, ease-out, ease-in-out)\n   - Calculates frontload index, Bezier control points, consistency, and burstiness\n   - Based on the algorithm in `docs/easing_activity_algorithm_node.md`\n\n### Application Flow\n\n1. **Upload** - Upload 3-5 CSV files:\n   - `grade_book.csv` (Required): user_id, total\n   - `learners.csv` (Required): user_id, first_name, last_name\n   - `submissions.csv` (Required): user_id, step_id, status, timestamp\n   - `meetings.csv` (Optional): user_id, name, [dd.mm.yyyy] columns\n   - `structure.csv` (Optional): course_id, module_id, lesson_id, step_id - enables clickable topic links to Cogniterra\n   \n   **Note**: CSV files can use either comma (`,`) or semicolon (`;`) as delimiter. The system automatically detects the correct delimiter.\n\n2. **Review** - Verify column recognition and preview data\n\n3. **Exclusions** - Optionally exclude specific user IDs\n\n4. **Settings** - Configure:\n   - Time bucketing (Daily/Weekly)\n   - Smoothing (Off/Light/Strong)\n   - Meetings usage toggles\n   - Alpha/Beta weights (for activity blending)\n\n5. **Processing** - Automated data processing with progress tracking\n\n6. **Results** - View results in two modes:\n   - Performance Segmentation: tables, filters, segment distribution\n   - Dynamic/Easing: curves, charts, easing patterns\n   - **NEW**: Click any student name to view personalized report\n\n### Personalized Student Reports\n\n**Feature**: Individual student detail pages with comprehensive, actionable insights.\n\n**Access**: Click on any student's name in the results tables (both Performance and Dynamic tabs).\n\n**What's Included**:\n- 📋 **Progress Highlights**: 3-5 key wins and focus areas in plain English\n- 🔥 **Overall Engagement**: Program-wide engagement level (High/Medium/Low) with description\n- 📊 **Activity Curve**: Visual timeline with frontload index, consistency, burstiness\n- ✨ **Going Well Topics**: Areas where student excels\n- 🎯 **Focus Areas**: Topics needing attention with specific reasons\n- 🚀 **Next Steps**: 2-3 prioritized, actionable suggestions\n- 📚 **Topic Analysis Table**: Detailed breakdown with deltas from course average\n  - **Clickable topic links** to Cogniterra (when structure.csv is uploaded)\n- 📊 **Full Statistics**: All performance metrics in one view\n\n**Algorithm**: Based on Personal Student Report Algorithm v1 (see `docs/personal_student_report_algorithm.md`)\n\n**Language**: Student-friendly, supportive, actionable - no heavy statistics or rankings\n\n**Learn More**: See `docs/student-report-feature-guide.md` for complete documentation\n\n### AI-Generated Reports (NEW!)\n\n**Feature**: Automatically generate comprehensive, human-friendly reports for managers and students using LiteLLM (GPT-4 via Hyperskill proxy).\n\n**Manager Reports**:\n- 📊 Executive summary of cohort performance\n- 👥 Group dynamics and engagement analysis\n- 🎓 Learning outcomes and project evaluation\n- 💬 Expert observations synthesis\n- 🎯 Opportunities and recommendations\n\n**Student Reports**:\n- 🌟 Personalized learning journey overview\n- 💪 Strengths and achievements\n- 📈 Skills development analysis\n- 👨‍🏫 Instructor feedback\n- 🚀 Growth opportunities and next steps\n\n**Key Benefits**:\n- ⚡ Auto-generates from raw data in seconds\n- ✏️ Fully editable before publishing\n- 🔒 Draft/publish workflow for quality control\n- 🎯 Tailored language for different audiences\n- 💰 Cost-effective (~$0.01-$0.05 per report)\n\n**Setup**: See `docs/LLM_SETUP.md` for quick start guide\n\n**Full Documentation**: See `docs/llm-reports-feature.md` for complete details\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+ and npm/yarn/pnpm\n\n### Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Run development server\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) to view the application.\n\n### Building for Production\n\n```bash\n# Build the application\nnpm run build\n\n# Start production server\nnpm start\n```\n\n## Technology Stack\n\n- **Framework**: Next.js 14 (App Router)\n- **UI Library**: Radix UI Themes + Radix Primitives\n- **Charts**: Chart.js + React Chart.js 2\n- **Styling**: CSS Modules (no Tailwind)\n- **Language**: TypeScript\n- **Data Processing**: CSV Parse/Stringify, Day.js\n\n## Project Structure\n\n```\n/app\n  /upload          - File upload screen\n  /review          - Data review screen\n  /exclusions      - User exclusion screen\n  /settings        - Display settings\n  /processing      - Data processing\n  /results         - Results display (dual mode)\n  /components      - Reusable components\n  layout.tsx       - Root layout with theme provider\n  page.tsx         - Home (redirects to upload)\n\n/lib\n  /context         - React Context for state management\n  /processors      - Data processing algorithms\n  /utils           - Helper functions\n  types.ts         - TypeScript type definitions\n\n/docs              - Algorithm documentation\n```\n\n## Data Processing\n\n### Performance Segmentation Algorithm (v3)\n\nImplements the logic from `docs/student-segment.md`:\n\n1. **Data normalization** - Standardizes column names\n2. **Core metrics** - Calculates total, submissions, unique_steps, correct_submissions\n3. **Derived metrics** - success_rate, persistence, efficiency\n4. **Temporal metrics** - active_days, active_days_ratio (from submission timestamps)\n5. **Activity-derived signals** - effort_index, consistency_index, struggle_index\n   - Effort: z-score normalized (submissions + active_days)\n   - Consistency: active_days / span_days\n   - Struggle: based on high persistence + low success rate\n6. **Meeting processing** - Attendance percentages\n7. **Segmentation** - Rule-based classification with activity-driven rules\n\n### Dynamic/Easing Algorithm (v3)\n\nImplements the logic from `docs/easing_activity_algorithm_node.md`:\n\n1. **Daily activity from submissions** - Weighted by status (correct=1.0, incorrect=0.25)\n2. **Composite activity** - `α * platform_events + β * meetings` (α=1.0, β=1.5)\n3. **Cumulative curve normalization** - Maps to [0,1] × [0,1]\n4. **Bezier proxy estimation** - Via quartiles (t25, t50, t75)\n5. **Frontload index** - FI = 0.5 - t50\n6. **Easing classification** - Matches to CSS easing patterns\n7. **Auxiliary metrics** - consistency, burstiness from daily activity\n\n## CSV File Requirements\n\n### grade_book.csv\n```csv\nuser_id,total\n123,85\n456,72\n```\n\n### learners.csv\n```csv\nuser_id,first_name,last_name\n123,John,Doe\n456,Jane,Smith\n```\n\n### submissions.csv (CRITICAL - drives all activity metrics)\n```csv\nuser_id,step_id,status,timestamp\n123,step_1,correct,2024-01-15T10:30:00Z\n123,step_2,incorrect,2024-01-16T14:20:00Z\n```\n**Note**: Timestamps can be Unix epoch (seconds or milliseconds) or ISO strings.\n\n### meetings.csv (optional)\n```csv\nuser_id,name,[15.01.2024] Webinar,[22.01.2024] Workshop\n123,John Doe,TRUE,FALSE\n456,Jane Smith,TRUE,TRUE\n```\n\n## Features Implemented\n\n✅ Multi-step file upload with validation  \n✅ CSV parsing with flexible column names  \n✅ User ID exclusion system  \n✅ Display settings configuration  \n✅ Performance segmentation with activity signals  \n✅ Dynamic/easing segmentation from submissions  \n✅ Dual-mode results display  \n✅ Interactive filtering and search  \n✅ Data visualization with Chart.js  \n✅ Responsive tables with scrolling  \n\n## Key Algorithm Changes (v3)\n\n### What Changed\n- ❌ **NO activity.csv required** - Everything built from submissions\n- ✅ **Activity from submissions**: Uses weighted attempts (correct=1.0, incorrect=0.25)\n- ✅ **Two-source blending**: platform_events + meetings (no separate activity file)\n- ✅ **New metrics**: consistency, burstiness in Dynamic mode\n- ✅ **Enhanced Performance**: effort/consistency/struggle indices from submissions\n\n### Activity Derivation\n```\nPlatform Activity per Day = Σ(correct: 1.0, incorrect: 0.25)\nComposite Activity = α * Platform + β * Meetings\n  where α=1.0 (platform weight), β=1.5 (meetings weight)\n```\n\n## Design Decisions\n\n- **No Tailwind CSS**: Uses CSS Modules as specified in requirements\n- **Radix UI**: Provides accessible, unstyled primitives and themed components\n- **Client-side processing**: All data processing happens in the browser\n- **React Context**: Simple state management without external libraries\n- **TypeScript**: Full type safety throughout the application\n- **No external activity files**: All metrics derived from existing data\n\n## Key Components\n\n- `AppContext` - Global state management\n- `FileUploadTile` - Drag-and-drop CSV upload\n- `PerformanceResults` - Performance segmentation display\n- `DynamicResults` - Dynamic segmentation display\n- `EasingChart` - Line chart for cumulative curves\n\n## Contributing\n\nThis project follows the specifications in:\n- `docs/unified_app_ui_userflow.md` - UX flow\n- `docs/student-segment.md` - Performance algorithm (v3)\n- `docs/easing_activity_algorithm_node.md` - Dynamic algorithm (v3)\n- `docs/RADIX_UI_DOCUMENTATION.md` - UI components\n- `docs/REACT_CHARTJS_DOCUMENTATION.md` - Charts\n\n## License\n\nPrivate project - All rights reserved\n\n## Development Notes\n\n- The app uses Next.js App Router (not Pages Router)\n- All pages are client components (`'use client'`)\n- Data processing is synchronous (could be moved to Web Workers)\n- Tables show first 100 rows for performance\n- CSV files are parsed entirely into memory\n- Activity metrics are computed on-the-fly from submissions\n\n## Troubleshooting\n\n### Files not uploading\n- Ensure files are valid CSV format\n- Check that required columns exist\n- File size should be reasonable (\u003c 10MB recommended)\n- Comments (lines starting with #) are automatically filtered\n\n### Processing fails\n- Verify all required files are uploaded (grade_book, learners, submissions)\n- Check CSV format and column names\n- Look at browser console for detailed errors\n- Ensure submissions.csv has valid timestamps\n\n### Charts not showing\n- Ensure submissions.csv has timestamp column\n- Check that data was successfully processed\n- Try refreshing the page\n\n## Support\n\nFor issues or questions, refer to:\n- `app-creation-log.md` - Detailed implementation notes\n- Documentation files in `/docs`\n- Component source code with inline comments\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperskill%2Filt-reports-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperskill%2Filt-reports-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperskill%2Filt-reports-generator/lists"}