README.md

---
title: Gohan Product Recommendation API
emoji: 🍚
colorFrom: yellow
colorTo: yellow
sdk: docker
sdk_version: "0.2.0"
app_file: app.py
pinned: false
---

# Gohan FastAPI

This is a FastAPI-based product recommendation API deployed on Hugging Face Spaces.

## Endpoints

- `GET /` - Root endpoint with API information
- `GET /status` - Health check and model status
- `POST /predict` - Main prediction endpoint with topK parameter
- `POST /predict_simple` - Simple prediction endpoint

## Usage

### Check API Status
```bash
curl "https://tabito123-gohan-api-light.hf.space/status"
```

### Make Predictions
```bash
curl -X POST "https://tabito123-gohan-api-light.hf.space/predict" \
  -H "Content-Type: application/json" \
  -d '{"company_data_json": "{\"INDUSTRY\": \"IT\"}", "topK": 10}'
```

## Model Loading

The API uses FastAPI's lifespan events to load models only once during startup, providing efficient cold start handling.

## Required Model Files

- `model/gohan/epoch_*.pt` (PyTorch model)
- `model/gohan/*.json` (encoder files)
- `model/gohan/gohan_pm.csv` (product master data)

## API Response Format

```json
{
  "status": "success",
  "model": "gohan",
  "recommendations": [
    {
      "category_id": 123,
      "category_name": "栄養豊富な雑穀米",
      "score": 0.95
    }
  ],
  "metadata": {
    "model_version": "gohan_cid_v1.0",
    "total_categories": 30,
    "requested_k": 10
  }
}
```

## Cold Start Handling

The API automatically handles cold starts by:
1. Loading models during startup
2. Providing `/status` endpoint to check readiness
3. Returning appropriate HTTP status codes during loading
4. Graceful error handling for unready states