@gullabs/any-llm

The default, batteries-included any-llm client package.

"Batteries-included" means concretely this: @gullabs/any-llm bundles @gullabs/core (the engine), @gullabs/google (the Gemini adapter), and @google/genai (the Gemini SDK) as dependencies and re-exports their full public API, so a single pnpm add gets you a working client instead of three separate installs.

Install

pnpm add @gullabs/any-llm

This installs the core engine, Gemini adapter, and @google/genai.

Usage

import {
  createClient,
  composeProviders,
  defaultGeminiRegistry,
  defineCallSite,
  googleProvider,
} from '@gullabs/any-llm'

const client = createClient({
  ...composeProviders([googleProvider()]),
})

const summarize = defineCallSite({
  id: 'summarize',
  provider: 'google',
  model: 'gemini-2.5-flash',
  jsonSchema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      bullets: { type: 'array', items: { type: 'string' } },
    },
    required: ['title', 'bullets'],
  },
  userTemplate: 'Summarize this:\n\n{{text}}',
})

// Auth is required per call — the library never reads environment variables itself.
const result = await client.runStructured(
  summarize,
  { text: documentText },
  { auth: { apiKey: process.env.GEMINI_API_KEY! } },
)

const descriptor = defaultGeminiRegistry.resolve('google', 'gemini-3.5-flash')
if (!descriptor) throw new Error('unknown model')

const parsedConfig = descriptor.configSchema.parse({
  reasoning: { effort: 'medium' },
})

Built-in descriptors own the strict model-config contract: descriptor.configSchema parses persisted or user-supplied config, and descriptor.configJsonSchema is the derived UI/form schema. Use reasoning.effort for Gemini 3 and Gemma built-ins, omit serviceTier for the provider's standard tier, and set flex explicitly when that trade-off is intended. priority remains rejected by the library for now.

Key exports

This package re-exports the full public API of @gullabs/core and @gullabs/google verbatim — createClient, composeProviders, defineCallSite, googleProvider, geminiAdapter, geminiPricingSource, LlmError, and every other named export from both packages. See their READMEs for details:

| Export | What it is | | --------------------------- | ----------------------------------------------------------- | | createClient(config) | Wires ports into a { generate, runStructured } client | | composeProviders(plugins) | Merges ProviderPlugins into ClientConfig fields | | defineCallSite(opts) | Defines a typed, reusable prompt template bound to a model | | googleProvider(opts?) | The Gemini ProviderPlugin factory, from @gullabs/google | | geminiAdapter(opts?) | The Gemini ProviderAdapter, from @gullabs/google | | geminiPricingSource() | Built-in Gemini pricing snapshot, from @gullabs/google | | LlmError | Typed error class — always thrown on call failure | | ANY_LLM_VERSION | This package's version, sourced from package.json |

Use @gullabs/core and @gullabs/google directly only when you want modular dependency control.

AI-agent skill

This package ships an Agent Skill at skills/any-llm/SKILL.md for AI coding tools that support the convention (e.g. Claude Code). Point a compatible assistant at it to get accurate, up-to-date usage guidance for this library instead of relying on its training data.

Learn more

• Monorepo root README — full architecture, auth model, and package overview
• docs/structured-output-validation.md — validating result.output after outputParsed
• docs/multi-runtime.md — web route + Temporal worker integration pattern