chatflow-agent 0.1.0__py3-none-any.whl

chatflow_agent/__init__.py

@@ -0,0 +1,57 @@
+"""chatflow-agent: Lightweight, async multi-agent framework with native handoffs."""
+
+from chatflow_agent.channels.base import BaseChannel, ChannelError
+from chatflow_agent.channels.cli import CLIChannel
+from chatflow_agent.channels.telegram import TelegramChannel
+from chatflow_agent.channels.whatsapp import WhatsAppChannel
+from chatflow_agent.core.agent import Agent
+from chatflow_agent.core.engines import AnthropicEngine, BaseEngine, GeminiEngine, OpenAIEngine
+from chatflow_agent.core.memory import SessionContext, SessionStore
+from chatflow_agent.core.runner import Runner
+from chatflow_agent.core.tools import Tool, tool
+from chatflow_agent.exceptions import (
+    AgentHandoffError,
+    ChatFlowError,
+    DependencyError,
+    ProviderError,
+    ToolExecutionError,
+)
+from chatflow_agent.types import (
+    AgentResponse,
+    Handoff,
+    Message,
+    Role,
+    ToolCall,
+    ToolResult,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    "Agent",
+    "AgentResponse",
+    "BaseChannel",
+    "ChannelError",
+    "CLIChannel",
+    "AnthropicEngine",
+    "BaseEngine",
+    "GeminiEngine",
+    "OpenAIEngine",
+    "Handoff",
+    "Message",
+    "Role",
+    "Runner",
+    "SessionContext",
+    "SessionStore",
+    "TelegramChannel",
+    "Tool",
+    "tool",
+    "ToolCall",
+    "ToolResult",
+    "WhatsAppChannel",
+    "ChatFlowError",
+    "DependencyError",
+    "ToolExecutionError",
+    "AgentHandoffError",
+    "ProviderError",
+]

chatflow_agent/channels/__init__.py

@@ -0,0 +1,14 @@
+"""Communication channels for chatflow-agent: CLI, WhatsApp, Telegram, and Webhook."""
+
+from chatflow_agent.channels.base import BaseChannel, ChannelError
+from chatflow_agent.channels.cli import CLIChannel
+from chatflow_agent.channels.telegram import TelegramChannel
+from chatflow_agent.channels.whatsapp import WhatsAppChannel
+
+__all__ = [
+    "BaseChannel",
+    "CLIChannel",
+    "ChannelError",
+    "TelegramChannel",
+    "WhatsAppChannel",
+]

chatflow_agent/channels/base.py

