Upload 20 files

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+__pycache__
+.pytest_cache
+*.py[cod]
+*.log
+.env
+upstage_creds.json
+tests
+smoke_test.py
+live_zcode_test.py
+requirements-dev.txt
+compose.yaml
+Makefile

.env.example

@@ -0,0 +1,18 @@
+# Public Hugging Face Space mode (requested default)
+PUBLIC_ACCESS=true
+# Only used if PUBLIC_ACCESS=false
+PROVIDER_API_KEY=
+
+PORT=7860
+LOG_LEVEL=INFO
+UPSTAGE_CACHE_DIR=/tmp/.cache/upstage
+MAX_CONCURRENT_REQUESTS=6
+QUEUE_TIMEOUT_SECONDS=20
+UPSTREAM_TIMEOUT_SECONDS=330
+UPSTREAM_RETRIES=1
+TOOL_PROTOCOL_RETRIES=1
+MAX_BODY_MB=4
+MAX_INPUT_CHARS=1000000
+MAX_BUFFERED_OUTPUT_CHARS=8000000
+# Disabled by default so ZCode agent loops are not throttled. Set for public abuse control.
+RATE_LIMIT_PER_MINUTE=0

.gitignore

@@ -0,0 +1,9 @@
+.env
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]
+*.log
+upstage_creds.json
+.cache/

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim-bookworm
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PORT=7860 \
+    UPSTAGE_CACHE_DIR=/home/user/.cache/upstage
+
+RUN useradd --create-home --uid 1000 --shell /bin/bash user
+WORKDIR /home/user/app
+
+COPY --chown=user:user requirements.txt ./requirements.txt
+RUN python -m pip install --upgrade pip && \
+    python -m pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user:user app.py tool_protocol.py upstage_provider.py upstage_interactive.py ./
+RUN mkdir -p /home/user/.cache/upstage && chown -R user:user /home/user
+
+USER user
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860/healthz', timeout=3)" || exit 1
+
+CMD ["sh", "-c", "exec uvicorn app:app --host 0.0.0.0 --port ${PORT:-7860} --workers 1 --proxy-headers --forwarded-allow-ips='*'"]

Makefile

@@ -0,0 +1,19 @@
+.PHONY: install test live run smoke zcode-live
+
+install:
+	python -m pip install -r requirements-dev.txt
+
+test:
+	pytest -q
+
+live:
+	UPSTAGE_LIVE=1 pytest -q tests/test_upstage_provider.py -k Live
+
+run:
+	uvicorn app:app --host 0.0.0.0 --port 7860
+
+smoke:
+	python smoke_test.py http://127.0.0.1:7860
+
+zcode-live:
+	python live_zcode_test.py http://127.0.0.1:7860

README.md

