docs(contract): dev-corp gemma4:26b 파라미터 범위 및 가이드 문서 추가

2026-07-09 20:48:05 +09:00 · 2026-07-09 20:48:05 +09:00 · a709db0251
commit a709db0251
parent 6d2de5bd1c
5 changed files with 386 additions and 11 deletions
--- a/agent-contract/outer/openai-compatible-api.md
+++ b/agent-contract/outer/openai-compatible-api.md
@ -187,17 +187,38 @@ Think 제어 field:
 - `think` (bool, optional): thinking/reasoning 생성 활성화 여부. 생략하면 provider 기본값을 유지한다. `false`는 thinking 생성을 끄도록 요청하고, `true`는 provider가 지원하면 thinking 생성을 명시 활성화한다.
 - `reasoning_effort` (string, optional): `none`, `low`, `medium`, `high` 중 하나. `none`은 `think=false`와 같은 disable 의미로 처리한다. `low`/`medium`/`high`는 provider가 지원하는 경우에만 전달한다.
 - `thinking_token_budget` (int, optional): thinking token budget. 0 이상이어야 한다.
- `include_reasoning` (bool, optional): OpenAI-compatible 응답에서 `reasoning_content` 노출 여부. 생략하거나 `true`이면 provider reasoning delta/message를 노출할 수 있고, `false`이면 provider가 reasoning을 생성해도 response의 `reasoning_content`를 제거한다.
+- `include_reasoning` (bool, optional): OpenAI-compatible 응답에서 `reasoning_content` 노출 여부. non-provider normalized route에서는 생략하거나 `true`이면 provider reasoning delta/message를 노출할 수 있고, `false`이면 provider가 reasoning을 생성해도 response의 `reasoning_content`를 제거한다. provider-pool pure `passthrough`는 provider body 보존이 우선이며, 현재 IOP가 이 field만으로 reasoning field를 제거한다고 보장하지 않는다.

