flatagents 2.7.0__tar.gz → 4.0.0__tar.gz

{flatagents-2.7.0 → flatagents-4.0.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # FlatAgents + FlatMachines Reference
 
-> **Target: <1000 tokens.** LLM-optimized. See `flatagent.d.ts`, `flatmachine.d.ts`, `profiles.d.ts` for schemas.
+> **Target: <1000 tokens.** LLM-optimized. See `flatagent.d.ts`, `flatmachine.d.ts`, `profile.d.ts`, `prompt.d.ts` for schemas.
 >
 > **Versioning:** All specs and SDKs use lockstep versioning.
 
@@ -21,8 +21,8 @@
 
 ```yaml
 # profiles.yml — agents reference by name
-spec: flatprofiles
-spec_version: "2.5.0"
+spec: flatprofile
+spec_version: "4.0.0"
 data:
   model_profiles:
     fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }
@@ -40,7 +40,7 @@ Resolution: default → profile → overrides → override
 - 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` → `~/.agents/flatmachines/auth.json`
+  - 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).
@@ -52,6 +52,21 @@ Resolution: default → profile → overrides → override
 - Inline flatagent config (`spec: flatagent`)
 - Typed adapter ref: `{ type: "flatagent" | "smolagents" | "pi-agent", ref?: "...", config?: {...} }`
 
+## LLM I/O & Formatting (Hard Rules)
+
+- Between LLM stages, default to **plain text/Markdown** handoffs.
+- Avoid JSON/Jinja-shaped model-to-model output unless required by strict schema validation or a boundary contract (API/DB/file format).
+- Why: JSON/Jinja handoffs increase parse fragility and token overhead.
+- Keep `input` / `output_to_context` mappings explicit and shallow.
+- Push heavy transforms to boundary actions only (final save/write steps).
+- Preserve full source text across stages (avoid excerpt-only chains unless explicitly requested).
+- Jinja in config (`input`, `output_to_context`, `transitions`, `foreach`, `wait_for`) must be cross-SDK portable:
+  - use property access, comparisons, simple conditionals
+  - avoid Python-specific features (`.items()`, `|tojson`, `len()`, `isinstance()`, list comprehensions).
+- **Never truncate** LLM inputs/outputs silently.
+  - If size is a problem: ask user, enforce prompt limits, reject+retry, or add a repair/compaction stage.
+- Each transform must have a one-line justification; otherwise remove it.
+
 ## State Fields
 
 | Field | Purpose |

{flatagents-2.7.0 → flatagents-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flatagents
-Version: 2.7.0
+Version: 4.0.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
@@ -45,7 +45,7 @@ Description-Content-Type: text/markdown
 
 Define single-call LLM agents in YAML. Use this package when you want **one structured call** per agent, with optional MCP tools and profile-driven model configs. For orchestration, install `flatmachines` separately.
 
-**For LLM/machine readers:** see [MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md).
+**For LLM/machine readers:** see [AGENTS.md](./AGENTS.md).
 
 ## Install
 
@@ -100,7 +100,7 @@ If `data.output` is provided, FlatAgents requests JSON mode and parses the respo
 ## Model Profiles (profiles.yml)
 
 ```yaml
-spec: flatprofiles
+spec: flatprofile
 spec_version: "0.10.0"
 
 data:
@@ -217,4 +217,5 @@ from flatagents import FlatMachine
 
 Source of truth:
 - [`flatagent.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/flatagent.d.ts)
