@pompeii-labs/magma/dist/trace-BClTKMpT.d.mts

The Typescript framework to build AI agents quickly and easily

import Anthropic from '@anthropic-ai/sdk';
import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions/completions';
import { ModelParams, GenerationConfig, ToolConfig, GoogleGenerativeAI } from '@google/generative-ai';
import Groq from 'groq-sdk';
import { ChatCompletionCreateParams } from 'groq-sdk/resources/chat/completions';
import OpenAI from 'openai';
import { Request, Response } from 'express';

declare const MagmaProviders: readonly ["openai", "anthropic", "groq", "google"];
type MagmaProvider = (typeof MagmaProviders)[number];
type MagmaClient = OpenAI | Anthropic | Groq | GoogleGenerativeAI;
type AnthropicModel = Anthropic.Messages.Model;
type OpenAIModel = ChatCompletionCreateParamsBase['model'];
type GroqModel = ChatCompletionCreateParams['model'];
type GoogleModel = ModelParams['model'];
type MagmaModel = AnthropicModel | OpenAIModel | GroqModel | GoogleModel;
type MagmaOpenAISettings = Omit<ChatCompletionCreateParamsBase, 'messages' | 'model' | 'function_call' | 'functions' | 'stream' | 'stream_options' | 'tools'>;
type MagmaAnthropicSettings = Omit<Anthropic.Messages.MessageCreateParams, 'max_tokens' | 'messages' | 'model' | 'stream' | 'tools' | 'system'> & {
    max_tokens?: number;
};
type MagmaGroqSettings = Omit<ChatCompletionCreateParams, 'messages' | 'model' | 'function_call' | 'functions' | 'stream' | 'tools'>;
type MagmaGoogleSettings = Omit<GenerationConfig, 'model'> & {
    toolConfig?: ToolConfig;
};
type OpenAIProviderConfig = {
    client?: object;
    provider: 'openai';
    model: OpenAIModel;
    settings?: MagmaOpenAISettings;
};
type AnthropicProviderConfig = {
    client?: object;
    provider: 'anthropic';
    model: AnthropicModel;
    settings?: MagmaAnthropicSettings;
};
type GroqProviderConfig = {
    client?: object;
    provider: 'groq';
    model: GroqModel;
    settings?: MagmaGroqSettings;
};
type GoogleProviderConfig = {
    client?: object;
    provider: 'google';
    model: GoogleModel;
    settings?: MagmaGoogleSettings;
};
type MagmaProviderConfig = OpenAIProviderConfig | AnthropicProviderConfig | GroqProviderConfig | GoogleProviderConfig;