@@ -0,0 +1,389 @@
+---
+title: Upstage Solar for ZCode
+emoji: ☀️
+colorFrom: yellow
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Upstage Solar for ZCode
+
+A purpose-built **OpenAI Chat Completions provider** for **Z.ai ZCode**, packaged as a public Hugging Face Docker Space.
+
+It is based on the async, pure-HTTP provider from:
+
+```text
+Adarshukumar/serv__/New Upstage Change Logs/upstage_provider.py
+```
+
+The transport discovers an anonymous Upstage Console session through Next.js server actions, uses `curl_cffi` with browser TLS impersonation, and talks to the Upstage demo Chat Completions stream. No browser, Selenium, API key, or upstream account is required.
+
+> This is an independent compatibility gateway, not an official Upstage service. The anonymous Console transport can change or be rate-limited by Upstage. Review Upstage's terms before operating a public relay.
+
+## Why this version works with ZCode
+
+The source provider was an excellent async chat library, but it was not an OpenAI web server and did not implement function calls. This project adds:
+
+- `GET /v1/models`
+- `GET /v1/models/{model}`
+- `POST /v1/chat/completions`
+- non-streaming OpenAI responses
+- realtime SSE for ordinary chat
+- `[DONE]` and `stream_options.include_usage`
+- separate `reasoning_content`
+- optional Upstage/Tavily web search and returned sources
+- OpenAI `system`, `developer`, `user`, `assistant`, and `tool` message handling
+- OpenAI `tools`, `tool_choice`, `parallel_tool_calls`, assistant `tool_calls`, and tool-result loops
+- JSON-Schema validation of generated function arguments
+- one bounded corrective retry when Solar emits malformed or missing required calls
+- OpenAI-shaped errors, body/input limits, concurrency control, optional rate limiting, and optional Bearer authentication
+- a non-root UID 1000 Docker image for Hugging Face Spaces
+
+## Important tool-calling design
+
+Upstage's official API supports native function calling. However, the anonymous Console demo endpoint used here currently accepts but **ignores** native `tools` and `tool_choice` fields. Pretending otherwise would break ZCode.
+
+This gateway therefore uses a constrained adapter:
+
+1. ZCode's function catalog and tool choice are validated.
+2. A bounded tool protocol is injected into Solar's system prompt.
+3. Solar emits its learned internal call format.
+4. The gateway parses the call, checks the function name, parses arguments as JSON, and validates them against the requested function's JSON Schema.
+5. Valid calls are returned as standard OpenAI `tool_calls`.
+6. On the next request, assistant calls and `role: tool` results are translated back into Solar's conversation format.
+
+Tool-aware generations are buffered until validation completes, then emitted as valid OpenAI JSON or SSE. Ordinary chat without tools is streamed token by token directly from Upstage.
+
+This is deliberate: ZCode receives a valid tool call or a clean error—never half of a malformed protocol block.
+
+## Models
+
+The API exposes the four canonical models present in the source provider:
+
+| Model ID | Reasoning efforts | Search | Source max output |
+|---|---|---:|---:|
+| `solar-pro3` | `low`, `medium`, `high` | yes | 65,536 |
+| `solar-pro2` | `low`, `high` | yes | 16,383 |
+| `syn-pro` | `low`, `high` | yes | 16,384 |
+| `upstage/solar-1-mini-chat` | none | yes | 16,383 |
+
+**Recommended for ZCode:** `solar-pro3`.
+
+## Deploy as a public Hugging Face Space
+
+### 1. Create the Space
+
+1. Open <https://huggingface.co/new-space>.
+2. Choose **Docker** as the SDK.
+3. Choose **Public** visibility.
+4. A free CPU Space is sufficient; inference runs remotely.
+
+### 2. Put this directory at the Space repository root
+
+The Space root must directly contain `README.md`, `Dockerfile`, `app.py`, `tool_protocol.py`, `upstage_provider.py`, and `requirements.txt`.
+
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
+cp -a /path/to/hf-space/. YOUR_SPACE/
+cd YOUR_SPACE
+git add .
+git commit -m "Deploy Upstage Solar OpenAI gateway for ZCode"
+git push
+```
+
+Hugging Face reads the metadata at the top of this README, builds the Docker image, and exposes port `7860`.
+
+No Space secret is required for the requested public deployment. Credentials discovered from the Upstage Console are cached inside the container under `UPSTAGE_CACHE_DIR` and are automatically refreshed.
+
+### 3. Verify the deployment
+
+```bash
+BASE=https://YOUR_USERNAME-YOUR_SPACE.hf.space
+curl -sS "$BASE/healthz"
+curl -sS "$BASE/v1/models" | python -m json.tool
+```
+
+## Connect ZCode
+
+ZCode appends `/chat/completions`, so the provider URL must end at **`/v1`**, not at the full endpoint.
+
+In ZCode:
+
+1. Open **Settings → Model settings**.
+2. Select **Add provider → Create custom provider**.
+3. Choose the **OpenAI-compatible / Chat Completions** API format.
+4. Enter:
+
+```text
+Name:      Upstage Solar HF
+Base URL:  https://YOUR_USERNAME-YOUR_SPACE.hf.space/v1
+API key:   public
+Model ID:  solar-pro3
+```
+
+The API key value is only a placeholder. With the default `PUBLIC_ACCESS=true`, the server accepts requests with no Authorization header and ignores arbitrary Bearer values.
+
+Suggested model limits if ZCode asks for them:
+
+```text
+Context: 131072
+Output:   65536
+```
+
+Use the ZCode UI when possible, because its local configuration schema can change. A typical custom-provider shape is:
+
+```json
+{
+  "provider": {
+    "upstage-solar-hf": {
+      "name": "Upstage Solar HF",
+      "kind": "openai-compatible",
+      "source": "custom",
+      "options": {
+        "baseURL": "https://YOUR_USERNAME-YOUR_SPACE.hf.space/v1",
+        "apiKey": "public",
+        "apiKeyRequired": false
+      },
+      "models": {
+        "solar-pro3": {
+          "name": "Solar Pro 3",
+          "limit": {
+            "context": 131072,
+            "output": 65536
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+ZCode will send its coding functions in `tools`; the gateway handles the call/result loop automatically. The server never executes ZCode tools itself—ZCode remains in control of filesystem and terminal operations.
+
+## API examples
+
+Set a local or deployed base URL:
+
+```bash
+BASE=http://127.0.0.1:7860
+```
+
+### Non-streaming chat
+
+```bash
+curl -sS "$BASE/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer public' \
+  -d '{
+    "model": "solar-pro3",
+    "messages": [{"role": "user", "content": "Reply with exactly OK"}],
+    "stream": false,
+    "max_tokens": 64
+  }' | python -m json.tool
+```
+
+### Realtime streaming with usage
+
+```bash
+curl -N "$BASE/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "solar-pro3",
+    "messages": [{"role": "user", "content": "Write a short Python function."}],
+    "stream": true,
+    "stream_options": {"include_usage": true}
+  }'
+```
+
+Reasoning is returned separately in `delta.reasoning_content`; it is not mixed into visible answer text.
+
+### Function call
+
+```bash
+curl -sS "$BASE/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "solar-pro3",
+    "messages": [{"role": "user", "content": "Read src/app.py before answering."}],
+    "tools": [{
+      "type": "function",
+      "function": {
+        "name": "read_file",
+        "description": "Read a workspace file",
+        "parameters": {
+          "type": "object",
+          "properties": {"path": {"type": "string"}},
+          "required": ["path"],
+          "additionalProperties": false
+        }
+      }
+    }],
+    "tool_choice": "required"
+  }' | python -m json.tool
+```
+
+A successful choice has `finish_reason: "tool_calls"`, `message.content: null`, and standard OpenAI `message.tool_calls`.
+
+### Web search
+
+```bash
+curl -sS "$BASE/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "solar-pro3",
+    "messages": [{"role": "user", "content": "What changed in Python recently?"}],
+    "search": true,
+    "reasoning_effort": "high"
+  }' | python -m json.tool
+```
+
+Search uses the source provider's Tavily-backed Upstage mode. Sources are returned in the top-level `sources` array. During streaming, a chunk may carry a top-level `sources` array before answer tokens.
+
+ZCode custom providers do not currently expose arbitrary per-request parameters in every UI version, so `search` is primarily useful to direct API clients unless the client lets you add it.
+
+### Structured JSON
+
+The gateway supports prompt-backed OpenAI response formats:
+
+```json
+"response_format": {"type": "json_object"}
+```
+
+and:
+
+```json
+{
+  "response_format": {
+    "type": "json_schema",
+    "json_schema": {
+      "name": "answer",
+      "schema": {
+        "type": "object",
+        "properties": {"answer": {"type": "string"}},
+        "required": ["answer"]
+      }
+    }
+  }
+}
+```
+
+Unlike function arguments, final structured answer JSON is prompt-backed and is not server-side schema validated.
+
+## Supported request fields
+
+Core fields:
+
+- `model`
+- `messages`
+- `stream`
+- `stream_options.include_usage`
+- `temperature`
+- `max_tokens` or `max_completion_tokens`
+- `reasoning_effort`, or `reasoning: {"effort": ...}`
+- `search`, `web_search`, or `enable_search`
+- `tools`
+- `tool_choice`: `none`, `auto`, `required`, or a specific function
+- `parallel_tool_calls`
+- legacy `functions` and `function_call`
+- `response_format`
+
+Only `n=1` is supported. The anonymous source transport is text-only; image/audio content parts return a clean `unsupported_content_type` error rather than being silently discarded.
+
+## Configuration
+
+All variables are optional:
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `PUBLIC_ACCESS` | `true` | Accept API calls without authentication |
+| `PROVIDER_API_KEY` | empty | Required Bearer key when `PUBLIC_ACCESS=false` |
+| `PORT` | `7860` | HTTP port |
+| `UPSTAGE_CACHE_DIR` | `/home/user/.cache/upstage` in Docker | Credential cache location |
+| `MAX_CONCURRENT_REQUESTS` | `6` | Concurrent Upstage generations |
+| `QUEUE_TIMEOUT_SECONDS` | `20` | Wait for a generation slot |
+| `UPSTREAM_TIMEOUT_SECONDS` | `330` | Per-generation timeout |
+| `UPSTREAM_RETRIES` | `1` | Retry count before any streamed output is committed |
+| `TOOL_PROTOCOL_RETRIES` | `1` | Corrective retries for invalid tool output; capped at 2 |
+| `MAX_BODY_MB` | `4` | Request body limit |
+| `MAX_INPUT_CHARS` | `1000000` | Serialized message limit |
+| `MAX_BUFFERED_OUTPUT_CHARS` | `8000000` | Tool-aware generation buffer limit |
+| `RATE_LIMIT_PER_MINUTE` | `0` | Per-IP in-memory request limit; `0` disables it |
+| `LOG_LEVEL` | `INFO` | Python log level |
+
+The requested public deployment defaults to no authentication and no rate limiter so rapid ZCode tool loops are not accidentally blocked. A concurrency limit still protects the Space.
+
+For a safer later deployment, set:
+
+```text
+PUBLIC_ACCESS=false
+PROVIDER_API_KEY=<long-random-secret>
+```
+
+Then use that secret as the ZCode API key.
+
+## Run locally
+
+### Native Python
+
+```bash
+python -m venv .venv
+. .venv/bin/activate             # Windows: .venv\Scripts\activate
+pip install -r requirements-dev.txt
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+### Docker Compose
+
+```bash
+cp .env.example .env
+docker compose up --build
+```
+
+### Docker directly
+
+```bash
+docker build -t upstage-zcode .
+docker run --rm -p 7860:7860 upstage-zcode
+```
+
+## Tests
+
+Offline unit and adapter tests:
+
+```bash
+pytest -q
+```
+
+Live source-provider tests, including fresh credential capture, realtime timing, search, history, and reasoning separation:
+
+```bash
+UPSTAGE_LIVE=1 pytest -q tests/test_upstage_provider.py -k Live
+```
+
+Full running-server smoke test, including an OpenAI tool call and tool-result continuation:
+
+```bash
+python smoke_test.py http://127.0.0.1:7860
+```
+
+A separate two-step ZCode-style coding probe verifies `tool_choice: auto`, a `read_file` call, its tool result, and a following `write_file` call:
+
+```bash
+python live_zcode_test.py http://127.0.0.1:7860
+```
+
+Both scripts can also target a deployed Space URL. The sandbox's recorded verification results are in [`TESTING.md`](TESTING.md).
+
+## Operational behavior
+
+- Credential discovery is lazy. `/healthz` and `/readyz` stay healthy even if Upstage is temporarily unavailable.
+- The first model request may take a few seconds while Next.js action IDs and cookies are captured.
+- Credentials are cached and automatically refreshed after auth rejection.
+- A streaming request is prefetched through its first Upstage event, so early upstream failures are returned as JSON errors instead of a misleading HTTP 200 SSE stream.
+- If an error occurs after streaming has begun, the server emits an SSE `error` object followed by `[DONE]`.
+- Usage uses Upstage counts when non-zero and a clearly internal character-based estimate when the demo stream reports zeros.
+- Logs contain bounded error summaries, never full prompts or discovered credentials.
+- Free Hugging Face Spaces sleep when idle; the first ZCode request after sleep may be slower.
+- Public Spaces can be used by anyone who knows the URL. In-memory limits are per replica and are not a substitute for authentication.

TESTING.md

@@ -0,0 +1,76 @@
+# Verification record
+
+Tested in the Arena sandbox on **2026-10-07** (Asia/Calcutta).
+
+## Final results
+
+| Layer | Result |
+|---|---|
+| Static Python compilation | passed |
+| Ruff critical checks (`E4,E7,E9,F,I`) on the new API/adapter/tests/scripts | passed |
+| Combined offline suite | **114 passed, 6 live-only skipped** |
+| Original Upstage live suite | **6/6 passed** |
+| Running-server smoke test | all checks passed |
+| Repeated ZCode coding-agent probe | **5/5 complete two-tool loops passed** |
+| OpenAI Python SDK probe | models, JSON chat, SSE+usage, and function call passed |
+| Secret/cache scan | no credential cache, `.env`, PEM, or old-provider reference included |
+
+## Live Upstage coverage
+
+The copied source suite passed live checks for:
+
+1. connection and short chat;
+2. typed realtime streaming;
+3. web-search sources;
+4. multi-turn history;
+5. fresh Next.js credential capture; and
+6. reasoning/content separation with no `<think>` leakage.
+
+## Running API coverage
+
+`smoke_test.py` passed against native Uvicorn on port 7860:
+
+- `/healthz`;
+- four-model discovery;
+- non-streaming Chat Completions;
+- realtime SSE and `[DONE]`;
+- streamed usage;
+- a required OpenAI function call; and
+- a follow-up turn containing an assistant `tool_calls` message and `role: tool` result.
+
+`live_zcode_test.py` was then run five consecutive times. Every run completed this two-step `tool_choice: auto` workflow:
+
+1. Solar selected `read_file` for `README.md`.
+2. The synthetic file result was returned as an OpenAI tool message.
+3. Solar selected `write_file` with schema-valid `path` and `content` arguments.
+
+The repeated run exposed occasional Solar narration instead of a structured call during development. The final adapter now detects that failure mode, performs one strict JSON retry, applies bounded repair only to tool-shaped JSON, validates the selected name and arguments against the caller's schema, and never exposes the narration as a tool call. The five-run verification passed after that fix.
+
+## OpenAI SDK coverage
+
+Using the official `openai` Python package with:
+
+```python
+OpenAI(base_url="http://127.0.0.1:7860/v1", api_key="public")
+```
+
+all of the following passed live:
+
+- `client.models.list()`;
+- non-streaming `client.chat.completions.create(...)`;
+- streaming chunks plus the usage-only chunk; and
+- `tools` + `tool_choice="required"` returning a parsed SDK `tool_calls` object.
+
+## Container note
+
+Docker/Podman is unavailable in this sandbox, so the image itself could not be executed here. The Dockerfile was reviewed statically and follows Hugging Face Docker Space conventions: `sdk: docker`, port `7860`, `0.0.0.0`, a health check, and non-root UID 1000. The exact application and pinned runtime dependencies were exercised natively.
+
+## Re-run
+
+```bash
+pytest -q
+UPSTAGE_LIVE=1 pytest -q tests/test_upstage_provider.py -k Live
+uvicorn app:app --host 0.0.0.0 --port 7860
+python smoke_test.py http://127.0.0.1:7860
+python live_zcode_test.py http://127.0.0.1:7860
+```

app.py

@@ -0,0 +1,919 @@
+"""OpenAI Chat Completions gateway for Upstage Solar and Z.ai ZCode.
+
+The model transport is derived from ``New Upstage Change Logs/upstage_provider.py``.
+This API layer adds canonical OpenAI JSON/SSE responses, request validation,
+reasoning/search metadata, public-Space safety limits, and a constrained function-
+calling adapter for ZCode's agent loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+from html import escape
+from typing import Any, AsyncGenerator, Callable
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse, JSONResponse, Response, StreamingResponse
+
+from tool_protocol import (
+    ParsedToolCall,
+    ToolConfiguration,
+    ToolProtocolError,
+    build_tool_instruction,
+    normalize_messages,
+    parse_embedded_tool_calls,
+    parse_generated_tool_calls,
+    parse_tool_configuration,
+)
+from upstage_provider import (
+    _MODELS,
+    StreamEvent,
+    UpstageAuthError,
+    UpstageError,
+    UpstageProvider,
+    UpstageStreamError,
+    _resolve_model,
+)
+
+
+def env_bool(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def env_int(name: str, default: int, minimum: int = 0) -> int:
+    try:
+        return max(minimum, int(os.getenv(name, str(default))))
+    except ValueError:
+        return max(minimum, default)
+
+
+def env_float(name: str, default: float, minimum: float = 0.0) -> float:
+    try:
+        return max(minimum, float(os.getenv(name, str(default))))
+    except ValueError:
+        return max(minimum, default)
+
+
+SERVICE_NAME = os.getenv("SERVICE_NAME", "Upstage Solar for ZCode")
+PUBLIC_ACCESS = env_bool("PUBLIC_ACCESS", True)
+PROVIDER_API_KEY = os.getenv("PROVIDER_API_KEY", "").strip()
+MAX_BODY_MB = env_int("MAX_BODY_MB", 4, 1)
+MAX_BODY_BYTES = MAX_BODY_MB * 1024 * 1024
+MAX_INPUT_CHARS = env_int("MAX_INPUT_CHARS", 1_000_000, 1_000)
+MAX_CONCURRENT_REQUESTS = env_int("MAX_CONCURRENT_REQUESTS", 6, 1)
+QUEUE_TIMEOUT_SECONDS = env_float("QUEUE_TIMEOUT_SECONDS", 20.0, 0.1)
+UPSTREAM_TIMEOUT_SECONDS = env_float("UPSTREAM_TIMEOUT_SECONDS", 330.0, 30.0)
+UPSTREAM_RETRIES = env_int("UPSTREAM_RETRIES", 1, 0)
+RATE_LIMIT_PER_MINUTE = env_int("RATE_LIMIT_PER_MINUTE", 0, 0)
+TOOL_PROTOCOL_RETRIES = min(env_int("TOOL_PROTOCOL_RETRIES", 1, 0), 2)
+MAX_BUFFERED_OUTPUT_CHARS = env_int("MAX_BUFFERED_OUTPUT_CHARS", 8_000_000, 10_000)
+
+logging.basicConfig(
+    level=os.getenv("LOG_LEVEL", "INFO").upper(),
+    format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+logger = logging.getLogger("upstage-zcode")
+
+request_slots = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
+rate_buckets: dict[str, deque[float]] = defaultdict(deque)
+rate_lock = asyncio.Lock()
+provider_factory: Callable[[], UpstageProvider] = UpstageProvider
+
+
+class ApiProblem(Exception):
+    def __init__(
+        self,
+        message: str,
+        status: int = 400,
+        error_type: str = "invalid_request_error",
+        code: str = "invalid_request",
+        param: str | None = None,
+        headers: dict[str, str] | None = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.error_type = error_type
+        self.code = code
+        self.param = param
+        self.headers = headers or {}
+
+
+@dataclass
+class ChatRequest:
+    model: str
+    messages: list[dict[str, str]]
+    stream: bool
+    include_usage: bool
+    temperature: float | None
+    max_tokens: int | None
+    reasoning: str | None
+    search: bool
+    tools: ToolConfiguration
+    response_instruction: str = ""
+
+
+@dataclass
+class GenerationResult:
+    content: str = ""
+    reasoning: str = ""
+    sources: list[dict[str, Any]] = field(default_factory=list)
+    usage: dict[str, int] = field(default_factory=dict)
+    tool_calls: list[ParsedToolCall] = field(default_factory=list)
+
+
+app = FastAPI(
+    title=SERVICE_NAME,
+    version="2.0.0",
+    description=(
+        "OpenAI-compatible Upstage Solar gateway for ZCode, with realtime SSE, "
+        "reasoning, web search, and validated function calls."
+    ),
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_headers=["*"],
+    expose_headers=["retry-after", "x-request-id", "x-ratelimit-limit"],
+)
+
+
+def error_payload(problem: ApiProblem) -> dict[str, Any]:
+    return {
+        "error": {
+            "message": problem.message,
+            "type": problem.error_type,
+            "param": problem.param,
+            "code": problem.code,
+        }
+    }
+
+
+def error_response(problem: ApiProblem, request_id: str | None = None) -> JSONResponse:
+    headers = dict(problem.headers)
+    if request_id:
+        headers["x-request-id"] = request_id
+    return JSONResponse(error_payload(problem), status_code=problem.status, headers=headers)
+
+
+def client_ip(request: Request) -> str:
+    forwarded = request.headers.get("x-forwarded-for", "")
+    if forwarded:
+        return forwarded.split(",", 1)[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+async def authorize(request: Request) -> None:
+    if PUBLIC_ACCESS:
+        return
+    supplied = request.headers.get("authorization", "")
+    expected = f"Bearer {PROVIDER_API_KEY}"
+    if not PROVIDER_API_KEY or not hmac.compare_digest(supplied, expected):
+        raise ApiProblem(
+            "Invalid or missing API key.",
+            401,
+            "authentication_error",
+            "invalid_api_key",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def enforce_rate_limit(request: Request) -> None:
+    if RATE_LIMIT_PER_MINUTE <= 0:
+        return
+    now = time.monotonic()
+    key = client_ip(request)
+    async with rate_lock:
+        bucket = rate_buckets[key]
+        while bucket and bucket[0] <= now - 60:
+            bucket.popleft()
+        if len(bucket) >= RATE_LIMIT_PER_MINUTE:
+            retry_after = max(1, int(60 - (now - bucket[0])))
+            raise ApiProblem(
+                "Public gateway rate limit reached. Retry shortly.",
+                429,
+                "rate_limit_error",
+                "rate_limit_exceeded",
+                headers={"Retry-After": str(retry_after)},
+            )
+        bucket.append(now)
+
+
+async def read_json_body(request: Request) -> dict[str, Any]:
+    length = request.headers.get("content-length")
+    if length:
+        try:
+            if int(length) > MAX_BODY_BYTES:
+                raise ApiProblem(
+                    f"Request exceeds the {MAX_BODY_MB} MB limit.",
+                    413,
+                    code="request_too_large",
+                )
+        except ValueError:
+            pass
+    body = await request.body()
+    if len(body) > MAX_BODY_BYTES:
+        raise ApiProblem(
+            f"Request exceeds the {MAX_BODY_MB} MB limit.",
+            413,
+            code="request_too_large",
+        )
+    try:
+        payload = json.loads(body)
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ApiProblem("Invalid JSON body.", code="invalid_json") from exc
+    if not isinstance(payload, dict):
+        raise ApiProblem("JSON body must be an object.", code="invalid_body")
+    return payload
+
+
+def parse_chat_request(payload: dict[str, Any]) -> ChatRequest:
+    model_raw = payload.get("model")
+    if not isinstance(model_raw, str) or not model_raw.strip():
+        raise ApiProblem("The 'model' field is required.", param="model", code="missing_model")
+    model = _resolve_model(model_raw)
+    if model not in _MODELS:
+        raise ApiProblem(
+            f"Model {model_raw!r} does not exist. Use GET /v1/models.",
+            404,
+            code="model_not_found",
+            param="model",
+        )
+
+    if payload.get("n", 1) != 1:
+        raise ApiProblem("Only n=1 is supported.", param="n", code="unsupported_parameter")
+    stream = payload.get("stream", False)
+    if not isinstance(stream, bool):
+        raise ApiProblem("'stream' must be a boolean.", param="stream")
+    stream_options = payload.get("stream_options") or {}
+    if not isinstance(stream_options, dict):
+        raise ApiProblem("'stream_options' must be an object.", param="stream_options")
+    include_usage = bool(stream_options.get("include_usage", False))
+
+    temperature = payload.get("temperature")
+    if temperature is not None:
+        if isinstance(temperature, bool) or not isinstance(temperature, (int, float)):
+            raise ApiProblem("'temperature' must be a number.", param="temperature")
+        temperature = float(temperature)
+        if not 0 <= temperature <= 2:
+            raise ApiProblem("'temperature' must be between 0 and 2.", param="temperature")
+
+    max_tokens = payload.get("max_completion_tokens", payload.get("max_tokens"))
+    if max_tokens is not None:
+        if isinstance(max_tokens, bool) or not isinstance(max_tokens, int) or max_tokens < 1:
+            raise ApiProblem("'max_tokens' must be a positive integer.", param="max_tokens")
+        model_limit = int(_MODELS[model]["max_tokens"])
+        if max_tokens > model_limit:
+            raise ApiProblem(
+                f"'max_tokens' exceeds {model!r}'s {model_limit} token limit.",
+                param="max_tokens",
+                code="context_length_exceeded",
+            )
+
+    reasoning = payload.get("reasoning_effort")
+    if reasoning is None and isinstance(payload.get("reasoning"), dict):
+        reasoning = payload["reasoning"].get("effort")
+    if reasoning is not None:
+        valid = _MODELS[model].get("reasoning") or []
+        if not isinstance(reasoning, str) or reasoning not in valid:
+            raise ApiProblem(
+                f"Invalid reasoning effort for {model!r}; choose one of {valid or ['none']}.",
+                param="reasoning_effort",
+            )
+
+    search = payload.get("search", payload.get("web_search", payload.get("enable_search", False)))
+    if not isinstance(search, bool):
+        raise ApiProblem("'search' must be a boolean.", param="search")
+
+    try:
+        tools = parse_tool_configuration(payload)
+    except ToolProtocolError as exc:
+        raise ApiProblem(str(exc), param=exc.param, code=exc.code) from exc
+
+    response_instruction = ""
+    response_format = payload.get("response_format")
+    if response_format is not None:
+        if not isinstance(response_format, dict):
+            raise ApiProblem("'response_format' must be an object.", param="response_format")
+        fmt_type = response_format.get("type", "text")
+        if fmt_type == "json_object":
+            response_instruction = "Return only one valid JSON object, with no Markdown fences."
+        elif fmt_type == "json_schema":
+            schema_wrapper = response_format.get("json_schema")
+            if not isinstance(schema_wrapper, dict):
+                raise ApiProblem(
+                    "'response_format.json_schema' must be an object.",
+                    param="response_format.json_schema",
+                )
+            response_instruction = (
+                "Return only JSON conforming to this response schema, with no Markdown fences:\n"
+                + json.dumps(schema_wrapper, ensure_ascii=False, separators=(",", ":"))
+            )
+        elif fmt_type != "text":
+            raise ApiProblem(
+                f"Unsupported response format {fmt_type!r}.",
+                param="response_format.type",
+                code="unsupported_parameter",
+            )
+
+    instruction_parts = [part for part in (response_instruction, build_tool_instruction(tools)) if part]
+    try:
+        messages = normalize_messages(payload.get("messages"), "\n\n".join(instruction_parts))
+    except ToolProtocolError as exc:
+        raise ApiProblem(str(exc), param=exc.param, code=exc.code) from exc
+    serialized_chars = len(json.dumps(messages, ensure_ascii=False))
+    if serialized_chars > MAX_INPUT_CHARS:
+        raise ApiProblem(
+            f"Serialized messages exceed the {MAX_INPUT_CHARS} character limit.",
+            413,
+            code="input_too_large",
+            param="messages",
+        )
+
+    return ChatRequest(
+        model=model,
+        messages=messages,
+        stream=stream,
+        include_usage=include_usage,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        reasoning=reasoning,
+        search=search,
+        tools=tools,
+        response_instruction=response_instruction,
+    )
+
+
+def estimate_tokens(text: str) -> int:
+    return max(1, round(len(text) / 4)) if text else 0
+
+
+def usage_from_provider(provider: Any, messages: list[dict[str, str]], content: str, reasoning: str) -> dict[str, int]:
+    last = getattr(provider, "last_usage", None)
+    api_usage = getattr(last, "api_usage", None) if last else None
+    if isinstance(api_usage, dict) and api_usage.get("total_tokens"):
+        prompt = int(api_usage.get("prompt_tokens") or 0)
+        completion = int(api_usage.get("completion_tokens") or 0)
+        total = int(api_usage.get("total_tokens") or prompt + completion)
+    else:
+        prompt = estimate_tokens(json.dumps(messages, ensure_ascii=False))
+        completion = estimate_tokens(content + reasoning)
+        total = prompt + completion
+    result: dict[str, Any] = {
+        "prompt_tokens": prompt,
+        "completion_tokens": completion,
+        "total_tokens": total,
+    }
+    if reasoning:
+        result["completion_tokens_details"] = {"reasoning_tokens": estimate_tokens(reasoning)}
+    return result
+
+
+def add_usage(a: dict[str, Any], b: dict[str, Any]) -> dict[str, int]:
+    return {
+        "prompt_tokens": int(a.get("prompt_tokens", 0)) + int(b.get("prompt_tokens", 0)),
+        "completion_tokens": int(a.get("completion_tokens", 0)) + int(b.get("completion_tokens", 0)),
+        "total_tokens": int(a.get("total_tokens", 0)) + int(b.get("total_tokens", 0)),
+    }
+
+
+def provider_stream(provider: Any, chat: ChatRequest, messages: list[dict[str, str]] | None = None):
+    return provider.stream(
+        messages=messages or chat.messages,
+        model=chat.model,
+        reasoning=chat.reasoning,
+        search=chat.search,
+        max_tokens=chat.max_tokens,
+        temperature=chat.temperature,
+    )
+
+
+async def collect_once(chat: ChatRequest, messages: list[dict[str, str]]) -> GenerationResult:
+    provider = provider_factory()
+    content_parts: list[str] = []
+    reasoning_parts: list[str] = []
+    sources: list[dict[str, Any]] = []
+    async with asyncio.timeout(UPSTREAM_TIMEOUT_SECONDS):
+        async for event in provider_stream(provider, chat, messages):
+            if event.kind == "content":
+                content_parts.append(event.text)
+            elif event.kind == "thinking":
+                reasoning_parts.append(event.text)
+            elif event.kind == "sources":
+                try:
+                    parsed = json.loads(event.text)
+                    if isinstance(parsed, dict) and isinstance(parsed.get("sources"), list):
+                        sources = parsed["sources"]
+                except json.JSONDecodeError:
+                    pass
+            if sum(map(len, content_parts)) + sum(map(len, reasoning_parts)) > MAX_BUFFERED_OUTPUT_CHARS:
+                raise ApiProblem(
+                    "The buffered model output exceeded the server safety limit.",
+                    502,
+                    "server_error",
+                    "output_too_large",
+                )
+    content = "".join(content_parts)
+    reasoning = "".join(reasoning_parts)
+    if not sources:
+        sources = list(getattr(provider, "last_sources", []) or [])
+    return GenerationResult(
+        content=content,
+        reasoning=reasoning,
+        sources=sources,
+        usage=usage_from_provider(provider, messages, content, reasoning),
+    )
+
+
+async def collect_with_retry(chat: ChatRequest, messages: list[dict[str, str]]) -> GenerationResult:
+    last_error: Exception | None = None
+    for attempt in range(UPSTREAM_RETRIES + 1):
+        try:
+            return await collect_once(chat, messages)
+        except ApiProblem:
+            raise
+        except (UpstageError, TimeoutError, OSError) as exc:
+            last_error = exc
+            if attempt >= UPSTREAM_RETRIES:
+                break
+            logger.warning("upstream generation failed; retrying attempt=%s error=%s", attempt + 1, type(exc).__name__)
+            await asyncio.sleep(min(2.0, 0.4 * (2**attempt)))
+    assert last_error is not None
+    raise last_error
+
+
+def narrates_unemitted_tool_call(content: str, tools: ToolConfiguration) -> bool:
+    """Detect Solar planning to call a tool but returning narration instead.
+
+    This narrow heuristic is only used to trigger the bounded protocol retry. It
+    avoids turning ordinary ``auto`` answers into forced calls.
+    """
+    text = " ".join(content.lower().split())
+    if not text:
+        return False
+    mentions_catalog = any(tool.name.lower() in text for tool in tools.tools)
+    intent_patterns = (
+        r"\b(?:i|we)\s+(?:will|need to|should|must|have to)\s+(?:now\s+)?(?:use|call|invoke|read|write|edit|create)",
+        r"\b(?:i'll|we'll)\s+(?:now\s+)?(?:use|call|invoke|read|write|edit|create)",
+        r"\b(?:use|using|call|calling|invoke|invoking)\s+(?:the\s+)?[a-z0-9_-]+\s+(?:tool|function)\b",
+        r"\b(?:respond|proceed)\s+with\s+(?:the\s+)?(?:a\s+)?tool call\b",
+    )
+    return mentions_catalog and any(re.search(pattern, text) for pattern in intent_patterns)
+
+
+def last_mentioned_tool(content: str, tools: ToolConfiguration) -> str | None:
+    """Return the catalog function mentioned latest in a narrated response."""
+    lowered = content.lower()
+    positions = [
+        (lowered.rfind(tool.name.lower()), tool.name)
+        for tool in tools.tools
+        if lowered.rfind(tool.name.lower()) >= 0
+    ]
+    return max(positions, default=(-1, None))[1]
+
+
+async def generate_buffered(chat: ChatRequest) -> GenerationResult:
+    """Collect a response, validating/retrying prompt-level function calls."""
+    messages = list(chat.messages)
+    aggregate_usage: dict[str, Any] = {}
+    last_problem: ToolProtocolError | None = None
+    for attempt in range(TOOL_PROTOCOL_RETRIES + 1):
+        result = await collect_with_retry(chat, messages)
+        aggregate_usage = add_usage(aggregate_usage, result.usage)
+        try:
+            narrated_intent = narrates_unemitted_tool_call(result.content, chat.tools)
+            try:
+                calls = parse_generated_tool_calls(result.content, chat.tools)
+            except ToolProtocolError:
+                calls = (
+                    parse_embedded_tool_calls(result.content, chat.tools)
+                    if narrated_intent
+                    else []
+                )
+                if not calls:
+                    raise
+            if not calls and narrated_intent:
+                calls = parse_embedded_tool_calls(result.content, chat.tools)
+                if not calls:
+                    raise ToolProtocolError(
+                        "The model narrated an intended tool call instead of emitting it.",
+                        code="invalid_tool_output",
+                    )
+            if chat.tools.must_call and not calls:
+                raise ToolProtocolError(
+                    "The model did not emit the required function call.",
+                    code="invalid_tool_output",
+                )
+            result.tool_calls = calls
+            result.usage = aggregate_usage
+            return result
+        except ToolProtocolError as exc:
+            last_problem = exc
+            if attempt >= TOOL_PROTOCOL_RETRIES:
+                break
+            logger.warning("tool output validation failed; retrying attempt=%s error=%s", attempt + 1, str(exc)[:200])
+            messages = [message.copy() for message in messages]
+            target = chat.tools.required_name or last_mentioned_tool(
+                result.content, chat.tools
+            )
+            target_text = (
+                f" The required function is {target!r}." if target else ""
+            )
+            strict_retry = (
+                "CORRECTION FOR THIS RETRY: A function call is now mandatory."
+                f"{target_text} Return exactly one plain JSON object with keys "
+                '"name" and "arguments", where "arguments" is a JSON object matching '
+                "the function schema. The first character must be { and the last must "
+                "be }. Do not use special tokens, XML, Markdown, explanation, planning, "
+                "or apologies."
+            )
+            if messages and messages[0].get("role") == "system":
+                messages[0]["content"] += "\n\n" + strict_retry
+            else:
+                messages.insert(0, {"role": "system", "content": strict_retry})
+            # Do not replay the model's narration as an assistant turn: it tends to
+            # anchor Solar into continuing the same prose. Retry from the original
+            # conversation with one terse correction instead.
+            messages.append(
+                {
+                    "role": "user",
+                    "content": (
+                        "TOOL GATEWAY VALIDATION ERROR: "
+                        f"{exc}. Emit the function call now as one plain JSON object: "
+                        '{"name":"FUNCTION_NAME","arguments":{}}. Return no prose.'
+                    ),
+                }
+            )
+    raise ApiProblem(
+        f"Solar could not produce a valid function call after retry: {last_problem}",
+        502,
+        "server_error",
+        "invalid_upstream_tool_call",
+    )
+
+
+def upstream_problem(exc: Exception) -> ApiProblem:
+    if isinstance(exc, ApiProblem):
+        return exc
+    if isinstance(exc, (TimeoutError, asyncio.TimeoutError)):
+        return ApiProblem(
+            "Upstage timed out while generating the response.",
+            504,
+            "server_error",
+            "upstream_timeout",
+        )
+    if isinstance(exc, UpstageAuthError):
+        return ApiProblem(
+            "Could not establish an anonymous Upstage Console session.",
+            502,
+            "server_error",
+            "upstream_auth_error",
+        )
+    if isinstance(exc, (UpstageStreamError, UpstageError, OSError)):
+        return ApiProblem(
+            f"Upstage generation failed: {str(exc)[:240]}",
+            502,
+            "server_error",
+            "upstream_error",
+        )
+    logger.exception("unexpected generation error", exc_info=exc)
+    return ApiProblem(
+        "Internal server error.", 500, "server_error", "internal_error"
+    )
+
+
+def model_object(model_id: str) -> dict[str, Any]:
+    cfg = _MODELS[model_id]
+    return {
+        "id": model_id,
+        "object": "model",
+        "created": 0,
+        "owned_by": "upstage",
+        "permission": [],
+        "capabilities": {
+            "chat_completions": True,
+            "streaming": True,
+            "tools": True,
+            "tool_transport": "validated_prompt_adapter",
+            "reasoning": cfg.get("reasoning") or [],
+            "web_search": bool(cfg.get("search")),
+            "max_output_tokens": cfg.get("max_tokens"),
+        },
+    }
+
+
+def chat_id() -> str:
+    return f"chatcmpl-{uuid.uuid4().hex}"
+
+
+def completion_json(chat: ChatRequest, result: GenerationResult, request_id: str) -> dict[str, Any]:
+    message: dict[str, Any] = {"role": "assistant"}
+    if result.tool_calls:
+        message["content"] = None
+        message["tool_calls"] = [call.as_openai() for call in result.tool_calls]
+        finish_reason = "tool_calls"
+    else:
+        message["content"] = result.content
+        finish_reason = "stop"
+    if result.reasoning:
+        message["reasoning_content"] = result.reasoning
+    body: dict[str, Any] = {
+        "id": chat_id(),
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": chat.model,
+        "system_fingerprint": "upstage-console-zcode-v2",
+        "choices": [{"index": 0, "message": message, "logprobs": None, "finish_reason": finish_reason}],
+        "usage": result.usage,
+    }
+    if result.sources:
+        body["sources"] = result.sources
+    return body
+
+
+def sse(data: dict[str, Any] | str) -> bytes:
+    encoded = data if isinstance(data, str) else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+    return f"data: {encoded}\n\n".encode("utf-8")
+
+
+def stream_chunk(
+    completion_id: str,
+    created: int,
+    model: str,
+    delta: dict[str, Any],
+    finish_reason: str | None = None,
+    **extra: Any,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "id": completion_id,
+        "object": "chat.completion.chunk",
+        "created": created,
+        "model": model,
+        "system_fingerprint": "upstage-console-zcode-v2",
+        "choices": [{"index": 0, "delta": delta, "logprobs": None, "finish_reason": finish_reason}],
+    }
+    body.update(extra)
+    return body
+
+
+async def buffered_sse(chat: ChatRequest, result: GenerationResult) -> AsyncGenerator[bytes, None]:
+    cid, created = chat_id(), int(time.time())
+    yield sse(stream_chunk(cid, created, chat.model, {"role": "assistant", "content": ""}))
+    if result.sources:
+        yield sse(stream_chunk(cid, created, chat.model, {}, sources=result.sources))
+    if result.reasoning:
+        for offset in range(0, len(result.reasoning), 512):
+            yield sse(stream_chunk(cid, created, chat.model, {"reasoning_content": result.reasoning[offset:offset + 512]}))
+    if result.tool_calls:
+        for index, call in enumerate(result.tool_calls):
+            item = call.as_openai()
+            item["index"] = index
+            yield sse(stream_chunk(cid, created, chat.model, {"tool_calls": [item]}))
+        finish = "tool_calls"
+    else:
+        for offset in range(0, len(result.content), 512):
+            yield sse(stream_chunk(cid, created, chat.model, {"content": result.content[offset:offset + 512]}))
+        finish = "stop"
+    yield sse(stream_chunk(cid, created, chat.model, {}, finish))
+    if chat.include_usage:
+        yield sse(
+            {
+                "id": cid,
+                "object": "chat.completion.chunk",
+                "created": created,
+                "model": chat.model,
+                "system_fingerprint": "upstage-console-zcode-v2",
+                "choices": [],
+                "usage": result.usage,
+            }
+        )
+    yield sse("[DONE]")
+
+
+async def acquire_slot() -> None:
+    try:
+        await asyncio.wait_for(request_slots.acquire(), QUEUE_TIMEOUT_SECONDS)
+    except TimeoutError as exc:
+        raise ApiProblem(
+            "The gateway is busy. Retry shortly.",
+            503,
+            "server_error",
+            "gateway_busy",
+            headers={"Retry-After": "5"},
+        ) from exc
+
+
+async def prepare_realtime(chat: ChatRequest):
+    """Open a provider stream and prefetch one event so early failures stay JSON."""
+    last_error: Exception | None = None
+    for attempt in range(UPSTREAM_RETRIES + 1):
+        provider = provider_factory()
+        iterator = provider_stream(provider, chat).__aiter__()
+        try:
+            first = await asyncio.wait_for(anext(iterator), UPSTREAM_TIMEOUT_SECONDS)
+            return provider, iterator, first
+        except StopAsyncIteration:
+            return provider, iterator, StreamEvent("done", "")
+        except (UpstageError, TimeoutError, OSError) as exc:
+            last_error = exc
+            try:
+                await iterator.aclose()
+            except Exception:
+                pass
+            if attempt >= UPSTREAM_RETRIES:
+                break
+            logger.warning("realtime upstream prefetch failed; retrying error=%s", type(exc).__name__)
+            await asyncio.sleep(min(2.0, 0.4 * (2**attempt)))
+    assert last_error is not None
+    raise last_error
+
+
+async def realtime_sse(
+    chat: ChatRequest,
+    provider: Any,
+    iterator: Any,
+    first: StreamEvent,
+) -> AsyncGenerator[bytes, None]:
+    cid, created = chat_id(), int(time.time())
+    sources: list[dict[str, Any]] = []
+    try:
+        yield sse(stream_chunk(cid, created, chat.model, {"role": "assistant", "content": ""}))
+
+        async def emit(event: StreamEvent):
+            nonlocal sources
+            if event.kind == "content":
+                return sse(stream_chunk(cid, created, chat.model, {"content": event.text}))
+            if event.kind == "thinking":
+                return sse(stream_chunk(cid, created, chat.model, {"reasoning_content": event.text}))
+            if event.kind == "sources":
+                try:
+                    parsed = json.loads(event.text)
+                    sources = parsed.get("sources", []) if isinstance(parsed, dict) else []
+                except json.JSONDecodeError:
+                    sources = []
+                return sse(stream_chunk(cid, created, chat.model, {}, sources=sources))
+            return None
+
+        chunk = await emit(first)
+        if chunk:
+            yield chunk
+        async with asyncio.timeout(UPSTREAM_TIMEOUT_SECONDS):
+            async for event in iterator:
+                chunk = await emit(event)
+                if chunk:
+                    yield chunk
+        yield sse(stream_chunk(cid, created, chat.model, {}, "stop"))
+        if chat.include_usage:
+            content = getattr(provider, "last_response", "") or ""
+            reasoning = getattr(provider, "last_reasoning", "") or ""
+            usage = usage_from_provider(provider, chat.messages, content, reasoning)
+            yield sse(
+                {
+                    "id": cid,
+                    "object": "chat.completion.chunk",
+                    "created": created,
+                    "model": chat.model,
+                    "system_fingerprint": "upstage-console-zcode-v2",
+                    "choices": [],
+                    "usage": usage,
+                }
+            )
+        yield sse("[DONE]")
+    except asyncio.CancelledError:
+        raise
+    except Exception as exc:
+        problem = upstream_problem(exc)
+        logger.warning("stream failed code=%s error=%s", problem.code, problem.message[:240])
+        yield sse(error_payload(problem))
+        yield sse("[DONE]")
+    finally:
+        try:
+            await iterator.aclose()
+        except Exception:
+            pass
+        request_slots.release()
+
+
+@app.get("/healthz", include_in_schema=False)
+async def healthz() -> dict[str, Any]:
+    return {"ok": True, "service": SERVICE_NAME, "version": "2.0.0"}
+
+
+@app.get("/readyz", include_in_schema=False)
+async def readyz() -> dict[str, Any]:
+    # Upstream credential capture is intentionally lazy: a transient Upstage outage
+    # must not cause Hugging Face to restart an otherwise healthy container.
+    return {"ready": True, "upstream_credentials": "lazy"}
+
+
+@app.get("/favicon.ico", include_in_schema=False)
+async def favicon() -> Response:
+    return Response(status_code=204)
+
+
+@app.get("/v1/models")
+async def list_models(request: Request) -> Response:
+    try:
+        await authorize(request)
+        return JSONResponse({"object": "list", "data": [model_object(name) for name in _MODELS]})
+    except ApiProblem as problem:
+        return error_response(problem)
+
+
+@app.get("/v1/models/{model_id:path}")
+async def retrieve_model(model_id: str, request: Request) -> Response:
+    try:
+        await authorize(request)
+        model = _resolve_model(model_id)
+        if model not in _MODELS:
+            raise ApiProblem(f"Model {model_id!r} was not found.", 404, code="model_not_found", param="model")
+        return JSONResponse(model_object(model))
+    except ApiProblem as problem:
+        return error_response(problem)
+
+
+@app.post("/v1/chat/completions")
+async def chat_completions(request: Request) -> Response:
+    request_id = request.headers.get("x-request-id") or f"req_{uuid.uuid4().hex}"
+    slot_acquired = False
+    try:
+        await authorize(request)
+        await enforce_rate_limit(request)
+        payload = await read_json_body(request)
+        chat = parse_chat_request(payload)
+        await acquire_slot()
+        slot_acquired = True
+
+        # Tool-aware responses are buffered so malformed model protocol never leaks
+        # into ZCode as ordinary text. Standard chat remains token-by-token realtime.
+        if chat.tools.enabled:
+            result = await generate_buffered(chat)
+            request_slots.release()
+            slot_acquired = False
+            if chat.stream:
+                return StreamingResponse(
+                    buffered_sse(chat, result),
+                    media_type="text/event-stream",
+                    headers={
+                        "Cache-Control": "no-cache",
+                        "X-Accel-Buffering": "no",
+                        "x-request-id": request_id,
+                    },
+                )
+            return JSONResponse(
+                completion_json(chat, result, request_id),
+                headers={"x-request-id": request_id},
+            )
+
+        if chat.stream:
+            provider, iterator, first = await prepare_realtime(chat)
+            # realtime_sse owns and releases this slot from here onward.
+            slot_acquired = False
+            return StreamingResponse(
+                realtime_sse(chat, provider, iterator, first),
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "X-Accel-Buffering": "no",
+                    "x-request-id": request_id,
+                },
+            )
+
+        result = await collect_with_retry(chat, chat.messages)
+        request_slots.release()
+        slot_acquired = False
+        return JSONResponse(
+            completion_json(chat, result, request_id),
+            headers={"x-request-id": request_id},
+        )
+    except Exception as exc:
+        if slot_acquired:
+            request_slots.release()
+        problem = upstream_problem(exc)
+        logger.warning("request failed request_id=%s code=%s error=%s", request_id, problem.code, problem.message[:240])
+        return error_response(problem, request_id)
+
+
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def home() -> HTMLResponse:
+    models = "".join(f"<code>{escape(name)}</code>" for name in _MODELS)
+    return HTMLResponse(
+        f"""<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{escape(SERVICE_NAME)}</title><style>
+:root{{--bg:#07111f;--card:#0d1b2e;--line:#203552;--text:#eaf2ff;--muted:#98abc7;--sun:#ffbf47;--ok:#53dda3}}*{{box-sizing:border-box}}body{{margin:0;min-height:100vh;background:radial-gradient(circle at 20% 0,#16335b 0,transparent 37%),var(--bg);color:var(--text);font:16px/1.55 ui-sans-serif,system-ui,sans-serif;display:grid;place-items:center;padding:28px}}main{{width:min(820px,100%);background:linear-gradient(145deg,rgba(18,40,70,.95),rgba(8,20,36,.98));border:1px solid var(--line);border-radius:24px;padding:clamp(26px,6vw,54px);box-shadow:0 30px 90px #0008}}.eyebrow{{color:var(--sun);font-weight:800;letter-spacing:.14em;text-transform:uppercase;font-size:.78rem}}h1{{font-size:clamp(2rem,6vw,4rem);line-height:1.02;margin:.35em 0}}p{{color:var(--muted);max-width:65ch}}.status{{display:inline-flex;align-items:center;gap:9px;color:var(--ok);font-weight:750}}.dot{{width:9px;height:9px;background:var(--ok);border-radius:50%;box-shadow:0 0 20px var(--ok)}}.grid{{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:14px;margin:28px 0}}.box{{padding:18px;border:1px solid var(--line);border-radius:15px;background:#071423aa}}.box b{{display:block;margin-bottom:7px}}code{{display:inline-block;background:#06101d;border:1px solid var(--line);border-radius:8px;padding:5px 9px;margin:4px;color:#cbe0ff}}a{{color:#7db7ff}}
+</style></head><body><main><div class="eyebrow">Upstage Solar · OpenAI compatible</div><h1>Built for ZCode.</h1><div class="status"><span class="dot"></span>Gateway healthy</div><p>Realtime Chat Completions, separated reasoning, optional web search, and schema-validated OpenAI function calls over the anonymous Upstage Console transport.</p><div class="grid"><div class="box"><b>Provider base URL</b><code>/v1</code></div><div class="box"><b>API key</b><code>public</code></div><div class="box"><b>Endpoints</b><a href="/v1/models">Models</a> · <a href="/docs">API docs</a></div></div><p>{models}</p><p><small>This is an independent compatibility gateway, not an official Upstage service.</small></p></main></body></html>"""
+    )

compose.yaml

@@ -0,0 +1,17 @@
+services:
+  upstage-zcode:
+    build: .
+    ports:
+      - "7860:7860"
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      PORT: "7860"
+      UPSTAGE_CACHE_DIR: /home/user/.cache/upstage
+    volumes:
+      - upstage-cache:/home/user/.cache/upstage
+    restart: unless-stopped
+
+volumes:
+  upstage-cache:

live_zcode_test.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Live two-step coding-agent probe against a running gateway.
+
+It verifies that an OpenAI ``auto`` tool loop selects ``read_file``, accepts the
+returned tool result, then selects ``write_file`` with schema-valid arguments.
+The script does not execute either call.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.request
+
+BASE = (sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:7860").rstrip("/")
+URL = BASE + "/v1/chat/completions"
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read a workspace file",
+            "parameters": {
+                "type": "object",
+                "properties": {"path": {"type": "string"}},
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Create or overwrite a workspace file",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_command",
+            "description": "Execute a shell command",
+            "parameters": {
+                "type": "object",
+                "properties": {"command": {"type": "string"}},
+                "required": ["command"],
+                "additionalProperties": False,
+            },
+        },
+    },
+]
+
+
+def post(messages):
+    payload = {
+        "model": "solar-pro3",
+        "messages": messages,
+        "tools": TOOLS,
+        "tool_choice": "auto",
+        "temperature": 0.1,
+        "max_tokens": 512,
+    }
+    req = urllib.request.Request(
+        URL,
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json", "Authorization": "Bearer public"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=360) as response:
+            return json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        raise AssertionError(f"HTTP {exc.code}: {exc.read().decode()}") from exc
+
+
+def main():
+    system = {"role": "system", "content": "You are a coding agent. Inspect files before editing."}
+    user = {
+        "role": "user",
+        "content": "Inspect README.md using the appropriate tool before you explain the project.",
+    }
+    first = post([system, user])
+    first_choice = first["choices"][0]
+    assert first_choice["finish_reason"] == "tool_calls", first
+    first_call = first_choice["message"]["tool_calls"][0]
+    assert first_call["function"]["name"] == "read_file", first_call
+    assert json.loads(first_call["function"]["arguments"])["path"] == "README.md"
+    print("PASS auto selected read_file")
+
+    second = post(
+        [
+            system,
+            user,
+            first_choice["message"],
+            {
+                "role": "tool",
+                "tool_call_id": first_call["id"],
+                "content": "# Demo Project\nA Python demo.",
+            },
+            {
+                "role": "user",
+                "content": (
+                    'Now create hello.py containing a hello() function that returns "world". '
+                    "Use the appropriate tool."
+                ),
+            },
+        ]
+    )
+    second_choice = second["choices"][0]
+    assert second_choice["finish_reason"] == "tool_calls", second
+    second_call = second_choice["message"]["tool_calls"][0]
+    assert second_call["function"]["name"] == "write_file", second_call
+    arguments = json.loads(second_call["function"]["arguments"])
+    assert arguments["path"] == "hello.py"
+    assert "def hello" in arguments["content"] and "world" in arguments["content"]
+    print("PASS tool result accepted; auto selected write_file")
+    print("ZCODE CODING-AGENT PROBE PASSED")
+
+
+if __name__ == "__main__":
+    main()

pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+pythonpath = .
+testpaths = tests
+addopts = -ra

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+httpx==0.28.1
+pytest==9.0.3

requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.115.12
+uvicorn[standard]==0.34.3
+curl_cffi==0.16.3
+jsonschema==4.26.0

smoke_test.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""End-to-end smoke test for a running local or deployed gateway."""
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.request
+
+BASE = (sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:7860").rstrip("/")
+
+
+def request(path: str, payload=None, stream=False):
+    data = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(
+        BASE + path,
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": "Bearer public",
+            "User-Agent": "upstage-zcode-smoke/2.0",
+        },
+    )
+    try:
+        response = urllib.request.urlopen(req, timeout=360)
+        raw = response.read().decode("utf-8", "replace")
+        return response.status, raw
+    except urllib.error.HTTPError as exc:
+        raise AssertionError(f"HTTP {exc.code} {path}: {exc.read().decode()}") from exc
+
+
+def tool_definition():
+    return {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the current weather in a city",
+            "parameters": {
+                "type": "object",
+                "properties": {"city": {"type": "string"}},
+                "required": ["city"],
+                "additionalProperties": False,
+            },
+        },
+    }
+
+
+def main():
+    status, raw = request("/healthz")
+    assert status == 200 and json.loads(raw)["ok"] is True
+    print("PASS health")
+
+    _, raw = request("/v1/models")
+    ids = [item["id"] for item in json.loads(raw)["data"]]
+    assert "solar-pro3" in ids and "solar-pro2" in ids
+    print(f"PASS models ({len(ids)})")
+
+    _, raw = request(
+        "/v1/chat/completions",
+        {
+            "model": "solar-pro3",
+            "stream": False,
+            "messages": [{"role": "user", "content": "Reply with exactly OK"}],
+            "max_tokens": 32,
+        },
+    )
+    body = json.loads(raw)
+    text = body["choices"][0]["message"]["content"]
+    assert text and "OK" in text.upper()
+    assert body["usage"]["total_tokens"] > 0
+    print("PASS non-streaming chat")
+
+    _, raw = request(
+        "/v1/chat/completions",
+        {
+            "model": "solar-pro3",
+            "stream": True,
+            "stream_options": {"include_usage": True},
+            "messages": [{"role": "user", "content": "Reply with exactly STREAM_OK"}],
+            "max_tokens": 32,
+        },
+    )
+    chunks = []
+    for line in raw.splitlines():
+        if not line.startswith("data: ") or line == "data: [DONE]":
+            continue
+        item = json.loads(line[6:])
+        choices = item.get("choices") or []
+        if choices:
+            chunks.append(choices[0].get("delta", {}).get("content", ""))
+    assert "STREAM_OK" in "".join(chunks)
+    assert "data: [DONE]" in raw
+    assert '"choices":[]' in raw and '"usage"' in raw
+    print("PASS realtime SSE + usage")
+
+    _, raw = request(
+        "/v1/chat/completions",
+        {
+            "model": "solar-pro3",
+            "stream": False,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "Use get_weather to check Delhi. Do not guess the weather.",
+                }
+            ],
+            "tools": [tool_definition()],
+            "tool_choice": "required",
+            "temperature": 0.1,
+            "max_tokens": 256,
+        },
+    )
+    body = json.loads(raw)
+    choice = body["choices"][0]
+    assert choice["finish_reason"] == "tool_calls"
+    call = choice["message"]["tool_calls"][0]
+    assert call["function"]["name"] == "get_weather"
+    arguments = json.loads(call["function"]["arguments"])
+    assert "delhi" in arguments["city"].lower()
+    print("PASS required function call")
+
+    _, raw = request(
+        "/v1/chat/completions",
+        {
+            "model": "solar-pro3",
+            "stream": False,
+            "messages": [
+                {"role": "user", "content": "Use get_weather to check Delhi, then summarize."},
+                {"role": "assistant", "content": None, "tool_calls": [call]},
+                {
+                    "role": "tool",
+                    "tool_call_id": call["id"],
+                    "content": json.dumps({"city": "Delhi", "temperature_c": 31, "condition": "clear"}),
+                },
+            ],
+            "tools": [tool_definition()],
+            "tool_choice": "auto",
+            "temperature": 0.1,
+            "max_tokens": 256,
+        },
+    )
+    body = json.loads(raw)
+    followup = body["choices"][0]
+    assert followup["finish_reason"] == "stop"
+    assert followup["message"]["content"]
+    print("PASS tool-result continuation")
+    print("ALL SMOKE TESTS PASSED")
+
+
+if __name__ == "__main__":
+    main()

tests/test_app.py

@@ -0,0 +1,379 @@
+from __future__ import annotations
+
+import json
+from collections import deque
+from types import SimpleNamespace
+
+import httpx
+import pytest
+
+import app as gateway
+from upstage_provider import StreamEvent, UpstageStreamError
+
+
+@pytest.fixture
+def anyio_backend():
+    return "asyncio"
+
+
+class FakeProvider:
+    def __init__(self, events=None, error=None, capture=None):
+        self.events = events or []
+        self.error = error
+        self.capture = capture
+        self.last_response = ""
+        self.last_reasoning = ""
+        self.last_sources = []
+        self.last_usage = None
+
+    async def stream(self, **kwargs):
+        if self.capture is not None:
+            self.capture.append(kwargs)
+        if self.error:
+            raise self.error
+        content, reasoning = [], []
+        for event in self.events:
+            if event.kind == "content":
+                content.append(event.text)
+            elif event.kind == "thinking":
+                reasoning.append(event.text)
+            elif event.kind == "sources":
+                self.last_sources = json.loads(event.text).get("sources", [])
+            yield event
+        self.last_response = "".join(content)
+        self.last_reasoning = "".join(reasoning)
+        self.last_usage = SimpleNamespace(
+            api_usage={"prompt_tokens": 5, "completion_tokens": 3, "total_tokens": 8}
+        )
+
+
+def factory_queue(monkeypatch, providers):
+    queue = deque(providers)
+    monkeypatch.setattr(gateway, "provider_factory", lambda: queue.popleft())
+    return queue
+
+
+@pytest.fixture(autouse=True)
+def reset_config(monkeypatch):
+    gateway.rate_buckets.clear()
+    monkeypatch.setattr(gateway, "PUBLIC_ACCESS", True)
+    monkeypatch.setattr(gateway, "RATE_LIMIT_PER_MINUTE", 0)
+    monkeypatch.setattr(gateway, "UPSTREAM_RETRIES", 0)
+    monkeypatch.setattr(gateway, "TOOL_PROTOCOL_RETRIES", 1)
+
+
+@pytest.fixture
+def client():
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=gateway.app), base_url="http://test"
+    )
+
+
+@pytest.mark.anyio
+async def test_health_home_and_models(client):
+    health = await client.get("/healthz")
+    ready = await client.get("/readyz")
+    home = await client.get("/")
+    models = await client.get("/v1/models")
+    one = await client.get("/v1/models/solar-pro3")
+    assert health.status_code == ready.status_code == home.status_code == 200
+    assert "Built for ZCode" in home.text
+    assert [item["id"] for item in models.json()["data"]] == [
+        "solar-pro3",
+        "solar-pro2",
+        "syn-pro",
+        "upstage/solar-1-mini-chat",
+    ]
+    assert one.json()["capabilities"]["tools"] is True
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_nonstream_chat_reasoning_sources_and_usage(client, monkeypatch):
+    sources = {"sources": [{"title": "A", "url": "https://a.test", "score": 0.9}]}
+    fake = FakeProvider(
+        [
+            StreamEvent("sources", json.dumps(sources)),
+            StreamEvent("thinking", "hmm"),
+            StreamEvent("content", "O"),
+            StreamEvent("content", "K"),
+            StreamEvent("done", ""),
+        ]
+    )
+    factory_queue(monkeypatch, [fake])
+    response = await client.post(
+        "/v1/chat/completions",
+        json={
+            "model": "solar-pro3",
+            "messages": [{"role": "user", "content": "hello"}],
+            "search": True,
+            "reasoning_effort": "high",
+        },
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["choices"][0]["message"]["content"] == "OK"
+    assert body["choices"][0]["message"]["reasoning_content"] == "hmm"
+    assert body["sources"][0]["url"] == "https://a.test"
+    assert body["usage"]["total_tokens"] == 8
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_realtime_sse_and_usage(client, monkeypatch):
+    fake = FakeProvider(
+        [
+            StreamEvent("thinking", "plan"),
+            StreamEvent("content", "Hel"),
+            StreamEvent("content", "lo"),
+            StreamEvent("done", ""),
+        ]
+    )
+    factory_queue(monkeypatch, [fake])
+    async with client.stream(
+        "POST",
+        "/v1/chat/completions",
+        json={
+            "model": "solar-pro3",
+            "stream": True,
+            "stream_options": {"include_usage": True},
+            "messages": [{"role": "user", "content": "hello"}],
+        },
+    ) as response:
+        text = (await response.aread()).decode()
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("text/event-stream")
+    assert '"reasoning_content":"plan"' in text
+    assert '"content":"Hel"' in text and '"content":"lo"' in text
+    assert '"choices":[],"usage"' in text
+    assert text.rstrip().endswith("data: [DONE]")
+    await client.aclose()
+
+
+def tool_payload(stream=False, choice="required"):
+    return {
+        "model": "solar-pro3",
+        "stream": stream,
+        "stream_options": {"include_usage": True},
+        "messages": [{"role": "user", "content": "Read app.py"}],
+        "tools": [
+            {
+                "type": "function",
+                "function": {
+                    "name": "read_file",
+                    "description": "Read a file",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"path": {"type": "string"}},
+                        "required": ["path"],
+                        "additionalProperties": False,
+                    },
+                },
+            }
+        ],
+        "tool_choice": choice,
+    }
+
+
+TOOL_WIRE = (
+    '<|tool_call:begin|>q123q<|tool_call:name|>read_file'
+    '<|tool_call:args|>{"path":"app.py"}<|tool_call:end|>'
+)
+
+
+@pytest.mark.anyio
+async def test_nonstream_validated_tool_call(client, monkeypatch):
+    capture = []
+    fake = FakeProvider([StreamEvent("content", TOOL_WIRE), StreamEvent("done", "")], capture=capture)
+    factory_queue(monkeypatch, [fake])
+    response = await client.post("/v1/chat/completions", json=tool_payload())
+    assert response.status_code == 200
+    choice = response.json()["choices"][0]
+    assert choice["finish_reason"] == "tool_calls"
+    call = choice["message"]["tool_calls"][0]
+    assert call["function"]["name"] == "read_file"
+    assert json.loads(call["function"]["arguments"]) == {"path": "app.py"}
+    assert "TOOL GATEWAY PROTOCOL" in capture[0]["messages"][0]["content"]
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_streamed_tool_call_is_openai_sse(client, monkeypatch):
+    fake = FakeProvider(
+        [StreamEvent("thinking", "need file"), StreamEvent("content", TOOL_WIRE), StreamEvent("done", "")]
+    )
+    factory_queue(monkeypatch, [fake])
+    response = await client.post("/v1/chat/completions", json=tool_payload(stream=True))
+    text = response.text
+    assert response.status_code == 200
+    assert '"tool_calls":[{"id":"call_' in text
+    assert '"finish_reason":"tool_calls"' in text
+    assert '"reasoning_content":"need file"' in text
+    assert TOOL_WIRE not in text
+    assert "data: [DONE]" in text
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_required_tool_output_retries_once(client, monkeypatch):
+    first = FakeProvider([StreamEvent("content", "I forgot the tool"), StreamEvent("done", "")])
+    second_capture = []
+    second = FakeProvider(
+        [StreamEvent("content", TOOL_WIRE), StreamEvent("done", "")],
+        capture=second_capture,
+    )
+    queue = factory_queue(monkeypatch, [first, second])
+    response = await client.post("/v1/chat/completions", json=tool_payload())
+    assert response.status_code == 200 and not queue
+    retry_messages = second_capture[0]["messages"]
+    assert "VALIDATION ERROR" in retry_messages[-1]["content"]
+    assert response.json()["usage"]["total_tokens"] == 16
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_auto_tool_choice_allows_plain_answer(client, monkeypatch):
+    fake = FakeProvider([StreamEvent("content", "No tool needed."), StreamEvent("done", "")])
+    factory_queue(monkeypatch, [fake])
+    response = await client.post("/v1/chat/completions", json=tool_payload(choice="auto"))
+    assert response.status_code == 200
+    choice = response.json()["choices"][0]
+    assert choice["finish_reason"] == "stop"
+    assert choice["message"]["content"] == "No tool needed."
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_auto_retries_narrated_tool_intent(client, monkeypatch):
+    first = FakeProvider(
+        [
+            StreamEvent(
+                "content",
+                "We need to write the file using the read_file tool. I will call it now.",
+            ),
+            StreamEvent("done", ""),
+        ]
+    )
+    second = FakeProvider([StreamEvent("content", TOOL_WIRE), StreamEvent("done", "")])
+    queue = factory_queue(monkeypatch, [first, second])
+    response = await client.post("/v1/chat/completions", json=tool_payload(choice="auto"))
+    assert response.status_code == 200 and not queue
+    assert response.json()["choices"][0]["finish_reason"] == "tool_calls"
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_tool_result_round_trip_is_normalized(client, monkeypatch):
+    capture = []
+    fake = FakeProvider([StreamEvent("content", "The file says OK."), StreamEvent("done", "")], capture=capture)
+    factory_queue(monkeypatch, [fake])
+    payload = tool_payload(choice="auto")
+    payload["messages"] = [
+        {"role": "user", "content": "Read app.py"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call_previous",
+                    "type": "function",
+                    "function": {"name": "read_file", "arguments": '{"path":"app.py"}'},
+                }
+            ],
+        },
+        {"role": "tool", "tool_call_id": "call_previous", "content": "OK"},
+    ]
+    response = await client.post("/v1/chat/completions", json=payload)
+    assert response.status_code == 200
+    sent = capture[0]["messages"]
+    assert "<|tool_call:name|>read_file" in sent[-2]["content"]
+    assert "TOOL RESULT" in sent[-1]["content"]
+    assert "function: read_file" in sent[-1]["content"]
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_upstream_prefetch_error_stays_json(client, monkeypatch):
+    monkeypatch.setattr(gateway, "UPSTREAM_RETRIES", 0)
+    factory_queue(monkeypatch, [FakeProvider(error=UpstageStreamError("boom"))])
+    response = await client.post(
+        "/v1/chat/completions",
+        json={
+            "model": "solar-pro3",
+            "stream": True,
+            "messages": [{"role": "user", "content": "hi"}],
+        },
+    )
+    assert response.status_code == 502
+    assert response.headers["content-type"].startswith("application/json")
+    assert response.json()["error"]["code"] == "upstream_error"
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_transient_generation_retry(client, monkeypatch):
+    monkeypatch.setattr(gateway, "UPSTREAM_RETRIES", 1)
+    bad = FakeProvider(error=UpstageStreamError("temporary"))
+    good = FakeProvider([StreamEvent("content", "OK"), StreamEvent("done", "")])
+    queue = factory_queue(monkeypatch, [bad, good])
+    response = await client.post(
+        "/v1/chat/completions",
+        json={"model": "solar-pro3", "messages": [{"role": "user", "content": "hi"}]},
+    )
+    assert response.status_code == 200 and not queue
+    assert response.json()["choices"][0]["message"]["content"] == "OK"
+    await client.aclose()
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    "payload,code,status",
+    [
+        ({}, "missing_model", 400),
+        ({"model": "nope", "messages": [{"role": "user", "content": "x"}]}, "model_not_found", 404),
+        ({"model": "solar-pro3", "messages": []}, "invalid_messages", 400),
+        ({"model": "solar-pro3", "messages": [{"role": "user", "content": "x"}], "n": 2}, "unsupported_parameter", 400),
+        ({"model": "solar-pro3", "messages": [{"role": "user", "content": "x"}], "max_tokens": 999999}, "context_length_exceeded", 400),
+    ],
+)
+async def test_clean_validation_errors(client, payload, code, status):
+    response = await client.post("/v1/chat/completions", json=payload)
+    assert response.status_code == status
+    assert response.json()["error"]["code"] == code
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_invalid_json_and_unsupported_image(client):
+    bad = await client.post(
+        "/v1/chat/completions",
+        content=b"{bad",
+        headers={"content-type": "application/json"},
+    )
+    image = await client.post(
+        "/v1/chat/completions",
+        json={
+            "model": "solar-pro3",
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [{"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}}],
+                }
+            ],
+        },
+    )
+    assert bad.status_code == 400 and bad.json()["error"]["code"] == "invalid_json"
+    assert image.status_code == 400
+    assert image.json()["error"]["code"] == "unsupported_content_type"
+    await client.aclose()
+
+
+@pytest.mark.anyio
+async def test_optional_auth(client, monkeypatch):
+    monkeypatch.setattr(gateway, "PUBLIC_ACCESS", False)
+    monkeypatch.setattr(gateway, "PROVIDER_API_KEY", "secret")
+    denied = await client.get("/v1/models")
+    allowed = await client.get("/v1/models", headers={"authorization": "Bearer secret"})
+    assert denied.status_code == 401
+    assert allowed.status_code == 200
+    await client.aclose()

tests/test_tool_protocol.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from tool_protocol import (
+    ToolProtocolError,
+    build_tool_instruction,
+    normalize_messages,
+    parse_embedded_tool_calls,
+    parse_generated_tool_calls,
+    parse_tool_configuration,
+)
+
+
+def payload(**overrides):
+    base = {
+        "tools": [
+            {
+                "type": "function",
+                "function": {
+                    "name": "read_file",
+                    "description": "Read a file",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"path": {"type": "string"}},
+                        "required": ["path"],
+                        "additionalProperties": False,
+                    },
+                },
+            }
+        ]
+    }
+    base.update(overrides)
+    return base
+
+
+def native(name="read_file", arguments=None, call_id="q123q"):
+    arguments = arguments or {"path": "src/app.py"}
+    return (
+        f"<|tool_call:begin|>{call_id}<|tool_call:name|>{name}"
+        f"<|tool_call:args|>{json.dumps(arguments)}<|tool_call:end|>"
+    )
+
+
+def test_default_auto_and_instruction():
+    config = parse_tool_configuration(payload())
+    assert config.choice == "auto" and config.enabled
+    instruction = build_tool_instruction(config)
+    assert "read_file" in instruction
+    assert "<|tool_call:begin|>" in instruction
+    assert "answer the user normally" in instruction
+
+
+def test_required_and_specific_choices():
+    required = parse_tool_configuration(payload(tool_choice="required"))
+    assert required.must_call and required.required_name is None
+    specific = parse_tool_configuration(
+        payload(tool_choice={"type": "function", "function": {"name": "read_file"}})
+    )
+    assert specific.choice == "specific"
+    assert specific.required_name == "read_file"
+
+
+def test_none_disables_adapter():
+    config = parse_tool_configuration(payload(tool_choice="none"))
+    assert not config.enabled
+    assert build_tool_instruction(config) == ""
+
+
+def test_legacy_functions_and_function_call():
+    fn = payload()["tools"][0]["function"]
+    config = parse_tool_configuration({"functions": [fn], "function_call": "read_file"})
+    assert config.required_name == "read_file"
+
+
+@pytest.mark.parametrize(
+    "bad,match",
+    [
+        ({"tools": "bad"}, "array"),
+        ({"tools": [{"type": "web_search"}]}, "Only tools"),
+        ({"tools": [{"type": "function", "function": {"name": "bad name"}}]}, "names"),
+        (payload(tool_choice="missing"), "tool_choice"),
+        ({"tools": [], "tool_choice": "required"}, "at least one"),
+    ],
+)
+def test_invalid_tool_configuration(bad, match):
+    with pytest.raises(ToolProtocolError, match=match):
+        parse_tool_configuration(bad)
+
+
+def test_normalize_developer_assistant_calls_and_tool_results():
+    config = parse_tool_configuration(payload())
+    messages = normalize_messages(
+        [
+            {"role": "system", "content": "system"},
+            {"role": "developer", "content": "developer"},
+            {"role": "user", "content": [{"type": "text", "text": "open it"}]},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_old",
+                        "type": "function",
+                        "function": {
+                            "name": "read_file",
+                            "arguments": '{"path":"a.py"}',
+                        },
+                    }
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_old", "content": "print('ok')"},
+        ],
+        build_tool_instruction(config),
+    )
+    assert messages[0]["role"] == "system"
+    assert "[DEVELOPER]" in messages[0]["content"]
+    assert "TOOL GATEWAY PROTOCOL" in messages[0]["content"]
+    assert "<|tool_call:name|>read_file" in messages[2]["content"]
+    assert messages[3]["role"] == "user"
+    assert "function: read_file" in messages[3]["content"]
+
+
+def test_normalize_rejects_image_content():
+    with pytest.raises(ToolProtocolError, match="not supported"):
+        normalize_messages(
+            [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "look"},
+                        {"type": "image_url", "image_url": {"url": "x"}},
+                    ],
+                }
+            ]
+        )
+
+
+def test_parse_native_tool_call_and_schema_validate():
+    config = parse_tool_configuration(payload(tool_choice="required"))
+    calls = parse_generated_tool_calls(native(), config)
+    assert len(calls) == 1
+    assert calls[0].name == "read_file"
+    assert calls[0].arguments == {"path": "src/app.py"}
+    dumped = calls[0].as_openai()
+    assert dumped["id"].startswith("call_")
+    assert json.loads(dumped["function"]["arguments"])["path"] == "src/app.py"
+
+
+def test_parse_multiple_native_calls():
+    tools = payload()["tools"] + [
+        {
+            "type": "function",
+            "function": {
+                "name": "write_file",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
+                    "required": ["path", "content"],
+                },
+            },
+        }
+    ]
+    config = parse_tool_configuration({"tools": tools, "tool_choice": "required"})
+    text = native() + native("write_file", {"path": "b.py", "content": "x"}, "q2q")
+    calls = parse_generated_tool_calls(text, config)
+    assert [call.name for call in calls] == ["read_file", "write_file"]
+
+
+def test_parallel_false_rejects_multiple():
+    tools = payload()["tools"] * 2
+    tools[1] = {"type": "function", "function": {"name": "other", "parameters": {"type": "object"}}}
+    config = parse_tool_configuration(
+        {"tools": tools, "tool_choice": "required", "parallel_tool_calls": False}
+    )
+    with pytest.raises(ToolProtocolError, match="multiple"):
+        parse_generated_tool_calls(native() + native("other", {}, "two"), config)
+
+
+def test_parse_xml_and_raw_json_fallbacks():
+    config = parse_tool_configuration(payload())
+    xml = '<tool_calls>[{"name":"read_file","arguments":{"path":"x"}}]</tool_calls>'
+    assert parse_generated_tool_calls(xml, config)[0].arguments["path"] == "x"
+    raw = '{"name":"read_file","arguments":{"path":"y"}}'
+    assert parse_generated_tool_calls(raw, config)[0].arguments["path"] == "y"
+
+
+def test_ordinary_json_is_not_misclassified():
+    config = parse_tool_configuration(payload())
+    assert parse_generated_tool_calls('{"answer":42}', config) == []
+
+
+def test_unknown_function_rejected():
+    config = parse_tool_configuration(payload())
+    with pytest.raises(ToolProtocolError, match="unknown"):
+        parse_generated_tool_calls(native("delete_everything", {"path": "x"}), config)
+
+
+def test_forced_function_enforced():
+    config = parse_tool_configuration(
+        payload(tool_choice={"type": "function", "function": {"name": "read_file"}})
+    )
+    with pytest.raises(ToolProtocolError, match="was forced"):
+        parse_generated_tool_calls(native("other", {}), config)
+
+
+def test_invalid_json_and_schema_rejected():
+    config = parse_tool_configuration(payload())
+    malformed = "<|tool_call:begin|>x<|tool_call:name|>read_file<|tool_call:args|>{bad}<|tool_call:end|>"
+    with pytest.raises(ToolProtocolError, match="not valid JSON"):
+        parse_generated_tool_calls(malformed, config)
+    with pytest.raises(ToolProtocolError, match="required property"):
+        parse_generated_tool_calls(native(arguments={"wrong": "x"}), config)
+
+
+def test_prose_around_tool_call_rejected():
+    config = parse_tool_configuration(payload())
+    with pytest.raises(ToolProtocolError, match="prose outside"):
+        parse_generated_tool_calls("I will call it: " + native(), config)
+
+
+def test_embedded_json_recovery_prefers_last_valid_call():
+    tools = payload()["tools"] + [
+        {
+            "type": "function",
+            "function": {
+                "name": "write_file",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string"},
+                        "content": {"type": "string"},
+                    },
+                    "required": ["path", "content"],
+                },
+            },
+        }
+    ]
+    config = parse_tool_configuration({"tools": tools})
+    narration = (
+        'For example {"name":"read_file","arguments":{"path":"old"}}. '
+        'I will now use {"name":"write_file","arguments":'
+        '{"path":"hello.py","content":"def hello():\\n    return \\"world\\""}}'
+    )
+    calls = parse_embedded_tool_calls(narration, config)
+    assert len(calls) == 1 and calls[0].name == "write_file"
+    assert calls[0].arguments["path"] == "hello.py"
+
+
+def test_repair_truncated_double_escaped_tool_json():
+    config = parse_tool_configuration(
+        {
+            "tools": [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "write_file",
+                        "parameters": {
+                            "type": "object",
+                            "properties": {
+                                "path": {"type": "string"},
+                                "content": {"type": "string"},
+                            },
+                            "required": ["path", "content"],
+                        },
+                    },
+                }
+            ]
+        }
+    )
+    malformed = (
+        r'{"name":"write_file","arguments":{"path":"hello.py",'
+        r'"content":"def hello():\\n    return \\"world\\""}'
+    )
+    calls = parse_generated_tool_calls(malformed, config)
+    assert calls[0].name == "write_file"
+    assert calls[0].arguments["path"] == "hello.py"
+    assert "world" in calls[0].arguments["content"]
+
+
+def test_incomplete_marker_rejected():
+    config = parse_tool_configuration(payload())
+    with pytest.raises(ToolProtocolError, match="incomplete"):
+        parse_generated_tool_calls("<|tool_call:begin|>oops", config)

tests/test_upstage_provider.py

@@ -0,0 +1,865 @@
+"""
+test_upstage.py — v3 provider test suite
+══════════════════════════════════════════════════════════════
+  Offline (always run):  parser, splitter, sources, models, payload,
+                         stream assembly (canned events), creds, usage.
+  Live (UPSTAGE_LIVE=1): real API — connect, realtime stream, search,
+                         multi-turn, fresh credential capture.
+
+  Run:  python3 -m pytest test_upstage.py -v
+        UPSTAGE_LIVE=1 python3 -m pytest test_upstage.py -k Live -v
+══════════════════════════════════════════════════════════════
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from upstage_provider import (          # noqa: E402
+    UpstageProvider,
+    UpstageAuthError,
+    UpstageStreamError,
+    _SSE,
+    _Sources,
+    _find_action_id,
+    _Creds,
+    _resolve_model,
+    _MODELS,
+    ThinkSplitter,
+    StreamEvent,
+    TurnUsage,
+    SessionUsage,
+)
+
+# think tags built from fragments (literal tags get mangled by file tools)
+_OPEN  = "<" + "think" + ">"
+_CLOSE = "</" + "think" + ">"
+
+LIVE = os.environ.get("UPSTAGE_LIVE") == "1"
+live = pytest.mark.skipif(not LIVE, reason="set UPSTAGE_LIVE=1 for live tests")
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def make_provider(**kw) -> UpstageProvider:
+    up = UpstageProvider(**kw)
+    up._connected = True          # skip credential pipeline in unit tests
+    return up
+
+
+def canned(events: List[Tuple[str, str]]):
+    """A fake _stream_events: assign as up._stream_events = canned([...])."""
+    async def fake(payload):
+        for ev in events:
+            yield ev
+    return fake
+
+
+# ═══════════════════════════════════════════════════════════
+# SSE PARSER
+# ═══════════════════════════════════════════════════════════
+class TestSSE:
+
+    def test_content_delta(self):
+        line = 'data: {"choices":[{"delta":{"content":"hi"},"finish_reason":null}]}'
+        assert _SSE.parse_line(line) == [("t-delta", "hi")]
+
+    def test_reasoning_delta(self):
+        line = 'data: {"choices":[{"delta":{"reasoning_content":"hmm"},"finish_reason":null}]}'
+        assert _SSE.parse_line(line) == [("r-delta", "hmm")]
+
+    def test_done_sentinel(self):
+        assert _SSE.parse_line("data: [DONE]") == [("done", "")]
+
+    def test_finish_stop(self):
+        line = 'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}'
+        assert _SSE.parse_line(line) == [("done", "")]
+
+    def test_empty_delta_skipped(self):
+        line = 'data: {"choices":[{"delta":{"content":""},"finish_reason":null}]}'
+        assert _SSE.parse_line(line) == []
+
+    def test_garbage(self):
+        assert _SSE.parse_line("") == []
+        assert _SSE.parse_line("event: ping") == []
+        assert _SSE.parse_line("data: {not json") == []
+
+    def test_search_start(self):
+        line = ('data: {"search":{"status":{"action":"search_start","description":"d"},'
+                '"search_queries":[{"query":"q1","results":[]}]}}')
+        assert _SSE.parse_line(line) == [("s-start", "q1")]
+
+    def test_search_finish(self):
+        sq = [{"query": "q1", "results": [{"url": "u", "title": "t"}]}]
+        obj = {"search": {"status": {"action": "search_finish", "description": "d"},
+                          "search_queries": sq}}
+        line = "data: " + json.dumps(obj)
+        evs = _SSE.parse_line(line)
+        assert evs == [("source", json.dumps(sq))]
+
+    def test_summarizing(self):
+        line = ('data: {"search":{"status":{"action":"summarizing","description":"sum"},'
+                '"search_queries":null}}')
+        assert _SSE.parse_line(line) == [("s-summary", "sum")]
+
+    def test_usage_zero_ignored(self):
+        line = ('data: {"choices":[{"delta":{"content":"x"},"finish_reason":null}],'
+                '"usage":{"prompt_tokens":0,"completion_tokens":0,"total_tokens":0}}')
+        assert _SSE.parse_line(line) == [("t-delta", "x")]
+
+    def test_usage_nonzero_emitted(self):
+        line = ('data: {"choices":[{"delta":{"content":"x"},"finish_reason":null}],'
+                '"usage":{"prompt_tokens":5,"completion_tokens":7,"total_tokens":12}}')
+        evs = _SSE.parse_line(line)
+        assert evs[0] == ("t-delta", "x")
+        assert evs[1][0] == "usage"
+        assert json.loads(evs[1][1])["total_tokens"] == 12
+
+    def test_usage_with_stop_done_last(self):
+        line = ('data: {"choices":[{"delta":{},"finish_reason":"stop"}],'
+                '"usage":{"prompt_tokens":1,"completion_tokens":2,"total_tokens":3}}')
+        evs = _SSE.parse_line(line)
+        assert [e[0] for e in evs] == ["usage", "done"]
+
+
+# ═══════════════════════════════════════════════════════════
+# ACTION-ID EXTRACTION
+# ═══════════════════════════════════════════════════════════
+class TestFindActionId:
+    A1 = "a" * 42
+    A2 = "b" * 42
+
+    def test_simple(self):
+        js = f'createServerReference)("{self.A1}",x.callServer,void 0,x.findSourceMapURL,"getConsoleCsrfToken")'
+        assert _find_action_id(js, "getConsoleCsrfToken") == self.A1
+
+    def test_cross_wiring_guard(self):
+        """Two actions on one line — id must stay pinned to its own name."""
+        js = (f'createServerReference)("{self.A1}",x.callServer,void 0,x.findSourceMapURL,"authAction"),'
+              f'createServerReference)("{self.A2}",x.callServer,void 0,x.findSourceMapURL,"getConsoleCsrfToken")')
+        assert _find_action_id(js, "getConsoleCsrfToken") == self.A2
+        assert _find_action_id(js, "authAction") == self.A1
+
+    def test_missing(self):
+        assert _find_action_id("nothing here", "getConsoleCsrfToken") is None
+
+    def test_id_length_flexible(self):
+        short = "c" * 40
+        js = f'createServerReference)("{short}",x.callServer,void 0,x.findSourceMapURL,"authAction")'
+        assert _find_action_id(js, "authAction") == short
+
+
+# ═══════════════════════════════════════════════════════════
+# THINK SPLITTER
+# ═══════════════════════════════════════════════════════════
+class TestThinkSplitter:
+
+    def test_plain_content_holds_partial(self):
+        sp = ThinkSplitter()
+        assert sp.feed("ab") == []                       # held: possible partial tag
+        assert sp.feed("let me ") == [("content", "abl")]
+        assert sp.feed("ok") == [("content", "et")]
+        assert sp.flush() == [("content", " me ok")]
+
+    def test_full_block_one_feed(self):
+        sp = ThinkSplitter()
+        # trailing "cd" is held back as a possible partial tag → flush()
+        out = sp.feed(f"ab{_OPEN}R1{_CLOSE}cd")
+        assert out == [("content", "ab"), ("thinking", "R1")]
+        assert sp.flush() == [("content", "cd")]
+
+    def test_open_tag_split_across_feeds(self):
+        sp = ThinkSplitter()
+        assert sp.feed("a<th") == []                     # partial open held
+        assert sp.feed("ink>R") == [("content", "a")]    # open tag completes
+        assert sp.feed("reason") == []                   # short: all held back
+        out = sp.feed(f"more{_CLOSE}after")
+        assert out == [("thinking", "Rreasonmore")]
+        assert sp.flush() == [("content", "after")]
+
+    def test_close_tag_split_across_feeds(self):
+        sp = ThinkSplitter()
+        sp.feed(f"{_OPEN}R")
+        sp.feed("1")
+        out = sp.feed(f"</thi" + "nk>done")
+        assert out == [("thinking", "R1")]
+        assert sp.flush() == [("content", "done")]
+
+    def test_ended_inside_think(self):
+        sp = ThinkSplitter()
+        out = sp.feed(f"{_OPEN}never closed")
+        assert out == [("thinking", "never")]
+        assert sp.flush() == [("thinking", " closed")]
+
+    def test_multiple_blocks(self):
+        sp = ThinkSplitter()
+        out = sp.feed(f"{_OPEN}A{_CLOSE}mid{_OPEN}B{_CLOSE}end")
+        assert out == [("thinking", "A"), ("content", "mid"), ("thinking", "B")]
+        assert sp.flush() == [("content", "end")]
+
+    def test_empty_feed_and_flush(self):
+        sp = ThinkSplitter()
+        assert sp.feed("") == []
+        assert sp.flush() == []
+
+
+# ═══════════════════════════════════════════════════════════
+# SOURCES
+# ═══════════════════════════════════════════════════════════
+class TestSources:
+    RAW = json.dumps([{
+        "query": "q",
+        "results": [
+            {"url": "https://a.com", "title": "A", "score": 0.9,
+             "content": "x" * 300},
+            {"url": "https://a.com", "title": "A-dup", "score": 0.5,
+             "content": "dup"},
+            {"url": "https://b.com", "title": "", "score": 0.7,
+             "content": "B content"},
+            {"url": "", "title": "no-url", "score": 0.1, "content": "skip"},
+        ],
+    }])
+
+    def test_parse_dedup_and_index(self):
+        got = _Sources.parse([self.RAW])
+        assert [s["url"] for s in got] == ["https://a.com", "https://b.com"]
+        assert [s["index"] for s in got] == [1, 2]
+        assert got[0]["query"] == "q"
+        assert got[1]["title"] == "Untitled"
+
+    def test_parse_snippet_truncation(self):
+        got = _Sources.parse([self.RAW])
+        assert len(got[0]["snippet"]) <= 203
+        assert got[0]["snippet"].endswith("...")
+
+    def test_parse_bad_input(self):
+        assert _Sources.parse(["not json", "null", "[]"]) == []
+
+    def test_format_text(self):
+        got = _Sources.parse([self.RAW])
+        txt = _Sources.format_text(got)
+        assert "📚 Sources (2)" in txt
+        assert "https://a.com" in txt and "https://b.com" in txt
+        assert "Score: 0.9000" in txt
+        assert _Sources.format_text([]) == ""
+
+    def test_format_json(self):
+        got = _Sources.parse([self.RAW])
+        blob = json.loads(_Sources.format_json(got))
+        assert len(blob["sources"]) == 2
+        assert set(blob["sources"][0]) == {"title", "url", "score"}
+
+
+# ═══════════════════════════════════════════════════════════
+# MODEL RESOLUTION
+# ═══════════════════════════════════════════════════════════
+class TestModels:
+
+    def test_alias(self):
+        assert _resolve_model("pro2") == "solar-pro2"
+        assert _resolve_model("mini") == "upstage/solar-1-mini-chat"
+        assert _resolve_model("syn") == "syn-pro"
+
+    def test_fuzzy(self):
+        assert _resolve_model("solar-pro") == "solar-pro3"   # first match wins
+
+    def test_unknown_passthrough(self):
+        assert _resolve_model("custom/model") == "custom/model"
+
+    def test_empty_default(self):
+        assert _resolve_model("") == "solar-pro3"
+
+    def test_list_models(self):
+        up = make_provider()
+        models = up.list_models()
+        assert len(models) == 4
+        assert [m for m in models if m["active"]] == [m for m in models if m["name"] == "solar-pro3"]
+
+    def test_model_info(self):
+        info = UpstageProvider.model_info()
+        assert info["thinking"] is True and info["search"] is True
+        assert set(info["models"]) == set(_MODELS)
+
+
+# ═══════════════════════════════════════════════════════════
+# PAYLOAD BUILDER
+# ═══════════════════════════════════════════════════════════
+class TestPayload:
+
+    def _p(self, up, search=False, reasoning=None):
+        return up._build_payload(
+            [{"role": "user", "content": "hi"}], up.model,
+            search, reasoning, None, None)
+
+    def test_basic(self):
+        up = make_provider()
+        p = self._p(up)
+        assert p["stream"] is True and p["model"] == "solar-pro3"
+        assert p["messages"] == [{"role": "user", "content": "hi"}]
+        assert "conversation_id" in p
+
+    def test_search_mode_on_last_user(self):
+        up = make_provider()
+        p = self._p(up, search=True)
+        assert p["messages"][-1]["mode"] == ["search"]
+        assert p["search_provider"] == "tavily"
+        assert p["reasoning_effort"] == "high"      # auto: search → high
+
+    def test_no_search_low_reasoning(self):
+        up = make_provider()
+        p = self._p(up, search=False)
+        assert "mode" not in p["messages"][-1]
+        assert "search_provider" not in p
+        assert p["reasoning_effort"] == "low"       # auto: no search → low
+
+    def test_explicit_reasoning_wins(self):
+        up = make_provider()
+        assert self._p(up, search=True, reasoning="medium")["reasoning_effort"] == "medium"
+        assert self._p(up, search=False, reasoning="high")["reasoning_effort"] == "high"
+
+    def test_invalid_reasoning_ignored(self):
+        up = make_provider()
+        assert self._p(up, search=False, reasoning="banana")["reasoning_effort"] == "low"
+
+    def test_min_model_has_no_reasoning(self):
+        up = make_provider()
+        p = up._build_payload([{"role": "user", "content": "hi"}],
+                              "upstage/solar-1-mini-chat", False, None, None, None)
+        assert "reasoning_effort" not in p
+
+    def test_system_injected(self):
+        up = make_provider(system="SYS")
+        p = self._p(up)
+        assert p["messages"][0] == {"role": "system", "content": "SYS"}
+
+    def test_syn_metadata(self):
+        up = make_provider()
+        p = up._build_payload([{"role": "user", "content": "hi"}],
+                              "syn-pro", False, None, None, None)
+        assert p["metadata"]["quality"] == 4
+
+    def test_input_not_mutated(self):
+        up = make_provider()
+        msgs = [{"role": "user", "content": "hi"}]
+        up._build_payload(msgs, "solar-pro3", True, None, None, None)
+        assert msgs == [{"role": "user", "content": "hi"}]     # no mode added in-place
+
+    def test_overrides(self):
+        up = make_provider(temperature=0.1, max_tokens=55)
+        p = up._build_payload([{"role": "user", "content": "hi"}],
+                              "solar-pro3", False, None, None, None)
+        assert p["temperature"] == 0.1 and p["max_tokens"] == 55
+        p2 = up._build_payload([{"role": "user", "content": "hi"}],
+                               "solar-pro3", False, None, 0.9, 77)
+        assert p2["temperature"] == 0.9 and p2["max_tokens"] == 77
+
+
+# ═══════════════════════════════════════════════════════════
+# STREAM ASSEMBLY (canned events, no network)
+# ═══════════════════════════════════════════════════════════
+class TestStreamAssembly:
+
+    def test_data_mode_basic(self):
+        up = make_provider()
+        up._stream_events = canned([("t-delta", "Hel"), ("t-delta", "lo"),
+                                    ("done", "")])
+
+        async def go():
+            evs = [ev async for ev in up.stream(data="hi")]
+            return evs
+        evs = run(go())
+        # short tokens are held back by the splitter → one merged flush event
+        assert [e.kind for e in evs] == ["content", "done"]
+        assert up.last_response == "Hello"
+        assert up.last_reasoning == ""
+        roles = [m["role"] for m in up.history]
+        assert roles == ["user", "assistant"]
+
+    def test_messages_mode_replaces_history(self):
+        up = make_provider()
+        up._stream_events = canned([("t-delta", "Bob here"), ("done", "")])
+        msgs = [
+            {"role": "system", "content": "You are Bob."},
+            {"role": "user", "content": "Name?"},
+        ]
+
+        async def go():
+            return [ev async for ev in up.stream(messages=msgs)]
+        run(go())
+        assert up.last_response == "Bob here"
+        # messages mode: per-call system is sent but not kept in history
+        assert [m["role"] for m in up.history] == ["user", "assistant"]
+        assert all(m["role"] != "system" for m in up.history)
+
+    def test_r_delta_is_thinking(self):
+        up = make_provider()
+        up._stream_events = canned([("r-delta", "hmm"), ("r-delta", "…"),
+                                    ("t-delta", "yes"), ("done", "")])
+
+        async def go():
+            return [ev async for ev in up.stream(data="q")]
+        evs = run(go())
+        assert [e.kind for e in evs] == ["thinking", "thinking", "content", "done"]
+        assert up.last_reasoning == "hmm…"
+        assert up.last_response == "yes"
+
+    def test_inline_think_splitting(self):
+        up = make_provider()
+        feed = [f"ab{_OPEN}R", f"1{_CLOSE}cd"]         # tags split across tokens
+        up._stream_events = canned([("t-delta", feed[0]),
+                                    ("t-delta", feed[1]), ("done", "")])
+
+        async def go():
+            return [ev async for ev in up.stream(data="q")]
+        evs = run(go())
+        assert "".join(e.text for e in evs if e.kind == "content") == "abcd"
+        assert "".join(e.text for e in evs if e.kind == "thinking") == "R1"
+        assert up.last_response == "abcd"
+        assert up.last_reasoning == "R1"
+
+    def test_think_markup_never_leaks(self):
+        up = make_provider()
+        up._stream_events = canned([
+            ("t-delta", f"x{_OPEN}A{_CLOSE}y"), ("done", "")])
+
+        async def go():
+            return [ev async for ev in up.stream(data="q")]
+        run(go())
+        assert _OPEN not in up.last_response and _CLOSE not in up.last_response
+        assert _OPEN not in up.last_reasoning and _CLOSE not in up.last_reasoning
+
+    def test_sources_yielded_first(self):
+        up = make_provider()
+        sq = [{"query": "q", "results": [{"url": "https://x.com", "title": "X"}]}]
+        up._stream_events = canned([
+            ("s-start", "q"),
+            ("source", json.dumps(sq)),
+            ("s-summary", "sum"),
+            ("t-delta", "Paris"), ("done", "")])
+
+        async def go():
+            return [ev async for ev in up.stream(data="cap of france?", search=True)]
+        evs = run(go())
+        assert evs[0].kind == "sources"
+        blob = json.loads(evs[0].text)
+        assert blob["sources"][0]["url"] == "https://x.com"
+        assert up.last_sources and up.last_sources[0]["url"] == "https://x.com"
+        assert "📚 Sources (1)" in up.last_sources_text
+        assert evs[-1].kind == "done"
+
+    def test_usage_event_captured(self):
+        up = make_provider()
+        up._stream_events = canned([
+            ("t-delta", "x"),
+            ("usage", json.dumps({"prompt_tokens": 5,
+                                  "completion_tokens": 3,
+                                  "total_tokens": 8})),
+            ("done", "")])
+
+        async def go():
+            return [ev async for ev in up.stream(data="q")]
+        run(go())
+        assert up.last_usage.api_usage["total_tokens"] == 8
+        assert up.last_usage.tokens == 8
+        assert up.last_usage.tokens_estimated is False
+
+    def test_last_usage_fields(self):
+        up = make_provider()
+        up._stream_events = canned([("t-delta", "hello world"), ("done", "")])
+
+        async def go():
+            return [ev async for ev in up.stream(data="q")]
+        run(go())
+        u = up.last_usage
+        assert u.ok is True and u.error == ""
+        assert u.model == "solar-pro3"
+        assert u.content_chars == len("hello world")
+        assert u.prompt_chars > 0
+        assert u.first_token_s is not None and u.first_token_s >= 0
+        assert u.elapsed_s >= u.first_token_s
+        assert u.tokens > 0 and u.tokens_estimated is True
+
+    def test_session_usage_accumulates(self):
+        up = make_provider()
+        up._stream_events = canned([("t-delta", "a"), ("done", "")])
+
+        async def go():
+            async for _ in up.stream(data="1"):
+                pass
+            async for _ in up.stream(data="2"):
+                pass
+        run(go())
+        tt = up.session_usage.totals()
+        assert tt["turns"] == 2 and tt["ok"] == 2 and tt["failed"] == 0
+        assert "TOTAL" in up.session_usage.format_report()
+
+        up.new_session()
+        assert up.session_usage.totals()["turns"] == 0
+        assert up.history == [] and up.last_response == ""
+        assert up.last_usage is None
+
+    def test_early_break_finalizes_state(self):
+        up = make_provider()
+        up._stream_events = canned([("t-delta", "ab"), ("t-delta", "cd"),
+                                    ("done", "")])
+
+        async def go():
+            n = 0
+            async for ev in up.stream(data="q"):
+                n += 1
+                if n == 1:
+                    break          # consumer abandons mid-stream
+            return n
+        assert run(go()) == 1
+        # state still consistent (both deltas were buffered before the
+        # first yield, so all of it is in last_response)
+        assert up.last_response == "abcd"
+        assert up.last_usage.ok is False
+        assert "interrupted" in up.last_usage.error
+        assert [m["role"] for m in up.history] == ["user"]   # no assistant appended
+
+    def test_auth_retry_succeeds(self):
+        up = make_provider()
+        calls = {"stream": 0, "capture": 0}
+        events = [("t-delta", "ok"), ("done", "")]
+
+        async def fake_stream(payload):
+            calls["stream"] += 1
+            if calls["stream"] == 1:
+                raise UpstageAuthError("401")
+            for ev in events:
+                yield ev
+
+        async def fake_capture():
+            calls["capture"] += 1
+
+        up._stream_events = fake_stream
+        up._creds.capture = fake_capture
+
+        async def go():
+            return [ev async for ev in up.stream(data="q")]
+        evs = run(go())
+        assert [e.kind for e in evs] == ["content", "done"]
+        assert calls["stream"] == 2 and calls["capture"] == 1
+        assert up.last_response == "ok"
+
+    def test_auth_failure_twice_raises(self):
+        up = make_provider()
+        calls = {"capture": 0}
+
+        async def fake_stream(payload):
+            raise UpstageAuthError("403")
+            yield            # pragma: no cover (async-gen marker)
+
+        async def fake_capture():
+            calls["capture"] += 1
+
+        up._stream_events = fake_stream
+        up._creds.capture = fake_capture
+
+        async def go():
+            async for _ in up.stream(data="q"):
+                pass
+        with pytest.raises(UpstageAuthError):
+            run(go())
+        assert calls["capture"] == 1                     # one re-capture, then give up
+        assert up.last_usage.ok is False
+        assert "auth" in up.last_usage.error
+
+    def test_generic_error_wrapped(self):
+        up = make_provider()
+
+        async def fake_stream(payload):
+            raise ConnectionError("socket blew up")
+            yield          # pragma: no cover (async gen marker)
+
+        up._stream_events = fake_stream
+
+        async def go():
+            async for _ in up.stream(data="q"):
+                pass
+        with pytest.raises(UpstageStreamError):
+            run(go())
+        assert up.last_usage.ok is False
+        assert "socket blew up" in up.last_usage.error
+
+    def test_chat_plain_string_contract(self):
+        up = make_provider()
+        sq = [{"query": "q", "results": [{"url": "https://x.com", "title": "X"}]}]
+        up._stream_events = canned([("source", json.dumps(sq)),
+                                    ("t-delta", "Paris"), ("done", "")])
+
+        async def go():
+            return [tok async for tok in up.chat(data="cap?", search=True)]
+        toks = run(go())
+        assert all(isinstance(t, str) for t in toks)
+        assert toks[0].startswith('{"sources"')
+        assert "".join(toks[1:]) == "Paris"
+
+    def test_requires_input(self):
+        up = make_provider()
+
+        async def go():
+            async for _ in up.stream():
+                pass
+        with pytest.raises(ValueError):
+            run(go())
+
+    def test_setters_chainable(self):
+        up = UpstageProvider()
+        out = (up.set_model("pro2").set_system("S").set_search(True)
+               .set_temperature(0.5).set_max_tokens(42))
+        assert out is up
+        assert (up.model, up.system, up.search,
+                up.temperature, up.max_tokens) == ("solar-pro2", "S", True, 0.5, 42)
+
+
+# ═══════════════════════════════════════════════════════════
+# CREDENTIALS (offline bits)
+# ═══════════════════════════════════════════════════════════
+class TestCreds:
+
+    def test_load_missing(self, tmp_path):
+        cr = _Creds(path=tmp_path / "nope.json")
+
+        async def go():
+            return await cr.load()
+        assert run(go()) is False
+
+    def test_save_load_roundtrip(self, tmp_path):
+        p = tmp_path / "sub" / "creds.json"
+        cr = _Creds(path=p)
+        cr.action_token = "a" * 42
+        cr.action_init = "b" * 42
+        cr.cookies = {"session_id": "s1", "other": "o"}
+
+        async def go():
+            await cr.save()
+            cr2 = _Creds(path=p)
+            ok = await cr2.load()
+            return ok, cr2
+        ok, cr2 = run(go())
+        assert ok is True
+        assert cr2.action_token == "a" * 42
+        assert cr2.cookies["session_id"] == "s1"
+        assert cr2.session_id == "s1"
+
+    def test_clear(self, tmp_path):
+        p = tmp_path / "c.json"
+
+        async def go():
+            cr = _Creds(path=p)
+            cr.action_token = "x"
+            await cr.save()
+            await cr.clear()
+            return p.exists()
+        assert run(go()) is False
+
+    def test_verify_without_action_token(self, tmp_path):
+        cr = _Creds(path=tmp_path / "c.json")
+
+        async def go():
+            return await cr.verify()
+        assert run(go()) is None
+
+
+# ═══════════════════════════════════════════════════════════
+# USAGE DEPARTMENT
+# ═══════════════════════════════════════════════════════════
+class TestUsage:
+
+    def test_estimate_tokens(self):
+        u = TurnUsage(model="m", thinking_chars=100, content_chars=100,
+                      elapsed_s=2.0)
+        assert u.tokens == 50
+        assert u.tokens_estimated is True
+        assert u.tokens_per_s == 25.0
+
+    def test_api_tokens_preferred(self):
+        u = TurnUsage(model="m", thinking_chars=100, content_chars=100,
+                      api_usage={"total_tokens": 77})
+        assert u.tokens == 77 and u.tokens_estimated is False
+
+    def test_format_line(self):
+        u = TurnUsage(model="solar-pro3", thinking_chars=120, content_chars=40,
+                      elapsed_s=2.0, first_token_s=0.5, n_sources=2)
+        line = u.format_line()
+        for frag in ("⏱ 2.0s", "first token 0.50s", "~40 tok (est)",
+                     "20 tok/s", "💭 120c", "solar-pro3", "📚 2"):
+            assert frag in line, line
+
+    def test_format_line_failed(self):
+        u = TurnUsage(model="m", ok=False, error="boom")
+        assert "✗" in u.format_line()
+
+    def test_session_report_empty(self):
+        assert "no turns yet" in SessionUsage().format_report()
+
+    def test_session_report_and_totals(self):
+        su = SessionUsage()
+        su.add(TurnUsage(model="m", thinking_chars=40, content_chars=20,
+                         elapsed_s=1.0, n_sources=1))
+        su.add(TurnUsage(model="m", ok=False, error="x", elapsed_s=0.5))
+        tt = su.totals()
+        assert tt["turns"] == 2 and tt["ok"] == 1 and tt["failed"] == 1
+        assert tt["tokens"] == 15
+        rep = su.format_report()
+        assert "📊 Session usage" in rep
+        assert "2 turns (1 ok, 1 failed)" in rep
+        su.clear()
+        assert su.totals()["turns"] == 0
+
+    def test_stream_event_defaults(self):
+        e = StreamEvent(kind="content")
+        assert e.text == ""
+        e2 = StreamEvent(kind="thinking", text="t")
+        assert e2.text == "t"
+
+
+# ═══════════════════════════════════════════════════════════
+# INTERACTIVE (command parsing)
+# ═══════════════════════════════════════════════════════════
+class TestInteractive:
+
+    def test_parse(self):
+        from upstage_interactive import parse_command
+        assert parse_command("/model pro2") == ("model", "pro2")
+        assert parse_command("  /SEARCH off  ") == ("search", "off")
+        assert parse_command("/quit") == ("quit", "")
+        assert parse_command("/") == ("help", "")
+        assert parse_command("hello") == ("chat", "hello")
+        assert parse_command("") == ("help", "")
+        assert parse_command("  ") == ("help", "")
+
+    def test_session_toggles(self):
+        import argparse
+        from upstage_interactive import Session
+        s = Session(argparse.Namespace(model="pro2", search=True, thinking="med"))
+        assert s.up.model == "solar-pro2"
+        assert s.up.search is True
+        assert s.thinking == "medium"
+
+
+# ═══════════════════════════════════════════════════════════
+# LIVE TESTS  (UPSTAGE_LIVE=1)
+# ═══════════════════════════════════════════════════════════
+class TestLive:
+
+    @live
+    def test_connect_and_short_chat(self):
+        up = UpstageProvider()
+
+        async def go():
+            await up.connect()
+            toks = [t async for t in up.chat(data="What is 2+2? One word.",
+                                             max_tokens=60)]
+            return toks
+        toks = run(asyncio.wait_for(go(), 120))
+        assert up.last_response.strip()
+        assert _OPEN not in up.last_response and _CLOSE not in up.last_response
+        u = up.last_usage
+        assert u.ok is True and u.elapsed_s > 0 and u.tokens > 0
+        assert [m["role"] for m in up.history] == ["user", "assistant"]
+
+    @live
+    def test_stream_typed_and_realtime(self):
+        up = UpstageProvider()
+
+        async def go():
+            loop = asyncio.get_event_loop()
+            token_times = []
+            done_time = None
+            async for ev in up.stream(data="Count 1 to 3, nothing else.",
+                                      max_tokens=80):
+                if ev.kind in ("thinking", "content") and ev.text:
+                    token_times.append(loop.time())
+                elif ev.kind == "done":
+                    done_time = loop.time()
+            return token_times, done_time
+        token_times, done_time = run(asyncio.wait_for(go(), 120))
+        assert len(token_times) >= 1
+        assert done_time is not None
+        # realtime: every token event arrived BEFORE the stream ended
+        assert all(t < done_time for t in token_times)
+        # and arrivals are non-decreasing in time (no buffering reorder)
+        assert token_times == sorted(token_times)
+
+    @live
+    def test_search_sources(self):
+        up = UpstageProvider()
+
+        async def go():
+            events = [ev async for ev in up.stream(
+                data="What is the capital of France? In one word.",
+                search=True, max_tokens=120)]
+            return events
+        events = run(asyncio.wait_for(go(), 180))
+        kinds = [e.kind for e in events]
+        assert "sources" in kinds
+        assert kinds.index("sources") < kinds.index("done")
+        assert up.last_sources
+        assert all(s["url"].startswith("http") for s in up.last_sources[:3])
+        assert "📚 Sources" in up.last_sources_text
+        assert up.last_usage.n_sources >= 1
+
+    @live
+    def test_multi_turn_history(self):
+        up = UpstageProvider()
+
+        async def go():
+            async for _ in up.chat(data="My name is Ada. Remember it.",
+                                   max_tokens=80):
+                pass
+            async for _ in up.chat(data="What is my name? One word.",
+                                   max_tokens=80):
+                pass
+            return up
+        up = run(asyncio.wait_for(go(), 180))
+        roles = [m["role"] for m in up.history]
+        assert roles == ["user", "assistant", "user", "assistant"]
+        assert "ada" in up.last_response.lower()
+        assert up.session_usage.totals()["turns"] == 2
+
+    @live
+    def test_fresh_credential_capture(self, tmp_path):
+        """Full capture pipeline in a clean cache dir (no pre-existing creds)."""
+        old = os.environ.get("UPSTAGE_CACHE_DIR")
+        os.environ["UPSTAGE_CACHE_DIR"] = str(tmp_path)
+        try:
+            up = UpstageProvider()
+
+            async def go():
+                await up.connect()          # cold → capture path
+                return await up._creds.verify()
+            token = run(asyncio.wait_for(go(), 120))
+            assert token
+            assert up._creds.action_token
+            assert (tmp_path / "upstage_creds.json").exists()
+        finally:
+            if old is None:
+                os.environ.pop("UPSTAGE_CACHE_DIR", None)
+            else:
+                os.environ["UPSTAGE_CACHE_DIR"] = old
+
+    @live
+    def test_reasoning_no_leak(self):
+        up = UpstageProvider()
+
+        async def go():
+            async for _ in up.chat(data="Is 97 prime? One word answer.",
+                                   reasoning="high", max_tokens=300):
+                pass
+        run(asyncio.wait_for(go(), 180))
+        assert _OPEN not in up.last_response and _CLOSE not in up.last_response
+        assert _OPEN not in up.last_reasoning and _CLOSE not in up.last_reasoning

tool_protocol.py

@@ -0,0 +1,645 @@
+"""Prompt-level OpenAI function-call adapter for the Upstage demo transport.
+
+Upstage's public Chat API supports native tools, but the anonymous Console demo
+endpoint used by ``upstage_provider.py`` currently ignores ``tools`` and
+``tool_choice``.  Solar itself understands a stable tool-call wire format.  This
+module exposes that format carefully, parses it, validates arguments against the
+client's JSON Schema, and converts it back to standard OpenAI ``tool_calls``.
+"""
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from jsonschema import ValidationError
+from jsonschema.validators import validator_for
+
+_NATIVE_RE = re.compile(
+    r"<\|tool_call:begin\|>(.*?)"
+    r"<\|tool_call:name\|>(.*?)"
+    r"<\|tool_call:args\|>(.*?)"
+    r"<\|tool_call:end\|>",
+    re.DOTALL,
+)
+_XML_RE = re.compile(r"<tool_calls>\s*(.*?)\s*</tool_calls>", re.DOTALL)
+_SINGLE_XML_RE = re.compile(r"<tool_call>\s*(.*?)\s*</tool_call>", re.DOTALL)
+_NAME_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_NATIVE_MARKERS = ("<|tool_call:", "<tool_calls>", "<tool_call>")
+
+
+class ToolProtocolError(ValueError):
+    """A request or generated tool call violates the gateway protocol."""
+
+    def __init__(self, message: str, *, param: str = "tools", code: str = "invalid_tools"):
+        super().__init__(message)
+        self.param = param
+        self.code = code
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+    def prompt_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+        }
+
+
+@dataclass(frozen=True)
+class ParsedToolCall:
+    name: str
+    arguments: dict[str, Any]
+    id: str
+
+    @classmethod
+    def create(cls, name: str, arguments: dict[str, Any]) -> "ParsedToolCall":
+        return cls(name=name, arguments=arguments, id=f"call_{uuid.uuid4().hex[:24]}")
+
+    def as_openai(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "arguments": json.dumps(
+                    self.arguments, ensure_ascii=False, separators=(",", ":")
+                ),
+            },
+        }
+
+
+@dataclass(frozen=True)
+class ToolConfiguration:
+    tools: tuple[ToolSpec, ...]
+    choice: str  # none | auto | required | specific
+    required_name: str | None
+    parallel: bool
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.tools) and self.choice != "none"
+
+    @property
+    def must_call(self) -> bool:
+        return self.choice in {"required", "specific"}
+
+
+def parse_tool_configuration(payload: dict[str, Any]) -> ToolConfiguration:
+    """Validate OpenAI ``tools``/``tool_choice`` (and legacy functions)."""
+    raw_tools = payload.get("tools")
+    if raw_tools is None and payload.get("functions") is not None:
+        raw_functions = payload.get("functions")
+        if not isinstance(raw_functions, list):
+            raise ToolProtocolError("'functions' must be an array.", param="functions")
+        raw_tools = [{"type": "function", "function": item} for item in raw_functions]
+    if raw_tools is None:
+        raw_tools = []
+    if not isinstance(raw_tools, list):
+        raise ToolProtocolError("'tools' must be an array.")
+    if len(raw_tools) > 128:
+        raise ToolProtocolError("At most 128 function tools are supported.")
+
+    specs: list[ToolSpec] = []
+    names: set[str] = set()
+    for index, raw in enumerate(raw_tools):
+        param = f"tools[{index}]"
+        if not isinstance(raw, dict) or raw.get("type", "function") != "function":
+            raise ToolProtocolError(
+                "Only tools with type 'function' are supported.", param=param
+            )
+        fn = raw.get("function")
+        if not isinstance(fn, dict):
+            raise ToolProtocolError("A function object is required.", param=f"{param}.function")
+        name = fn.get("name")
+        if not isinstance(name, str) or not _NAME_RE.fullmatch(name):
+            raise ToolProtocolError(
+                "Function names must be 1-128 letters, digits, underscores, or hyphens.",
+                param=f"{param}.function.name",
+            )
+        if name in names:
+            raise ToolProtocolError(f"Duplicate function name '{name}'.", param=param)
+        names.add(name)
+        description = fn.get("description", "")
+        if description is None:
+            description = ""
+        if not isinstance(description, str):
+            raise ToolProtocolError(
+                "Function description must be a string.",
+                param=f"{param}.function.description",
+            )
+        parameters = fn.get("parameters", {"type": "object"})
+        if not isinstance(parameters, dict):
+            raise ToolProtocolError(
+                "Function parameters must be a JSON Schema object.",
+                param=f"{param}.function.parameters",
+            )
+        specs.append(ToolSpec(name, description[:4000], parameters))
+
+    raw_choice = payload.get("tool_choice", payload.get("function_call"))
+    required_name: str | None = None
+    if raw_choice is None:
+        choice = "auto" if specs else "none"
+    elif isinstance(raw_choice, str):
+        aliases = {"any": "required"}
+        choice = aliases.get(raw_choice, raw_choice)
+        if choice not in {"none", "auto", "required"}:
+            # Legacy function_call may be a function name string.
+            if choice in names:
+                required_name = choice
+                choice = "specific"
+            else:
+                raise ToolProtocolError(
+                    "'tool_choice' must be 'none', 'auto', 'required', or a function object.",
+                    param="tool_choice",
+                )
+    elif isinstance(raw_choice, dict):
+        fn = raw_choice.get("function", raw_choice)
+        required_name = fn.get("name") if isinstance(fn, dict) else None
+        if not isinstance(required_name, str) or required_name not in names:
+            raise ToolProtocolError(
+                "The forced function in 'tool_choice' is not present in 'tools'.",
+                param="tool_choice",
+            )
+        choice = "specific"
+    else:
+        raise ToolProtocolError("Invalid 'tool_choice'.", param="tool_choice")
+
+    if choice in {"auto", "required", "specific"} and not specs:
+        raise ToolProtocolError(
+            "'tool_choice' requires at least one function tool.", param="tool_choice"
+        )
+
+    parallel = payload.get("parallel_tool_calls", True)
+    if not isinstance(parallel, bool):
+        raise ToolProtocolError(
+            "'parallel_tool_calls' must be a boolean.", param="parallel_tool_calls"
+        )
+    return ToolConfiguration(tuple(specs), choice, required_name, parallel)
+
+
+def build_tool_instruction(config: ToolConfiguration) -> str:
+    """Create a bounded, explicit protocol instruction understood by Solar."""
+    if not config.enabled:
+        return ""
+    if config.choice == "specific":
+        choice_text = (
+            f"You MUST request the function {config.required_name!r}. "
+            "Do not choose another function and do not answer in prose."
+        )
+    elif config.choice == "required":
+        choice_text = (
+            "You MUST request at least one listed function. Do not answer in prose."
+        )
+    else:
+        choice_text = (
+            "Request a function when it is useful or necessary. If no function is "
+            "needed, answer the user normally in prose."
+        )
+    parallel_text = (
+        "You may emit several consecutive calls when they are independent."
+        if config.parallel
+        else "Emit at most one function call."
+    )
+    catalog = json.dumps(
+        [tool.prompt_dict() for tool in config.tools],
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+    return f"""
+TOOL GATEWAY PROTOCOL (highest priority for response formatting)
+You can request the functions listed below. Never claim that you cannot use tools.
+{choice_text}
+{parallel_text}
+
+For every function request, emit exactly this format (without Markdown fences):
+<|tool_call:begin|>call_id<|tool_call:name|>FUNCTION_NAME<|tool_call:args|>{{"argument":"value"}}<|tool_call:end|>
+The args section MUST be one valid JSON object conforming to that function's schema.
+For multiple calls, concatenate complete call blocks. A response containing calls must
+contain only call blocks, with no prose before or after. Never narrate that you will,
+should, or need to call a tool: emit the call block immediately instead. For coding tasks,
+reading, writing, editing, searching, or running workspace content requires the matching
+function when one is listed. Tool results from earlier calls are labelled TOOL RESULT in
+the conversation; use them to continue the task.
+
+AVAILABLE FUNCTIONS:
+{catalog}
+END TOOL GATEWAY PROTOCOL
+""".strip()
+
+
+def _content_to_text(content: Any, *, param: str) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        raise ToolProtocolError(
+            "Message content must be a string or an array of text parts.",
+            param=param,
+            code="invalid_messages",
+        )
+    parts: list[str] = []
+    for index, part in enumerate(content):
+        if isinstance(part, str):
+            parts.append(part)
+            continue
+        if not isinstance(part, dict):
+            raise ToolProtocolError(
+                "Message content parts must be objects.",
+                param=f"{param}[{index}]",
+                code="invalid_messages",
+            )
+        kind = part.get("type")
+        if kind in {"text", "input_text", "output_text"}:
+            text = part.get("text", "")
+            if not isinstance(text, str):
+                raise ToolProtocolError(
+                    "Text content must be a string.",
+                    param=f"{param}[{index}].text",
+                    code="invalid_messages",
+                )
+            parts.append(text)
+        else:
+            raise ToolProtocolError(
+                f"Content part type {kind!r} is not supported by this text-only transport.",
+                param=f"{param}[{index}].type",
+                code="unsupported_content_type",
+            )
+    return "\n".join(part for part in parts if part)
+
+
+def _existing_tool_call_wire(tool_calls: Any) -> tuple[str, dict[str, str]]:
+    if tool_calls is None:
+        return "", {}
+    if not isinstance(tool_calls, list):
+        raise ToolProtocolError(
+            "Assistant 'tool_calls' must be an array.",
+            param="messages.tool_calls",
+            code="invalid_messages",
+        )
+    blocks: list[str] = []
+    call_names: dict[str, str] = {}
+    for item in tool_calls:
+        if not isinstance(item, dict) or item.get("type", "function") != "function":
+            raise ToolProtocolError(
+                "Only assistant function tool calls are supported.",
+                param="messages.tool_calls",
+                code="invalid_messages",
+            )
+        fn = item.get("function")
+        name = fn.get("name") if isinstance(fn, dict) else None
+        arguments = fn.get("arguments", "{}") if isinstance(fn, dict) else "{}"
+        if not isinstance(name, str) or not _NAME_RE.fullmatch(name):
+            raise ToolProtocolError(
+                "Assistant tool call has an invalid function name.",
+                param="messages.tool_calls.function.name",
+                code="invalid_messages",
+            )
+        if isinstance(arguments, dict):
+            arguments = json.dumps(arguments, ensure_ascii=False, separators=(",", ":"))
+        if not isinstance(arguments, str):
+            raise ToolProtocolError(
+                "Assistant tool arguments must be a JSON string or object.",
+                param="messages.tool_calls.function.arguments",
+                code="invalid_messages",
+            )
+        call_id = item.get("id")
+        if not isinstance(call_id, str) or not call_id:
+            call_id = f"call_{uuid.uuid4().hex[:24]}"
+        call_names[call_id] = name
+        blocks.append(
+            f"<|tool_call:begin|>{call_id}<|tool_call:name|>{name}"
+            f"<|tool_call:args|>{arguments}<|tool_call:end|>"
+        )
+    return "".join(blocks), call_names
+
+
+def normalize_messages(
+    raw_messages: Any, tool_instruction: str = ""
+) -> list[dict[str, str]]:
+    """Convert OpenAI system/developer/tool turns to demo-supported text turns."""
+    if not isinstance(raw_messages, list) or not raw_messages:
+        raise ToolProtocolError(
+            "'messages' must be a non-empty array.",
+            param="messages",
+            code="invalid_messages",
+        )
+
+    system_parts: list[str] = []
+    turns: list[dict[str, str]] = []
+    known_call_names: dict[str, str] = {}
+
+    for index, message in enumerate(raw_messages):
+        param = f"messages[{index}]"
+        if not isinstance(message, dict):
+            raise ToolProtocolError(
+                "Every message must be an object.", param=param, code="invalid_messages"
+            )
+        role = message.get("role")
+        if role not in {"system", "developer", "user", "assistant", "tool", "function"}:
+            raise ToolProtocolError(
+                f"Unsupported message role {role!r}.",
+                param=f"{param}.role",
+                code="invalid_messages",
+            )
+        content = _content_to_text(message.get("content"), param=f"{param}.content")
+
+        if role in {"system", "developer"}:
+            if content:
+                label = "DEVELOPER" if role == "developer" else "SYSTEM"
+                system_parts.append(f"[{label}]\n{content}")
+        elif role == "assistant":
+            wire, names = _existing_tool_call_wire(message.get("tool_calls"))
+            known_call_names.update(names)
+            combined = content
+            if wire:
+                combined = f"{combined}\n{wire}" if combined else wire
+            turns.append({"role": "assistant", "content": combined})
+        elif role in {"tool", "function"}:
+            call_id = message.get("tool_call_id", "")
+            name = message.get("name") or known_call_names.get(str(call_id), "unknown")
+            turns.append(
+                {
+                    "role": "user",
+                    "content": (
+                        f"TOOL RESULT\ncall_id: {call_id}\nfunction: {name}\n"
+                        f"result:\n{content}\nEND TOOL RESULT"
+                    ),
+                }
+            )
+        else:
+            turns.append({"role": "user", "content": content})
+
+    if tool_instruction:
+        system_parts.append(tool_instruction)
+    if system_parts:
+        turns.insert(0, {"role": "system", "content": "\n\n".join(system_parts)})
+    if not any(turn["role"] == "user" for turn in turns):
+        raise ToolProtocolError(
+            "At least one user or tool-result message is required.",
+            param="messages",
+            code="invalid_messages",
+        )
+    return turns
+
+
+def _coerce_call(item: Any) -> tuple[str, dict[str, Any]]:
+    if not isinstance(item, dict):
+        raise ToolProtocolError(
+            "Generated tool call must be a JSON object.", code="invalid_tool_output"
+        )
+    fn = item.get("function") if isinstance(item.get("function"), dict) else item
+    name = fn.get("name")
+    arguments = fn.get("arguments", fn.get("args"))
+    if isinstance(arguments, str):
+        try:
+            arguments = json.loads(arguments)
+        except json.JSONDecodeError as exc:
+            raise ToolProtocolError(
+                f"Generated arguments for {name!r} are not valid JSON: {exc.msg}.",
+                code="invalid_tool_output",
+            ) from exc
+    if not isinstance(name, str) or not isinstance(arguments, dict):
+        raise ToolProtocolError(
+            "Generated tool call needs a function name and a JSON-object arguments value.",
+            code="invalid_tool_output",
+        )
+    return name.strip(), arguments
+
+
+def _append_missing_json_closers(text: str) -> str | None:
+    """Append only missing ``}``/``]`` delimiters to truncated JSON."""
+    stack: list[str] = []
+    in_string = False
+    escaped = False
+    pairs = {"}": "{", "]": "["}
+    for character in text:
+        if in_string:
+            if escaped:
+                escaped = False
+            elif character == "\\":
+                escaped = True
+            elif character == '"':
+                in_string = False
+            continue
+        if character == '"':
+            in_string = True
+        elif character in "{[":
+            stack.append(character)
+        elif character in "}]":
+            if not stack or stack[-1] != pairs[character]:
+                return None
+            stack.pop()
+    if in_string or escaped:
+        return None
+    closers = "".join("}" if opener == "{" else "]" for opener in reversed(stack))
+    return text + closers
+
+
+def _repair_tool_json(text: str) -> Any | None:
+    """Apply bounded repairs seen in Solar's narrated JSON fallback."""
+    variants = [text]
+    # Solar occasionally double-escapes an arguments object as though it were
+    # itself a JSON string. Try removing exactly one escape layer.
+    collapsed = text.replace("\\\\", "\\")
+    if collapsed != text:
+        variants.append(collapsed)
+    for variant in variants:
+        closed = _append_missing_json_closers(variant)
+        if closed is None:
+            continue
+        try:
+            return json.loads(closed)
+        except json.JSONDecodeError:
+            continue
+    return None
+
+
+def _json_candidates(text: str) -> list[Any]:
+    candidates: list[Any] = []
+    xml_matches = list(_XML_RE.finditer(text))
+    single_matches = list(_SINGLE_XML_RE.finditer(text))
+    for match in xml_matches:
+        try:
+            candidates.append(json.loads(match.group(1)))
+        except json.JSONDecodeError as exc:
+            raise ToolProtocolError(
+                f"Generated <tool_calls> payload is invalid JSON: {exc.msg}.",
+                code="invalid_tool_output",
+            ) from exc
+    for match in single_matches:
+        try:
+            candidates.append(json.loads(match.group(1)))
+        except json.JSONDecodeError as exc:
+            raise ToolProtocolError(
+                f"Generated <tool_call> payload is invalid JSON: {exc.msg}.",
+                code="invalid_tool_output",
+            ) from exc
+    if candidates:
+        residue = _XML_RE.sub("", text)
+        residue = _SINGLE_XML_RE.sub("", residue).strip()
+        if residue:
+            raise ToolProtocolError(
+                "Generated tool calls contained prose outside the call blocks.",
+                code="invalid_tool_output",
+            )
+        return candidates
+
+    stripped = text.strip()
+    if stripped.startswith(("{", "[")):
+        try:
+            value = json.loads(stripped)
+        except json.JSONDecodeError as exc:
+            tool_shaped = '"name"' in stripped and (
+                '"arguments"' in stripped or '"args"' in stripped
+            )
+            value = _repair_tool_json(stripped) if tool_shaped else None
+            if value is None:
+                if tool_shaped:
+                    raise ToolProtocolError(
+                        f"Generated tool-call JSON is malformed: {exc.msg}.",
+                        code="invalid_tool_output",
+                    ) from exc
+                return []
+        # Do not misclassify an ordinary JSON answer as a tool call.
+        if isinstance(value, dict) and (
+            "tool_calls" in value or ("name" in value and ("arguments" in value or "args" in value))
+        ):
+            candidates.append(value.get("tool_calls", value))
+        elif isinstance(value, list) and value and all(
+            isinstance(x, dict) and "name" in x for x in value
+        ):
+            candidates.append(value)
+    return candidates
+
+
+def parse_embedded_tool_calls(
+    text: str, config: ToolConfiguration
+) -> list[ParsedToolCall]:
+    """Recover the last schema-valid call JSON from narrated model output.
+
+    This is intentionally separate from the strict parser. The gateway invokes it
+    only after a narrow detector confirms that Solar is narrating an intended call.
+    It lets a coding turn recover when the model writes the correct call JSON after
+    phrases such as "I will call the tool", while ordinary JSON answers stay text.
+    """
+    decoder = json.JSONDecoder()
+    candidates: list[Any] = []
+    for index, character in enumerate(text):
+        if character not in "{[":
+            continue
+        try:
+            value, _ = decoder.raw_decode(text[index:])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict) and (
+            "tool_calls" in value
+            or ("name" in value and ("arguments" in value or "args" in value))
+        ):
+            candidates.append(value)
+        elif isinstance(value, list) and value and all(
+            isinstance(item, dict) and "name" in item for item in value
+        ):
+            candidates.append(value)
+
+    # The final object is normally the model's actual proposed call; earlier
+    # objects are often examples copied while it reasons about the protocol.
+    for candidate in reversed(candidates):
+        try:
+            return parse_generated_tool_calls(
+                json.dumps(candidate, ensure_ascii=False, separators=(",", ":")),
+                config,
+            )
+        except ToolProtocolError:
+            continue
+    return []
+
+
+def parse_generated_tool_calls(
+    text: str, config: ToolConfiguration
+) -> list[ParsedToolCall]:
+    """Parse and schema-check Solar output, returning OpenAI-ready calls."""
+    if not config.enabled:
+        return []
+
+    raw_calls: list[tuple[str, dict[str, Any]]] = []
+    native_matches = list(_NATIVE_RE.finditer(text))
+    for match in native_matches:
+        name = match.group(2).strip()
+        try:
+            arguments = json.loads(match.group(3).strip())
+        except json.JSONDecodeError as exc:
+            raise ToolProtocolError(
+                f"Generated arguments for {name!r} are not valid JSON: {exc.msg}.",
+                code="invalid_tool_output",
+            ) from exc
+        if not isinstance(arguments, dict):
+            raise ToolProtocolError(
+                f"Generated arguments for {name!r} must be a JSON object.",
+                code="invalid_tool_output",
+            )
+        raw_calls.append((name, arguments))
+    if native_matches and _NATIVE_RE.sub("", text).strip():
+        raise ToolProtocolError(
+            "Generated tool calls contained prose outside the call blocks.",
+            code="invalid_tool_output",
+        )
+
+    if not raw_calls:
+        for value in _json_candidates(text):
+            items = value if isinstance(value, list) else [value]
+            raw_calls.extend(_coerce_call(item) for item in items)
+
+    if not raw_calls:
+        if any(marker in text for marker in _NATIVE_MARKERS):
+            raise ToolProtocolError(
+                "The model emitted an incomplete tool-call block.",
+                code="invalid_tool_output",
+            )
+        return []
+
+    by_name = {tool.name: tool for tool in config.tools}
+    parsed: list[ParsedToolCall] = []
+    for name, arguments in raw_calls:
+        if config.required_name and name != config.required_name:
+            raise ToolProtocolError(
+                f"The model requested {name!r}; {config.required_name!r} was forced.",
+                code="invalid_tool_output",
+            )
+        spec = by_name.get(name)
+        if spec is None:
+            raise ToolProtocolError(
+                f"The model requested unknown function {name!r}.",
+                code="invalid_tool_output",
+            )
+        try:
+            validator_cls = validator_for(spec.parameters)
+            validator_cls.check_schema(spec.parameters)
+            validator_cls(spec.parameters).validate(arguments)
+        except ValidationError as exc:
+            path = ".".join(str(part) for part in exc.absolute_path)
+            where = f" at {path}" if path else ""
+            raise ToolProtocolError(
+                f"Arguments for {name!r} fail its JSON Schema{where}: {exc.message}",
+                code="invalid_tool_output",
+            ) from exc
+        except Exception:
+            # Some clients send permissive vendor JSON-Schema dialects.  Do not
+            # reject a model call solely because the schema itself is unknown.
+            pass
+        parsed.append(ParsedToolCall.create(name, arguments))
+
+    if not config.parallel and len(parsed) > 1:
+        raise ToolProtocolError(
+            "The model emitted multiple calls while parallel_tool_calls is false.",
+            code="invalid_tool_output",
+        )
+    return parsed

upstage_interactive.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""
+══════════════════════════════════════════════════════════════
+  💬  upstage_interactive.py — live chat REPL for Upstage Solar (v3)
+
+  Run:   python3 upstage_interactive.py
+         python3 upstage_interactive.py --model pro2 --search
+         python3 upstage_interactive.py --thinking high
+         python3 upstage_interactive.py --selftest     (offline smoke check)
+
+  Type messages and hit enter — tokens stream in live over a single
+  asyncio loop (curl_cffi AsyncSession, no threads).
+
+  Rendering:
+    assistant ▸ 💭 thinking tokens (dim)
+                📝 answer tokens   (bright)
+       ⏱ 3.2s · first token 1.1s · ~128 tok (est) · 40 tok/s · solar-pro3
+
+  Commands:
+    /help                      this list
+    /models                    list models (★ = active)
+    /model <name|alias>        switch model (solar3, pro2, syn, mini…)
+    /system <text>             set the system prompt
+    /search on|off             web search (auto-high reasoning when on)
+    /think auto|low|med|high   reasoning effort (auto = search-based)
+    /history                   show conversation turns
+    /sources                   show sources from the last search
+    /usage                     session usage report (the usage department)
+    /clear                     drop conversation history
+    /reset                     clear history + last_* state + usage stats
+    /credits                   force credential re-capture (~2-5s)
+    /quit                      exit (also: Ctrl-D)
+══════════════════════════════════════════════════════════════
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from upstage_provider import UpstageProvider   # noqa: E402
+
+# ─────────────────────────────────────────────────────────────
+# colors (auto-off when piped / NO_COLOR set)
+# ─────────────────────────────────────────────────────────────
+HAS_COLOR = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+def c(text: str, code: str) -> str:
+    return f"\033[{code}m{text}\033[0m" if HAS_COLOR else text
+
+DIM, BOLD, CYAN, GREEN, YELLOW, RED, MAGENTA = "2", "1", "36", "32", "33", "31", "35"
+
+PROMPT      = c("you ▸ ", BOLD + CYAN)
+CONT_PROMPT = c("   ⋮ ", BOLD + CYAN)
+BANNER_RULE = "─" * 62
+
+
+# ─────────────────────────────────────────────────────────────
+# command parsing (pure → unit-testable)
+# ─────────────────────────────────────────────────────────────
+VALID_MODELS_ALIASES = {
+    "solar-pro3", "solar-pro2", "syn-pro", "upstage/solar-1-mini-chat",
+    "solar3", "solar2", "syn", "mini", "pro3", "pro2",
+}
+VALID_THINKING = {"auto", "low", "med", "medium", "high"}
+
+
+def parse_command(line: str) -> tuple[str, str]:
+    """
+    '  /model pro2 ' → ("model", "pro2")
+    'hello world'    → ("chat", "hello world")
+    '/'              → ("help", "")
+    """
+    s = line.strip()
+    if not s:
+        return ("help", "")
+    if s.startswith("/"):
+        cmd, _, arg = s[1:].partition(" ")
+        return (cmd.strip().lower() or "help", arg.strip())
+    return ("chat", s)
+
+
+# ─────────────────────────────────────────────────────────────
+# the REPL
+# ─────────────────────────────────────────────────────────────
+class Session:
+    def __init__(self, args):
+        self.up = UpstageProvider(
+            model=args.model or None,
+            search=bool(args.search),
+        )
+        self.thinking: str | None = None
+        if args.thinking and args.thinking != "auto":
+            self.thinking = "medium" if args.thinking == "med" else args.thinking
+
+    # ── one chat turn (realtime, typed events) ───────────
+    async def chat(self, text: str):
+        kwargs: dict = {}
+        if self.thinking:
+            kwargs["reasoning"] = self.thinking
+
+        print(c("assistant ▸ ", BOLD + MAGENTA), end="", flush=True)
+        phase: str | None = None       # None → "thinking" → "content"
+        prefix_len = len("assistant ▸ ")
+        try:
+            async for ev in self.up.stream(data=text, **kwargs):
+                if ev.kind == "sources":
+                    try:
+                        n = len(json.loads(ev.text)["sources"])
+                    except Exception:
+                        n = "?"
+                    print(c(f"  [📚 {n} sources collected]", DIM),
+                          end="", flush=True)
+                elif ev.kind == "thinking":
+                    if phase is None:
+                        print(c("💭 ", YELLOW), end="", flush=True)
+                        phase = "thinking"
+                    print(c(ev.text, DIM), end="", flush=True)
+                elif ev.kind == "content":
+                    if phase is None:
+                        pass  # starts right after "assistant ▸ "
+                    elif phase == "thinking":
+                        print("\n" + " " * prefix_len + c("📝 ", CYAN),
+                              end="", flush=True)
+                    phase = "content"
+                    print(ev.text, end="", flush=True)
+                elif ev.kind == "done":
+                    pass
+            print()  # newline after the stream
+        except KeyboardInterrupt:
+            print()
+            print(c("… (interrupted)", YELLOW))
+            return
+        except Exception as e:
+            print(f"\n⚠  {e}", end="")
+            hint = "  ↳ try: /credits" if "auth" in str(e).lower() else ""
+            print(c(hint, YELLOW if hint else RED))
+            return
+
+        u = self.up.last_usage
+        if u:
+            print(c("   " + u.format_line(), DIM))
+        if self.up.last_sources:
+            for s in self.up.last_sources[:3]:
+                print(c(f"     [{s['index']}] {s['title']} — {s['url']}", DIM))
+            if len(self.up.last_sources) > 3:
+                print(c(f"     … {len(self.up.last_sources) - 3} more "
+                        f"(/sources)", DIM))
+
+    # ── commands ─────────────────────────────────────────
+    async def handle(self, line: str) -> bool:
+        """Return False to quit."""
+        cmd, arg = parse_command(line)
+
+        if cmd == "chat":
+            await self.chat(arg)
+            return True
+
+        if cmd == "quit":
+            print(c("bye 👋", DIM))
+            return False
+
+        if cmd == "help":
+            print(__doc__.split("Commands:")[-1].strip())
+            return True
+
+        if cmd == "models":
+            for m in self.up.list_models():
+                mark = c("★", YELLOW) if m["active"] else " "
+                print(f"  {mark} {m['name']:<28} "
+                      f"reasoning={m['reasoning']}  max_tokens={m['max_tokens']}")
+            return True
+
+        if cmd == "model":
+            if not arg:
+                print(f"  current: {self.up.model}")
+                return True
+            self.up.set_model(arg)
+            print(f"  model → {self.up.model}")
+            return True
+
+        if cmd == "system":
+            self.up.set_system(arg)
+            print(f"  system prompt set ({len(arg)} chars)" if arg
+                  else "  system prompt cleared")
+            return True
+
+        if cmd == "search":
+            on = arg.lower() in ("on", "1", "true", "yes") if arg else None
+            if on is None:
+                print(f"  search is {'ON' if self.up.search else 'off'} "
+                      f"(usage: /search on|off)")
+                return True
+            self.up.set_search(on)
+            print(f"  search {'ON 🔍 (auto-high reasoning)' if on else 'off'}")
+            return True
+
+        if cmd == "think":
+            if not arg:
+                cur = self.thinking or "auto"
+                print(f"  thinking: {cur} (auto = high w/ search, low without)")
+                return True
+            a = arg.lower()
+            if a not in VALID_THINKING:
+                print(c(f"  ✗ unknown effort {arg!r} — use auto|low|med|high", RED))
+                return True
+            self.thinking = ("medium" if a == "med" else a) if a != "auto" else None
+            print(f"  thinking: {self.thinking or 'auto'}")
+            return True
+
+        if cmd == "history":
+            hist = self.up.get_history()
+            if not hist:
+                print("  (empty)")
+                return True
+            for m in hist:
+                body = m["content"].replace("\n", " ")
+                if len(body) > 100:
+                    body = body[:100] + "…"
+                print(f"  {c(m['role'] + ':', DIM)} {body}")
+            return True
+
+        if cmd == "sources":
+            if not self.up.last_sources:
+                print("  (no sources yet — use /search on)")
+                return True
+            print(self.up.last_sources_text)
+            return True
+
+        if cmd in ("usage", "stats"):
+            report = self.up.session_usage.format_report()
+            if "no turns yet" in report:
+                print("  (no turns yet)")
+                return True
+            print(report)
+            return True
+
+        if cmd == "clear":
+            self.up.clear_history()
+            print("  history cleared")
+            return True
+
+        if cmd == "reset":
+            self.up.new_session()
+            print("  session reset (history + sources + traces + usage stats)")
+            return True
+
+        if cmd == "credits":
+            print("  re-capturing credentials (pure HTTP, ~2-5s)…", flush=True)
+            try:
+                await self.up.refresh_credentials()
+                tok = await self.up._creds.verify()
+                print(c("  ✓ fresh credentials" if tok
+                        else "  ✗ verify failed", GREEN if tok else RED))
+            except Exception as e:
+                print(c(f"  ✗ {e}", RED))
+            return True
+
+        print(c(f"  ✗ unknown /{cmd} — try /help", YELLOW))
+        return True
+
+
+# ─────────────────────────────────────────────────────────────
+# async REPL driver — one event loop for the whole session
+# ─────────────────────────────────────────────────────────────
+async def run_repl(s: Session) -> None:
+    print(c("⏳ connecting (cached creds → instant, else ~2-5s capture)…",
+            DIM), flush=True)
+    try:
+        await s.up.connect()
+        print(c("✓ connected", GREEN))
+    except Exception as e:
+        print(c(f"✗ connect failed: {e}\n  (credentials will be retried on "
+                f"first message)", RED))
+    print()
+
+    while True:
+        try:
+            line = input(PROMPT)
+        except (EOFError, KeyboardInterrupt):
+            print(c("\nbye 👋", DIM))
+            return
+
+        # multi-line: trailing backslash continues
+        while line.rstrip().endswith("\\"):
+            try:
+                line = line.rstrip()[:-1] + "\n" + input(CONT_PROMPT)
+            except (EOFError, KeyboardInterrupt):
+                print()
+                return
+
+        if not line.strip():
+            continue
+        try:
+            if not await s.handle(line):
+                return
+        except KeyboardInterrupt:
+            print(c("\n… (cancelled)", YELLOW))
+        except Exception as e:
+            print(c(f"✗ {type(e).__name__}: {e}", RED))
+
+
+# ─────────────────────────────────────────────────────────────
+# selftest — offline smoke check, no network
+# ─────────────────────────────────────────────────────────────
+def selftest() -> int:
+    print("selftest: starting (offline)…")
+    assert parse_command("/model pro2") == ("model", "pro2")
+    assert parse_command("  /SEARCH off  ") == ("search", "off")
+    assert parse_command("/quit") == ("quit", "")
+    assert parse_command("/") == ("help", "")
+    assert parse_command("plain message") == ("chat", "plain message")
+    assert parse_command("") == ("help", "")
+
+    s = Session(argparse.Namespace(model=None, search=False, thinking=None))
+    assert s.up.model == "solar-pro3"
+    s.up.set_model("mini")
+    assert s.up.model == "upstage/solar-1-mini-chat"
+    s.up.set_search(True)
+    assert s.up.search is True
+    assert s.thinking is None
+    assert s.up.list_models()
+    assert UpstageProvider.model_info()["thinking"] is True
+
+    # usage department (offline)
+    from upstage_provider import TurnUsage, SessionUsage, ThinkSplitter
+    tu = TurnUsage(model="solar-pro3", thinking_chars=120, content_chars=40,
+                   elapsed_s=2.0, first_token_s=0.5, n_sources=2)
+    assert tu.tokens == 40                       # (120+40)/4 estimate
+    assert tu.tokens_estimated is True
+    assert "solar-pro3" in tu.format_line()
+    assert "📚 2" in tu.format_line()
+    tu.api_usage = {"prompt_tokens": 10, "completion_tokens": 30, "total_tokens": 40}
+    assert tu.tokens == 40 and tu.tokens_estimated is False
+    su = SessionUsage()
+    su.add(tu)
+    rep = su.format_report()
+    assert "TOTAL" in rep and "1 turns" in rep
+    tu2 = TurnUsage(model="mini", ok=False, error="boom", elapsed_s=1.0)
+    su.add(tu2)
+    assert su.totals()["failed"] == 1
+    # think splitter (last 6 chars held back as possible partial tag)
+    sp = ThinkSplitter()
+    assert sp.feed("ab") == []
+    assert sp.feed("let me ") == [("content", "abl")]
+    assert sp.feed("ok") == [("content", "et")]
+    assert sp.flush() == [("content", " me ok")]
+    sp2 = ThinkSplitter()
+    assert sp2.feed("a<th") == []
+    assert sp2.feed("ink>R") == [("content", "a")]
+    assert sp2.feed("ans") == []
+    assert sp2.flush() == [("thinking", "Rans")]
+    print("selftest: ✅ all checks passed")
+    return 0
+
+
+# ─────────────────────────────────────────────────────────────
+def banner(s: Session):
+    print(c(BANNER_RULE, DIM))
+    print(c("  ☀️  Upstage Solar — interactive (v3, fully async)", BOLD))
+    print(c(BANNER_RULE, DIM))
+    print(f"  {s.up}")
+    print(f"  {c('type /help for commands · /usage for stats · /quit to exit', DIM)}\n")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Upstage Solar REPL")
+    ap.add_argument("--model", default=None,
+                    help="initial model (solar3, pro2, syn, mini, …)")
+    ap.add_argument("--search", action="store_true",
+                    help="start with web search ON")
+    ap.add_argument("--thinking", default="auto",
+                    choices=["auto", "low", "med", "high"],
+                    help="reasoning effort (default: auto)")
+    ap.add_argument("--selftest", action="store_true",
+                    help="run offline smoke checks and exit")
+    args = ap.parse_args()
+
+    if args.selftest:
+        return selftest()
+
+    s = Session(args)
+    banner(s)
+
+    try:
+        asyncio.run(run_repl(s))
+    finally:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except KeyboardInterrupt:
+        print(c("\nbye 👋", DIM))
+        raise SystemExit(0)

upstage_provider.py

@@ -0,0 +1,1374 @@
+"""
+══════════════════════════════════════════════════════════════════
+  ☀️  Upstage Solar Provider  — v3, fully async, curl_cffi only
+
+  Async streaming reasoning model via console.upstage.ai
+  4 models · Web search · Reasoning modes
+  Auto-credentials via PURE HTTP (curl_cffi) · Cached to disk
+  NO requests · NO DrissionPage · NO threads · NO fake "hi" prompt
+
+  ┌────────────────────────────────────────────────────────────┐
+  │  v3 changes (the "realtime" rebuild):                      │
+  │                                                            │
+  │  • 100% asyncio — one event loop, zero thread bridges.     │
+  │    The v2 design ran the completion stream in a worker     │
+  │    thread (plain `requests` + queue polling). v3 streams   │
+  │    with curl_cffi's native AsyncSession:                   │
+  │                                                            │
+  │        async for line in r.aiter_lines():  → yield         │
+  │                                                            │
+  │    Every chunk is parsed and yielded the instant it hits   │
+  │    the socket — true realtime.                             │
+  │  • curl_cffi ONLY — Chrome TLS impersonation on every      │
+  │    call (credentials AND completions). `requests` is gone. │
+  │  • Typed stream: stream() yields StreamEvent(kind, text)   │
+  │    with kind ∈ {"sources","thinking","content","done"}.    │
+  │    chat() stays as the plain-string convenience API.       │
+  │  • Usage department: TurnUsage + SessionUsage.             │
+  │    Every turn records elapsed time, time-to-first-token,   │
+  │    thinking/answer char counts, estimated tokens,          │
+  │    tokens/sec, sources, API-reported usage (when non-zero).│
+  │    → up.last_usage, up.session_usage.format_report()       │
+  └────────────────────────────────────────────────────────────┘
+
+  ┌────────────────────────────────────────────────────────────┐
+  │  Credential Pipeline (v2, kept — no browser):              │
+  │                                                            │
+  │  The console is a Next.js app. Its client JS bundles embed │
+  │  every server action id, e.g.:                             │
+  │                                                            │
+  │    createServerReference)("002f44cb…d5", …,               │
+  │        "getConsoleCsrfToken")                              │
+  │                                                            │
+  │  1. Load cache/upstage_creds.json                          │
+  │  2. Verify CSRF token via RSC POST                         │
+  │  3. Valid?  → Instant start                                │
+  │  4. Invalid → pure-HTTP re-capture:                        │
+  │       a. GET /playground/chat  → session cookies           │
+  │       b. read its JS chunks, regex out the action id       │
+  │          BY NAME (robust to id-length changes)             │
+  │       c. RSC POST (data="[]") → parse the token            │
+  │       d. save cookies + action ids                         │
+  │                                                            │
+  │  First run : ~2-5s   (GET + chunk scan)                    │
+  │  Next runs : ~1-2s   (cached credentials)                  │
+  └────────────────────────────────────────────────────────────┘
+
+  Usage:
+      from upstage_provider import UpstageProvider
+
+      up = UpstageProvider()
+
+      # plain strings (v1/v2 compatible):
+      async for token in up.chat(data="Hello!"):
+          print(token, end="", flush=True)
+
+      # typed, realtime events:
+      async for ev in up.stream(data="What is 2+2?"):
+          if ev.kind == "sources":   print(ev.text)
+          elif ev.kind == "thinking": print(ev.text, end="")   # dim
+          elif ev.kind == "content":  print(ev.text, end="")   # bright
+
+      # after a turn:
+      up.last_response      # text content (no think markup)
+      up.last_reasoning     # reasoning trace
+      up.last_sources       # [{index,title,url}, ...]
+      up.last_usage         # TurnUsage (timing, tokens, …)
+      up.session_usage.format_report()   # the usage department
+══════════════════════════════════════════════════════════════
+"""
+
+from __future__ import annotations
+
+import json
+import os as _os
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, AsyncGenerator, Dict, List, Optional, Tuple
+
+from curl_cffi import requests as _cffi
+
+# ═══════════════════════════════════════════════════════════
+# §1 — CONSTANTS
+# ═══════════════════════════════════════════════════════════
+_CONSOLE  = "https://console.upstage.ai"
+_API_HOST = "https://ap-northeast-2.apistage.ai"
+_CHAT_EP  = "/playground/chat"
+_COMP_URL = f"{_API_HOST}/v1/web/demo/chat/completions?include_think=true"
+
+def _cred_file() -> Path:
+    """Resolved at call time so UPSTAGE_CACHE_DIR can change post-import."""
+    return Path(_os.getenv("UPSTAGE_CACHE_DIR", "/tmp/.cache/upstage")) / \
+        "upstage_creds.json"
+
+_UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/146.0.0.0 Safari/537.36"
+)
+
+# Action names to extract from the client JS bundles (stable across
+# builds — only the 42-hex ids change on redeploys).
+_ACTION_TOKEN = "getConsoleCsrfToken"   # → {"token": "<jwt>"}
+_ACTION_INIT  = "authAction"            # → flight "1:null" (kept for parity)
+
+# Cap on how many JS chunks we scan during capture.
+_MAX_CHUNK_SCAN = 80
+
+_UA_HEADERS = {"User-Agent": _UA}
+
+# (connect_timeout, read_timeout) — curl_cffi makes the total
+# connect+read, so a 5-minute envelope is plenty for long generations.
+_CONNECT_TIMEOUT = 15
+_STREAM_TIMEOUT   = 300
+
+
+def _http_session() -> "_cffi.AsyncSession":
+    """curl_cffi async session impersonating Chrome's TLS fingerprint."""
+    return _cffi.AsyncSession(impersonate="chrome")
+
+
+# ═══════════════════════════════════════════════════════════
+# §2 — ERRORS
+# ═══════════════════════════════════════════════════════════
+class UpstageError(Exception):
+    """Base class for all provider errors."""
+
+
+class UpstageAuthError(UpstageError):
+    """Credentials invalid / rejected — a re-capture was attempted."""
+
+
+class UpstageStreamError(UpstageError):
+    """The stream could not be established or died mid-flight."""
+
+
+# ═══════════════════════════════════════════════════════════
+# §3 — MODEL REGISTRY
+# ═══════════════════════════════════════════════════════════
+_MODELS: Dict[str, Dict[str, Any]] = {
+    "solar-pro3": {
+        "reasoning":   ["low", "medium", "high"],
+        "search":      True,
+        "system":      "",
+        "temperature": 0.8,
+        "max_tokens":  65536,
+        "metadata":    None,
+    },
+    "solar-pro2": {
+        "reasoning":   ["low", "high"],
+        "search":      True,
+        "system":      "",
+        "temperature": 0.8,
+        "max_tokens":  16383,
+        "metadata":    None,
+    },
+    "syn-pro": {
+        "reasoning":   ["low", "high"],
+        "search":      True,
+        "system":      "",
+        "temperature": 0.7,
+        "max_tokens":  16384,
+        "metadata": {
+            "helpfulness": 4, "correctness": 4, "coherence": 4,
+            "complexity": 4, "verbosity": 4, "quality": 4,
+            "toxicity": 0, "humor": 0, "creativity": 0,
+        },
+    },
+    "upstage/solar-1-mini-chat": {
+        "reasoning":   None,
+        "search":      True,
+        "system":      "",
+        "temperature": 0.8,
+        "max_tokens":  16383,
+        "metadata":    None,
+    },
+}
+
+_MODEL_ALIASES: Dict[str, str] = {
+    "solar-pro3": "solar-pro3", "solar-pro2": "solar-pro2",
+    "syn-pro": "syn-pro",
+    "solar-1-mini-chat": "upstage/solar-1-mini-chat",
+    "upstage/solar-1-mini-chat": "upstage/solar-1-mini-chat",
+    "solar3": "solar-pro3", "solar2": "solar-pro2",
+    "pro3": "solar-pro3", "pro2": "solar-pro2",
+    "syn": "syn-pro", "mini": "upstage/solar-1-mini-chat",
+}
+
+
+def _resolve_model(val: str) -> str:
+    if not val:
+        return "solar-pro3"
+    v = val.lower().strip()
+    if v in _MODEL_ALIASES:
+        return _MODEL_ALIASES[v]
+    if v in _MODELS:
+        return v
+    for name in _MODELS:
+        if v in name.lower():
+            return name
+    return val
+
+
+# ════════════════════════════��══════════════════════════════
+# §4 — SSE PARSER
+# ═══════════════════════════════════════════════════════════
+class _SSE:
+    """
+    Parse Upstage SSE lines into a list of (event_type, content) tuples.
+
+    Event types:
+        "r-delta"   — reasoning token (delta.reasoning_content)
+        "t-delta"   — text/content token (delta.content)
+        "source"    — search results JSON string
+        "s-start"   — search started
+        "s-summary" — summarizing
+        "usage"     — non-zero usage block from the API (JSON string)
+        "done"      — stream finished (always last, if present)
+
+    A single line can produce several events (e.g. the final chunk
+    carries both `usage` and `finish_reason: stop`).
+    """
+
+    @staticmethod
+    def parse_line(line: str) -> List[Tuple[str, str]]:
+        if not line or not line.startswith("data: "):
+            return []
+
+        data = line[6:].strip()
+        if data == "[DONE]":
+            return [("done", "")]
+
+        try:
+            obj = json.loads(data)
+        except json.JSONDecodeError:
+            return []
+
+        events: List[Tuple[str, str]] = []
+
+        # ── Search events (arrived without choices) ──
+        search = obj.get("search")
+        if obj.get("choices") is None and search:
+            st     = search.get("status", {})
+            action = st.get("action", "")
+            desc   = st.get("description", "")
+            raw_sq = search.get("search_queries")
+
+            if action == "search_start":
+                query = ""
+                if raw_sq and isinstance(raw_sq, list) and raw_sq:
+                    query = raw_sq[0].get("query", "")
+                events.append(("s-start", query))
+            elif action == "search_finish":
+                if raw_sq:
+                    events.append(("source", json.dumps(raw_sq)))
+            elif action == "summarizing":
+                events.append(("s-summary", desc))
+        else:
+            # ── Content / Thinking chunks ──
+            choices = obj.get("choices")
+            if choices:
+                delta  = choices[0].get("delta", {})
+                finish = choices[0].get("finish_reason")
+
+                rc = delta.get("reasoning_content", "")
+                if rc:
+                    events.append(("r-delta", rc))
+
+                text = delta.get("content", "")
+                if text:
+                    # <think> splitting happens one level up
+                    events.append(("t-delta", text))
+
+        # ── Usage (only when the API reports non-zero counts) ──
+        usage = obj.get("usage")
+        if isinstance(usage, dict) and (
+            usage.get("prompt_tokens") or usage.get("completion_tokens")
+            or usage.get("total_tokens")
+        ):
+            events.append(("usage", json.dumps(usage)))
+
+        # ── done LAST so a same-line usage event is not skipped ──
+        if obj.get("choices") and obj["choices"][0].get("finish_reason") == "stop":
+            events.append(("done", ""))
+
+        return events
+
+
+# ═══════════════════════════════════════════════════════════
+# §5 — SOURCE FORMATTER
+# ═══════════════════════════════════════════════════════════
+class _Sources:
+
+    @staticmethod
+    def parse(raw_json_list: List[str]) -> List[Dict]:
+        seen_urls: set[str] = set()
+        result: List[Dict] = []
+        idx = 0
+
+        for raw in raw_json_list:
+            try:
+                queries = json.loads(raw) if isinstance(raw, str) else raw
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+            if not isinstance(queries, list):
+                continue
+
+            for q_data in queries:
+                query_text  = q_data.get("query", "")
+                raw_results = q_data.get("results", [])
+
+                if not isinstance(raw_results, list):
+                    continue
+
+                for r in raw_results:
+                    url     = r.get("url", "").strip()
+                    title   = r.get("title", "").strip()
+                    score   = float(r.get("score", 0.0))
+                    content = r.get("content", "").strip()
+
+                    if not url or url in seen_urls:
+                        continue
+
+                    seen_urls.add(url)
+                    idx += 1
+
+                    snippet = content[:200].replace("\n", " ").strip()
+                    if len(content) > 200:
+                        snippet += "..."
+
+                    result.append({
+                        "index":   idx,
+                        "query":   query_text,
+                        "title":   title or "Untitled",
+                        "url":     url,
+                        "score":   score,
+                        "snippet": snippet,
+                    })
+
+        return result
+
+    @staticmethod
+    def format_text(sources: List[Dict]) -> str:
+        if not sources:
+            return ""
+        lines = [
+            "",
+            "  ┌─────────────────────────────────────────",
+            f"  │ 📚 Sources ({len(sources)})",
+        ]
+        for s in sources:
+            lines.append(f"  │  [{s.get('index', '?')}] {s.get('title', '')}")
+            lines.append(f"  │      {s.get('url', '')}")
+            if s.get("score"):
+                try:
+                    lines.append(f"  │      Score: {float(s['score']):.4f}")
+                except (TypeError, ValueError):
+                    pass
+        lines.append("  └─────────────────────────────────────────")
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_json(sources: List[Dict]) -> str:
+        """Format sources as a JSON string for streaming."""
+        clean_sources = []
+        for src in sources:
+            clean_sources.append({
+                "title": src.get("title", ""),
+                "url":   src.get("url", ""),
+                "score": src.get("score", 0),
+            })
+        return json.dumps({"sources": clean_sources})
+
+
+# ═══════════════════════════════════════════════════════════
+# §6 — THINK SPLITTER
+# ═══════════════════════════════════════════════════════════
+_OPEN  = "<think>"
+_CLOSE = "</think>"
+
+
+class ThinkSplitter:
+    """
+    The backend inlines thinking INSIDE content deltas as
+    <think>…</think> markup, and tags can be split across tokens.
+    Feed it raw content tokens; get back (kind, segment) pairs with
+    kind ∈ {"content", "thinking"} — each segment clean of markup.
+
+    A trailing partial tag (e.g. buffer ending in `<thi`) is held
+    back until the next feed() decides what it was; flush() releases
+    whatever remains when the stream ends.
+    """
+
+    def __init__(self, open_tag: str = _OPEN, close_tag: str = _CLOSE):
+        self._open  = open_tag
+        self._close = close_tag
+        self._buf   = ""
+        self._in    = False
+
+    def feed(self, text: str) -> List[Tuple[str, str]]:
+        out: List[Tuple[str, str]] = []
+        self._buf += text
+        while True:
+            if self._in:
+                j = self._buf.find(self._close)
+                if j == -1:
+                    hold = len(self._close) - 1
+                    if len(self._buf) > hold:
+                        seg, self._buf = self._buf[:-hold], self._buf[-hold:]
+                    else:
+                        seg = ""
+                    if seg:
+                        out.append(("thinking", seg))
+                    break
+                seg = self._buf[:j]
+                if seg:
+                    out.append(("thinking", seg))
+                self._in  = False
+                self._buf = self._buf[j + len(self._close):]
+            else:
+                i = self._buf.find(self._open)
+                if i == -1:
+                    hold = len(self._open) - 1
+                    if len(self._buf) > hold:
+                        seg, self._buf = self._buf[:-hold], self._buf[-hold:]
+                    else:
+                        seg = ""
+                    if seg:
+                        out.append(("content", seg))
+                    break
+                seg = self._buf[:i]
+                if seg:
+                    out.append(("content", seg))
+                self._in  = True
+                self._buf = self._buf[i + len(self._open):]
+        return out
+
+    def flush(self) -> List[Tuple[str, str]]:
+        """Release anything still buffered (stream over)."""
+        if not self._buf:
+            return []
+        kind = "thinking" if self._in else "content"
+        seg, self._buf = self._buf, ""
+        return [(kind, seg)]
+
+
+# ═══════════════════════════════════════════════════════════
+# §7 — USAGE DEPARTMENT
+# ═══════════════════════════════════════════════════════════
+@dataclass
+class TurnUsage:
+    """Measured stats for one chat turn."""
+    model:            str    = "solar-pro3"
+    ok:               bool   = True
+    error:            str    = ""
+    prompt_chars:     int    = 0
+    thinking_chars:   int    = 0
+    content_chars:    int    = 0
+    n_sources:        int    = 0
+    api_usage:        Optional[Dict[str, Any]] = None   # when non-zero
+    elapsed_s:        float  = 0.0
+    first_token_s:    Optional[float] = None
+
+    # ── tokens: API-reported if present, else chars/4 estimate ──
+    @property
+    def tokens_estimated(self) -> bool:
+        return not (self.api_usage
+                    and (self.api_usage.get("total_tokens") or 0) > 0)
+
+    @property
+    def tokens(self) -> int:
+        if not self.tokens_estimated:
+            return int(self.api_usage.get("total_tokens") or 0)
+        chars = self.thinking_chars + self.content_chars
+        # any non-empty response is at least one token
+        return max(1, round(chars / 4)) if chars > 0 else 0
+
+    @property
+    def tokens_per_s(self) -> Optional[float]:
+        if self.elapsed_s <= 0:
+            return None
+        return self.tokens / self.elapsed_s
+
+    def format_line(self) -> str:
+        bits = [f"⏱ {self.elapsed_s:.1f}s"]
+        if self.first_token_s is not None:
+            bits.append(f"first token {self.first_token_s:.2f}s")
+        if self.tokens:
+            est = " (est)" if self.tokens_estimated else ""
+            bits.append(f"~{self.tokens} tok{est}")
+            if self.tokens_per_s:
+                bits.append(f"{self.tokens_per_s:.0f} tok/s")
+        if self.thinking_chars:
+            bits.append(f"💭 {self.thinking_chars}c")
+        bits.append(self.model)
+        if self.n_sources:
+            bits.append(f"📚 {self.n_sources}")
+        if not self.ok:
+            bits.append(f"✗ {self.error[:40]}")
+        return " · ".join(bits)
+
+
+class SessionUsage:
+    """Accumulates TurnUsage across a provider's lifetime."""
+
+    def __init__(self) -> None:
+        self.turns: List[TurnUsage] = []
+
+    def add(self, turn: TurnUsage) -> None:
+        self.turns.append(turn)
+
+    def clear(self) -> None:
+        self.turns.clear()
+
+    def totals(self) -> Dict[str, Any]:
+        ok = [t for t in self.turns if t.ok]
+        return {
+            "turns":        len(self.turns),
+            "ok":           len(ok),
+            "failed":       len(self.turns) - len(ok),
+            "elapsed_s":    round(sum(t.elapsed_s for t in ok), 2),
+            "tokens":       sum(t.tokens for t in ok),
+            "thinking_chars": sum(t.thinking_chars for t in ok),
+            "content_chars":  sum(t.content_chars for t in ok),
+            "sources":      sum(t.n_sources for t in ok),
+        }
+
+    def format_report(self) -> str:
+        if not self.turns:
+            return "  (no turns yet)"
+        lines = [
+            "",
+            "  ┌──────────────────────────────────────────────────────────────────",
+            "  │ 📊 Session usage",
+            "  │  turn  status      time     tokens   thinking  answer   src  model",
+            "  │  ──────  ─────────  ──────  ────────  ────────  ──────  ───  ─────",
+        ]
+        for i, t in enumerate(self.turns, 1):
+            status = "✓" if t.ok else f"✗ {t.error[:14]}"
+            lines.append(
+                f"  │  {i:<6} {status:<11} {t.elapsed_s:>5.1f}s  {t.tokens:>6}  "
+                f"{t.thinking_chars:>6}    {t.content_chars:>4}   {t.n_sources:>2}  {t.model}"
+            )
+        tt = self.totals()
+        lines.append("  │  ──────  ─────────  ──────  ────────  ────────  ──────  ───  ─────")
+        lines.append(
+            f"  │  TOTAL  {tt['turns']} turns ({tt['ok']} ok, {tt['failed']} failed) · "
+            f"{tt['elapsed_s']:.1f}s · ~{tt['tokens']} tokens · "
+            f"{tt['sources']} sources"
+        )
+        lines.append("  └──────────────────────────────────────────────────────────────────")
+        return "\n".join(lines)
+
+
+# ═══════════════════════════════════════════════════════════
+# §8 — STREAM EVENTS
+# ═══════════════════════════════════════════════════════════
+@dataclass
+class StreamEvent:
+    """One realtime piece of the response.
+
+    kind:
+        "sources"   — search sources (JSON blob, streamed first)
+        "thinking"  — reasoning token
+        "content"   — answer token
+        "done"      — stream finished (final event)
+    """
+    kind: str
+    text: str = ""
+
+
+# ═��═════════════════════════════════════════════════════════
+# §9 — CREDENTIAL MANAGER  (pure HTTP, fully async)
+# ═══════════════════════════════════════════════════════════
+def _find_action_id(js_text: str, action_name: str) -> Optional[str]:
+    """
+    Extract a Next.js server-action id from a client JS bundle by its
+    declared name. Matches minified patterns like:
+
+        createServerReference)("002f44cb…d5",x.callServer,void 0,x.findSourceMapURL,"getConsoleCsrfToken")
+
+    The regex pins the id to its OWN argument list (exactly 3 unquoted
+    args before the name), so when several actions are declared on one
+    line (very common after minification) ids can't be cross-wired.
+    No fixed length assumption (ids were 40 hex, now 42 — extract by
+    name so future format changes don't break capture).
+    """
+    m = re.search(
+        r'createServerReference\)\("([a-f0-9]{32,80})"(?:,[^,\"]+){3},'
+        r'"' + re.escape(action_name) + r'"\)',
+        js_text,
+    )
+    return m.group(1) if m else None
+
+
+class _Creds:
+
+    def __init__(self, path: Optional[Path] = None):
+        self.path          = Path(path) if path else _cred_file()
+        self.action_init:  Optional[str]  = None
+        self.action_token: Optional[str]  = None
+        self.cookies:      Dict[str, str] = {}
+        self.session_id:   str            = str(uuid.uuid4())
+
+    # ── Load / Save / Clear (tiny file → plain sync I/O) ──
+    async def load(self) -> bool:
+        if not self.path.exists():
+            return False
+        try:
+            data = json.loads(self.path.read_text())
+            self.action_init  = data.get("action_init")
+            self.action_token = data.get("action_token")
+            self.cookies      = data.get("cookies", {})
+            self.session_id   = self.cookies.get("session_id", str(uuid.uuid4()))
+            return bool(self.action_token)
+        except Exception:
+            return False
+
+    async def save(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "action_init":  self.action_init,
+            "action_token": self.action_token,
+            "cookies":      self.cookies,
+            "saved_at":     time.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        self.path.write_text(json.dumps(data, indent=2))
+
+    async def clear(self):
+        try:
+            if self.path.exists():
+                self.path.unlink()
+        except Exception:
+            pass
+
+    # ── Verify (one RSC POST) ─────────────────────────────
+    async def verify(self) -> Optional[str]:
+        if not self.action_token:
+            return None
+        try:
+            async with _http_session() as http:
+                return await self._try_get_token(http)
+        except Exception:
+            return None
+
+    async def _rsc_post(self, http, action_id: str) -> str:
+        headers = {
+            "accept":       "text/x-component",
+            "content-type": "text/plain;charset=UTF-8",
+            "next-action":  action_id,
+            "origin":       _CONSOLE,
+            "referer":      f"{_CONSOLE}{_CHAT_EP}",
+            "User-Agent":   _UA,
+        }
+        # NOTE: no next-router-state-tree needed — verified empirically
+        # that the token action answers with and without it.
+        r = await http.post(
+            f"{_CONSOLE}{_CHAT_EP}",
+            headers=headers, data="[]",
+            cookies=self.cookies, timeout=20,
+        )
+        r.raise_for_status()
+        return r.text
+
+    async def _try_get_token(self, http) -> Optional[str]:
+        try:
+            body = await self._rsc_post(http, self.action_token)
+            for line in body.strip().splitlines():
+                if '"token"' in line:
+                    idx = line.index("{")
+                    try:
+                        return json.loads(line[idx:])["token"]
+                    except Exception:
+                        continue
+        except Exception:
+            pass
+        return None
+
+    # ── Capture via pure HTTP (async) ─────────────────────
+    async def capture(self):
+        """
+        Browser-free credential capture:
+
+          1. GET /playground/chat        → session cookies + chunk list
+          2. GET the RSC payload         → additional chunk refs (ins.)
+          3. scan chunks for createServerReference("…","getConsoleCsrfToken")
+          4. RSC POST with that id       → parse {"token": …}
+          5. store cookies + ids
+        """
+        async with _http_session() as http:
+            # 1) page load — sets the session cookies we need
+            page = await http.get(f"{_CONSOLE}{_CHAT_EP}",
+                                  headers=_UA_HEADERS, timeout=20)
+            page.raise_for_status()
+            html = page.text
+
+            # 2) merge chunk refs from the page + its RSC payload
+            chunk_refs = sorted(set(re.findall(r'static/chunks/[^\\"\\s\],]+\.js', html)))
+            try:
+                rsc = await http.get(
+                    f"{_CONSOLE}{_CHAT_EP}",
+                    headers={**_UA_HEADERS, "RSC": "1"},
+                    timeout=20,
+                )
+                if rsc.status_code == 200:
+                    chunk_refs = sorted(set(chunk_refs) | set(
+                        re.findall(r'static/chunks/[^\\"\\s\],]+\.js', rsc.text)))
+            except Exception:
+                pass  # RSC scan is insurance only
+
+            # 3) scan chunks for the action ids (by name)
+            action_token: Optional[str] = None
+            action_init:  Optional[str] = None
+            scanned = 0
+            for ref in chunk_refs[:_MAX_CHUNK_SCAN]:
+                scanned += 1
+                try:
+                    r = await http.get(f"{_CONSOLE}/_next/{ref}",
+                                       headers=_UA_HEADERS, timeout=20)
+                except Exception:
+                    continue
+                if r.status_code != 200:
+                    continue
+                js = r.text
+                if action_token is None and _ACTION_TOKEN in js:
+                    action_token = _find_action_id(js, _ACTION_TOKEN)
+                if action_init is None and _ACTION_INIT in js:
+                    action_init = _find_action_id(js, _ACTION_INIT)
+                if action_token:
+                    break
+
+            if not action_token:
+                raise RuntimeError(
+                    f"Could not find '{_ACTION_TOKEN}' action in any of "
+                    f"{scanned} scanned JS chunks — the console may have "
+                    f"changed structure. Delete {_cred_file()} and retry."
+                )
+
+            # 4) prove the action works + harvest a first token
+            self._cookies_from(http)
+            self.action_token = action_token
+            self.action_init  = action_init
+            body = await self._rsc_post(http, action_token)
+            if '"token"' not in body:
+                raise RuntimeError(
+                    f"Token action '{action_token[:12]}…' answered but "
+                    f"no token in response (len={len(body)})."
+                )
+
+            self.session_id = self.cookies.get("session_id", str(uuid.uuid4()))
+        await self.save()
+
+    def _cookies_from(self, http):
+        try:
+            d = http.cookies.get_dict()
+            if isinstance(d, dict) and d:
+                self.cookies = {str(k): str(v) for k, v in d.items()}
+        except Exception:
+            pass
+        if "session_id" not in self.cookies:
+            self.cookies["session_id"] = str(uuid.uuid4())
+
+
+# ═══════════════════════════════════════════════════════════
+# §10 — MAIN PROVIDER  (fully async, realtime)
+# ═══════════════════════════════════════════════════════════
+class UpstageProvider:
+    """
+    ☀️ Upstage Solar — Async Reasoning Model Provider (v3)
+
+    4 models · Web search · Reasoning modes · Session usage stats
+    100% asyncio streaming over curl_cffi (Chrome TLS impersonation)
+    Credentials cached to disk for instant subsequent startups.
+
+    ┌─────────────────────────────────────────────────────────┐
+    │  up = UpstageProvider()                                 │
+    │  up = UpstageProvider(model="solar-pro3")               │
+    │                                                         │
+    │  # Plain strings (backward compatible):                 │
+    │  async for t in up.chat(data="Hello!"):                 │
+    │      print(t, end="")                                   │
+    │                                                         │
+    │  # Typed realtime events:                               │
+    │  async for ev in up.stream(                             │
+    │      messages=[                                         │
+    │          {"role":"system", "content":"You are Bob"},    │
+    │          {"role":"user",   "content":"Name?"},          │
+    │      ],                                                 │
+    │      model="solar-pro2",                                │
+    │      search=True,                                       │
+    │  ):                                                     │
+    │      if ev.kind == "thinking":  print(ev.text, dim)     │
+    │      elif ev.kind == "content":  print(ev.text, bright) │
+    │                                                         │
+    │  # After chat:                                          │
+    │  up.last_response      # text content                   │
+    │  up.last_reasoning     # reasoning trace                │
+    │  up.last_sources       # [{index,title,url}, ...]       │
+    │  up.last_sources_text  # formatted text block           │
+    │  up.last_usage         # TurnUsage (time/tokens/ttfb)   │
+    │  up.session_usage.format_report()  # usage department   │
+    └─────────────────────────────────────────────────────────┘
+
+    Priority:
+        messages given  →  data is IGNORED
+        messages empty  →  data is used
+    """
+
+    def __init__(
+        self,
+        model:       Optional[str]   = None,
+        system:      str   = "",
+        search:      bool  = False,
+        max_tokens:  Optional[int]   = None,
+        temperature: Optional[float] = None,
+    ):
+        self.model       = _resolve_model(model) if model else "solar-pro3"
+        self.system      = system
+        self.search      = search
+        self.max_tokens  = max_tokens
+        self.temperature = temperature
+
+        self.history:           List[Dict] = []
+        self.last_response:     str        = ""
+        self.last_reasoning:    str        = ""
+        self.last_sources:      List[Dict] = []
+        self.last_sources_text: str        = ""
+        self.last_sources_json: str        = ""
+        self.last_usage:        Optional[TurnUsage] = None
+
+        self.session_usage = SessionUsage()
+
+        self._creds     = _Creds()
+        self._connected = False
+
+    # ═══════════════════════════════════════════════════
+    # CONNECTION PIPELINE
+    # ═══════════════════════════════════════════════════
+    async def connect(self):
+        """
+        Explicitly connect to Upstage.
+        Tries cached credentials first (instant).
+        Falls back to pure-HTTP re-capture if needed.
+        Called automatically on first chat()/stream().
+        """
+        loaded = await self._creds.load()
+
+        if loaded:
+            token = await self._creds.verify()
+            if token:
+                self._connected = True
+                return
+
+        # Credentials expired or missing — re-capture over HTTP
+        await self._creds.capture()
+        self._connected = True
+
+    async def _ensure_connected(self):
+        if not self._connected:
+            await self.connect()
+
+    # ── Get CSRF token (with auto-refresh) ────────────
+    async def _get_csrf(self) -> str:
+        token = await self._creds.verify()
+        if token:
+            return token
+
+        # Refresh
+        await self._creds.capture()
+        token = await self._creds.verify()
+        if token:
+            return token
+
+        raise UpstageAuthError(
+            f"Could not obtain CSRF token. "
+            f"Try deleting {_cred_file()} and restarting."
+        )
+
+    # ── Payload builder (pure logic) ──────────────────
+    def _build_payload(
+        self,
+        messages:    List[Dict],
+        model:       str,
+        search:      bool,
+        reasoning:   Optional[str],
+        temperature: Optional[float],
+        max_tokens:  Optional[int],
+    ) -> Dict:
+        cfg  = _MODELS.get(model, _MODELS["solar-pro3"])
+        temp = (
+            temperature if temperature is not None
+            else (self.temperature or cfg["temperature"])
+        )
+        tok = (
+            max_tokens if max_tokens is not None
+            else (self.max_tokens or cfg["max_tokens"])
+        )
+
+        msgs = [m.copy() for m in messages]
+
+        if not msgs or msgs[0].get("role") != "system":
+            sys_content = self.system or cfg["system"] or ""
+            if sys_content:
+                msgs.insert(0, {"role": "system", "content": sys_content})
+
+        if search and cfg["search"]:
+            for m in reversed(msgs):
+                if m["role"] == "user":
+                    m["mode"] = ["search"]
+                    break
+
+        payload: Dict = {
+            "conversation_id": str(uuid.uuid4()),
+            "stream":          True,
+            "log_enabled":     True,
+            "messages":        msgs,
+            "model":           model,
+            "temperature":     temp,
+            "max_tokens":      tok,
+        }
+
+        # Automatically set reasoning based on search:
+        # search on  → HIGH reasoning · search off → LOW
+        if cfg.get("reasoning"):
+            valid_reasoning = cfg["reasoning"]
+
+            if search:
+                effort = ("high" if "high" in valid_reasoning
+                          else valid_reasoning[-1])
+            else:
+                effort = ("low" if "low" in valid_reasoning
+                          else valid_reasoning[0])
+
+            # Override with explicit reasoning if provided
+            if reasoning and reasoning in valid_reasoning:
+                effort = reasoning
+
+            payload["reasoning_effort"] = effort
+
+        if cfg.get("metadata"):
+            payload["metadata"] = cfg["metadata"]
+
+        if search and cfg["search"]:
+            payload["search_provider"] = "tavily"
+
+        return payload
+
+    # ═══════════════════════════════════════════════════
+    # RAW STREAM  (native async curl_cffi — the realtime core)
+    # ═══════════════════════════════════════════════════
+    async def _stream_events(
+        self, payload: Dict
+    ) -> AsyncGenerator[Tuple[str, str], None]:
+        """
+        One attempt: POST the completion and yield (etype, econtent)
+        tuples the instant each SSE line arrives on the socket.
+        No threads, no queues, no polling — just aiter_lines().
+        """
+        csrf = await self._get_csrf()
+        headers = {
+            "accept":                    "*/*",
+            "content-type":              "application/json",
+            "origin":                    _CONSOLE,
+            "referer":                   f"{_CONSOLE}/",
+            "x-csrf-token":             csrf,
+            "x-session-id":             self._creds.session_id,
+            "x-upstage-logging-enabled": "true",
+            "User-Agent":               _UA,
+        }
+
+        async with _http_session() as http:
+            r = await http.post(
+                _COMP_URL,
+                json=payload,
+                headers=headers,
+                cookies=dict(self._creds.cookies),
+                stream=True,
+                timeout=(_CONNECT_TIMEOUT, _STREAM_TIMEOUT),
+            )
+            try:
+                if r.status_code in (401, 403):
+                    raise UpstageAuthError(
+                        f"Auth error: HTTP {r.status_code}"
+                    )
+                if r.status_code != 200:
+                    raise UpstageStreamError(
+                        f"HTTP {r.status_code}: {r.text[:200]}"
+                    )
+
+                async for raw in r.aiter_lines():
+                    line = (raw.decode("utf-8", "replace")
+                            if isinstance(raw, (bytes, bytearray)) else raw)
+                    for ev in _SSE.parse_line(line):
+                        yield ev
+                        if ev[0] == "done":
+                            return
+            finally:
+                try:
+                    await r.aclose()
+                except Exception:
+                    pass
+
+    async def _events_with_retry(
+        self, payload: Dict
+    ) -> AsyncGenerator[Tuple[str, str], None]:
+        """
+        _stream_events with one auth-retry: on UpstageAuthError
+        (401/403 — happens before any chunk is yielded) re-capture
+        credentials once and try again.
+        """
+        for attempt in (1, 2):
+            try:
+                async for ev in self._stream_events(payload):
+                    yield ev
+                return
+            except UpstageAuthError:
+                if attempt == 1:
+                    await self._creds.capture()
+                    continue
+                raise
+
+    # ═══════════════════════════════════════════════════
+    # ★  STREAM  (typed, realtime)
+    # ═══════════════════════════════════════════════════
+    async def stream(
+        self,
+        data:        Optional[str]   = None,
+        messages:    Optional[List[Dict]] = None,
+        model:       Optional[str]   = None,
+        system:      Optional[str]   = None,
+        reasoning:   Optional[str]   = None,
+        search:      Optional[bool]  = None,
+        max_tokens:  Optional[int]   = None,
+        temperature: Optional[float] = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        """
+        Realtime async stream of the full response.
+
+        Args:
+            data        : Simple prompt (ignored if messages given)
+            messages    : OpenAI-style [{role, content}]
+            model       : Override model (solar-pro3/pro2/syn-pro/mini)
+            system      : Override system prompt
+            reasoning   : Reasoning effort (low/medium/high)
+            search      : Web search enabled
+            max_tokens  : Max output tokens
+            temperature : Sampling temperature
+
+        Yields StreamEvent(kind, text), kind ∈
+            "sources"    — search sources JSON (first, when searching)
+            "thinking"   — reasoning tokens (dim-friendly)
+            "content"    — answer tokens
+            "done"       — final event
+
+        After iteration (even if abandoned early):
+            .last_response / .last_reasoning / .last_sources
+            .last_usage       — TurnUsage
+            .session_usage    — accumulated usage department
+        """
+        if not messages and not data:
+            raise ValueError("Provide 'messages' or 'data'")
+
+        await self._ensure_connected()
+
+        # ── Resolve model ──────────────────────────────
+        use_model = _resolve_model(model) if model else self.model
+
+        # ── Resolve options ────────────────────────────
+        use_search = search if search is not None else self.search
+        use_system = system if system is not None else self.system
+
+        # ── Build messages ─────────────────────────────
+        if messages:
+            # MESSAGES MODE — data is IGNORED
+            clean: List[Dict] = []
+            for msg in messages:
+                role    = msg.get("role", "")
+                content = msg.get("content", "")
+                if isinstance(content, list):
+                    content = " ".join(
+                        p.get("text", "") for p in content
+                        if p.get("type") == "text"
+                    )
+                if role == "system":
+                    use_system = content
+                elif role in ("user", "assistant"):
+                    clean.append({"role": role, "content": content})
+            self.history = clean
+
+            send_msgs: List[Dict] = []
+            if use_system:
+                send_msgs.append({"role": "system", "content": use_system})
+            send_msgs.extend(clean)
+
+        else:
+            # DATA MODE — append to history
+            self.history.append({"role": "user", "content": data})
+
+            send_msgs = []
+            if use_system:
+                send_msgs.append({"role": "system", "content": use_system})
+            send_msgs.extend(self.history)
+
+        # ── Build payload ──────────────────────────────
+        payload = self._build_payload(
+            send_msgs, use_model, use_search,
+            reasoning, temperature, max_tokens,
+        )
+
+        # ── State for this turn ────────────────────────
+        t0 = time.time()
+        usage = TurnUsage(
+            model=use_model,
+            prompt_chars=len(json.dumps(send_msgs, ensure_ascii=False)),
+        )
+        splitter        = ThinkSplitter()
+        reasoning_parts: List[str] = []
+        content_parts:   List[str] = []
+        raw_sources:     List[str] = []
+        sources_yielded = False
+        first_token:     Optional[float] = None
+        completed       = False
+
+        def _note(kind: str, seg: str):
+            nonlocal first_token
+            if first_token is None:
+                first_token = time.time() - t0
+            if kind == "thinking":
+                reasoning_parts.append(seg)
+                usage.thinking_chars += len(seg)
+            else:
+                content_parts.append(seg)
+                usage.content_chars += len(seg)
+
+        try:
+            async for etype, econtent in self._events_with_retry(payload):
+                if etype == "done":
+                    break
+
+                elif etype == "source":
+                    raw_sources.append(econtent)
+                    if use_search and not sources_yielded and raw_sources:
+                        sources_yielded = True
+                        fmt = _Sources.parse(raw_sources)
+                        self.last_sources      = fmt
+                        self.last_sources_json = _Sources.format_json(fmt)
+                        self.last_sources_text = _Sources.format_text(fmt)
+                        usage.n_sources        = len(fmt)
+                        if first_token is None:
+                            first_token = time.time() - t0
+                        yield StreamEvent("sources", self.last_sources_json)
+
+                elif etype == "usage":
+                    try:
+                        u = json.loads(econtent)
+                        if isinstance(u, dict) and u:
+                            usage.api_usage = u
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+
+                elif etype == "r-delta":
+                    _note("thinking", econtent)
+                    yield StreamEvent("thinking", econtent)
+
+                elif etype == "t-delta":
+                    for kind, seg in splitter.feed(econtent):
+                        _note(kind, seg)
+                        yield StreamEvent(kind, seg)
+
+                # s-start / s-summary: internal, not surfaced
+
+            # flush the splitter (stream finished cleanly)
+            for kind, seg in splitter.flush():
+                _note(kind, seg)
+                yield StreamEvent(kind, seg)
+
+            completed = True          # before the yield: a consumer that
+            yield StreamEvent("done", "")   # stops *on* done is a clean exit
+
+        except UpstageError as e:
+            usage.ok    = False
+            usage.error = ("auth: " if isinstance(e, UpstageAuthError) else "") + str(e)[:160]
+            raise
+        except Exception as e:
+            usage.ok    = False
+            usage.error = str(e)[:200]
+            raise UpstageStreamError(f"stream failed: {e}") from e
+        finally:
+            # finalize state — runs on clean exit, early break,
+            # GeneratorExit, and error paths alike
+            if not completed:
+                for kind, seg in splitter.flush():
+                    _note(kind, seg)          # state only — no yield here
+                if usage.ok and not usage.error:
+                    usage.ok    = False
+                    usage.error = "stream interrupted"
+
+            usage.elapsed_s     = time.time() - t0
+            usage.first_token_s = first_token
+            self.last_response  = "".join(content_parts)
+            self.last_reasoning = "".join(reasoning_parts)
+
+            if raw_sources:
+                fmt = _Sources.parse(raw_sources)
+                if fmt:
+                    self.last_sources      = fmt
+                    self.last_sources_text = _Sources.format_text(fmt)
+                    self.last_sources_json = _Sources.format_json(fmt)
+                    usage.n_sources        = len(fmt)
+
+            self.last_usage    = usage
+            self.session_usage.add(usage)
+
+            if usage.ok and self.last_response:
+                self.history.append({
+                    "role":    "assistant",
+                    "content": self.last_response,
+                })
+
+    # ═══════════════════════════════════════════════════
+    # ★  CHAT  (plain-string convenience, v1/v2 contract)
+    # ═══════════════════════════════════════════════════
+    async def chat(
+        self,
+        data:        Optional[str]   = None,
+        messages:    Optional[List[Dict]] = None,
+        model:       Optional[str]   = None,
+        system:      Optional[str]   = None,
+        reasoning:   Optional[str]   = None,
+        search:      Optional[bool]  = None,
+        max_tokens:  Optional[int]   = None,
+        temperature: Optional[float] = None,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Async-stream tokens from Upstage Solar (plain strings).
+
+        Yields the sources JSON blob first (when searching), then
+        reasoning + answer tokens in realtime. Identical contract to
+        the v1/v2 chat() — built on top of stream() now.
+        """
+        async for ev in self.stream(
+            data=data, messages=messages, model=model, system=system,
+            reasoning=reasoning, search=search, max_tokens=max_tokens,
+            temperature=temperature,
+        ):
+            yield ev.text
+
+    # ═══════════════════════════════════════════════════
+    # SETTERS (chainable)
+    # ═══════════════════════════════════════════════════
+    def set_model(self, model: str) -> "UpstageProvider":
+        self.model = _resolve_model(model)
+        return self
+
+    def set_system(self, prompt: str) -> "UpstageProvider":
+        self.system = prompt
+        return self
+
+    def set_search(self, enabled: bool) -> "UpstageProvider":
+        self.search = enabled
+        return self
+
+    def set_temperature(self, t: float) -> "UpstageProvider":
+        self.temperature = t
+        return self
+
+    def set_max_tokens(self, n: int) -> "UpstageProvider":
+        self.max_tokens = n
+        return self
+
+    # ── History ──────────────────────────────────────────
+    def clear_history(self):
+        self.history.clear()
+
+    def get_history(self) -> List[Dict]:
+        out: List[Dict] = []
+        if self.system:
+            out.append({"role": "system", "content": self.system})
+        out.extend(self.history)
+        return out
+
+    def get_sources(self) -> List[Dict]:
+        return self.last_sources
+
+    def get_sources_text(self) -> str:
+        return self.last_sources_text
+
+    def get_sources_json(self) -> str:
+        return self.last_sources_json
+
+    def new_session(self):
+        self.history.clear()
+        self.last_response     = ""
+        self.last_reasoning    = ""
+        self.last_sources      = []
+        self.last_sources_text = ""
+        self.last_sources_json = ""
+        self.last_usage        = None
+        self.session_usage.clear()
+
+    async def refresh_credentials(self):
+        """Force re-capture credentials (pure HTTP, ~2-5s)."""
+        await self._creds.capture()
+
+    @staticmethod
+    async def clear_credentials():
+        """Delete cached credentials file."""
+        creds = _Creds()
+        await creds.clear()
+
+    # ═══════════════════════════════════════════════════
+    # INFO
+    # ═══════════════════════════════════════════════════
+    def list_models(self) -> List[Dict]:
+        return [{
+            "name":       name,
+            "short":      name.split("/")[-1],
+            "reasoning":  cfg.get("reasoning"),
+            "search":     cfg.get("search", False),
+            "max_tokens": cfg.get("max_tokens"),
+            "active":     name == self.model,
+        } for name, cfg in _MODELS.items()]
+
+    @staticmethod
+    def available_models() -> List[str]:
+        return list(_MODELS.keys())
+
+    @staticmethod
+    def model_info() -> Dict:
+        return {
+            "name":     "Upstage Solar",
+            "provider": "Upstage AI",
+            "models":   list(_MODELS.keys()),
+            "thinking": True,
+            "search":   True,
+        }
+
+    # ═══════════════════════════════════════════════════
+    # LIFECYCLE
+    # ═══════════════════════════════════════════════════
+    async def close(self):
+        pass  # sessions are per-call — nothing persistent to close
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.close()
+
+    def __repr__(self):
+        s = "🔍" if self.search else ""
+        r = "💭high" if self.search else "💭low"
+        flags = f" {s}{r}".rstrip()
+        return (
+            f"UpstageProvider("
+            f"model={self.model!r}, "
+            f"via={'cached' if self._connected else 'not-connected'}, "
+            f"history={len(self.history)}, "
+            f"turns={self.session_usage.totals()['turns']}"
+            f"{flags})"
+        )