IntentGuard Weekend MVP — Development Specification

Status: Specification complete; implementation not started.

IntentGuard is a local-first support-intent classifier that compares a TF-IDF logistic-regression baseline with a fine-tuned DistilBERT classifier and can abstain when model confidence is below a validation-derived threshold.

The repository is intentionally scoped to a 12–16 hour weekend implementation on one laptop. It demonstrates production ML judgment through an end-to-end pipeline, honest evaluation, input validation, focused tests, latency measurement, and a small FastAPI inference boundary.

Scope-frozen vertical slice#

1. Download and validate BANKING77.
2. Train and evaluate the classical baseline.
3. Fine-tune and evaluate one DistilBERT classifier.
4. Select an abstention threshold from validation data.
5. Serve POST /v1/predict and GET /health.
6. Run focused tests and generate a comparison report.

Nothing else belongs to the guaranteed MVP.

Source of truth#

Read these documents in order:

1. Project brief
2. Requirements and acceptance criteria
3. Architecture
4. ML system design
5. Implementation plan
6. Scope control
7. Agent operating guide

Supporting documents:

• Pre-documentation scope review
• Production readiness
• Interface contract
• Test and evaluation strategy
• Traceability matrix
• GitHub presentation plan
• Final validation
• Sources
• Architecture decisions

Planned implementation commands#

These commands are contracts for the implementation; they are not claims that the application already exists.

make setup
make data
make baseline
make train
make evaluate
make test
make serve

The primary demonstration path will be:

make setup data baseline train evaluate test
make serve

Honest status#

No accuracy, F1, calibration, latency, user-impact, or production-usage claims should be added until they are generated by the reproducible evaluation pipeline.