type AgentProps = MagmaProviderConfig & {
    verbose?: boolean;
    messageContext?: number;
    stream?: boolean;
    sessionId?: string;
};
declare class MagmaAgent {
    verbose?: boolean;
    stream: boolean;
    sessionId: string;
    private providerConfig;
    private retryCount;
    private messages;
    private middlewareRetries;
    private messageContext;
    private scheduledJobs;
    private abortControllers;
    constructor(args?: AgentProps);
    log(message: string): void;
    setup?(opts?: object): Promise<void>;
    /**
     * Optional method to receive input from the user
     * @param message message object received from the user - type to be defined by extending class
     */
    receive?(message: any): Promise<void>;
    /**
     * Sends data to the connected client depending on the medium (ws, SSE, etc)
     * @param message any data object to be sent to the client
     */
    send(message: Record<string, any>): Promise<void>;
    onWsClose(code: number, reason?: string): Promise<void>;
    cleanup(): Promise<void>;
    private _cleanup;
    /**
     * Handles the completion process by interacting with the configured provider and executing middleware.
     * This function performs the following steps:
     * 1. Retrieves the provider instance based on the configured provider name.
     * 2. Executes the 'preCompletion' middleware, which can modify the last message before making the AI request.
     * 3. Configures the completion request with necessary parameters such as model, messages, and tools.
     * 4. Sends the completion request to the provider and updates usage statistics.
     * 5. If the response indicates a 'tool_call', runs the 'preToolExecution' middleware and executes the appropriate tool.
     * 6. If not a tool call, runs the 'onCompletion' middleware with the returned message.
     *
     * If an error occurs during the process, the function will either trigger an error update handler or rethrow the error.
     *
     * @returns { MagmaMessage } A promise that resolves to a `MagmaMessage` object, which is either the final message
     * returned from the provider or the result of a tool execution
     *
     * @throws Will rethrow the error if no `onError` handler is defined
     */
    main(args?: {
        config?: MagmaProviderConfig;
        parentRequestIds?: string[];
        trace?: TraceEvent[];
        onTrace?: (trace: TraceEvent[]) => void;
    }): Promise<MagmaAssistantMessage | null>;
    /**
     * Set the provider configuration for the agent
     * @param providerConfig provider configuration
     */
    setProviderConfig(providerConfig: MagmaProviderConfig): void;
    /**
     * Store a message in the agent context
     *
     * @param content content of the message to store
     * @param role message role (default: user)
     */
    addMessage(message: MagmaMessageType): void;
    /**
     * Set the messages for the agent
     * @param messages messages to set
     */
    setMessages(messages: MagmaMessage[]): void;
    /**
     * Remove a message from the agent context
     * If no filter is provided, the last message is removed
     *
     * @param filter optional, remove messages that match the filter
     */
    removeMessage(filter?: (message: MagmaMessage) => boolean): void;
    /**
     * Get the last N messages from the agent context
     * @param slice number of messages to return (default: 20)
     * @returns array of messages
     */
    getMessages(slice?: number): MagmaMessage[];
    /**
     * Stops the currently executing request.
     * @returns true if a request was killed, false otherwise
     */
    kill(): void;
    /**
     * Return whether the agent is currently processing a request
     */
    get processing(): boolean;
    scheduleJobs({ verbose }?: {
        verbose?: boolean;
    }): void;
    cancelJobs(): void;
    /**
     * Given a tool call, find the appropriate function to handle the run
     *
     * @param message MagmaAssistantMessage message to execute tools on
     * @param allowList optional, list of tool names to allow
     * @param trace trace event array
     * @param requestId request id
     * @returns MagmaUserMessage with tool results
     */
    private executeTools;
    private runPreCompletionMiddleware;
    private runOnCompletionMiddleware;
    private runOnMainFinishMiddleware;
    private runPreToolExecutionMiddleware;
    private runOnToolExecutionMiddleware;
    get utilities(): MagmaUtilities[];
    getUtilities(): MagmaUtilities[];
    getTools(): MagmaTool[];
    getMiddleware(): MagmaMiddleware[];
    getHooks(): MagmaHook[];
    getJobs(): MagmaJob[];
    get tools(): MagmaTool[];
    get middleware(): MagmaMiddleware[];
    get hooks(): MagmaHook[];
    get jobs(): MagmaJob[];
    getSystemPrompts(): MagmaSystemMessageType[];
    onError(error: Error): Promise<void> | void;
    onStreamChunk(chunk: MagmaStreamChunk | null): Promise<void> | void;
    onUsageUpdate(usage: object): Promise<void> | void;
    onCleanup(): Promise<void> | void;
}

type MagmaHook = {
    name: string;
    handler: (request: Request, response: Response, agent: MagmaAgent) => Promise<void>;
    session?: 'default' | (string & {}) | ((req: Request) => string | Promise<string>);
    setup?: ((req: Request) => Record<string, any> | Promise<Record<string, any>>) | Record<string, any>;
    description?: string;
};

interface MagmaJob {
    handler: (agent: MagmaAgent) => Promise<void> | void;
    schedule: string;
    options?: {
        timezone?: string;
    };
    name?: string;
}

