flatmachines 1.0.0__py3-none-any.whl

flatmachines/assets/profiles.d.ts

@@ -0,0 +1,140 @@
+/**
+ * FlatAgents Model Profiles Schema
+ * =================================
+ *
+ * Model profiles provide reusable model configurations that agents can reference
+ * by name. This enables centralized model management and easy switching between
+ * configurations (e.g., development vs production, fast vs quality).
+ *
+ * STRUCTURE:
+ * ----------
+ * spec           - Fixed string "flatprofiles"
+ * spec_version   - Semver string
+ * data           - Profile definitions and settings
+ * metadata       - Extensibility layer
+ *
+ * DERIVED SCHEMAS:
+ * ----------------
+ * This file (/profiles.d.ts) is the SOURCE OF TRUTH for all profile schemas.
+ * Other schemas (JSON Schema, etc.) are DERIVED from this file using scripts.
+ * See: /scripts/generate-spec-assets.ts
+ *
+ * PROFILE RESOLUTION ORDER (low to high priority):
+ * ------------------------------------------------
+ * 1. default profile from profiles.yml (fallback when agent has no model config)
+ * 2. Named profile from agent's model: "profile-name"
+ * 3. Inline overrides from agent's model: { profile: "name", temperature: 0.5 }
+ * 4. override profile from profiles.yml (trumps all agent configs)
+ *
+ * AGENT USAGE:
+ * ------------
+ * String shorthand - profile lookup:
+ *
+ *   data:
+ *     model: "fast-cheap"
+ *
+ * Profile with overrides:
+ *
+ *   data:
+ *     model:
+ *       profile: "fast-cheap"
+ *       temperature: 0.9
+ *
+ * Inline config (no profile):
+ *
+ *   data:
+ *     model:
+ *       provider: cerebras
+ *       name: zai-glm-4.6
+ *       temperature: 0.6
+ *
+ * EXAMPLE CONFIGURATION:
+ * ----------------------
+ *
+ *   spec: flatprofiles
+ *   spec_version: "0.7.0"
+ *
+ *   data:
+ *     model_profiles:
+ *       fast-cheap:
+ *         provider: cerebras
+ *         name: zai-glm-4.6
+ *         temperature: 0.6
+ *         max_tokens: 2048
+ *
+ *       smart-expensive:
+ *         provider: anthropic
+ *         name: claude-3-opus-20240229
+ *         temperature: 0.3
+ *         max_tokens: 4096
+ *
+ *       local-dev:
+ *         provider: ollama
+ *         name: llama3
+ *         base_url: http://localhost:11434
+ *         temperature: 0.7
+ *
+ *       deterministic:
+ *         provider: openai
+ *         name: gpt-4-turbo
+ *         temperature: 0
+ *         seed: 42
+ *
+ *     default: fast-cheap
+ *     # override: smart-expensive
+ *
+ *   metadata:
+ *     description: "Model profiles for the project"
+ *
+ * PROFILESDATA FIELDS:
+ * --------------------
+ * model_profiles - Named model profiles, keyed by profile name
+ * default        - Default profile name, used when agent has no model config
+ * override       - Override profile name, trumps all agent model configs
+ *
+ * MODELPROFILECONFIG FIELDS:
+ * --------------------------
+ * Defines all parameters for an LLM model.
+ * name              - Model name (e.g., "gpt-4", "zai-glm-4.6", "claude-3-opus-20240229")
+ * provider          - Provider name (e.g., "openai", "anthropic", "cerebras", "ollama")
+ * temperature       - Sampling temperature (0.0 to 2.0)
+ * max_tokens        - Maximum tokens to generate
+ * top_p             - Nucleus sampling parameter (0.0 to 1.0)
+ * top_k             - Top-k sampling parameter
+ * frequency_penalty - Frequency penalty (-2.0 to 2.0)
+ * presence_penalty  - Presence penalty (-2.0 to 2.0)
+ * seed              - Random seed for reproducibility
+ * base_url          - Custom base URL for the API (e.g., for local models or proxies)
+ * stream            - Enable streaming responses (default: false)
+ */
+
+export const SPEC_VERSION = "1.0.0";
+
+export interface ProfilesWrapper {
+  spec: "flatprofiles";
+  spec_version: string;
+  data: ProfilesData;
+  metadata?: Record<string, any>;
+}
+
+export interface ProfilesData {
+  model_profiles: Record<string, ModelProfileConfig>;
+  default?: string;
+  override?: string;
+}
+
+export 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;
+  stream?: boolean;
+}
+
+export type FlatprofilesConfig = ProfilesWrapper;

