azion/packages/ai/dist/index.d.mts

Azion Packages for Edge Computing.

/**
 * Represents a message in the AI conversation.
 *
 * @property {('system' | 'user' | 'assistant')} role - The role of the message sender.
 * @property {string} content - The content of the message.
 */
interface AzionAIMessage {
    role: 'system' | 'user' | 'assistant';
    content: string;
}
/**
 * Configuration options for the Azion AI request.
 *
 * @property {string} [session_id] - Unique identifier for the session.
 * @property {string} [url] - URL associated with the request.
 * @property {string} [app] - Application identifier.
 * @property {string} [user_name] - Name of the user.
 * @property {string} [client_id] - Client identifier.
 * @property {string} [system_prompt] - System-level prompt.
 * @property {string} [user_prompt] - User-level prompt.
 */
interface AzionAIConfig {
    session_id?: string;
    url?: string;
    app?: string;
    user_name?: string;
    client_id?: string;
    system_prompt?: string;
    user_prompt?: string;
}
/**
 * Structure of an AI request to be sent to the Azion AI service.
 *
 * @property {AzionAIMessage[]} messages - Array of messages in the conversation.
 * @property {AzionAIConfig} [azion] - Additional Azion-specific configuration.
 * @property {boolean} [stream] - Whether to use streaming for the response.
 */
interface AzionAIRequest {
    messages: AzionAIMessage[];
    azion?: AzionAIConfig;
    stream?: boolean;
}
/**
 * Structure of the AI response received from the Azion AI service.
 *
 * @property {Object[]} choices - Array of response choices.
 * @property {string} choices[].finish_reason - Reason for finishing the response.
 * @property {number} choices[].index - Index of the choice.
 * @property {Object} choices[].message - Message content and role.
 * @property {string} choices[].message.content - Content of the message.
 * @property {string} choices[].message.role - Role of the message sender.
 * @property {null} choices[].logprobs - Log probabilities (null in this case).
 * @property {number} created - Timestamp of when the response was created.
 * @property {string} id - Unique identifier for the response.
 * @property {string} model - Model used for generating the response.
 * @property {string} object - Type of object returned.
 * @property {Object} usage - Token usage statistics.
 * @property {number} usage.completion_tokens - Number of tokens in the completion.
 * @property {number} usage.prompt_tokens - Number of tokens in the prompt.
 * @property {number} usage.total_tokens - Total number of tokens used.
 * @property {Object} usage.completion_tokens_details - Detailed token usage for completion.
 * @property {number} usage.completion_tokens_details.reasoning_tokens - Number of tokens used for reasoning.
 */
interface AzionAIResponse {
    choices: {
        finish_reason: string;
        index: number;
        message: {
            content: string;
            role: string;
        };
        logprobs: null;
    }[];
    created: number;
    id: string;
    model: string;
    object: string;
    usage: {
        completion_tokens: number;
        prompt_tokens: number;
        total_tokens: number;
        completion_tokens_details: {
            reasoning_tokens: number;
        };
    };
}
/**
 * Structure of a streaming AI response from the Azion AI service.
 *
 * @property {Object[]} choices - Array of response choices.
 * @property {Object} choices[].delta - Delta of the response content.
 * @property {string} [choices[].delta.content] - Content of the delta, if any.
 * @property {string | null} choices[].finish_reason - Reason for finishing the response, if applicable.
 * @property {number} choices[].index - Index of the choice.
 * @property {null} choices[].logprobs - Log probabilities (null in this case).
 * @property {number} created - Timestamp of when the response was created.
 * @property {string} id - Unique identifier for the response.
 * @property {string} model - Model used for generating the response.
 * @property {string} object - Type of object returned.
 * @property {string} system_fingerprint - Fingerprint of the system.
 */
interface AzionAIStreamResponse {
    choices: {
        delta: {
            content?: string;
        };
        finish_reason: string | null;
        index: number;
        logprobs: null;
    }[];
    created: number;
    id: string;
    model: string;
    object: string;
    system_fingerprint: string;
}
/**
 * Generic result type for Azion AI operations.
 *
 * @template T - The type of data expected in the result.
 * @property {T | null} data - The data returned from the operation, if successful.
 * @property {Error | null} error - The error object, if the operation failed.
 */
