pi-dynamic-models

pi install @ssweens/pi-dynamic-models

Dynamic model discovery for pi. Point it at any OpenAI-compatible, Anthropic, or Google API server and it fetches available models at startup — no manual model list needed.

Setup

1. Install the package

Add to your Pi agent settings (~/.pi/agent/settings.json):

{
  "packages": [
    "local:/path/to/playbook/packages/pi-dynamic-models"
  ]
}

2. Create the config file

Create ~/.pi/agent/settings/pi-dynamic-models.json:

[
  {
    "provider": "local-llm",
    "baseUrl": "http://192.168.1.51:9999/v1",
    "apiKey": "MY_API_KEY",
    "api": "openai-completions",
    "compat": {
      "supportsUsageInStreaming": true,
      "maxTokensField": "max_tokens"
    }
  },
  {
    "provider": "my-proxy",
    "baseUrl": "http://localhost:8082",
    "apiKey": "secret",
    "api": "anthropic-messages"
  }
]

Fields

| Field | Required | Description | |-------|----------|-------------| | provider | ✓ | Name shown in the model selector | | baseUrl | ✓ | Server URL, including /v1 if needed | | api | | Pi API type (default: openai-completions). See below. | | apiKey | | Literal key, env var name, or !shell-command — same resolution as models.json. Omit for open servers. | | compat | | OpenAI compat overrides applied to every model. See below. | | models | | Per-model metadata keyed by model ID. Overrides defaults for discovered models. Models listed here but not returned by the server are still registered. |

models override fields (all optional)

| Field | Type | Default | |-------|------|---------| | name | string | model ID | | reasoning | boolean | false | | input | ["text"] | ["text","image"] | ["text"] | | contextWindow | number | 128000 | | maxTokens | number | 16384 |

If the server is unreachable at startup, only models explicitly listed in models are registered.

Supported API types

Any Pi KnownApi value:

| Value | Use for | |-------|---------| | openai-completions | Ollama, vLLM, LM Studio, llama.cpp, most local servers | | openai-responses | OpenAI Responses API compatible servers | | anthropic-messages | Anthropic-compatible proxies | | google-generative-ai | Google AI compatible servers | | azure-openai-responses | Azure OpenAI |

compat fields (openai-completions only)

| Field | Type | Description | |-------|------|-------------| | supportsStore | boolean | Whether the server supports the store field | | supportsDeveloperRole | boolean | Whether to use developer role instead of system | | supportsReasoningEffort | boolean | Whether the server supports reasoning_effort | | supportsUsageInStreaming | boolean | Whether stream_options: {include_usage: true} works | | maxTokensField | "max_tokens" | "max_completion_tokens" | Which field to use for max output tokens | | requiresToolResultName | boolean | Whether tool results require the name field | | requiresAssistantAfterToolResult | boolean | Whether an assistant message is required between tool result and next user message | | requiresThinkingAsText | boolean | Whether thinking blocks must be converted to <thinking> text | | requiresMistralToolIds | boolean | Whether tool call IDs must be normalized to Mistral format | | thinkingFormat | "openai" | "zai" | "qwen" | Format for reasoning/thinking parameter | | supportsStrictMode | boolean | Whether the strict field in tool definitions is supported |

Overriding model metadata

Discovered models use conservative defaults (contextWindow: 128000, maxTokens: 16384, reasoning: false, input: ["text"]). Override them directly in the config file using the models dict:

{
  "provider": "local-llm",
  "baseUrl": "http://192.168.1.51:9999/v1",
  "models": {
    "my-model-id": {
      "name": "My Model",
      "reasoning": true,
      "input": ["text", "image"],
      "contextWindow": 200000,
      "maxTokens": 32000
    }
  }
}

Troubleshooting

No models appear: Check that the config file exists at ~/.pi/agent/settings/pi-dynamic-models.json and the server is reachable.

Wrong API behavior: Set the correct api field for your server type.

Token counting or field errors: Add the appropriate compat settings for your server.