wirebox 0.2.0__tar.gz → 0.4.0__tar.gz

{wirebox-0.2.0 → wirebox-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wirebox
-Version: 0.2.0
+Version: 0.4.0
 Summary: Official Python SDK for Wirebox — Real-world identity and communication layer for AI agents
 Project-URL: Homepage, https://wirebox.sh
 Project-URL: Documentation, https://docs.wirebox.sh

wirebox-0.4.0/examples/auto_reply.py

@@ -0,0 +1,155 @@
+"""Wirebox Python SDK — Autonomous Auto-Reply Agent Example.
+
+Demonstrates:
+1. Resolving the active AgentIdentity with zero-config credentials
+2. Ensuring an agent-scoped webhook subscription is active
+3. Connecting an in-memory WebSocket reverse-proxy tunnel
+4. Intercepting "email.received" events in process memory
+5. Automatically dispatching a threaded reply via agent.reply_email()
+
+Usage:
+    python examples/auto_reply.py
+    python examples/auto_reply.py --once   # Connects, verifies health ping, and exits cleanly
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import sys
+
+import httpx
+
+from wirebox import AsyncWirebox
+from wirebox.exceptions import WireboxAPIError
+
+
+async def main() -> None:
+    once_mode = "--once" in sys.argv
+
+    print("=" * 64)
+    print("  Wirebox Python SDK — Autonomous Auto-Reply Agent")
+    print("========================================================\n")
+
+    async with AsyncWirebox() as client:
+        agent = await client.get_identity()
+
+        print(f"Agent Handle:    @{agent.agent_handle}")
+        print(f"Display Name:    {agent.display_name or 'N/A'}")
+        print(f"Mailbox Address: {agent.mailbox.email_address}")
+        print(f"Tunnel URL:      {agent.tunnel.public_url}")
+
+        target_endpoint = f"{agent.tunnel.public_url}/webhook"
+
+        # 1. Ensure webhook subscription exists
+        webhooks = await agent.list_webhooks()
+        hook = next((w for w in webhooks if w.url == target_endpoint), None)
+        ephemeral = False
+
+        if not hook:
+            print(f"\nSetting up webhook subscription for {target_endpoint}...")
+            hook = await agent.create_webhook(
+                url=target_endpoint,
+                events=["email.received", "test.ping"],
+            )
+            ephemeral = True
+            print(f"✔ Webhook registered: {hook.id}")
+        else:
+            print(f"✔ Using existing webhook subscription: {hook.id}")
+
+        # 2. In-memory event handler
+        async def handle_request(request: httpx.Request) -> httpx.Response:
+            now = datetime.datetime.now().strftime("%H:%M:%S")
+
+            try:
+                payload = json.loads(request.content.decode("utf-8"))
+            except Exception:
+                payload = {}
+
+            event_type = payload.get("event_type") or payload.get("type") or "unknown"
+
+            if event_type == "test.ping":
+                print(f"[{now}] 🏓 Ping event received. Returning 200 OK.")
+                return httpx.Response(200, json={"pong": True})
+
+            if event_type == "email.received":
+                data = payload.get("data") or {}
+                incoming = data.get("message") or {}
+                sender = incoming.get("from") or incoming.get("from_address") or "Unknown"
+                subject = incoming.get("subject") or "(no subject)"
+                snippet = incoming.get("snippet") or incoming.get("preview") or ""
+                msg_id = incoming.get("id")
+
+                print(f"\n[{now}] 📬 Email received!")
+                print(f"   From:    {sender}")
+                print(f"   Subject: {subject}")
+                if snippet:
+                    print(f"   Snippet: {snippet[:80]}")
+
+                if msg_id:
+                    try:
+                        print("   ⚡ Dispatching automated reply via agent.reply_email()...")
+                        reply = await agent.reply_email(
+                            msg_id,
+                            text=(
+                                f"Hello!\n\n"
+                                f"This is an automated response from @{agent.agent_handle} "
+                                f"powered by the Wirebox Python SDK.\n\n"
+                                f'I have received your email: "{subject}".\n\n'
+                                f"All systems operational!"
+                            ),
+                        )
+                        reply_id = reply.id or reply.message_id
+                        print(f"   ✔ Reply dispatched successfully! ID: {reply_id}")
+                    except WireboxAPIError as reply_err:
+                        print(f"   ❌ Failed to reply: {reply_err}")
+            else:
+                print(f"[{now}] ℹ️ Received event: {event_type}")
+
+            return httpx.Response(200, json={"received": True})
+
+        # 3. Connect in-memory tunnel session
+        print("\nConnecting in-memory tunnel gateway...")
+        session = await agent.connect_tunnel(handler=handle_request)
+        print("✔ Tunnel connected and ready to receive real-world events!")
+        print("\n💡 Test this agent now by sending an email to:")
+        print(f"   👉 {agent.mailbox.email_address}")
+
+        if once_mode:
+            print("\n[--once flag detected] Testing tunnel ping before exit...")
+            # Fire an internal test ping if supported
+            try:
+                await client.webhooks.test(hook.id)
+                print("✔ Webhook test ping successfully delivered!")
+            except Exception as test_err:
+                print(f"ℹ️  Ping status: {test_err}")
+
+            print("\nDisconnecting tunnel session...")
+            await session.close()
+            if ephemeral and hook:
+                print(f"Removing ephemeral webhook {hook.id}...")
+                await client.webhooks.delete(hook.id)
+            print("[✓] Auto-reply test cycle completed successfully!")
+            return
+
+        print("\nWaiting for incoming events (Press Ctrl+C to exit)...\n")
+
+        try:
+            await session.wait_closed()
+        finally:
+            print("\nDisconnecting tunnel session...")
+            await session.close()
+            if ephemeral and hook:
+                print(f"Removing ephemeral webhook {hook.id}...")
+                await client.webhooks.delete(hook.id)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\nShutdown complete.")
+    except Exception as exc:
+        print(f"\n[!] Error: {exc}", file=sys.stderr)
+        sys.exit(1)

wirebox-0.4.0/examples/personal_agent_identity.py

@@ -0,0 +1,193 @@
+"""Wirebox Python SDK — Personal Agent Identity Layer.
+
+Demonstrates how an AI platform or agent developer uses Wirebox as the
+foundational IDENTITY and REAL-WORLD COMMUNICATION layer for autonomous agents.
+
+Key Architectural Principle:
+- Wirebox does NOT implement agent reasoning, LLM orchestration, or task planning.
+- Wirebox provides the physical IDENTITY INFRASTRUCTURE that equips agents with:
+  1. Identity Presence: Unique global agent handle (@handle) and tenant isolation
+  2. Mailbox Infrastructure: Dedicated email address ({handle}@wireboxmail.com)
+  3. Telecom & Messaging: Dedicated carrier phone numbers, SMS, and Apple iMessage
+  4. Edge Gateway (Tunnel): Reverse-proxy WebSocket tunnel streaming real-world
+     inbound events directly into the agent's runtime process
+
+Usage:
+    python examples/personal_agent_identity.py
+    python examples/personal_agent_identity.py --once   # Self-test cycle and exit
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import time
+
+from wirebox import AsyncWirebox
+from wirebox.exceptions import WireboxAPIError
+
+
+async def main() -> None:
+    once_mode = "--once" in sys.argv
+
+    print("=" * 64)
+    print("  Wirebox Python SDK — Personal Agent Identity Layer")
+    print("  Identity & Communication Infrastructure for AI Agents")
+    print("=" * 64 + "\n")
+
+    async with AsyncWirebox() as client:
+        # ----------------------------------------------------------------------
+        # Phase 1: Identity Provisioning & Resolution
+        # ----------------------------------------------------------------------
+        print("[Phase 1: Identity Provisioning & Resolution]")
+        whoami = await client.whoami()
+        is_identity_scoped = bool(whoami.scoped_identity_id)
+
+        if is_identity_scoped:
+            print("✔ Operating in Identity-Scoped Mode (Strict Tenant Isolation)")
+            identity = await client.get_identity()
+            print(
+                f"✔ Loaded active agent identity: @{identity.agent_handle} "
+                f"({identity.display_name or 'N/A'})\n"
+            )
+        else:
+            print("✔ Operating in Platform Admin Mode")
+            # Reuse existing identity if available to conserve tenant quotas
+            existing_agents = await client.list_identities(limit=1)
+            if existing_agents:
+                identity = existing_agents[0]
+                print(
+                    f"✔ Reusing active agent identity: @{identity.agent_handle} "
+                    f"({identity.display_name or 'N/A'})\n"
+                )
+            else:
+                agent_handle = f"assistant-{int(time.time()) % 10000}"
+                print(f"Provisioning new agent identity container: @{agent_handle}...")
+                identity = await client.create_identity(
+                    agent_handle,
+                    display_name="Personal Travel Coordinator",
+                    description="Dedicated real-world identity for autonomous travel coordination",
+                )
+                print(f"✔ Identity container provisioned! ID: {identity.id}\n")
+
+        # ----------------------------------------------------------------------
+        # Phase 2: Inspect Communication Assets Bound to this Identity
+        # ----------------------------------------------------------------------
+        print("-" * 64)
+        print(f"  Identity Assets Bound to @{identity.agent_handle}")
+        print("-" * 64)
+        print(f"  📧 Mailbox:     {identity.mailbox.email_address}")
+        print(f"  🌐 Edge Tunnel: {identity.tunnel.public_url}")
+        print("  📱 Messaging:   Configured for Carrier SMS & Phone Numbers")
+        print("-" * 64 + "\n")
+
+        # ----------------------------------------------------------------------
+        # Phase 3: Phone & Telecom Infrastructure
+        # ----------------------------------------------------------------------
+        print("[Phase 2: Phone & Telecom Infrastructure]")
+        try:
+            phone_num = await identity.get_phone_number()
+            print(
+                f"✔ Bound carrier phone number: {phone_num.phone_number} "
+                f"(Status: {phone_num.status})\n"
+            )
+        except Exception:
+            print(f"Requesting carrier phone number allocation for @{identity.agent_handle}...")
+            try:
+                new_phone = await client.phone.numbers.provision(
+                    identity.agent_handle,
+                    country_code="US",
+                    type="local",
+                )
+                print(
+                    f"✔ Carrier phone number provisioned: {new_phone.phone_number} "
+                    f"({new_phone.type})\n"
+                )
+            except WireboxAPIError as err:
+                if err.status_code == 403 and "phone_provisioning_restricted" in str(err):
+                    print(
+                        "ℹ️  [Telecom Gate] Phone number provisioning is currently in Private Beta."
+                    )
+                    print(
+                        "    (Once organization is whitelisted, dedicated US/CA cellular numbers activate instantly)\n"
+                    )
+                elif err.status_code == 409:
+                    print("✔ Agent already possesses an active phone number.\n")
+                else:
+                    print(f"ℹ️  [Telecom Notice] {err}\n")
+
+        # ----------------------------------------------------------------------
+        # Phase 4: Outbound Real-World Communication (Using Identity Mailbox)
+        # ----------------------------------------------------------------------
+        print("[Phase 3: Outbound Communication via Identity Mailbox]")
+        print("Dispatching travel reservation confirmation from agent's dedicated identity...")
+
+        recipient = os.environ.get("AGENT_RECIPIENT") or identity.mailbox.email_address
+        try:
+            email_result = await identity.send_email(
+                to=recipient,
+                subject="[Confirmed] Flight SFO -> HND Reservation for Alex",
+                text="\n".join(
+                    [
+                        "Hello Alex,",
+                        "",
+                        "Your autonomous travel assistant has finalized your booking:",
+                        "  - Flight: NH 107 (San Francisco -> Tokyo Haneda)",
+                        "  - Status: Confirmed & Ticketed",
+                        "  - Booking Ref: WB-9921B",
+                        "",
+                        "This notification was dispatched using the agent's dedicated Wirebox identity mailbox.",
+                        "You can reply directly to this thread anytime to request adjustments.",
+                        "",
+                        f"— {identity.display_name or 'Agent'} (@{identity.agent_handle})",
+                    ]
+                ),
+            )
+
+            print("✔ Outbound email dispatched!")
+            print(f"  Message ID: {email_result.id or email_result.message_id}")
+            print(f"  Recipient:  {recipient}\n")
+        except WireboxAPIError as err:
+            if "not a verified address" in str(err):
+                print(
+                    f"ℹ️ [Sandbox Notice] Recipient '{recipient}' is not verified in sandbox mode."
+                )
+                print("   (Set AGENT_RECIPIENT=<your-verified-email> to test external delivery)\n")
+            else:
+                raise
+
+        # ----------------------------------------------------------------------
+        # Phase 5: Inbound Edge Gateway (Ingesting Real-World Signals into Agent)
+        # ----------------------------------------------------------------------
+        print("[Phase 4: Inbound Edge Gateway (Mail & Phone Events)]")
+        target_endpoint = f"{identity.tunnel.public_url}/webhook"
+
+        hook = await identity.create_webhook(
+            url=target_endpoint,
+            events=["email.received", "test.ping", "sms.received"],
+        )
+        print(f"✔ Webhook route bound: {hook.id} -> {target_endpoint}\n")
+
+        print("----------------------------------------------------------------")
+        print("  Personal Agent Identity Container Ready")
+        print(f"  Agent Handle:    @{identity.agent_handle}")
+        print(f"  Email Address:   {identity.mailbox.email_address}")
+        print(f"  Gateway Tunnel:  {identity.tunnel.public_url}")
+        print("----------------------------------------------------------------")
+
+        if once_mode:
+            print("\n[--once flag detected] Test cycle complete. Exiting cleanly.")
+            return
+
+        print("\nAgent identity infrastructure is operational. Press Ctrl+C to stop.\n")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\nShutdown requested by user.")
+    except Exception as exc:
+        print(f"\n[!] Error: {exc}", file=sys.stderr)
+        sys.exit(1)

wirebox-0.4.0/examples/quickstart.py

@@ -0,0 +1,87 @@
+"""Wirebox Python SDK — Quickstart Example.
+
+Demonstrates zero-config initialization with Wirebox(), caller introspection,
+identity discovery, sending an outbound email, and inspecting inbox messages.
+
+Usage:
+    python -m examples.quickstart
+    # or
+    python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from wirebox import Wirebox
+
+
+def main() -> None:
+    print("=" * 60)
+    print("Wirebox Python SDK - Quickstart")
+    print("=" * 60)
+
+    # 1. Zero-config client initialization
+    # Automatically resolves API key from ~/.wirebox/credentials or ~/.wirebox/config
+    client = Wirebox()
+
+    # 2. Caller introspection via /v1/me
+    who = client.whoami()
+    print(f"\n[1] Authenticated Organization: {who.organization.name} ({who.organization.id})")
+    print(f"    Billing Plan: {who.organization.billing_plan}")
+    print(f"    Active Actor: {who.auth.actor_id} (Type: {who.auth.type})")
+    print(f"    Usage: {who.usage.agents_count}/{who.usage.agents_limit} agents provisioned")
+
+    # 3. Retrieve or discover active agent identity
+    agents = client.list_identities(limit=10)
+    if not agents:
+        print("\n[!] No active agent identities found. Creating a starter identity...")
+        agent = client.create_identity("assistant-bot", display_name="AI Assistant")
+    else:
+        agent = agents[0]
+
+    print(f"\n[2] Active Agent Identity: @{agent.agent_handle}")
+    print(f"    Display Name:    {agent.display_name or 'N/A'}")
+    print(f"    Primary Mailbox: {agent.mailbox.email_address}")
+    print(f"    Network Tunnel:  {agent.tunnel.public_url}")
+
+    # 4. Dispatch a verified outbound email
+    recipient = os.environ.get("AGENT_RECIPIENT") or agent.mailbox.email_address
+    print(f"\n[3] Dispatching verified outbound message to: {recipient}...")
+
+    dispatch_result = agent.send_email(
+        to=recipient,
+        subject="[Wirebox Quickstart] Autonomous Agent Online",
+        text=(
+            f"Hello!\n\n"
+            f"Your personal agent @{agent.agent_handle} is fully provisioned with real-world infrastructure:\n"
+            f"- Email Inbox: {agent.mailbox.email_address}\n"
+            f"- Edge Tunnel: {agent.tunnel.public_url}\n\n"
+            f"Sent autonomously via the Wirebox Edge Core API."
+        ),
+    )
+
+    print(f"    Message Dispatched! ID: {dispatch_result.id}")
+    if dispatch_result.thread_id:
+        print(f"    Thread ID: {dispatch_result.thread_id}")
+
+    # 5. Inspect mailbox messages
+    print(f"\n[4] Querying recent messages for {agent.mailbox.email_address}...")
+    messages = agent.list_messages(limit=5)
+    print(f"    Found {len(messages)} recent message(s):")
+    for msg in messages:
+        snippet_text = (msg.snippet or msg.preview)[:60]
+        print(f"     - [{msg.direction.upper()}] from={msg.from_address}")
+        print(f"       subject: {msg.subject}")
+        print(f"       snippet: {snippet_text}...")
+
+    print("\n[✓] Wirebox Python Quickstart completed successfully!\n")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(f"\n[!] Error: {exc}", file=sys.stderr)
+        sys.exit(1)

{wirebox-0.2.0 → wirebox-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wirebox"
-version = "0.2.0"
+version = "0.4.0"
 description = "Official Python SDK for Wirebox — Real-world identity and communication layer for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

{wirebox-0.2.0 → wirebox-0.4.0}/src/wirebox/__init__.py

@@ -20,6 +20,7 @@ from wirebox.exceptions import (
 )
 from wirebox.identity import AgentIdentity, AsyncAgentIdentity
 from wirebox.imessage import AsyncIMessageClient, IMessageClient
+from wirebox.phone import AsyncPhoneClient, PhoneClient
 from wirebox.tunnels import TunnelSession
 from wirebox.types import (
     EmailMessage,
@@ -29,9 +30,15 @@ from wirebox.types import (
     ImessageConversationLastMessage,
     ImessageMessage,
     ImessageRouterInfo,
+    ListPhoneMessagesResult,
+    ListPhoneNumbersResult,
     MailboxSummary,
     MessageAttachmentSummary,
     MessageSummary,
+    PhoneMediaItem,
+    PhoneMessage,
+    PhoneNumber,
+    PhoneNumberCapabilities,
     SendEmailAttachment,
     SendEmailResult,
     SendImessageResult,
@@ -44,8 +51,10 @@ from wirebox.types import (
     WebhookStatus,
     WebhookTestResult,
     WhoamiApiKey,
+    WhoamiAuth,
     WhoamiOrganization,
     WhoamiResult,
+    WhoamiUsage,
 )
 from wirebox.verify_webhook import verify_webhook
 
@@ -63,6 +72,8 @@ __all__ = [
     "AsyncAgentIdentity",
     "IMessageClient",
     "AsyncIMessageClient",
+    "PhoneClient",
+    "AsyncPhoneClient",
     "TunnelSession",
     "verify_webhook",
     # Exceptions
@@ -89,6 +100,12 @@ __all__ = [
     "ImessageConversation",
     "ImessageConversationLastMessage",
     "ImessageMessage",
+    "PhoneNumberCapabilities",
+    "PhoneNumber",
+    "PhoneMediaItem",
+    "PhoneMessage",
+    "ListPhoneNumbersResult",
+    "ListPhoneMessagesResult",
     "Tunnel",
     "TunnelClientTelemetry",
     "Webhook",
@@ -99,5 +116,7 @@ __all__ = [
     "WebhookStatus",
     "WhoamiOrganization",
     "WhoamiApiKey",
+    "WhoamiAuth",
+    "WhoamiUsage",
     "WhoamiResult",
 ]

wirebox-0.4.0/src/wirebox/_config.py

@@ -0,0 +1,110 @@
+"""Wirebox Python SDK — Client Configuration and Credentials Resolver.
+
+Resolves API key and base URL from:
+1. Explicit constructor arguments
+2. Environment variables (WIREBOX_API_KEY, WIREBOX_BASE_URL)
+3. ~/.wirebox/credentials or ~/.wirebox/config file
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from wirebox._http import DEFAULT_BASE_URL
+
+
+def _get_config_search_paths() -> list[Path]:
+    custom_cred = os.environ.get("WIREBOX_CREDENTIALS_PATH")
+    custom_cfg = os.environ.get("WIREBOX_CONFIG_PATH")
+    if custom_cred or custom_cfg:
+        paths: list[Path] = []
+        if custom_cred:
+            paths.append(Path(custom_cred).expanduser())
+        if custom_cfg:
+            paths.append(Path(custom_cfg).expanduser())
+        return paths
+
+    home_dir = os.environ.get("WIREBOX_HOME")
+    base_dir = Path(home_dir).expanduser() / ".wirebox" if home_dir else Path.home() / ".wirebox"
+
+    return [base_dir / "credentials", base_dir / "config"]
+
+
+def _read_config_file(path: Path) -> dict[str, str]:
+    try:
+        text = path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return {}
+
+    if not text:
+        return {}
+
+    # 1. Try JSON format
+    if text.startswith("{"):
+        try:
+            parsed = json.loads(text)
+            if isinstance(parsed, dict):
+                return {str(k): str(v) for k, v in parsed.items() if v is not None}
+        except Exception:
+            pass
+
+    out: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            key, _, val = line.partition("=")
+            out[key.strip()] = val.strip().strip("\"'")
+        elif ":" in line:
+            key, _, val = line.partition(":")
+            out[key.strip()] = val.strip().strip("\"'")
+        elif line.startswith("wb_live_") or line.startswith("wb_test_"):
+            out["api_key"] = line
+
+    return out
+
+
+def resolve_client_settings(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> tuple[str | None, str]:
+    """Resolves (api_key, base_url) with fallback: explicit -> env -> file."""
+    # 1. Resolve API key
+    resolved_key = api_key.strip() if api_key and api_key.strip() else None
+    if not resolved_key:
+        env_key = os.environ.get("WIREBOX_API_KEY")
+        if env_key and env_key.strip():
+            resolved_key = env_key.strip()
+
+    # 2. Resolve Base URL
+    resolved_url = base_url.strip().rstrip("/") if base_url and base_url.strip() else None
+    if not resolved_url:
+        env_url = os.environ.get("WIREBOX_BASE_URL")
+        if env_url and env_url.strip():
+            resolved_url = env_url.strip().rstrip("/")
+
+    # 3. If either is still missing, search config files
+    if not resolved_key or not resolved_url:
+        for file_path in _get_config_search_paths():
+            cfg = _read_config_file(file_path)
+            if not cfg:
+                continue
+
+            if not resolved_key:
+                file_key = cfg.get("api_key") or cfg.get("apiKey") or cfg.get("token")
+                if file_key and file_key.strip():
+                    resolved_key = file_key.strip()
+
+            if not resolved_url:
+                file_url = cfg.get("base_url") or cfg.get("baseUrl")
+                if file_url and file_url.strip():
+                    resolved_url = file_url.strip().rstrip("/")
+
+            if resolved_key and resolved_url:
+                break
+
+    return (resolved_key, resolved_url or DEFAULT_BASE_URL)

wirebox-0.4.0/src/wirebox/_version.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"