pimodels

package
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 8 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 AZUREOPENAI_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, validated — see below
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
WithWebSearch Provider's built-in web search, where supported
WithAdvisor Advisor model, where supported
WithMaxOutputTokens Cap a reply, in tokens
WithLegacyMaxTokens Send max_tokens — required for Ollama
WithSystemCAsDisabled Trust only the WithCACert bundle
WithTraceSink Capture every HTTP request and response this client makes

Options apply in order, so a later one wins.

Reasoning effort

WithThinkingLevel takes any string-backed type — a ThinkingLevel constant, a plain string from a flag or config file, or your own named string type — and there are five levels:

Constant Value Meaning
ThinkingNone "none" Don't reason, where the model can be told
ThinkingLow "low" Cheapest level that still reasons
ThinkingMedium "medium" Balanced
ThinkingHigh "high" pi-go's own config default
ThinkingMax "max" Most reasoning the provider offers

ThinkingUnset — the empty string, and the zero value — leaves the provider's own default in force.

m, err := pimodels.New(ctx, "claude-opus-4-7", pimodels.WithThinkingLevel(pimodels.ThinkingHigh))

A string variable can be passed straight through, and ParseThinkingLevel is there when you want to find out early — or normalize the spelling:

level, err := pimodels.ParseThinkingLevel(os.Getenv("PI_THINKING"))
if err != nil {
    return err                          // names the accepted set
}
m, err := pimodels.New(ctx, name, pimodels.WithThinkingLevel(level))

An unrecognized level is an error from New, not a silent pass-through. That is deliberate: providers omit a level they do not recognize rather than rejecting it, so an unchecked typo looks like a setting that was applied and had no effect. "xhigh" and "off" are rejected for the same reason — some providers honor those spellings and others drop them, so accepting either would mean one provider quietly ignoring what you asked for.

Which providers act on it

Choosing a level is a request, not a guarantee. Three things can weaken it:

  • Some providers ignore the level entirely. OpenAI, Azure, Gemini and agentgateway never receive it, because their constructors do not take one. The option is still accepted and validated, so the same code works across providers; the model just runs at its own default.
  • Some collapse the range. Anthropic puts every active level on one adaptive config (that form carries no effort field), and Mistral documents only two values (high and none), so it maps every active level to high.
  • ThinkingNone is not a universal off switch. Ollama and Mistral honor it, xAI maps it to its lowest tier because Grok's reasoning models have no off position, and OpenRouter ignores it — effort: "none" is rejected by some of the providers behind it, so the override is omitted and the model's own default stands. Do not read a quiet turn as proof that reasoning was disabled.

Per level, per provider:

Level Ollama Anthropic Mistral xAI OpenRouter
none off off off lowest ignored
low low adaptive high low low
medium medium adaptive high medium medium
high high adaptive high high high
max max adaptive high xhigh max

Ollama, xAI and OpenRouter preserve the widest range; Anthropic and Mistral carry the least.

Token limits on Ollama-backed endpoints

Both token options below apply to the OpenAI-compatible paths — openai, azure, openrouter, opencode, xai and agentgateway — and are read by the Chat Completions request builder.

Point an explicit endpoint at a gateway or proxy in front of Ollama, which is where these matter:

m, err := pimodels.New(ctx, "llama3",
    pimodels.WithBaseURL("http://127.0.0.1:4000/v1"),
    pimodels.WithLegacyMaxTokens(),      // send max_tokens, not max_completion_tokens
    pimodels.WithMaxOutputTokens(4096),  // cap the reply
)

WithLegacyMaxTokens is not a preference. An endpoint that understands only max_tokens ignores max_completion_tokens without an error, so the model runs unbounded instead of being rejected. The agentgateway provider sets this itself for its known Ollama routes; set it when naming the endpoint yourself.

WithMaxOutputTokens is for a backend whose models stop below the default and reject the request rather than clamping it.

The native ollama/ client is different

An ollama/<name> model name selects pi-go's native Ollama client, which speaks Ollama's own API rather than the OpenAI wire. Neither option above affects it — there is no max_tokens field to choose and nothing to cap in the request body. Its output cap is the PI_OLLAMA_NUM_PREDICT environment variable, which defaults to 16384 tokens; a value <= 0 removes the cap.

To set a cap for Ollama from code rather than the environment, reach it through a gateway instead:

m, err := pimodels.New(ctx, "llama3",
    pimodels.WithBaseURL("http://127.0.0.1:4000/v1"),
    pimodels.WithMaxOutputTokens(4096),
)

Trusting only one CA

WithCACert is additive by default: the bundle is trusted alongside the system roots, which is what a TLS-intercepting proxy wants. When an endpoint must instead be reachable through that CA and nothing else:

m, err := pimodels.New(ctx, "claude-sonnet-5",
    pimodels.WithCACert("/etc/ssl/corp.pem"),
    pimodels.WithSystemCAsDisabled(),
)

This is the opposite of the proxy case. Use it only when a public root being able to reach the endpoint would itself be the problem.

Tracing the traffic

WithTraceSink hands you each request and response this client sends:

m, err := pimodels.New(ctx, "claude-sonnet-5",
    pimodels.WithTraceSink(func(e pimodels.TraceEntry) {
        audit.Log(e.Exchange, e.Method, e.URL, e.Status, e.Body)
    }))

TraceEntry is an alias for the type pi-go's own --trace-http writes, so request and response arrive as separate entries tied together by Exchange — a streaming body is not complete when its headers are, so one combined record could not be emitted until the stream drained.

The sink belongs to the client, not the process:

  • Two clients with different sinks trace independently.
  • Installing one does not displace pi-go's --trace-http sink, or anything else in the host process that is tracing.

That last point is why this is an option rather than a SetSink-style call: the global sink is a single slot that SetSink replaces, so a public library claiming it would clobber its host.

Capture is on as soon as a sink is set — there is no separate flag, because a trace with nowhere to go is not a useful state. Note this is the opposite arrangement from pi-go's own TraceHTTP setting, which captures nothing until httplog.SetEnabled(true) and a global sink are both in place. Do not assume the two behave alike.

Two things to know before wiring one up:

  • Entries arrive synchronously on the request goroutine, so a slow sink delays the request. Queue and return rather than writing inline.
  • Bodies are cleartext. Credentials are masked (Bearer s***(32 bytes)), but prompts, completions and tool output are not. That is the point of a trace and also the reason it is opt-in.

TraceMaxBody() reports the byte cap applied before an entry reaches the sink; a body cut at the cap sets BodyTruncated.

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"

m, err := pimodels.NewFromInfo(ctx, info) // build exactly that resolved pair

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. If you want to build the inspected model later, pass the returned Info to NewFromInfo; Info.Model is the provider's stripped model/deployment name, so feeding it back to New reparses it as a new user-facing model name.

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

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.

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

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
}

func NewFromInfo added in v0.0.84

func NewFromInfo(ctx context.Context, info Info, opts ...Option) (Model, error)

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

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

func WithMaxOutputTokens(n int64) Option

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

func WithThinkingLevel[T ~string](level T) Option

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

type TraceEntry = httplog.Entry

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).

Jump to

Keyboard shortcuts

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