-Reasoning-only 완료 처리:
+### dev-corp `gemma4:26b` provider-pool passthrough 파라미터 범위
+
+이 표는 dev-corp의 `gemma4:26b` provider-pool route에서, 현재 IOP 설정과 provider/vLLM 최적화 값을 변경하지 않고 standard OpenAI-compatible caller가 요청 파라미터만 바꿔 측정할 때의 현재 계약 범위다. Pi TUI의 고정 호출 방식이나 다른 model/provider route의 동작으로 일반화하지 않는다.
+
+| 요청 파라미터 | 현재 기대 동작 | 권장 판정 |
+| --- | --- | --- |
+| `stream=false`, `think` 생략 | provider에 non-stream Chat Completions 요청으로 전달되고 Edge는 provider JSON body를 relay한다. reasoning field가 있으면 보존될 수 있다. | standard OpenAI-compatible caller에서 non-stream 동작 측정 가능. reasoning을 숨기려면 client에서 `choices[].message.reasoning_content`, `reasoning` 등 provider reasoning field를 제거한다. |
+| `stream=true`, `think` 생략 | provider SSE body를 relay한다. reasoning delta가 있으면 보존될 수 있다. | streaming 동작 측정 가능. client는 `choices[].delta.reasoning_content`, `reasoning`, `reasoning_text` 같은 reasoning delta를 선택적으로 무시한다. |
+| `include_reasoning=false` | field는 수신/전달될 수 있지만 pure `passthrough`에서 IOP-side filtering을 보장하지 않는다. provider가 무시하면 reasoning field가 그대로 올 수 있다. | 현재 IOP 설정을 바꾸지 않는 조건에서는 hide-only 스위치로 보지 않는다. client-side filtering을 기준으로 둔다. |
+| `think=false` | Edge validation conflict가 없으면 요청은 통과하고 model catalog의 default thinking budget 주입은 억제된다. 이후 provider body에 `think:false`가 반영될 수 있으나, 현재 `gemma4:26b` provider 최적화 값과 충돌하거나 backend별로 무시/실패/품질 저하가 날 수 있다. | “숨기기만” 하는 옵션이 아니다. dev-corp `gemma4:26b` 기본 안정 호출에서는 생략한다. |
+| `reasoning_effort="none"` | `think=false`와 같은 disable 의도로 해석되어 default thinking budget 주입을 억제한다. provider tunnel에서는 runtime/provider 지원 여부에 의존한다. | `think=false`와 같은 이유로 기본 안정 호출에서는 생략한다. |
+| 명시적 `thinking_token_budget` | 0 이상이면 conflict validation 후 provider tunnel body에 반영될 수 있다. catalog 기본 budget 대신 caller 값으로 provider thinking budget을 바꾸는 요청이다. | 최적화된 `gemma4:26b` 기본값을 바꾸는 측정으로만 사용한다. 일반 표준 안정 호출에서는 생략한다. |
+| `metadata.iop_response_mode="passthrough+sideband"` | provider content는 보존하고 IOP sideband observation만 추가한다. reasoning hide를 수행하지 않는다. | route/usage 관측이 필요할 때만 사용한다. |
+| `metadata.iop_response_mode="transformed"` | provider model group route에서는 `400 invalid_request_error`로 거부한다. | dev-corp `gemma4:26b` provider-pool에서는 사용하지 않는다. |
+| `/v1/responses` 호출 | provider model group raw passthrough parity 전까지 지원하지 않는다. | `gemma4:26b` provider-pool 외부 호출은 `/v1/chat/completions` 기준으로 측정한다. |
+
+현재 구현에서 `think=false`를 “provider에는 기본 think를 유지하되 IOP가 응답에서 reasoning만 감추는 hide-only 모드”로 해석하지 않는다. 그런 동작이 필요하면 provider/vLLM 설정 변경이 아니라 Edge provider-pool passthrough 응답 filtering 정책을 별도 구현/계약 갱신해야 한다.
+
+Reasoning-only 완료 처리 (non-provider normalized route):

 - provider가 reasoning은 생성했지만 최종 assistant `content`와 `tool_calls` 없이 완료하면 Edge는 성공 응답을 빈 content로 끝내지 않는다.
 - `include_reasoning` 생략 또는 `true`인 요청은 기존 reasoning 본문을 `reasoning_content`에 유지하고, `content`가 비어 있으면 reasoning 본문을 fallback content로도 반환한다. `finish_reason`이 `stop`이 아니면 fallback content 뒤에 IOP notice를 붙인다.
 - `include_reasoning=false`인 요청은 reasoning 본문을 노출하지 않는다. 대신 `content`에 IOP notice를 넣어 "reasoning was hidden" 상태와 `finish_reason`을 알린다.
 - streaming 응답도 같은 정책을 따른다. reasoning-only 완료 시 최종 finish chunk와 `[DONE]` 전에 fallback 또는 hidden-reasoning notice를 `content` delta로 한 번 전송한다.
+- Chat Completions provider-pool pure `passthrough` 응답 body에는 이 normalized fallback/filtering 정책을 적용하지 않는다.

 Provider별 think-control 정책:

+아래 정책은 normalized adapter execution path 기준이다. Chat Completions provider-pool pure `passthrough`는 Node adapter의 normalized `Execute`/request-body builder를 거치지 않고 provider HTTP body를 tunnel로 전달하므로, dev-corp `gemma4:26b` 측정 범위는 위 표를 우선한다.
+
 - `vLLM`:
  - `think=false` 또는 `reasoning_effort=none` -> 내부 `chat_template_kwargs.enable_thinking=false`
  - `think=true` 또는 budget-only -> 내부 `chat_template_kwargs.enable_thinking=true`