interface AzionAIResult<T> {
    data: T | null;
    error: Error | null;
}
/**
 * Interface for the Azion AI client, providing methods to interact with the AI service.
 */
interface AzionAIClient {
    /**
     * Sends a chat request to the AI service.
     *
     * @param {AzionAIRequest} request - The chat request to be sent.
     * @param {AzionClientOptions} [options] - Additional options for the request.
     * @returns {Promise<AzionAIResult<AzionAIResponse>>} A promise that resolves to the chat result or an error.
     *
     * @example
     * const result = await aiClient.chat({
     *   messages: [{ role: 'user', content: 'Hello, AI!' }]
     * });
     * if (result.data) {
     *   console.log('AI response:', result.data.choices[0].message.content);
     * } else {
     *   console.error('Error:', result.error);
     * }
     */
    chat: (request: AzionAIRequest, options?: AzionClientOptions) => Promise<AzionAIResult<AzionAIResponse>>;
    /**
     * Sends a streaming chat request to the AI service.
     *
     * @param {AzionAIRequest} request - The chat request to be sent.
     * @param {AzionClientOptions} [options] - Additional options for the request.
     * @returns {AsyncGenerator<AzionAIResult<AzionAIStreamResponse>>} An async generator that produces partial chat results.
     *
     * @example
     * const stream = aiClient.streamChat({
     *   messages: [{ role: 'user', content: 'Tell me a story' }]
     * });
     * for await (const chunk of stream) {
     *   if (chunk.data) {
     *     console.log('AI chunk:', chunk.data.choices[0].delta.content);
     *   } else {
     *     console.error('Error:', chunk.error);
     *   }
     * }
     */
    streamChat: (request: AzionAIRequest, options?: AzionClientOptions) => AsyncGenerator<AzionAIResult<AzionAIStreamResponse>>;
}
/**
 * Options for configuring the Azion client behavior.
 *
 * @property {boolean} [debug] - Enable debug mode for detailed logging.
 * @property {boolean} [force] - Force the operation even if it might be destructive.
 *
 * @example
 * const options: AzionClientOptions = {
 *   debug: true,
 *   force: false
 * };
 */
type AzionClientOptions = {
    debug?: boolean;
    force?: boolean;
};
/**
 * Function type for creating an Azion AI Client.
 *
 * @param {Object} [config] - Configuration options for the AI client.
 * @param {string} [config.token] - Authentication token for Azion API. If not provided,
 * the client will attempt to use the AZION_TOKEN environment variable.
 * @param {AzionClientOptions} [config.options] - Additional client options.
 *
 * @returns {AzionAIClient} An instance of the Azion AI Client.
 *
 * @example
 * // Create an AI client with a token and debug mode enabled
 * const aiClient = createAzionAIClient({
 *   token: 'your-api-token',
 *   options: { debug: true }
 * });
 *
 * @example
 * // Create an AI client using environment variables for token
 * const aiClient = createAzionAIClient();
 *
 * @example
 * // Use the AI client to send a chat request
 * const response = await aiClient.chat({
 *   messages: [{ role: 'user', content: 'Hello, AI!' }]
 * });
 */
type CreateAzionAIClient = (config?: Partial<{
    token: string;
    options?: AzionClientOptions;
}>) => AzionAIClient;

/**
 * @module @azion/ai
 * @description This module provides a client for interacting with Azion AI services.
 */

/**
 * Executes an AI chat request.
 *
 * @async
 * @function chatMethod
 * @param {string} token - Authentication token for the API.
 * @param {AzionAIRequest} request - Request object containing chat parameters.
 * @param {AzionClientOptions} [options] - Additional client options.
 * @returns {Promise<AzionAIResult<AzionAIResponse>>} A promise that resolves to the chat result or an error.
 *
 * @example
 * const { data, error } = await chatMethod('your-token', {
 *   messages: [{ role: 'user', content: 'Hello, AI!' }]
 * }, { debug: true });
 * if (data) {
 *   console.log('AI response:', data.choices[0].message.content);
 * } else if (error) {
 *   console.error('Error:', error.message);
 * }
 */
