iop/docs/dev-corp-pi-settings-guide.md

# 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 기준으로 복원한다.