docs: update dev-corp profile with sampling parameter extension

2026-07-10 07:40:02 +09:00 · 2026-07-10 07:40:02 +09:00 · 6ab66277b8
commit 6ab66277b8
parent 526bfb31a7
4 changed files with 118 additions and 4 deletions
--- a/agent-test/dev-corp/edge-smoke.md
+++ b/agent-test/dev-corp/edge-smoke.md
@ -57,7 +57,7 @@ dev-corp provider pool과 3-node 연결 상태를 점검할 때는 `agent-test/d
 - Edge-Node TCP transport 기본 후보: `digitalplatform-iop.cloud:18087`
 - mac-mini/internal 후보는 dev-corp Edge 경로가 아니다. Node `edge_addr`는 `digitalplatform-iop.cloud:18087`이어야 한다.
 - model alias 후보: `gemma4:26b`
- host Pi dev-corp profile: `agent-test/dev-corp/inventory.yaml`의 `model.pi_agent_profile` 기준. 2026-07-09 현재 Pi 기본 provider/model/thinking level은 `dev-corp` / `gemma4:26b` / `high`이며, base URL은 public Edge route `http://digitalplatform-iop.cloud:18086/v1`이다. dev `qwen3.6:35b` Pi profile은 `agent-test/dev/inventory.yaml`에서 별도로 관리한다.
+- host Pi dev-corp profile: `agent-test/dev-corp/inventory.yaml`의 `model.pi_agent_profile` 기준. 2026-07-10 현재 Pi 기본 provider/model/thinking level은 `dev-corp` / `gemma4:26b` / `high`이며, base URL은 public Edge route `http://digitalplatform-iop.cloud:18086/v1`이고 sampling parameter는 Pi extension으로 `temperature=0.2`, `top_p=0.95`를 주입한다. dev `qwen3.6:35b` Pi profile은 `agent-test/dev/inventory.yaml`에서 별도로 관리한다.

 노드 후보:

--- a/agent-test/dev-corp/inventory.yaml
+++ b/agent-test/dev-corp/inventory.yaml
@ -115,7 +115,7 @@ model:
    strict_output_behavior: provider_pool_catalog_default_overrides_strict_disable
    adapter_mapping: vllm_and_vllm_mlx_use_chat_template_kwargs_enable_thinking_true
  pi_agent_profile:
-    observed_at: "2026-07-09"
+    observed_at: "2026-07-10"
    config_scope: host_local_pi_agent
    config_dir: ~/.pi/agent
    install:
@ -124,6 +124,8 @@ model:
      binary: /opt/homebrew/bin/pi
      settings_file: ~/.pi/agent/settings.json
      models_file: ~/.pi/agent/models.json
+      extension_files:
+        - ~/.pi/agent/extensions/dev-corp-temperature.ts
    profile_namespace: dev_corp_gemma4_pi
    current_default_provider: dev-corp
    current_default_model: gemma4:26b
@ -132,6 +134,8 @@ model:
    current_default_api: openai-completions
    current_default_auth_header: true
    current_default_thinking_level: high
+    current_default_temperature: 0.2
+    current_default_top_p: 0.95
    hide_thinking_block: false
    http_idle_timeout_ms: 300000
    retry_provider_timeout_ms: 300000
