@memgrafter/flatagents 0.10.0 → 2.1.0

package/MACHINES.md

@@ -22,7 +22,7 @@
 ```yaml
 # profiles.yml — agents reference by name
 spec: flatprofiles
-spec_version: "0.10.0"
+spec_version: "2.1.0"
 data:
   model_profiles:
     fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }
@@ -34,6 +34,13 @@ data:
 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 |
@@ -49,6 +56,7 @@ Resolution: default → profile → overrides → override
 | `on_error` | State name or `{ default: x, ErrorType: y }` |
 | `transitions` | `[{ condition: "expr", to: state }, { to: default }]` |
 | `mode` | `settled` (all) / `any` (first) for parallel |
+| `wait_for` | Channel to wait for external signal (Jinja2 template) |
 | `timeout` | Seconds (0=forever) |
 
 ## Patterns
@@ -80,6 +88,19 @@ launch: background_task
 launch_input: { data: "{{ context.data }}" }
 ```
 
+**Wait for signal** (checkpoint, exit, resume on signal):
+```yaml
+wait_for_approval:
+  wait_for: "approval/{{ context.task_id }}"
+  timeout: 86400
+  output_to_context:
+    approved: "{{ output.approved }}"
+  transitions:
+    - condition: "context.approved"
+      to: continue
+    - to: rejected
+```
+
 ## Distributed Worker Pattern
 
 Use hook actions (e.g., `DistributedWorkerHooks`) with a `RegistrationBackend` + `WorkBackend` to build worker pools.
@@ -102,6 +123,31 @@ states:
 
 See `sdk/examples/distributed_worker/` for a full example.
 
+## Signals & Triggers
+
+Machine pauses at `wait_for` state → checkpoints with `waiting_channel` → process exits. Nothing running.
+
+**Signal delivery**: External process writes signal → trigger fires → dispatcher resumes matching machines.
+
+```
+send("approval/task-001", {approved: true})
+  → SQLite INSERT + touch trigger file
+  → launchd/systemd starts dispatcher
+  → dispatcher queries checkpoints WHERE waiting_channel = "approval/task-001"
+  → resumes machine from checkpoint, signal data as output.*
+```
+
+**Channel semantics**:
+- Addressed: `"approval/{{ context.task_id }}"` → one waiter
+- Broadcast: `"quota/openai"` → N waiters (dispatcher controls limit)
+
+**10,000 waiting machines** = 10,000 rows in SQLite. Zero processes, zero memory.
+
+**Trigger backends**: `none` (polling), `file` (launchd/systemd — nothing running), `socket` (UDS, in-process).
+DynamoDB Streams is implicit (no trigger code needed).
+
+**Signal backends**: `memory` (testing), `sqlite` (local durable), `dynamodb` (AWS).
+
 ## Context Variables
 
 `context.*` (all states), `input.*` (initial), `output.*` (in output_to_context), `item`/`as` (foreach)
@@ -123,3 +169,12 @@ class MyHooks(MachineHooks):
 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.

package/README.md

@@ -2,7 +2,7 @@
 
 Define LLM agents in YAML. Run them anywhere.
 
-**For LLM/machine readers:** see [MACHINES.md](./MACHINES.md) for comprehensive reference.
+**For LLM/machine readers:** see [MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md) for comprehensive reference.
 
 ## Why?
 
@@ -35,19 +35,19 @@ Use FlatAgent alone for simple tasks. Use FlatMachine when you need multi-step w
 
 | Example | What it demonstrates |
 |---------|---------------------|
