Clean up docs. Fix test script incorrect path.

.gitignore

@@ -1,4 +1,7 @@
 dyff-outputs/
 models/
+test_datasets/
+test_results/
 venv/
 **/__pycache__
+*.tmp

README.md

@@ -39,9 +39,6 @@ make docker-build
 
 # Run
 make docker-run
-
-# Check logs
-docker logs -f safe-challenge-2025/example-submission
 ```
 
 ## Testing the API
@@ -76,16 +73,16 @@ example-submission/
 ├── main.py                      # Entry point
 ├── app/
 │   ├── core/
-│   │   ├── app.py               # App factory, config, DI, lifecycle
+│   │   ├── app.py               # <= INSTANTIATE YOUR DETECTOR HERE
 │   │   └── logging.py           # Logging setup
 │   ├── api/
 │   │   ├── models.py            # Request/response schemas
-│   │   ├── controllers.py       # <= IMPLEMENT YOUR DETECTOR HERE
+│   │   ├── controllers.py       # Business logic
 │   │   └── routes/
 │   │       └── prediction.py    # POST /predict
 │   └── services/
-│       ├── base.py              # Abstract InferenceService class
-│       └── inference.py         # ResNet implementation
+│       ├── base.py              # <= YOUR DETECTOR IMPLEMENTS THIS INTERFACE
+│       └── inference.py         # Example service based on ResNet-18
 ├── models/
 │   └── microsoft/
 │       └── resnet-18/           # Model weights and config
@@ -97,17 +94,16 @@ example-submission/
 ├── .env.example                 # Environment config template
 ├── cat.json                     # An example /predict request object
 ├── makefile
+├── prompt.sh                    # Script that makes a /predict request
 ├── requirements.in              
 ├── requirements.txt
-├── response.json               # An example /predict response object
+├── response.json                # An example /predict response object
 └──
 ```
 
-The key design decision here is that `app/core/app.py` consolidates everything—config, dependency injection, lifecycle, and the app factory. This avoids the mess of managing global state across multiple files.
-
 ## How to Plug In Your Own Model
 
-The whole service is built around one abstract base class: `InferenceService`. Implement it for your model, and everything else just works.
+To integrate your model, implement the `InferenceService` abstract class defined in `app/services/base.py`. You can follow the example implementation in `app/services/inference.py`, which is based on ResNet-18. After implementing the required interface, instantiate your model in the `lifespan()` function in `app/core/app.py`, replacing the `ResNetInferenceService` instance.
 
 ### Step 1: Create Your Service Class
 
@@ -115,7 +111,6 @@ The whole service is built around one abstract base class: `InferenceService`. I
 # app/services/your_model_service.py
 from app.services.base import InferenceService
 from app.api.models import ImageRequest, PredictionResponse
-import asyncio
 
 class YourModelService(InferenceService[ImageRequest, PredictionResponse]):
     def __init__(self, model_name: str):
@@ -124,26 +119,22 @@ class YourModelService(InferenceService[ImageRequest, PredictionResponse]):
         self.model = None
         self._is_loaded = False
 
-    async def load_model(self) -> None:
+    def load_model(self) -> None:
         """Load your model here. Called once at startup."""
         self.model = load_your_model(self.model_path)
         self._is_loaded = True
 
-    async def predict(self, request: ImageRequest) -> PredictionResponse:
-        """Run inference. Offload heavy work to thread pool."""
-        return await asyncio.to_thread(self._predict_sync, request)
-
-    def _predict_sync(self, request: ImageRequest) -> PredictionResponse:
+    def predict(self, request: ImageRequest) -> PredictionResponse:
         """Actual inference happens here."""
         image = decode_base64_image(request.image.data)
         result = self.model(image)
 
+        logprobs = ...
+        mask = ...
+
         return PredictionResponse(
-            prediction=result.label,
-            confidence=result.confidence,
-            predicted_label=result.class_id,
-            model=self.model_name,
-            mediaType=request.image.mediaType
+            logprobs=logprobs,
+            localizationMask=mask,
         )
 
     @property