@@ -0,0 +1,58 @@
+"""Abstract BaseChannel definition for chatflow-agent."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from chatflow_agent.core.runner import Runner
+from chatflow_agent.exceptions import ChatFlowError
+from chatflow_agent.types import AgentResponse
+
+
+class ChannelError(ChatFlowError):
+    """Raised when an operation on a channel fails or runner is detached."""
+
+
+class BaseChannel(ABC):
+    """Abstract base class for all communication channels (CLI, WhatsApp, Telegram, Webhook)."""
+
+    def __init__(self) -> None:
+        self.runner: Runner | None = None
+
+    def attach(self, runner: Runner) -> "BaseChannel":
+        """Attach a multi-agent Runner instance to this channel."""
+        self.runner = runner
+        return self
+
+    def _ensure_runner_attached(self) -> Runner:
+        """Validate that a runner is properly bound."""
+        if not self.runner:
+            raise ChannelError(
+                f"No Runner is attached to channel '{self.__class__.__name__}'. "
+                "Call 'channel.attach(runner)' before running or dispatching messages."
+            )
+        return self.runner
+
+    async def dispatch_async(
+        self,
+        session_id: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> AgentResponse:
+        """Forward an incoming message to the attached runner asynchronously."""
+        runner = self._ensure_runner_attached()
+        return await runner.run_async(session_id, message, metadata=metadata)
+
+    def dispatch(
+        self,
+        session_id: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> AgentResponse:
+        """Forward an incoming message to the attached runner synchronously."""
+        runner = self._ensure_runner_attached()
+        return runner.run(session_id, message, metadata=metadata)
+
+    @abstractmethod
+    def run(self, **kwargs: Any) -> None:
+        """Start listening for incoming messages or launch the channel event loop."""
+        pass

chatflow_agent/channels/cli.py

@@ -0,0 +1,62 @@
+"""Interactive Command-Line Interface (CLI) channel for chatflow-agent."""
+
+import sys
+from typing import Any
+
+from chatflow_agent.channels.base import BaseChannel
+from chatflow_agent.types import AgentResponse
+
+
+class CLIChannel(BaseChannel):
+    """Terminal-based interactive channel for real-time multi-agent testing and debugging."""
+
+    def __init__(
+        self,
+        session_id: str = "cli_user",
+        prompt_prefix: str = "\nYou: ",
+    ) -> None:
+        super().__init__()
+        self.session_id = session_id
+        self.prompt_prefix = prompt_prefix
+
+    def send_message(self, text: str) -> AgentResponse:
+        """Convenience method to dispatch a single message synchronously."""
+        return self.dispatch(self.session_id, text)
+
+    def run(self, **kwargs: Any) -> None:
+        """Start an interactive terminal conversation session."""
+        runner = self._ensure_runner_attached()
+
+        print("=" * 65)
+        print(f"ChatFlow CLI Session Started [Starting: {runner.starting_agent.name}]")
+        print("Type 'exit', 'quit' or 'salir' to end the session.")
+        print("=" * 65)
+
+        while True:
+            try:
+                user_input = input(self.prompt_prefix).strip()
+            except (KeyboardInterrupt, EOFError):
+                print("\n\nSession ended by user.")
+                break
+
+            if not user_input:
+                continue
+
+            if user_input.lower() in ("exit", "quit", "salir"):
+                print("\nGoodbye!")
+                break
+
+            # Dispatch to runner
+            try:
+                response = self.dispatch(self.session_id, user_input)
+                # Show handoff indicator if a transfer occurred
+                if response.handoff:
+                    print(f"[Transferred to {response.handoff.target_agent_name}]")
+                    if response.handoff.reason:
+                        print(f"   Reason: {response.handoff.reason}")
+
+                # Print final text response
+                print(f"\n[{response.active_agent_name}]: {response.content}")
+
+            except Exception as err:
+                print(f"\nError during processing: {err}", file=sys.stderr)

chatflow_agent/channels/telegram.py

@@ -0,0 +1,115 @@
+"""Telegram channel adapter using python-telegram-bot."""
+
+import logging
+from typing import Any
+
+from chatflow_agent.channels.base import BaseChannel
+from chatflow_agent.exceptions import DependencyError
+from chatflow_agent.types import AgentResponse
+
+logger = logging.getLogger("chatflow_agent.telegram")
+
+
+class TelegramChannel(BaseChannel):
+    """Telegram bot integration supporting async polling and multi-agent dispatching."""
+
+    def __init__(
+        self,
+        token: str,
+        start_message: str = "Hello! I am your AI multi-agent assistant. How can I help you today?",
+        fallback_message: str = (
+            "Disculpa, ocurrió un inconveniente al procesar tu solicitud. "
+            "Por favor intenta nuevamente en unos momentos."
+        ),
+        allowed_updates: list[str] | None = None,
+    ) -> None:
+        super().__init__()
+        self.token = token
+        self.start_message = start_message
+        self.fallback_message = fallback_message
+        self.allowed_updates = allowed_updates
+
+        # Verify optional dependencies
+        try:
+            from telegram import Update
+            from telegram.constants import ChatAction
+            from telegram.ext import Application, filters
+        except ImportError as err:
+            raise DependencyError(
+                feature="TelegramChannel",
+                extra_package="telegram",
+            ) from err
+
+        self._update_cls = Update
+        self._action_cls = ChatAction
+        self._filters = filters
+
+        # Initialize python-telegram-bot application
+        self.app = Application.builder().token(self.token).build()
+        self._setup_handlers()
+
+    def _setup_handlers(self) -> None:
+        """Register Telegram command and message handlers."""
+        from telegram.ext import CommandHandler, MessageHandler, filters
+
+        self.app.add_handler(CommandHandler("start", self._handle_start))
+        self.app.add_handler(CommandHandler("reset", self._handle_reset))
+        self.app.add_handler(
+            MessageHandler(filters.TEXT & ~filters.COMMAND, self._handle_message)
+        )
+
+    async def _handle_start(self, update: Any, context: Any) -> None:
+        """Respond to /start command."""
+        if update.message:
+            await update.message.reply_text(self.start_message)
+
+    async def _handle_reset(self, update: Any, context: Any) -> None:
+        """Clear memory for current chat via /reset command."""
+        if not update.effective_chat or not update.message:
+            return
+
+        chat_id = str(update.effective_chat.id)
+        if self.runner:
+            session = self.runner.get_session(chat_id)
+            if session:
+                session.clear_history()
+        await update.message.reply_text("Conversation memory has been reset.")
+
+    async def _handle_message(self, update: Any, context: Any) -> None:
+        """Process standard incoming text messages from Telegram with error resilience."""
+        if not update.effective_chat or not update.message or not update.message.text:
+            return
+
+        chat_id = str(update.effective_chat.id)
+        user_text = update.message.text
+        user_name = update.effective_user.username if update.effective_user else None
+
+        # Display typing indicator while processing
+        try:
+            await context.bot.send_chat_action(
+                chat_id=update.effective_chat.id,
+                action=self._action_cls.TYPING,
+            )
+        except Exception:
+            pass
+
+        try:
+            response: AgentResponse = await self.dispatch_async(
+                session_id=chat_id,
+                message=user_text,
+                metadata={
+                    "channel": "telegram",
+                    "chat_id": chat_id,
+                    "username": user_name,
+                },
+            )
+            await update.message.reply_text(response.content)
+        except Exception as err:
+            logger.error(f"Error processing Telegram message: {err}")
+            await update.message.reply_text(self.fallback_message)
+
+    def run(self, **kwargs: Any) -> None:
+        """Start polling for Telegram updates."""
+        self._ensure_runner_attached()
+        logger.info("Starting Telegram bot polling...")
+        self.app.run_polling(allowed_updates=self.allowed_updates, **kwargs)

chatflow_agent/channels/whatsapp.py

@@ -0,0 +1,213 @@
+"""WhatsApp channel adapter using FastAPI and Meta Cloud API webhooks."""
+
+import logging
+from typing import Any
+
+from chatflow_agent.channels.base import BaseChannel
+from chatflow_agent.exceptions import DependencyError
+from chatflow_agent.types import AgentResponse
+
+logger = logging.getLogger("chatflow_agent.whatsapp")
+
+
+class WhatsAppChannel(BaseChannel):
+    """WhatsApp integration supporting Meta Cloud API and generic webhooks with resilience."""
+
+    def __init__(
+        self,
+        verify_token: str,
+        access_token: str | None = None,
+        phone_number_id: str | None = None,
+        api_version: str = "v21.0",
+        fallback_message: str = (
+            "Disculpa, estamos experimentando una demora temporal con nuestro servicio. "
+            "Por favor intenta nuevamente en unos momentos."
+        ),
+        unsupported_media_message: str = (
+            "Por el momento solo puedo procesar mensajes de texto."
+        ),
+    ) -> None:
+        super().__init__()
+        self.verify_token = verify_token
+        self.access_token = access_token
+        self.phone_number_id = phone_number_id
+        self.api_version = api_version
+        self.fallback_message = fallback_message
+        self.unsupported_media_message = unsupported_media_message
+
+        # Verify optional dependencies
+        try:
+            import httpx
+            import uvicorn
+            from fastapi import FastAPI
+        except ImportError as err:
+            raise DependencyError(
+                feature="WhatsAppChannel",
+                extra_package="whatsapp",
+            ) from err
+
+        self._httpx = httpx
+        self._uvicorn = uvicorn
+        self.app = FastAPI(title="ChatFlow WhatsApp Webhook Server")
+        self._setup_routes()
+
+    def _setup_routes(self) -> None:
+        """Register webhook endpoints on the FastAPI application."""
+        from fastapi import HTTPException, Query, Request, Response, status
+        from fastapi.responses import JSONResponse, PlainTextResponse
+
+        @self.app.get("/health")
+        async def health_check() -> dict[str, str]:
+            return {"status": "healthy", "channel": "whatsapp"}
+
+        @self.app.get("/webhook")
+        async def verify_webhook(
+            request: Request,
+            hub_mode: str | None = Query(None, alias="hub.mode"),
+            hub_challenge: str | None = Query(None, alias="hub.challenge"),
+            hub_verify_token: str | None = Query(None, alias="hub.verify_token"),
+        ) -> Response:
+            """Meta webhook verification challenge endpoint."""
+            if hub_mode == "subscribe" and hub_verify_token == self.verify_token:
+                logger.info("WhatsApp webhook verified successfully.")
+                return PlainTextResponse(content=hub_challenge or "")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Verification token mismatch",
+            )
+
+        @self.app.post("/webhook")
+        async def handle_incoming_message(request: Request) -> Response:
+            """Process incoming WhatsApp message events with anti-500 error shield."""
+            payload = await request.json()
+            extracted = self._extract_message_and_sender(payload)
+
+            if not extracted:
+                # Return 200 to acknowledge status notifications (delivered, read, etc.)
+                return JSONResponse(content={"status": "ignored_or_status_update"})
+
+            sender_phone, user_text = extracted
+
+            # 1. Handle non-text media (audios, images, stickers, documents)
+            if user_text is None:
+                if self.access_token and self.phone_number_id:
+                    await self._send_outbound_whatsapp(
+                        to_phone=sender_phone, text=self.unsupported_media_message
+                    )
+                return JSONResponse(
+                    content={
+                        "status": "unsupported_media_handled",
+                        "sender": sender_phone,
+                        "reply": self.unsupported_media_message,
+                    }
+                )
+
+            # 2. Process message through attached runner with anti-500 error shield
+            reply_text: str
+            active_agent: str
+            try:
+                response: AgentResponse = await self.dispatch_async(
+                    session_id=sender_phone,
+                    message=user_text,
+                    metadata={"channel": "whatsapp", "phone": sender_phone},
+                )
+                reply_text = response.content
+                active_agent = response.active_agent_name
+            except Exception as err:
+                logger.error(f"Error dispatching WhatsApp message from {sender_phone}: {err}")
+                reply_text = self.fallback_message
+                active_agent = "fallback"
+
+            # If Meta credentials are provided, send outbound reply to WhatsApp API
+            if self.access_token and self.phone_number_id:
+                await self._send_outbound_whatsapp(
+                    to_phone=sender_phone, text=reply_text
+                )
+
+            # Always return HTTP 200 to Meta to avoid retry storms
+            return JSONResponse(
+                content={
+                    "status": "success",
+                    "sender": sender_phone,
+                    "reply": reply_text,
+                    "active_agent": active_agent,
+                }
+            )
+
+    def _extract_message_and_sender(
+        self, payload: dict[str, Any]
+    ) -> tuple[str, str | None] | None:
+        """Extract sender phone number and message from payload.
+
+        Returns:
+            (phone, text) for text messages.
+            (phone, None) for non-text media messages.
+            None for status updates or empty payloads.
+        """
+        # 1. Standard Meta Cloud API webhook format
+        entry = payload.get("entry")
+        if isinstance(entry, list) and entry:
+            changes = entry[0].get("changes")
+            if isinstance(changes, list) and changes:
+                value = changes[0].get("value", {})
+                messages = value.get("messages")
+                if isinstance(messages, list) and messages:
+                    msg = messages[0]
+                    sender = msg.get("from")
+                    if not sender:
+                        return None
+
+                    msg_type = msg.get("type", "text")
+                    if msg_type == "text":
+                        text = msg.get("text", {}).get("body")
+                        if text:
+                            return str(sender), str(text)
+                    # Non-text media message received
+                    return str(sender), None
+
+        # 2. Generic / Evolution API webhook format
+        sender = (
+            payload.get("phone")
+            or payload.get("from")
+            or payload.get("sender")
+        )
+        if sender:
+            text = (
+                payload.get("message")
+                or payload.get("text")
+                or payload.get("body")
+            )
+            if text:
+                return str(sender), str(text)
+            return str(sender), None
+
+        return None
+
+    async def _send_outbound_whatsapp(self, to_phone: str, text: str) -> None:
+        """Send message back to user via Meta WhatsApp Cloud API."""
+        url = f"https://graph.facebook.com/{self.api_version}/{self.phone_number_id}/messages"
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+        body = {
+            "messaging_product": "whatsapp",
+            "to": to_phone,
+            "type": "text",
+            "text": {"body": text},
+        }
+
+        try:
+            async with self._httpx.AsyncClient() as client:
+                res = await client.post(url, json=body, headers=headers, timeout=10.0)
+                if res.status_code >= 400:
+                    logger.error(
+                        f"Failed to send outbound WhatsApp message: {res.status_code} - {res.text}"
+                    )
+        except Exception as err:
+            logger.error(f"Error calling WhatsApp Cloud API: {err}")
+
+    def run(self, host: str = "0.0.0.0", port: int = 8000, **kwargs: Any) -> None:
+        """Launch the FastAPI webhook server using uvicorn."""
+        self._ensure_runner_attached()
+        self._uvicorn.run(self.app, host=host, port=port, **kwargs)

chatflow_agent/core/__init__.py

@@ -0,0 +1,18 @@
+"""Core modules for chatflow-agent: tools, memory, agents, engine, and runner."""
+
+from chatflow_agent.core.agent import Agent
+from chatflow_agent.core.engine import EngineTurnResult, GeminiEngine
+from chatflow_agent.core.memory import SessionContext, SessionStore
+from chatflow_agent.core.runner import Runner
+from chatflow_agent.core.tools import Tool, tool
+
+__all__ = [
+    "Agent",
+    "EngineTurnResult",
+    "GeminiEngine",
+    "Runner",
+    "SessionContext",
+    "SessionStore",
+    "Tool",
+    "tool",
+]

chatflow_agent/core/agent.py

@@ -0,0 +1,135 @@
+"""Agent abstraction and peer handoff orchestration for chatflow-agent."""
+
+import re
+from collections.abc import Callable
+from typing import Any
+
+from chatflow_agent.core.tools import Tool
+from chatflow_agent.types import Handoff
+
+
+def _sanitize_tool_name(name: str) -> str:
+    """Convert an agent name into a valid tool identifier (alphanumeric and underscores)."""
+    clean = re.sub(r"[^a-zA-Z0-9_]", "_", name.strip().lower())
+    clean = re.sub(r"_+", "_", clean).strip("_")
+    return f"transfer_to_{clean}"
+
+
+class Agent:
+    """Represents an autonomous specialized agent with its own tools and peer handoffs."""
+
+    def __init__(
+        self,
+        name: str,
+        instructions: str | Callable[[], str],
+        model: str = "gemini-2.5-flash",
+        tools: list[Tool | Callable[..., Any]] | None = None,
+        handoffs: list["Agent"] | None = None,
+        provider: str | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        engine: Any | None = None,
+    ) -> None:
+        self.name = name
+        self.instructions = instructions
+        self.model = model
+        self.provider = provider
+        self.base_url = base_url
+        self.api_key = api_key
+        self.engine = engine
+        self.tools: list[Tool] = []
+        self.handoffs: list[Agent] = []
+
+        if tools:
+            for t in tools:
+                self.add_tool(t)
+
+        if handoffs:
+            for h in handoffs:
+                self.add_handoff(h)
+
+    def get_instructions(self) -> str:
+        """Resolve and return the system instructions."""
+        if callable(self.instructions):
+            return self.instructions()
+        return self.instructions
+
+    def add_tool(self, tool_or_callable: Tool | Callable[..., Any]) -> Tool:
+        """Register a tool or callable to this agent."""
+        if isinstance(tool_or_callable, Tool):
+            t = tool_or_callable
+        else:
+            t = Tool(tool_or_callable)
+
+        # Avoid duplicate tools by name
+        self.tools = [existing for existing in self.tools if existing.name != t.name]
+        self.tools.append(t)
+        return t
+
+    def tool(
+        self,
+        name_or_func: str | Callable[..., Any] | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> Any:
+        """Decorator to register a tool directly onto this agent instance.
+
+        Usage:
+            @agent.tool
+            def query_db(id: int) -> dict: ...
+
+            @agent.tool(name="custom_query", description="Fetch db row")
+            def query_db(id: int) -> dict: ...
+        """
+        if callable(name_or_func):
+            t = Tool(name_or_func)
+            self.add_tool(t)
+            return t
+
+        def decorator(fn: Callable[..., Any]) -> Tool:
+            tool_name = name or (name_or_func if isinstance(name_or_func, str) else None)
+            t = Tool(fn, name=tool_name, description=description)
+            self.add_tool(t)
+            return t
+
+        return decorator
+
+    def add_handoff(self, target_agent: "Agent") -> None:
+        """Register a peer agent to which this agent can hand off dialogue."""
+        if target_agent.name == self.name:
+            raise ValueError(f"Agent '{self.name}' cannot register a handoff to itself.")
+
+        # Avoid duplicates
+        self.handoffs = [h for h in self.handoffs if h.name != target_agent.name]
+        self.handoffs.append(target_agent)
+
+    def _create_handoff_tool(self, target_agent: "Agent") -> Tool:
+        """Generate a synthetic routing tool that transfers control to target_agent."""
+        tool_name = _sanitize_tool_name(target_agent.name)
+        desc = (
+            f"Hand off the dialogue to '{target_agent.name}'. "
+            f"Target agent specialty: {target_agent.get_instructions()[:120]}..."
+        )
+
+        def handoff_executor(reason: str | None = None) -> Handoff:
+            """Transfer the conversation to another specialized agent."""
+            return Handoff(
+                target_agent_name=target_agent.name,
+                reason=reason,
+            )
+
+        return Tool(func=handoff_executor, name=tool_name, description=desc)
+
+    def get_all_tools(self) -> list[Tool]:
+        """Return all user tools combined with synthetic handoff tools."""
+        combined: list[Tool] = list(self.tools)
+        for peer in self.handoffs:
+            combined.append(self._create_handoff_tool(peer))
+        return combined
+
+    def __repr__(self) -> str:
+        return (
+            f"<Agent name={self.name!r} model={self.model!r} "
+            f"tools={len(self.tools)} handoffs={len(self.handoffs)}>"
+        )

chatflow_agent/core/engine.py

@@ -0,0 +1,5 @@
+"""Backward-compatible re-exports for chatflow_agent.core.engine."""
+
+from chatflow_agent.core.engines import BaseEngine, EngineTurnResult, GeminiEngine
+
+__all__ = ["BaseEngine", "EngineTurnResult", "GeminiEngine"]