declare const MagmaMiddlewareTriggers: readonly ["onCompletion", "preCompletion", "onToolExecution", "preToolExecution", "onMainFinish"];
type MagmaMiddlewareTriggerType = (typeof MagmaMiddlewareTriggers)[number];
type MagmaMiddlewareReturnType<T extends MagmaMiddlewareTriggerType> = T extends 'preCompletion' ? string | void : T extends 'onCompletion' ? string | void : T extends 'preToolExecution' ? MagmaToolCall | void : T extends 'onToolExecution' ? MagmaToolResult | void : T extends 'onMainFinish' ? string | void : never;
type MagmaMiddlewareParamType<T extends MagmaMiddlewareTriggerType> = T extends 'preToolExecution' ? MagmaToolCall : T extends 'onToolExecution' ? MagmaToolResult : T extends 'preCompletion' ? string : T extends 'onCompletion' ? string : T extends 'onMainFinish' ? string : never;
type MagmaMiddleware = {
    trigger: MagmaMiddlewareTriggerType;
    action: (message: MagmaMiddlewareParamType<MagmaMiddlewareTriggerType>, agent: MagmaAgent) => Promise<MagmaMiddlewareReturnType<MagmaMiddlewareTriggerType>> | MagmaMiddlewareReturnType<MagmaMiddlewareTriggerType>;
    name: string;
    critical?: boolean;
    order?: number;
    id: string;
};

type MagmaToolParamType = 'string' | 'number' | 'object' | 'boolean' | 'array';
type MagmaToolObjectParam = {
    type: 'object';
    description?: string;
    properties: (MagmaToolParam & {
        key: string;
        required?: boolean;
    })[];
};
type MagmaToolArrayParam = {
    type: 'array';
    description?: string;
    items: MagmaToolParam;
    limit?: number;
};
type MagmaToolStringParam = {
    type: 'string';
    description?: string;
    enum?: string[];
};
type MagmaToolNumberParam = {
    type: 'number';
    description?: string;
    enum?: number[];
};
type MagmaToolBooleanParam = {
    type: 'boolean';
    description?: string;
};
type MagmaToolParam = MagmaToolObjectParam | MagmaToolArrayParam | MagmaToolStringParam | MagmaToolNumberParam | MagmaToolBooleanParam;
type MagmaToolReturnType = string | Record<string, any> | void;
type MagmaToolTarget = (call: MagmaToolCall, agent: MagmaAgent) => MagmaToolReturnType | Promise<MagmaToolReturnType>;
type MagmaTool = {
    name: string;
    description: string;
    params: (MagmaToolParam & {
        key: string;
        required?: boolean;
    })[];
    target: MagmaToolTarget;
    enabled: (agent: MagmaAgent) => boolean;
    cache?: boolean;
};

type MagmaUtilities = {
    tools: MagmaTool[];
    middleware: MagmaMiddleware[];
    hooks: MagmaHook[];
    jobs: MagmaJob[];
};

type MagmaCompletionStopReason = 'natural' | 'tool_call' | 'content_filter' | 'max_tokens' | 'unsupported' | 'unknown';
type MagmaCompletion = {
    message: MagmaAssistantMessage;
    provider: MagmaProvider;
    model: string;
    usage: MagmaUsage;
    stop_reason: MagmaCompletionStopReason;
};
type MagmaUsage = {
    input_tokens: number;
    output_tokens: number;
    cache_write_tokens: number;
    cache_read_tokens: number;
};
type MagmaImageType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/url';
type MagmaImage = {
    data: string;
    type: MagmaImageType;
};
type MagmaMessageType = MagmaSystemMessageType | MagmaAssistantMessageType | MagmaUserMessageType;
type MagmaSystemMessageType = {
    id?: string | number;
    role: 'system';
    blocks?: MagmaContentBlock[];
    content?: string;
    cache?: boolean;
};
type MagmaTextBlock = {
    type: 'text';
    text: string;
};
type MagmaToolCallBlock = {
    type: 'tool_call';
    tool_call: MagmaToolCall;
};
type MagmaToolResultBlock = {
    type: 'tool_result';
    tool_result: MagmaToolResult;
};
type MagmaReasoningBlock = {
    type: 'reasoning';
    reasoning: string;
    redacted?: true;
    signature?: string;
};
type MagmaImageBlock = {
    type: 'image';
    image: MagmaImage;
};
type MagmaContentBlock = (MagmaTextBlock | MagmaToolCallBlock | MagmaToolResultBlock | MagmaReasoningBlock | MagmaImageBlock) & {
    cache?: boolean;
};
type MagmaUserMessageType = {
    id?: string | number;
    role: 'user';
    blocks?: MagmaContentBlock[];
    content?: string;
};
type MagmaAssistantMessageType = {
    id?: string | number;
    role: 'assistant';
    blocks?: MagmaContentBlock[];
    content?: string;
};
type MagmaToolCall = {
    id: string;
    fn_name: string;
    fn_args: Record<string, any>;
    fn_args_buffer?: string;
    error?: string;
};
type MagmaToolResult = {
    id: string;
    result: MagmaToolReturnType;
    error?: boolean;
    fn_name: string;
    call: MagmaToolCall;
};
type MagmaStreamChunk = {
    id: string;
    provider: MagmaProvider;
    model: string;
    delta: MagmaAssistantMessage;
    buffer: MagmaAssistantMessage;
    stop_reason: MagmaCompletionStopReason | undefined;
    usage: {
        input_tokens: number | null;
        output_tokens: number | null;
        cache_write_tokens: number | null;
        cache_read_tokens: number | null;
    };
};
declare class MagmaMessage {
    id?: string | number;
    role: MagmaMessageType['role'];
    blocks: MagmaContentBlock[];
    constructor({ role, content, blocks, id }: MagmaMessageType);
    getText(): string;
    getToolCalls(): MagmaToolCall[];
    getToolResults(): MagmaToolResult[];
    getReasoning(): string;
    getImages(): MagmaImage[];
    get content(): string;
}
declare class MagmaUserMessage extends MagmaMessage {
    role: 'user';
    constructor(magmaUserMessage: MagmaUserMessageType);
}
declare class MagmaAssistantMessage extends MagmaMessage {
    role: 'assistant';
    constructor(magmaAssistantMessage: MagmaAssistantMessageType);
}
declare class MagmaSystemMessage extends MagmaMessage {
    role: 'system';
    constructor(magmaSystemMessage: MagmaSystemMessageType);
}

