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)

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.