agentfootprint 6.43.0 → 6.45.0

package/dist/esm/adapters/llm/BrowserOpenAIProvider.d.ts

@@ -0,0 +1,95 @@
+/**
+ * BrowserOpenAIProvider — fetch-based OpenAI adapter for browsers.
+ *
+ * Pattern: Adapter (GoF). Zero peer dependencies — uses global `fetch`.
+ * Role:    Outer ring. Same `LLMProvider` contract as `OpenAIProvider`
+ *          but skips the `openai` SDK. For prototypes / playgrounds.
+ *          Production apps should proxy through a backend.
+ * Emits:   N/A.
+ *
+ * Also works with OpenAI-compatible endpoints (Ollama, Together, vLLM)
+ * via `apiUrl`.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT supported.
+ * • CORS depends on the endpoint — OpenAI requires the user-supplied
+ *   key in the Authorization header, which they'll do explicitly.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+export interface BrowserOpenAIProviderOptions {
+    /** API key. REQUIRED. */
+    readonly apiKey: string;
+    /** Default model when `LLMRequest.model` is `'openai'`. */
+    readonly defaultModel?: string;
+    /** Default max tokens. */
+    readonly defaultMaxTokens?: number;
+    /** Override the API URL (Ollama, Together, vLLM, OpenAI proxies). */
+    readonly apiUrl?: string;
+    /** Optional `Organization` header. */
+    readonly organization?: string;
+    /** Auth header scheme. `'bearer'` (default) → `Authorization: Bearer <key>`;
+     *  `'api-key'` → the `api-key` header (Azure OpenAI). */
+    readonly authScheme?: 'bearer' | 'api-key';
+    /** Treat the target as a **reasoning model** (o-series): omit `temperature` and send
+     *  the `developer` role. Standard o-series ids are auto-detected; set for arbitrary
+     *  Azure deployment names. */
+    readonly reasoning?: boolean;
+    /** @internal Custom fetch implementation for tests. */
+    readonly _fetch?: typeof fetch;
+}
+export declare function browserOpenai(options: BrowserOpenAIProviderOptions): LLMProvider;
+export declare class BrowserOpenAIProvider implements LLMProvider {
+    readonly name = "browser-openai";
+    private readonly inner;
+    constructor(options: BrowserOpenAIProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export interface BrowserAzureOpenAIProviderOptions {
+    /** Resource endpoint, e.g. `https://my-co.openai.azure.com` (or a same-origin
+     *  proxy path like `/azure` to sidestep CORS in dev). REQUIRED. */
+    readonly endpoint: string;
+    /** API key (Azure `api-key`). REQUIRED. */
+    readonly apiKey: string;
+    /** Azure API version, e.g. `2024-12-01-preview`. REQUIRED. */
+    readonly apiVersion: string;
+    /** The DEPLOYMENT name (Azure's "model"), e.g. `gpt-4o-128k`. REQUIRED. */
+    readonly deployment: string;
+    /** Default max tokens. */
+    readonly defaultMaxTokens?: number;
+    /** Set when the Azure deployment is a **reasoning model** (o1/o3/o4-mini) — omits
+     *  `temperature` and sends the `developer` role. */
+    readonly reasoning?: boolean;
+    /** @internal Custom fetch implementation for tests. */
+    readonly _fetch?: typeof fetch;
+}
+/**
+ * Fetch-based **Azure OpenAI** provider for the browser/edge — no SDK, no Node.
+ *
+ * The browser can't use the Node `azureOpenai()` (it needs the `openai` SDK), so
+ * use this in a browser "bring your own (company) key" flow. Builds the
+ * deployment-scoped Azure URL + `api-key` header + `api-version`, and reuses all
+ * of `browserOpenai()`'s body/streaming/tool logic. The request `model` is the
+ * deployment; `'azure'` resolves to the configured `deployment`.
+ *
+ * **CORS:** an `*.openai.azure.com` resource may not allow direct browser calls;
+ * if blocked, point `endpoint` at a same-origin proxy (e.g. a Vite `/azure`
+ * proxy) or a backend. Same trade-off as `browserOpenai`.
+ *
+ * @example
+ *   import { browserAzureOpenai } from 'agentfootprint';
+ *   const provider = browserAzureOpenai({
+ *     endpoint: 'https://my-co.openai.azure.com',
+ *     apiKey: userKey, apiVersion: '2024-12-01-preview', deployment: 'gpt-4o-128k',
+ *   });
+ *   // Agent.create({ provider, model: 'azure' })
+ */
+export declare function browserAzureOpenai(options: BrowserAzureOpenAIProviderOptions): LLMProvider;
+export declare class BrowserAzureOpenAIProvider implements LLMProvider {
+    readonly name = "browser-azure-openai";
+    private readonly inner;
+    constructor(options: BrowserAzureOpenAIProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}

package/dist/esm/adapters/llm/MockProvider.d.ts

@@ -0,0 +1,153 @@
+/**
+ * MockProvider — deterministic LLMProvider for tests + examples.
+ *
+ * Pattern: Adapter (GoF, Design Patterns ch. 4).
+ * Role:    Ports-and-Adapters outer ring (Cockburn, 2005) — implements the
+ *          LLMProvider port without calling out to a real LLM service.
+ * Emits:   N/A (adapters don't emit; recorders observe them).
+ *
+ * Two modes, same provider:
+ *   • DEFAULT (no latency options)  — instant `complete()`, no streaming.
+ *     Use in unit tests; behavior unchanged from earlier revisions.
+ *   • REALISTIC (`thinkingMs` set)  — randomised "thinking" latency before
+ *     the response, plus a `stream()` implementation that emits the
+ *     content word-by-word with `chunkDelayMs` between chunks. Lets
+ *     consumers SEE the run unfold (pauses, streaming tokens, tool
+ *     dispatch) instead of having every step finish in microseconds.
+ *
+ * Realistic mode is the right default for the playground / Lens demos:
+ * a real OpenAI / Anthropic call takes 3–8 s, so the UX you build for
+ * that timing is what matters. Use `MockProvider.realistic()` for the
+ * common 3–8 s thinking + 30–80 ms per word streaming preset.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+/** Either a fixed value (in ms) or a random `[min, max]` range (inclusive). */
+export type LatencyMs = number | readonly [number, number];
+/**
+ * One scripted reply consumed in order from `MockProviderOptions.replies`.
+ * String → plain text content; Partial<LLMResponse> → can include
+ * `toolCalls`, `usage`, `stopReason` for tool-using ReAct loops.
+ */
+export type MockReply = string | Partial<LLMResponse>;
+export interface MockProviderOptions {
+    readonly name?: string;
+    /** Fixed response content. Overrides `respond` when set. */
+    readonly reply?: string;
+    /**
+     * Scripted replies for multi-turn / tool-using agents. Each entry
+     * is consumed in order — iteration 1 reads `replies[0]`, iteration
+     * 2 reads `replies[1]`, and so on. Use Partial<LLMResponse> to
+     * inject `toolCalls`:
+     *
+     * ```ts
+     * mock({
+     *   replies: [
+     *     { toolCalls: [{ id: '1', name: 'lookup', args: { id: 42 } }] },
+     *     { content: 'Found it: refunds take 3 business days.' },
+     *   ],
+     * });
+     * ```
+     *
+     * **Exhaustion semantics:** if the agent calls the LLM more times
+     * than there are replies, `complete()` / `stream()` throw a clear
+     * error. This makes mock-script bugs loud, not silent. Tune the
+     * agent's `maxIterations` to bound the call count.
+     *
+     * Takes precedence over `reply` and `respond` when set.
+     */
+    readonly replies?: readonly MockReply[];
+    /**
+     * Build the response from the request. Returns either a plain
+     * string (renders as content with no tool calls) or a partial
+     * `LLMResponse` so consumers can simulate tool calls + multi-turn
+     * loops without needing a separate `scripted()` helper.
+     *
+     * Default: echoes the last user message.
+     */
+    readonly respond?: (req: LLMRequest) => string | Partial<LLMResponse>;
+    /**
+     * Simulated wall-clock delay per request (ms).
+     * Pass a single number for a fixed delay or a `[min, max]` tuple for
+     * a uniformly random delay (e.g. `[3000, 8000]` for "real LLM"
+     * thinking time). Default 0 (instant).
+     *
+     * Aliased via `delayMs` for backward compatibility.
+     */
+    readonly thinkingMs?: LatencyMs;
+    /** Alias for `thinkingMs`. Kept for back-compat with prior revisions. */
+    readonly delayMs?: LatencyMs;
+    /**
+     * For `stream()`: delay between successive chunks (ms). Pass a
+     * single number for a fixed delay or a `[min, max]` tuple for a
+     * uniformly random delay per chunk (e.g. `[30, 80]` for typing-like
+     * cadence). Default 30ms.
+     *
+     * Has no effect on `complete()`.
+     */
+    readonly chunkDelayMs?: LatencyMs;
+    /** Fixed stop reason to return. Default 'stop'. */
+    readonly stopReason?: string;
+    /** Override usage counts returned. Default: chars/4 heuristic. */
+    readonly usage?: Readonly<{
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    }>;
+}
+export declare class MockProvider implements LLMProvider {
+    readonly name: string;
+    private readonly reply?;
+    private readonly replies?;
+    private repliesCursor;
+    private readonly respond;
+    private readonly thinkingMs;
+    private readonly chunkDelayMs;
+    private readonly stopReason;
+    private readonly usageOverride;
+    constructor(options?: MockProviderOptions);
+    /**
+     * Reset the scripted-replies cursor. Useful when reusing one
+     * `MockProvider` instance across multiple test scenarios — each
+     * scenario can `provider.resetReplies()` to start from `replies[0]`
+     * again. No-op when `replies` was not supplied.
+     */
+    resetReplies(): void;
+    /**
+     * Convenience factory for the playground / Lens demo defaults: a
+     * real-feel mock with 3–8 s of "thinking" before the response and
+     * 30–80 ms per streamed word. Lets users observe pause/resume,
+     * streaming, and tool dispatch happening live without hitting a
+     * paid API.
+     */
+    static realistic(options?: MockProviderOptions): MockProvider;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Streaming mode — emits the response content word-by-word so
+     * consumers (Lens commentary, chat UIs) can render tokens as they
+     * arrive. Tool calls land all at once on the final chunk because
+     * that is how real providers (OpenAI, Anthropic) deliver them too.
+     */
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+    private buildResponse;
+    /**
+     * Resolve the next reply source for one `complete()` / `stream()` call.
+     * Priority: `replies` (scripted, throws on exhaustion) → `reply` (single
+     * fixed string) → `respond` (callback default). Replies are consumed
+     * in order; the cursor is per-instance, not per-request.
+     */
+    private consumeNextReply;
+}
+/**
+ * Lowercase factory for `MockProvider` — matches the v1 `mock()` import
+ * shape so docs and quick-starts stay copy-pasteable. Equivalent to
+ * `new MockProvider(options)`.
+ *
+ * @example
+ *   import { Agent, mock, defineTool } from 'agentfootprint';
+ *
+ *   const agent = Agent.create({ provider: mock({ reply: 'hello' }) })
+ *     .tool(defineTool({ name: 'echo', ... }))
+ *     .build();
+ */
+export declare function mock(options?: MockProviderOptions): MockProvider;

package/dist/esm/adapters/llm/OpenAIProvider.d.ts

@@ -0,0 +1,220 @@
+/**
+ * OpenAIProvider — wraps the `openai` SDK as an `LLMProvider`.
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from
+ *          OpenAI's Chat Completions API. Knows nothing about agents,
+ *          recorders, or compositions.
+ * Emits:   N/A.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT supported  (`LLMMessage.content` is
+ *   `string`). May extend in a future release.
+ * • `responseFormat` (JSON-mode) NOT exposed  — pass schema
+ *   instructions via `systemPrompt` for now.
+ *
+ * The `baseURL` option enables OpenAI-compatible APIs (Ollama, Together,
+ * Groq, vLLM, LM Studio) without a separate adapter — see the `ollama()`
+ * convenience factory below.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+interface OpenAIClient {
+    chat: {
+        completions: {
+            create(params: OpenAICreateParams): Promise<OpenAIChatCompletion> | AsyncIterable<OpenAIStreamChunk>;
+        };
+    };
+}
+interface OpenAICreateParams {
+    model: string;
+    messages: OpenAIMessage[];
+    tools?: OpenAITool[];
+    /** Legacy token cap — DEPRECATED by OpenAI and REJECTED by o-series reasoning
+     *  models. Kept only for custom OpenAI-compatible endpoints (Ollama/vLLM/…). */
+    max_tokens?: number;
+    /** Current token cap — accepted by all OpenAI/Azure chat models incl. o-series. */
+    max_completion_tokens?: number;
+    temperature?: number;
+    stop?: string[];
+    stream?: boolean;
+    /** Ask OpenAI/Azure to emit a final usage chunk while streaming. */
+    stream_options?: {
+        include_usage: boolean;
+    };
+}
+interface OpenAIMessage {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+}
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface OpenAIChatCompletion {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: 'assistant';
+            content: string | null;
+            tool_calls?: OpenAIToolCall[];
+        };
+        finish_reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | string;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+interface OpenAIStreamChunk {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                type?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+export interface OpenAIProviderOptions {
+    /** API key. Defaults to `OPENAI_API_KEY` env var. */
+    readonly apiKey?: string;
+    /** Base URL — set for OpenAI-compatible APIs (Ollama, Together, vLLM). */
+    readonly baseURL?: string;
+    /**
+     * Default model used when `LLMRequest.model` is `'openai'` (the
+     * shorthand). Full model ids pass through unchanged.
+     */
+    readonly defaultModel?: string;
+    /** Default max tokens when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /**
+     * Treat the target as a **reasoning model** (o-series: o1 / o3 / o4-mini, or an
+     * Azure reasoning deployment). Reasoning models reject `max_tokens` and an explicit
+     * `temperature`, and use the `developer` role in place of `system`. Standard o-series
+     * model ids are auto-detected; set this explicitly for Azure deployments whose name
+     * does not reveal the underlying model.
+     */
+    readonly reasoning?: boolean;
+    /** @internal Pre-built client for testing. Skips SDK import. */
+    readonly _client?: OpenAIClient;
+}
+/**
+ * Build an `LLMProvider` backed by OpenAI's Chat Completions API.
+ *
+ * @example
+ *   import { Agent } from 'agentfootprint';
+ *   import { openai } from 'agentfootprint/llm-providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: openai({ defaultModel: 'gpt-4o' }),
+ *     model: 'openai',
+ *   })
+ *     .tool(searchTool)
+ *     .build();
+ */
+export declare function openai(options?: OpenAIProviderOptions): LLMProvider;
+/**
+ * Class form for consumers who prefer `new OpenAIProvider(...)`.
+ */
+export declare class OpenAIProvider implements LLMProvider {
+    readonly name = "openai";
+    private readonly inner;
+    constructor(options?: OpenAIProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export interface AzureOpenAIProviderOptions {
+    /** Resource endpoint, e.g. `https://my-co.openai.azure.com`. Env fallbacks:
+     *  `AZURE_OPENAI_ENDPOINT`, then `OPENAI_BASE_URL`. */
+    readonly endpoint?: string;
+    /** API key. Env fallbacks: `AZURE_OPENAI_API_KEY`, then `OPENAI_API_KEY`. */
+    readonly apiKey?: string;
+    /** Azure API version, e.g. `2024-12-01-preview`. Env fallback:
+     *  `AZURE_OPENAI_API_VERSION`. Required. */
+    readonly apiVersion?: string;
+    /** The DEPLOYMENT name (Azure's "model"), e.g. `gpt-4o-128k`. Env fallbacks:
+     *  `AZURE_OPENAI_DEPLOYMENT`, then `MODEL_NAME`. Required. */
+    readonly deployment?: string;
+    /** Default max tokens when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /**
+     * Set when the Azure DEPLOYMENT is a **reasoning model** (o1/o3/o4-mini). Azure
+     * deployment names are arbitrary, so this cannot be auto-detected — declare it to
+     * omit `temperature` and send the `developer` role. (`max_completion_tokens` is used
+     * for all Azure deployments regardless.)
+     */
+    readonly reasoning?: boolean;
+    /** @internal Pre-built client for testing. Skips SDK import. */
+    readonly _client?: OpenAIClient;
+}
+/**
+ * Build an `LLMProvider` for **Azure OpenAI**.
+ *
+ * Azure is NOT a drop-in OpenAI-compatible URL — it uses a deployment-scoped
+ * path, `api-key` header auth, and an `api-version` query param. This wraps the
+ * `openai` SDK's `AzureOpenAI` client (which handles all that) and reuses the
+ * exact same completion/streaming/tool-call logic as `openai()`.
+ *
+ * The request's `model` is the Azure **deployment** name. Pass a deployment id
+ * to target it; the shorthands `'azure'` / `'azure-openai'` resolve to the
+ * configured default `deployment`.
+ *
+ * @example
+ *   import { azureOpenai } from 'agentfootprint/llm-providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: azureOpenai({
+ *       endpoint: process.env.OPENAI_BASE_URL,            // *.openai.azure.com
+ *       apiKey: process.env.AZURE_OPENAI_API_KEY,
+ *       apiVersion: process.env.AZURE_OPENAI_API_VERSION, // 2024-12-01-preview
+ *       deployment: process.env.MODEL_NAME,               // gpt-4o-128k
+ *     }),
+ *     model: 'azure',
+ *   }).build();
+ */
+export declare function azureOpenai(options?: AzureOpenAIProviderOptions): LLMProvider;
+/**
+ * Convenience factory for Ollama (OpenAI-compatible endpoint).
+ *
+ * @example
+ *   import { ollama } from 'agentfootprint/llm-providers';
+ *
+ *   const provider = ollama({ defaultModel: 'llama3.2' });
+ *   // Talks to http://localhost:11434/v1 by default.
+ */
+export declare function ollama(options?: OpenAIProviderOptions & {
+    readonly host?: string;
+}): LLMProvider;
+export {};

package/dist/esm/adapters/llm/createProvider.d.ts

@@ -0,0 +1,85 @@
+/**
+ * createProvider — by-name factory for any built-in LLMProvider.
+ *
+ * Pattern: Abstract Factory (GoF) over the concrete provider factories.
+ * Role:    Convenience entry point. Useful for config-driven setups
+ *          where the provider is chosen at runtime (env var, feature
+ *          flag, tenant preference).
+ * Emits:   N/A.
+ *
+ * @example
+ *   const kind = (process.env.LLM_PROVIDER ?? 'anthropic') as ProviderKind;
+ *   const provider = createProvider({
+ *     kind,
+ *     apiKey: process.env.LLM_API_KEY,
+ *     defaultModel: process.env.LLM_MODEL,
+ *   } as CreateProviderOptions);
+ *
+ * For provider-specific options (Bedrock region, Ollama host, Browser
+ * apiUrl, etc.) construct the underlying factory directly — this
+ * helper deliberately exposes only the common subset.
+ */
+import type { LLMProvider } from '../types.js';
+import { type MockProviderOptions } from './MockProvider.js';
+import { type AnthropicProviderOptions } from './AnthropicProvider.js';
+import { type OpenAIProviderOptions } from './OpenAIProvider.js';
+import { type BedrockProviderOptions } from './BedrockProvider.js';
+import { type BrowserAnthropicProviderOptions } from './BrowserAnthropicProvider.js';
+import { type BrowserOpenAIProviderOptions } from './BrowserOpenAIProvider.js';
+/** Built-in provider kinds. Custom providers don't go through this factory. */
+export type ProviderKind = 'mock' | 'anthropic' | 'openai' | 'ollama' | 'bedrock' | 'browser-anthropic' | 'browser-openai';
+/**
+ * Common subset of options accepted across all built-in providers.
+ * Provider-specific keys (region for Bedrock, host for Ollama,
+ * organization for OpenAI, apiUrl for browser) are passed through
+ * verbatim — TypeScript narrows by `kind`.
+ */
+export type CreateProviderOptions = ({
+    readonly kind: 'mock';
+} & MockProviderOptions) | ({
+    readonly kind: 'anthropic';
+} & AnthropicProviderOptions) | ({
+    readonly kind: 'openai';
+} & OpenAIProviderOptions) | ({
+    readonly kind: 'ollama';
+} & OpenAIProviderOptions & {
+    readonly host?: string;
+}) | ({
+    readonly kind: 'bedrock';
+} & BedrockProviderOptions) | ({
+    readonly kind: 'browser-anthropic';
+} & BrowserAnthropicProviderOptions) | ({
+    readonly kind: 'browser-openai';
+} & BrowserOpenAIProviderOptions);
+/**
+ * Build any built-in LLMProvider from a tagged options object.
+ */
+export declare function createProvider(options: CreateProviderOptions): LLMProvider;
+/** What `providerFromEnv()` resolved: the provider + the `model` to pass to
+ *  `Agent.create({ provider, model })`, and which `kind` was detected. */
+export interface ProviderFromEnv {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly kind: 'azure-openai' | 'anthropic' | 'openai' | 'mock';
+}
+/**
+ * Resolve an `LLMProvider` from environment variables — drop your company's
+ * values in `.env` and the right provider is configured automatically, with no
+ * code branching. (Node only — reads `process.env`; the vendor SDK is lazy-loaded
+ * only for the detected provider.)
+ *
+ * Detection order (first match wins):
+ *   1. **Azure OpenAI** — `AZURE_OPENAI_API_KEY` + (`AZURE_OPENAI_ENDPOINT` |
+ *      `OPENAI_BASE_URL`) [+ `AZURE_OPENAI_API_VERSION`, `AZURE_OPENAI_DEPLOYMENT`|`MODEL_NAME`]
+ *   2. **Anthropic** — `ANTHROPIC_API_KEY`
+ *   3. **OpenAI** — `OPENAI_API_KEY`
+ * Otherwise throws (or returns the mock when `{ fallbackToMock: true }`).
+ *
+ * @example
+ *   import { providerFromEnv } from 'agentfootprint';
+ *   const { provider, model, kind } = providerFromEnv({ fallbackToMock: true });
+ *   const agent = Agent.create({ provider, model }).build();
+ */
+export declare function providerFromEnv(opts?: {
+    readonly fallbackToMock?: boolean;
+}): ProviderFromEnv;