{"id":46785302,"url":"https://github.com/meappy/kumon-marker","last_synced_at":"2026-04-01T20:52:29.575Z","repository":{"id":343011301,"uuid":"1134994423","full_name":"meappy/kumon-marker","owner":"meappy","description":"Automated Kumon worksheet marker using your favourite AI","archived":false,"fork":false,"pushed_at":"2026-03-15T03:58:10.000Z","size":14118,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T16:06:26.584Z","etag":null,"topics":["ai","computer-vision","education","fastapi","helm","kubernetes","python","react"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meappy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2026-01-15T13:51:07.000Z","updated_at":"2026-03-15T03:55:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/meappy/kumon-marker","commit_stats":null,"previous_names":["meappy/kumon-marker"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/meappy/kumon-marker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meappy%2Fkumon-marker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meappy%2Fkumon-marker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meappy%2Fkumon-marker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meappy%2Fkumon-marker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meappy","download_url":"https://codeload.github.com/meappy/kumon-marker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meappy%2Fkumon-marker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: 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":["ai","computer-vision","education","fastapi","helm","kubernetes","python","react"],"created_at":"2026-03-10T01:13:32.670Z","updated_at":"2026-04-01T20:52:29.567Z","avatar_url":"https://github.com/meappy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"branding/banner.png\" alt=\"Kumon Marker\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/meappy/kumon-marker/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/meappy/kumon-marker\" alt=\"Release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/meappy/kumon-marker/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/meappy/kumon-marker/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/meappy/kumon-marker/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/meappy/kumon-marker\" alt=\"Stars\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://conventionalcommits.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg\" alt=\"Conventional Commits\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.12-blue?logo=python\u0026logoColor=white\" alt=\"Python 3.12\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/React-18-61dafb?logo=react\u0026logoColor=white\" alt=\"React 18\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/FastAPI-009688?logo=fastapi\u0026logoColor=white\" alt=\"FastAPI\" /\u003e\n\u003c/p\u003e\n\nAutomated marking system for Kumon maths and English worksheets using pluggable vision AI providers.\n\n## Features\n\n- **Automatic worksheet marking** — Uses vision AI (Ollama, Anthropic Claude, Google Gemini, or OpenAI) to analyse and mark worksheets\n- **PDF annotation** — Marks correct pages with green circles, errors with red ticks\n- **Report generation** — Creates detailed PDF reports with scores and corrections\n- **Google Drive integration** — Sync worksheets directly from Google Drive\n- **Multi-user support** — Google OAuth authentication with per-user data isolation\n- **Job queue** — RabbitMQ-based queue for reliable background processing\n- **Kubernetes ready** — Helm charts with Argo CD GitOps deployment\n\n## Architecture\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Frontend  │────▶│   FastAPI   │────▶│  RabbitMQ   │────▶│   Worker    │\n│   (React)   │◀────│   (API)     │     │  (Queue)    │     │ (Processor) │\n└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘\n                           │                                       │\n                           ▼                                       ▼\n                    ┌─────────────┐                         ┌─────────────┐\n                    │ PostgreSQL  │                         │  Vision AI  │\n                    │  (Jobs DB)  │                         │  Provider   │\n                    └─────────────┘                         └─────────────┘\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Docker and Docker Compose (for local development)\n- Kubernetes cluster with Helm (for production)\n- Google Cloud project with OAuth configured\n- Vision AI backend: Ollama (local), Google Gemini, Anthropic Claude, or OpenAI\n\n### Local Development\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/meappy/kumon-marker.git\n   cd kumon-marker\n   ```\n\n2. Create environment file:\n   ```bash\n   cp .env.example .env\n   # Edit .env with your settings\n   ```\n\n3. Start with Docker Compose:\n   ```bash\n   docker compose up -d\n   ```\n\n4. Access the app at http://localhost:3000\n\n### Kubernetes Deployment\n\n1. Create namespace:\n   ```bash\n   kubectl create namespace kumon-marker\n   ```\n\n2. Deploy with Helm:\n   ```bash\n   helm upgrade --install kumon-marker ./helm/kumon-marker \\\n     -f ./helm/kumon-marker/values.yaml \\\n     -f ./helm/kumon-marker/values-local.yaml \\\n     -n kumon-marker\n   ```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VISION_PROVIDER` | AI provider: `ollama`, `anthropic`, `gemini`, `openai` | `ollama` |\n| `VALIDATION_METHOD` | Worksheet validation: `ocr` or `llm` | `ocr` |\n| `OLLAMA_BASE_URL` | Ollama server URL | `http://localhost:11434` |\n| `OLLAMA_MODEL` | Ollama model name | `moondream` |\n| `ANTHROPIC_API_KEY` | Anthropic API key or OAuth token | - |\n| `ANTHROPIC_MODEL` | Anthropic model name | `claude-sonnet-4-20250514` |\n| `GEMINI_API_KEY` | Google Gemini API key | - |\n| `GEMINI_MODEL` | Gemini model name | `gemini-2.0-flash` |\n| `OPENAI_API_KEY` | OpenAI API key | - |\n| `OPENAI_MODEL` | OpenAI model name | `gpt-4o` |\n| `GOOGLE_CLIENT_ID` | Google OAuth client ID | - |\n| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | - |\n| `ALLOWED_USERS` | Comma-separated list of allowed emails | - |\n| `SESSION_SECRET` | Secret for signing session cookies | - |\n| `RABBITMQ_URL` | RabbitMQ connection URL | - |\n| `DATABASE_URL` | PostgreSQL connection URL | - |\n\n## Development\n\n### Project Structure\n\n```\nkumon-marker/\n├── backend/           # FastAPI backend\n│   ├── app/\n│   │   ├── core/      # Config, session management\n│   │   ├── models/    # Pydantic schemas, SQLAlchemy models\n│   │   ├── routers/   # API endpoints\n│   │   └── services/  # Business logic (providers, marking, etc.)\n│   └── pyproject.toml\n├── frontend/          # React + Vite + Tailwind CSS\n│   ├── src/\n│   │   ├── api/       # API client\n│   │   ├── components/# React components\n│   │   └── utils/     # Helper functions\n│   └── package.json\n├── helm/              # Kubernetes Helm charts\n│   └── kumon-marker/\n├── branding/          # Logo, favicon, banner assets\n├── scripts/           # Development scripts\n│   └── version.py     # Version management\n├── Dockerfile         # Multi-stage Docker build\n└── VERSION            # Current version\n```\n\n### CI/CD \u0026 GitOps\n\nThis project uses **Semantic Release** for automated versioning and **Argo CD** for GitOps deployments.\n\n```bash\n# Feature branch → builds dev image\ngit checkout -b feat/my-feature\ngit commit -m \"feat: add new feature\"\ngit push origin feat/my-feature\n\n# Merge to main → auto version bump + deploy\n# fix: commits → patch (0.6.2 → 0.6.3)\n# feat: commits → minor (0.6.2 → 0.7.0)\n# BREAKING CHANGE: → major (0.6.2 → 1.0.0)\n```\n\n### Version Management\n\nAll version numbers are kept in sync across files:\n\n```bash\n# Show current versions\n./scripts/version.py show\n\n# Bump version\n./scripts/version.py bump patch    # Bug fix\n./scripts/version.py bump minor    # Feature\n./scripts/version.py bump major    # Breaking change\n\n# Sync all files to VERSION\n./scripts/version.py sync\n```\n\n### Building\n\n```bash\n# Build Docker image\ndocker build -t ghcr.io/meappy/kumon-marker:latest .\n```\n\n## API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/auth/status` | Get authentication status |\n| POST | `/api/auth/login` | Initiate Google OAuth login |\n| POST | `/api/auth/logout` | Logout |\n| GET | `/api/worksheets` | List marked worksheets |\n| POST | `/api/worksheets/{id}/process` | Queue worksheet for marking |\n| GET | `/api/worksheets/{id}/marked` | Download marked PDF |\n| GET | `/api/worksheets/{id}/report` | Download report PDF |\n| GET | `/api/gdrive/files` | List Google Drive files |\n| POST | `/api/gdrive/sync/{id}` | Sync file from Google Drive |\n| GET | `/api/jobs/status` | Get job queue status |\n| DELETE | `/api/jobs/{id}` | Cancel a job |\n\n## References\n\n- [Kumon Home Marking Guides](https://kumon.sg/home-marking-guides/) — Official marking guides for maths and English worksheets\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to fork, set up your environment, and submit a pull request.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeappy%2Fkumon-marker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeappy%2Fkumon-marker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeappy%2Fkumon-marker/lists"}