@standardagents/anthropic 0.0.0-stub.ffffff → 0.17.0

package/LICENSE.txt

@@ -0,0 +1,48 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 FormKit Inc. All Rights Reserved.
+
+UNLICENSED - DO NOT USE
+
+This software and associated documentation files (the "Software") are the sole
+and exclusive property of FormKit Inc. ("FormKit").
+
+USE RESTRICTIONS
+
+The Software is UNLICENSED and proprietary. NO PERMISSION is granted to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, or to permit persons to whom the Software is furnished to do so,
+under any circumstances, without prior written authorization from FormKit Inc.
+
+UNAUTHORIZED USE PROHIBITED
+
+Any use of this Software without a valid, written license agreement signed by
+authorized officers of FormKit Inc. is strictly prohibited and constitutes
+unauthorized use and infringement of FormKit's intellectual property rights.
+
+LICENSING INQUIRIES
+
+Organizations interested in licensing this Software should contact:
+enterprise@formkit.com
+
+A written license agreement must be executed before any use of this Software
+is authorized.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+FORMKIT INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with the laws
+of the jurisdiction in which FormKit Inc. is incorporated, without regard to
+its conflict of law provisions.
+
+FormKit Inc.
+https://formkit.com
+enterprise@formkit.com

package/README.md

@@ -1,3 +1,35 @@
 # @standardagents/anthropic
 
