decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/utils/telegram/helpers.py

@@ -0,0 +1,174 @@
+"""
+Telegram helpers for end-to-end verification in judges.
+
+These helpers directly query the Telegram REST API to verify that the agent's
+actions have had the expected effect on the environment state.
+
+Usage in judges:
+    from dt_arena.utils.telegram.helpers import configure_telegram, get_chat_messages, list_calls
+    from dt_arena.utils.utils import get_mcp_env_var
+
+    class Judge:
+        def __init__(self):
+            config = load_task_config(_task_dir)
+            configure_telegram(
+                base_url=get_mcp_env_var(config, "telegram", "TELEGRAM_API_URL"),
+                access_token=get_mcp_env_var(config, "telegram", "TELEGRAM_USER_ACCESS_TOKEN"),
+            )
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import urllib.parse as urlparse
+from typing import Dict, Any, List, Optional, Tuple
+
+
+# Module-level configuration - set by configure_telegram()
+_telegram_config: Dict[str, str] = {}
+
+
+def configure_telegram(
+    base_url: Optional[str] = None,
+    access_token: Optional[str] = None,
+) -> None:
+    """Configure Telegram connection parameters.
+
+    Call this once in your judge's __init__ before using any helper functions.
+
+    Args:
+        base_url: Telegram API base URL (e.g., "http://127.0.0.1:8038")
+        access_token: User access token for authentication
+    """
+    global _telegram_config
+    _telegram_config = {
+        "base_url": (base_url or "").rstrip("/"),
+        "access_token": access_token or "",
+    }
+
+
+def _get_host_port() -> Tuple[str, int]:
+    """Get host and port from configured base URL."""
+    url = _telegram_config.get("base_url", "")
+    if not url:
+        env_port = os.environ.get("TELEGRAM_API_PORT", "8038")
+        return "127.0.0.1", int(env_port)
+    parsed = urlparse.urlparse(url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or 8038
+    return host, port
+
+
+def _request(method: str, path: str, body: Optional[Dict] = None,
+             token: Optional[str] = None) -> Dict[str, Any]:
+    """Make an HTTP request to the Telegram API."""
+    host, port = _get_host_port()
+    tok = token or _telegram_config.get("access_token", "")
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {tok}",
+    }
+    conn = http.client.HTTPConnection(host, port, timeout=10)
+    payload = json.dumps(body).encode() if body else None
+    conn.request(method, path, body=payload, headers=headers)
+    resp = conn.getresponse()
+    data = resp.read()
+    conn.close()
+    if resp.status >= 400:
+        raise Exception(f"Telegram API error {resp.status}: {data.decode()}")
+    return json.loads(data.decode()) if data else {}
+
+
+def get_chat_messages(phone_number: str, limit: int = 200,
+                      token: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Get all messages in a chat thread with a specific phone number.
+
+    Args:
+        phone_number: The phone number of the contact
+        limit: Maximum number of messages to return
+        token: Optional override access token
+
+    Returns:
+        List of message dicts
+    """
+    encoded = urlparse.quote(phone_number, safe="")
+    result = _request("GET", f"/messages/chat/{encoded}?limit={limit}", token=token)
+    return result.get("messages", [])
+
+
+def list_chats(limit: int = 50, token: Optional[str] = None) -> List[Dict[str, Any]]:
+    """List all chat threads.
+
+    Returns:
+        List of thread dicts
+    """
+    result = _request("GET", f"/messages/chats?limit={limit}", token=token)
+    return result.get("threads", [])
+
+
+def search_messages(query: str, limit: int = 50,
+                    token: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Search messages by content.
+
+    Args:
+        query: Search query string
+        limit: Maximum number of results
+
+    Returns:
+        List of matching message dicts
+    """
+    encoded = urlparse.quote(query, safe="")
+    result = _request("GET", f"/messages/search?query={encoded}&limit={limit}", token=token)
+    return result.get("messages", [])
+
+
+def list_calls(phone_number: Optional[str] = None, limit: int = 50,
+               token: Optional[str] = None) -> List[Dict[str, Any]]:
+    """List call records.
+
+    Args:
+        phone_number: Optional filter by phone number
+        limit: Maximum number of results
+
+    Returns:
+        List of call record dicts
+    """
+    path = f"/calls?limit={limit}"
+    if phone_number:
+        path += f"&phone_number={urlparse.quote(phone_number, safe='')}"
+    result = _request("GET", path, token=token)
+    return result.get("calls", [])
+
+
+def get_unread_messages(limit: int = 50,
+                        token: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Get unread incoming messages.
+
+    Returns:
+        List of unread message dicts
+    """
+    result = _request("GET", f"/messages/unread?limit={limit}", token=token)
+    return result.get("unread_messages", [])
+
+
+def send_message(phone_number: str, body: str,
+                 token: Optional[str] = None) -> Dict[str, Any]:
+    """Send a message to a phone number.
+
+    Args:
+        phone_number: Recipient phone number
+        body: Message text
+
+    Returns:
+        Message response dict
+    """
+    return _request("POST", "/messages/send", {
+        "phone_number": phone_number,
+        "body": body,
+    }, token=token)
+
+
+def reset_telegram(token: Optional[str] = None) -> Dict[str, Any]:
+    """Reset the Telegram environment to seed data."""
+    return _request("POST", "/api/v1/reset", token=token)

dt_arena/utils/terminal/helpers.py

@@ -0,0 +1,20 @@
+"""Shared utilities for terminal Docker container resolution."""
+
+from __future__ import annotations
+
+import os
+
+
+def get_terminal_container_name() -> str:
+    """Derive terminal container name from TERMINAL_PROJECT_NAME.
+
+    Uses Docker Compose naming convention: {project_name}-terminal-env-1
+    """
+    project = os.environ.get("TERMINAL_PROJECT_NAME")
+    if project:
+        return f"{project}-terminal-env-1"
+
+    raise RuntimeError(
+        "Cannot resolve terminal container name: "
+        "TERMINAL_PROJECT_NAME is not set"
+    )