Documentation
¶
Overview ¶
Package pimodels builds LLM clients for the providers pi-go supports, for use from outside pi-go.
It resolves a model name to a provider, finds the API key, and returns a Model — the ADK interface an agent consumes. That is the whole remit.
Isolation ¶
This package knows about models and providers. It knows nothing about agents, tools, sessions or skills, and it must stay that way: an embedder composes the two halves itself.
m, err := pimodels.New(ctx, "gpt-5.6-luna")
if err != nil {
return err
}
a, err := piagent.New(ctx, piagent.WithModel(m))
Because both packages meet at ADK's model.LLM rather than at each other, neither imports the other, and a change to provider handling cannot become a breaking change to the agent API.
API keys ¶
New reads the key from the provider's environment variable — OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, AZUREOPENAI_API_KEY, or <PROVIDER>_API_KEY for the rest. WithAPIKey overrides that. Providers that need no key, such as a local Ollama, work with neither set.
Nothing here reads pi-go's config file. FromConfig does, explicitly, for embedders that want the same model a `pi` session would pick.
Tracing ¶
WithTraceSink records the HTTP traffic of one client and delivers it to a callback, without touching process-global state. pi-go's own --trace-http machinery is not usable from an embedder: it needs httplog.SetEnabled and a globally installed sink, and the global sink is a single slot a library has no business claiming.
Index ¶
- func APIKeyEnvVar(providerName string) string
- func ContextWindow(modelName string) int64
- func ContextWindowFor(providerName, modelName string) int64
- func TraceMaxBody() int
- type Info
- type Model
- type Option
- func WithAPIKey(key string) Option
- func WithAdvisor(advisorModel string, maxUses int, caching bool) Option
- func WithBaseURL(url string) Option
- func WithCACert(path string) Option
- func WithConnectTimeout(d time.Duration) Option
- func WithHeaders(h map[string]string) Option
- func WithInsecureTLS() Option
- func WithLegacyMaxTokens() Option
- func WithMaxOutputTokens(n int64) Option
- func WithPromptCachingDisabled() Option
- func WithSystemCAsDisabled() Option
- func WithThinkingLevel[T ~string](level T) Option
- func WithTraceSink(fn func(TraceEntry)) Option
- func WithWebSearch() Option
- type ProviderNamer
- type ThinkingLevel
- type TraceEntry
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func APIKeyEnvVar ¶
APIKeyEnvVar names the environment variable New reads a provider's key from, so an embedder can report a missing credential precisely.
Example ¶
Report a missing credential precisely, rather than letting the first request fail with a provider-specific auth error.
package main
import (
"fmt"
"log"
"github.com/dimetron/pi-go/pimodels"
)
func main() {
info, err := pimodels.Resolve("grok-4.6")
if err != nil {
log.Fatal(err)
}
fmt.Printf("set %s to use %s\n", pimodels.APIKeyEnvVar(info.Provider), info.Provider)
}
Output: set XAI_API_KEY to use xai
func ContextWindow ¶
ContextWindow returns a model's context window in tokens, or 0 when the model is unknown. Prefer ContextWindowFor when the provider is known: an Azure deployment can share a name with an OpenAI model without sharing its window.
Example ¶
ContextWindow is how an embedder decides what fits before sending it.
package main
import (
"fmt"
"github.com/dimetron/pi-go/pimodels"
)
func main() {
fmt.Println(pimodels.ContextWindow("gemini-3.7-flash") > 0)
}
Output: true
func ContextWindowFor ¶
ContextWindowFor returns a model's context window for a specific provider.
func TraceMaxBody ¶ added in v0.1.6
func TraceMaxBody() int
TraceMaxBody returns the byte cap applied to a traced request or response body before it reaches a WithTraceSink function. A truncated entry reports it in BodyTruncated.
Types ¶
type Info ¶
type Info struct {
// Provider is the backend that will serve the model: "openai",
// "anthropic", "gemini", "mistral", "xai", "ollama", "azure", "opencode"
// or "agentgateway".
Provider string
// Model is the model name as the provider expects it, with any routing
// prefix such as "ollama/" removed.
Model string
// BaseURL is the endpoint finally selected. Recorded because the same
// model name served by Ollama, by a gateway and by a vendor API behaves
// differently, and a trace without it cannot be reproduced.
BaseURL string
// Ollama reports whether the model is served by an Ollama daemon.
Ollama bool
// LocalOllama reports that an explicit ollama/ prefix selected the local
// daemon. It preserves that routing decision when the Info is passed to
// NewFromInfo, even if the stripped model name also looks like an Ollama
// cloud tag.
LocalOllama bool
// Custom reports whether an explicit OpenAI-compatible endpoint was used.
Custom bool
}
Info describes how a model name was resolved.
func Resolve ¶
Resolve reports how a model name would be routed, without building a client or needing a credential. Useful for validating configuration at startup.
Example ¶
Resolve answers "where would this request actually go" without building a client or needing a credential — worth doing at startup, so a misconfigured model name fails before the first request rather than during it.
package main
import (
"fmt"
"log"
"github.com/dimetron/pi-go/pimodels"
)
func main() {
info, err := pimodels.Resolve("claude-sonnet-5")
if err != nil {
log.Fatal(err)
}
fmt.Println(info.Provider)
}
Output: anthropic
Example (Ollama) ¶
A local Ollama model needs no credential at all.
package main
import (
"fmt"
"log"
"github.com/dimetron/pi-go/pimodels"
)
func main() {
info, err := pimodels.Resolve("ollama/gemma4:e4b")
if err != nil {
log.Fatal(err)
}
fmt.Println(info.Provider, info.Model, info.Ollama)
}
Output: ollama gemma4:e4b true
type Model ¶
Model is the interface an ADK agent consumes. Aliased so an embedder using only this package does not have to import ADK to name the return type; it is the same type, so passing it to any ADK agent works unchanged.
func FromConfig ¶
FromConfig builds the model a `pi` session would use for the given role, reading ~/.pi-go/config.json and any project config.
An empty role means "default". This is the one function here that touches pi-go's own configuration; New is self-contained and takes an explicit name.
func New ¶
New resolves modelName and returns a client for it.
The provider is inferred from the name: "gpt-*" is OpenAI, "claude-*" is Anthropic, "gemini-*" is Gemini, "grok-*" is xAI, an "ollama/" prefix or a ":cloud" suffix routes to Ollama, and so on. Pass WithBaseURL to override the endpoint for any of them.
Example ¶
The common case: name a model, get a client. The provider is inferred from the name and the key comes from that provider's environment variable.
package main
import (
"context"
"log"
"github.com/dimetron/pi-go/pimodels"
)
func main() {
ctx := context.Background()
m, err := pimodels.New(ctx, "gpt-5.6-luna")
if err != nil {
log.Fatal(err)
}
// m is an ADK model.LLM. Hand it to any ADK agent — including pi-go's,
// which takes it as piagent.WithModel(m).
_ = m
}
Output:
Example (Gateway) ¶
Point the client at a gateway or a self-hosted OpenAI-compatible server. The explicit endpoint wins over anything inferred from the model name.
package main
import (
"context"
"log"
"github.com/dimetron/pi-go/pimodels"
)
func main() {
ctx := context.Background()
m, err := pimodels.New(ctx, "gpt-5.6-luna",
pimodels.WithBaseURL("https://llm-gateway.internal/v1"),
pimodels.WithAPIKey("tenant-key"),
pimodels.WithHeaders(map[string]string{"X-Tenant": "acme"}),
)
if err != nil {
log.Fatal(err)
}
_ = m
}
Output:
func NewFromInfo ¶ added in v0.0.84
NewFromInfo builds a client from the result of Resolve, without reparsing Info.Model as a fresh model name. Use it when startup code first inspects a model with Resolve and later wants to construct exactly that resolved provider/model pair.
type Option ¶
type Option func(*options)
Option configures New. Options are applied in order, so a later one wins.
func WithAPIKey ¶
WithAPIKey sets the credential explicitly, overriding the environment.
func WithAdvisor ¶
WithAdvisor enables an advisor model for providers that support it, bounded by maxUses per request (0 = unbounded).
func WithBaseURL ¶
WithBaseURL points the client at a different endpoint — a gateway, a proxy, or a self-hosted OpenAI-compatible server.
func WithCACert ¶
WithCACert trusts a PEM bundle in addition to the system roots — the answer for a TLS-intercepting corporate proxy, which otherwise forces callers to disable verification for every endpoint.
func WithConnectTimeout ¶
WithConnectTimeout bounds connection establishment. It deliberately does not bound the request: streaming completions run long, and a request timeout that is short enough to be useful for connect is short enough to kill them.
func WithHeaders ¶
WithHeaders adds headers to every request, for gateways that need routing or tenancy metadata.
func WithInsecureTLS ¶
func WithInsecureTLS() Option
WithInsecureTLS disables certificate verification.
Prefer WithCACert: this turns verification off for every endpoint the client reaches, not just the one that needed it.
func WithLegacyMaxTokens ¶ added in v0.1.6
func WithLegacyMaxTokens() Option
WithLegacyMaxTokens sends max_tokens instead of max_completion_tokens on the Chat Completions wire, for an OpenAI-compatible endpoint that cannot read the modern field.
Set it when pointing WithBaseURL at an OpenAI-compatible proxy in front of Ollama, or at any server that ignores max_completion_tokens: that field being ignored is silent, so the model runs unbounded rather than returning an error.
Scoped to the OpenAI-compatible paths, like WithMaxOutputTokens. The native ollama/ client already speaks Ollama's own API and never had the problem; the agentgateway provider sets this for its own known Ollama routes without help.
func WithMaxOutputTokens ¶ added in v0.1.6
WithMaxOutputTokens caps a reply, in tokens, on the OpenAI-compatible paths (openai, azure, openrouter, opencode, xai and agentgateway).
Set it for a backend whose models stop below the default and reject the request rather than clamping it. A per-request MaxOutputTokens still wins over this.
The native Ollama client is not on those paths and does not read this: it caps output with PI_OLLAMA_NUM_PREDICT, which is a variable rather than a per-client option. Reaching Ollama through a gateway is the way to set a cap in code.
func WithPromptCachingDisabled ¶
func WithPromptCachingDisabled() Option
WithPromptCachingDisabled turns off the cache_control breakpoints the Anthropic provider sets by default.
Caching is on by default because it only ever lowers the bill: a request whose prefix is below the minimum cacheable length is simply not cached, with no error and no extra cost. Disable it only when a provider-side behavior makes it undesirable.
func WithSystemCAsDisabled ¶ added in v0.1.6
func WithSystemCAsDisabled() Option
WithSystemCAsDisabled narrows trust to the bundle given to WithCACert alone, so an endpoint is reachable only through that CA and never through a public root.
Only useful together with WithCACert, and only when the endpoint must not be reachable any other way — the opposite of what a TLS-intercepting proxy wants, which is additive trust.
func WithThinkingLevel ¶
WithThinkingLevel sets the reasoning effort for models that support it.
It takes any string-backed type, so a ThinkingLevel constant, a plain string from a flag or config file, and a caller's own named string type all work without a conversion. That matters for more than convenience: typing the parameter as ThinkingLevel alone would have rejected `WithThinkingLevel(level)` where level is a string variable, turning a validating change into a source-breaking one for every caller that reads the level from somewhere else. The empty string is valid and means "leave the provider's default in force".
An unrecognized level is reported by New rather than sent, so a typo fails at construction instead of silently leaving the model on its own default. Use ParseThinkingLevel to find out early, and to normalize the spelling.
func WithTraceSink ¶ added in v0.1.6
func WithTraceSink(fn func(TraceEntry)) Option
WithTraceSink records every request and response this client makes, handing each to fn. It is the way to trace an embedder's traffic without touching process-global state.
The sink belongs to the client, not to the process: two clients built with different sinks trace independently, and installing one here does not displace pi-go's own --trace-http sink or anything else in the host process. That is the reason this option exists instead of a SetSink-style call — the global sink is a single slot that SetSink replaces.
Capture is on whenever a sink is set; there is no separate flag, because a trace with nowhere to go is not a useful state. Note that pi-go's own TraceHTTP setting is the opposite arrangement — it only takes effect once httplog.SetEnabled(true) has been called — so the two are not interchangeable.
Entries arrive synchronously on the request goroutine, so a slow fn delays the request: queue the entry and return rather than writing it inline.
fn receives prompts, completions and tool output in cleartext. Credentials are masked; nothing else is.
func WithWebSearch ¶ added in v0.1.8
func WithWebSearch() Option
WithWebSearch enables the provider's built-in web search: OpenAI's web_search tool on the Responses API, or xAI's server-side tools (which are on by default for xAI).
Opt-in because OpenAI rejects the tool on models that do not support it — gpt-4.1-nano, and gpt-5 at minimal reasoning — so sending it unconditionally would fail ordinary turns on those models.
The search runs server-side and cites what it read. Because it never produces a tool call pi-go's loop executes, the agent's own toolset is unaffected: this does not register a tool, and an embedder that also composes a client-side search tool will have two search tools in the request.
type ProviderNamer ¶
type ProviderNamer interface {
// Provider returns the provider family: "openai", "anthropic", "gemini",
// "mistral", "xai", "ollama", "azure", "opencode" or "agentgateway".
Provider() string
}
ProviderNamer reports which provider family serves a model.
Every Model returned by New and FromConfig implements it. It is declared as a named interface for documentation, but consumers should type-assert the *shape* rather than import this package for the type:
if p, ok := m.(interface{ Provider() string }); ok {
span.SetAttributes(attribute.String("gen_ai.provider.name", p.Provider()))
}
That keeps the dependency direction right. A consumer needing the provider — for a span attribute, or to enable a provider-specific tool such as Gemini's server-side grounding — gets it without importing pimodels, and without keeping a second copy of the model-name-to-provider table. Those copies drift the moment a vendor adds a naming convention.
A model built any other way will not satisfy the assertion, so always handle the not-ok branch.
type ThinkingLevel ¶ added in v0.1.9
type ThinkingLevel string
ThinkingLevel is the reasoning effort to ask a model for.
The vocabulary is pi-go's: the same five levels the TUI's sidebar indicator and `thinkingLevel` in ~/.pi-go/config.json use. A provider maps them onto its own wire vocabulary, and providers differ in how much of the range they preserve. Choosing a level is therefore a request, not a guarantee, and the README carries the per-provider table.
Two limits are worth knowing here, because both make a level look applied when it is not:
- Some providers ignore it entirely. internal/provider.NewLLM does not pass a level to the OpenAI, Azure, Gemini or agentgateway constructors, so on those the model runs at its own default whatever is set here.
- ThinkingNone is not a universal off switch. xAI maps it to its lowest tier (Grok's reasoning models have no off position) and OpenRouter omits the override, because effort "none" is rejected by some providers behind it.
Accepting these levels anyway is deliberate: the alternative is code that stops working when the provider changes, and a level a model cannot express is the model's limitation rather than the option's wrongness.
const ( // ThinkingNone asks the model not to reason, where it can be told. Providers // with no off switch land on their lowest tier instead; see the mapping // notes in internal/provider/xai.go. ThinkingNone ThinkingLevel = "none" // ThinkingLow is the cheapest level that still requests reasoning. ThinkingLow ThinkingLevel = "low" // ThinkingMedium balances effort against latency. ThinkingMedium ThinkingLevel = "medium" // ThinkingHigh is what pi-go's own config defaults to (config.Defaults). ThinkingHigh ThinkingLevel = "high" // ThinkingMax requests the most reasoning the provider offers. Providers // without a top tier above high treat it as high. ThinkingMax ThinkingLevel = "max" )
const ThinkingUnset ThinkingLevel = ""
ThinkingUnset leaves the provider's own default in force. It is the zero ThinkingLevel and the value WithThinkingLevel has when it is not called.
func ParseThinkingLevel ¶ added in v0.1.9
func ParseThinkingLevel(s string) (ThinkingLevel, error)
ParseThinkingLevel converts a level string to a ThinkingLevel, so a caller reading one from a file or a flag gets the same validation the option applies rather than an error on the first request.
The empty string is accepted and returns "", meaning "leave the provider's default in force" — the same meaning it has in WithThinkingLevel.
func (ThinkingLevel) String ¶ added in v0.1.9
func (l ThinkingLevel) String() string
String returns the level as it goes on the wire.
func (ThinkingLevel) Validate ¶ added in v0.1.9
func (l ThinkingLevel) Validate() error
Validate reports whether the level is one a provider can act on.
It rejects an unrecognized level rather than passing it through, because every provider treats an unknown string by silently omitting the parameter — a typo is accepted, the model keeps its own default, and nothing in the response says why the setting did not take effect.
Case and surrounding whitespace are normalized rather than rejected, and the same normalization ParseThinkingLevel applies: a level read from a config file routinely arrives as " High ", and the two functions disagreeing about it would mean validating early proved nothing about passing it later.
type TraceEntry ¶ added in v0.1.6
TraceEntry is one captured half of an HTTP exchange between a provider client and its endpoint: an outgoing request, or the response to it. Requests and responses arrive as separate entries, correlated by Exchange.
It is an alias rather than a copy so the field set cannot drift from the transport that produces it; it is the same type pi-go's own --trace-http writes. Credentials in Headers are already masked, and Body is capped (see TraceMaxBody).