| name | taasim-api-contract |
| description | Use this skill when API behavior, route docs, Cassandra integration, or ML fallback behavior is unclear or broken and the FastAPI contract must be corrected and documented. |
CasaMotion API Contract
Trigger
Use this skill when endpoints and docs diverge, deployment dependencies drift, or /api/trips behavior must be formally decided and enforced.
Workflow
- Inspect API surface and schemas in api/main.py.
- Verify runtime dependencies in api/requirements.txt and image assumptions in api/Dockerfile.
- Compare README API table against implemented routes and response behavior.
- Cross-check Cassandra schema expectations against config/cassandra-init.cql and current API writes/reads.
- Audit ML behavior:
- startup model load path
- heuristic fallback path
- health exposure (model_loaded)
- Decide and document /api/trips contract mode:
- publish to Kafka raw.trips
- write directly to Cassandra
- stay demo-only (explicitly documented)
- Apply smallest code+doc edits, then run contract verification.
Required Checks
- api/main.py
- api/requirements.txt
- api/Dockerfile
- README API table
- Cassandra schema
- /api/trips integration mode decision
Validation Commands
rg -n "@app\\.(get|post|put|delete)\\(" api/main.py
rg -n "/api/|auth|forecast|trips|zones|health" README.MD
rg -n "cassandra|kafka|raw.trips|model|fallback|PYSPARK_ENABLED|MODEL_PATH" api/main.py
rg -n "cassandra|kafka|pyspark|fastapi|uvicorn" api/requirements.txt
rg -n "FROM|COPY|CMD|ENV" api/Dockerfile
rg -n "CREATE TABLE|vehicle_positions|demand_zones|trips" config/cassandra-init.cql
docker compose config --quiet
Output Contract
Return:
- Contract diff table: endpoint, current_behavior, expected_behavior, required_change.
- Explicit /api/trips decision and rationale.
- Verification checklist (docs, code, runtime) with pass/fail markers.
