flowforge-sdk 0.4.0__tar.gz → 0.4.2__tar.gz

flowforge_sdk-0.4.2/.gitignore

@@ -0,0 +1,68 @@
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Claude Code — ignore local state (plans, sessions, caches) everywhere.
+.claude/
+# …but at the repo root, commit just the in-repo FlowForge skill so every
+# contributor gets the same domain expertise. Any other .claude/ content
+# (including other user-installed skills under .claude/skills/) stays
+# ignored, and nested .claude/ dirs (e.g. dashboard/.claude/) stay fully
+# ignored.
+!/.claude/
+/.claude/*
+!/.claude/skills/
+/.claude/skills/*
+!/.claude/skills/flowforge/
+!/.claude/skills/flowforge/**
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+*.egg-info/
+*.egg
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.pyo
+*.pyd
+
+# Node.js
+node_modules/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Testing
+coverage/
+.coverage
+htmlcov/
+
+# Docker
+*.pid
+/.openclaude-profile.json

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowforge-sdk
-Version: 0.4.0
+Version: 0.4.2
 Summary: Python SDK for FlowForge - AI workflow orchestration
 Project-URL: Homepage, https://github.com/flowforge/flowforge
 Project-URL: Documentation, https://flowforge.dev/docs

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowforge-sdk"
-version = "0.4.0"
+version = "0.4.2"
 description = "Python SDK for FlowForge - AI workflow orchestration"
 readme = "README.md"
 requires-python = ">=3.11"

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/src/flowforge/__init__.py

@@ -9,6 +9,7 @@ from flowforge.config import (
     FunctionConfig,
     RateLimit,
     Throttle,
+    TokenRateLimit,
     concurrency,
     rate_limit,
     throttle,
@@ -18,6 +19,7 @@ from flowforge.decorators import function
 from flowforge.exceptions import (
     FlowForgeError,
     NonRetryableError,
+    RateLimited,
     RetryableError,
     StepCompleted,
     StepError,
@@ -66,6 +68,7 @@ __all__ = [
     # Configuration
     "Concurrency",
     "RateLimit",
+    "TokenRateLimit",
     "Throttle",
     "FunctionConfig",
     "concurrency",
@@ -81,5 +84,6 @@ __all__ = [
     "StepFailed",
     "StepTimeout",
     "RetryableError",
+    "RateLimited",
     "NonRetryableError",
 ]

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/src/flowforge/config.py

@@ -75,6 +75,52 @@ class Throttle:
         }
 
 
+@dataclass
+class TokenRateLimit:
+    """
+    Per-model token-budget rate limit for LLM calls inside a function.
+
+    Caps the tokens consumed per minute for a specific model. Enforced as a
+    pre-flight token-bucket check inside the server's AI service: requests
+    that would exceed the bucket wait durably (via step.sleep inside the SDK
+    retry loop) instead of hitting the provider and getting a 429.
+
+    Example:
+        @flowforge.function(
+            id="research",
+            rate_limits=[
+                TokenRateLimit("claude-sonnet-4-6", tokens_per_minute=25_000),
+            ],
+        )
+    """
+
+    model: str
+    """Model name the limit applies to (e.g. "claude-sonnet-4-6")."""
+
+    tokens_per_minute: int
+    """Maximum tokens consumed per minute."""
+
+    key: str | None = None
+    """
+    Optional *literal* grouping key used as a suffix on the Redis bucket so
+    distinct values get distinct buckets. When None, the bucket is scoped
+    per (tenant, function, model).
+
+    Note: this is currently a static string, not an expression. The server
+    uses it verbatim as the Redis-key suffix; per-event evaluation (e.g.
+    ``event.data.tenant_id``) is a follow-up. To isolate buckets by caller
+    today, pass a concrete value like ``"premium"`` or ``"free"`` from the
+    code that constructs the decorator.
+    """
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model": self.model,
+            "tokens_per_minute": self.tokens_per_minute,
+            "key": self.key,
+        }
+
+
 @dataclass
 class Debounce:
     """
@@ -130,6 +176,9 @@ class FunctionConfig:
     rate_limit: RateLimit | None = None
     """Rate limiting configuration."""
 
+    rate_limits: list["TokenRateLimit"] = field(default_factory=list)
+    """Per-model token-budget limits (AC9)."""
+
     throttle: Throttle | None = None
     """Throttle configuration."""
 
@@ -157,6 +206,8 @@ class FunctionConfig:
             config["concurrency"] = self.concurrency.to_dict()
         if self.rate_limit:
             config["rate_limit"] = self.rate_limit.to_dict()
+        if self.rate_limits:
+            config["rate_limits"] = [rl.to_dict() for rl in self.rate_limits]
         if self.throttle:
             config["throttle"] = self.throttle.to_dict()
         if self.debounce:

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/src/flowforge/decorators.py

@@ -5,7 +5,14 @@ import inspect
 from collections.abc import Awaitable, Callable
 from typing import Any, ParamSpec, TypeVar
 
-from flowforge.config import Concurrency, Debounce, FunctionConfig, RateLimit, Throttle
+from flowforge.config import (
+    Concurrency,
+    Debounce,
+    FunctionConfig,
+    RateLimit,
+    Throttle,
+    TokenRateLimit,
+)
 from flowforge.context import Context
 from flowforge.triggers import Trigger
 
@@ -31,6 +38,7 @@ class FlowForgeFunction:
         timeout: str = "5m",
         concurrency: Concurrency | None = None,
         rate_limit: RateLimit | None = None,
+        rate_limits: list[TokenRateLimit] | None = None,
         throttle: Throttle | None = None,
         debounce: Debounce | None = None,
         cancel_on: list[str] | None = None,
@@ -47,6 +55,7 @@ class FlowForgeFunction:
             timeout=timeout,
             concurrency=concurrency,
             rate_limit=rate_limit,
+            rate_limits=rate_limits or [],
             throttle=throttle,
             debounce=debounce,
             cancel_on=cancel_on or [],
@@ -79,6 +88,7 @@ def function(
     timeout: str = "5m",
     concurrency: Concurrency | None = None,
     rate_limit: RateLimit | None = None,
+    rate_limits: list[TokenRateLimit] | None = None,
     throttle: Throttle | None = None,
     debounce: Debounce | None = None,
     cancel_on: list[str] | None = None,
@@ -97,7 +107,10 @@ def function(
         retries: Number of retry attempts on failure (default: 3).
         timeout: Maximum execution time (default: "5m").
         concurrency: Concurrency limiting configuration.
-        rate_limit: Rate limiting configuration.
+        rate_limit: Rate limiting configuration (invocations per period).
+        rate_limits: Per-model token-budget limits enforced pre-flight on
+            LLM calls (see TokenRateLimit). Prevents 429s by absorbing
+            back-pressure into durable step.sleep waits.
         throttle: Throttle configuration.
         debounce: Debounce configuration.
         cancel_on: List of events that cancel running instances.
@@ -156,6 +169,7 @@ def function(
             timeout=timeout,
             concurrency=concurrency,
             rate_limit=rate_limit,
+            rate_limits=rate_limits,
             throttle=throttle,
             debounce=debounce,
             cancel_on=cancel_on,

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/src/flowforge/exceptions.py

@@ -58,17 +58,67 @@ class StepTimeout(StepError):
         super().__init__(step_id, f"timed out after {timeout_seconds}s")
 
 
-class RetryableError(FlowForgeError):
+class RetryableError(StepFailed):
     """
     Raised to indicate an error that should trigger a retry.
 
-    Use this to signal that the current step should be retried,
-    e.g., for transient network errors or rate limits.
+    Used for transient failures (rate limits, brief network issues). Subclasses
+    StepFailed so existing `except StepFailed` catchers still catch it; callers
+    that want retry-specific behaviour can catch RetryableError directly.
     """
 
-    def __init__(self, message: str, retry_after: float | None = None) -> None:
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        step_id: str = "",
+        retry_after: float | None = None,
+        attempt: int = 1,
+        max_attempts: int = 1,
+    ) -> None:
         self.retry_after = retry_after
-        super().__init__(message)
+        super().__init__(step_id, message, attempt=attempt, max_attempts=max_attempts)
+
+
+class RateLimited(RetryableError):
+    """
+    Raised when an LLM provider rate-limited the request and retries exhausted.
+
+    Carries enough context for callers to decide follow-up behaviour (switch
+    providers, surface to the user, park the run).
+
+    Aliases:
+      - ``self.original`` / ``self.original_error`` — both point at the
+        underlying provider exception (or its string form). Error payloads
+        serialised via ``str(e.original_error)`` therefore surface the real
+        root cause, not the synthesised "rate limited by …" banner.
+    """
+
+    def __init__(
+        self,
+        *,
+        step_id: str = "",
+        retry_after: float | None = None,
+        provider: str = "",
+        model: str = "",
+        original: Exception | str = "",
+        attempt: int = 1,
+        max_attempts: int = 1,
+    ) -> None:
+        self.provider = provider
+        self.model = model
+        self.original = original
+        # Pass `original` through StepFailed so `e.original_error` reflects
+        # the underlying provider failure. The exception's __str__ still
+        # includes a readable banner via the StepError base message.
+        banner = f"rate limited by {provider or 'provider'} on {model or 'model'}"
+        super().__init__(
+            original if original else banner,
+            step_id=step_id,
+            retry_after=retry_after,
+            attempt=attempt,
+            max_attempts=max_attempts,
+        )
 
 
 class NonRetryableError(FlowForgeError):

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/src/flowforge/execution.py

@@ -137,19 +137,31 @@ class ExecutionEngine:
             )
 
         except StepFailed as e:
-            # Step failed, let server handle retry
+            # Step failed, let server handle retry.
+            # Preserve the actual exception class (StepFailed | RetryableError |
+            # RateLimited) so the server / dashboard can distinguish them.
+            error_payload: dict[str, Any] = {
+                "type": type(e).__name__,
+                "message": str(e.original_error),
+                "step_id": e.step_id,
+                "attempt": e.attempt,
+                "max_attempts": e.max_attempts,
+                "retryable": True,
+                "traceback": traceback.format_exc(),
+            }
+            retry_after = getattr(e, "retry_after", None)
+            if retry_after is not None:
+                error_payload["retry_after"] = retry_after
+            provider = getattr(e, "provider", None)
+            if provider:
+                error_payload["provider"] = provider
+            model = getattr(e, "model", None)
+            if model:
+                error_payload["model"] = model
             return ExecutionResult(
                 status="error",
                 step_id=e.step_id,
-                error={
-                    "type": "StepFailed",
-                    "message": str(e.original_error),
-                    "step_id": e.step_id,
-                    "attempt": e.attempt,
-                    "max_attempts": e.max_attempts,
-                    "retryable": True,
-                    "traceback": traceback.format_exc(),
-                },
+                error=error_payload,
             )
 
         except NonRetryableError as e:

{flowforge_sdk-0.4.0 → flowforge_sdk-0.4.2}/src/flowforge/steps.py

@@ -2,19 +2,60 @@
 
 import hashlib
 import json
+import os
+import random
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime, timedelta
 from typing import Any, TypeVar
 
 from flowforge.agent import AgentResult, AgentState
 from flowforge.agent_def import AgentDefinition
-from flowforge.exceptions import StepCompleted, StepFailed
+from flowforge.exceptions import RateLimited, StepCompleted, StepFailed
 from flowforge.network import Network, NetworkResult, NetworkState, RouterContext
 from flowforge.router import LLMRouter
 from flowforge.tools import SubAgentConfig, Tool
 
 T = TypeVar("T")
 
+# Defaults for LLM-call retry on rate-limit. See _resolve_num_retries /
+# _retry_sleep below.
+_DEFAULT_LLM_NUM_RETRIES = 5
+_DEFAULT_LLM_MAX_RETRY_DELAY = 120.0
+_RETRY_JITTER_RANGE = (0.8, 1.2)
+
+
+def _resolve_num_retries(explicit: int | None) -> int:
+    """
+    Determine the retry budget for an LLM call.
+
+    Precedence: explicit kwarg > FLOWFORGE_LLM_NUM_RETRIES env >
+    LITELLM_NUM_RETRIES env (back-compat) > default 5. Clamped to >= 0.
+    """
+    if explicit is not None:
+        return max(0, int(explicit))
+    for var in ("FLOWFORGE_LLM_NUM_RETRIES", "LITELLM_NUM_RETRIES"):
+        raw = os.environ.get(var)
+        if raw is None:
+            continue
+        try:
+            return max(0, int(raw))
+        except ValueError:
+            continue
+    return _DEFAULT_LLM_NUM_RETRIES
+
+
+def _retry_sleep(retry_after: float) -> float:
+    """Apply ±20% jitter and clamp to [1s, FLOWFORGE_LLM_MAX_RETRY_DELAY]."""
+    try:
+        max_delay = float(
+            os.environ.get("FLOWFORGE_LLM_MAX_RETRY_DELAY", _DEFAULT_LLM_MAX_RETRY_DELAY)
+        )
+    except ValueError:
+        max_delay = _DEFAULT_LLM_MAX_RETRY_DELAY
+    base = max(0.0, float(retry_after))
+    jittered = base * random.uniform(*_RETRY_JITTER_RANGE)
+    return max(1.0, min(jittered, max_delay))
+
 
 def _parse_duration(duration: str | timedelta) -> float:
     """Parse a duration string or timedelta to seconds."""
@@ -183,14 +224,25 @@ class StepManager:
         tools: list[Any] | None = None,
         tool_choice: str | dict[str, Any] = "auto",
         max_tool_calls: int = 10,
+        num_retries: int | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
-        Execute an LLM call with automatic retry and cost tracking.
-
-        Supports multiple providers (OpenAI, Anthropic, etc.) with
-        unified interface. Automatically retries on rate limits
-        and transient errors.
+        Execute an LLM call with durable rate-limit retry and cost tracking.
+
+        Supports multiple providers (OpenAI, Anthropic, etc.) with a unified
+        interface. On provider 429 (or pre-flight token-bucket exhaustion),
+        expands into a durable chain of ``{step_id}`` (first attempt,
+        rate-limited) → ``{step_id}/retry-sleep-1`` → ``{step_id}/attempt-2``
+        → … driven by Retry-After with ±20% jitter. The worker is freed
+        during each sleep. When retries exhaust, raises
+        :class:`flowforge.RateLimited`.
+
+        **Narrower than you might expect:** only provider 429 responses are
+        retried here. Non-rate-limit transient errors (timeouts, 5xx,
+        connection failures) propagate immediately as ``StepFailed`` and
+        are subject to the function-level retry policy set on
+        ``@flowforge.function(retries=N)``.
 
         Args:
             step_id: Unique identifier for this AI step.
@@ -204,6 +256,10 @@ class StepManager:
             tools: List of Tool objects that the LLM can call.
             tool_choice: How the LLM should choose tools ("auto", "required", "none", or specific tool).
             max_tool_calls: Maximum number of tool calls allowed in this step.
+            num_retries: Override the rate-limit retry budget for this call.
+                ``None`` (default) reads ``FLOWFORGE_LLM_NUM_RETRIES`` →
+                ``LITELLM_NUM_RETRIES`` → 5. ``0`` disables retry and
+                raises ``RateLimited`` on the first 429.
             **kwargs: Additional provider-specific parameters.
 
         Returns:
@@ -256,12 +312,9 @@ class StepManager:
             if result.get("tool_calls"):
                 print(f"Tools called: {result['tool_calls']}")
         """
-        # Check for memoized result
-        is_memoized, result = self._get_memoized_result(step_id)
-        if is_memoized:
-            return result  # type: ignore
+        num_retries = _resolve_num_retries(num_retries)
 
-        # Build messages if prompt provided
+        # Build messages once (shared across attempts).
         if prompt is not None and messages is None:
             if isinstance(prompt, str):
                 messages = [{"role": "user", "content": prompt}]
@@ -271,7 +324,6 @@ class StepManager:
         if messages is None:
             raise ValueError("Either 'prompt' or 'messages' must be provided")
 
-        # Convert Tool objects to JSON-serializable OpenAI schema dicts
         tools_schema = None
         if tools:
             tools_schema = [
@@ -279,8 +331,79 @@ class StepManager:
                 for t in tools
             ]
 
-        # This will be executed by the server/executor with LLM client
-        ai_request = {
+        # Durable retry loop. Each attempt is its own memoised sub-step, with
+        # a step.sleep between attempts so the worker is freed during the
+        # wait. First attempt keeps the caller's step_id (back-compat); only
+        # subsequent attempts get an /attempt-N suffix.
+        last_signal: dict[str, Any] | None = None
+        for attempt in range(num_retries + 1):
+            attempt_id = step_id if attempt == 0 else f"{step_id}/attempt-{attempt + 1}"
+            result = await self._ai_attempt(
+                attempt_id,
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                provider=provider,
+                use_cache=use_cache,
+                tools_schema=tools_schema,
+                tool_choice=tool_choice,
+                max_tool_calls=max_tool_calls,
+                extra_kwargs=kwargs,
+            )
+
+            if not (isinstance(result, dict) and result.get("__rate_limited")):
+                return result  # type: ignore[return-value]
+
+            last_signal = result
+            if attempt >= num_retries:
+                break
+
+            retry_after = float(result.get("__retry_after") or 1.0)
+            sleep_s = _retry_sleep(retry_after)
+            await self.sleep(
+                f"{step_id}/retry-sleep-{attempt + 1}",
+                duration=f"{sleep_s:.3f}s",
+            )
+
+        assert last_signal is not None  # loop always sets it before breaking
+        raise RateLimited(
+            step_id=step_id,
+            retry_after=last_signal.get("__retry_after"),
+            provider=str(last_signal.get("__provider") or ""),
+            model=str(last_signal.get("__model") or model),
+            original=str(last_signal.get("__error") or ""),
+            attempt=num_retries + 1,
+            max_attempts=num_retries + 1,
+        )
+
+    async def _ai_attempt(
+        self,
+        attempt_id: str,
+        *,
+        model: str,
+        messages: list[dict[str, str]],
+        max_tokens: int,
+        temperature: float,
+        provider: str | None,
+        use_cache: bool,
+        tools_schema: list[dict[str, Any]] | None,
+        tool_choice: str | dict[str, Any],
+        max_tool_calls: int,
+        extra_kwargs: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Execute a single LLM attempt.
+
+        On first call yields to the server (raises StepCompleted). On replay,
+        returns the memoised server response — either a normal AI response dict
+        or a rate-limit marker ({"__rate_limited": True, "__retry_after": ...}).
+        """
+        is_memoized, result = self._get_memoized_result(attempt_id)
+        if is_memoized:
+            return result  # type: ignore[return-value]
+
+        ai_request: dict[str, Any] = {
             "type": "ai",
             "model": model,
             "messages": messages,
@@ -291,10 +414,10 @@ class StepManager:
             "tools": tools_schema,
             "tool_choice": tool_choice,
             "max_tool_calls": max_tool_calls,
-            **kwargs,
+            **extra_kwargs,
         }
 
-        raise StepCompleted(step_id=step_id, result=ai_request)
+        raise StepCompleted(step_id=attempt_id, result=ai_request)
 
     async def wait_for_event(
         self,
@@ -459,6 +582,7 @@ class StepManager:
         checkpoint_strategy: str = "per_tool",
         max_tool_calls: int = 50,
         temperature: float = 0.7,
+        num_retries: int | None = None,
         _depth: int = 0,
         _max_depth: int = 3,
         **kwargs: Any,
@@ -550,7 +674,9 @@ class StepManager:
                 state.status = "max_tool_calls"
                 break
 
-            # Call LLM with current messages
+            # Call LLM with current messages. num_retries propagates per
+            # iteration — a 429 on iter-N/think only retries iter-N/think;
+            # earlier iterations stay memoised.
             think_step_id = f"{step_id}/iter-{state.iteration}/think"
             ai_response = await self.ai(
                 think_step_id,
@@ -560,6 +686,7 @@ class StepManager:
                 tools=tools,
                 tool_choice="auto",
                 max_tool_calls=max_tool_calls - state.tool_calls_count,
+                num_retries=num_retries,
                 **kwargs,
             )
 
@@ -1156,6 +1283,7 @@ class _StepProxy:
         tools: list[Any] | None = None,
         tool_choice: str | dict[str, Any] = "auto",
         max_tool_calls: int = 10,
+        num_retries: int | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         return await self._get_manager().ai(
@@ -1170,6 +1298,7 @@ class _StepProxy:
             tools=tools,
             tool_choice=tool_choice,
             max_tool_calls=max_tool_calls,
+            num_retries=num_retries,
             **kwargs,
         )
 
@@ -1219,6 +1348,7 @@ class _StepProxy:
         checkpoint_strategy: str = "per_tool",
         max_tool_calls: int = 50,
         temperature: float = 0.7,
+        num_retries: int | None = None,
         _depth: int = 0,
         _max_depth: int = 3,
         **kwargs: Any,
@@ -1233,6 +1363,7 @@ class _StepProxy:
             checkpoint_strategy=checkpoint_strategy,
             max_tool_calls=max_tool_calls,
             temperature=temperature,
+            num_retries=num_retries,
             _depth=_depth,
             _max_depth=_max_depth,
             **kwargs,

flowforge_sdk-0.4.0/.gitignore

@@ -1,57 +0,0 @@
-# Environment and secrets
-.env
-.env.*
-!.env.example
-
-# Claude Code
-.claude/
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-.venv/
-venv/
-ENV/
-*.egg-info/
-*.egg
-dist/
-build/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-*.pyo
-*.pyd
-
-# Node.js
-node_modules/
-.next/
-out/
-.turbo/
-*.tsbuildinfo
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-logs/
-
-# Testing
-coverage/
-.coverage
-htmlcov/
-
-# Docker
-*.pid
-/.openclaude-profile.json