Merge pull request #1 from DDMAL/ic_reimplementation

The initial stage of IC re-implementation. Features:

- Similar data structure as legacy (Image, glyph, etc)
- Same KNN algorithm
- Independent KNN model (library free)
- Primary API ports

Author: Yueqiao12Zhang

README.md

@@ -0,0 +1,51 @@
+# ic_new
+
+A modern rewrite of the **Interactive Classifier** — a tool for interactively classifying chant-manuscript neumes using a k-Nearest Neighbors model.
+
+This project replaces the legacy Rodan job (Django + Celery + Gamera + Backbone.Marionette) at [`/Rodan-lite/backend/django/code/jobs/interactive_classifier/`] with a non-Django Python service, a React + Vite frontend, and no Gamera dependency.
+
+## Key differences from the legacy IC
+
+- **Input is a full page image plus a bounding-box annotation file** (for example, MOTHRA JSON or YOLO), not page-level GameraXML. Neume crops are derived from those annotations rather than supplied as pre-cropped glyph images.
+- **Manual split (CCA on a single glyph) is deferred.** Reintroduce only if real data shows crops that contain multiple neumes.
+- **Output stays as GameraXML** so downstream MEI pipelines keep working.
+
+## Status
+
+| Layer       | Path         | Status                                |
+|-------------|--------------|---------------------------------------|
+| Algorithm core | `core/ic_core/` | In progress — scaffolded, partial impl |
+| API         | `api/`       | In progress, open to future change    |
+| Frontend    | `frontend/`  | Not started                           |
+
+## Repository layout
+
+```
+ic_new/
+├── core/
+│   ├── ic_core/        # Phase 1: algorithm core (uv-managed Python package)
+│   └── tests/          # Pytest suite + fixtures
+├── api/                # Phase 2: FastAPI service (planned)
+├── frontend/           # Phase 3: React + Vite UI (planned)
+└── docs/
+    ├── CLAUDE.md       # Guidance for Claude Code working in this repo
+    ├── migration_plan.md
+    └── KNN_ALGORITHM.md
+```
+
+## Quickstart (algorithm core)
+
+The core package uses [uv](https://docs.astral.sh/uv/) for environment and dependency management.
+
+```bash
+cd core/ic_core
+uv sync                 # install dependencies
+uv run pytest ../tests  # run tests
+uv run ruff check .     # lint
+```
+
+## Documentation
+
+- [docs/migration_plan.md](docs/migration_plan.md) — full migration strategy, phasing, and risks
+- [docs/KNN_ALGORITHM.md](docs/KNN_ALGORITHM.md) — algorithm spec and invariants
+- [docs/CLAUDE.md](docs/CLAUDE.md) — architecture notes and conventions for AI-assisted development

api/README.md

@@ -0,0 +1,36 @@
+# ic-api
+
+FastAPI service that wraps [`ic_core`](../core/ic_core) and exposes
+the Interactive Classifier as HTTP endpoints for the frontend.
+
+This is Phase 2 of the migration plan (`../docs/migration_plan.md`).
+The service stores session state in-memory only — sessions are lost
+on restart, which is fine for the single-user / local-tool target.
+Swap [`store.py`](src/ic_api/store.py) for a SQLite-backed store
+when persistence becomes a requirement.
+
+## Run
+
+```bash
+uv sync
+uv run ic-api          # binds to 127.0.0.1:8000
+```
+
+## Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/sessions` | Create a session and ingest a page + bbox file |
+| `GET` | `/sessions/{id}` | Fetch the current session state |
+| `POST` | `/sessions/{id}/classify` | Run a classify round |
+| `POST` | `/sessions/{id}/glyphs/{gid}` | Update a single glyph |
+| `DELETE` | `/sessions/{id}/glyphs/{gid}` | Delete a glyph |
+| `POST` | `/sessions/{id}/group` | Manual group (union N glyphs) |
+| `POST` | `/sessions/{id}/auto-group` | **501** — deferred (needs page-coord input) |
+| `POST` | `/sessions/{id}/classes/{name}/rename` | Rename a class |
+| `DELETE` | `/sessions/{id}/classes/{name}` | Delete a class from autocomplete |
+| `POST` | `/sessions/{id}/save` | No-op for the in-memory store; returns current state |
+| `POST` | `/sessions/{id}/complete` | Transition to EXPORT, returns GameraXML |
+| `DELETE` | `/sessions/{id}` | Discard the session |
+
+See [`src/ic_api/main.py`](src/ic_api/main.py) for the full schemas.

api/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "ic-api"
+version = "0.1.0"
+description = "FastAPI service for the Interactive Classifier"
+readme = "README.md"
+authors = [
+    { name = "Yueqiao Zhang", email = "yueqiao.zhang@mail.mcgill.ca" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.118.0",
+    "uvicorn[standard]>=0.32.0",
+    "pydantic>=2.10.0",
+    # Required by FastAPI's UploadFile/Form parsing for the
+    # multipart POST /sessions endpoint.
+    "python-multipart>=0.0.20",
+    "ic-core",
+]
+
+[project.scripts]
+ic-api = "ic_api.main:run"
+
+[tool.uv.sources]
+# Use the sibling core package directly during dev so changes there
+# are picked up without re-publishing.
+ic-core = { path = "../core/ic_core", editable = true }
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.27.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.15.12",
+]

api/src/ic_api/__init__.py

@@ -0,0 +1,4 @@
+"""ic-api — FastAPI service wrapping the ic_core algorithm package."""
+from ic_api.main import app, run
+
+__all__ = ["app", "run"]