Skip to content

API surface

This page lists every public package, as inventoried on 2026-10-15 against v0.13.3, with a proposed status for v1.0:

  • stable: covered by the v1 compatibility promise;
  • experimental: may change in a minor release after v1;
  • internal: should move out of the public API.

The maintainer decides each status. The work is tracked in the v1.0 milestone, and the criteria are in the design’s §14.

The “Imported by” column counts direct imports in each product’s main branch. A product can also reach a package through coremodels.Open without importing it.

PackageExportsImported byProposedWhy
coremodels (root)Open, Options, Providermast, core-agentstableThe front door: a profile to a provider
llmLLM, Request, Response, ErrEmptyResponsemast, core-agentstableThe contract. Its fields are genai types, by decision (see below)
usageDetail, Attach, FromMetadata, Int64, MetadataKeymast, core-agentstableThe normalized usage record (requirement R3)
callctxside-call, prompt-cache, built-ins and prior-success markerscore-agentstableSmall and context-only. The dialects read it, and core-agent sets it
authConfig, Credential, Kind, Options, TokenSource, QuotaProjecter, ErrNoADC, CloudPlatformScopemast, core-agentstableCredential kinds are part of the profile schema
profileProfile, Model, Capabilities, Resolve, Resolved, Find, Expand, Builtin, BuiltinNames, DecodeJSON, the enum types, ReservedBodyKeys, Hasmast, core-agentstable, with two names to resolveThe schema both products read. ReservedBodyKeys is an exported mutable slice, and Has is a one-line *bool helper. Tier’s meaning waits on Q2
retryPolicy, Default, Record, Snapshot, WithRecord, GaveUp, MarkUnary, WithHeaderTimeout, ErrNoResponse, MetadataKeycore-agentpartly experimentalWhat stays public depends on Q7. Record/Snapshot and the give-up reason are the likely stable core
toolwireEntry, EntryFor, Verify, Summary, Wireneither (tests and dialects)internal candidateThe tool-schema invariant the adapters are held to. No product imports it
pricingCatalog, NewCatalog, Rates, LongContext, ModelRates, Options, Refresh, built-in tables, IntroductoryRates, the file layer (UserFile, ProjectFile, LoadUserFile, SaveUserFile, ProjectFileName)mast, core-agentstable core, file layer to decide32 exported names. The file layer encodes where a product keeps pricing.json, which is close to product policy (house rule #12). Data versioning is #71. Options.Profiles (v0.15.0) carries both declared rates and pricing mode, so Options.Declared plus DeclaredFromProfiles overlaps it; keep one for v1
kvmetricsSampler, New, FromProfile, Window, Between, Reading, Run, Options, ErrNoMetrics, ErrStoppedmastexperimentalOne consumer, introduced in v0.10.0
dialect/openaichatClient, New, Options, ModelOptions, APIError, metadata keysmaststablemast also uses it directly; most callers reach it through Open
dialect/openairespClient, New, Options, ModelOptions, APIError, metadata keysneitherstableReached through Open
dialect/anthropicClient, New, Options, CacheOptions, BuiltinTools, APIError, TTL and version constantsmast, core-agentstableBoth products use cache options directly
dialect/geminiClient, New, Options, BuiltinTools, ContextCache and its hook types, GroundingEvidence, IsTransient, IsBareInvalidArgument, IsBareInvalidArgumentBody, ErrEmptyResponsecore-agentstable, except ContextCache (experimental)The cache hooks were introduced in v0.8.0 and serve one product’s cache design
dialect/gemini/vertexcacheManager, NewManager, CachesClient, Options, Status, Gone, IsBelowCacheMinimumcore-agentexperimentalOne consumer, closely tied to Vertex’s caching API
adkv2 (module)Wrap, FromADK, Request, Response, ADKRequest, ADKResponse, GroundingProjectionmast, core-agentstableThe ADK v2 shim; it exposes ADK types by design

genai and ADK types in exported signatures

Section titled “genai and ADK types in exported signatures”

These signatures tie core-models’ compatibility to genai’s. That coupling is accepted (design D7, decided in #69): a breaking change to one of these types is a core-models major. The modules page has the complete list; the main ones are:

  • llm.Request: []*genai.Content and *genai.GenerateContentConfig.
  • llm.Response: *genai.Content, CitationMetadata, GroundingMetadata, GenerateContentResponseUsageMetadata, LogprobsResult, Transcription and genai.FinishReason.
  • toolwire.EntryFor: *genai.FunctionDeclaration.
  • gemini.GroundingEvidence: *genai.GroundingMetadata.
  • gemini.ContextCacheInitFn: *genai.Content and []*genai.Tool.

adkv2’s ADK v2 types are its purpose. The core module imports no ADK package, per house rule #8.

Tracked in #70.

DialectTypeHow a product classifies it
openaichat, openairesp*APIError, with public fieldsHTTPStatus(), Type, Code
anthropic*APIError, opaque, wrapping the SDK errorHTTPStatus(), MidStream(), errors.As to the SDK error
geminigenai’s own errors, unwrappedgemini.IsTransient, gemini.IsBareInvalidArgument, vertexcache.Gone, vertexcache.IsBelowCacheMinimum

Some errors carry no type:

  • Refusals of unsupported settings or parts are plain errors. A product can only read their text.
  • The sentinels are llm.ErrEmptyResponse, gemini.ErrEmptyResponse (which wraps the first), retry.ErrNoResponse, auth.ErrNoADC, kvmetrics.ErrNoMetrics and kvmetrics.ErrStopped.

Both products classify some provider errors by their text:

  • core-agent’s attach layer matches retry.ErrNoResponse’s message, so that it stays free of provider dependencies.
  • mast’s attach layer matches rate-limit and quota substrings.