-- [`profiles.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/profiles.d.ts)
+- [`prompt.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/prompt.d.ts)
+- [`profile.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/profile.d.ts)

{flatagents-2.7.0 → flatagents-4.0.0}/README.md

@@ -2,7 +2,7 @@
 
 Define single-call LLM agents in YAML. Use this package when you want **one structured call** per agent, with optional MCP tools and profile-driven model configs. For orchestration, install `flatmachines` separately.
 
-**For LLM/machine readers:** see [MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md).
+**For LLM/machine readers:** see [AGENTS.md](./AGENTS.md).
 
 ## Install
 
@@ -57,7 +57,7 @@ If `data.output` is provided, FlatAgents requests JSON mode and parses the respo
 ## Model Profiles (profiles.yml)
 
 ```yaml
-spec: flatprofiles
+spec: flatprofile
 spec_version: "0.10.0"
 
 data:
@@ -174,4 +174,5 @@ from flatagents import FlatMachine
 
 Source of truth:
 - [`flatagent.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/flatagent.d.ts)
-- [`profiles.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/profiles.d.ts)
+- [`prompt.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/prompt.d.ts)
+- [`profile.d.ts`](https://github.com/memgrafter/flatagents/blob/main/sdk/python/flatagents/flatagents/assets/profile.d.ts)

{flatagents-2.7.0 → flatagents-4.0.0}/flatagents/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.7.0"
+__version__ = "4.0.0"
 
 from .baseagent import (
     # Base agent (abstract, for multi-step agents)
@@ -35,6 +35,8 @@ from .flatagent import FlatAgent
 from .profiles import (
     ProfileManager,
     resolve_model_config,
+    load_profile_from_file,
+    resolve_profile_config,
 )
 from .validation import (
     validate_flatagent_config,
@@ -63,6 +65,21 @@ from .tool_loop import (
     StopReason,
     SteeringProvider,
 )
+from .adapters import (
+    ClaudeCodeExecutor,
+    create_claude_code_executor,
+    CodexCliExecutor,
+    CodexAppServerTransport,
+    create_codex_cli_executor,
+    SmolagentsExecutor,
+    create_smolagents_executor,
+    PiAgentBridgeExecutor,
+    create_pi_agent_bridge_executor,
+    ClaudeCodeSessionHoldback,
+    ClaudeCodeForkResult,
+    CodexSessionHoldback,
+    CodexForkResult,
+)
 # Provider-specific utilities
 from .providers import (
     CerebrasRateLimits,
@@ -159,6 +176,22 @@ __all__ = [
     # Model Profiles
     "ProfileManager",
     "resolve_model_config",
+    "load_profile_from_file",
+    "resolve_profile_config",
+    # Runtime adapters
+    "ClaudeCodeExecutor",
+    "create_claude_code_executor",
+    "CodexCliExecutor",
+    "CodexAppServerTransport",
+    "create_codex_cli_executor",
+    "SmolagentsExecutor",
+    "create_smolagents_executor",
+    "PiAgentBridgeExecutor",
+    "create_pi_agent_bridge_executor",
+    "ClaudeCodeSessionHoldback",
+    "ClaudeCodeForkResult",
+    "CodexSessionHoldback",
+    "CodexForkResult",
     # Tool Use
     "ToolResult",
     "ToolProvider",

flatagents-4.0.0/flatagents/adapters/__init__.py

@@ -0,0 +1,32 @@
+"""Single-agent runtime adapters for FlatAgents."""
+
+from .claude_code import ClaudeCodeExecutor, create_claude_code_executor
+from .codex_cli import CodexCliExecutor, CodexAppServerTransport, create_codex_cli_executor
+from .pi_agent_bridge import PiAgentBridgeExecutor, create_pi_agent_bridge_executor
+from .claude_code_sessions import SessionHoldback as ClaudeCodeSessionHoldback, ForkResult as ClaudeCodeForkResult
+from .codex_cli_sessions import CodexSessionHoldback, ForkResult as CodexForkResult
+
+__all__ = [
+    "ClaudeCodeExecutor",
+    "create_claude_code_executor",
+    "CodexCliExecutor",
+    "CodexAppServerTransport",
+    "create_codex_cli_executor",
+    "PiAgentBridgeExecutor",
+    "create_pi_agent_bridge_executor",
+    "ClaudeCodeSessionHoldback",
+    "ClaudeCodeForkResult",
+    "CodexSessionHoldback",
+    "CodexForkResult",
+]
+
+try:
+    from .smolagents import SmolagentsExecutor, create_smolagents_executor
+
+    __all__.extend([
+        "SmolagentsExecutor",
+        "create_smolagents_executor",
+    ])
+except ImportError:  # pragma: no cover - optional dependency
+    SmolagentsExecutor = None  # type: ignore[assignment]
+    create_smolagents_executor = None  # type: ignore[assignment]

flatagents-4.0.0/flatagents/adapters/call_throttle.py

@@ -0,0 +1,110 @@
+"""Async call throttle — serialized gate with jitter.
+
+Enforces a minimum delay between calls.  An asyncio.Lock serialises the
+"when to launch" decision so concurrent callers are staggered, but the
+actual work (subprocess, network call, …) runs concurrently once past
+the gate.
+
+    throttle = CallThrottle(delay=3.0, jitter=4.0)
+
+    # 3 concurrent tasks:
+    #   t≈0s   task-1 passes gate immediately (first call)
+    #   t≈0s   task-2 acquires lock, sleeps ~7s, passes gate
+    #   t≈7s   task-3 acquires lock, sleeps ~5s, passes gate
+    #   all 3 subprocesses now running concurrently
+
+Delay formula per call::
+
+    wait = max(0, (last_call + delay + uniform(0, 2*jitter)) - now)
+
+With ``delay=3, jitter=4`` the gap between consecutive calls is
+uniformly distributed over **[3, 11] seconds**, with millisecond
+granularity from float arithmetic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+import time
+
+logger = logging.getLogger(__name__)
+
+
+class CallThrottle:
+    """Async rate limiter: base delay + uniform jitter between calls.
+
+    Args:
+        delay: Minimum base seconds between calls.
+        jitter: Half-width of the jitter window.  Actual jitter added is
+            ``uniform(0, 2 * jitter)`` so the total gap is in
+            ``[delay, delay + 2*jitter]``.  Set to 0 for fixed delay.
+    """
+
+    def __init__(self, delay: float = 0.0, jitter: float = 0.0) -> None:
+        self._delay = max(0.0, delay)
+        self._jitter = max(0.0, jitter)
+        self._lock = asyncio.Lock()
+        self._last_call: float = 0.0   # monotonic timestamp
+
+    @property
+    def enabled(self) -> bool:
+        return self._delay > 0 or self._jitter > 0
+
+    async def wait(self) -> float:
+        """Block until the next call is allowed.
+
+        Returns the number of seconds actually waited (0.0 on first call
+        or when the throttle is disabled).
+        """
+        if not self.enabled:
+            return 0.0
+
+        async with self._lock:
+            now = time.monotonic()
+
+            if self._last_call == 0.0:
+                # First call — no wait
+                self._last_call = now
+                return 0.0
+
+            # Compute jitter with ms granularity
+            jitter_ms = random.randint(0, int(2 * self._jitter * 1000))
+            jitter_s = jitter_ms / 1000.0
+
+            target = self._last_call + self._delay + jitter_s
+            wait_s = max(0.0, target - now)
+
+            if wait_s > 0:
+                logger.debug(
+                    "CallThrottle: sleeping %.3fs (delay=%.1f jitter=%.3f)",
+                    wait_s, self._delay, jitter_s,
+                )
+                await asyncio.sleep(wait_s)
+
+            self._last_call = time.monotonic()
+            return wait_s
+
+    def reset(self) -> None:
+        """Reset the throttle so the next call passes immediately."""
+        self._last_call = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Factory from config dict
+# ---------------------------------------------------------------------------
+
+def throttle_from_config(config: dict) -> CallThrottle:
+    """Create a CallThrottle from an adapter config dict.
+
+    Recognised keys::
+
+        rate_limit_delay:  3.0   # base seconds (default 0 = disabled)
+        rate_limit_jitter: 4.0   # ±seconds (default 0)
+
+    Returns a disabled throttle when neither key is set.
+    """
+    delay = float(config.get("rate_limit_delay", 0))
+    jitter = float(config.get("rate_limit_jitter", 0))
+    return CallThrottle(delay=delay, jitter=jitter)