flowforge-sdk 0.1.0__py3-none-any.whl

flowforge/__init__.py

@@ -0,0 +1,79 @@
+"""FlowForge SDK - Build reliable AI workflows with durable execution."""
+
+from flowforge.client import FlowForge
+from flowforge.context import Context, Event
+from flowforge.decorators import function
+from flowforge.steps import step
+from flowforge.triggers import Trigger, trigger
+from flowforge.tools import Tool, tool
+from flowforge.agent import AgentConfig, AgentState, AgentResult
+from flowforge.network import Network, NetworkState, NetworkResult, RouterContext, network
+from flowforge.agent_def import AgentDefinition, agent_def
+from flowforge import router
+from flowforge.config import (
+    Concurrency,
+    RateLimit,
+    Throttle,
+    FunctionConfig,
+    concurrency,
+    rate_limit,
+    throttle,
+)
+from flowforge.exceptions import (
+    FlowForgeError,
+    StepError,
+    StepCompleted,
+    StepFailed,
+    StepTimeout,
+    RetryableError,
+    NonRetryableError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main client
+    "FlowForge",
+    # Context and events
+    "Context",
+    "Event",
+    # Decorators
+    "function",
+    # Steps
+    "step",
+    # Tools
+    "Tool",
+    "tool",
+    # Agent
+    "AgentConfig",
+    "AgentState",
+    "AgentResult",
+    # Network
+    "Network",
+    "NetworkState",
+    "NetworkResult",
+    "RouterContext",
+    "network",
+    "AgentDefinition",
+    "agent_def",
+    "router",
+    # Triggers
+    "Trigger",
+    "trigger",
+    # Configuration
+    "Concurrency",
+    "RateLimit",
+    "Throttle",
+    "FunctionConfig",
+    "concurrency",
+    "rate_limit",
+    "throttle",
+    # Exceptions
+    "FlowForgeError",
+    "StepError",
+    "StepCompleted",
+    "StepFailed",
+    "StepTimeout",
+    "RetryableError",
+    "NonRetryableError",
+]

flowforge/agent.py

