flatmachines 1.0.0__py3-none-any.whl

flatmachines/assets/flatagents-runtime.schema.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/SDKRuntimeWrapper",
+  "definitions": {
+    "SDKRuntimeWrapper": {
+      "type": "object",
+      "properties": {
+        "spec": {
+          "type": "string",
+          "const": "flatagents-runtime"
+        },
+        "spec_version": {
+          "type": "string",
+          "const": "1.0.0"
+        },
+        "execution_lock": {
+          "$ref": "#/definitions/ExecutionLock"
+        },
+        "persistence_backend": {
+          "$ref": "#/definitions/PersistenceBackend"
+        },
+        "result_backend": {
+          "$ref": "#/definitions/ResultBackend"
+        },
+        "execution_config": {
+          "$ref": "#/definitions/ExecutionConfig"
+        },
+        "machine_hooks": {
+          "$ref": "#/definitions/MachineHooks"
+        },
+        "llm_backend": {
+          "$ref": "#/definitions/LLMBackend"
+        },
+        "machine_invoker": {
+          "$ref": "#/definitions/MachineInvoker"
+        },
+        "backend_config": {
+          "$ref": "#/definitions/BackendConfig"
+        },
+        "machine_snapshot": {
+          "$ref": "#/definitions/MachineSnapshot"
+        },
+        "registration_backend": {
+          "$ref": "#/definitions/RegistrationBackend"
+        },
+        "work_backend": {
+          "$ref": "#/definitions/WorkBackend"
+        }
+      },
+      "required": [
+        "spec",
+        "spec_version"
+      ],
+      "additionalProperties": false,
+      "description": "Wrapper interface for JSON schema generation. Groups all runtime interfaces that SDKs must implement."
+    },
+    "ExecutionLock": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "FlatAgents Runtime Interface Spec ==================================\n\nThis file defines the runtime interfaces that SDKs MUST implement to be considered compliant. These are NOT configuration schemas (see flatagent.d.ts and flatmachine.d.ts for those).\n\nREQUIRED IMPLEMENTATIONS:\n-------------------------   - ExecutionLock: NoOpLock (MUST), LocalFileLock (SHOULD)   - PersistenceBackend: MemoryBackend (MUST), LocalFileBackend (SHOULD)   - ResultBackend: InMemoryResultBackend (MUST)   - ExecutionType: Default, Retry, Parallel, MDAPVoting (MUST)   - MachineHooks: Base interface (MUST)   - RegistrationBackend: SQLiteRegistrationBackend (MUST), MemoryRegistrationBackend (SHOULD)   - WorkBackend: SQLiteWorkBackend (MUST), MemoryWorkBackend (SHOULD)\n\nOPTIONAL IMPLEMENTATIONS:\n-------------------------   - Distributed backends (Redis, Postgres, etc.)   - LLMBackend (SDK may use native provider SDKs)\n\nEXECUTION LOCKING:\n------------------ Prevents concurrent execution of the same machine instance.\n\nSDKs MUST provide:   - NoOpLock: For when locking is handled externally or disabled\n\nSDKs SHOULD provide:   - LocalFileLock: For single-node deployments using fcntl/flock\n\nDistributed deployments should implement Redis/Consul/etcd locks.\n\nPERSISTENCE BACKEND:\n-------------------- Storage backend for machine checkpoints.\n\nSDKs MUST provide:   - MemoryBackend: For testing and ephemeral runs\n\nSDKs SHOULD provide:   - LocalFileBackend: For durable local storage with atomic writes\n\nRESULT BACKEND:\n--------------- Inter-machine communication via URI-addressed results.\n\nURI format: flatagents://{execution_id}/{path}   - path is typically \"result\" or \"checkpoint\"\n\nSDKs MUST provide:   - InMemoryResultBackend: For single-process execution\n\nEXECUTION TYPES:\n---------------- Execution strategy for agent calls.\n\nSDKs MUST implement all four types:   - default: Single call, no retry   - retry: Configurable backoffs with jitter   - parallel: Run N samples, return all successes   - mdap_voting: Multi-sample with consensus voting\n\nMACHINE HOOKS:\n-------------- Extension points for machine execution. All methods are optional and can be sync or async.\n\nSDKs SHOULD provide:   - WebhookHooks: Send events to HTTP endpoint   - CompositeHooks: Combine multiple hook implementations\n\nLLM BACKEND (OPTIONAL):\n----------------------- Abstraction over LLM providers.\n\nThis interface is OPTIONAL - SDKs may use provider SDKs directly. Useful for:   - Unified retry/monitoring across providers   - Provider-agnostic code   - Testing with mock backends\n\nMACHINE INVOKER:\n---------------- Interface for invoking peer machines. Used internally by FlatMachine for `machine:` and `launch:` states.\n\nBACKEND CONFIGURATION:\n---------------------- Backend configuration for machine settings.\n\nExample in YAML:   settings:     backends:       persistence: local       locking: none       results: memory"
+    },
+    "PersistenceBackend": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "ResultBackend": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "ExecutionConfig": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "default",
+            "retry",
+            "parallel",
+            "mdap_voting"
+          ]
+        },
+        "backoffs": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          }
+        },
+        "jitter": {
+          "type": "number"
+        },
+        "n_samples": {
+          "type": "number"
+        },
+        "k_margin": {
+          "type": "number"
+        },
+        "max_candidates": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false
+    },
+    "MachineHooks": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "LLMBackend": {
+      "type": "object",
+      "properties": {
+        "totalCost": {
+          "type": "number",
+          "description": "Total cost accumulated across all calls."
+        },
+        "totalApiCalls": {
+          "type": "number",
+          "description": "Total API calls made."
+        }
+      },
+      "required": [
+        "totalCost",
+        "totalApiCalls"
+      ],
+      "additionalProperties": false
+    },
+    "MachineInvoker": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "BackendConfig": {
+      "type": "object",
+      "properties": {
+        "persistence": {
+          "type": "string",
+          "enum": [
+            "memory",
+            "local",
+            "redis",
+            "postgres",
+            "s3"
+          ],
+          "description": "Checkpoint storage. Default: memory"
+        },
+        "locking": {
+          "type": "string",
+          "enum": [
+            "none",
+            "local",
+            "redis",
+            "consul"
+          ],
+          "description": "Execution locking. Default: none"
+        },
+        "results": {
+          "type": "string",
+          "enum": [
+            "memory",
+            "redis"
+          ],
+          "description": "Inter-machine results. Default: memory"
+        },
+        "registration": {
+          "type": "string",
+          "enum": [
+            "memory",
+            "sqlite",
+            "redis"
+          ],
+          "description": "Worker registration. Default: memory"
+        },
+        "work": {
+          "type": "string",
+          "enum": [
+            "memory",
+            "sqlite",
+            "redis"
+          ],
+          "description": "Work pool. Default: memory"
+        },
+        "sqlite_path": {
+          "type": "string",
+          "description": "Path for sqlite backends (registration and work share this)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "MachineSnapshot": {
+      "type": "object",
+      "properties": {
+        "execution_id": {
+          "type": "string"
+        },
+        "machine_name": {
+          "type": "string"
+        },
+        "spec_version": {
+          "type": "string"
+        },
+        "current_state": {
+          "type": "string"
+        },
+        "context": {
+          "type": "object"
+        },
+        "step": {
+          "type": "number"
+        },
+        "created_at": {
+          "type": "string"
+        },
+        "event": {
+          "type": "string"
+        },
+        "output": {
+          "type": "object"
+        },
+        "total_api_calls": {
+          "type": "number"
+        },
+        "total_cost": {
+          "type": "number"
+        },
+        "parent_execution_id": {
+          "type": "string"
+        },
+        "pending_launches": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LaunchIntent"
+          }
+        }
+      },
+      "required": [
+        "execution_id",
+        "machine_name",
+        "spec_version",
+        "current_state",
+        "context",
+        "step",
+        "created_at"
+      ],
+      "additionalProperties": false
+    },
+    "LaunchIntent": {
+      "type": "object",
+      "properties": {
+        "execution_id": {
+          "type": "string"
+        },
+        "machine": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object"
+        },
+        "launched": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "execution_id",
+        "machine",
+        "input",
+        "launched"
+      ],
+      "additionalProperties": false
+    },
+    "RegistrationBackend": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "REGISTRATION BACKEND:\n--------------------- Worker lifecycle management for distributed execution.\n\nSDKs MUST provide:   - SQLiteRegistrationBackend: For local deployments\n\nSDKs SHOULD provide:   - MemoryRegistrationBackend: For testing\n\nImplementation notes:   - Time units: Python reference SDK uses seconds for all interval values   - Stale threshold: SDKs SHOULD default to 2× heartbeat_interval if not specified"
+    },
+    "WorkBackend": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "WORK BACKEND:\n------------- Work distribution via named pools with atomic claim.\n\nSDKs MUST provide:   - SQLiteWorkBackend: For local deployments\n\nSDKs SHOULD provide:   - MemoryWorkBackend: For testing\n\nImplementation notes:   - Atomic claim: SDKs MUST ensure no two workers can claim the same job   - Test requirements: Include concurrent claim race condition tests"
+    }
+  }
+}