declare const chatMethod: (token: string, request: AzionAIRequest, options?: AzionClientOptions) => Promise<AzionAIResult<AzionAIResponse>>;
/**
 * Executes a streaming AI chat request.
 *
 * @async
 * @generator
 * @function streamChatMethod
 * @param {string} token - Authentication token for the API.
 * @param {AzionAIRequest} request - Request object containing chat parameters.
 * @param {AzionClientOptions} [options] - Additional client options.
 * @yields {AzionAIResult<AzionAIStreamResponse>} Generates partial chat results in real-time.
 *
 * @example
 * const stream = streamChatMethod('your-token', {
 *   messages: [{ role: 'user', content: 'Tell me a story' }]
 * }, { debug: true });
 * for await (const { data, error } of stream) {
 *   if (data) {
 *     console.log('AI chunk:', data.choices[0].delta.content);
 *   } else if (error) {
 *     console.error('Error:', error.message);
 *   }
 * }
 */
declare const streamChatMethod: (token: string, request: AzionAIRequest, options?: AzionClientOptions) => AsyncGenerator<AzionAIResult<AzionAIStreamResponse>>;
/**
 * Executes an AI chat request with automatic token resolution.
 *
 * @async
 * @function chat
 * @param {AzionAIRequest} request - Request object containing chat parameters.
 * @param {AzionClientOptions} [options] - Additional client options.
 * @returns {Promise<AzionAIResult<AzionAIResponse>>} A promise that resolves to the chat result or an error.
 *
 * @example
 * const { data, error } = await chat({
 *   messages: [{ role: 'user', content: 'What is the capital of France?' }]
 * });
 * if (data) {
 *   console.log('AI response:', data.choices[0].message.content);
 * } else if (error) {
 *   console.error('Error:', error.message);
 * }
 */
declare const chat: (request: AzionAIRequest, options?: AzionClientOptions) => Promise<AzionAIResult<AzionAIResponse>>;
/**
 * Executes a streaming AI chat request with automatic token resolution.
 *
 * @async
 * @generator
 * @function streamChat
 * @param {AzionAIRequest} request - Request object containing chat parameters.
 * @param {AzionClientOptions} [options] - Additional client options.
 * @returns {AsyncGenerator<AzionAIResult<AzionAIStreamResponse>>} An async generator that produces partial chat results.
 *
 * @example
 * const stream = streamChat({
 *   messages: [{ role: 'user', content: 'Write a short story about a robot' }]
 * });
 * for await (const { data, error } of stream) {
 *   if (data) {
 *     process.stdout.write(data.choices[0].delta.content || '');
 *   } else if (error) {
 *     console.error('Error:', error.message);
 *   }
 * }
 */
declare const streamChat: (request: AzionAIRequest, options?: AzionClientOptions) => AsyncGenerator<AzionAIResult<AzionAIStreamResponse>>;
/**
 * Creates an Azion AI client with methods to interact with AI services.
 *
 * @function createClient
 * @param {Partial<{ token: string; options?: AzionClientOptions }>} [config] - Optional configuration for the client.
 * @returns {AzionAIClient} A client object with methods to interact with AI services.
 *
 * @example
 * const aiClient = createClient({ token: 'your-api-token', options: { debug: true } });
 *
 * // Using the chat method
 * const { data: chatData, error: chatError } = await aiClient.chat({
 *   messages: [{ role: 'user', content: 'Explain quantum computing' }]
 * });
 * if (chatData) {
 *   console.log('AI response:', chatData.choices[0].message.content);
 * } else if (chatError) {
 *   console.error('Chat error:', chatError.message);
 * }
 *
 * // Using the streamChat method
 * const stream = aiClient.streamChat({
 *   messages: [{ role: 'user', content: 'Write a poem about AI' }]
 * });
 * for await (const { data: streamData, error: streamError } of stream) {
 *   if (streamData) {
 *     process.stdout.write(streamData.choices[0].delta.content || '');
 *   } else if (streamError) {
 *     console.error('Stream error:', streamError.message);
 *   }
 * }
 */
declare const createClient: CreateAzionAIClient;

export { type AzionAIClient, type AzionAIConfig, type AzionAIMessage, type AzionAIRequest, type AzionAIResponse, type AzionAIResult, type AzionAIStreamResponse, type AzionClientOptions, type CreateAzionAIClient, chat, chatMethod, createClient, createClient as default, streamChat, streamChatMethod };