aitextaroo 0.1.0__tar.gz

aitextaroo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rwcrabtree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aitextaroo-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: aitextaroo
+Version: 0.1.0
+Summary: Client library for AI Text-a-roo — give any AI agent a phone number
+Author-email: AI Text-a-roo <hello@aitextaroo.com>
+License: MIT
+Project-URL: Homepage, https://aitextaroo.com
+Project-URL: Documentation, https://github.com/rwfresh/aitextaroo-clients
+Project-URL: Repository, https://github.com/rwfresh/aitextaroo-clients
+Project-URL: Issues, https://github.com/rwfresh/aitextaroo-clients/issues
+Keywords: sms,ai,agent,chatbot,text-messaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: bridge
+Requires-Dist: pyyaml>=6.0; extra == "bridge"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# AI Text-a-roo
+
+Give any AI agent a phone number. In 60 seconds.
+
+```
+pip install aitextaroo
+```
+
+## What is this?
+
+[AI Text-a-roo](https://aitextaroo.com) is an SMS gateway for AI agents. You sign up, get a phone number, and your agent can send and receive text messages.
+
+This library connects your agent to the gateway. No webhook, no public IP, no server setup — just one outbound HTTPS connection.
+
+## Setup
+
+### Let your agent do it
+
+Tell your agent:
+
+> Go to aitextaroo.com and set up SMS for me.
+
+Your agent will find the setup instructions and handle everything.
+
+### Or use the CLI
+
+```bash
+# 1. Install
+pip install aitextaroo
+
+# 2. Verify your phone (sends a 6-digit code)
+aitextaroo-setup --phone +12125551234
+
+# 3. Enter the code, get your API key
+aitextaroo-setup --phone +12125551234 --code 123456
+
+# 4. Start the bridge
+aitextaroo-bridge --api-key YOUR_KEY
+```
+
+The bridge auto-detects your AI agent and starts piping SMS through it.
+
+Supported agents: `claude` (Claude Code), `hermes`, `openclaw`, `nanoclaw`.
+
+## How it works
+
+```
+Your phone                AI Text-a-roo              Your machine
+    │                         │                          │
+    ├── SMS "hey" ──────────► │                          │
+    │                         ├── SSE stream ──────────► │
+    │                         │                          ├── Agent processes
+    │                         │   POST /v1/send ◄────────┤   the message
+    │  ◄── SMS "hello!" ──────┤                          │
+    │                         │                          │
+```
+
+1. User texts your assigned number
+2. AI Text-a-roo pushes the message via SSE (Server-Sent Events)
+3. Your agent processes it and replies via `client.send()`
+4. The reply is delivered as SMS
+
+No polling. No webhooks. No public IP. Works behind NAT, firewalls, VPNs.
+
+## Features
+
+### Conversation history
+
+The bridge keeps conversation context in memory so your agent can have
+coherent multi-turn conversations over SMS. History is local — nothing
+is stored on our servers.
+
+### SMS formatting
+
+Agent responses are automatically cleaned for SMS — markdown bold,
+italic, code blocks, and headers are stripped to plain text.
+
+### SMS commands
+
+Your user can text these commands:
+
+| Command   | What it does                           |
+|-----------|----------------------------------------|
+| `/help`   | List available commands                |
+| `/new`    | Start a fresh conversation             |
+| `/status` | Show agent name, uptime, message count |
+
+## Python API
+
+### TextarooClient
+
+```python
+import asyncio
+from aitextaroo import TextarooClient
+
+async def main():
+    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}")
+
+asyncio.run(main())
+```
+
+#### `listen(auto_reconnect=True)` → `AsyncIterator[InboundMessage]`
+
+Opens an SSE stream and yields messages as they arrive. Handles reconnection automatically.
+
+#### `send(text)` → `str`
+
+Send an SMS to the registered user. Returns the message ID.
+
+#### `account()` → `dict`
+
+Get account info (tier, assigned number, usage).
+
+#### `close()`
+
+Release resources.
+
+### Signup API (static methods)
+
+```python
+# Send verification code
+await TextarooClient.request_verification(phone="+12125551234")
+
+# Confirm and get API key
+result = await TextarooClient.confirm_verification(phone="+12125551234", code="123456")
+print(result["api_key"])
+print(result["assigned_number"])
+```
+
+### InboundMessage
+
+| Field         | Type   | Description              |
+|---------------|--------|--------------------------|
+| `id`          | `str`  | Unique message ID (UUID) |
+| `text`        | `str`  | Message body             |
+| `received_at` | `str`  | ISO 8601 timestamp       |
+| `channel`     | `str`  | Always `"sms"`           |
+| `has_pin`     | `bool` | Whether sender has a PIN |
+
+## Privacy
+
+- Messages pass through and disappear — nothing is stored on our servers
+- Conversation history lives in your bridge process memory only
+- When the bridge stops, history is gone
+- Your phone number is hashed and encrypted at rest
+
+## Environment Variables
+
+| Variable              | Description                              |
+|-----------------------|------------------------------------------|
+| `AITEXTAROO_API_KEY`  | Your API key (alternative to `--api-key`) |
+| `AITEXTAROO_BASE_URL` | Custom API URL (for self-hosted)          |
+
+## License
+
+MIT

aitextaroo-0.1.0/README.md

@@ -0,0 +1,160 @@
+# AI Text-a-roo
+
+Give any AI agent a phone number. In 60 seconds.
+
+```
+pip install aitextaroo
+```
+
+## What is this?
+
+[AI Text-a-roo](https://aitextaroo.com) is an SMS gateway for AI agents. You sign up, get a phone number, and your agent can send and receive text messages.
+
+This library connects your agent to the gateway. No webhook, no public IP, no server setup — just one outbound HTTPS connection.
+
+## Setup
+
+### Let your agent do it
+
+Tell your agent:
+
+> Go to aitextaroo.com and set up SMS for me.
+
+Your agent will find the setup instructions and handle everything.
+
+### Or use the CLI
+
+```bash
+# 1. Install
+pip install aitextaroo
+
+# 2. Verify your phone (sends a 6-digit code)
+aitextaroo-setup --phone +12125551234
+
+# 3. Enter the code, get your API key
+aitextaroo-setup --phone +12125551234 --code 123456
+
+# 4. Start the bridge
+aitextaroo-bridge --api-key YOUR_KEY
+```
+
+The bridge auto-detects your AI agent and starts piping SMS through it.
+
+Supported agents: `claude` (Claude Code), `hermes`, `openclaw`, `nanoclaw`.
+
+## How it works
+
+```
+Your phone                AI Text-a-roo              Your machine
+    │                         │                          │
+    ├── SMS "hey" ──────────► │                          │
+    │                         ├── SSE stream ──────────► │
+    │                         │                          ├── Agent processes
+    │                         │   POST /v1/send ◄────────┤   the message
+    │  ◄── SMS "hello!" ──────┤                          │
+    │                         │                          │
+```
+
+1. User texts your assigned number
+2. AI Text-a-roo pushes the message via SSE (Server-Sent Events)
+3. Your agent processes it and replies via `client.send()`
+4. The reply is delivered as SMS
+
+No polling. No webhooks. No public IP. Works behind NAT, firewalls, VPNs.
+
+## Features
+
+### Conversation history
+
+The bridge keeps conversation context in memory so your agent can have
+coherent multi-turn conversations over SMS. History is local — nothing
+is stored on our servers.
+
+### SMS formatting
+
+Agent responses are automatically cleaned for SMS — markdown bold,
+italic, code blocks, and headers are stripped to plain text.
+
+### SMS commands
+
+Your user can text these commands:
+
+| Command   | What it does                           |
+|-----------|----------------------------------------|
+| `/help`   | List available commands                |
+| `/new`    | Start a fresh conversation             |
+| `/status` | Show agent name, uptime, message count |
+
+## Python API
+
+### TextarooClient
+
+```python
+import asyncio
+from aitextaroo import TextarooClient
+
+async def main():
+    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}")
+
+asyncio.run(main())
+```
+
+#### `listen(auto_reconnect=True)` → `AsyncIterator[InboundMessage]`
+
+Opens an SSE stream and yields messages as they arrive. Handles reconnection automatically.
+
+#### `send(text)` → `str`
+
+Send an SMS to the registered user. Returns the message ID.
+
+#### `account()` → `dict`
+
+Get account info (tier, assigned number, usage).
+
+#### `close()`
+
+Release resources.
+
+### Signup API (static methods)
+
+```python
+# Send verification code
+await TextarooClient.request_verification(phone="+12125551234")
+
+# Confirm and get API key
+result = await TextarooClient.confirm_verification(phone="+12125551234", code="123456")
+print(result["api_key"])
+print(result["assigned_number"])
+```
+
+### InboundMessage
+
+| Field         | Type   | Description              |
+|---------------|--------|--------------------------|
+| `id`          | `str`  | Unique message ID (UUID) |
+| `text`        | `str`  | Message body             |
+| `received_at` | `str`  | ISO 8601 timestamp       |
+| `channel`     | `str`  | Always `"sms"`           |
+| `has_pin`     | `bool` | Whether sender has a PIN |
+
+## Privacy
+
+- Messages pass through and disappear — nothing is stored on our servers
+- Conversation history lives in your bridge process memory only
+- When the bridge stops, history is gone
+- Your phone number is hashed and encrypted at rest
+
+## Environment Variables
+
+| Variable              | Description                              |
+|-----------------------|------------------------------------------|
+| `AITEXTAROO_API_KEY`  | Your API key (alternative to `--api-key`) |
+| `AITEXTAROO_BASE_URL` | Custom API URL (for self-hosted)          |
+
+## License
+
+MIT

aitextaroo-0.1.0/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-0.1.0/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)