@@ -151,8 +142,6 @@ class YourModelService(InferenceService[ImageRequest, PredictionResponse]):
         return self._is_loaded
 ```
 
-**Important:** Use `asyncio.to_thread()` to run CPU-heavy inference in a background thread. This keeps the server responsive while your model is working.
-
 ### Step 2: Register Your Service
 
 Open `app/core/app.py` and find the lifespan function:
@@ -162,14 +151,14 @@ Open `app/core/app.py` and find the lifespan function:
 service = ResNetInferenceService(model_name="microsoft/resnet-18")
 
 # To this:
-service = YourModelService(model_name="your-org/your-model")
+service = YourModelService(...)
 ```
 
 That's it. The `/predict` endpoint now serves your model.
 
 ### Model Files
 
-Put your model files under `models/` with the full org/model structure:
+Put your model files under the `models/` directory:
 
 ```
 models/
@@ -180,8 +169,6 @@ models/
         └── (other files)
 ```
 
-No renaming, no dropping the org prefix—it just mirrors the Hugging Face structure.
-
 ## Configuration
 
 Settings are managed via environment variables or a `.env` file. See `.env.example` for all available options.
@@ -251,7 +238,7 @@ If you see "Model directory not found", check that your model files exist at the
 {
   "image": {
     "mediaType": "image/jpeg",  // or "image/png"
-    "data": "<base64-encoded-image>"
+    "data": "<base64 string>"
   }
 }
 ```
@@ -259,11 +246,11 @@ If you see "Model directory not found", check that your model files exist at the
 **Response:**
 ```json
 {
-  "prediction": "string",      // Human-readable label
-  "confidence": 0.0,           // Softmax probability
-  "predicted_label": 0,        // Numeric class index
-  "model": "org/model-name",   // Model identifier
-  "mediaType": "image/jpeg"    // Echoed from request
+  "logprobs": [float],         // Log-probabilities of each label
+  "localizationMask": {        // [Optional] binary mask
+    "mediaType": "image/png",  // Always png
+    "data": "<base64 string>"  // Image data
+  }
 }
 ```
 
@@ -291,8 +278,12 @@ This creates:
 
 ```bash
 # Start your service first
-uvicorn main:app --reload
+make serve
+```
+
+In another terminal:
 
+```bash
 # Quick test (5 samples per dataset)
 python scripts/test_datasets.py --quick
 
@@ -367,7 +358,7 @@ uvicorn main:app --port 8080
 
 **Model not loading:**
 - Check the path: models should be in `models/<org>/<model-name>/`
-- Make sure you ran `bash scripts/model_download.bash`
+- If you're trying to run the example ResNet-based model, make sure you ran `make download` to fetch the model weights.
 - Check logs for the exact error
 
 **Slow inference:**

app/core/app.py

@@ -3,7 +3,7 @@
 import asyncio
 import warnings
 from contextlib import asynccontextmanager
-from typing import AsyncGenerator, Optional
+from typing import AsyncGenerator
 
 from fastapi import FastAPI
 from pydantic import Field

app/services/inference.py

@@ -2,7 +2,6 @@
 
 import base64
 import os
-import random
 from io import BytesIO
 
 import numpy as np
@@ -61,7 +60,6 @@ class ResNetInferenceService(InferenceService[ImageRequest, PredictionResponse])
 
         image_data = base64.b64decode(request.image.data)
         image = Image.open(BytesIO(image_data))
-        width, height = image.size
 
         if image.mode != 'RGB':
             image = image.convert('RGB')

scripts/test_datasets.py

@@ -23,7 +23,7 @@ class DatasetTester:
     def __init__(self, base_url: str = "http://127.0.0.1:8000", datasets_dir: str = "test_datasets"):
         self.base_url = base_url.rstrip('/')
         self.datasets_dir = Path(datasets_dir)
-        self.endpoint = f"{self.base_url}/predict/resnet"
+        self.endpoint = f"{self.base_url}/predict"
         self.results = []
 
     def load_dataset(self, dataset_path: Path) -> pd.DataFrame:
@@ -352,7 +352,7 @@ class DatasetTester:
 def main():
     parser = argparse.ArgumentParser(description="Test PyArrow datasets against ML inference service")
     parser.add_argument("--base-url", default="http://127.0.0.1:8000", help="Base URL of the API")
-    parser.add_argument("--datasets-dir", default="scripts/test_datasets", help="Directory containing datasets")
+    parser.add_argument("--datasets-dir", default="test_datasets", help="Directory containing datasets")
     parser.add_argument("--max-samples", type=int, help="Max samples per dataset to test")
     parser.add_argument("--category", help="Filter datasets by category (standard, edge_case, performance, model_comparison)")
     parser.add_argument("--quick", action="store_true", help="Quick test with max 5 samples per dataset")