-| [helloworld](./sdk/examples/helloworld/python) | Minimal setup — single agent, single state machine |
-| [writer_critic](./sdk/examples/writer_critic/python) | Multi-agent loop — writer drafts, critic reviews, iterates |
-| [story_writer](./sdk/examples/story_writer/python) | Multi-step creative workflow with chapter generation |
-| [human-in-the-loop](./sdk/examples/human-in-the-loop/python) | Pause execution for human approval via hooks |
-| [error_handling](./sdk/examples/error_handling/python) | Error recovery and retry patterns at state machine level |
-| [dynamic_agent](./sdk/examples/dynamic_agent/python) | On-the-fly agent generation from runtime context |
-| [character_card](./sdk/examples/character_card/python) | Loading agent config from character card format |
-| [mdap](./sdk/examples/mdap/python) | MDAP voting execution — multi-sample consensus |
-| [gepa_self_optimizer](./sdk/examples/gepa_self_optimizer/python) | Self-optimizing prompts via reflection and critique |
-| [research_paper_analysis](./sdk/examples/research_paper_analysis/python) | Document analysis with structured extraction |
-| [multi_paper_synthesizer](./sdk/examples/multi_paper_synthesizer/python) | Cross-document synthesis with dynamic machine launching |
-| [support_triage_json](./sdk/examples/support_triage_json/python) | JSON input/output with classification pipeline |
-| [parallelism](./sdk/examples/parallelism/python) | Parallel machines, dynamic foreach, fire-and-forget launches |
+| [helloworld](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/helloworld/python) | Minimal setup — single agent, single state machine |
+| [writer_critic](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/writer_critic/python) | Multi-agent loop — writer drafts, critic reviews, iterates |
+| [story_writer](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/story_writer/python) | Multi-step creative workflow with chapter generation |
+| [human-in-the-loop](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/human-in-the-loop/python) | Pause execution for human approval via hooks |
+| [error_handling](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/error_handling/python) | Error recovery and retry patterns at state machine level |
+| [dynamic_agent](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/dynamic_agent/python) | On-the-fly agent generation from runtime context |
+| [character_card](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/character_card/python) | Loading agent config from character card format |
+| [mdap](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/mdap/python) | MDAP voting execution — multi-sample consensus |
+| [gepa_self_optimizer](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/gepa_self_optimizer/python) | Self-optimizing prompts via reflection and critique |
+| [research_paper_analysis](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/research_paper_analysis/python) | Document analysis with structured extraction |
+| [multi_paper_synthesizer](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/multi_paper_synthesizer/python) | Cross-document synthesis with dynamic machine launching |
+| [support_triage_json](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/support_triage_json/python) | JSON input/output with classification pipeline |
+| [parallelism](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/parallelism/python) | Parallel machines, dynamic foreach, fire-and-forget launches |
 
 ## Quick Start
 
@@ -167,7 +167,7 @@ Use `enum: [...]` to constrain string values.
 
 ## Multi-Agent Workflows
 
