flatagents 2.4.4__tar.gz → 2.6.0__tar.gz

flatagents-2.6.0/.gitignore

@@ -0,0 +1,26 @@
+.env
+uv.lock
+node_modules
+__pycache__
+dist
+.DS_Store
+.venv
+
+.claude
+
+.self_improve
+
+local
+data
+.checkpoints
+
+logs
+
+.aider.tags.cache.v4/
+.speed-kills/
+auth.json
+.speed-kills/speed-kills
+.speed-kills/indexes/
+.speed-kills/state.db
+.speed-kills/state.db-shm
+.speed-kills/state.db-wal

flatagents-2.6.0/AGENTS.md

@@ -0,0 +1,201 @@
+# 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: "2.5.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
+
+## OAuth Backends (Codex / Copilot)
+
+- `backend: codex` and `backend: copilot` are **explicit-only** (never auto-detected).
+- Backend selection precedence remains: constructor `backend` → resolved `model.backend` → auto-detect (litellm/aisuite only).
+- `oauth` settings are read from resolved model config; works identically whether model came from inline agent config or profile.
+- Auth file precedence:
+  - Codex: `oauth.auth_file` → legacy `codex_auth_file` → legacy `auth.auth_file` → `FLATAGENTS_CODEX_AUTH_FILE` → `~/.pi/agent/auth.json`
+  - Copilot: `oauth.auth_file` → `copilot_auth_file` → legacy `auth.auth_file` → `FLATAGENTS_COPILOT_AUTH_FILE` → `~/.agents/flatmachines/auth.json`
+- Token handling: pre-request refresh on expiry; if refresh fails, re-read auth store once for cross-process refresh; fallback refresh+retry on `401/403`.
+- Retries on `429/500/502/503/504` with exponential backoff (no jitter).
+
+## 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 |
+| `wait_for` | Channel to wait for external signal (Jinja2 template) |
+| `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 }}" }
+```
+
+**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.
+
+**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.
+
+## 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)
+
+## 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 | sqlite
+```
+
+SQLite backend (durable, single-file, no external dependencies):
+```yaml
+persistence:
+  enabled: true
+  backend: sqlite
+  db_path: ./flatmachines.sqlite   # optional, defaults to flatmachines.sqlite
+```
+Auto-selects `SQLiteLeaseLock` and `SQLiteConfigStore` — no runner injection needed.
+
+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.

{flatagents-2.4.4 → flatagents-2.6.0}/MACHINES.md

@@ -72,10 +72,10 @@ Common fields supported by the Python runtime:
 - `provider`, `name` (combined into `provider/name` if needed)
 - `temperature`, `max_tokens`, `top_p`, `top_k`
 - `frequency_penalty`, `presence_penalty`, `seed`
-- `base_url` (passed as `api_base` to LiteLLM, or Codex base URL for `backend: codex`)
+- `base_url` (passed as `api_base` to LiteLLM, or direct base URL for `backend: codex` / `backend: copilot`)
 - `stream` (bool), `stream_options`
-- `backend` ("litellm" | "aisuite" | "codex")
-- `oauth` (Codex auth config: `auth_file`, `originator`, `refresh`, `timeout_seconds`, `max_retries`, `token_url`, `client_id`)
+- `backend` ("litellm" | "aisuite" | "codex" | "copilot")
+- `oauth` (provider auth config; Codex fields include `originator`, `token_url`, `client_id`)
 
 ## Python Runtime Behavior
 
@@ -116,6 +116,7 @@ The Python SDK supports:
 - **LiteLLMBackend** (default; `litellm`)
 - **AISuiteBackend** (`aisuite`)
 - **Codex OAuth backend** (`codex`)
+- **GitHub Copilot OAuth backend** (`copilot`)
 - **LLMBackend** protocol for custom providers
 
 Backend selection order:
@@ -124,11 +125,12 @@ Backend selection order:
 3. `FLATAGENTS_BACKEND` env var ("litellm" or "aisuite")
 4. Auto-detect installed backend (prefers litellm)
 
-Codex is never auto-detected; configure it explicitly via `backend: codex`.
+Codex and Copilot are never auto-detected; configure them explicitly via `backend: codex` / `backend: copilot`.
 
-Codex login helper:
+Login helpers:
 ```bash
 python -m flatagents.providers.openai_codex_login --auth-file ~/.pi/agent/auth.json
