add readme

Author: abdratsd

README.md

@@ -0,0 +1,82 @@
+# InteractiveAI usecase Agent API
+
+A minimal Flask service that each usecase can drop into their AI agent application. It receives a recommendation request from **InteractiveAI** and returns computed **actions** synchronously.
+
+---
+
+## Features
+- **Single endpoint:** `POST /v1/get_recommendations`
+- **Synchronous:** compute and return actions in the same response
+- **Strict inputs:** `use_case`, `context`, `event` are **required**
+- **Health check:** `GET /v1/healthz`
+
+---
+
+## Requirements
+- Python 3.10+
+- `pip install flask`
+
+---
+
+## Run (development)
+```bash
+python app.py
+# Service listens on http://0.0.0.0:8000
+```
+> For production, use a proper WSGI server (e.g., gunicorn/uvicorn) and disable `debug`.
+
+---
+
+## API
+
+### POST `/v1/get_recommendations`
+**Purpose:** InteractiveAI sends a recommendation request. Your agent computes **actions** and returns them in the response.
+
+**Headers**
+- `Content-Type: application/json`
+
+**Request Body (JSON)**
+- **Required**
+  - `use_case` *(string)* — e.g., `Railway`, `Powergrid`, `ATM`.
+  - `context` *(object)* — Snapshot/state data from simulator.
+  - `event` *(object)* — Trigger info (alarms, alerts, malfunctions, etc.).
+- **Optional**
+  - `agent_type` *(string, default: `generic`)*
+  - `sim_api` *(object)* — Hints/endpoints if your agent needs to fetch extra simulator data (left to usecase logic).
+
+**Response (200 OK, JSON)**
+- `title` *(string)*
+- `description` *(string)*
+- `use_case` *(string)*
+- `agent_type` *(string)*
+- `actions` *(array of objects)* — **computed by your agent logic**
+
+**Error Responses**
+- `400 Bad Request` → `{"error":"bad_request","message":"...","details":{"missing":[...]}}`
+- `5xx` → Unexpected server errors
+
+---
+
+### GET `/v1/healthz`
+- Returns `200 OK` with body `ok`.
+
+---
+
+## Implementation Notes
+- Put your decision logic where the `actions` list is produced in `get_recommendations`.
+- If `sim_api` is present and your use case requires extra simulator data, fetch it before deciding actions (usecase-specific).
+- Security is intentionally omitted for this initial version; it will be added later. 
+---
+
+## File Overview
+- `app.py`
+  - `POST /v1/get_recommendations` — main endpoint
+  - `GET /v1/healthz` — readiness probe
+  - Minimal `400` helper for validation errors
+
+---
+
+## What Partners Must Implement
+- The **decision logic** producing the `actions` array.
+- (Optional) **Simulator fetches** based on `sim_api`.
+- (Later) **Auth, retries, persistence, logging**, and an async callback flow if needed.