Forward explicit reasoning controls to compatible generators

README.md

@@ -14,6 +14,16 @@ See [decision routing, provider requirements and examples](docs/DECISION-MODELS.
 The same decision policies can [classify context fragments for selective
 compaction](docs/FRAGMENT-COMPACTION.md), with generative summaries only where needed.
 
+Generation requests on `/v1/chat/completions` and `/v1/responses` can pass
+`reasoning` (an object) or `reasoning_effort` (a string) through to
+OpenAI-compatible providers. For example, `"reasoning":{"effort":"low"}`
+selects a lower effort when the chosen model supports it. The provider validates
+supported values; omitting the fields preserves its defaults. A policy can set
+`["set_param","reasoning_effort","low"]` for its generation calls, including
+compaction. Generic flows carry request controls to their generation nodes;
+native decision nodes receive their own independent contracts. These controls
+do not translate to the native Bedrock, Anthropic or Google APIs.
+
 Concretely it's an async FastAPI shim that runs the
 [`unhardcoded-engine`](https://github.com/genlayerlabs/unhardcoded-engine) core
 and inherits its provider selection, fallback, retry and per-provider auth. The core

llm_router_host.py

@@ -385,7 +385,7 @@ async def execute_flow_async(self, flow_ir, base_contract,
         input_text = _last_user_text(base_contract.get("messages") or [])
         carry = {k: base_contract[k] for k in
                  ("max_tokens", "tools", "tool_choice", "response_format",
-                  "temperature", "seed", "session", "cache_hot_route")
+                  "temperature", "seed", "reasoning", "reasoning_effort", "session", "cache_hot_route")
                  if k in base_contract}
 
         async def run_node(nid, node, prompt):

provider_adapters/openai_compatible.py

@@ -120,7 +120,8 @@ def _prepare_openai_call(
         "model": offer.get("wire_model_id") or request["served_model_id"],
         "messages": request.get("messages") or [],
     }
-    for field in ("tools", "response_format", "temperature", "seed", "max_tokens"):
+    for field in ("tools", "response_format", "temperature", "seed", "max_tokens",
+                  "reasoning", "reasoning_effort"):
         v = request.get(field)
         if v is not None:
             body[field] = v

shim.py

@@ -82,6 +82,8 @@ class ChatRequest(BaseModel):
     tools: list[dict] | None = None
     tool_choice: Any = None
     response_format: dict | None = None
+    reasoning: dict | None = None
+    reasoning_effort: str | None = None
     temperature: float | None = None
     seed: int | None = None
     max_tokens: int | None = None
@@ -130,7 +132,7 @@ class DecisionsRequest(BaseModel):
 
 class ResponsesRequest(BaseModel):
     """Permissive OpenAI /v1/responses body. Unknown fields are kept
-    (extra="allow") so Responses params the shim does not read (reasoning,
+    (extra="allow") so Responses params the shim does not read (
     include, store, parallel_tool_calls, prompt_cache_key, text,
     previous_response_id, …) never break the request."""
     model_config = ConfigDict(extra="allow")
@@ -142,6 +144,8 @@ class ResponsesRequest(BaseModel):
     tool_choice: Any = None
     stream: bool = False
     max_output_tokens: int | None = None
+    reasoning: dict | None = None
+    reasoning_effort: str | None = None
     temperature: float | None = None
     first_token_timeout_ms: int | None = None
     timeout_ms: int | None = None
@@ -1304,6 +1308,8 @@ async def _handle_responses(req: ResponsesRequest, profile_name: str | None = No
             tools=_rapi.tools_to_chat(req.tools),
             tool_choice=_rapi.tool_choice_to_chat(req.tool_choice),
             temperature=req.temperature,
+            reasoning=req.reasoning,
+            reasoning_effort=req.reasoning_effort,
             max_tokens=req.max_output_tokens,
             first_token_timeout_ms=req.first_token_timeout_ms,
             timeout_ms=req.timeout_ms,
@@ -1635,6 +1641,10 @@ def _request_to_contract(
         contract["tool_choice"] = req.tool_choice
     if req.response_format is not None:
         contract["response_format"] = req.response_format
+    if req.reasoning is not None:
+        contract["reasoning"] = req.reasoning
+    if req.reasoning_effort is not None:
+        contract["reasoning_effort"] = req.reasoning_effort
     if req.temperature is not None:
         contract["temperature"] = req.temperature
     if req.seed is not None:

tests/test_reasoning_controls.py

@@ -0,0 +1,111 @@
+"""Explicit generation controls must reach the OpenAI-compatible wire unchanged."""
+import copy
+from pathlib import Path
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from provider_adapters.openai_compatible import make_async_call_provider, stream_openai_compatible
+from shim import ChatRequest, _request_to_contract, create_app
+from llm_router_host import LLMRouterHost
+from tests.test_compact import _PIN
+from tests.test_streaming import OPENAI_REQ, FakeStreamClient, FakeStreamResponse, _openai_lines
+
+
+CONTROLS = [{"reasoning": {"enabled": False}}, {"reasoning": {"effort": "low"}},
+            {"reasoning_effort": "low"}, {}]
+
+
+@pytest.fixture
+def host():
+    root = Path(__file__).resolve().parents[1]
+    host = LLMRouterHost(router_path=root/'core/router.lua',
+        config_path=root/'core/config.example.lua', metrics_path=root/'core/metrics.example.lua',
+        env={"COMPUT3_API_KEY": "fixture-credential"})
+    host.init()
+    return host
+
+
+@pytest.mark.parametrize("controls", CONTROLS)
+def test_chat_contract_preserves_explicit_controls(controls):
+    contract = _request_to_contract(ChatRequest(**controls), "default")
+    assert {k: contract[k] for k in ("reasoning", "reasoning_effort") if k in contract} == controls
+
+
+@pytest.mark.parametrize("controls", CONTROLS)
+@pytest.mark.asyncio
+async def test_buffered_adapter_sends_controls(controls):
+    seen = []
+    async def respond(request):
+        import json
+        seen.append(json.loads(request.content))
+        return httpx.Response(200, json={"choices": [{"message": {"content": "ok"}}]})
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as client:
+        result = await make_async_call_provider(client=client)({**OPENAI_REQ, **controls})
+    assert result["ok"]
+    assert {k: seen[0][k] for k in ("reasoning", "reasoning_effort") if k in seen[0]} == controls
+
+
+@pytest.mark.parametrize("controls", CONTROLS)
+@pytest.mark.asyncio
+async def test_streaming_adapter_sends_controls(controls):
+    client = FakeStreamClient(FakeStreamResponse(200, _openai_lines("ok")))
+    await stream_openai_compatible({**OPENAI_REQ, **controls}, lambda _: None, client=client)
+    body = client.requests[0]["json"]
+    assert {k: body[k] for k in ("reasoning", "reasoning_effort") if k in body} == controls
+
+
+@pytest.mark.parametrize("endpoint", ["/v1/chat/completions", "/v1/responses"])
+@pytest.mark.parametrize("stream", [False, True])
+@pytest.mark.parametrize("controls", CONTROLS[:3])
+def test_http_to_core_provider_preserves_controls(host, endpoint, stream, controls):
+    seen = []
+    async def call(req):
+        seen.append(copy.deepcopy(req))
+        return {"ok": True, "response": {"text": "ok", "tokens_in": 1, "tokens_out": 1}}
+    host.set_async_call_hook(call)
+    payload = {"policy_ir": _PIN, "stream": stream, **controls}
+    payload.update({"input": "hello"} if endpoint.endswith("responses") else
+                   {"messages": [{"role": "user", "content": "hello"}]})
+    response = TestClient(create_app(host)).post(endpoint, json=payload)
+    assert response.status_code == 200, response.text
+    assert len(seen) == 1
+    assert {k: seen[0][k] for k in ("reasoning", "reasoning_effort") if k in seen[0]} == controls
+
+
+def test_policy_can_set_reasoning_effort_before_provider_call(host):
+    seen = []
+    async def call(req):
+        seen.append(req)
+        return {"ok": True, "response": {"text": "ok"}}
+    host.set_async_call_hook(call)
+    policy = copy.deepcopy(_PIN)
+    policy[4] = ["set_param", "reasoning_effort", "low"]
+    response = TestClient(create_app(host)).post(
+        "/v1/chat/completions", json={"messages": [], "policy_ir": policy})
+    assert response.status_code == 200, response.text
+    assert seen[0]["reasoning_effort"] == "low"
+
+
+@pytest.mark.parametrize("controls", CONTROLS[:3])
+def test_flow_controls_reach_generation_but_not_native_decisions(host, monkeypatch, controls):
+    from tests.test_flow_data import triage
+    seen = []
+    async def execute(contract, **kwargs):
+        seen.append(copy.deepcopy(contract))
+        if contract.get("protocol") == "decisions":
+            response = {"decision": {"model": "fixture", "answers": {
+                key: {"type": "choice", "choice": "support",
+                      "probabilities": {"support": 1.0, "sales": 0.0}} for key in ("a", "b")}}}
+        else:
+            response = {"text": '{"a":"Reply A","b":"Reply B"}', "finish_reason": "stop"}
+        return {"ok": True, "response": response}
+    monkeypatch.setattr(host, "execute_async", execute)
+    response = TestClient(create_app(host)).post("/v1/chat/completions", json={
+        "flow_ir": triage(), "flow_input": {"a": "Crash", "b": "Question"}, **controls})
+    assert response.status_code == 200, response.text
+    assert len(seen) == 2
+    assert seen[0]["protocol"] == "decisions"
+    assert not any(k in seen[0] for k in controls)
+    assert {k: seen[1][k] for k in controls} == controls