flatmachines/assets/flatagents-runtime.slim.d.ts

@@ -0,0 +1,187 @@
+export interface ExecutionLock {
+    acquire(key: string): Promise<boolean>;
+    release(key: string): Promise<void>;
+}
+export 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[]>;
+}
+export 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>;
+}
+export interface AgentResult {
+    output?: Record<string, any> | null;
+    content?: string | null;
+    raw?: any;
+    usage?: Record<string, any> | null;
+    cost?: number | null;
+    metadata?: Record<string, any> | null;
+}
+export interface AgentExecutor {
+    execute(input: Record<string, any>, context?: Record<string, any>): Promise<AgentResult>;
+    metadata?: Record<string, any>;
+}
+export interface ExecutionType {
+    execute(executor: AgentExecutor, input: Record<string, any>, context?: Record<string, any>): Promise<AgentResult>;
+}
+export interface ExecutionConfig {
+    type: "default" | "retry" | "parallel" | "mdap_voting";
+    backoffs?: number[];
+    jitter?: number;
+    n_samples?: number;
+    k_margin?: number;
+    max_candidates?: number;
+}
+export 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>>;
+}
+export interface LLMBackend {
+    totalCost: number;
+    totalApiCalls: number;
+    call(messages: Message[], options?: LLMOptions): Promise<string>;
+    callRaw(messages: Message[], options?: LLMOptions): Promise<any>;
+}
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface LLMOptions {
+    temperature?: number;
+    max_tokens?: number;
+    tools?: ToolDefinition[];
+    response_format?: {
+        type: "json_object";
+    } | {
+        type: "text";
+    };
+}
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, any>;
+    };
+}
+export interface MachineInvoker {
+    invoke(machineName: string, input: Record<string, any>, options?: {
+        timeout?: number;
+    }): Promise<Record<string, any>>;
+    launch(machineName: string, input: Record<string, any>): Promise<string>;
+}
+export 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[];
+}
+export interface LaunchIntent {
+    execution_id: string;
+    machine: string;
+    input: Record<string, any>;
+    launched: boolean;
+}
+export interface RegistrationBackend {
+    register(worker: WorkerRegistration): Promise<WorkerRecord>;
+    heartbeat(worker_id: string, metadata?: Record<string, any>): Promise<void>;
+    updateStatus(worker_id: string, status: string): Promise<void>;
+    get(worker_id: string): Promise<WorkerRecord | null>;
+    list(filter?: WorkerFilter): Promise<WorkerRecord[]>;
+}
+export interface WorkerRegistration {
+    worker_id: string;
+    host?: string;
+    pid?: number;
+    capabilities?: string[];
+    pool_id?: string;
+    started_at: string;
+}
+export interface WorkerRecord extends WorkerRegistration {
+    status: string;
+    last_heartbeat: string;
+    current_task_id?: string;
+}
+export interface WorkerFilter {
+    status?: string | string[];
+    capability?: string;
+    pool_id?: string;
+    stale_threshold_seconds?: number;
+}
+export interface WorkBackend {
+    pool(name: string): WorkPool;
+}
+export interface WorkPool {
+    push(item: any, options?: {
+        max_retries?: number;
+    }): Promise<string>;
+    claim(worker_id: string): Promise<WorkItem | null>;
+    complete(item_id: string, result?: any): Promise<void>;
+    fail(item_id: string, error?: string): Promise<void>;
+    size(): Promise<number>;
+    releaseByWorker(worker_id: string): Promise<number>;
+}
+export interface WorkItem {
+    id: string;
+    data: any;
+    claimed_by?: string;
+    claimed_at?: string;
+    attempts: number;
+    max_retries: number;
+}
+export interface BackendConfig {
+    persistence?: "memory" | "local" | "redis" | "postgres" | "s3";
+    locking?: "none" | "local" | "redis" | "consul";
+    results?: "memory" | "redis";
+    registration?: "memory" | "sqlite" | "redis";
+    work?: "memory" | "sqlite" | "redis";
+    sqlite_path?: string;
+}
+export const SPEC_VERSION = "1.0.0";
+export interface SDKRuntimeWrapper {
+    spec: "flatagents-runtime";
+    spec_version: typeof SPEC_VERSION;
+    execution_lock?: ExecutionLock;
+    persistence_backend?: PersistenceBackend;
+    result_backend?: ResultBackend;
+    execution_config?: ExecutionConfig;
+    machine_hooks?: MachineHooks;
+    llm_backend?: LLMBackend;
+    machine_invoker?: MachineInvoker;
+    backend_config?: BackendConfig;
+    machine_snapshot?: MachineSnapshot;
+    registration_backend?: RegistrationBackend;
+    work_backend?: WorkBackend;
+}