@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/anthropic-client.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Anthropic API client service for Claude interactions
+ *
+ * This module provides a comprehensive client for interacting with Anthropic's Claude API,
+ * supporting streaming responses, model switching, token tracking, and retry logic with
+ * exponential backoff.
+ */
+import { ModelConfig, StreamingResponse, Message, Tool, ContentBlock } from '../types/anthropic.js';
+import { TokenUsage, CostEstimate } from '../types/token.js';
+import { type Provider } from '../constants/defaults.js';
+/**
+ * Options for sending messages to the API
+ */
+export interface MessageOptions {
+    /** System prompt to use */
+    system?: string;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for response generation (0-1) */
+    temperature?: number;
+    /** Tools available for the model to use */
+    tools?: Tool[];
+    /** Stop sequences to end generation */
+    stopSequences?: string[];
+    /** Enable prompt caching for system prompt (reduces cost on repeated calls) */
+    enablePromptCaching?: boolean;
+    /** Override model for this specific call (e.g., use 'haiku' for cheaper summarization) */
+    model?: string;
+    /** Type of call for cost tracking (conversation or compaction, defaults to conversation) */
+    callType?: 'conversation' | 'compaction';
+    /** Abort signal to cancel the request */
+    abortSignal?: AbortSignal;
+    /** JSON schema for structured output (uses beta API with betaJSONSchemaOutputFormat helper) */
+    outputFormat?: Record<string, unknown> & {
+        type: 'object';
+    };
+}
+/**
+ * Result from a non-streaming message request
+ */
+export interface MessageResult {
+    /** The generated content */
+    content: string;
+    /** Token usage statistics */
+    usage: TokenUsage;
+    /** Cost estimate for the request */
+    cost: CostEstimate;
+    /** Stop reason from the API */
+    stopReason?: string;
+    /** Model used for generation */
+    model: string;
+}
+/**
+ * Tool use block from the API response
+ */
+export interface ToolUseBlock {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Full response from the API including tool use blocks
+ */
+export interface AgenticResponse {
+    /** Text content from the response */
+    textContent: string;
+    /** Tool use blocks if any */
+    toolUseBlocks: ToolUseBlock[];
+    /** Stop reason - 'end_turn' or 'tool_use' */
+    stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
+    /** Token usage */
+    usage: TokenUsage;
+    /** Cost estimate */
+    cost: CostEstimate;
+    /** The full content blocks for building assistant message */
+    contentBlocks: ContentBlock[];
+}
+/**
+ * Event types for streaming tool use blocks
+ */
+export type ToolStreamEvent = {
+    type: 'tool_start';
+    id: string;
+    name: string;
+} | {
+    type: 'tool_input_delta';
+    id: string;
+    partialInput: string;
+} | {
+    type: 'tool_complete';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+/**
+ * Configuration for retry behavior
+ */
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterFactor: number;
+}
+/**
+ * AnthropicClient class provides a comprehensive interface for interacting
+ * with Anthropic's Claude API. It supports streaming responses, model switching,
+ * automatic token tracking, and retry logic with exponential backoff.
+ *
+ * Features:
+ * - Streaming and non-streaming message generation
+ * - Automatic model switching with validation
+ * - Token usage tracking and cost estimation
+ * - Retry logic with exponential backoff and jitter
+ * - Event emission for token updates and model changes
+ * - Connection testing and validation
+ */
+declare class AnthropicClient {
+    private clients;
+    private currentModel;
+    private eventEmitter;
+    private retryConfig;
+    private initialized;
+    private apiKey;
+    private providerApiKeys;
+    constructor(retryConfig?: Partial<RetryConfig>);
+    /**
+     * Gets the provider for a given model.
+     */
+    private getModelProvider;
+    /**
+     * Gets the API key for a specific provider.
+     * Returns cached key if available, otherwise fetches from credential store.
+     */
+    private getApiKeyForProvider;
+    /**
+     * Resolves the base URL for a given model.
+     *
+     * @param modelId - The model ID to resolve base URL for
+     * @returns The base URL for the model
+     */
+    private resolveBaseUrl;
+    /**
+     * Gets or creates a client for the specified model.
+     * Uses provider-specific API keys when available.
+     *
+     * @param modelId - The model ID to get client for
+     * @returns The Anthropic client instance for the model's base URL
+     */
+    private getClientForModel;
+    /**
+     * Initializes the client with API keys from credential store.
+     * Loads API keys for all configured providers.
+     * Must be called before making any API requests.
+     *
+     * @returns True if initialization was successful, false otherwise
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Checks if the client has been initialized with a valid API key.
+     *
+     * @returns True if the client is ready to make requests
+     */
+    isInitialized(): boolean;
+    /**
+     * Gets the current model configuration.
+     *
+     * @returns The ModelConfig for the currently selected model
+     */
+    getCurrentModel(): ModelConfig;
+    /**
+     * Gets the current model ID.
+     *
+     * @returns The model ID string
+     */
+    getCurrentModelId(): string;
+    /**
+     * Switches to a different Claude model.
+     * Automatically loads the API key for the new model's provider if needed.
+     *
+     * @param modelIdOrAlias - The model ID or alias (e.g., 'sonnet', 'opus', 'haiku')
+     * @returns True if the switch was successful, false if the model is unknown or API key is missing
+     */
+    setModel(modelIdOrAlias: string): boolean;
+    /**
+     * Switches to a different model (async version).
+     * Automatically loads the API key for the new model's provider if not already cached.
+     *
+     * @param modelIdOrAlias - The model ID or alias
+     * @returns True if the switch was successful
+     */
+    setModelAsync(modelIdOrAlias: string): Promise<boolean>;
+    /**
+     * Sends a message and streams the response in real-time.
+     * Yields StreamingResponse objects as content is generated.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Optional configuration for the request
+     * @yields StreamingResponse objects containing text chunks, tool use, or completion info
+     */
+    streamMessage(messages: Message[], options?: MessageOptions): AsyncGenerator<StreamingResponse>;
+    /**
+     * Sends a message and waits for the complete response.
+     * Use this for non-streaming use cases where you need the full response at once.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Optional configuration for the request
+     * @returns Promise resolving to the complete message result
+     * @throws Error if the request fails after all retries
+     */
+    sendMessage(messages: Message[], options?: MessageOptions): Promise<MessageResult>;
+    /**
+     * Removes markdown code fence delimiters from JSON content.
+     * Extracts JSON from ```json or ``` code blocks, or returns trimmed content if no code fence found.
+     *
+     * @param content - The raw content string that may contain markdown code fences
+     * @returns The cleaned JSON string
+     */
+    private removeMarkdownCodeFence;
+    /**
+     * Creates a JSON schema output format object from the given JSON schema.
+     * If this is passed to the `.parse()` method then the response message will contain a
+     * `.parsed_output` property that is the result of parsing the content with the given JSON schema.
+     *
+     */
+    private betaJSONSchemaOutputFormat;
+    /**
+     * Sends a message with structured JSON output using the beta parse API.
+     * This enforces the response to conform to a specific JSON schema.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Configuration including outputFormat (JSON schema)
+     * @returns Promise resolving to the complete message result with structured JSON
+     * @throws Error if the request fails or schema validation fails
+     */
+    sendStructuredMessage(messages: Message[], options: MessageOptions): Promise<MessageResult>;
+    /**
+     * Creates a message with full response including tool use blocks.
+     * This is the primary method for the agentic loop.
+     *
+     * @param messages - Array of conversation messages (can include tool_result blocks)
+     * @param options - Configuration for the request
+     * @param onTextChunk - Optional callback for streaming text chunks
+     * @param onToolEvent - Optional callback for tool use streaming events
+     * @returns Full response with tool use blocks and stop reason
+     */
+    createAgenticMessage(messages: Message[], options?: MessageOptions, onTextChunk?: (text: string) => void, onToolEvent?: (event: ToolStreamEvent) => void): Promise<AgenticResponse>;
+    /**
+     * Tests the API connection by sending a minimal request.
+     * Useful for validating API key and connectivity.
+     *
+     * @returns True if the connection test succeeded, false otherwise
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Validates an API key by attempting to make a test request.
+     *
+     * @param apiKey - The API key to validate
+     * @param model - Optional model to use for validation (determines base URL)
+     * @returns True if the API key is valid, false otherwise
+     */
+    validateApiKey(apiKey: string, model?: string): Promise<boolean>;
+    /**
+     * Gets available models with their configurations.
+     *
+     * @returns Array of available ModelConfig objects
+     */
+    getAvailableModels(): ModelConfig[];
+    /**
+     * Estimates the cost for a given token usage with the current model.
+     *
+     * @param usage - Token usage to estimate cost for
+     * @returns Cost estimate in USD
+     */
+    estimateCost(usage: TokenUsage): CostEstimate;
+    /**
+     * Calculates the cost for token usage with a specific model.
+     * Uses the centralized cost calculation from cost-tracker.ts which handles
+     * all token types including cache operations.
+     *
+     * @param usage - Token usage statistics
+     * @param model - Model configuration with pricing
+     * @returns Cost estimate breakdown (for backward compatibility with CostEstimate type)
+     */
+    private calculateCost;
+    /**
+     * Formats messages for the Anthropic API.
+     *
+     * @param messages - Array of Message objects
+     * @returns Formatted messages for the API
+     */
+    private formatMessages;
+    /**
+     * Determines if an error is retryable.
+     *
+     * @param error - The error to check
+     * @returns True if the error is retryable
+     */
+    private getFriendlyErrorMessage;
+    private isRetryableError;
+    /**
+     * Calculates retry delay with exponential backoff and jitter.
+     *
+     * @param attempt - Current attempt number (0-indexed)
+     * @returns Delay in milliseconds
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleeps for the specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     */
+    private sleep;
+    /**
+     * Resets the client state, requiring re-initialization.
+     */
+    reset(): void;
+    /**
+     * Gets the list of providers that have API keys configured.
+     *
+     * @returns Array of provider names with configured API keys
+     */
+    getConfiguredProviders(): Provider[];
+    /**
+     * Checks if an API key is configured for a specific provider.
+     *
+     * @param provider - The provider to check
+     * @returns True if an API key is configured for this provider
+     */
+    hasApiKeyForProvider(provider: Provider): boolean;
+    /**
+     * Sets an API key for a specific provider at runtime.
+     * Useful for dynamically adding provider API keys during a session.
+     *
+     * @param provider - The provider name
+     * @param apiKey - The API key to set
+     */
+    setProviderApiKey(provider: Provider, apiKey: string): void;
+}
+/**
+ * Gets the singleton AnthropicClient instance.
+ * Creates the instance on first call.
+ *
+ * Note: You must call initialize() on the returned client before making API requests.
+ *
+ * @returns Promise resolving to the AnthropicClient instance
+ */
+export declare function getAnthropicClient(): Promise<AnthropicClient>;
+/**
+ * Creates a new AnthropicClient instance with custom configuration.
+ * Use this when you need a separate instance from the singleton.
+ *
+ * @param retryConfig - Optional custom retry configuration
+ * @returns A new AnthropicClient instance
+ */
+export declare function createAnthropicClient(retryConfig?: Partial<RetryConfig>): AnthropicClient;
+export { AnthropicClient };
+//# sourceMappingURL=anthropic-client.d.ts.map

package/dist/services/anthropic-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-client.d.ts","sourceRoot":"","sources":["../../src/services/anthropic-client.ts"],"names":[],"mappings":"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"}