type TraceEventType = 'completion' | 'middleware' | 'tool_execution';
type TraceEventPhase = 'start' | 'end';
type TraceEventStatus = 'abort' | 'error' | 'success';
type TraceEvent = {
    type: TraceEventType;
    phase: 'start';
    requestId: string;
    timestamp: number;
    data: Record<string, unknown>;
} | {
    type: TraceEventType;
    phase: 'end';
    status: TraceEventStatus;
    requestId: string;
    timestamp: number;
    data: Record<string, unknown>;
};
type TraceSpan = {
    type: TraceEventType;
    startEvent: TraceEvent;
    endEvent: TraceEvent;
};

export { type MagmaToolTarget as $, type MagmaContentBlock as A, type MagmaToolResult as B, type MagmaStreamChunk as C, MagmaUserMessage as D, MagmaAssistantMessage as E, MagmaSystemMessage as F, MagmaProviders as G, type MagmaProvider as H, type MagmaClient as I, type AnthropicModel as J, type GroqModel as K, type GoogleModel as L, type MagmaUtilities as M, type MagmaModel as N, type OpenAIModel as O, type OpenAIProviderConfig as P, type AnthropicProviderConfig as Q, type GroqProviderConfig as R, type GoogleProviderConfig as S, type TraceEvent as T, MagmaMiddlewareTriggers as U, type MagmaToolParamType as V, type MagmaToolObjectParam as W, type MagmaToolArrayParam as X, type MagmaToolStringParam as Y, type MagmaToolNumberParam as Z, type MagmaToolBooleanParam as _, type TraceEventType as a, type TraceEventPhase as a0, type TraceEventStatus as a1, type TraceSpan as a2, type MagmaHook as b, type MagmaJob as c, type MagmaMiddleware as d, type MagmaTool as e, MagmaMessage as f, MagmaAgent as g, type MagmaToolReturnType as h, type MagmaToolCall as i, type MagmaToolParam as j, type MagmaMiddlewareTriggerType as k, type MagmaMiddlewareReturnType as l, type MagmaMiddlewareParamType as m, type MagmaProviderConfig as n, type MagmaCompletionStopReason as o, type MagmaCompletion as p, type MagmaUsage as q, type MagmaImageType as r, type MagmaImage as s, type MagmaMessageType as t, type MagmaSystemMessageType as u, type MagmaTextBlock as v, type MagmaToolCallBlock as w, type MagmaToolResultBlock as x, type MagmaReasoningBlock as y, type MagmaImageBlock as z };