aitextaroo 0.1.0__py3-none-any.whl

aitextaroo/__init__.py

@@ -0,0 +1,18 @@
+"""AI Text-a-roo — give any AI agent a phone number.
+
+Connect to the AI Text-a-roo SMS gateway to receive and send
+text messages through any AI agent framework.
+
+Example:
+    >>> from aitextaroo import TextarooClient
+    >>> client = TextarooClient(api_key="your-key")
+    >>> async for message in client.listen():
+    ...     print(f"Got: {message.text}")
+    ...     await client.send(f"You said: {message.text}")
+"""
+
+from aitextaroo.client import TextarooClient
+from aitextaroo.models import InboundMessage, StreamEvent
+
+__version__ = "0.1.0"
+__all__ = ["TextarooClient", "InboundMessage", "StreamEvent"]

aitextaroo/agents.py

@@ -0,0 +1,235 @@
+"""Agent abstraction for the AI Text-a-roo bridge.
+
+Defines how the bridge communicates with AI agents. Each agent
+takes a text message in and produces a text response.
+
+The only implementation today is CliAgent — a one-shot subprocess
+invocation per message. New agent types (HTTP API, long-running
+process, etc.) can be added by implementing the Agent protocol.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+# Maximum time to wait for an agent to respond (seconds).
+DEFAULT_TIMEOUT = 120
+
+
+class Agent(ABC):
+    """Interface for an AI agent that processes text messages.
+
+    Implementations must be able to:
+    1. Accept a text prompt and return a text response.
+    2. Provide a display name and optional system prompt.
+    3. Release any held resources on close.
+
+    The bridge reads system_prompt to build conversation context.
+    The agent receives the fully-assembled prompt — it does not
+    need to manage conversation state or system instructions.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable name for display and logging."""
+
+    @property
+    def system_prompt(self) -> str:
+        """System instructions prepended to every prompt by the bridge.
+
+        Override to provide agent-specific context (e.g., "respond
+        concisely, these are SMS messages"). Default is empty.
+        """
+        return ""
+
+    @abstractmethod
+    async def ask(self, text: str) -> str:
+        """Send a fully-assembled prompt and return the response.
+
+        The prompt already includes system instructions and
+        conversation history (assembled by the bridge). The agent
+        just needs to run it.
+
+        Args:
+            text: The complete prompt to send.
+
+        Returns:
+            The agent's response text.
+
+        Raises:
+            asyncio.TimeoutError: If the agent doesn't respond in time.
+            RuntimeError: If the agent process fails.
+        """
+
+    async def close(self) -> None:
+        """Release any resources held by this agent.
+
+        Default implementation does nothing. Override if your agent
+        holds open connections or processes.
+        """
+
+
+# ── CLI Agent ────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class CliAgentConfig:
+    """How to invoke a CLI agent.
+
+    Attributes:
+        name: Human-readable name (for logging and display).
+        command: Executable name (must be on PATH).
+        args: Arguments placed before the prompt.
+        system_prompt: Context the bridge prepends to prompts.
+        timeout: Max seconds to wait for a response.
+    """
+
+    name: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    system_prompt: str = ""
+    timeout: float = DEFAULT_TIMEOUT
+
+
+class CliAgent(Agent):
+    """Runs a CLI agent as a one-shot subprocess per message.
+
+    Each call to ask() spawns a fresh process:
+        {command} {args} "{prompt}"
+
+    Stdout is captured as the response. Stderr is logged on failure.
+    This is the simplest and most reliable approach — no process
+    lifecycle management, no stdin/stdout protocol, no state leaks.
+
+    The agent receives the complete prompt from the bridge. It does
+    not manage system prompts or conversation context — that's the
+    bridge's responsibility.
+
+    Args:
+        config: How to invoke the agent CLI.
+    """
+
+    def __init__(self, config: CliAgentConfig) -> None:
+        self._config = config
+
+    @property
+    def name(self) -> str:
+        return self._config.name
+
+    @property
+    def system_prompt(self) -> str:
+        return self._config.system_prompt
+
+    async def ask(self, text: str) -> str:
+        """Spawn the agent CLI with the prompt and return its output."""
+        cmd = [self._config.command, *self._config.args, text]
+
+        logger.debug("Running: %s %s '%s...'", cmd[0], " ".join(cmd[1:-1]), text[:40])
+
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=self._config.timeout,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise
+
+        if process.returncode != 0:
+            error_text = stderr.decode(errors="replace")[:200]
+            logger.warning(
+                "Agent %s exited with code %d: %s",
+                self._config.name, process.returncode, error_text,
+            )
+
+        return stdout.decode(errors="replace").strip()
+
+
+# ── Agent Registry ───────────────────────────────────────────────
+
+# Built-in agent configurations. Each entry defines how to invoke
+# a known CLI agent. The bridge uses these to auto-detect and
+# instantiate agents.
+#
+# To add a new agent: add an entry here and it works automatically.
+# No other code changes needed.
+
+BUILTIN_AGENTS: dict[str, CliAgentConfig] = {
+    "claude": CliAgentConfig(
+        name="Claude Code",
+        command="claude",
+        args=["-p"],
+        system_prompt=(
+            "You are receiving SMS text messages from a user. "
+            "Respond concisely — these are text messages with a 1600 character limit."
+        ),
+    ),
+    "hermes": CliAgentConfig(
+        name="Hermes",
+        command="hermes",
+        args=["--pipe"],
+        system_prompt=(
+            "You are receiving SMS text messages from a user via AI Text-a-roo. "
+            "Respond conversationally. Keep responses concise — they're text messages."
+        ),
+    ),
+    "openclaw": CliAgentConfig(
+        name="OpenClaw",
+        command="openclaw",
+        args=["--pipe"],
+        system_prompt="You are receiving SMS text messages. Respond concisely.",
+    ),
+    "nanoclaw": CliAgentConfig(
+        name="NanoClaw",
+        command="nanoclaw",
+        args=["--pipe"],
+        system_prompt="You are receiving SMS text messages. Respond concisely.",
+    ),
+}
+
+
+def detect_agents() -> list[str]:
+    """Find which supported agents are installed on this system.
+
+    Returns:
+        Agent names found on PATH, in preference order.
+    """
+    found = []
+    for name, config in BUILTIN_AGENTS.items():
+        if shutil.which(config.command):
+            found.append(name)
+            logger.debug("Detected agent: %s (%s)", config.name, config.command)
+    return found
+
+
+def create_agent(name: str) -> CliAgent:
+    """Create an agent instance by name.
+
+    Args:
+        name: Key in BUILTIN_AGENTS (e.g., "claude", "hermes").
+
+    Returns:
+        A ready-to-use CliAgent.
+
+    Raises:
+        ValueError: If the agent name is not recognized.
+    """
+    config = BUILTIN_AGENTS.get(name)
+    if config is None:
+        available = ", ".join(BUILTIN_AGENTS.keys())
+        raise ValueError(f"Unknown agent: {name!r}. Available: {available}")
+    return CliAgent(config)

aitextaroo/bridge.py

@@ -0,0 +1,157 @@
+"""SMS-to-agent bridge for AI Text-a-roo.
+
+Connects to the AI Text-a-roo SSE stream, forwards inbound SMS
+messages to a local AI agent (with conversation context), and sends
+the agent's formatted responses back as SMS.
+
+This module is orchestration — it delegates to:
+- agents.py for agent communication
+- conversation.py for history management
+- commands.py for /slash command handling
+- formatting.py for SMS-friendly output
+- client.py for API communication
+"""
+
+from __future__ import annotations
+
+import logging
+
+from aitextaroo.agents import Agent
+from aitextaroo.client import TextarooClient
+from aitextaroo.commands import CommandRouter
+from aitextaroo.conversation import Conversation
+from aitextaroo.formatting import format_for_sms
+from aitextaroo.models import InboundMessage
+
+logger = logging.getLogger(__name__)
+
+# SMS character limit. Responses exceeding this are truncated.
+MAX_SMS_LENGTH = 1600
+
+
+class Bridge:
+    """Bridges SMS messages between AI Text-a-roo and a local AI agent.
+
+    The bridge's message flow:
+    1. Receive inbound SMS via SSE stream.
+    2. If it's a /command, handle locally (no agent call).
+    3. Otherwise, build full prompt (system + history + message).
+    4. Send to agent, get response.
+    5. Record both messages in conversation history.
+    6. Format the response for SMS and send it back.
+
+    The bridge owns prompt construction — the agent just receives
+    a complete prompt and returns a response. This keeps system
+    prompt and conversation context management in one place.
+
+    Args:
+        client: An authenticated TextarooClient.
+        agent: An Agent implementation that processes messages.
+        max_history: Max messages to keep in conversation context.
+    """
+
+    def __init__(
+        self,
+        client: TextarooClient,
+        agent: Agent,
+        max_history: int = 20,
+    ) -> None:
+        self._client = client
+        self._agent = agent
+        self._conversation = Conversation(max_messages=max_history)
+        self._commands = CommandRouter(
+            agent_name=agent.name,
+            conversation=self._conversation,
+        )
+
+    async def run(self) -> None:
+        """Listen for SMS and bridge them to the agent.
+
+        Runs indefinitely. The TextarooClient handles SSE reconnection
+        automatically. Call this from asyncio.run() or as a task.
+        """
+        try:
+            async for message in self._client.listen():
+                await self._handle(message)
+        finally:
+            await self._agent.close()
+            await self._client.close()
+
+    async def _handle(self, message: InboundMessage) -> None:
+        """Route an inbound SMS to commands or the agent."""
+        text = message.text.strip()
+
+        if self._commands.is_command(text):
+            response = self._commands.handle(text)
+            await self._send(response)
+            return
+
+        await self._handle_conversation(message.id, text)
+
+    async def _handle_conversation(self, message_id: str, text: str) -> None:
+        """Build prompt, call agent, record history, send reply."""
+        logger.info("Inbound SMS [%s]: %s", message_id, text[:50])
+
+        prompt = self._build_prompt(text)
+
+        # Call the agent
+        try:
+            response = await self._agent.ask(prompt)
+        except TimeoutError:
+            logger.error("Agent timed out on message %s", message_id)
+            await self._send("Sorry, I took too long to respond. Try again?")
+            return
+        except Exception:
+            logger.exception("Agent error on message %s", message_id)
+            await self._send("Sorry, something went wrong. Try again?")
+            return
+
+        if not response:
+            logger.warning("Agent returned empty response for %s", message_id)
+            return
+
+        # Record both sides only after a successful response.
+        # This keeps history balanced — no orphaned user messages.
+        self._conversation.add_user_message(text)
+        self._conversation.add_assistant_message(response)
+        self._commands.increment_message_count()
+
+        # Format for SMS and send
+        formatted = format_for_sms(response)
+        if len(formatted) > MAX_SMS_LENGTH:
+            formatted = formatted[: MAX_SMS_LENGTH - 3] + "..."
+            logger.warning("Response truncated to %d chars", MAX_SMS_LENGTH)
+
+        await self._send(formatted)
+        logger.info("Reply sent for %s", message_id)
+
+    def _build_prompt(self, text: str) -> str:
+        """Assemble the complete prompt: system + history + new message.
+
+        The bridge owns prompt construction so that system instructions
+        and conversation context are always included, regardless of
+        which agent is being used or how many messages have been sent.
+        """
+        parts: list[str] = []
+
+        # System prompt — always included so the agent stays in character
+        system = self._agent.system_prompt
+        if system:
+            parts.append(f"[System]\n{system}")
+
+        # Conversation history — provides multi-turn context
+        context = self._conversation.format_as_context()
+        if context:
+            parts.append(context)
+
+        # The new message
+        parts.append(f"[New message]\nUser: {text}")
+
+        return "\n\n".join(parts)
+
+    async def _send(self, text: str) -> None:
+        """Send a reply, logging but not raising on failure."""
+        try:
+            await self._client.send(text)
+        except Exception:
+            logger.exception("Failed to send reply")

aitextaroo/cli.py

@@ -0,0 +1,108 @@
+"""CLI entry point for the AI Text-a-roo bridge.
+
+Usage:
+    aitextaroo-bridge --api-key YOUR_KEY
+    aitextaroo-bridge --api-key YOUR_KEY --agent claude
+    AITEXTAROO_API_KEY=your_key aitextaroo-bridge
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import sys
+
+from aitextaroo.agents import BUILTIN_AGENTS, create_agent, detect_agents
+from aitextaroo.bridge import Bridge
+from aitextaroo.client import TextarooClient
+
+
+def main() -> None:
+    """Parse arguments, wire dependencies, run the bridge."""
+    args = _parse_args()
+    _configure_logging(args.verbose)
+
+    api_key = args.api_key
+    if not api_key:
+        _exit_error("API key required. Use --api-key or set AITEXTAROO_API_KEY.")
+
+    agent_name = _resolve_agent(args.agent)
+
+    # Wire dependencies
+    client = TextarooClient(api_key=api_key, base_url=args.base_url)
+    agent = create_agent(agent_name)
+    bridge = Bridge(client=client, agent=agent)
+
+    print(f"Starting bridge with {agent.name}...")
+    print("Listening for SMS messages. Ctrl+C to stop.")
+
+    try:
+        asyncio.run(bridge.run())
+    except KeyboardInterrupt:
+        print("\nBridge stopped.")
+
+
+def _parse_args() -> argparse.Namespace:
+    """Build and parse CLI arguments."""
+    parser = argparse.ArgumentParser(
+        prog="aitextaroo-bridge",
+        description="Bridge SMS messages to your AI agent. Your agent gets a phone number.",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=os.environ.get("AITEXTAROO_API_KEY", ""),
+        help="AI Text-a-roo API key (or set AITEXTAROO_API_KEY env var)",
+    )
+    parser.add_argument(
+        "--agent",
+        choices=["auto", *BUILTIN_AGENTS.keys()],
+        default="auto",
+        help="Which agent to use (default: auto-detect)",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("AITEXTAROO_BASE_URL", "https://api.aitextaroo.com"),
+        help="API base URL (default: https://api.aitextaroo.com)",
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    return parser.parse_args()
+
+
+def _configure_logging(verbose: bool) -> None:
+    """Set up logging for the bridge process."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def _resolve_agent(choice: str) -> str:
+    """Resolve 'auto' to a detected agent name, or validate the explicit choice."""
+    if choice != "auto":
+        return choice
+
+    agents = detect_agents()
+    if not agents:
+        _exit_error(
+            "No supported AI agent found on PATH. Install one of:\n"
+            + "".join(f"  - {name}\n" for name in BUILTIN_AGENTS)
+        )
+    print(f"Auto-detected agent: {agents[0]}")
+    return agents[0]
+
+
+def _exit_error(message: str) -> None:
+    """Print error to stderr and exit."""
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()