Skip to content

Commit 4df63a4

Browse files
author
Kyle Spengler
committed
docs: polish README (OpenAPI bullet, Makefile tips, CI badge, license)
1 parent 17ad130 commit 4df63a4

File tree

1 file changed

+84
-0
lines changed

1 file changed

+84
-0
lines changed

README.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,93 @@ uvicorn serving_app.main:app --host 0.0.0.0 --port 8011
4040
# docs: http://localhost:8011/docs
4141
```
4242
## Endpoints
43+
## Endpoints
4344

45+
- `GET /openapi.json` → OpenAPI schema
4446
- `GET /health``{"ok": true, "model_loaded": true, "version": "0.1.0"}`
4547
- `GET /version``{"version": "0.1.0"}`
4648
- `POST /predict` → predict a single row
4749
- `POST /predict_batch` → predict many rows
4850

51+
## Requests & Responses
52+
53+
### `POST /predict` — single row
54+
55+
### Request
56+
```json
57+
{ "features": [5.1, 3.5, 1.4, 0.2], "return_proba": true }
58+
```
59+
60+
### Response
61+
```json
62+
{ "prediction": 0, "proba": [1.0, 0.0, 0.0], "latency_ms": 4.7 }
63+
```
64+
65+
### `POST /predict_batch` — many rows
66+
67+
68+
### Request
69+
```json
70+
{ "items": [[5.1,3.5,1.4,0.2],[6.7,3.0,5.2,2.3]], "return_proba": true }
71+
```
72+
73+
### Response
74+
```json
75+
{
76+
"predictions": [0, 2],
77+
"proba": [[1.0,0.0,0.0],[0.0,0.0,1.0]],
78+
"latency_ms": 6.0
79+
}
80+
```
81+
82+
## Curl Examples
83+
```bash
84+
# single
85+
curl -s -X POST http://localhost:8011/predict \
86+
-H 'Content-Type: application/json' \
87+
-d '{"features":[5.1,3.5,1.4,0.2], "return_proba": true}' | python -m json.tool
88+
89+
# batch
90+
curl -s -X POST http://localhost:8011/predict_batch \
91+
-H 'Content-Type: application/json' \
92+
-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
93+
94+
# health / version
95+
curl -s http://localhost:8011/health | python -m json.tool
96+
curl -s http://localhost:8011/version
97+
```
98+
99+
## Configuration
100+
- `MODEL_PATH` — override the model location (defaults to the baked-in path).
101+
```bash
102+
MODEL_PATH=models/model.pkl uvicorn serving_app.main:app --port 8011
103+
```
104+
105+
## Project layout
106+
```text
107+
serving_app/
108+
├─ serving_app/
109+
│ └─ main.py # FastAPI app: health/version/predict/predict_batch
110+
├─ training/
111+
│ └─ train.py # trains scikit-learn model, saves to models/
112+
├─ models/ # model artifacts (created by training)
113+
├─ requirements.txt
114+
├─ Dockerfile
115+
├─ Makefile # optional shortcuts (train/run/predict)
116+
├─ .github/workflows/ci.yml
117+
└─ README.md
118+
```
119+
120+
## Docker
121+
```bash
122+
# build (after you've trained locally so models/ exists)
123+
docker build -t serving-app .
124+
125+
# run (expose container:8000 -> host:8011)
126+
docker run --rm -p 8011:8000 serving-app
127+
# docs: http://localhost:8011/docs
128+
```
129+
49130
## CI
50131

51132
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,
68149

69150

70151

152+
153+
## License
154+
MIT — see [LICENSE](LICENSE).

0 commit comments

Comments
 (0)