@@ -0,0 +1,86 @@
+"""Agent loop primitives for FlowForge."""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from flowforge.tools import Tool
+
+
+@dataclass
+class AgentConfig:
+    """
+    Configuration for agent execution.
+
+    Attributes:
+        model: Model to use (e.g., "claude-sonnet-4-20250514", "gpt-4o").
+        system: System prompt for the agent.
+        tools: List of tools the agent can use.
+        max_iterations: Maximum number of agent loop iterations.
+        checkpoint_strategy: When to checkpoint agent state.
+        max_tool_calls: Maximum number of tool calls across all iterations.
+        temperature: Sampling temperature for LLM.
+    """
+
+    model: str
+    system: str = ""
+    tools: list[Tool] = field(default_factory=list)
+    max_iterations: int = 20
+    checkpoint_strategy: Literal["per_tool", "per_iteration", "final_only"] = "per_tool"
+    max_tool_calls: int = 50
+    temperature: float = 0.7
+
+
+@dataclass
+class AgentState:
+    """
+    State of an agent during execution.
+
+    Attributes:
+        messages: Conversation history including user, assistant, and tool messages.
+        iteration: Current iteration number.
+        tool_calls_count: Total number of tool calls made.
+        tokens_used: Total tokens used across all iterations.
+        status: Current status of the agent.
+    """
+
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    iteration: int = 0
+    tool_calls_count: int = 0
+    tokens_used: int = 0
+    status: Literal["running", "completed", "max_iterations", "max_tool_calls", "failed"] = "running"
+
+
+@dataclass
+class AgentResult:
+    """
+    Result of agent execution.
+
+    Attributes:
+        output: Final output text from the agent.
+        status: Final status of the agent execution.
+        iterations: Number of iterations completed.
+        tool_calls_count: Total number of tool calls made.
+        tokens_used: Total tokens used.
+        messages: Full conversation history.
+        tool_calls: Detailed list of all tool calls made.
+    """
+
+    output: str
+    status: Literal["completed", "max_iterations", "max_tool_calls", "failed"]
+    iterations: int
+    tool_calls_count: int
+    tokens_used: int
+    messages: list[dict[str, Any]]
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert result to dictionary for serialization."""
+        return {
+            "output": self.output,
+            "status": self.status,
+            "iterations": self.iterations,
+            "tool_calls_count": self.tool_calls_count,
+            "tokens_used": self.tokens_used,
+            "messages": self.messages,
+            "tool_calls": self.tool_calls,
+        }

flowforge/agent_def.py

@@ -0,0 +1,76 @@
+"""Agent definition for multi-agent networks."""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flowforge.tools import Tool
+
+
+@dataclass
+class AgentDefinition:
+    """
+    Definition of an agent within a network.
+
+    Agents in a network are defined separately from AgentConfig to allow
+    networks to manage agent instances and routing independently.
+
+    Attributes:
+        name: Unique identifier for the agent within the network.
+        system: System prompt for the agent.
+        tools: List of tools available to the agent.
+        model: Model to use (overrides network default if specified).
+
+    Example:
+        classifier = AgentDefinition(
+            name="classifier",
+            system="You classify customer inquiries...",
+            tools=[classify_tool],
+            model="gpt-4o-mini",
+        )
+    """
+
+    name: str
+    system: str
+    tools: list["Tool"] = field(default_factory=list)
+    model: str | None = None  # Override network default
+
+
+def agent_def(
+    name: str,
+    system: str,
+    tools: list["Tool"] | None = None,
+    model: str | None = None,
+) -> AgentDefinition:
+    """
+    Create an agent definition for use in networks.
+
+    Args:
+        name: Unique agent name within the network.
+        system: System prompt for agent behavior.
+        tools: List of Tool instances the agent can use.
+        model: Model override (uses network default if None).
+
+    Returns:
+        AgentDefinition ready for network inclusion.
+
+    Example:
+        from flowforge import agent_def, tool
+
+        @tool()
+        def search_kb(query: str) -> dict:
+            return {"results": [...]}
+
+        support = agent_def(
+            name="support",
+            system="Provide customer support using the knowledge base",
+            tools=[search_kb],
+            model="claude-sonnet-4-20250514",
+        )
+    """
+    return AgentDefinition(
+        name=name,
+        system=system,
+        tools=tools or [],
+        model=model,
+    )

flowforge/ai/__init__.py

@@ -0,0 +1,5 @@
+"""AI provider integrations for FlowForge."""
+
+from flowforge.ai.providers import AIProvider, get_provider
+
+__all__ = ["AIProvider", "get_provider"]

flowforge/ai/providers.py

@@ -0,0 +1,203 @@
+"""AI provider implementations for FlowForge."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+import json
+
+
+class AIProvider(ABC):
+    """Base class for AI providers."""
+
+    @abstractmethod
+    async def complete(
+        self,
+        model: str,
+        messages: list[dict[str, str]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """
+        Generate a completion from the AI model.
+
+        Args:
+            model: Model identifier.
+            messages: List of message dicts with 'role' and 'content'.
+            max_tokens: Maximum tokens to generate.
+            temperature: Sampling temperature.
+            **kwargs: Additional provider-specific parameters.
+
+        Returns:
+            Dict with 'content', 'model', 'usage', and provider-specific data.
+        """
+        pass
+
+
+class OpenAIProvider(AIProvider):
+    """OpenAI API provider."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        self.api_key = api_key
+
+    async def complete(
+        self,
+        model: str,
+        messages: list[dict[str, str]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError:
+            raise ImportError("openai package required. Install with: pip install openai")
+
+        client = AsyncOpenAI(api_key=self.api_key)
+
+        response = await client.chat.completions.create(
+            model=model,
+            messages=messages,  # type: ignore
+            max_tokens=max_tokens,
+            temperature=temperature,
+            **kwargs,
+        )
+
+        return {
+            "content": response.choices[0].message.content,
+            "model": response.model,
+            "usage": {
+                "prompt_tokens": response.usage.prompt_tokens if response.usage else 0,
+                "completion_tokens": response.usage.completion_tokens if response.usage else 0,
+                "total_tokens": response.usage.total_tokens if response.usage else 0,
+            },
+            "finish_reason": response.choices[0].finish_reason,
+        }
+
+
+class AnthropicProvider(AIProvider):
+    """Anthropic API provider."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        self.api_key = api_key
+
+    async def complete(
+        self,
+        model: str,
+        messages: list[dict[str, str]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError:
+            raise ImportError("anthropic package required. Install with: pip install anthropic")
+
+        client = AsyncAnthropic(api_key=self.api_key)
+
+        # Extract system message if present
+        system = None
+        filtered_messages = []
+        for msg in messages:
+            if msg["role"] == "system":
+                system = msg["content"]
+            else:
+                filtered_messages.append(msg)
+
+        response = await client.messages.create(
+            model=model,
+            messages=filtered_messages,  # type: ignore
+            max_tokens=max_tokens,
+            system=system or "",
+            **kwargs,
+        )
+
+        return {
+            "content": response.content[0].text if response.content else "",
+            "model": response.model,
+            "usage": {
+                "prompt_tokens": response.usage.input_tokens,
+                "completion_tokens": response.usage.output_tokens,
+                "total_tokens": response.usage.input_tokens + response.usage.output_tokens,
+            },
+            "stop_reason": response.stop_reason,
+        }
+
+
+class LiteLLMProvider(AIProvider):
+    """
+    LiteLLM provider for unified access to multiple AI providers.
+
+    Supports OpenAI, Anthropic, Cohere, Hugging Face, and many more
+    through a unified interface.
+    """
+
+    def __init__(self) -> None:
+        pass
+
+    async def complete(
+        self,
+        model: str,
+        messages: list[dict[str, str]],
+        max_tokens: int = 1000,
+        temperature: float = 0.7,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        try:
+            import litellm
+        except ImportError:
+            raise ImportError("litellm package required. Install with: pip install litellm")
+
+        response = await litellm.acompletion(
+            model=model,
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            **kwargs,
+        )
+
+        return {
+            "content": response.choices[0].message.content,
+            "model": response.model,
+            "usage": {
+                "prompt_tokens": response.usage.prompt_tokens if response.usage else 0,
+                "completion_tokens": response.usage.completion_tokens if response.usage else 0,
+                "total_tokens": response.usage.total_tokens if response.usage else 0,
+            },
+            "finish_reason": response.choices[0].finish_reason,
+        }
+
+
+def get_provider(provider_name: str | None = None, model: str | None = None) -> AIProvider:
+    """
+    Get an AI provider instance.
+
+    Args:
+        provider_name: Explicit provider name ('openai', 'anthropic', 'litellm').
+        model: Model name to auto-detect provider from.
+
+    Returns:
+        AIProvider instance.
+    """
+    if provider_name:
+        provider_name = provider_name.lower()
+        if provider_name == "openai":
+            return OpenAIProvider()
+        elif provider_name == "anthropic":
+            return AnthropicProvider()
+        elif provider_name == "litellm":
+            return LiteLLMProvider()
+        else:
+            # Default to LiteLLM for unknown providers
+            return LiteLLMProvider()
+
+    # Auto-detect from model name
+    if model:
+        model_lower = model.lower()
+        if model_lower.startswith("gpt") or model_lower.startswith("o1"):
+            return OpenAIProvider()
+        elif model_lower.startswith("claude"):
+            return AnthropicProvider()
+
+    # Default to LiteLLM
+    return LiteLLMProvider()