flatmachines/assets/profiles.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/ProfilesWrapper",
+  "definitions": {
+    "ProfilesWrapper": {
+      "type": "object",
+      "properties": {
+        "spec": {
+          "type": "string",
+          "const": "flatprofiles"
+        },
+        "spec_version": {
+          "type": "string"
+        },
+        "data": {
+          "$ref": "#/definitions/ProfilesData"
+        },
+        "metadata": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "spec",
+        "spec_version",
+        "data"
+      ],
+      "additionalProperties": false
+    },
+    "ProfilesData": {
+      "type": "object",
+      "properties": {
+        "model_profiles": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/ModelProfileConfig"
+          }
+        },
+        "default": {
+          "type": "string"
+        },
+        "override": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "model_profiles"
+      ],
+      "additionalProperties": false
+    },
+    "ModelProfileConfig": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "provider": {
+          "type": "string"
+        },
+        "temperature": {
+          "type": "number"
+        },
+        "max_tokens": {
+          "type": "number"
+        },
+        "top_p": {
+          "type": "number"
+        },
+        "top_k": {
+          "type": "number"
+        },
+        "frequency_penalty": {
+          "type": "number"
+        },
+        "presence_penalty": {
+          "type": "number"
+        },
+        "seed": {
+          "type": "number"
+        },
+        "base_url": {
+          "type": "string"
+        },
+        "stream": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

flatmachines/assets/profiles.slim.d.ts

@@ -0,0 +1,26 @@
+export const SPEC_VERSION = "1.0.0";
+export interface ProfilesWrapper {
+    spec: "flatprofiles";
+    spec_version: string;
+    data: ProfilesData;
+    metadata?: Record<string, any>;
+}
+export interface ProfilesData {
+    model_profiles: Record<string, ModelProfileConfig>;
+    default?: string;
+    override?: string;
+}
+export 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;
+    stream?: boolean;
+}
+export type FlatprofilesConfig = ProfilesWrapper;

flatmachines/backends.py

