runagents 0.2.0__py3-none-any.whl

runagents/__init__.py

@@ -0,0 +1,8 @@
+"""RunAgents — Python SDK for the RunAgents AI agent platform."""
+
+from runagents.client import Client
+from runagents.agent import Agent, tool
+from runagents.runtime import RunContext
+
+__version__ = "0.2.0"
+__all__ = ["Client", "Agent", "tool", "RunContext"]

runagents/agent.py

@@ -0,0 +1,143 @@
+"""Agent SDK for writing RunAgents agents.
+
+Provides a high-level Agent class that reads operator-injected env vars
+and exposes ``call_tool()`` and ``chat()`` helpers. Stdlib only.
+
+Usage::
+
+    from runagents import Agent
+
+    agent = Agent()
+    result = agent.chat("What is 2+2?", tools=[...])
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import functools
+from typing import Any, Callable
+
+
+class Agent:
+    """High-level agent helper that reads operator-injected env vars.
+
+    Attributes:
+        system_prompt: The agent's system prompt.
+        model: LLM model name (e.g. ``gpt-4o-mini``).
+        llm_gateway_url: URL for the LLM gateway chat completions endpoint.
+        tool_urls: Mapping of tool name → base URL.
+    """
+
+    def __init__(self):
+        self.system_prompt = os.environ.get("SYSTEM_PROMPT", "You are a helpful assistant.")
+        self.model = os.environ.get("LLM_MODEL", "gpt-4o-mini")
+        self.llm_gateway_url = os.environ.get(
+            "LLM_GATEWAY_URL",
+            "http://llm-gateway.agent-system.svc:8080/v1/chat/completions",
+        )
+        self.tool_urls: dict[str, str] = {}
+        for key, val in os.environ.items():
+            if key.startswith("TOOL_URL_"):
+                name = key[len("TOOL_URL_"):].lower().replace("_", "-")
+                self.tool_urls[name] = val
+
+    def call_tool(
+        self,
+        name: str,
+        path: str = "/",
+        payload: dict | None = None,
+        method: str = "POST",
+    ) -> dict:
+        """Call a platform tool by name.
+
+        The Istio mesh handles auth and policy — this just makes the HTTP call.
+
+        Args:
+            name: Tool name (must be in ``self.tool_urls``).
+            path: HTTP path on the tool (default ``/``).
+            payload: JSON body (for POST/PUT/PATCH).
+            method: HTTP method.
+
+        Returns:
+            Parsed JSON response.
+
+        Raises:
+            KeyError: If tool name is not found in env vars.
+        """
+        from runagents.runtime import execute_tool_call
+
+        base = self.tool_urls.get(name)
+        if base is None:
+            env_key = "TOOL_URL_" + name.upper().replace("-", "_")
+            raise KeyError(f"Tool {name!r} not found. Set {env_key} or check requiredTools.")
+
+        url = base.rstrip("/") + path
+        body = json.dumps(payload) if payload else None
+        result_str = execute_tool_call(method, url, body=body)
+        try:
+            return json.loads(result_str)
+        except (json.JSONDecodeError, TypeError):
+            return {"raw": result_str}
+
+    def chat(
+        self,
+        message: str,
+        tools: list[dict] | None = None,
+        history: list[dict] | None = None,
+    ) -> dict:
+        """Send a chat completion request through the LLM gateway.
+
+        Args:
+            message: User message.
+            tools: OpenAI-format tool definitions (optional).
+            history: Prior conversation messages (optional).
+
+        Returns:
+            Full OpenAI-format response dict.
+        """
+        from runagents.runtime import call_llm
+
+        messages = list(history) if history else []
+        messages.append({"role": "user", "content": message})
+
+        return call_llm(
+            messages,
+            gateway_url=self.llm_gateway_url,
+            model=self.model,
+            system_prompt=self.system_prompt if not history else None,
+            tools=tools,
+        )
+
+
+def tool(fn: Callable | None = None, *, name: str | None = None, description: str = "") -> Any:
+    """Decorator to mark a function as a tool handler.
+
+    The decorated function gains ``.tool_name`` and ``.tool_description``
+    attributes for discovery by frameworks.
+
+    Usage::
+
+        @tool
+        def calculator(expression: str) -> str:
+            return str(eval(expression))
+
+        @tool(name="weather-lookup", description="Get current weather")
+        def weather(city: str) -> dict:
+            ...
+    """
+    def decorator(f: Callable) -> Callable:
+        f.tool_name = name or f.__name__.replace("_", "-")  # type: ignore[attr-defined]
+        f.tool_description = description or (f.__doc__ or "").strip().split("\n")[0]  # type: ignore[attr-defined]
+
+        @functools.wraps(f)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return f(*args, **kwargs)
+
+        wrapper.tool_name = f.tool_name  # type: ignore[attr-defined]
+        wrapper.tool_description = f.tool_description  # type: ignore[attr-defined]
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator

runagents/cli/__init__.py

@@ -0,0 +1 @@
+"""RunAgents CLI — Python entry point that delegates to Go binary."""

runagents/cli/binary.py

@@ -0,0 +1,121 @@
+"""Go CLI binary downloader — mirrors cli/npm/install.js logic.
+
+Downloads from S3, verifies SHA256, caches at ~/.runagents/bin/.
+Stdlib only: urllib.request, tarfile, hashlib, platform.
+"""
+
+import hashlib
+import os
+import platform
+import shutil
+import stat
+import sys
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+CLI_VERSION = "1.0.6"
+S3_BASE = "https://runagents-releases.s3.amazonaws.com/cli"
+
+PLATFORM_MAP = {"Darwin": "darwin", "Linux": "linux", "Windows": "windows"}
+ARCH_MAP = {"x86_64": "amd64", "AMD64": "amd64", "arm64": "arm64", "aarch64": "arm64"}
+
+_BIN_DIR = Path.home() / ".runagents" / "bin"
+
+
+def ensure_binary(version: str = CLI_VERSION) -> Path | None:
+    """Return path to Go binary, downloading if needed. Returns None on failure."""
+    # 1. Check cached binary
+    cached = _BIN_DIR / f"runagents-{version}"
+    if cached.exists() and os.access(cached, os.X_OK):
+        return cached
+
+    # 2. Check PATH
+    on_path = shutil.which("runagents")
+    if on_path:
+        return Path(on_path)
+
+    # 3. Download
+    try:
+        return _download(version)
+    except Exception as e:
+        print(f"Warning: could not download CLI binary: {e}", file=sys.stderr)
+        return None
+
+
+def _download(version: str) -> Path:
+    plat = PLATFORM_MAP.get(platform.system())
+    arch = ARCH_MAP.get(platform.machine())
+    if not plat or not arch:
+        raise RuntimeError(f"Unsupported platform: {platform.system()}/{platform.machine()}")
+
+    ext = ".zip" if plat == "windows" else ".tar.gz"
+    asset = f"runagents_{plat}_{arch}{ext}"
+    url = f"{S3_BASE}/v{version}/{asset}"
+    checksums_url = f"{S3_BASE}/v{version}/checksums.txt"
+
+    _BIN_DIR.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        archive_path = Path(tmpdir) / asset
+
+        # Download archive
+        print(f"Downloading runagents v{version} for {plat}/{arch}...")
+        urllib.request.urlretrieve(url, archive_path)
+
+        # Verify checksum
+        try:
+            with urllib.request.urlopen(checksums_url, timeout=10) as resp:
+                checksums_text = resp.read().decode()
+            expected_hash = _find_hash(checksums_text, asset)
+            if expected_hash:
+                actual_hash = _sha256(archive_path)
+                if actual_hash != expected_hash:
+                    raise RuntimeError(
+                        f"SHA256 mismatch for {asset}: expected {expected_hash}, got {actual_hash}"
+                    )
+        except urllib.error.URLError:
+            pass  # Skip verification if checksums unavailable
+
+        # Extract
+        bin_name = "runagents.exe" if plat == "windows" else "runagents"
+        if ext == ".tar.gz":
+            with tarfile.open(archive_path, "r:gz") as tar:
+                # Find the binary in the archive
+                for member in tar.getmembers():
+                    if member.name.endswith(bin_name):
+                        member.name = bin_name
+                        tar.extract(member, tmpdir)
+                        break
+        else:
+            import zipfile
+            with zipfile.ZipFile(archive_path) as zf:
+                for name in zf.namelist():
+                    if name.endswith(bin_name):
+                        zf.extract(name, tmpdir)
+                        break
+
+        src = Path(tmpdir) / bin_name
+        dst = _BIN_DIR / f"runagents-{version}"
+        shutil.move(str(src), str(dst))
+        dst.chmod(dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        print(f"Installed runagents v{version} to {dst}")
+        return dst
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _find_hash(checksums_text: str, asset_name: str) -> str | None:
+    for line in checksums_text.strip().splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == asset_name:
+            return parts[0]
+    return None

runagents/cli/dev_cmd.py

@@ -0,0 +1,308 @@
+"""``runagents dev`` — local dev server with mock tools and hot reload."""
+
+import json
+import os
+import signal
+import sys
+import threading
+import time
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+
+
+def run_dev(args: list[str]) -> None:
+    if args and args[0] in ("-h", "--help"):
+        print(
+            "Usage: runagents dev [options]\n\n"
+            "Start local dev server.\n\n"
+            "Options:\n"
+            "  --port PORT     Agent port (default 8080)\n"
+            "  --mock-port PORT  Mock tool server port (default 9090)\n"
+            "  --no-mock       Skip mock tool server\n"
+            "  --watch         Hot-reload on .py changes (requires watchdog)\n"
+        )
+        return
+
+    # Parse args
+    port = 8080
+    mock_port = 9090
+    use_mock = True
+    watch = False
+    i = 0
+    while i < len(args):
+        if args[i] == "--port" and i + 1 < len(args):
+            port = int(args[i + 1])
+            i += 2
+        elif args[i] == "--mock-port" and i + 1 < len(args):
+            mock_port = int(args[i + 1])
+            i += 2
+        elif args[i] == "--no-mock":
+            use_mock = False
+            i += 1
+        elif args[i] == "--watch":
+            watch = True
+            i += 1
+        else:
+            i += 1
+
+    config = _load_runagents_yaml()
+    if config is None:
+        print("Error: runagents.yaml not found. Run 'runagents init' first.", file=sys.stderr)
+        sys.exit(1)
+
+    # Set env vars matching operator injection
+    _setup_env(config, mock_port, use_mock)
+
+    print(f"RunAgents Dev Server")
+    print(f"  Agent:       :{port}")
+    if use_mock:
+        print(f"  Mock tools:  :{mock_port}")
+    print(f"  Model:       {os.environ.get('LLM_MODEL', 'gpt-4o-mini')}")
+    print(f"  Entry point: {config.get('entry_point', 'agent.py')}")
+    print()
+
+    # Start mock tool server
+    mock_server = None
+    if use_mock:
+        mock_server = _start_mock_server(mock_port, config.get("tools", []))
+
+    # Start agent runtime
+    try:
+        if watch:
+            _run_with_watch(port, config)
+        else:
+            _run_agent(port)
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    finally:
+        if mock_server:
+            mock_server.shutdown()
+
+
+def _load_runagents_yaml() -> dict | None:
+    """Load runagents.yaml from current directory."""
+    for name in ("runagents.yaml", "runagents.yml"):
+        p = Path.cwd() / name
+        if p.exists():
+            # Use a simple YAML subset parser (stdlib only)
+            return _parse_simple_yaml(p.read_text())
+    return None
+
+
+def _parse_simple_yaml(text: str) -> dict:
+    """Parse a simple single-level YAML file (no nested objects beyond one level)."""
+    result: dict = {}
+    current_key = None
+    current_list: list | None = None
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # List item
+        if stripped.startswith("- "):
+            if current_list is not None:
+                current_list.append(stripped[2:].strip().strip('"').strip("'"))
+            continue
+
+        # Key: value
+        if ":" in stripped:
+            key, _, val = stripped.partition(":")
+            key = key.strip()
+            val = val.strip().strip('"').strip("'")
+
+            # Handle nested keys (one level deep via indentation)
+            indent = len(line) - len(line.lstrip())
+            if indent > 0 and current_key and isinstance(result.get(current_key), dict):
+                result[current_key][key] = val
+                continue
+
+            if val == "":
+                # Could be a list or nested dict
+                # Peek: if next non-empty line starts with "- ", it's a list
+                result[key] = {}
+                current_key = key
+                current_list = None
+                continue
+            elif val == "[]":
+                result[key] = []
+                current_key = key
+                current_list = result[key]
+                continue
+
+            result[key] = val
+            current_key = key
+            current_list = None
+
+    return result
+
+
+def _setup_env(config: dict, mock_port: int, use_mock: bool) -> None:
+    """Set environment variables matching what the operator would inject."""
+    os.environ.setdefault("SYSTEM_PROMPT", config.get("system_prompt", "You are a helpful assistant."))
+    os.environ.setdefault("AGENT_NAME", config.get("name", "dev-agent"))
+
+    # LLM config
+    model_cfg = config.get("model", {})
+    if isinstance(model_cfg, dict):
+        model = model_cfg.get("model", "gpt-4o-mini")
+    else:
+        model = "gpt-4o-mini"
+    os.environ.setdefault("LLM_MODEL", model)
+
+    # LLM gateway: if platform configured, use it; else direct OpenAI
+    if os.environ.get("RUNAGENTS_ENDPOINT"):
+        from runagents.config import load_config
+        cfg = load_config()
+        os.environ.setdefault("LLM_GATEWAY_URL", f"{cfg.endpoint}/v1/chat/completions")
+    elif os.environ.get("OPENAI_API_KEY"):
+        os.environ.setdefault("LLM_GATEWAY_URL", "https://api.openai.com/v1/chat/completions")
+    else:
+        os.environ.setdefault("LLM_GATEWAY_URL", "http://localhost:8092/v1/chat/completions")
+
+    # Tools
+    tools = config.get("tools", [])
+    if isinstance(tools, list) and use_mock:
+        for t in tools:
+            if isinstance(t, str):
+                env_key = "TOOL_URL_" + t.upper().replace("-", "_")
+                os.environ.setdefault(env_key, f"http://localhost:{mock_port}")
+
+    # Tool definitions + routes for runtime
+    os.environ.setdefault("TOOL_DEFINITIONS_JSON", "[]")
+    os.environ.setdefault("TOOL_ROUTES_JSON", "{}")
+
+    # User entry point
+    entry = config.get("entry_point", "agent.py")
+    if entry:
+        module = entry.removesuffix(".py")
+        os.environ.setdefault("USER_ENTRY_POINT", module)
+
+    os.environ.setdefault("PORT", "8080")
+
+
+def _start_mock_server(port: int, tools: list) -> HTTPServer:
+    """Start a mock tool server that returns echo responses."""
+
+    class MockHandler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            self._respond({"method": "GET", "path": self.path, "mock": True})
+
+        def do_POST(self):
+            length = int(self.headers.get("Content-Length", 0))
+            body = self.rfile.read(length).decode() if length else "{}"
+            try:
+                payload = json.loads(body)
+            except json.JSONDecodeError:
+                payload = {"raw": body}
+
+            self._respond({
+                "method": "POST",
+                "path": self.path,
+                "received": payload,
+                "mock": True,
+                "result": f"Mock response for {self.path}",
+            })
+
+        def do_PUT(self):
+            self.do_POST()
+
+        def do_PATCH(self):
+            self.do_POST()
+
+        def do_DELETE(self):
+            self._respond({"method": "DELETE", "path": self.path, "mock": True, "deleted": True})
+
+        def _respond(self, data: dict) -> None:
+            body = json.dumps(data).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, format, *args):
+            print(f"  [mock] {args[0]}")
+
+    server = HTTPServer(("0.0.0.0", port), MockHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server
+
+
+def _run_agent(port: int) -> None:
+    """Start the agent runtime server."""
+    os.environ["PORT"] = str(port)
+
+    # Add cwd to path so user's agent.py is importable
+    if str(Path.cwd()) not in sys.path:
+        sys.path.insert(0, str(Path.cwd()))
+
+    from runagents.runtime import main as runtime_main
+    runtime_main()
+
+
+def _run_with_watch(port: int, config: dict) -> None:
+    """Run with file watching and auto-restart."""
+    try:
+        from watchdog.observers import Observer
+        from watchdog.events import FileSystemEventHandler
+    except ImportError:
+        print("Warning: watchdog not installed. Running without hot-reload.")
+        print("Install with: pip install runagents[dev]")
+        _run_agent(port)
+        return
+
+    import subprocess
+
+    process = None
+    lock = threading.Lock()
+
+    def start():
+        nonlocal process
+        env = os.environ.copy()
+        env["PORT"] = str(port)
+        process = subprocess.Popen(
+            [sys.executable, "-c", "from runagents.runtime import main; main()"],
+            env=env,
+            cwd=str(Path.cwd()),
+        )
+
+    def restart():
+        nonlocal process
+        with lock:
+            if process:
+                process.terminate()
+                process.wait(timeout=5)
+            print("  [dev] Restarting agent...")
+            start()
+
+    class ReloadHandler(FileSystemEventHandler):
+        def __init__(self):
+            self._last = 0
+
+        def on_modified(self, event):
+            if not event.src_path.endswith(".py"):
+                return
+            now = time.time()
+            if now - self._last < 1:
+                return
+            self._last = now
+            restart()
+
+    observer = Observer()
+    observer.schedule(ReloadHandler(), str(Path.cwd()), recursive=True)
+    observer.start()
+
+    start()
+    try:
+        while True:
+            if process and process.poll() is not None:
+                break
+            time.sleep(0.5)
+    finally:
+        observer.stop()
+        observer.join()
+        if process:
+            process.terminate()

runagents/cli/init_cmd.py

@@ -0,0 +1,57 @@
+"""``runagents init [name]`` — scaffold a new agent project."""
+
+import os
+import sys
+from pathlib import Path
+
+_TEMPLATE_DIR = Path(__file__).parent / "templates"
+
+
+def run_init(args: list[str]) -> None:
+    if args and args[0] in ("-h", "--help"):
+        print("Usage: runagents init [name]\n\nScaffold a new agent project.")
+        return
+
+    name = args[0] if args else "my-agent"
+    target = Path.cwd() / name
+
+    if target.exists():
+        print(f"Error: directory '{name}' already exists.", file=sys.stderr)
+        sys.exit(1)
+
+    target.mkdir(parents=True)
+    _render_templates(target, name)
+
+    print(f"Created project '{name}/' with:")
+    for f in sorted(target.rglob("*")):
+        if f.is_file():
+            print(f"  {f.relative_to(target)}")
+    print(f"\nNext steps:\n  cd {name}\n  pip install runagents\n  runagents dev")
+
+
+def _render_templates(target: Path, name: str) -> None:
+    """Read .tmpl files and write rendered output."""
+    replacements = {
+        "{{name}}": name,
+        "{{name_underscore}}": name.replace("-", "_"),
+    }
+
+    file_map = {
+        "agent.py.tmpl": "agent.py",
+        "runagents.yaml.tmpl": "runagents.yaml",
+        "requirements.txt.tmpl": "requirements.txt",
+        "claude_md.tmpl": "CLAUDE.md",
+        "cursorrules.tmpl": ".cursorrules",
+        "agents_md.tmpl": "AGENTS.md",
+        "mcp_json.tmpl": ".mcp.json",
+        "gitignore.tmpl": ".gitignore",
+    }
+
+    for tmpl_name, out_name in file_map.items():
+        tmpl_path = _TEMPLATE_DIR / tmpl_name
+        if not tmpl_path.exists():
+            continue
+        content = tmpl_path.read_text()
+        for old, new in replacements.items():
+            content = content.replace(old, new)
+        (target / out_name).write_text(content)