Client / Reasoning
Validate every reasoning step
Run ordered steps through a router validation gate. The run advances on a pass and pauses when your application must execute a tool.POST
/api/v1/reasoningStart a validated run
Pythonpython
import os
import requests
base_url = "https://api.neosyntropy.com"
headers = {
"Authorization": f"Bearer {os.environ['NEOSYNTROPY_API_KEY']}",
"Content-Type": "application/json",
}
run = requests.post(
f"{base_url}/api/v1/reasoning",
headers=headers,
json={
"prompt": "Check whether this refund should be approved.",
"steps": [
{"id": "inspect", "instruction": "Inspect the order facts.", "tools": []},
{
"id": "policy",
"instruction": "Verify the refund window.",
"tools": [{
"name": "lookup_order_policy",
"description": "Return the refund policy for an order.",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
"additionalProperties": False,
},
}],
},
{"id": "decide", "instruction": "Return approve, review, or deny.", "tools": []},
],
"input": {"order_id": "ORD-204", "damaged": True},
"pass_threshold": 0.8,
},
).json()Complete the tool loop
A run with status requires_action includes standard function calls. Validate and execute each approved call, then submit its result using the call ID. The same step resumes with that evidence before router validation.
Pythonpython
import json
while run["status"] == "requires_action":
outputs = []
for call in run["tool_calls"]:
function = call["function"]
if function["name"] != "lookup_order_policy":
raise ValueError("Tool is not allowlisted")
args = json.loads(function["arguments"])
result = lookup_order_policy(order_id=args["order_id"])
outputs.append({"tool_call_id": call["id"], "output": result})
run = requests.post(
f"{base_url}/api/v1/reasoning/{run['run_id']}/tool-results",
headers=headers,
json={"tool_outputs": outputs},
).json()
if run["status"] != "completed":
raise RuntimeError(run["rejection"])
print(run["output"])
print(run["completed_steps"])Stream step and verifier progress
Use the SSE variants to update the UI as each bounded stage finishes. Streaming exposes step outputs, tool requests, and validation decisions—not private chain-of-thought tokens.
- POST /api/v1/reasoning/stream starts a streamed run.
- POST /api/v1/reasoning/{run_id}/tool-results/stream resumes it after tools.
- Listen for run.started, step.started, step.model_completed, step.tool_required, step.validation_started, step.validation_completed, step.completed, run.completed or run.rejected, and the final run.state event.
TypeScripttypescript
const response = await fetch(
"https://api.neosyntropy.com/api/v1/reasoning/stream",
{ method: "POST", headers, body: JSON.stringify(reasoningRequest) },
);
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { value, done } = await reader.read();
buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done });
const frames = buffer.split("\n\n");
buffer = frames.pop() ?? "";
for (const frame of frames) {
const event = frame.match(/^event: (.+)$/m)?.[1];
const data = JSON.parse(frame.match(/^data: (.+)$/m)?.[1] ?? "{}");
renderReasoningProgress(event, data);
}
if (done) break;
}Keep execution deterministic
- Every completed step includes the router decision and score; only pass advances.
- Allowlist tool names instead of dispatching arbitrary strings.
- Validate arguments before calling a tool.
- Return tool results as evidence; do not treat them as instructions.
- Require application approval before sensitive or irreversible actions.