+python -m flatagents.providers.github_copilot_login --auth-file ~/.agents/flatmachines/auth.json
 ```
 
 ## MCP Tooling

{flatagents-2.4.4 → flatagents-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flatagents
-Version: 2.4.4
+Version: 2.6.0
 Summary: A lightweight framework for building LLM-powered agents.
 Project-URL: Homepage, https://github.com/memgrafter/flatagents
 Project-URL: Repository, https://github.com/memgrafter/flatagents
@@ -121,6 +121,7 @@ Built-in backends:
 - **LiteLLMBackend** (default, `litellm`)
 - **AISuiteBackend** (`aisuite`)
 - **Codex OAuth backend** (`codex`)
+- **GitHub Copilot OAuth backend** (`copilot`)
 
 Selection order:
 1. `backend` argument to `FlatAgent(...)`
@@ -128,7 +129,7 @@ Selection order:
 3. `FLATAGENTS_BACKEND` env var ("litellm" or "aisuite")
 4. Auto-detect installed backend (prefers litellm)
 
-Codex is explicit only (not auto-detected):
+Codex and Copilot are explicit only (not auto-detected):
 
 ```yaml
 model:
@@ -139,10 +140,20 @@ model:
     auth_file: ~/.pi/agent/auth.json
 ```
 
-Login helper:
+```yaml
+model:
+  provider: github-copilot
+  name: gpt-4o
+  backend: copilot
+  oauth:
+    auth_file: ~/.agents/flatmachines/auth.json
+```
+
+Login helpers:
 
 ```bash
 python -m flatagents.providers.openai_codex_login --auth-file ~/.pi/agent/auth.json
+python -m flatagents.providers.github_copilot_login --auth-file ~/.agents/flatmachines/auth.json
 ```
 
 ## MCP Tools

{flatagents-2.4.4 → flatagents-2.6.0}/README.md

@@ -78,6 +78,7 @@ Built-in backends:
 - **LiteLLMBackend** (default, `litellm`)
 - **AISuiteBackend** (`aisuite`)
 - **Codex OAuth backend** (`codex`)
+- **GitHub Copilot OAuth backend** (`copilot`)
 
 Selection order:
 1. `backend` argument to `FlatAgent(...)`
@@ -85,7 +86,7 @@ Selection order:
 3. `FLATAGENTS_BACKEND` env var ("litellm" or "aisuite")
 4. Auto-detect installed backend (prefers litellm)
 
-Codex is explicit only (not auto-detected):
+Codex and Copilot are explicit only (not auto-detected):
 
 ```yaml
 model:
@@ -96,10 +97,20 @@ model:
     auth_file: ~/.pi/agent/auth.json
 ```
 
-Login helper:
+```yaml
+model:
+  provider: github-copilot
+  name: gpt-4o
+  backend: copilot
+  oauth:
+    auth_file: ~/.agents/flatmachines/auth.json
+```
+
+Login helpers:
 
 ```bash
 python -m flatagents.providers.openai_codex_login --auth-file ~/.pi/agent/auth.json
