rapidagent 0.3.0__py3-none-any.whl

rapidagent/__init__.py

@@ -0,0 +1,4 @@
+from rapidagent.core.base import RapidAgent, BaseNode, BaseGraph
+from rapidagent.tools.decorator import tool
+
+__all__ = ["RapidAgent", "BaseNode", "BaseGraph", "tool"]

rapidagent/backends/__init__.py

@@ -0,0 +1,16 @@
+# Lazy imports — backends may have optional dependencies
+from rapidagent.backends.base import Backend, BackendResult
+
+__all__ = ["Backend", "BackendResult"]
+
+
+def LangGraphBackend(*args, **kwargs):
+    """Lazy loader — langgraph is an optional dependency."""
+    from rapidagent.backends.langgraph import LangGraphBackend as _LB
+    return _LB(*args, **kwargs)
+
+
+def DirectBackend(*args, **kwargs):
+    """Lazy loader — pure Python, no extra deps."""
+    from rapidagent.backends.direct import DirectBackend as _DB
+    return _DB(*args, **kwargs)

rapidagent/backends/base.py

@@ -0,0 +1,193 @@
+"""Abstract backend interface for agent execution."""
+
+from __future__ import annotations
+
+import abc
+import sys
+from dataclasses import dataclass, field
+from typing import Any, Generator
+
+from rapidagent.models.config import ModelConfig
+from rapidagent.tools.registry import ToolRegistry
+
+
+# ---------------------------------------------------------------------------
+# Token / cost tracking
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TokenUsage:
+    """Token and cost tracking from an LLM response."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    cost_usd: float = 0.0
+
+    def add(self, other: TokenUsage) -> None:
+        self.prompt_tokens += other.prompt_tokens
+        self.completion_tokens += other.completion_tokens
+        self.total_tokens += other.total_tokens
+        self.cost_usd += other.cost_usd
+
+    @classmethod
+    def from_openai_response(cls, response: Any, model: str = "gpt-4o-mini") -> TokenUsage:
+        """Parse token usage from an OpenAI chat completion response."""
+        rates = {
+            "gpt-4o-mini": (0.00015, 0.00060),
+            "gpt-4o": (0.00250, 0.01000),
+            "gpt-5": (0.00500, 0.02000),
+        }
+        usage = getattr(response, "usage", None) or getattr(response, "usage_metadata", None)
+        if usage is None:
+            return cls()
+
+        pt = getattr(usage, "prompt_tokens", getattr(usage, "input_tokens", 0)) or 0
+        ct = getattr(usage, "completion_tokens", getattr(usage, "output_tokens", 0)) or 0
+        r = rates.get(model, (0.0, 0.0))
+        cost = (pt / 1_000_000) * r[0] + (ct / 1_000_000) * r[1]
+        return cls(prompt_tokens=pt, completion_tokens=ct, total_tokens=pt + ct, cost_usd=cost)
+
+
+# ---------------------------------------------------------------------------
+# Result
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BackendResult:
+    """Standard result returned by any backend's ``invoke`` / ``stream``."""
+
+    messages: list[Any] = field(default_factory=list)
+    content: str = ""
+    error: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+    usage: TokenUsage = field(default_factory=TokenUsage)
+
+    @classmethod
+    def from_content(cls, content: str) -> "BackendResult":
+        return cls(content=content, messages=[{"role": "assistant", "content": content}])
+
+
+# ---------------------------------------------------------------------------
+# Backend
+# ---------------------------------------------------------------------------
+
+class Backend(abc.ABC):
+    """Abstract base for agent execution backends."""
+
+    name: str = ""
+
+    def __init__(self, checkpoint_dir: str | None = None) -> None:
+        self._checkpoint_dir = checkpoint_dir
+        self._guardrail_pipeline: Any = None
+
+    def set_guardrails(self, pipeline: Any) -> None:
+        self._guardrail_pipeline = pipeline
+
+    # -- Single agent --
+
+    @abc.abstractmethod
+    def build_react(
+        self,
+        llm_config: ModelConfig,
+        tools: ToolRegistry,
+        system_prompt: str,
+        max_iterations: int = 10,
+        response_format: type | None = None,
+    ) -> Any:
+        """Build a compiled ReAct agent.
+
+        Args:
+            llm_config: Model configuration (provider, model, auth, etc.).
+            tools: Registered tools.
+            system_prompt: System prompt for the LLM.
+            max_iterations: Max ReAct loop iterations.
+            response_format: Optional Pydantic model for structured output.
+        Returns:
+            An opaque compiled object for ``invoke`` / ``stream``.
+        """
+        ...
+
+    @abc.abstractmethod
+    def invoke(
+        self,
+        compiled: Any,
+        message: str,
+        thread_id: str | None = None,
+        stream: bool = False,
+    ) -> BackendResult:
+        """Run the agent with a message.
+
+        Args:
+            compiled: Compiled agent from ``build_react``.
+            message: User input.
+            thread_id: Conversation thread ID (for checkpointing).
+            stream: If True, ``result.content`` is updated progressively.
+        """
+        ...
+
+    @abc.abstractmethod
+    def stream(
+        self,
+        compiled: Any,
+        message: str,
+        thread_id: str | None = None,
+    ) -> Any:
+        """Stream agent execution events."""
+        ...
+
+    # -- Multi-agent --
+
+    def build_supervisor(
+        self,
+        supervisor_config: ModelConfig,
+        workers: dict[str, Any],
+        supervisor_prompt: str | None = None,
+    ) -> Any:
+        """Build a supervisor/worker multi-agent system.
+
+        Falls back to ``DirectSupervisorGraph`` by default.
+        Override in backend-specific subclasses for deeper integration.
+        """
+        from rapidagent.backends.direct import DirectSupervisorGraph
+
+        return DirectSupervisorGraph(
+            supervisor_config=supervisor_config,
+            workers=workers,
+            supervisor_prompt=supervisor_prompt,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def get_default_backend() -> str:
+    if sys.version_info >= (3, 14):
+        return "direct"
+    return "langgraph"
+
+
+def create_backend(name: str | None = None, checkpoint_dir: str | None = None) -> Backend:
+    import warnings
+
+    name = name or get_default_backend()
+
+    if name == "langgraph":
+        try:
+            from rapidagent.backends.langgraph import LangGraphBackend
+
+            return LangGraphBackend(checkpoint_dir=checkpoint_dir)
+        except ImportError:
+            warnings.warn(
+                "LangGraph not installed. Falling back to 'direct'. "
+                "Install: pip install rapidagent[langgraph]",
+                stacklevel=2,
+            )
+            from rapidagent.backends.direct import DirectBackend
+            return DirectBackend(checkpoint_dir=checkpoint_dir)
+    elif name == "direct":
+        from rapidagent.backends.direct import DirectBackend
+        return DirectBackend(checkpoint_dir=checkpoint_dir)
+    else:
+        raise ValueError(f"Unknown backend: '{name}'. Supported: 'langgraph', 'direct'.")