runagents 0.2.0__tar.gz

runagents-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: runagents
+Version: 0.2.0
+Summary: RunAgents Python SDK — deploy, manage, and build AI agents
+Author-email: RunAgents <try@runagents.io>
+License: Apache-2.0
+Project-URL: Homepage, https://runagents.io
+Project-URL: Documentation, https://docs.runagents.io
+Project-URL: Repository, https://github.com/runagents-io/runagents
+Project-URL: Issues, https://github.com/runagents-io/runagents/issues
+Keywords: ai,agents,runagents,llm,tool-calling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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 :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: watchdog>=3.0; extra == "dev"
+
+# RunAgents Python SDK
+
+Everything you need to build, test, and deploy AI agents on [RunAgents](https://runagents.io) — in one package.
+
+## Install
+
+```bash
+pip install runagents        # Core SDK + CLI + runtime (zero deps)
+pip install runagents[mcp]   # + MCP server for AI coding assistants
+pip install runagents[dev]   # + hot-reload for local dev
+```
+
+## Quickstart
+
+```bash
+runagents init my-agent      # Scaffold a project
+cd my-agent
+runagents dev                # Local dev server with mock tools
+runagents deploy             # Ship to the platform
+```
+
+## Python API
+
+### Client — manage platform resources
+
+```python
+from runagents import Client
+
+client = Client()  # reads ~/.runagents/config.json + env vars
+
+agents = client.agents.list()
+tools = client.tools.list()
+runs = client.runs.list(agent="payment-agent")
+
+result = client.agents.deploy(
+    name="my-agent",
+    source_files={"agent.py": open("agent.py").read()},
+    required_tools=["stripe-api"],
+    llm_configs=[{"provider": "openai", "model": "gpt-4o-mini", "role": "default"}],
+)
+```
+
+### Agent — write agent code
+
+```python
+from runagents import Agent, tool
+
+agent = Agent()  # reads TOOL_URL_*, LLM_GATEWAY_URL, LLM_MODEL from env
+
+# Call a platform tool (mesh handles auth)
+result = agent.call_tool("echo-tool", "/echo", {"message": "hello"})
+
+# Chat via LLM gateway
+response = agent.chat("What is 2+2?", tools=[...])
+
+# Custom handler (Tier 2)
+def handler(request, ctx):
+    message = request["message"]
+    result = agent.chat(message)
+    return result["choices"][0]["message"]["content"]
+```
+
+### @tool decorator
+
+```python
+from runagents import tool
+
+@tool(name="calculator", description="Evaluate math expressions")
+def calculate(expression: str) -> str:
+    return str(eval(expression))
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `runagents init [name]` | Scaffold a new agent project |
+| `runagents dev` | Start local dev server with mock tools |
+| `runagents deploy` | Deploy an agent (delegates to Go CLI) |
+| `runagents agents list` | List agents |
+| `runagents tools list` | List tools |
+| `runagents runs list` | List runs |
+| `runagents config` | Manage configuration |
+
+## Runtime
+
+The runtime provides the HTTP server for deployed agents — tool calling loop, SSE streaming, health checks, OAuth consent, and JIT approvals. It runs automatically inside the platform; for local development use `runagents dev`.
+
+```python
+# Backward compatible — still works
+import runagents_runtime
+```
+
+## MCP Server
+
+```bash
+pip install runagents[mcp]
+runagents-mcp  # starts on stdio
+```
+
+14 tools for AI coding assistants (Claude Code, Cursor, Codex). See [AI Assistant Setup](https://docs.runagents.io/cli/ai-assistant-setup/).
+
+## Configuration
+
+Reads from `~/.runagents/config.json` with env var overrides:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RUNAGENTS_ENDPOINT` | Platform API URL | `http://localhost:8092` |
+| `RUNAGENTS_API_KEY` | API key or workspace key | — |
+| `RUNAGENTS_NAMESPACE` | Target namespace | `default` |
+
+## Documentation
+
+- [RunAgents Docs](https://docs.runagents.io)
+- [Writing Agents](https://docs.runagents.io/getting-started/writing-agents/)
+- [Agent Runtime](https://docs.runagents.io/platform/agent-runtime/)
+- [AI Assistant Setup](https://docs.runagents.io/cli/ai-assistant-setup/)
+- [CLI Commands](https://docs.runagents.io/cli/commands/)
+
+## License
+
+Apache-2.0

runagents-0.2.0/README.md

@@ -0,0 +1,123 @@
+# RunAgents Python SDK
+
+Everything you need to build, test, and deploy AI agents on [RunAgents](https://runagents.io) — in one package.
+
+## Install
+
+```bash
+pip install runagents        # Core SDK + CLI + runtime (zero deps)
+pip install runagents[mcp]   # + MCP server for AI coding assistants
+pip install runagents[dev]   # + hot-reload for local dev
+```
+
+## Quickstart
+
+```bash
+runagents init my-agent      # Scaffold a project
+cd my-agent
+runagents dev                # Local dev server with mock tools
+runagents deploy             # Ship to the platform
+```
+
+## Python API
+
+### Client — manage platform resources
+
+```python
+from runagents import Client
+
+client = Client()  # reads ~/.runagents/config.json + env vars
+
+agents = client.agents.list()
+tools = client.tools.list()
+runs = client.runs.list(agent="payment-agent")
+
+result = client.agents.deploy(
+    name="my-agent",
+    source_files={"agent.py": open("agent.py").read()},
+    required_tools=["stripe-api"],
+    llm_configs=[{"provider": "openai", "model": "gpt-4o-mini", "role": "default"}],
+)
+```
+
+### Agent — write agent code
+
+```python
+from runagents import Agent, tool
+
+agent = Agent()  # reads TOOL_URL_*, LLM_GATEWAY_URL, LLM_MODEL from env
+
+# Call a platform tool (mesh handles auth)
+result = agent.call_tool("echo-tool", "/echo", {"message": "hello"})
+
+# Chat via LLM gateway
+response = agent.chat("What is 2+2?", tools=[...])
+
+# Custom handler (Tier 2)
+def handler(request, ctx):
+    message = request["message"]
+    result = agent.chat(message)
+    return result["choices"][0]["message"]["content"]
+```
+
+### @tool decorator
+
+```python
+from runagents import tool
+
+@tool(name="calculator", description="Evaluate math expressions")
+def calculate(expression: str) -> str:
+    return str(eval(expression))
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `runagents init [name]` | Scaffold a new agent project |
+| `runagents dev` | Start local dev server with mock tools |
+| `runagents deploy` | Deploy an agent (delegates to Go CLI) |
+| `runagents agents list` | List agents |
+| `runagents tools list` | List tools |
+| `runagents runs list` | List runs |
+| `runagents config` | Manage configuration |
+
+## Runtime
+
+The runtime provides the HTTP server for deployed agents — tool calling loop, SSE streaming, health checks, OAuth consent, and JIT approvals. It runs automatically inside the platform; for local development use `runagents dev`.
+
+```python
+# Backward compatible — still works
+import runagents_runtime
+```
+
+## MCP Server
+
+```bash
+pip install runagents[mcp]
+runagents-mcp  # starts on stdio
+```
+
+14 tools for AI coding assistants (Claude Code, Cursor, Codex). See [AI Assistant Setup](https://docs.runagents.io/cli/ai-assistant-setup/).
+
+## Configuration
+
+Reads from `~/.runagents/config.json` with env var overrides:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RUNAGENTS_ENDPOINT` | Platform API URL | `http://localhost:8092` |
+| `RUNAGENTS_API_KEY` | API key or workspace key | — |
+| `RUNAGENTS_NAMESPACE` | Target namespace | `default` |
+
+## Documentation
+
+- [RunAgents Docs](https://docs.runagents.io)
+- [Writing Agents](https://docs.runagents.io/getting-started/writing-agents/)
+- [Agent Runtime](https://docs.runagents.io/platform/agent-runtime/)
+- [AI Assistant Setup](https://docs.runagents.io/cli/ai-assistant-setup/)
+- [CLI Commands](https://docs.runagents.io/cli/commands/)
+
+## License
+
+Apache-2.0

runagents-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runagents"
+version = "0.2.0"
+description = "RunAgents Python SDK — deploy, manage, and build AI agents"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "RunAgents", email = "try@runagents.io"},
+]
+keywords = ["ai", "agents", "runagents", "llm", "tool-calling"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+dev = ["watchdog>=3.0"]
+
+[project.scripts]
+runagents = "runagents.cli.main:main"
+runagents-mcp = "runagents.mcp:main"
+
+[project.urls]
+Homepage = "https://runagents.io"
+Documentation = "https://docs.runagents.io"
+Repository = "https://github.com/runagents-io/runagents"
+Issues = "https://github.com/runagents-io/runagents/issues"
+
+[tool.setuptools.packages.find]
+include = ["runagents*"]
+
+[tool.setuptools]
+py-modules = ["runagents_runtime"]
+
+[tool.setuptools.package-data]
+"runagents.cli" = ["templates/*"]

runagents-0.2.0/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-0.2.0/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-0.2.0/runagents/cli/__init__.py

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

runagents-0.2.0/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