-Placeholder release to reserve the package name. Real versions are published by the Standard Agents release automation.
+Anthropic (Claude) provider for [Standard Agents](https://standardagentbuilder.com). Wraps the official `@anthropic-ai/sdk` and translates between the Standard Agents provider spec and the Anthropic Messages API.
+
+## Features
+
+- Streaming and non-streaming generation through the Messages API
+- Tool use with parallel tool results and image tool outputs
+- Extended thinking across model generations: adaptive thinking + effort on Claude 4.6+, token budgets on Claude 4.0-4.5, with thinking blocks (text + signature) round-tripped exactly on multi-turn conversations
+- Anthropic server-side `web_search` tool exposed as a provider tool
+- Vision (images), PDF and plain-text document inputs
+- Structured outputs via `output_config.format` for JSON schema response formats
+- Prompt caching opt-in for the system prompt (`providerOptions.cacheSystemPrompt`)
+- Live model listing and per-model capability detection via the Anthropic Models API
+- Usage normalization (prompt/completion/cached/reasoning tokens) plus exact per-request cost derived from raw billing buckets (cache writes at 1.25x/2x, cache reads at 0.1x) for documented Claude models
+
+## Usage
+
+```typescript
+import { defineModel } from '@standardagents/spec';
+import { anthropic } from '@standardagents/anthropic';
+
+export default defineModel({
+  name: 'claude-opus',
+  provider: anthropic,
+  model: 'claude-opus-4-8',
+  inputPrice: 5,
+  outputPrice: 25,
+  providerOptions: {
+    cacheSystemPrompt: true,
+  },
+});
+```
+
+Set `ANTHROPIC_API_KEY` in your environment.

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import { LLMProviderInterface, ProviderFactoryConfig, ModelCapabilities, ToolDefinition, ToolArgs, ToolTenvs, ProviderModelInfo, ProviderRequest, ProviderResponse, ProviderStreamChunk, InspectedRequest, ProviderFactoryWithOptions } from '@standardagents/spec';
+import { z } from 'zod';
+import Anthropic from '@anthropic-ai/sdk';
+
+/**
+ * Anthropic provider options schema.
+ *
+ * Defines typed providerOptions for Anthropic (Claude) models, providing
+ * TypeScript autocompletion and runtime validation.
+ *
+ * @see https://platform.claude.com/docs/en/api/messages
+ * @module
+ */
+
+/**
+ * Anthropic provider options schema.
+ *
+ * These options are passed directly to the Anthropic Messages API and control
+ * various aspects of request handling and generation.
+ *
+ * @example
+ * ```typescript
+ * providerOptions: {
+ *   service_tier: 'auto',
+ *   metadata: { user_id: 'user-123' },
+ *   cacheSystemPrompt: true,
+ * }
+ * ```
+ */
+declare const anthropicProviderOptions: z.ZodObject<{
+    service_tier: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        standard_only: "standard_only";
+    }>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        user_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    cacheSystemPrompt: z.ZodOptional<z.ZodBoolean>;
+    thinking: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+/**
+ * TypeScript type for Anthropic provider options.
+ * Inferred from the Zod schema for type-safe usage.
+ */
+type AnthropicProviderOptions = z.infer<typeof anthropicProviderOptions>;
+
+/**
+ * Known Anthropic model pricing for request cost calculation.
+ *
+ * The Anthropic Messages API reports token usage (including cache buckets)
+ * but no dollar cost, and the Models API exposes no pricing data — so cost
+ * is derived here from the raw usage buckets and a maintained price table.
+ * This is more accurate than a flat promptTokens * inputPrice calculation
+ * because Anthropic bills the prompt in three differently-priced buckets:
+ *
+ * - uncached input tokens: base input rate
+ * - cache writes: 1.25x input (5-minute TTL) or 2x input (1-hour TTL)
+ * - cache reads: 0.1x input
+ *
+ * Thinking tokens are billed as ordinary output tokens (already included in
+ * output_tokens), so no separate reasoning rate applies.
+ */
+
+type AnthropicUsage = Anthropic.Messages.Usage;
+interface AnthropicModelPricing {
+    /** USD per million input tokens */
+    inputPerMillion: number;
+    /** USD per million output tokens (includes thinking tokens) */
+    outputPerMillion: number;
+}
+/**
+ * Look up pricing for a model ID via longest-prefix match.
+ * Returns null for unknown models so callers fall back to model-defined
+ * inputPrice/outputPrice rather than guessing.
+ */
+declare function getAnthropicModelPricing(modelId: string | null | undefined): AnthropicModelPricing | null;
+/**
+ * Token buckets needed for exact cost calculation. Mirrors the relevant
+ * subset of the API's usage object so stream state can reuse this shape.
+ */
+interface AnthropicUsageBuckets {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+}
+/**
+ * Extract billing buckets from an API usage object. When the per-TTL cache
+ * creation breakdown is absent, all cache writes are assumed 5-minute TTL
+ * (the API default and by far the most common case).
+ */
+declare function extractUsageBuckets(usage: AnthropicUsage): AnthropicUsageBuckets;
+/**
+ * Calculate the exact USD cost of a request from its raw usage buckets.
+ * Returns undefined when the model has no known pricing, so the execution
+ * engine can fall back to model-configured prices.
+ */
+declare function calculateAnthropicUsageCost(modelId: string | null | undefined, buckets: AnthropicUsageBuckets): number | undefined;
+
+/**
+ * Anthropic provider implementation for Standard Agents
+ *
+ * Uses the Messages API for all requests via the official @anthropic-ai/sdk.
+ * Supports the full Claude family: claude-fable-5, claude-opus-4-x,
+ * claude-sonnet-4-x, claude-haiku-4-5, claude-3-x, etc.
+ */
+declare class AnthropicProvider implements LLMProviderInterface {
+    readonly name = "anthropic";
+    readonly specificationVersion: "1";
+    private client;
+    private config;
+    /** Cache for models list to avoid repeated API calls */
+    private static modelsCache;
+    private static modelsCacheTime;
+    private static readonly CACHE_TTL;
+    constructor(config: ProviderFactoryConfig);
+    private getClient;
+    supportsModel(modelId: string): boolean;
+    /**
+     * Get the icon for this provider as a data URI.
+     * Always returns the Anthropic icon since all models are from Anthropic.
+     */
+    getIcon(_modelId?: string): string;
+    /**
+     * Capability mappings for Anthropic models, keyed by model ID prefix.
+     * Used as a fallback when the live Models API is unavailable; the API's
+     * capability listing takes precedence when reachable.
+     */
+    private static readonly MODEL_CAPABILITIES;
+    /**
+     * Look up static capabilities for a model by exact then prefix match.
+     */
+    private static lookupStaticCapabilities;
+    /**
+     * Map a live Models API capability listing to Standard Agents capabilities.
+     */
+    private static mapLiveCapabilities;
+    /**
+     * Get capabilities for a specific model.
+     * Prefers the live Models API (which reports per-model capability flags)
+     * and falls back to the static prefix table when the API is unreachable.
+     */
+    getModelCapabilities(modelId: string): Promise<ModelCapabilities | null>;
+    /**
+     * Provider-embedded tools using defineTool().
+     * These are Anthropic's server-side tools that execute on Anthropic's
+     * servers. The execute function is a no-op since execution is handled by
+     * the provider; results surface as providerTools entries on the response.
+     */
+    private static readonly TOOLS;
+    /**
+     * Get tools embedded in this provider.
+     * Anthropic's web_search server tool is available on all current models.
+     *
+     * @param modelId - Optional filter to get tools available for a specific model
+     * @returns Record of tool name to tool definition
+     */
+    getTools(_modelId?: string): Record<string, ToolDefinition<any, ToolArgs | null, ToolTenvs | null>>;
+    /**
+     * Fetch models from the Anthropic Models API with caching.
+     */
+    private fetchModelsWithCache;
+    /**
+     * Map Anthropic model info to ProviderModelInfo.
+     */
+    private mapToProviderModelInfo;
+    /**
+     * Get list of available models from Anthropic.
+     * Fetches from the Models API with caching.
+     *
+     * @param filter - Optional search string to filter models by name/id
+     */
+    getModels(filter?: string): Promise<ProviderModelInfo[]>;
+    /**
+     * Resolve the default max_tokens for a model from the static capability
+     * table, clamped so non-streaming requests stay under HTTP timeouts.
+     */
+    private defaultMaxTokensFor;
+    generate(request: ProviderRequest): Promise<ProviderResponse>;
+    stream(request: ProviderRequest): Promise<AsyncIterable<ProviderStreamChunk>>;
+    private toProviderError;
+    /**
+     * Transform a ProviderRequest to Anthropic Messages API format for inspection.
+     * Returns the exact request body that would be sent, with base64 data truncated.
+     */
+    inspectRequest(request: ProviderRequest): Promise<InspectedRequest>;
+}
+
+/**
+ * Anthropic (Claude) provider factory for Standard Agents
+ *
+ * Includes typed providerOptions for Anthropic-specific configuration.
+ *
+ * @example
+ * ```typescript
+ * import { defineModel } from '@standardagents/builder';
+ * import { anthropic } from '@standardagents/anthropic';
+ *
+ * export default defineModel({
+ *   name: 'claude-opus',
+ *   provider: anthropic,
+ *   model: 'claude-opus-4-8',
+ *   inputPrice: 5,
+ *   outputPrice: 25,
+ *   capabilities: {
+ *     supportsImages: true,
+ *     supportsToolCalls: true,
+ *     supportsJsonMode: true,
+ *     maxContextTokens: 1000000,
+ *   },
+ *   providerOptions: {
+ *     cacheSystemPrompt: true,
+ *   },
+ * });
+ * ```
+ */
+declare const anthropic: ProviderFactoryWithOptions<typeof anthropicProviderOptions>;
+
+export { type AnthropicModelPricing, AnthropicProvider, type AnthropicProviderOptions, type AnthropicUsageBuckets, anthropic, anthropicProviderOptions, calculateAnthropicUsageCost, extractUsageBuckets, getAnthropicModelPricing };