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, AZURE_OPENAI_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.
Index ¶
- func APIKeyEnvVar(providerName string) string
- func ContextWindow(modelName string) int64
- func ContextWindowFor(providerName, modelName string) int64
- 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 WithPromptCachingDisabled() Option
- func WithThinkingLevel(level string) Option
- type ProviderNamer
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.
Types ¶
type Info ¶
type Info struct {
// Provider is the backend that will serve the model: "openai",
// "anthropic", "gemini", "mistral", "xai", "ollama", "azure", "opencode".
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
// 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:
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 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 WithThinkingLevel ¶
WithThinkingLevel sets the reasoning effort for models that support it ("none", "low", "medium", "high"). Ignored by models that do not.
type ProviderNamer ¶
type ProviderNamer interface {
// Provider returns the provider family: "openai", "anthropic", "gemini",
// "mistral", "xai", "ollama", "azure" or "opencode".
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.