@oh-my-pi/pi-coding-agent 12.7.6 → 12.8.0

package/docs/models.md

@@ -1,234 +0,0 @@
-# `models.yml` provider integration guide
-
-`models.yml` lets you register custom model providers (local or hosted), override built-in providers, and tune model metadata.
-
-Default location:
-
-- `~/.omp/agent/models.yml`
-
-Legacy support:
-
-- `models.json` is still read and auto-migrated to `models.yml` when possible.
-
-## Top-level shape
-
-```yaml
-providers:
-  <provider-name>:
-    # Provider config
-```
-
-`<provider-name>` is the provider ID used everywhere else (selection, auth lookup, etc.).
-
-## Provider fields
-
-```yaml
-providers:
-  my-provider:
-    baseUrl: https://api.example.com/v1
-    apiKey: MY_PROVIDER_API_KEY
-    api: openai-responses
-    headers:
-      X-Custom-Header: value
-    authHeader: true
-    auth: apiKey
-    discovery:
-      type: ollama
-    modelOverrides:
-      <model-id-within-provider>:
-        name: Friendly Name
-    models:
-      - id: model-id
-        name: My Model
-        api: openai-responses
-        reasoning: false
-        input: [text]
-        cost:
-          input: 0
-          output: 0
-          cacheRead: 0
-          cacheWrite: 0
-        contextWindow: 128000
-        maxTokens: 16384
-        headers:
-          X-Model-Header: value
-        compat:
-          supportsStore: true
-          supportsDeveloperRole: true
-          supportsReasoningEffort: true
-          maxTokensField: max_completion_tokens
-          openRouterRouting:
-            only: [anthropic]
-          vercelGatewayRouting:
-            order: [openai, anthropic]
-```
-
-### `api` values
-
-Supported API adapters:
-
-- `openai-completions`
-- `openai-responses`
-- `openai-codex-responses`
-- `azure-openai-responses`
-- `anthropic-messages`
-- `google-generative-ai`
-- `google-vertex`
-
-`auth` values:
-
-- `apiKey` (default)
-- `none`
-
-`discovery.type` values:
-
-- `ollama`
-
-If `discovery` is set, provider-level `api` is required.
-
-## Required vs optional
-
-### Full custom provider (defines `models`)
-
-If `models` is non-empty, you must set:
-
-- `baseUrl`
-- `apiKey` (unless `auth: none`)
-- `api` at provider level or per model
-
-If `auth: none` is set, `apiKey` is optional even when `models` are defined.
-
-### Override-only provider (no `models`)
-
-If `models` is empty/missing, set at least one of:
-
-- `baseUrl`
-- `modelOverrides`
-- `discovery`
-
-Use this to modify built-in providers without redefining all models.
-
-Default values when omitted in a model definition:
-
-- `reasoning: false`
-- `input: [text]`
-- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
-- `contextWindow: 128000`
-- `maxTokens: 16384`
-
-Header merge behavior:
-
-- Provider `headers` are applied first
-- Model-level `headers` override provider headers on key conflicts
-## Merge behavior
-
-`models.yml` does not replace the built-in registry.
-
-1. Built-in models load first.
-2. Provider-level overrides (`baseUrl`, `headers`) are applied.
-3. `modelOverrides` are applied by model ID within each provider.
-4. Custom `models` are merged in.
-5. If a custom model has the same `provider + id` as an existing model, it replaces that model.
-
-## API key behavior
-
-`apiKey` resolution is:
-
-1. Treat value as env var name (preferred)
-2. If env var not found, treat value as literal key
-
-Example:
-
-```yaml
-apiKey: OPENROUTER_API_KEY
-```
-
-If `OPENROUTER_API_KEY` exists, that value is used. Otherwise, the literal string `OPENROUTER_API_KEY` is used as the token.
-
-Use `authHeader: true` when your endpoint expects:
-
-```http
-Authorization: Bearer <apiKey>
-```
-
-Set `auth: none` for keyless providers (local gateways, unauthenticated dev endpoints).
-
-## Practical integration patterns
-
-### 1) OpenAI-compatible endpoint (vLLM / LM Studio / gateway)
-
-```yaml
-providers:
-  local-openai:
-    baseUrl: http://127.0.0.1:8000/v1
-    auth: none
-    api: openai-completions
-    models:
-      - id: Qwen/Qwen2.5-Coder-32B-Instruct
-        name: Qwen 2.5 Coder 32B (local)
-```
-
-### 2) Anthropic-compatible proxy
-
-```yaml
-providers:
-  anthropic-proxy:
-    baseUrl: https://proxy.example.com/anthropic
-    apiKey: ANTHROPIC_PROXY_KEY
-    api: anthropic-messages
-    authHeader: true
-    models:
-      - id: claude-sonnet-4-20250514
-        name: Claude Sonnet 4 (Proxy)
-        reasoning: true
-        input: [text, image]
-```
-
-### 3) Override built-in provider without redefining models
-
-```yaml
-providers:
-  openrouter:
-    baseUrl: https://my-corp-proxy.example.com/v1
-    headers:
-      X-Team: platform
-    modelOverrides:
-      anthropic/claude-sonnet-4:
-        name: Sonnet 4 (Corp Route)
-```
-
-### 4) Runtime discovery for Ollama
-
-```yaml
-providers:
-  ollama:
-    baseUrl: http://127.0.0.1:11434
-    api: openai-completions
-    auth: none
-    discovery:
-      type: ollama
-```
-
-The agent will query `GET /api/tags` and register discovered models dynamically.
-
-## Validation failures to watch for
-
-Common schema/validation errors:
-
-- Provider with `models` but missing `baseUrl`
-- Provider with `models` and `auth != none` but missing `apiKey`
-- Model missing `api` when neither provider-level nor model-level `api` is set
-- Non-positive `contextWindow` or `maxTokens`
-- `discovery` configured without provider-level `api`
-
-When `models.yml` has errors, the agent falls back to built-in models and reports a load error.
-
-## Quick start
-
-1. Create `~/.omp/agent/models.yml`
-2. Add one provider with one model
-3. Start the agent and open `/model`
-4. Confirm your provider/model appears
-5. If auth fails, check env vars and `authHeader`
-
-For SDK usage, `ModelRegistry` also accepts a custom path so you can load non-default `models.yml` files programmatically.