-For orchestration, use FlatMachine ([full docs in MACHINES.md](./MACHINES.md)):
+For orchestration, use FlatMachine ([full docs in MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md)):
 
 ```python
 from flatagents import FlatMachine
@@ -182,7 +182,7 @@ FlatMachine provides: state transitions, conditional branching, loops, retry wit
 
 - Checkpoint and restore
 - Python SDK (TypeScript SDK in progress)
-- [MACHINES.md](./MACHINES.md) — LLM-optimized reference docs
+- [MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md) — LLM-optimized reference docs
 - Decider agents and machines
 - On-the-fly agent and machine definitions
 - Webhook hooks for remote state machine handling
@@ -206,9 +206,9 @@ FlatMachine provides: state transitions, conditional branching, loops, retry wit
 ## Specs
 
 TypeScript definitions are the source of truth:
-- [`flatagent.d.ts`](./flatagent.d.ts)
-- [`flatmachine.d.ts`](./flatmachine.d.ts)
-- [`profiles.d.ts`](./profiles.d.ts)
+- [`flatagent.d.ts`](https://github.com/memgrafter/flatagents/blob/main/flatagent.d.ts)
+- [`flatmachine.d.ts`](https://github.com/memgrafter/flatagents/blob/main/flatmachine.d.ts)
+- [`profiles.d.ts`](https://github.com/memgrafter/flatagents/blob/main/profiles.d.ts)
 
 ## Python SDK
 

package/dist/index.d.mts

@@ -1,3 +1,39 @@
+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>>;
+}
+/**
+ * Name-based registry for resolving hooks from machine config.
+ *
+ * Machine configs reference hooks by name (e.g., hooks: "my-hooks").
+ * The registry maps names to factory classes/functions and resolves
+ * them at runtime, keeping configs language-agnostic.
+ */
+declare class HooksRegistry {
+    private factories;
+    register(name: string, factory: HooksFactory): void;
+    has(name: string): boolean;
+    resolve(ref: HooksRef): MachineHooks;
+    private resolveSingle;
+}
+
 /**
  * Model configuration for an agent.
  * Can be inline config, profile reference, or profile with overrides.
@@ -200,9 +236,18 @@ interface ResultBackend {
     exists(uri: string): Promise<boolean>;
     delete(uri: string): Promise<void>;
 }
+type HooksRef = string | HooksRefConfig | Array<string | HooksRefConfig>;
+interface HooksRefConfig {
+    name: string;
+    args?: Record<string, any>;
+}
+type HooksFactory = {
+    new (args?: Record<string, any>): MachineHooks;
+} | ((args?: Record<string, any>) => MachineHooks);
 interface MachineOptions {
     config: MachineConfig | string;
     hooks?: MachineHooks;
+    hooksRegistry?: HooksRegistry;
     persistence?: PersistenceBackend;
     resultBackend?: ResultBackend;
     executionLock?: ExecutionLock;
@@ -409,6 +454,7 @@ declare class FlatMachine {
     private context;
     private input;
     private hooks?;
+    private _hooksRegistry;
     private checkpointManager?;
     private resultBackend?;
     private executionLock;
@@ -420,6 +466,8 @@ declare class FlatMachine {
     private currentState?;
     private currentStep;
     constructor(options: MachineOptions);
+    get hooksRegistry(): HooksRegistry;
+    private resolveHooks;
     execute(input?: Record<string, any>, resumeSnapshot?: MachineSnapshot): Promise<any>;
     private executeInternal;
     resume(executionId: string): Promise<any>;
@@ -574,28 +622,6 @@ declare class MDAPVotingExecution implements ExecutionType {
 }
 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>;
@@ -670,4 +696,4 @@ declare class LocalFileLock implements ExecutionLock {
     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 };
+export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type HooksFactory, type HooksRef, type HooksRefConfig, HooksRegistry, 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 };

package/dist/index.d.ts

@@ -1,3 +1,39 @@
+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>>;
+}
+/**
+ * Name-based registry for resolving hooks from machine config.
+ *
+ * Machine configs reference hooks by name (e.g., hooks: "my-hooks").
+ * The registry maps names to factory classes/functions and resolves
+ * them at runtime, keeping configs language-agnostic.
+ */
+declare class HooksRegistry {
+    private factories;
+    register(name: string, factory: HooksFactory): void;
+    has(name: string): boolean;
+    resolve(ref: HooksRef): MachineHooks;
+    private resolveSingle;
+}
+
 /**
  * Model configuration for an agent.
  * Can be inline config, profile reference, or profile with overrides.
@@ -200,9 +236,18 @@ interface ResultBackend {
     exists(uri: string): Promise<boolean>;
     delete(uri: string): Promise<void>;
 }
+type HooksRef = string | HooksRefConfig | Array<string | HooksRefConfig>;
+interface HooksRefConfig {
+    name: string;
+    args?: Record<string, any>;
+}
+type HooksFactory = {
+    new (args?: Record<string, any>): MachineHooks;
+} | ((args?: Record<string, any>) => MachineHooks);
 interface MachineOptions {
     config: MachineConfig | string;
     hooks?: MachineHooks;
+    hooksRegistry?: HooksRegistry;
     persistence?: PersistenceBackend;
     resultBackend?: ResultBackend;
     executionLock?: ExecutionLock;
@@ -409,6 +454,7 @@ declare class FlatMachine {
     private context;
     private input;
     private hooks?;
+    private _hooksRegistry;
     private checkpointManager?;
     private resultBackend?;
     private executionLock;
@@ -420,6 +466,8 @@ declare class FlatMachine {
     private currentState?;
     private currentStep;
     constructor(options: MachineOptions);
+    get hooksRegistry(): HooksRegistry;
+    private resolveHooks;
     execute(input?: Record<string, any>, resumeSnapshot?: MachineSnapshot): Promise<any>;
     private executeInternal;
     resume(executionId: string): Promise<any>;
@@ -574,28 +622,6 @@ declare class MDAPVotingExecution implements ExecutionType {
 }
 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>;
@@ -670,4 +696,4 @@ declare class LocalFileLock implements ExecutionLock {
     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 };
+export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type HooksFactory, type HooksRef, type HooksRefConfig, HooksRegistry, 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 };