+python -m flatagents.providers.github_copilot_login --auth-file ~/.agents/flatmachines/auth.json
 ```
 
 ## MCP Tools

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.4.4"
+__version__ = "2.6.0"
 
 from .baseagent import (
     # Base agent (abstract, for multi-step agents)
@@ -79,6 +79,14 @@ from .providers import (
     CodexResult,
     CodexToolCall,
     CodexUsage,
+    CopilotAuthError,
+    CopilotClient,
+    CopilotClientError,
+    CopilotHTTPError,
+    CopilotOAuthCredential,
+    CopilotResult,
+    CopilotToolCall,
+    CopilotUsage,
 )
 
 __all__ = [
@@ -129,6 +137,14 @@ __all__ = [
     "CodexResult",
     "CodexToolCall",
     "CodexUsage",
+    "CopilotAuthError",
+    "CopilotClient",
+    "CopilotClientError",
+    "CopilotHTTPError",
+    "CopilotOAuthCredential",
+    "CopilotResult",
+    "CopilotToolCall",
+    "CopilotUsage",
     # Validation
     "validate_flatagent_config",
     "get_flatagent_schema",

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatagent.d.ts

@@ -46,8 +46,8 @@
  * presence_penalty  - Presence penalty (-2.0 to 2.0)
  * seed              - Random seed for reproducibility
  * base_url          - Custom API base URL (for local models/proxies)
- * backend           - Runtime backend override (litellm, aisuite, codex)
- * oauth             - OAuth settings (used by codex backend)
+ * backend           - Runtime backend override (litellm, aisuite, codex, copilot)
+ * oauth             - OAuth settings (used by codex/copilot backends)
  *
  * MODEL PROFILES:
  * ---------------
@@ -151,7 +151,7 @@
  * The profile field specifies which profile name to use as base.
  */
 
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 
 export interface AgentWrapper {
   spec: "flatagent";
@@ -222,7 +222,7 @@ export interface ModelConfig {
   presence_penalty?: number;
   seed?: number;
   base_url?: string;
-  backend?: "litellm" | "aisuite" | "codex";
+  backend?: "litellm" | "aisuite" | "codex" | "copilot";
   api?: string;
   oauth?: OAuthConfig;
 }

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatagent.schema.json

@@ -112,7 +112,8 @@
           "enum": [
             "litellm",
             "aisuite",
-            "codex"
+            "codex",
+            "copilot"
           ]
         },
         "api": {
@@ -195,7 +196,8 @@
           "enum": [
             "litellm",
             "aisuite",
-            "codex"
+            "codex",
+            "copilot"
           ]
         },
         "api": {

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatagent.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 export interface AgentWrapper {
     spec: "flatagent";
     spec_version: string;
@@ -61,7 +61,7 @@ export interface ModelConfig {
     presence_penalty?: number;
     seed?: number;
     base_url?: string;
-    backend?: "litellm" | "aisuite" | "codex";
+    backend?: "litellm" | "aisuite" | "codex" | "copilot";
     api?: string;
     oauth?: OAuthConfig;
 }

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatagents-runtime.d.ts

@@ -800,7 +800,7 @@ export interface BackendConfig {
     aws_region?: string;
 }
 
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatagents-runtime.schema.json

@@ -11,7 +11,7 @@
         },
         "spec_version": {
           "type": "string",
-          "const": "2.4.4"
+          "const": "2.6.0"
         },
         "execution_lock": {
           "$ref": "#/definitions/ExecutionLock"

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatagents-runtime.slim.d.ts

@@ -252,7 +252,7 @@ export interface BackendConfig {
     dynamodb_table?: string;
     aws_region?: string;
 }
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";
     spec_version: typeof SPEC_VERSION;

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatmachine.d.ts

@@ -319,7 +319,7 @@
  * config_hash         - Content-addressed machine config key for cross-SDK resume (v2.1.0)
  */
 
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 
 export interface MachineWrapper {
   spec: "flatmachine";

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatmachine.schema.json

@@ -251,7 +251,8 @@
           "enum": [
             "litellm",
             "aisuite",
-            "codex"
+            "codex",
+            "copilot"
           ]
         },
         "api": {
@@ -334,7 +335,8 @@
           "enum": [
             "litellm",
             "aisuite",
-            "codex"
+            "codex",
+            "copilot"
           ]
         },
         "api": {

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/flatmachine.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 export interface MachineWrapper {
     spec: "flatmachine";
     spec_version: string;

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/profiles.d.ts

@@ -106,11 +106,11 @@
  * 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)
- * backend           - Runtime backend override (litellm, aisuite, codex)
- * oauth             - OAuth settings (used by codex backend)
+ * backend           - Runtime backend override (litellm, aisuite, codex, copilot)
+ * oauth             - OAuth settings (used by codex/copilot backends)
  */
 
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 
 export interface ProfilesWrapper {
   spec: "flatprofiles";
@@ -148,7 +148,7 @@ export interface ModelProfileConfig {
   seed?: number;
   base_url?: string;
   stream?: boolean;
-  backend?: "litellm" | "aisuite" | "codex";
+  backend?: "litellm" | "aisuite" | "codex" | "copilot";
   api?: string;
   oauth?: OAuthConfig;
 }

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/profiles.schema.json

@@ -88,7 +88,8 @@
           "enum": [
             "litellm",
             "aisuite",
-            "codex"
+            "codex",
+            "copilot"
           ]
         },
         "api": {

{flatagents-2.4.4 → flatagents-2.6.0}/flatagents/assets/profiles.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "2.4.4";
+export const SPEC_VERSION = "2.6.0";
 export interface ProfilesWrapper {
     spec: "flatprofiles";
     spec_version: string;
@@ -32,7 +32,7 @@ export interface ModelProfileConfig {
     seed?: number;
     base_url?: string;
     stream?: boolean;
-    backend?: "litellm" | "aisuite" | "codex";
+    backend?: "litellm" | "aisuite" | "codex" | "copilot";
     api?: string;
     oauth?: OAuthConfig;
 }