@@ -0,0 +1,222 @@
+"""
+Result backends for FlatMachine inter-machine communication.
+
+Result backends handle the storage and retrieval of machine execution results,
+enabling machines to read outputs from peer machines they launched.
+
+URI Scheme: flatagents://{execution_id}/[checkpoint|result]
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, asdict
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+def make_uri(execution_id: str, path: str = "result") -> str:
+    """Generate a FlatAgents URI for a given execution and path.
+
+    Args:
+        execution_id: Unique execution identifier
+        path: URI path component (default: "result")
+
+    Returns:
+        URI string in format flatagents://{execution_id}/{path}
+    """
+    return f"flatagents://{execution_id}/{path}"
+
+
+def parse_uri(uri: str) -> tuple[str, str]:
+    """Parse a FlatAgents URI into execution_id and path.
+
+    Args:
+        uri: URI in format flatagents://{execution_id}/{path}
+
+    Returns:
+        Tuple of (execution_id, path)
+
+    Raises:
+        ValueError: If URI format is invalid
+    """
+    if not uri.startswith("flatagents://"):
+        raise ValueError(f"Invalid FlatAgents URI: {uri}")
+
+    rest = uri[len("flatagents://"):]
+    parts = rest.split("/", 1)
+
+    if len(parts) == 1:
+        return parts[0], "result"
+    return parts[0], parts[1]
+
+
+@dataclass
+class LaunchIntent:
+    """
+    Launch intent for outbox pattern.
+    Recorded in checkpoint before launching to ensure exactly-once semantics.
+    """
+    execution_id: str
+    machine: str
+    input: Dict[str, Any]
+    launched: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LaunchIntent":
+        return cls(**data)
+
+
+@runtime_checkable
+class ResultBackend(Protocol):
+    """
+    Protocol for result backends.
+
+    Result backends store and retrieve machine execution results,
+    enabling inter-machine communication.
+    """
+
+    async def write(self, uri: str, data: Any) -> None:
+        """Write data to a URI.
+
+        Args:
+            uri: FlatAgents URI (flatagents://{execution_id}/{path})
+            data: Data to store (will be serialized)
+        """
+        ...
+
+    async def read(self, uri: str, block: bool = True, timeout: Optional[float] = None) -> Any:
+        """Read data from a URI.
+
+        Args:
+            uri: FlatAgents URI
+            block: If True, wait for data to be available
+            timeout: Maximum seconds to wait (None = forever, only used if block=True)
+
+        Returns:
+            The stored data, or None if not found and block=False
+
+        Raises:
+            TimeoutError: If timeout expires while waiting
+        """
+        ...
+
+    async def exists(self, uri: str) -> bool:
+        """Check if data exists at a URI.
+
+        Args:
+            uri: FlatAgents URI
+
+        Returns:
+            True if data exists, False otherwise
+        """
+        ...
+
+    async def delete(self, uri: str) -> None:
+        """Delete data at a URI.
+
+        Args:
+            uri: FlatAgents URI
+        """
+        ...
+
+
+class InMemoryResultBackend:
+    """
+    In-memory result backend for local execution.
+
+    Stores results in memory with asyncio Event-based blocking reads.
+    Suitable for single-process execution where machines run in the same process.
+    """
+
+    def __init__(self):
+        self._store: Dict[str, Any] = {}
+        self._events: Dict[str, asyncio.Event] = {}
+        self._lock = asyncio.Lock()
+
+    def _get_key(self, uri: str) -> str:
+        """Convert URI to storage key."""
+        execution_id, path = parse_uri(uri)
+        return f"{execution_id}/{path}"
+
+    def _get_event(self, key: str) -> asyncio.Event:
+        """Get or create an event for a key."""
+        if key not in self._events:
+            self._events[key] = asyncio.Event()
+        return self._events[key]
+
+    async def write(self, uri: str, data: Any) -> None:
+        """Write data to a URI."""
+        key = self._get_key(uri)
+        async with self._lock:
+            self._store[key] = data
+            event = self._get_event(key)
+            event.set()
+        logger.debug(f"ResultBackend: wrote to {uri}")
+
+    async def read(self, uri: str, block: bool = True, timeout: Optional[float] = None) -> Any:
+        """Read data from a URI."""
+        key = self._get_key(uri)
+
+        if not block:
+            return self._store.get(key)
+
+        event = self._get_event(key)
+
+        # Check if already available
+        if key in self._store:
+            return self._store[key]
+
+        # Wait for data
+        try:
+            await asyncio.wait_for(event.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            raise TimeoutError(f"Timeout waiting for result at {uri}")
+
+        return self._store.get(key)
+
+    async def exists(self, uri: str) -> bool:
+        """Check if data exists at a URI."""
+        key = self._get_key(uri)
+        return key in self._store
+
+    async def delete(self, uri: str) -> None:
+        """Delete data at a URI."""
+        key = self._get_key(uri)
+        async with self._lock:
+            self._store.pop(key, None)
+            if key in self._events:
+                del self._events[key]
+
+
+# Singleton for shared in-memory backend
+_default_backend: Optional[InMemoryResultBackend] = None
+
+
+def get_default_result_backend() -> InMemoryResultBackend:
+    """Get the default shared in-memory result backend."""
+    global _default_backend
+    if _default_backend is None:
+        _default_backend = InMemoryResultBackend()
+    return _default_backend
+
+
+def reset_default_result_backend() -> None:
+    """Reset the default result backend (for testing)."""
+    global _default_backend
+    _default_backend = None
+
+
+__all__ = [
+    "ResultBackend",
+    "InMemoryResultBackend",
+    "LaunchIntent",
+    "make_uri",
+    "parse_uri",
+    "get_default_result_backend",
+    "reset_default_result_backend",
+]