docs: polish README (OpenAPI bullet, Makefile tips, CI badge, license)

Author: Kyle Spengler

README.md

@@ -40,12 +40,93 @@ uvicorn serving_app.main:app --host 0.0.0.0 --port 8011
 # docs: http://localhost:8011/docs
 ```
 ## Endpoints
+## Endpoints
 
+- `GET /openapi.json` → OpenAPI schema
 - `GET /health`  → `{"ok": true, "model_loaded": true, "version": "0.1.0"}`
 - `GET /version` → `{"version": "0.1.0"}`
 - `POST /predict` → predict a single row
 - `POST /predict_batch` → predict many rows
 
+## Requests & Responses
+
+### `POST /predict` — single row
+
+### Request
+```json
+{ "features": [5.1, 3.5, 1.4, 0.2], "return_proba": true }
+```
+
+### Response
+```json
+{ "prediction": 0, "proba": [1.0, 0.0, 0.0], "latency_ms": 4.7 }
+```
+
+### `POST /predict_batch` — many rows
+
+
+### Request
+```json
+{ "items": [[5.1,3.5,1.4,0.2],[6.7,3.0,5.2,2.3]], "return_proba": true }
+```
+
+### Response
+```json
+{
+  "predictions": [0, 2],
+  "proba": [[1.0,0.0,0.0],[0.0,0.0,1.0]],
+  "latency_ms": 6.0
+}
+```
+
+## Curl Examples
+```bash
+# single
+curl -s -X POST http://localhost:8011/predict \
+  -H 'Content-Type: application/json' \
+  -d '{"features":[5.1,3.5,1.4,0.2], "return_proba": true}' | python -m json.tool
+
+# batch
+curl -s -X POST http://localhost:8011/predict_batch \
+  -H 'Content-Type: application/json' \
+  -d '{"items":[[5.1,3.5,1.4,0.2],[6.7,3.0,5.2,2.3]], "return_proba": true}' | python -m json.tool
+
+# health / version
+curl -s http://localhost:8011/health  | python -m json.tool
+curl -s http://localhost:8011/version
+```
+
+## Configuration
+- `MODEL_PATH` — override the model location (defaults to the baked-in path).
+```bash
+MODEL_PATH=models/model.pkl uvicorn serving_app.main:app --port 8011
+```
+
+## Project layout
+```text
+serving_app/
+├─ serving_app/
+│  └─ main.py            # FastAPI app: health/version/predict/predict_batch
+├─ training/
+│  └─ train.py           # trains scikit-learn model, saves to models/
+├─ models/               # model artifacts (created by training)
+├─ requirements.txt
+├─ Dockerfile
+├─ Makefile              # optional shortcuts (train/run/predict)
+├─ .github/workflows/ci.yml
+└─ README.md
+```
+
+## Docker
+```bash
+# build (after you've trained locally so models/ exists)
+docker build -t serving-app .
+
+# run (expose container:8000 -> host:8011)
+docker run --rm -p 8011:8000 serving-app
+# docs: http://localhost:8011/docs
+```
+
 ## CI
 
 A lightweight GitHub Actions workflow (.github/workflows/ci.yml) installs deps, boots the API, and smoke-tests /health. Extend it with linting, unit tests, or load tests as you grow.
@@ -68,3 +149,6 @@ A lightweight GitHub Actions workflow (.github/workflows/ci.yml) installs deps,
 
 
 
+
+## License
+MIT — see [LICENSE](LICENSE).