package/docs/python-repl.md

@@ -1,110 +0,0 @@
-# Python REPL (Jupyter Kernel Gateway)
-
-## Requirements
-
-- Python 3 available on PATH (or via an active virtualenv)
-- `jupyter-kernel-gateway` (`kernel_gateway` module) and `ipykernel` installed in the selected Python environment
-
-Install:
-
-```bash
-python -m pip install jupyter_kernel_gateway ipykernel
-```
-
-## How It Works
-
-The Python tool uses a Jupyter Kernel Gateway and talks to it over REST and WebSocket APIs.
-By default it uses a shared local gateway so multiple pi instances reuse the same gateway process.
-
-Shared-gateway startup flow:
-
-1. Filter the environment and resolve the Python runtime (including venv detection)
-2. Acquire the shared gateway (reuse a healthy gateway or spawn `python -m kernel_gateway` on 127.0.0.1:PORT)
-3. Wait for gateway readiness (`GET /api/kernelspecs`)
-4. Create a kernel (`POST /api/kernels`)
-5. Connect WebSocket for execution messages
-6. Initialize kernel environment, run prelude helpers, and load extension modules
-
-## External Gateway Support
-
-Instead of spawning a local gateway, you can connect to an already-running Jupyter Kernel Gateway:
-
-```bash
-# Connect to external gateway
-export PI_PYTHON_GATEWAY_URL="http://127.0.0.1:8888"
-
-# Optional: auth token if gateway requires it (KG_AUTH_TOKEN)
-export PI_PYTHON_GATEWAY_TOKEN="your-token-here"
-```
-
-When `PI_PYTHON_GATEWAY_URL` is set:
-
-- No local gateway process is spawned
-- Kernels are created on the external gateway
-- The gateway process is not killed on shutdown
-- Availability check uses `/api/kernelspecs` endpoint instead of local module check
-
-This is useful for:
-
-- Remote kernel execution
-- Shared kernel environments
-- Pre-configured gateway setups
-
-## Environment Propagation
-
-- The kernel inherits a filtered environment (explicit allowlist + denylist)
-- Allowlisted prefixes include `LC_`, `XDG_`, and `PI_`; known API-key vars are removed
-- `PYTHONPATH` is passed through if present
-- Virtual environments are detected via `VIRTUAL_ENV`, `.venv/`, or `venv/` and preferred when present
-
-## Prelude Extensions
-
-Optional `.py` modules are loaded after the prelude from:
-
-- `~/.omp/agent/modules` and `~/.pi/agent/modules`
-- `<project>/.omp/modules` and `<project>/.pi/modules`
-
-Project modules override user modules with the same filename.
-
-## Kernel Modes
-
-Settings under `python` control exposure and reuse:
-
-- `toolMode`: `both` (default), `ipy-only`, `bash-only`
-- `kernelMode`: `session` (default) or `per-call`
-- `sharedGateway`: `true` (default). Setting to `false` throws an error because local (per-process) gateways are not supported; the shared gateway is required.
-
-Mode behavior:
-
-- `session`: reuse kernels per session id, serialize execution, evict after 5 minutes of idle time (max 4 sessions)
-- `per-call`: create a fresh kernel per tool call and shut it down afterward
-
-Environment override:
-
-- `PI_PY=0|bash` → `bash-only`
-- `PI_PY=1|py` → `ipy-only`
-- `PI_PY=mix|both` → `both`
-
-## Shell Helper
-
-The Python prelude exposes `run()` which executes a shell command via `bash -c` (or `sh -c` fallback)
-and returns a `ShellResult` with `stdout`, `stderr`, and `code`.
-
-## Output Handling
-
-- Streams `stdout`/`stderr` as text
-- `application/x-omp-status` emits structured status events for the TUI
-- `image/png` display data renders inline in TUI
-- `application/json` display data renders as a collapsible tree
-- `text/markdown` is rendered as-is, `text/plain` is used as a fallback
-- `text/html` display data is converted to basic markdown
-
-## Troubleshooting
-
-- **Kernel unavailable**: Ensure `python` + `jupyter-kernel-gateway` + `ipykernel` are installed; the session will fall back to bash-only.
-- **Python mode override**: Check `python.toolMode` or `PI_PY` if the Python tool is missing.
-- **Shared gateway disabled**: `python.sharedGateway=false` causes the Python tool to error because local (per-process) gateways are not supported.
-- **Skip preflight checks**: Set `PI_PYTHON_SKIP_CHECK=1` to bypass kernel availability checks.
-- **External gateway unreachable**: Check the URL is correct and the gateway is running. If auth is required, set `PI_PYTHON_GATEWAY_TOKEN`.
-- **IPC tracing**: Set `PI_PYTHON_IPC_TRACE=1` to log kernel message flow.
-- **Stdin requests**: Interactive input is not supported; refactor code to avoid `input()` or provide data programmatically.