feat: transparent openai responses api integration

README.md

@@ -132,6 +132,41 @@ This way the Ollama backend servers are utilized more efficient than by simply u
 
 NOMYO Router also supports OpenAI API compatible v1 backend servers.
 
+## OpenAI Responses API
+
+In addition to Chat Completions, NOMYO Router exposes the OpenAI **Responses API**:
+
+```
+POST   /v1/responses                  # create a response (stream or non-stream)
+GET    /v1/responses/{id}             # retrieve a stored response
+DELETE /v1/responses/{id}             # delete a stored response
+POST   /v1/responses/{id}/cancel      # cancel a background response
+```
+
+It works transparently across **all** backends. When the routed model lives on a native
+Responses backend (external OpenAI) the request is forwarded as-is; for Ollama and llama-server the
+router translates Responses ⇄ Chat Completions in both directions (request, response, and streaming
+typed SSE events), so clients get a consistent `/v1/responses` surface regardless of backend.
+
+### Conversation state (`store` / `previous_response_id`)
+
+The router **owns conversation state itself** (persisted in its SQLite DB) rather than delegating to
+the upstream provider, so `store` and `previous_response_id` behave identically on every backend.
+On a follow-up request the router rehydrates the prior turns from its DB and expands them into the
+conversation; outbound native calls always send `store=false`. Trade-off: this forgoes OpenAI's
+server-side reasoning-state reuse in exchange for uniform, backend-agnostic chaining.
+
+### Background mode
+
+`background:true` (which requires `store:true`) returns immediately with `{"status":"queued"}`; the
+request runs server-side and the client polls `GET /v1/responses/{id}` until the status reaches a
+terminal state (`completed` / `failed` / `cancelled`). `POST /v1/responses/{id}/cancel` aborts it.
+
+Limitations: streaming reconnect-resume via `starting_after` is not yet implemented. In a
+multi-worker/replica deployment polling works via the shared DB, but `cancel` only reaches the
+running task in the worker that started it (other workers just mark the stored row cancelled). A
+background task interrupted by a server restart is reconciled to `failed` on the next startup.
+
 ## Semantic LLM Cache
 
 NOMYO Router includes an optional semantic cache that serves repeated or semantically similar LLM requests from cache — no endpoint round-trip, no token cost, response in <10 ms.
@@ -172,7 +207,7 @@ Each request is keyed on `model + system_prompt` (exact) combined with a weighte
 
 ### Cached routes
 
-`/api/chat` · `/api/generate` · `/v1/chat/completions` · `/v1/completions`
+`/api/chat` · `/api/generate` · `/v1/chat/completions` · `/v1/completions` · `/v1/responses`
 
 ### Cache management