--- a/docs/dev-corp-openai-compatible-call-guide.md
+++ b/docs/dev-corp-openai-compatible-call-guide.md
@ -0,0 +1,146 @@
+# dev-corp OpenAI-Compatible Direct Call Guide
+
+이 문서는 dev-corp public Edge를 OpenAI-compatible HTTP client에서 직접 호출할 때의 사람용 가이드다. 계약 원문은 `agent-contract/outer/openai-compatible-api.md`이며, 여기서는 `digitalplatform-iop.cloud` 외부 호출에 필요한 값과 dev-corp `gemma4:26b` provider-pool 한계만 정리한다. Pi coding agent 설정은 `docs/dev-corp-pi-settings-guide.md`를 따른다.
+
+## 대상 범위
+
+- 환경: dev-corp public Edge
+- Base URL: `http://digitalplatform-iop.cloud:18086/v1`
+- 기본 endpoint: `POST /v1/chat/completions`
+- 모델 alias: `gemma4:26b`
+- 인증: `Authorization: Bearer <token>`
+- 기준 호출 방식: OpenAI-compatible Chat Completions 표준 HTTP 요청
+
+`/v1/responses`는 dev-corp `gemma4:26b` provider-pool에서 raw passthrough parity 전까지 지원하지 않는다. 외부 표준 호출은 `/v1/chat/completions`를 기준으로 한다.
+
+## 기본 설정
+
+| 항목 | 값 |
+| --- | --- |
+| Base URL | `http://digitalplatform-iop.cloud:18086/v1` |
+| Models endpoint | `GET /v1/models` |
+| Chat endpoint | `POST /v1/chat/completions` |
+| Model | `gemma4:26b` |
+| Content-Type | `application/json` |
+| Authorization | `Bearer <token>` |
+| Response mode | `metadata.iop_response_mode` 생략, 기본 `passthrough` |
+| Streaming | client가 SSE를 처리할 수 있으면 `stream:true`, 아니면 `stream:false` |
+
+토큰 원문은 tracked 문서, 예시 파일, 로그에 남기지 않는다.
+
+## 권장 요청
+
+가장 안정적인 기본 요청은 `think`, `reasoning_effort`, `thinking_token_budget`을 직접 지정하지 않는 형태다. 이렇게 호출하면 dev-corp `gemma4:26b` provider-pool의 현재 catalog/runtime 기본값을 유지한다.
+
+```bash
+curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token>' \
+  -d '{
+    "model": "gemma4:26b",
+    "messages": [
+      {
+        "role": "user",
+        "content": "간단히 현재 호출이 정상인지 확인해줘."
+      }
+    ],
+    "stream": false
+  }'
+```
+
+Streaming이 필요한 client는 `stream:true`를 명시하고 SSE `data:` chunk를 처리한다.
+
+```bash
+curl -N http://digitalplatform-iop.cloud:18086/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token>' \
+  -d '{
+    "model": "gemma4:26b",
+    "messages": [
+      {
+        "role": "user",
+        "content": "한 문장으로 응답해줘."
+      }
+    ],
+    "stream": true
+  }'
+```
+
+## 파라미터 기준
+
+| 파라미터 | 권장값 | 이유 |
+| --- | --- | --- |
+| `model` | `gemma4:26b` | dev-corp provider-pool의 외부 alias다. |
+| `stream` | client 처리 방식에 맞게 `false` 또는 `true` | `false`는 JSON body, `true`는 SSE stream을 반환한다. |
+| `think` | 생략 | 현재 Gemma4 runtime은 thinking enabled 기준으로 튜닝되어 있다. |
+| `reasoning_effort` | 생략 | `none`은 thinking disable 의도라 기본 안정 호출에 맞지 않는다. |
+| `thinking_token_budget` | 생략 | 생략하면 IOP catalog의 dev-corp `gemma4:26b` 기본 thinking budget을 사용한다. 명시하면 최적화된 기본값을 바꾸는 측정이 된다. |
+| `include_reasoning` | hide 보장용으로 사용하지 않음 | provider-pool pure `passthrough`는 provider body 보존이 우선이라 IOP-side reasoning 제거를 보장하지 않는다. |
+| `metadata.iop_response_mode` | 생략 또는 `passthrough` | provider-original 응답을 relay한다. |
+| `metadata.iop_response_mode="passthrough+sideband"` | 관측이 필요할 때만 사용 | provider body에 IOP sideband가 추가되며 hide 동작은 아니다. |
+| `metadata.iop_response_mode="transformed"` | 사용하지 않음 | provider model group route에서는 `400 invalid_request_error`로 거부된다. |
+
+Provider 전용 field인 `chat_template_kwargs`, `format`, `keep_alive`, `options`는 Chat Completions 외부 요청 body에 넣지 않는다. 이 값들은 dev-corp provider runtime 쪽 최적화 영역이며, OpenAI-compatible public Edge 호출자가 직접 조작하는 계약이 아니다.
+
+## Reasoning 처리
+
+dev-corp `gemma4:26b` provider-pool은 pure `passthrough`를 기본으로 한다. 따라서 provider가 reasoning field를 반환하면 Edge는 그 field를 보존할 수 있다.
+
+Non-stream 응답에서 client가 숨길 수 있는 대표 field:
+
+- `choices[].message.reasoning_content`
+- `choices[].message.reasoning`
+- `choices[].message.reasoning_text`
+
+Streaming 응답에서 client가 숨길 수 있는 대표 delta field:
+
+- `choices[].delta.reasoning_content`
+- `choices[].delta.reasoning`
+- `choices[].delta.reasoning_text`
+
+사용자에게 reasoning을 보여주지 않아야 하는 client는 위 field를 표시/저장/후속 prompt에 주입하지 않도록 client 쪽에서 필터링한다. `include_reasoning=false`만으로 dev-corp `gemma4:26b` provider-pool에서 reasoning이 제거된다고 가정하지 않는다.
+
+## Gemma4 설정으로 인한 한계
+
+dev-corp `gemma4:26b` provider-pool은 Gemma4 agent/tool-call 호환성을 위해 vLLM/vLLM-MLX runtime을 thinking enabled, Gemma4 parser/template, long-context 기준으로 맞춰 둔 상태다. 이 설정은 현재 동작 가능한 최적값에 가깝기 때문에 외부 caller가 요청 파라미터로 thinking 동작을 끄거나 budget을 바꾸면 backend별로 무시, 오류, 품질 저하, tool-call drift가 날 수 있다.
+
+현재 한계:
+
+- `think=false`는 “응답에서 reasoning만 숨김”이 아니라 thinking disable 요청이다.
+- `reasoning_effort="none"`도 thinking disable 의도로 해석된다.
+- 명시적 `thinking_token_budget`은 dev-corp 기본 budget을 바꾸는 요청이다.
+- `include_reasoning=false`는 provider-pool pure `passthrough`에서 hide-only 스위치가 아니다.
+- streaming 응답에는 reasoning delta가 먼저 오고 최종 content가 뒤따를 수 있다.
+- provider-pool은 여러 runtime 후보를 사용하므로 token 단위 출력, reasoning field 이름, chunk 경계가 완전히 동일하다고 가정하지 않는다.
+- exact-output match보다 HTTP 성공, 정상 JSON/SSE 구조, 최종 assistant content 존재 여부를 우선 판정한다.
+
+Reasoning을 provider에서 생성하게 두되 외부 사용자에게 보이지 않게 하려면, 현재 안정 기준은 `think` 관련 파라미터를 생략하고 client에서 reasoning field를 무시하는 것이다.
+
+## 검증 순서
+
+1. Model 목록 확인:
+
+```bash
+curl -fsS http://digitalplatform-iop.cloud:18086/v1/models \
+  -H 'Authorization: Bearer <token>'
+```
+
+2. Non-stream Chat Completions 확인:
+
+```bash
+curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token>' \
+  -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"ok만 응답해줘."}],"stream":false}'
+```
+
+3. Streaming Chat Completions 확인:
+
+```bash
+curl -N http://digitalplatform-iop.cloud:18086/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token>' \
+  -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"ok만 응답해줘."}],"stream":true}'
+```
+
+성공 판정은 HTTP 200, OpenAI-compatible `choices[]` 구조, 최종 assistant 응답 수신 기준으로 한다. Reasoning field가 포함되는 것만으로 실패로 보지 않는다.
--- a/docs/dev-corp-pi-settings-guide.md
+++ b/docs/dev-corp-pi-settings-guide.md
@ -0,0 +1,204 @@
+# dev-corp Pi Settings Guide
+
+이 문서는 host-local Pi coding agent를 dev-corp `gemma4:26b` provider-pool에 맞춰 설정할 때의 기준이다. 일반 OpenAI-compatible HTTP 직접 호출은 `docs/dev-corp-openai-compatible-call-guide.md`를 따른다.
+
+## 대상 범위
+
+- Pi package: `pi-coding-agent`
+- 확인된 Pi version: `0.80.3`
+- Pi binary: `pi`
+- 설정 디렉터리: `~/.pi/agent`
+- 설정 파일:
+  - `~/.pi/agent/settings.json`
+  - `~/.pi/agent/models.json`
+- 대상 provider: `dev-corp`
+- 대상 model: `gemma4:26b`
+- Base URL: `http://digitalplatform-iop.cloud:18086/v1`
+
+이 가이드는 dev-corp Gemma4 Pi profile 전용이다. dev/Qwen profile, direct provider 실험 profile, IOP Edge/Node/provider/vLLM runtime 설정으로 일반화하지 않는다.
+
+## 핵심 원칙
+
+- Pi 쪽 설정만 바꾼다. IOP Edge config, Node config, provider runtime, vLLM/vLLM-MLX launch option은 건드리지 않는다.
+- `apiKey`, `authHeader` 같은 secret 값은 새로 출력하거나 tracked 문서에 기록하지 않는다.
+- `dev-corp` provider가 기본값이어야 하며 direct provider profile을 기본값으로 두지 않는다.
+- Pi의 `openai-completions` 경로는 Chat Completions streaming 호출 기준이다. 일반 HTTP `stream:false` 측정은 Pi가 아니라 표준 caller 가이드에서 다룬다.
+- dev-corp `gemma4:26b`는 provider-pool catalog와 provider runtime이 thinking enabled 기준으로 맞춰져 있다. Pi에서 thinking disable을 시도하지 않는다.
+
+## settings.json 기준
+
+`~/.pi/agent/settings.json`의 dev-corp 기준값:
+
+```json
+{
+  "defaultProvider": "dev-corp",
+  "defaultModel": "gemma4:26b",
+  "defaultThinkingLevel": "high",
+  "hideThinkingBlock": false,
+  "httpIdleTimeoutMs": 300000,
+  "retry": {
+    "provider": {
+      "timeoutMs": 300000,
+      "maxRetries": 0,
+      "maxRetryDelayMs": 60000
+    }
+  },
+  "enabledModels": [
+    "dev-corp-direct/**",
+    "dev-corp-spark01/**",
+    "dev-corp/*"
+  ]
+}
+```
+
+`lastChangelogVersion`, `theme` 같은 Pi UI/local preference field는 기존 값을 보존한다.
+
+## models.json 기준
+
+`~/.pi/agent/models.json`에는 최소한 `providers.dev-corp`가 아래 의미를 가져야 한다. 예시의 `<preserve-existing-secret>`은 새 값으로 덮어쓰지 말고 기존 값을 유지한다는 뜻이다.
+
+```json
+{
+  "providers": {
+    "dev-corp": {
+      "baseUrl": "http://digitalplatform-iop.cloud:18086/v1",
+      "api": "openai-completions",
+      "apiKey": "<preserve-existing-secret>",
+      "authHeader": "<preserve-existing-secret>",
+      "compat": {
+        "supportsStore": false,
+        "supportsDeveloperRole": false,
+        "supportsReasoningEffort": false,
+        "supportsUsageInStreaming": false,
+        "maxTokensField": "max_tokens",
+        "requiresToolResultName": true,
+        "requiresAssistantAfterToolResult": true,
+        "supportsStrictMode": false
+      },
+      "models": [
+        {
+          "id": "gemma4:26b",
+          "name": "dev-corp gemma4:26b",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 262144,
+          "maxTokens": 32768,
+          "cost": {
+            "input": 0,
+            "output": 0,
+            "cacheRead": 0,
+            "cacheWrite": 0
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+`dev-corp-direct`와 `dev-corp-spark01` provider가 있더라도 fallback/실험용으로만 둔다. 기본 provider/model은 항상 `dev-corp` / `gemma4:26b`다.
+
+## Gemma4 한계와 Pi 설정 의미
+
+현재 dev-corp `gemma4:26b` provider-pool은 Gemma4 agent/tool-call 호환성을 위해 provider runtime을 `reasoning_parser=gemma4`, `tool_call_parser=gemma4`, thinking enabled, long-context 기준으로 맞춰 둔 상태다. 이 값들은 provider 쪽 최적화 지점이므로 Pi 설정에서 우회하지 않는다.
+
+주의할 점:
+
+- `supportsReasoningEffort`는 `false`로 둔다. `true`로 바꾸면 Pi가 `reasoning_effort`를 보낼 수 있고, 현재 provider-pool 안정 경로와 어긋날 수 있다.
+- `defaultThinkingLevel`은 `high`로 둔다. 단, dev-corp `supportsReasoningEffort=false` 기준에서는 Pi가 top-level `reasoning_effort=high`를 보내는 용도가 아니라 profile alignment와 UI 기준값이다.
+- `hideThinkingBlock`은 현재 기준 `false`다. reasoning이 흘러오는지 관측 가능한 baseline을 유지한다. UI에서 숨김이 필요하더라도 provider thinking disable과 혼동하지 않는다.
+- `thinking_token_budget`, `think=false`, `reasoning_effort=none` 같은 요청 파라미터를 Pi 설정으로 강제하지 않는다.
+- Pi가 보는 context window는 `262144`, max output token 기준은 `32768`이다. provider runtime과 IOP catalog도 이 범위에 맞춰져 있어야 한다.
+
+Reasoning을 생성하게 두되 사용자에게 노출하지 않는 정책은 Pi UI/rendering 또는 별도 client filtering 문제다. provider/vLLM 설정이나 IOP provider-pool 기본 파라미터를 바꿔 해결하지 않는다.
+
+## 검증
+
+설정 후 secret을 출력하지 않는 범위에서 아래를 확인한다.
+
+```bash
+pi --version
+jq '{defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock, httpIdleTimeoutMs, retry, enabledModels}' ~/.pi/agent/settings.json
+jq '.providers["dev-corp"] | {
+  baseUrl,
+  api,
+  hasApiKey: has("apiKey"),
+  hasAuthHeader: has("authHeader"),
+  compat,
+  models
+}' ~/.pi/agent/models.json
+```
+
+기대값:
+
+- `pi --version`은 현재 기준 `0.80.3`
+- `defaultProvider`는 `dev-corp`
+- `defaultModel`은 `gemma4:26b`
+- `defaultThinkingLevel`은 `high`
+- `providers.dev-corp.baseUrl`은 `http://digitalplatform-iop.cloud:18086/v1`
+- `providers.dev-corp.api`는 `openai-completions`
+- `providers.dev-corp.compat.supportsReasoningEffort`는 `false`
+- `providers.dev-corp.compat.maxTokensField`는 `max_tokens`
+- `providers.dev-corp.models[0].contextWindow`는 `262144`
+- `providers.dev-corp.models[0].maxTokens`는 `32768`
+
+실제 호출 검증은 짧은 prompt로 수행한다. tool-call 검증이 목적이면 일반 chat smoke와 별도로 forced tool call, auto tool call, streaming `delta.tool_calls`, tool result 후 최종 답변을 확인한다.
+
+## Codex/Claude 작업 프롬프트
+
+아래 프롬프트는 Codex나 Claude에게 host-local Pi 설정을 맡길 때 그대로 전달하는 기준이다.
+
+```text
+현재 호스트의 Pi coding agent를 dev-corp Gemma4 provider-pool 기준으로 맞춰줘.
+
+범위:
+- 수정 가능: ~/.pi/agent/settings.json, ~/.pi/agent/models.json
+- 수정 금지: IOP repo 설정, Edge config, Node config, provider runtime, vLLM/vLLM-MLX start script, secret 원문 출력
+- 현재 기준 provider/model: dev-corp / gemma4:26b
+- Base URL: http://digitalplatform-iop.cloud:18086/v1
+- Pi API: openai-completions
+
+작업 규칙:
+1. 먼저 pi --version, ~/.pi/agent/settings.json, ~/.pi/agent/models.json 구조를 확인해.
+2. apiKey, authHeader, token, secret 값은 화면에 출력하지 말고 기존 값을 보존해.
+3. 편집 전 settings.json과 models.json을 timestamp가 붙은 백업 파일로 복사해.
+4. settings.json에는 아래 기준을 반영해:
+   - defaultProvider: dev-corp
+   - defaultModel: gemma4:26b
+   - defaultThinkingLevel: high
+   - hideThinkingBlock: false
+   - httpIdleTimeoutMs: 300000
+   - retry.provider.timeoutMs: 300000
+   - retry.provider.maxRetries: 0
+   - retry.provider.maxRetryDelayMs: 60000
+   - enabledModels: ["dev-corp-direct/**", "dev-corp-spark01/**", "dev-corp/*"]
+   - theme, lastChangelogVersion 등 기존 UI/local preference는 보존
+5. models.json의 providers.dev-corp는 아래 기준을 반영해:
+   - baseUrl: http://digitalplatform-iop.cloud:18086/v1
+   - api: openai-completions
+   - 기존 apiKey/authHeader는 보존
+   - compat.supportsStore: false
+   - compat.supportsDeveloperRole: false
+   - compat.supportsReasoningEffort: false
+   - compat.supportsUsageInStreaming: false
+   - compat.maxTokensField: max_tokens
+   - compat.requiresToolResultName: true
+   - compat.requiresAssistantAfterToolResult: true
+   - compat.supportsStrictMode: false
+   - model id: gemma4:26b
+   - model name: dev-corp gemma4:26b
+   - reasoning: true
+   - input: ["text"]
+   - contextWindow: 262144
+   - maxTokens: 32768
+   - cost input/output/cacheRead/cacheWrite: 0
+6. dev-corp-direct 또는 dev-corp-spark01 provider가 있으면 삭제하지 말고 fallback/실험용으로 보존해. 단 defaultProvider/defaultModel은 dev-corp/gemma4:26b로 둬.
+7. supportsReasoningEffort를 true로 바꾸거나 think=false, reasoning_effort=none, thinking_token_budget 강제 설정을 추가하지 마. dev-corp Gemma4 provider-pool은 현재 thinking enabled 기준으로 튜닝되어 있고, reasoning hide는 provider 설정 변경이 아니라 client/UI 처리 문제야.
+8. 변경 후 jq로 secret 없이 핵심 값만 출력해서 검증해.
+
+검증 출력에는 apiKey/authHeader 원문을 절대 포함하지 말고, hasApiKey/hasAuthHeader boolean 정도만 보여줘.
+```
+
+## 실패 시 되돌리기
+
+백업한 파일로 `settings.json`과 `models.json`을 되돌린 뒤 Pi를 다시 실행한다. 실패가 `think=false`, `reasoning_effort`, `thinking_token_budget`, direct provider URL 변경과 관련되어 보이면 해당 변경을 제거하고 dev-corp public Edge route 기준으로 복원한다.
--- a/docs/edge-local-dev-guide.md
+++ b/docs/edge-local-dev-guide.md
@ -133,23 +133,24 @@ http://<edge-host>:18081/v1

 ## 7. Thinking/Reasoning 제어 smoke

