flatmachines 1.0.0__py3-none-any.whl

flatmachines/adapters/pi_agent_bridge.py

@@ -0,0 +1,127 @@
+"""pi-mono adapter using a Node.js runner (cross-runtime bridge)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from typing import Any, Dict, Optional
+
+from ..agents import AgentAdapter, AgentAdapterContext, AgentExecutor, AgentRef, AgentResult
+
+
+class PiAgentBridgeExecutor(AgentExecutor):
+    def __init__(
+        self,
+        ref: str,
+        config: Optional[Dict[str, Any]],
+        runner_path: str,
+        node_path: str,
+        cwd: str,
+        env: Dict[str, str],
+        timeout: Optional[float],
+    ):
+        self._ref = ref
+        self._config = config or {}
+        self._runner_path = runner_path
+        self._node_path = node_path
+        self._cwd = cwd
+        self._env = env
+        self._timeout = timeout
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        return {}
+
+    async def execute(
+        self,
+        input_data: Dict[str, Any],
+        context: Optional[Dict[str, Any]] = None,
+    ) -> AgentResult:
+        request = {
+            "ref": self._ref,
+            "config": self._config,
+            "input": input_data,
+            "context": context or {},
+        }
+        payload = json.dumps(request)
+
+        proc = await asyncio.create_subprocess_exec(
+            self._node_path,
+            self._runner_path,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self._cwd,
+            env=self._env,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(payload.encode()), timeout=self._timeout)
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            raise TimeoutError("pi-agent runner timed out")
+
+        if proc.returncode != 0:
+            raise RuntimeError(
+                f"pi-agent runner failed ({proc.returncode}): {stderr.decode().strip()}"
+            )
+
+        if not stdout:
+            return AgentResult()
+
+        try:
+            result = json.loads(stdout.decode())
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON from pi-agent runner: {stdout.decode()}") from exc
+
+        return AgentResult(
+            output=result.get("output"),
+            content=result.get("content"),
+            raw=result.get("raw"),
+            usage=result.get("usage"),
+            cost=result.get("cost"),
+            metadata=result.get("metadata"),
+        )
+
+
+class PiAgentBridgeAdapter(AgentAdapter):
+    type_name = "pi-agent"
+
+    def create_executor(
+        self,
+        *,
+        agent_name: str,
+        agent_ref: AgentRef,
+        context: AgentAdapterContext,
+    ) -> AgentExecutor:
+        if not agent_ref.ref:
+            raise ValueError(f"pi-agent reference missing ref for agent '{agent_name}'")
+
+        settings = context.settings.get("agent_runners", {}).get("pi_agent", {})
+        config = agent_ref.config or {}
+
+        runner_path = config.get("runner") or settings.get("runner")
+        if not runner_path:
+            runner_path = os.path.join(os.path.dirname(__file__), "pi_agent_runner.mjs")
+        elif not os.path.isabs(runner_path):
+            runner_path = os.path.join(context.config_dir, runner_path)
+
+        node_path = config.get("node") or settings.get("node") or "node"
+        timeout = config.get("timeout") or settings.get("timeout")
+        cwd = config.get("cwd") or settings.get("cwd") or context.config_dir
+
+        env = dict(os.environ)
+        env.update(settings.get("env", {}) if isinstance(settings.get("env"), dict) else {})
+        env.update(config.get("env", {}) if isinstance(config.get("env"), dict) else {})
+
+        return PiAgentBridgeExecutor(
+            ref=agent_ref.ref,
+            config=config.get("agent_config") or config.get("config") or {},
+            runner_path=runner_path,
+            node_path=node_path,
+            cwd=cwd,
+            env=env,
+            timeout=timeout,
+        )

flatmachines/adapters/pi_agent_runner.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "url";
+import { resolve } from "path";
+import process from "process";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+function parseRef(ref) {
+  if (!ref) {
+    throw new Error("Missing ref for pi-agent runner");
+  }
+  const [moduleRef, exportName] = ref.split("#");
+  return { moduleRef, exportName: exportName || "buildAgent" };
+}
+
+async function loadFactory(moduleRef, exportName) {
+  const url = moduleRef.startsWith(".") || moduleRef.startsWith("/")
+    ? pathToFileURL(resolve(moduleRef)).href
+    : moduleRef;
+  const mod = await import(url);
+  const factory = mod[exportName] || mod.default;
+  if (!factory) {
+    throw new Error(`Factory '${exportName}' not found in ${moduleRef}`);
+  }
+  return factory;
+}
+
+function extractText(content) {
+  if (!content) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (part.type === "text") return part.text || "";
+        return "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+async function run() {
+  const raw = await readStdin();
+  if (!raw) {
+    throw new Error("No input provided to pi-agent runner");
+  }
+  const request = JSON.parse(raw);
+  const { ref, config, input } = request;
+  const { moduleRef, exportName } = parseRef(ref);
+
+  const factory = await loadFactory(moduleRef, exportName);
+  const agent = await factory(config || {});
+
+  if (!agent || typeof agent.prompt !== "function") {
+    throw new Error("Factory did not return a pi-mono Agent instance");
+  }
+
+  const payload = input || {};
+
+  if (payload.messages) {
+    await agent.prompt(payload.messages);
+  } else if (payload.message) {
+    await agent.prompt(payload.message);
+  } else if (payload.task || payload.prompt) {
+    const task = payload.task || payload.prompt;
+    const images = payload.images || undefined;
+    await agent.prompt(task, images);
+  } else {
+    throw new Error("pi-agent input requires task/prompt or message(s)");
+  }
+
+  const messages = agent.state?.messages || [];
+  const assistant = [...messages].reverse().find((msg) => msg.role === "assistant");
+  const content = assistant ? extractText(assistant.content) : "";
+  const usage = assistant?.usage || null;
+  const cost = usage?.cost?.total ?? null;
+
+  const response = {
+    output: { content },
+    content,
+    usage,
+    cost,
+    raw: { messages },
+  };
+
+  process.stdout.write(JSON.stringify(response));
+}
+
+run().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

flatmachines/adapters/smolagents.py

@@ -0,0 +1,125 @@
+"""smolagents adapter for FlatMachines."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import importlib.util
+import os
+from typing import Any, Dict, Optional, Tuple
+
+from ..agents import AgentAdapter, AgentAdapterContext, AgentExecutor, AgentRef, AgentResult
+
+try:
+    from smolagents.agents import MultiStepAgent, RunResult
+except ImportError as exc:  # pragma: no cover - optional dependency
+    raise ImportError("smolagents is required for SmolagentsAdapter") from exc
+
+
+class SmolagentsExecutor(AgentExecutor):
+    def __init__(self, agent: MultiStepAgent, default_kwargs: Optional[Dict[str, Any]] = None):
+        self._agent = agent
+        self._default_kwargs = default_kwargs or {}
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        return {}
+
+    async def execute(
+        self,
+        input_data: Dict[str, Any],
+        context: Optional[Dict[str, Any]] = None,
+    ) -> AgentResult:
+        task = input_data.get("task") or input_data.get("prompt")
+        if task is None:
+            raise ValueError("smolagents adapter requires input.task or input.prompt")
+
+        run_kwargs = dict(self._default_kwargs)
+        additional_args = input_data.get("additional_args")
+        if additional_args is not None:
+            run_kwargs["additional_args"] = additional_args
+
+        if input_data.get("max_steps") is not None:
+            run_kwargs["max_steps"] = input_data["max_steps"]
+
+        if input_data.get("return_full_result") is not None:
+            run_kwargs["return_full_result"] = input_data["return_full_result"]
+        else:
+            run_kwargs.setdefault("return_full_result", True)
+
+        result = await asyncio.to_thread(self._agent.run, task, **run_kwargs)
+
+        if isinstance(result, RunResult):
+            output = result.output
+            usage = result.token_usage.dict() if result.token_usage is not None else None
+            content = None
+            if output is None:
+                content = None
+            elif isinstance(output, dict):
+                content = output.get("content") if isinstance(output.get("content"), str) else None
+            else:
+                content = str(output)
+                output = {"content": content}
+
+            return AgentResult(
+                output=output if isinstance(output, dict) else None,
+                content=content,
+                raw=result,
+                usage=usage,
+            )
+
+        if isinstance(result, dict):
+            return AgentResult(output=result, raw=result)
+
+        content = None if result is None else str(result)
+        return AgentResult(output={"content": content} if content is not None else None, content=content, raw=result)
+
+
+class SmolagentsAdapter(AgentAdapter):
+    type_name = "smolagents"
+
+    def create_executor(
+        self,
+        *,
+        agent_name: str,
+        agent_ref: AgentRef,
+        context: AgentAdapterContext,
+    ) -> AgentExecutor:
+        if agent_ref.ref:
+            factory = _load_factory(agent_ref.ref, context.config_dir)
+            kwargs = agent_ref.config or {}
+            agent = factory(**kwargs)
+            if not isinstance(agent, MultiStepAgent):
+                raise TypeError("smolagents factory did not return MultiStepAgent")
+            return SmolagentsExecutor(agent)
+
+        raise ValueError(f"smolagents reference missing ref for agent '{agent_name}'")
+
+
+def _parse_ref(ref: str) -> Tuple[str, str]:
+    if "#" in ref:
+        module_ref, factory_name = ref.split("#", 1)
+    else:
+        module_ref, factory_name = ref, "build_agent"
+    return module_ref, factory_name
+
+
+def _load_factory(ref: str, config_dir: str):
+    module_ref, factory_name = _parse_ref(ref)
+
+    if module_ref.endswith(".py") or module_ref.startswith(".") or "/" in module_ref:
+        module_path = module_ref
+        if not os.path.isabs(module_path):
+            module_path = os.path.join(config_dir, module_path)
+        spec = importlib.util.spec_from_file_location("smolagents_factory", module_path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Unable to load smolagents factory from {module_path}")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    else:
+        module = importlib.import_module(module_ref)
+
+    factory = getattr(module, factory_name, None)
+    if factory is None:
+        raise AttributeError(f"Factory '{factory_name}' not found in {module_ref}")
+    return factory

flatmachines/agents.py

@@ -0,0 +1,144 @@
+"""Agent executor interfaces and adapter registry for FlatMachines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Optional, Protocol
+
+
+@dataclass
+class AgentResult:
+    """Normalized result from an agent execution."""
+
+    output: Optional[Dict[str, Any]] = None
+    content: Optional[str] = None
+    raw: Any = None
+    usage: Optional[Dict[str, Any]] = None
+    cost: Optional[float] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def output_payload(self) -> Dict[str, Any]:
+        if self.output is not None:
+            return self.output
+        if self.content is not None:
+            return {"content": self.content}
+        return {}
+
+
+class AgentExecutor(Protocol):
+    """Protocol for running a single agent call."""
+
+    async def execute(
+        self,
+        input_data: Dict[str, Any],
+        context: Optional[Dict[str, Any]] = None,
+    ) -> AgentResult:
+        ...
+
+    @property
+    def metadata(self) -> Dict[str, Any]:  # Optional metadata for execution strategies
+        ...
+
+
+@dataclass
+class AgentRef:
+    """Normalized agent reference for adapter resolution."""
+
+    type: str
+    ref: Optional[str] = None
+    config: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class AgentAdapterContext:
+    config_dir: str
+    settings: Dict[str, Any]
+    machine_name: str
+    profiles_file: Optional[str] = None
+    profiles_dict: Optional[Dict[str, Any]] = None
+
+
+class AgentAdapter(Protocol):
+    """Adapter interface used to build agent executors."""
+
+    type_name: str
+
+    def create_executor(
+        self,
+        *,
+        agent_name: str,
+        agent_ref: AgentRef,
+        context: AgentAdapterContext,
+    ) -> AgentExecutor:
+        ...
+
+
+class AgentAdapterRegistry:
+    """Registry mapping adapter type names to adapter instances."""
+
+    def __init__(self, adapters: Optional[Iterable[AgentAdapter]] = None):
+        self._adapters: Dict[str, AgentAdapter] = {}
+        if adapters:
+            for adapter in adapters:
+                self.register(adapter)
+
+    def register(self, adapter: AgentAdapter) -> None:
+        self._adapters[adapter.type_name] = adapter
+
+    def get(self, type_name: str) -> AgentAdapter:
+        if type_name not in self._adapters:
+            raise KeyError(f"No agent adapter registered for type '{type_name}'")
+        return self._adapters[type_name]
+
+    def create_executor(
+        self,
+        *,
+        agent_name: str,
+        agent_ref: AgentRef,
+        context: AgentAdapterContext,
+    ) -> AgentExecutor:
+        adapter = self.get(agent_ref.type)
+        return adapter.create_executor(
+            agent_name=agent_name,
+            agent_ref=agent_ref,
+            context=context,
+        )
+
+
+DEFAULT_AGENT_TYPE = "flatagent"
+
+
+def normalize_agent_ref(raw_ref: Any) -> AgentRef:
+    """Normalize agent reference into AgentRef.
+
+    Backward compatibility:
+      - string -> type=flatagent, ref=string
+      - dict with spec: flatagent -> type=flatagent, config=dict
+    """
+    if isinstance(raw_ref, str):
+        return AgentRef(type=DEFAULT_AGENT_TYPE, ref=raw_ref)
+
+    if isinstance(raw_ref, dict):
+        if "type" in raw_ref:
+            return AgentRef(
+                type=raw_ref["type"],
+                ref=raw_ref.get("ref"),
+                config=raw_ref.get("config"),
+            )
+
+        if raw_ref.get("spec") == "flatagent":
+            return AgentRef(type=DEFAULT_AGENT_TYPE, config=raw_ref)
+
+    raise ValueError(
+        "Invalid agent reference. Expected string path or {type, ref/config}."
+    )
+
+
+def coerce_agent_result(value: Any) -> AgentResult:
+    if isinstance(value, AgentResult):
+        return value
+    if isinstance(value, dict):
+        return AgentResult(output=value, raw=value)
+    if value is None:
+        return AgentResult()
+    return AgentResult(content=str(value), raw=value)

flatmachines/assets/MACHINES.md

@@ -0,0 +1,141 @@
+# FlatAgents + FlatMachines Reference
+
+> **Target: <1000 tokens.** LLM-optimized. See `flatagent.d.ts`, `flatmachine.d.ts`, `profiles.d.ts` for schemas.
+>
+> **Versioning:** All specs and SDKs use lockstep versioning.
+
+## Concepts
+
+**FlatAgent**: Single LLM call. Model + prompts + output schema. No orchestration.
+**FlatMachine**: State machine orchestrating agents. States, transitions, conditions, loops, error handling.
+
+| Need | Use |
+|------|-----|
+| Single LLM call | FlatAgent |
+| Multi-step/branching/retry/errors | FlatMachine |
+| Parallel execution | `machine: [a, b, c]` |
+| Dynamic parallelism | `foreach` |
+| Background tasks | `launch` |
+
+## Model Profiles
+
+```yaml
+# profiles.yml — agents reference by name
+spec: flatprofiles
+spec_version: "0.10.0"
+data:
+  model_profiles:
+    fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }
+    smart: { provider: anthropic, name: claude-3-opus-20240229 }
+  default: fast        # Fallback
+  # override: smart    # Force all
+```
+
+Agent model field: `"fast"` | `{ profile: "fast", temperature: 0.9 }` | `{ provider: x, name: y }`
+Resolution: default → profile → overrides → override
+
+## Agent References
+
+`data.agents` values may be:
+- String path to a flatagent config
+- Inline flatagent config (`spec: flatagent`)
+- Typed adapter ref: `{ type: "flatagent" | "smolagents" | "pi-agent", ref?: "...", config?: {...} }`
+
+## State Fields
+
+| Field | Purpose |
+|-------|---------|
+| `type` | `initial` (entry) / `final` (exit+output) |
+| `agent` | Agent to call |
+| `machine` | Machine(s) — string or `[array]` for parallel |
+| `foreach` | Array expr for dynamic parallelism (`as`: item var, `key`: result key) |
+| `launch` / `launch_input` | Fire-and-forget machine(s) |
+| `input` | Map input to agent/machine |
+| `output_to_context` | Map `output.*` to `context.*` |
+| `execution` | `{ type: retry, backoffs: [2,8,16], jitter: 0.1 }` |
+| `on_error` | State name or `{ default: x, ErrorType: y }` |
+| `transitions` | `[{ condition: "expr", to: state }, { to: default }]` |
+| `mode` | `settled` (all) / `any` (first) for parallel |
+| `timeout` | Seconds (0=forever) |
+
+## Patterns
+
+**Execution types**: `default` | `retry` (backoffs, jitter) | `parallel` (n_samples) | `mdap_voting` (k_margin, max_candidates)
+
+**Transitions**: `condition: "context.score >= 8"` with `to: state`. Last without condition = default.
+
+**Loops**: Transition `to: same_state`. Machine has `max_steps` safety.
+
+**Errors**: `on_error: state` or per-type. Context gets `last_error`, `last_error_type`.
+
+**Parallel machines**:
+```yaml
+machine: [review_a, review_b]  # Results keyed by name
+mode: settled  # or "any"
+```
+
+**Foreach**:
+```yaml
+foreach: "{{ context.items }}"
+as: item
+machine: processor
+```
+
+**Launch** (fire-and-forget):
+```yaml
+launch: background_task
+launch_input: { data: "{{ context.data }}" }
+```
+
+## Distributed Worker Pattern
+
+Use hook actions (e.g., `DistributedWorkerHooks`) with a `RegistrationBackend` + `WorkBackend` to build worker pools.
+
+**Core machines**
+- **Checker**: `get_pool_state` → `calculate_spawn` → `spawn_workers`
+- **Worker**: `register_worker` → `claim_job` → process → `complete_job`/`fail_job` → `deregister_worker`
+- **Reaper**: `list_stale_workers` → `reap_stale_workers`
+
+`spawn_workers` expects `worker_config_path` in context (or override hooks to resolve it). Custom queues can compose the base hooks and add actions.
+
+```yaml
+context:
+  worker_config_path: "./job_worker.yml"
+states:
+  check_state: { action: get_pool_state }
+  calculate_spawn: { action: calculate_spawn }
+  spawn_workers: { action: spawn_workers }
+```
+
+See `sdk/examples/distributed_worker/` for a full example.
+
+## Context Variables
+
+`context.*` (all states), `input.*` (initial), `output.*` (in output_to_context), `item`/`as` (foreach)
+
+## Hooks
+
+`on_machine_start`, `on_machine_end`, `on_state_enter`, `on_state_exit`, `on_transition`, `on_error`, `on_action`
+
+```python
+class MyHooks(MachineHooks):
+    def on_action(self, action: str, context: dict) -> dict:
+        if action == "fetch": context["data"] = api_call()
+        return context
+```
+
+## Persistence
+
+```yaml
+persistence: { enabled: true, backend: local }  # local | memory
+```
+Resume: `machine.execute(resume_from=execution_id)`
+
+## SDKs
+
+### Python SDKs
+- **flatagents** (agents): `pip install flatagents[litellm]`
+- **flatmachines** (orchestration): `pip install flatmachines[flatagents]`
+
+### JavaScript SDK
+A single JS SDK lives under [`sdk/js`](./sdk/js). It follows the same specs but is not yet split into separate FlatAgents/FlatMachines packages.

flatmachines/assets/README.md

@@ -0,0 +1,11 @@
+# Specification Static Assets
+
+**IMPORTANT: The canonical specs are in the repo root.**
+
+* `*.d.ts` - copied from canonical spec at repo.
+* `*.slim.d.ts` - No comments, less context.
+* `*.schema.json` - Automated json conversion.
+
+These assets are included here for easy availability for machines or to copy to SDKs.
+
+It is recommended to directly regenerate these assets in your sdk release with `/scripts/generate-spec-assets.sh`