@ -141,6 +145,12 @@ model:
      - dev-corp-direct/**
      - dev-corp-spark01/**
      - dev-corp/*
+    extensions:
+      - path: ~/.pi/agent/extensions/dev-corp-temperature.ts
+        registered_in_settings: extensions/dev-corp-temperature.ts
+        hook: before_provider_request
+        scope: dev-corp provider only
+        effect: inject temperature 0.2 and top_p 0.95 into provider request payload
    api_key_value_tracked: false
    route_policy: current dev-corp Pi default must use the public Edge route digitalplatform-iop.cloud.
    pi_model_parameters:
@ -152,6 +162,9 @@ model:
      max_tokens: 32768
      reasoning: true
      thinking_level: high
+      request_temperature: 0.2
+      request_top_p: 0.95
+      sampling_parameter_source: before_provider_request extension dev-corp-temperature.ts
      expected_iop_thinking_token_budget: 1024
      compat:
        supports_developer_role: false
@ -194,6 +207,8 @@ model:
        edge_context_window: 262144
        pi_max_tokens: 32768
        provider_default_max_tokens: 32768
+        pi_temperature: 0.2
+        pi_top_p: 0.95
        pi_reasoning: true
        edge_reasoning_policy: bounded_thinking
        edge_default_thinking_token_budget: 1024
--- a/docs/dev-corp-openai-compatible-call-guide.md
+++ b/docs/dev-corp-openai-compatible-call-guide.md
@ -14,6 +14,50 @@ dev-corp `gemma4:26b` 모델을 OpenAI-compatible 방식으로 직접 호출할

 `/v1/responses`가 아니라 `/v1/chat/completions`를 사용한다.

+## Pi 설정
+
+현재 호스트의 Pi dev-corp profile은 `~/.pi/agent/settings.json`과 `~/.pi/agent/models.json`을 기준으로 한다.
+
+필수 기본값:
+
+| 항목 | 값 |
+| --- | --- |
+| `defaultProvider` | `dev-corp` |
+| `defaultModel` | `gemma4:26b` |
+| `defaultThinkingLevel` | `high` |
+| `extensions` | `extensions/dev-corp-temperature.ts` |
+
+Pi `0.80.3`의 `models.json` provider/model schema에는 고정 sampling parameter 필드가 없다. dev-corp Pi 호출의 `temperature`와 `top_p`는 전역 extension `~/.pi/agent/extensions/dev-corp-temperature.ts`의 `before_provider_request` hook에서 적용한다.
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const DEV_CORP_PROVIDER = "dev-corp";
+const DEV_CORP_TEMPERATURE = 0.2;
+const DEV_CORP_TOP_P = 0.95;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_provider_request", (event, ctx) => {
+    if (ctx.model?.provider !== DEV_CORP_PROVIDER) return;
+    if (!isRecord(event.payload)) return;
+
+    return {
+      ...event.payload,
+      temperature: DEV_CORP_TEMPERATURE,
+      top_p: DEV_CORP_TOP_P,
+    };
+  });
+}
+```
+
+이 hook은 provider가 `dev-corp`일 때만 요청 payload에 `temperature: 0.2`, `top_p: 0.95`를 추가한다. `dev-corp-direct`, `dev-corp-spark01` 같은 direct provider에는 적용하지 않는다.
+
+이미 실행 중인 Pi session에는 `/reload` 또는 재시작 후 반영한다.
+
 ## 권장 요청

 기본 권장 호출은 `stream:true`다. `think`, `reasoning_effort`, `thinking_token_budget`은 보내지 않는다.
@ -49,6 +93,8 @@ curl -fsS http://digitalplatform-iop.cloud:18086/v1/chat/completions \
 | --- | --- |
 | `model` | `gemma4:26b` |
 | `stream` | 기본 `true`, 필요하면 `false` |
+| `temperature` | Pi dev-corp profile은 extension으로 `0.2` 고정 |
+| `top_p` | Pi dev-corp profile은 extension으로 `0.95` 고정 |
 | `think` | 생략 |
 | `reasoning_effort` | 생략 |
 | `thinking_token_budget` | 생략 |
--- a/docs/dev-corp-pi-settings-guide.md
+++ b/docs/dev-corp-pi-settings-guide.md
@ -27,7 +27,7 @@ pi --version
 디렉터리가 없으면 만든다.

 ```bash
-mkdir -p ~/.pi/agent
+mkdir -p ~/.pi/agent/extensions
 ```

 ## settings.json
@ -48,12 +48,54 @@ mkdir -p ~/.pi/agent
  },
  "enabledModels": [
    "dev-corp/*"
+  ],
+  "extensions": [
+    "extensions/dev-corp-temperature.ts"
  ]
 }
 ```

 기존 `theme`, `lastChangelogVersion` 같은 개인 설정은 유지해도 된다.

+## sampling parameter extension
+
+Pi `0.80.3`의 `models.json` provider/model schema에는 고정 sampling parameter 필드가 없다. dev-corp Pi 호출의 `temperature`와 `top_p`는 전역 extension의 `before_provider_request` hook으로 적용한다.
+
+파일 위치:
+
+```text
+~/.pi/agent/extensions/dev-corp-temperature.ts
+```
+
+내용:
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const DEV_CORP_PROVIDER = "dev-corp";
+const DEV_CORP_TEMPERATURE = 0.2;
+const DEV_CORP_TOP_P = 0.95;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_provider_request", (event, ctx) => {
+    if (ctx.model?.provider !== DEV_CORP_PROVIDER) return;
+    if (!isRecord(event.payload)) return;
+
+    return {
+      ...event.payload,
+      temperature: DEV_CORP_TEMPERATURE,
+      top_p: DEV_CORP_TOP_P,
+    };
+  });
+}
+```
+
+이 extension은 provider가 `dev-corp`일 때만 요청 payload에 `temperature: 0.2`, `top_p: 0.95`를 추가한다. `dev-corp-direct`, `dev-corp-spark01` 같은 direct provider에는 적용하지 않는다.
+
 ## models.json

 `apiKey`에는 실제 토큰을 넣는다. 토큰은 문서, 로그, 공유 화면에 남기지 않는다.
@ -101,14 +143,17 @@ mkdir -p ~/.pi/agent

 - `supportsReasoningEffort`는 `false`로 둔다.
 - `think=false`, `reasoning_effort=none`, `thinking_token_budget`을 강제로 추가하지 않는다.
+- dev-corp Pi 호출 sampling parameter는 `~/.pi/agent/extensions/dev-corp-temperature.ts`로 `temperature: 0.2`, `top_p: 0.95`를 주입한다.
 - Pi는 `openai-completions` 기준으로 streaming 호출을 기본 사용한다. non-stream이 필요한 경우는 Pi가 아니라 일반 OpenAI-compatible 호출에서 `stream:false`로 선택한다.
 - reasoning 표시 여부는 Pi UI나 client 표시 정책에서 선택적으로 처리한다.
+- 이미 실행 중인 Pi session에는 `/reload` 또는 재시작 후 extension 변경을 반영한다.

 ## 확인

 ```bash
 pi --version
-jq '{defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock}' ~/.pi/agent/settings.json
+jq '{defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock, extensions}' ~/.pi/agent/settings.json
+test -f ~/.pi/agent/extensions/dev-corp-temperature.ts
 jq '.providers["dev-corp"] | {
  baseUrl,
  api,
@ -128,6 +173,7 @@ jq '.providers["dev-corp"] | {
 - Pi 설치
 - ~/.pi/agent/settings.json
 - ~/.pi/agent/models.json
+- ~/.pi/agent/extensions/dev-corp-temperature.ts

 수정 금지:
 - 이 저장소 코드와 설정
@ -149,6 +195,12 @@ settings.json:
 - retry.provider.maxRetries: 0
 - retry.provider.maxRetryDelayMs: 60000
 - enabledModels: ["dev-corp/*"]
+- extensions: ["extensions/dev-corp-temperature.ts"]
+
+sampling parameter extension:
+- 파일: ~/.pi/agent/extensions/dev-corp-temperature.ts
+- before_provider_request hook에서 ctx.model.provider가 dev-corp일 때만 payload.temperature를 0.2, payload.top_p를 0.95로 설정
+- dev-corp-direct, dev-corp-spark01에는 적용하지 않음

 models.json:
 - providers.dev-corp.baseUrl: http://digitalplatform-iop.cloud:18086/v1
@ -172,4 +224,5 @@ models.json:

 think=false, reasoning_effort=none, thinking_token_budget 설정은 추가하지 마.
 검증 출력에는 apiKey 원문을 포함하지 말고 hasApiKey boolean만 보여줘.
+이미 실행 중인 Pi session에는 /reload 또는 재시작이 필요하다고 안내해줘.
 ```