-`/v1/chat/completions` 요청은 `think`, `reasoning_effort`, `thinking_token_budget`, `include_reasoning`으로 thinking/reasoning 동작과 응답 노출을 제어할 수 있다.
+`/v1/chat/completions` 요청은 `think`, `reasoning_effort`, `thinking_token_budget`, `include_reasoning`으로 thinking/reasoning 동작과 응답 노출을 제어할 수 있다. 단, provider-pool pure `passthrough`는 provider body 보존이 우선이므로 `include_reasoning=false`만으로 IOP-side reasoning 제거를 보장하지 않는다.

- 공통 안정 smoke: `think` 생략, `include_reasoning=false`, 또는 budget-only `thinking_token_budget`
- `think=false`: reasoning 생성을 끄고 content stream이 유지되어야 한다.
- `include_reasoning=false`: thinking 생성은 허용하고 response reasoning_content만 숨김.
- `reasoning_effort=low|medium|high`: provider 매핑에 따라 unsupported error를 반환할 수 있다.
+- dev-corp `gemma4:26b` provider-pool 안정 smoke: `think`, `reasoning_effort`, `thinking_token_budget`을 생략하고 현재 provider/vLLM 기본값을 유지한다.
+- 일반 표준 caller의 `stream=false` 측정은 `/v1/chat/completions`에서 요청 파라미터만으로 확인한다.
+- `include_reasoning=false`는 non-provider normalized route의 hide 동작 기준이다. dev-corp `gemma4:26b` provider-pool pure `passthrough`에서는 client가 reasoning field를 선택적으로 무시/제거한다.
+- `think=false` 또는 `reasoning_effort=none`은 hide-only 옵션이 아니라 thinking disable 요청이다. dev-corp `gemma4:26b` 기본 안정 smoke에서는 쓰지 않는다.
+- 세부 표와 금지/허용 범위는 `agent-contract/outer/openai-compatible-api.md`의 dev-corp `gemma4:26b` provider-pool passthrough 파라미터 범위를 기준으로 한다.

