pimodels

package
v0.0.78 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 24, 2026 License: MIT Imports: 6 Imported by: 0

README

pimodels

Build LLM clients for the providers pi-go supports, from outside pi-go.

import "github.com/dimetron/pi-go/pimodels"

m, err := pimodels.New(ctx, "gpt-5.6-luna")

m is an ADK model.LLM. Hand it to any ADK agent.

What it does

Resolves a model name to a provider, finds the API key, and returns a client. That is the whole remit — it knows nothing about agents, tools, sessions or skills.

Model name Provider
gpt-* openai
claude-* anthropic
gemini-* gemini
grok-* xai
mistral-*, magistral-* mistral
ollama/<name>, *:cloud ollama
azure/<deployment> azure
anything, with WithBaseURL OpenAI-compatible

Isolation

This package and the agent package meet at ADK's model.LLM, not at each other. Neither imports the other:

m, err := pimodels.New(ctx, "gpt-5.6-luna")       // this package
a, err := piagent.New(ctx, piagent.WithModel(m))  // the agent package

That boundary is enforced by a test, not a convention — isolation_test.go asserts the build graph and fails CI if this package ever reaches into the agent, the tool set, or the CLI. A public package cannot afford for a change to provider handling to become a breaking change to the agent API.

API keys

New reads the key from the provider's environment variable:

Provider Variable
openai OPENAI_API_KEY
anthropic ANTHROPIC_API_KEY
gemini GEMINI_API_KEY
azure AZURE_OPENAI_API_KEY
everything else <PROVIDER>_API_KEY

WithAPIKey overrides it. A local Ollama needs neither.

Use APIKeyEnvVar(provider) to report a missing credential precisely instead of letting the first request fail with a provider-specific auth error.

Options

Option Purpose
WithAPIKey Explicit credential
WithBaseURL Gateway, proxy, or self-hosted endpoint
WithThinkingLevel Reasoning effort where supported
WithHeaders Extra headers for gateway routing or tenancy
WithConnectTimeout Bounds connect only — not the request, which streams
WithCACert Trust a PEM bundle alongside system roots
WithInsecureTLS Disable verification — prefer WithCACert
WithPromptCachingDisabled Turn off Anthropic cache breakpoints
WithAdvisor Advisor model, where supported

Options apply in order, so a later one wins.

Without a model name

FromConfig(ctx, role) builds the model a pi session would use, reading ~/.pi-go/config.json. An empty role means default. This is the only function here that touches pi-go's configuration; New is self-contained.

Inspecting before connecting

info, err := pimodels.Resolve("claude-sonnet-5")
// info.Provider == "anthropic"

pimodels.ContextWindow("gemini-3.7-flash")           // tokens, 0 if unknown
pimodels.ContextWindowFor("azure", "my-deployment")  // provider-aware

Resolve needs no credential and makes no request, so it is safe to run at startup to validate configuration.

Finding the provider from a model

Every model returned by New and FromConfig also reports its provider family, so a consumer never needs its own model-name prefix table:

if p, ok := m.(interface{ Provider() string }); ok {
    span.SetAttributes(attribute.String("gen_ai.provider.name", p.Provider()))
}

Assert the shape, not the named ProviderNamer type — that way the consumer depends on ADK and a structural interface, not on this package. A model built any other way will not satisfy it, so always handle the not-ok branch.

A note on Info.BaseURL

Resolve fills Info.BaseURL whenever an explicit endpoint was given. pi-go's own provider.ResolveWithBaseURL leaves that field empty and only the TUI fills it in afterwards, by hand — so the same call inside pi-go answers less completely than this one does. An embedder has no second place to look, so this package completes it.

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func APIKeyEnvVar

func APIKeyEnvVar(providerName string) string

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

func ContextWindow(modelName string) int64

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

func ContextWindowFor(providerName, modelName string) int64

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

func Resolve(modelName string, opts ...Option) (Info, error)

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

type Model = model.LLM

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

func FromConfig(ctx context.Context, role string, opts ...Option) (Model, error)

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

func New(ctx context.Context, modelName string, opts ...Option) (Model, error)

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
}
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
}

type Option

type Option func(*options)

Option configures New. Options are applied in order, so a later one wins.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets the credential explicitly, overriding the environment.

func WithAdvisor

func WithAdvisor(advisorModel string, maxUses int, caching bool) Option

WithAdvisor enables an advisor model for providers that support it, bounded by maxUses per request (0 = unbounded).

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL points the client at a different endpoint — a gateway, a proxy, or a self-hosted OpenAI-compatible server.

func WithCACert

func WithCACert(path string) Option

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

func WithConnectTimeout(d time.Duration) Option

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

func WithHeaders(h map[string]string) Option

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

func WithThinkingLevel(level string) Option

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL