@memgrafter/flatagents 0.8.0

package/dist/index.d.mts

@@ -0,0 +1,673 @@
+/**
+ * Model configuration for an agent.
+ * Can be inline config, profile reference, or profile with overrides.
+ */
+interface ModelConfig {
+    name: string;
+    provider?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    top_k?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    seed?: number;
+    base_url?: string;
+}
+/**
+ * Model config that references a profile with optional overrides.
+ */
+interface ProfiledModelConfig extends Partial<ModelConfig> {
+    profile: string;
+}
+/**
+ * Model profile configuration (used in profiles.yml).
+ */
+interface ModelProfileConfig {
+    name: string;
+    provider?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    top_k?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    seed?: number;
+    base_url?: string;
+}
+/**
+ * Profiles configuration (profiles.yml structure).
+ */
+interface ProfilesConfig {
+    spec: "flatprofiles";
+    spec_version: string;
+    data: {
+        model_profiles: Record<string, ModelProfileConfig>;
+        default?: string;
+        override?: string;
+    };
+    metadata?: Record<string, any>;
+}
+interface AgentConfig {
+    spec: "flatagent";
+    spec_version: string;
+    data: {
+        name?: string;
+        /**
+         * Model configuration.
+         * - String: Profile name lookup (e.g., "fast-cheap")
+         * - ModelConfig: Inline config with name, provider, etc.
+         * - ProfiledModelConfig: Profile reference with optional overrides
+         */
+        model: string | ModelConfig | ProfiledModelConfig;
+        system: string;
+        user: string;
+        instruction_suffix?: string;
+        output?: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+            required?: boolean;
+            items?: any;
+            properties?: any;
+        }>;
+        mcp?: {
+            servers: Record<string, MCPServer>;
+            tool_filter?: ToolFilter;
+            tool_prompt?: string;
+        };
+    };
+}
+interface MachineConfig {
+    spec: "flatmachine";
+    spec_version: string;
+    data: {
+        name?: string;
+        expression_engine?: "simple" | "cel";
+        context?: Record<string, any>;
+        agents?: Record<string, string>;
+        machines?: Record<string, string | MachineConfig | MachineWrapper | MachineReference>;
+        states: Record<string, State>;
+        settings?: {
+            max_steps?: number;
+            backends?: BackendConfig;
+            [key: string]: any;
+        };
+        persistence?: {
+            enabled: boolean;
+            backend: "local" | "memory" | "redis" | string;
+            checkpoint_on?: string[];
+            [key: string]: any;
+        };
+    };
+}
+interface State {
+    type?: "initial" | "final";
+    agent?: string;
+    machine?: string | string[] | MachineInput[];
+    action?: string;
+    execution?: {
+        type: "default" | "retry" | "parallel" | "mdap_voting";
+        backoffs?: number[];
+        jitter?: number;
+        n_samples?: number;
+        k_margin?: number;
+        max_candidates?: number;
+    };
+    input?: Record<string, any>;
+    output_to_context?: Record<string, any>;
+    output?: Record<string, any>;
+    transitions?: {
+        condition?: string;
+        to: string;
+    }[];
+    on_error?: string | Record<string, string>;
+    foreach?: string;
+    as?: string;
+    key?: string;
+    mode?: "settled" | "any";
+    timeout?: number;
+    launch?: string | string[];
+    launch_input?: Record<string, any>;
+    tool_loop?: boolean;
+    sampling?: "single" | "multi";
+}
+interface MachineSnapshot {
+    execution_id: string;
+    machine_name: string;
+    spec_version: string;
+    current_state: string;
+    context: Record<string, any>;
+    step: number;
+    created_at: string;
+    event?: string;
+    output?: Record<string, any>;
+    total_api_calls?: number;
+    total_cost?: number;
+    parent_execution_id?: string;
+    pending_launches?: LaunchIntent[];
+}
+interface LaunchIntent {
+    execution_id: string;
+    machine: string;
+    input: Record<string, any>;
+    launched: boolean;
+}
+interface MCPServer {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    serverUrl?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+interface ToolFilter {
+    allow?: string[];
+    deny?: string[];
+}
+interface ExecutionConfig {
+    type: "default" | "retry" | "parallel" | "mdap_voting";
+    backoffs?: number[];
+    jitter?: number;
+    n_samples?: number;
+    k_margin?: number;
+    max_candidates?: number;
+}
+interface ExecutionType {
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+interface MachineHooks {
+    onMachineStart?(context: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
+    onMachineEnd?(context: Record<string, any>, output: any): any | Promise<any>;
+    onStateEnter?(state: string, context: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
+    onStateExit?(state: string, context: Record<string, any>, output: any): any | Promise<any>;
+    onTransition?(from: string, to: string, context: Record<string, any>): string | Promise<string>;
+    onError?(state: string, error: Error, context: Record<string, any>): string | null | Promise<string | null>;
+    onAction?(action: string, context: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
+}
+interface PersistenceBackend {
+    save(key: string, snapshot: MachineSnapshot): Promise<void>;
+    load(key: string): Promise<MachineSnapshot | null>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+interface ResultBackend {
+    write(uri: string, data: any): Promise<void>;
+    read(uri: string, options?: {
+        block?: boolean;
+        timeout?: number;
+    }): Promise<any>;
+    exists(uri: string): Promise<boolean>;
+    delete(uri: string): Promise<void>;
+}
+interface MachineOptions {
+    config: MachineConfig | string;
+    hooks?: MachineHooks;
+    persistence?: PersistenceBackend;
+    resultBackend?: ResultBackend;
+    executionLock?: ExecutionLock;
+    configDir?: string;
+    executionId?: string;
+    parentExecutionId?: string;
+    /** Path to profiles.yml for model profile resolution */
+    profilesFile?: string;
+}
+interface MachineInput {
+    name: string;
+    input?: Record<string, any>;
+}
+interface MachineReference {
+    path?: string;
+    inline?: MachineConfig;
+}
+interface MachineWrapper {
+    spec: "flatmachine";
+    spec_version: string;
+    data: MachineConfig["data"];
+}
+interface BackendConfig {
+    persistence?: "memory" | "local" | "redis" | "postgres" | "s3";
+    locking?: "none" | "local" | "redis" | "consul";
+    results?: "memory" | "redis";
+}
+/**
+ * Prevents concurrent execution of the same machine instance.
+ * See flatagents-runtime.d.ts for spec.
+ */
+interface ExecutionLock {
+    acquire(key: string): Promise<boolean>;
+    release(key: string): Promise<void>;
+}
+
+/**
+ * LLM Backend Types
+ *
+ * Matches flatagents-runtime.d.ts specification.
+ * These types abstract over different LLM providers.
+ */
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface LLMOptions {
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    top_k?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    seed?: number;
+    tools?: ToolDefinition[];
+    response_format?: {
+        type: 'json_object';
+    } | {
+        type: 'text';
+    };
+}
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, any>;
+    };
+}
+/**
+ * Abstraction over LLM providers.
+ * See flatagents-runtime.d.ts for canonical definition.
+ */
+interface LLMBackend {
+    /** Total cost accumulated across all calls. */
+    totalCost: number;
+    /** Total API calls made. */
+    totalApiCalls: number;
+    /**
+     * Call LLM and return content string.
+     */
+    call(messages: Message[], options?: LLMOptions): Promise<string>;
+    /**
+     * Call LLM and return raw provider response.
+     */
+    callRaw(messages: Message[], options?: LLMOptions): Promise<any>;
+}
+/**
+ * Configuration for creating an LLM backend.
+ */
+interface LLMBackendConfig {
+    provider: string;
+    name: string;
+    apiKey?: string;
+    baseURL?: string;
+}
+
+/**
+ * VercelAIBackend - LLM backend using Vercel AI SDK
+ *
+ * Supports multiple providers through Vercel AI SDK:
+ * - OpenAI
+ * - Anthropic
+ * - Cerebras
+ * - OpenAI-compatible (Groq, Together, Fireworks, etc.)
+ */
+
+declare class VercelAIBackend implements LLMBackend {
+    totalCost: number;
+    totalApiCalls: number;
+    private model;
+    constructor(config: LLMBackendConfig);
+    private createModel;
+    call(messages: Message[], options?: LLMOptions): Promise<string>;
+    callRaw(messages: Message[], options?: LLMOptions): Promise<any>;
+}
+
+/**
+ * MockLLMBackend - Mock backend for testing
+ *
+ * Provides predictable responses for testing without hitting real APIs.
+ */
+
+interface MockResponse {
+    content: string;
+    raw?: any;
+}
+declare class MockLLMBackend implements LLMBackend {
+    totalCost: number;
+    totalApiCalls: number;
+    private responses;
+    private responseIndex;
+    private defaultResponse;
+    /**
+     * Create a mock backend with predefined responses.
+     *
+     * @param responses - Array of responses to return in order
+     * @param defaultResponse - Response to use when responses are exhausted
+     */
+    constructor(responses?: MockResponse[], defaultResponse?: MockResponse);
+    call(messages: Message[], options?: LLMOptions): Promise<string>;
+    callRaw(messages: Message[], options?: LLMOptions): Promise<any>;
+    /**
+     * Reset the response index to start from the beginning.
+     */
+    reset(): void;
+    /**
+     * Add responses to the queue.
+     */
+    addResponses(responses: MockResponse[]): void;
+}
+
+/**
+ * Options for constructing a FlatAgent with custom backends.
+ */
+interface AgentOptions {
+    /** Path to YAML config file or inline AgentConfig */
+    config: string | AgentConfig;
+    /** Custom LLM backend (if not provided, uses VercelAIBackend based on config) */
+    llmBackend?: LLMBackend;
+    /** Base directory for resolving relative paths */
+    configDir?: string;
+    /** Path to profiles.yml for model profile resolution */
+    profilesFile?: string;
+}
+declare class FlatAgent {
+    config: AgentConfig;
+    private mcpProvider?;
+    private llmBackend?;
+    private configDir;
+    private profilesFile?;
+    private resolvedModelConfig;
+    /**
+     * Create a FlatAgent.
+     *
+     * @param configOrOptions - Config path, config object, or AgentOptions
+     */
+    constructor(configOrOptions: AgentConfig | string | AgentOptions);
+    /**
+     * Get or create the LLM backend.
+     */
+    private getBackend;
+    call(input: Record<string, any>): Promise<{
+        content: string;
+        output: any;
+    }>;
+    private extractOutput;
+}
+
+declare class FlatMachine {
+    config: MachineConfig;
+    executionId: string;
+    private agents;
+    private context;
+    private input;
+    private hooks?;
+    private checkpointManager?;
+    private resultBackend?;
+    private executionLock;
+    private configDir;
+    private profilesFile?;
+    private checkpointEvents;
+    private parentExecutionId?;
+    private pendingLaunches;
+    private currentState?;
+    private currentStep;
+    constructor(options: MachineOptions);
+    execute(input?: Record<string, any>, resumeSnapshot?: MachineSnapshot): Promise<any>;
+    private executeInternal;
+    resume(executionId: string): Promise<any>;
+    private findInitialState;
+    private executeAgent;
+    private executeMachine;
+    private launchMachines;
+    private evaluateTransitions;
+    private checkpoint;
+    private render;
+    private renderDirectValue;
+    private resolvePath;
+    private shouldCheckpoint;
+    private createResultBackend;
+    private createExecutionLock;
+    private createSettingsPersistenceBackend;
+    private createPersistenceBackend;
+    private createAgent;
+    private createMachine;
+    private resolveMachineConfig;
+    private resolveMachinePath;
+    private resolveProfilesFile;
+    private getMachineName;
+    private makeResultUri;
+    private addPendingLaunch;
+    private markLaunched;
+    private clearPendingLaunch;
+    private resumePendingLaunches;
+    private launchAndWrite;
+    private normalizeMachineResult;
+    private invokeMachineSingle;
+    private launchFireAndForget;
+    private awaitWithMode;
+    private firstCompleted;
+    private withTimeout;
+    private pickFirstKeyedResult;
+}
+
+/**
+ * Model profile management for FlatAgents.
+ *
+ * Provides centralized model configuration through profiles.yml files.
+ * Profiles enable easy switching between model configurations (e.g., dev vs prod).
+ *
+ * Resolution order (low to high priority):
+ * 1. default profile (fallback)
+ * 2. Named profile from agent's model field
+ * 3. Inline overrides from agent's model field
+ * 4. override profile (trumps all)
+ */
+
+/**
+ * Manages model profiles from profiles.yml files.
+ *
+ * Resolution order (low to high priority):
+ * 1. default profile (fallback)
+ * 2. Named profile from agent's model field
+ * 3. Inline overrides from agent's model field
+ * 4. override profile (trumps all)
+ *
+ * @example
+ * ```typescript
+ * const manager = new ProfileManager("config/profiles.yml");
+ * const config = manager.resolveModelConfig("fast-cheap");
+ * console.log(config);
+ * // { provider: 'cerebras', name: 'zai-glm-4.6', temperature: 0.6 }
+ * ```
+ */
+declare class ProfileManager {
+    private profiles;
+    private defaultProfile;
+    private overrideProfile;
+    readonly profilesFile: string | undefined;
+    constructor(profilesFile?: string);
+    /**
+     * Get or create a ProfileManager for a directory.
+     * Caches instances by directory to avoid re-reading profiles.yml.
+     */
+    static getInstance(configDir: string): ProfileManager;
+    /**
+     * Clear cached ProfileManager instances.
+     */
+    static clearCache(): void;
+    private loadProfiles;
+    /**
+     * Get a profile by name.
+     */
+    getProfile(name: string): ModelProfileConfig | undefined;
+    /**
+     * Get all loaded profiles.
+     */
+    getProfiles(): Record<string, ModelProfileConfig>;
+    /**
+     * Get the default profile name.
+     */
+    getDefaultProfile(): string | undefined;
+    /**
+     * Get the override profile name.
+     */
+    getOverrideProfile(): string | undefined;
+    /**
+     * Resolve the final model configuration.
+     *
+     * Resolution order:
+     * 1. Start with default profile (if set)
+     * 2. Apply named profile (if agentModelConfig is string or has 'profile' key)
+     * 3. Merge inline overrides (if agentModelConfig is dict)
+     * 4. Apply override profile (trumps all)
+     *
+     * @param agentModelConfig - Agent's model config (string, object, or undefined)
+     * @returns Fully resolved model configuration
+     * @throws Error if a referenced profile is not found
+     */
+    resolveModelConfig(agentModelConfig: string | ModelConfig | undefined): ModelConfig;
+}
+/**
+ * Convenience function to resolve model configuration.
+ *
+ * @param agentModelConfig - Agent's model config (string, object, or undefined)
+ * @param configDir - Directory containing agent config (for profiles.yml lookup)
+ * @param profilesFile - Explicit path to profiles.yml (overrides auto-discovery)
+ * @returns Fully resolved model configuration
+ *
+ * @example
+ * ```typescript
+ * const config = resolveModelConfig("fast-cheap", "./config");
+ * console.log(config);
+ * // { provider: 'cerebras', name: 'zai-glm-4.6', temperature: 0.6 }
+ * ```
+ */
+declare function resolveModelConfig(agentModelConfig: string | ModelConfig | undefined, configDir: string, profilesFile?: string): ModelConfig;
+
+declare class DefaultExecution implements ExecutionType {
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+declare class RetryExecution implements ExecutionType {
+    private backoffs;
+    private jitter;
+    constructor(backoffs?: number[], jitter?: number);
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+declare class ParallelExecution implements ExecutionType {
+    private nSamples;
+    constructor(nSamples?: number);
+    execute<T>(fn: () => Promise<T>): Promise<any>;
+}
+declare class MDAPVotingExecution implements ExecutionType {
+    private kMargin;
+    private maxCandidates;
+    constructor(kMargin?: number, maxCandidates?: number);
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+declare function getExecutionType(config?: ExecutionConfig): ExecutionType;
+
+declare class WebhookHooks implements MachineHooks {
+    private url;
+    constructor(url: string);
+    private send;
+    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
+    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
+    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
+    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
+    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
+}
+declare class CompositeHooks implements MachineHooks {
+    private hooks;
+    constructor(hooks: MachineHooks[]);
+    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
+    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
+    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
+    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
+    onTransition(from: string, to: string, context: Record<string, any>): Promise<string>;
+    onError(state: string, error: Error, context: Record<string, any>): Promise<string | null>;
+    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
+}
+
+declare class MemoryBackend implements PersistenceBackend {
+    private store;
+    save(key: string, snapshot: MachineSnapshot): Promise<void>;
+    load(key: string): Promise<MachineSnapshot | null>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+declare class LocalFileBackend implements PersistenceBackend {
+    private dir;
+    constructor(dir?: string);
+    private ensureDir;
+    private getPath;
+    save(key: string, snapshot: MachineSnapshot): Promise<void>;
+    load(key: string): Promise<MachineSnapshot | null>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+}
+declare class CheckpointManager {
+    private backend;
+    constructor(backend: PersistenceBackend);
+    checkpoint(snapshot: MachineSnapshot): Promise<void>;
+    restore(executionId: string): Promise<MachineSnapshot | null>;
+}
+
+declare const inMemoryResultBackend: ResultBackend;
+
+declare class MCPToolProvider {
+    private clients;
+    connect(servers: Record<string, MCPServer>): Promise<void>;
+    listTools(filter?: ToolFilter): Promise<any[]>;
+    callTool(name: string, args: any): Promise<any>;
+    private matchesFilter;
+    private match;
+}
+
+declare function evaluate(expr: string, ctx: {
+    context: any;
+    input: any;
+    output: any;
+}): any;
+
+type TemplateAllowlist = {
+    filters?: string[];
+    tags?: string[];
+    patterns?: string[];
+};
+declare function setTemplateAllowlist(allowlist?: TemplateAllowlist | null): void;
+
+/**
+ * NoOpLock - Always acquires the lock.
+ * Use when locking is handled externally or disabled.
+ *
+ * Required by flatagents-runtime.d.ts spec.
+ */
+declare class NoOpLock implements ExecutionLock {
+    acquire(key: string): Promise<boolean>;
+    release(key: string): Promise<void>;
+}
+/**
+ * LocalFileLock - File-based locking for single-node deployments.
+ * Uses exclusive file creation to prevent concurrent execution.
+ *
+ * Recommended by flatagents-runtime.d.ts spec.
+ */
+declare class LocalFileLock implements ExecutionLock {
+    private lockDir;
+    private handles;
+    constructor(lockDir?: string);
+    private getLockPath;
+    private ensureDir;
+    acquire(key: string): Promise<boolean>;
+    release(key: string): Promise<void>;
+}
+
+export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type LLMBackend, type LLMBackendConfig, type LLMOptions, LocalFileBackend, LocalFileLock, type MCPServer, MCPToolProvider, MDAPVotingExecution, type MachineConfig, type MachineHooks, type MachineOptions, type MachineSnapshot, MemoryBackend, type Message, MockLLMBackend, type MockResponse, type ModelConfig, type ModelProfileConfig, NoOpLock, ParallelExecution, type PersistenceBackend, ProfileManager, type ProfiledModelConfig, type ProfilesConfig, type ResultBackend, RetryExecution, type State, type TemplateAllowlist, type ToolCall, type ToolDefinition, type ToolFilter, VercelAIBackend, WebhookHooks, evaluate, getExecutionType, inMemoryResultBackend, resolveModelConfig, setTemplateAllowlist };