-예시 (thinking 비활성화):
+예시 (dev-corp `gemma4:26b` provider-pool non-stream 측정, think 생략):

 ```bash
 curl -fsS http://<edge-host>:18081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
-  -d '{"model":"<model-alias>","messages":[{"role":"user","content":"hello"}],"think":false}'
+  -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"hello"}],"stream":false}'
 ```

-예시 (thinking 생성은 허용하고 response reasoning_content만 숨김):
+예시 (non-provider normalized route에서 response reasoning_content 숨김):

 ```bash
 curl -fsS http://<edge-host>:18081/v1/chat/completions \
@ -169,4 +170,4 @@ Pi/Cline형 긴 agent prompt와 `tools[]` 요청은 provider가 native `tool_cal
 - 요청 `tools[]`에 있는 valid tool-call은 `message.tool_calls` 또는 stream `delta.tool_calls`와 `finish_reason: "tool_calls"`로 정규화된다.
 - 요청 `tools[]`에 없는 unknown tool hallucination이나 malformed 블록은 success content가 아니라 `tool_validation_error`로 끝난다.

-evidence는 tracked 문서가 아니라 ignored run 위치(`agent-test/runs/**`) 또는 code-review output path에 저장한다.
+evidence는 tracked 문서가 아니라 ignored run 위치(`agent-test/runs/**`) 또는 code-review output path에 저장한다.
--- a/docs/openai-compatible-api-contract.md
+++ b/docs/openai-compatible-api-contract.md
@ -9,5 +9,8 @@
 - Chat Completions provider route의 기본 응답 mode는 provider-original `passthrough`다.
 - caller는 `metadata.iop_response_mode`에 `passthrough`, `passthrough+sideband`, `transformed` 중 하나를 넣어 응답 경로를 선택할 수 있다.
 - `passthrough+sideband`와 `transformed`는 IOP 확장/변환 응답이며 provider-original byte identity로 취급하지 않는다.
+- dev-corp `gemma4:26b` provider-pool에서 `think`/`stream`/`include_reasoning` 요청 파라미터만 바꿔 측정하는 범위는 계약 원문의 `dev-corp gemma4:26b provider-pool passthrough 파라미터 범위` 표를 기준으로 한다.
+- dev-corp `digitalplatform-iop.cloud` 직접 호출 가이드는 [dev-corp-openai-compatible-call-guide.md](./dev-corp-openai-compatible-call-guide.md)를 기준으로 한다.
+- dev-corp Pi coding agent 설정 가이드는 [dev-corp-pi-settings-guide.md](./dev-corp-pi-settings-guide.md)를 기준으로 한다.

 에이전트 작업에서는 [agent-contract/index.md](../agent-contract/index.md)의 라우팅 규칙을 먼저 따른다.