@honeagents/hone 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,674 @@
+/**
+ * AI Provider definitions compatible with Vercel AI SDK.
+ *
+ * This module provides type-safe provider identifiers that align with
+ * the Vercel AI SDK's official provider packages (@ai-sdk/*).
+ *
+ * @see https://ai-sdk.dev/providers/ai-sdk-providers
+ *
+ * @example
+ * ```typescript
+ * import { AIProvider } from "@honeagents/hone";
+ *
+ * const agent = await hone.agent("my-agent", {
+ *   provider: AIProvider.OpenAI,
+ *   model: "gpt-4o",
+ *   defaultPrompt: "You are a helpful assistant.",
+ * });
+ * ```
+ */
+/**
+ * Supported AI providers from the Vercel AI SDK ecosystem.
+ *
+ * These correspond to the official @ai-sdk/* provider packages.
+ * Use these identifiers when specifying the `provider` field in agent options.
+ */
+declare enum AIProvider {
+    /** OpenAI - GPT models (gpt-4o, gpt-4, gpt-3.5-turbo, etc.) */
+    OpenAI = "openai",
+    /** Anthropic - Claude models (claude-3-opus, claude-3-sonnet, claude-3-haiku, etc.) */
+    Anthropic = "anthropic",
+    /** Google Generative AI - Gemini models (gemini-pro, gemini-1.5-pro, etc.) */
+    Google = "google",
+    /** Google Vertex AI - Enterprise Gemini models */
+    GoogleVertex = "google-vertex",
+    /** Azure OpenAI Service - Azure-hosted OpenAI models */
+    Azure = "azure",
+    /** xAI - Grok models */
+    XAI = "xai",
+    /** Mistral AI - Mistral models (mistral-large, mistral-medium, etc.) */
+    Mistral = "mistral",
+    /** Cohere - Command models */
+    Cohere = "cohere",
+    /** Groq - Fast inference for open models */
+    Groq = "groq",
+    /** Together.ai - Open model hosting */
+    TogetherAI = "togetherai",
+    /** Fireworks - Fast inference platform */
+    Fireworks = "fireworks",
+    /** DeepInfra - Model inference */
+    DeepInfra = "deepinfra",
+    /** DeepSeek - DeepSeek models */
+    DeepSeek = "deepseek",
+    /** Cerebras - Fast inference */
+    Cerebras = "cerebras",
+    /** Perplexity - Perplexity models with web search */
+    Perplexity = "perplexity",
+    /** Amazon Bedrock - AWS-hosted models */
+    AmazonBedrock = "amazon-bedrock",
+    /** Baseten - Model hosting platform */
+    Baseten = "baseten"
+}
+/**
+ * Type representing all valid provider string values.
+ * Use this when you need a union type of provider strings.
+ */
+type AIProviderValue = `${AIProvider}`;
+/**
+ * Array of all provider values for runtime validation.
+ */
+declare const AI_PROVIDER_VALUES: readonly AIProviderValue[];
+/**
+ * Check if a string is a valid AI provider.
+ *
+ * @param value - The string to check
+ * @returns True if the value is a valid AIProvider
+ *
+ * @example
+ * ```typescript
+ * if (isValidProvider(userInput)) {
+ *   // userInput is typed as AIProviderValue
+ * }
+ * ```
+ */
+declare function isValidProvider(value: string): value is AIProviderValue;
+/**
+ * Get the display name for a provider.
+ *
+ * @param provider - The provider identifier
+ * @returns Human-readable provider name
+ *
+ * @example
+ * ```typescript
+ * getProviderDisplayName("openai") // "OpenAI"
+ * getProviderDisplayName("amazon-bedrock") // "Amazon Bedrock"
+ * ```
+ */
+declare function getProviderDisplayName(provider: AIProviderValue | string): string;
+
+type HoneConfig = {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+};
+/**
+ * Supported entity types in the Hone system.
+ */
+type EntityType = "agent" | "tool" | "prompt";
+type ParamsValue = string | GetTextPromptOptions;
+type Params = Record<string, ParamsValue>;
+type SimpleParams = Record<string, string>;
+/**
+ * Hyperparameters for LLM configuration.
+ * Used by agents to configure LLM behavior.
+ */
+type Hyperparameters = {
+    /** LLM model identifier (e.g., "gpt-4", "claude-3-opus") - REQUIRED for agents */
+    model?: string;
+    /**
+     * LLM provider identifier. Use AIProvider enum for type safety.
+     * @example AIProvider.OpenAI, AIProvider.Anthropic, "openai", "anthropic"
+     */
+    provider?: AIProviderValue | (string & Record<string, never>);
+    /** Sampling temperature (0.00 to 2.00) */
+    temperature?: number;
+    /** Maximum output tokens */
+    maxTokens?: number;
+    /** Nucleus sampling parameter (0.00 to 1.00) */
+    topP?: number;
+    /** Repetition penalty (-2.00 to 2.00) */
+    frequencyPenalty?: number;
+    /** Topic diversity penalty (-2.00 to 2.00) */
+    presencePenalty?: number;
+    /** Array of stop tokens */
+    stopSequences?: string[];
+    /** Array of tool IDs this agent can use */
+    tools?: string[];
+};
+/**
+ * Required hyperparameters for agents.
+ * Model and provider are mandatory.
+ */
+type RequiredAgentHyperparameters = Required<Pick<Hyperparameters, "model" | "provider">> & Omit<Hyperparameters, "model" | "provider">;
+/**
+ * Options for fetching an agent.
+ * Model and provider are REQUIRED.
+ *
+ * @typeParam TExtra - Type for custom extra data that will be stored and returned
+ */
+type GetAgentOptions<TExtra extends Record<string, unknown> = Record<string, unknown>> = RequiredAgentHyperparameters & {
+    /**
+     * The major version of the agent. SDK controls this value.
+     * When majorVersion changes, minorVersion resets to 0.
+     * If not specified, defaults to 1.
+     */
+    majorVersion?: number;
+    /**
+     * Optional name for the agent for easier identification.
+     * Will fallback to id if not provided.
+     */
+    name?: string;
+    /**
+     * Parameters to substitute into the prompt. You can also nest agent/tool calls here.
+     */
+    params?: Params;
+    /**
+     * The default prompt to use if none is found in the database.
+     * The use of variables should be in the form `{{variableName}}`.
+     *
+     * @example
+     * ```typescript
+     * agent("greeting", {
+     *   model: "gpt-4",
+     *   provider: "openai",
+     *   params: { userName: "Alice" },
+     *   defaultPrompt: "Hello, {{userName}}! Welcome to our service.",
+     * })
+     * ```
+     */
+    defaultPrompt: string;
+    /**
+     * Custom extra data to store with the agent.
+     * This data is stored in the database and returned in the AgentResult.
+     *
+     * @example
+     * ```typescript
+     * agent<{ customField: string }>("my-agent", {
+     *   model: "gpt-4",
+     *   provider: "openai",
+     *   defaultPrompt: "...",
+     *   extra: { customField: "my-value" },
+     * })
+     * ```
+     */
+    extra?: TExtra;
+};
+/**
+ * Base result returned by hone.agent() without extra data.
+ * Contains both the evaluated system prompt and hyperparameters.
+ */
+type BaseAgentResult = {
+    /** The fully evaluated system prompt with all parameters substituted */
+    systemPrompt: string;
+    /** LLM model identifier (e.g., "gpt-4", "claude-3-opus") */
+    model: string;
+    /** LLM provider (e.g., "openai", "anthropic") */
+    provider: string;
+    /** Sampling temperature (0.00 to 2.00) */
+    temperature: number | null;
+    /** Maximum output tokens */
+    maxTokens: number | null;
+    /** Nucleus sampling parameter (0.00 to 1.00) */
+    topP: number | null;
+    /** Repetition penalty (-2.00 to 2.00) */
+    frequencyPenalty: number | null;
+    /** Topic diversity penalty (-2.00 to 2.00) */
+    presencePenalty: number | null;
+    /** Array of stop tokens */
+    stopSequences: string[];
+    /** Array of allowed tool IDs */
+    tools: string[];
+};
+/**
+ * The result returned by hone.agent()
+ * Contains the evaluated system prompt, hyperparameters, and any extra data.
+ *
+ * @typeParam TExtra - Type for custom extra data that was stored with the agent
+ */
+type AgentResult<TExtra extends Record<string, unknown> = Record<string, unknown>> = BaseAgentResult & TExtra;
+type HoneAgent = <TExtra extends Record<string, unknown> = Record<string, unknown>>(id: string, options: GetAgentOptions<TExtra>) => Promise<AgentResult<TExtra>>;
+/**
+ * Options for fetching a tool.
+ * Tools don't have hyperparameters - they're just versioned text templates.
+ */
+type GetToolOptions = {
+    /**
+     * The major version of the tool. SDK controls this value.
+     * When majorVersion changes, minorVersion resets to 0.
+     * If not specified, defaults to 1.
+     */
+    majorVersion?: number;
+    /**
+     * Optional name for the tool for easier identification.
+     * Will fallback to id if not provided.
+     */
+    name?: string;
+    /**
+     * Parameters to substitute into the prompt. You can also nest agent/tool calls here.
+     */
+    params?: Params;
+    /**
+     * The default prompt/description to use if none is found in the database.
+     * The use of variables should be in the form `{{variableName}}`.
+     *
+     * @example
+     * ```typescript
+     * tool("search", {
+     *   params: { query: "weather" },
+     *   defaultPrompt: "Search the web for: {{query}}",
+     * })
+     * ```
+     */
+    defaultPrompt: string;
+};
+/**
+ * The result returned by hone.tool()
+ * Contains the evaluated prompt with parameters substituted.
+ */
+type ToolResult = {
+    /** The fully evaluated prompt with all parameters substituted */
+    prompt: string;
+};
+type HoneTool = (id: string, options: GetToolOptions) => Promise<ToolResult>;
+/**
+ * Options for fetching a text prompt.
+ * Text prompts are simple versioned text templates with no hyperparameters.
+ * They can be nested inside agents, tools, or other prompts.
+ */
+type GetTextPromptOptions = {
+    /**
+     * The major version of the prompt. SDK controls this value.
+     * When majorVersion changes, minorVersion resets to 0.
+     * If not specified, defaults to 1.
+     */
+    majorVersion?: number;
+    /**
+     * Optional name for the prompt for easier identification.
+     * Will fallback to id if not provided.
+     */
+    name?: string;
+    /**
+     * Parameters to substitute into the prompt. You can also nest other prompts here.
+     */
+    params?: Params;
+    /**
+     * The default text to use if none is found in the database.
+     * The use of variables should be in the form `{{variableName}}`.
+     *
+     * @example
+     * ```typescript
+     * prompt("tone-guidelines", {
+     *   defaultPrompt: "Always be friendly and professional.",
+     * })
+     * ```
+     */
+    defaultPrompt: string;
+};
+/**
+ * The result returned by hone.prompt()
+ * Contains the evaluated text with parameters substituted.
+ */
+type TextPromptResult = {
+    /** The fully evaluated text with all parameters substituted */
+    text: string;
+};
+type HoneTextPrompt = (id: string, options: GetTextPromptOptions) => Promise<TextPromptResult>;
+/**
+ * Represents a tool call made by the assistant.
+ * Compatible with OpenAI's function calling format.
+ */
+type ToolCall = {
+    /** Unique identifier for this tool call */
+    id: string;
+    /** Name of the tool/function being called */
+    name: string;
+    /** JSON string of the arguments to pass to the tool */
+    arguments: string;
+};
+type Message = {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    /** Tool calls requested by the assistant (present when role is "assistant") */
+    tool_calls?: ToolCall[];
+    /** ID of the tool call this message is responding to (present when role is "tool") */
+    tool_call_id?: string;
+};
+type TrackConversationOptions = {
+    sessionId: string;
+};
+type HoneTrack = (id: string, messages: Message[], options: TrackConversationOptions) => Promise<void>;
+type HoneClient = {
+    /**
+     * Fetches and evaluates an agent by its ID with the given options.
+     * @param id The unique identifier for the agent.
+     * @param options Options for fetching and evaluating the agent. Model and provider are required.
+     * @returns A Promise that resolves to an AgentResult containing systemPrompt and hyperparameters.
+     */
+    agent: HoneAgent;
+    /**
+     * Fetches and evaluates a tool by its ID with the given options.
+     * @param id The unique identifier for the tool.
+     * @param options Options for fetching and evaluating the tool.
+     * @returns A Promise that resolves to a ToolResult containing the evaluated prompt.
+     */
+    tool: HoneTool;
+    /**
+     * Fetches and evaluates a text prompt by its ID with the given options.
+     * @param id The unique identifier for the prompt.
+     * @param options Options for fetching and evaluating the prompt.
+     * @returns A Promise that resolves to a TextPromptResult containing the evaluated text.
+     */
+    prompt: HoneTextPrompt;
+    /**
+     * Adds messages to track a conversation under the given ID.
+     * @param id The unique identifier for the conversation to track.
+     * @param messages An array of Message objects representing the conversation.
+     * @param options Optional TrackConversationOptions such as sessionId.
+     */
+    track: HoneTrack;
+};
+/**
+ * Internal representation of an entity node in the tree.
+ */
+type EntityNode = Hyperparameters & {
+    id: string;
+    type: EntityType;
+    name?: string;
+    majorVersion?: number;
+    params: SimpleParams;
+    prompt: string;
+    children: EntityNode[];
+};
+/**
+ * Agent node is an EntityNode with type="agent"
+ */
+type AgentNode = EntityNode & {
+    type: "agent";
+};
+type AgentRequestItem = Omit<AgentNode, "children" | "params"> & {
+    paramKeys: string[];
+    childrenIds: string[];
+};
+type AgentRequest = {
+    agents: {
+        rootId: string;
+        map: Record<string, AgentRequestItem>;
+    };
+};
+type AgentResponseItem = {
+    prompt: string;
+    model: string | null;
+    provider: string | null;
+    temperature: number | null;
+    maxTokens: number | null;
+    topP: number | null;
+    frequencyPenalty: number | null;
+    presencePenalty: number | null;
+    stopSequences: string[];
+    tools: string[];
+};
+type AgentResponse = Record<string, AgentResponseItem>;
+/** @deprecated Use GetAgentOptions instead */
+type GetPromptOptions = GetAgentOptions;
+/** @deprecated Use AgentNode instead */
+type PromptNode = AgentNode;
+/** @deprecated Use AgentRequest instead */
+type PromptRequest = AgentRequest;
+/** @deprecated Use AgentResponse instead */
+type PromptResponse = AgentResponse;
+/** @deprecated Use HoneAgent instead */
+type HonePrompt = HoneAgent;
+
+declare class Hone implements HoneClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: HoneConfig);
+    private makeRequest;
+    agent<TExtra extends Record<string, unknown> = Record<string, unknown>>(id: string, options: GetAgentOptions<TExtra>): Promise<AgentResult<TExtra>>;
+    tool(id: string, options: GetToolOptions): Promise<ToolResult>;
+    prompt(id: string, options: GetTextPromptOptions): Promise<TextPromptResult>;
+    track(id: string, messages: Message[], options: TrackConversationOptions): Promise<void>;
+}
+declare function createHoneClient(config: HoneConfig): HoneClient;
+
+/**
+ * Tool tracking helpers for the Hone SDK.
+ *
+ * These utilities help format tool calls and results for tracking conversations
+ * that include function calling / tool use.
+ */
+
+/**
+ * Creates an assistant message containing tool calls.
+ *
+ * @param toolCalls - Array of tool calls the assistant is requesting
+ * @param content - Optional text content alongside tool calls (usually empty)
+ * @returns A Message object formatted for tool call requests
+ *
+ * @example
+ * ```typescript
+ * const message = createToolCallMessage([
+ *   { id: "call_abc123", name: "get_weather", arguments: '{"location":"SF"}' }
+ * ]);
+ * // { role: "assistant", content: "", tool_calls: [...] }
+ * ```
+ */
+declare function createToolCallMessage(toolCalls: ToolCall[], content?: string): Message;
+/**
+ * Creates a tool result message responding to a specific tool call.
+ *
+ * @param toolCallId - The ID of the tool call this result responds to
+ * @param result - The result from executing the tool (will be stringified if not a string)
+ * @returns A Message object formatted as a tool response
+ *
+ * @example
+ * ```typescript
+ * const message = createToolResultMessage("call_abc123", { temp: 72, unit: "F" });
+ * // { role: "tool", content: '{"temp":72,"unit":"F"}', tool_call_id: "call_abc123" }
+ * ```
+ */
+declare function createToolResultMessage(toolCallId: string, result: unknown): Message;
+/**
+ * Extracts messages from an OpenAI chat completion response.
+ *
+ * Handles both regular assistant messages and messages with tool calls.
+ *
+ * @param response - The OpenAI chat completion response object
+ * @returns Array of Message objects ready to be tracked
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from "openai";
+ *
+ * const openai = new OpenAI();
+ * const response = await openai.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages: [...],
+ *   tools: [...]
+ * });
+ *
+ * const messages = extractOpenAIMessages(response);
+ * await hone.track("conversation", [...existingMessages, ...messages], { sessionId });
+ * ```
+ */
+declare function extractOpenAIMessages(response: {
+    choices: Array<{
+        message: {
+            role: string;
+            content: string | null;
+            tool_calls?: Array<{
+                id: string;
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }>;
+        };
+    }>;
+}): Message[];
+/**
+ * Extracts messages from an Anthropic Claude response.
+ *
+ * Handles both text responses and tool use blocks.
+ *
+ * @param response - The Anthropic message response object
+ * @returns Array of Message objects ready to be tracked
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from "@anthropic-ai/sdk";
+ *
+ * const anthropic = new Anthropic();
+ * const response = await anthropic.messages.create({
+ *   model: "claude-sonnet-4-20250514",
+ *   messages: [...],
+ *   tools: [...]
+ * });
+ *
+ * const messages = extractAnthropicMessages(response);
+ * await hone.track("conversation", [...existingMessages, ...messages], { sessionId });
+ * ```
+ */
+declare function extractAnthropicMessages(response: {
+    role: string;
+    content: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "tool_use";
+        id: string;
+        name: string;
+        input: unknown;
+    }>;
+}): Message[];
+/**
+ * Extracts messages from a Google Gemini response.
+ *
+ * Handles both text responses and function call parts.
+ * Note: Gemini doesn't provide unique IDs for function calls, so we generate
+ * them using the format `gemini_{functionName}_{index}`.
+ *
+ * @param response - The Gemini GenerateContentResponse object
+ * @returns Array of Message objects ready to be tracked
+ *
+ * @example
+ * ```typescript
+ * import { GoogleGenerativeAI } from "@google/generative-ai";
+ *
+ * const genAI = new GoogleGenerativeAI(apiKey);
+ * const model = genAI.getGenerativeModel({ model: "gemini-pro" });
+ *
+ * const response = await model.generateContent({
+ *   contents: [...],
+ *   tools: [{ functionDeclarations: [...] }]
+ * });
+ *
+ * const messages = extractGeminiMessages(response);
+ * await hone.track("conversation", [...existingMessages, ...messages], { sessionId });
+ * ```
+ */
+declare function extractGeminiMessages(response: {
+    candidates?: Array<{
+        content?: {
+            role?: string;
+            parts?: Array<{
+                text: string;
+            } | {
+                functionCall: {
+                    name: string;
+                    args: Record<string, unknown>;
+                };
+            }>;
+        };
+    }>;
+}): Message[];
+/**
+ * Short alias for createToolResultMessage.
+ * Creates a tool result message responding to a specific tool call.
+ *
+ * @example
+ * ```typescript
+ * messages.push(toolResult(toolCall.id, { temp: 72 }));
+ * ```
+ */
+declare const toolResult: typeof createToolResultMessage;
+/**
+ * Short alias for extractOpenAIMessages.
+ * Extracts messages from an OpenAI chat completion response.
+ *
+ * @example
+ * ```typescript
+ * messages.push(...fromOpenAI(response));
+ * ```
+ */
+declare const fromOpenAI: typeof extractOpenAIMessages;
+/**
+ * Short alias for extractAnthropicMessages.
+ * Extracts messages from an Anthropic Claude response.
+ *
+ * @example
+ * ```typescript
+ * messages.push(...fromAnthropic(response));
+ * ```
+ */
+declare const fromAnthropic: typeof extractAnthropicMessages;
+/**
+ * Short alias for extractGeminiMessages.
+ * Extracts messages from a Google Gemini response.
+ *
+ * @example
+ * ```typescript
+ * messages.push(...fromGemini(response));
+ * ```
+ */
+declare const fromGemini: typeof extractGeminiMessages;
+
+/**
+ * Constructs an AgentNode from the given id and GetAgentOptions.
+ * Traverses nested agents/tools recursively.
+ *
+ * @param id the unique identifier for the agent node
+ * @param options the GetAgentOptions containing agent details and parameters
+ * @param ancestorIds Set of ancestor IDs to detect circular references
+ * @returns AgentNode
+ * @throws Error if a self-reference or circular reference is detected
+ */
+declare function getAgentNode(id: string, options: GetAgentOptions, ancestorIds?: Set<string>): AgentNode;
+/**
+ * Evaluates an AgentNode (alias for evaluateEntity for backwards compatibility)
+ */
+declare function evaluateAgent(node: AgentNode): string;
+/**
+ * Inserts parameters into a prompt template.
+ *
+ * @param prompt The prompt template containing placeholders in the form `{{variableName}}`.
+ * @param params An object mapping variable names to their replacement values.
+ * @returns The prompt with all placeholders replaced by their corresponding values.
+ */
+declare function insertParamsIntoPrompt(prompt: string, params?: SimpleParams): string;
+/**
+ * Traverses an AgentNode tree (alias for backwards compatibility)
+ */
+declare function traverseAgentNode(node: AgentNode, callback: (node: AgentNode, parentId: string | null) => void, parentId?: string | null): void;
+/**
+ * Formats an AgentNode into an AgentRequest suitable for the /sync_agents API.
+ * (Backwards compatible format)
+ */
+declare function formatAgentRequest(node: AgentNode): AgentRequest;
+/**
+ * Updates all nodes in an AgentNode tree (alias for backwards compatibility)
+ */
+declare function updateAgentNodes(root: AgentNode, callback: (agentNode: AgentNode) => AgentNode): AgentNode;
+/** @deprecated Use getAgentNode instead */
+declare const getPromptNode: typeof getAgentNode;
+/** @deprecated Use evaluateAgent instead */
+declare const evaluatePrompt: typeof evaluateAgent;
+/** @deprecated Use traverseAgentNode instead */
+declare const traversePromptNode: typeof traverseAgentNode;
+/** @deprecated Use formatAgentRequest instead */
+declare const formatPromptRequest: typeof formatAgentRequest;
+/** @deprecated Use updateAgentNodes instead */
+declare const updatePromptNodes: typeof updateAgentNodes;
+
+export { AIProvider, type AIProviderValue, AI_PROVIDER_VALUES, type AgentNode, type AgentRequest, type AgentResponse, type AgentResponseItem, type AgentResult, type GetAgentOptions, type GetPromptOptions, Hone, type HoneAgent, type HoneClient, type HonePrompt, type HoneTrack, type Hyperparameters, type Message, type PromptNode, type PromptRequest, type PromptResponse, type ToolCall, createHoneClient, createToolCallMessage, createToolResultMessage, evaluateAgent, evaluatePrompt, extractAnthropicMessages, extractGeminiMessages, extractOpenAIMessages, formatAgentRequest, formatPromptRequest, fromAnthropic, fromGemini, fromOpenAI, getAgentNode, getPromptNode, getProviderDisplayName, insertParamsIntoPrompt, isValidProvider, toolResult, traverseAgentNode, traversePromptNode, updateAgentNodes, updatePromptNodes };