monkeyscode 1.0.0__py3-none-any.whl

monkeyscode/__init__.py

@@ -0,0 +1,178 @@
+"""
+MonkeysCode Python SDK.
+
+Programmatic agent control for Python. Supports streaming, custom tools,
+goal mode, session management, and CI/CD integrations.
+
+Usage::
+
+    from monkeyscode import MonkeysCode
+
+    agent = MonkeysCode(api_key="mc_...")
+    result = await agent.run("Fix all Python type errors")
+    print(result.summary)
+
+For streaming::
+
+    async for event in agent.stream("Refactor auth module"):
+        if event.type == "text":
+            print(event.content, end="", flush=True)
+"""
+
+from monkeyscode.admin import AdminClient
+from monkeyscode.agent import MonkeysCode, MonkeysCodeOptions
+from monkeyscode.cli_process import (
+    AssistantMessage,
+    CliOptions,
+    InitMessage,
+    McProcessError,
+    McSchemaError,
+    MonkeysCodeClient,
+    PermissionAllow,
+    PermissionDeny,
+    ResultMessage,
+    ToolPermissionContext,
+    UserMessage,
+)
+from monkeyscode.cli_process import query as query_cli
+from monkeyscode.daemon import DaemonClient, DaemonClientOptions, DaemonEvent, DaemonRunParams
+from monkeyscode.events import (
+    AgentEvent,
+    AgentResult,
+    CompleteEvent,
+    ErrorEvent,
+    FileChange,
+    FileEditEvent,
+    GoalOptions,
+    GoalResult,
+    TextEvent,
+    TokenUsage,
+    ToolCallEvent,
+    ToolResultEvent,
+)
+from monkeyscode.export import to_html, to_markdown, to_transcript
+from monkeyscode.hooks import (
+    HookManager,
+    PostToolContext,
+    PostToolHook,
+    PreToolContext,
+    PreToolHook,
+    PreToolResult,
+)
+from monkeyscode.mcp import McpManager, McpServerConfig, McpServerStatus, McpTool, McpToolResult
+from monkeyscode.orchestrator import AgentSlotResult, OrchestratorResult, run_fan_out, run_parallel
+from monkeyscode.otel import OtelExporter, OtelOptions
+from monkeyscode.runs import RunRecord, RunStore
+from monkeyscode.sandbox import (
+    SandboxOptions,
+    SandboxResult,
+    detect_sandbox_mode,
+    is_docker_available,
+    run_in_sandbox,
+)
+from monkeyscode.session import Session, SessionOptions
+from monkeyscode.subagent import (
+    SubagentOptions,
+    SubagentResult,
+    cap_summary,
+    spawn_subagent,
+)
+from monkeyscode.telemetry import TelemetryCollector, TelemetryOptions, with_telemetry
+from monkeyscode.tools import ToolDefinition, define_tool
+from monkeyscode.watcher import WatchOptions, format_change_batch, watch_files
+
+__version__ = "1.0.0"
+
+# Grouped by module on purpose; the order of __all__ has no runtime effect.
+__all__ = [  # noqa: RUF022
+    # Events
+    "AgentEvent",
+    "AgentResult",
+    "CompleteEvent",
+    "ErrorEvent",
+    "FileChange",
+    "FileEditEvent",
+    "GoalOptions",
+    "GoalResult",
+    # Agent
+    "MonkeysCode",
+    "MonkeysCodeOptions",
+    # Session
+    "Session",
+    "SessionOptions",
+    "TextEvent",
+    "TokenUsage",
+    "ToolCallEvent",
+    "ToolDefinition",
+    "ToolResultEvent",
+    # Tools
+    "define_tool",
+    # Hooks
+    "HookManager",
+    "PreToolContext",
+    "PreToolHook",
+    "PreToolResult",
+    "PostToolContext",
+    "PostToolHook",
+    # Subagent
+    "SubagentOptions",
+    "SubagentResult",
+    "cap_summary",
+    "spawn_subagent",
+    # Admin
+    "AdminClient",
+    # Local engine over the mc subprocess (cli_process)
+    "query_cli",
+    "MonkeysCodeClient",
+    "CliOptions",
+    "InitMessage",
+    "AssistantMessage",
+    "UserMessage",
+    "ResultMessage",
+    "PermissionAllow",
+    "PermissionDeny",
+    "ToolPermissionContext",
+    "McSchemaError",
+    "McProcessError",
+    # Export
+    "to_markdown",
+    "to_html",
+    "to_transcript",
+    # Daemon
+    "DaemonClient",
+    "DaemonClientOptions",
+    "DaemonRunParams",
+    "DaemonEvent",
+    # MCP
+    "McpManager",
+    "McpServerConfig",
+    "McpTool",
+    "McpToolResult",
+    "McpServerStatus",
+    # Watcher
+    "watch_files",
+    "format_change_batch",
+    "WatchOptions",
+    # Orchestrator
+    "run_parallel",
+    "run_fan_out",
+    "OrchestratorResult",
+    "AgentSlotResult",
+    # Telemetry
+    "TelemetryCollector",
+    "TelemetryOptions",
+    "with_telemetry",
+    # OTEL
+    "OtelExporter",
+    "OtelOptions",
+    # Runs
+    "RunStore",
+    "RunRecord",
+    # Sandbox
+    "run_in_sandbox",
+    "SandboxOptions",
+    "SandboxResult",
+    "is_docker_available",
+    "detect_sandbox_mode",
+]
+

monkeyscode/_http.py

@@ -0,0 +1,83 @@
+"""
+MonkeysCode SDK — SSE HTTP Client.
+
+Internal module that handles SSE (Server-Sent Events) streaming
+via httpx. Used by the MonkeysCode agent class.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+
+async def stream_sse(
+    url: str,
+    *,
+    method: str = "POST",
+    headers: dict[str, str] | None = None,
+    json_body: dict[str, Any] | None = None,
+    timeout: float = 300.0,
+) -> AsyncIterator[dict[str, Any]]:
+    """
+    Stream SSE events from an HTTP endpoint.
+
+    Yields parsed JSON objects from ``data:`` lines in the SSE stream.
+    Automatically handles:
+    - Multi-line buffering
+    - ``[DONE]`` sentinel
+    - Malformed lines (skipped silently)
+
+    Args:
+        url: The endpoint URL.
+        method: HTTP method (default: POST).
+        headers: Request headers.
+        json_body: JSON request body (for POST).
+        timeout: Request timeout in seconds.
+
+    Yields:
+        Parsed JSON dictionaries from each SSE ``data:`` line.
+    """
+    all_headers = {
+        "Accept": "text/event-stream",
+        "Content-Type": "application/json",
+        **(headers or {}),
+    }
+
+    async with httpx.AsyncClient(timeout=httpx.Timeout(timeout)) as client:
+        async with client.stream(
+            method,
+            url,
+            headers=all_headers,
+            json=json_body,
+        ) as response:
+            response.raise_for_status()
+
+            buffer = ""
+            async for chunk in response.aiter_text():
+                buffer += chunk
+                lines = buffer.split("\n")
+                buffer = lines.pop()  # Keep incomplete last line
+
+                for line in lines:
+                    line = line.strip()
+
+                    if not line:
+                        continue
+
+                    if not line.startswith("data: "):
+                        continue
+
+                    data = line[6:].strip()
+
+                    if data == "[DONE]":
+                        return
+
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        # Skip malformed SSE lines
+                        continue

monkeyscode/admin.py

@@ -0,0 +1,141 @@
+"""
+MonkeysCode SDK — Admin API Client.
+
+REST client for team managers to monitor agent activity,
+usage, and costs across their organization.
+
+Usage::
+
+    from monkeyscode.admin import AdminClient
+
+    admin = AdminClient(api_key="mc_...")
+
+    usage = await admin.get_usage(period="30d")
+    print(f"Total cost: ${usage['total_cost']:.2f}")
+
+    runs = await admin.list_runs(limit=20)
+    for run in runs["runs"]:
+        print(f"  {run['id']} — {run['user']['name']} — ${run['cost']:.4f}")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.monkeyscode.com"
+
+
+class AdminClient:
+    """
+    Admin API client for monitoring team agent usage.
+
+    Requires an API key with admin/owner permissions on the organization.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+
+    # ── Usage ─────────────────────────────────────────────────────────
+
+    async def get_usage(
+        self,
+        *,
+        period: str = "30d",
+        user: str | None = None,
+        model: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Get usage report for the organization.
+
+        Returns dict with: total_cost, total_runs, total_tokens,
+        by_model, by_user, daily.
+        """
+        params: dict[str, str] = {"period": period}
+        if user:
+            params["user"] = user
+        if model:
+            params["model"] = model
+        return await self._request("GET", "/v1/admin/usage", params=params)
+
+    # ── Runs ──────────────────────────────────────────────────────────
+
+    async def list_runs(
+        self,
+        *,
+        limit: int = 50,
+        cursor: str | None = None,
+        status: str | None = None,
+        user: str | None = None,
+        model: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        List agent runs across the organization.
+
+        Returns dict with: runs, cursor, has_more, total.
+        """
+        params: dict[str, str] = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        if status:
+            params["status"] = status
+        if user:
+            params["user"] = user
+        if model:
+            params["model"] = model
+        return await self._request("GET", "/v1/admin/runs", params=params)
+
+    async def get_run(self, run_id: str) -> dict[str, Any]:
+        """Get details for a specific run."""
+        return await self._request("GET", f"/v1/admin/runs/{run_id}")
+
+    async def cancel_run(self, run_id: str) -> dict[str, Any]:
+        """Cancel a running agent."""
+        return await self._request("POST", f"/v1/admin/runs/{run_id}/cancel")
+
+    # ── Active Agents ─────────────────────────────────────────────────
+
+    async def get_active_agents(self) -> list[dict[str, Any]]:
+        """List currently active agents across the organization."""
+        return await self._request("GET", "/v1/admin/agents")
+
+    # ── Team Members ──────────────────────────────────────────────────
+
+    async def list_members(self) -> list[dict[str, Any]]:
+        """List team members and their usage stats."""
+        return await self._request("GET", "/v1/admin/members")
+
+    # ── Internal ──────────────────────────────────────────────────────
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "monkeyscode-sdk-python/1.0.0",
+        }
+
+        async with httpx.AsyncClient() as client:
+            response = await client.request(
+                method,
+                url,
+                headers=headers,
+                params=params,
+                json=json_body,
+            )
+            response.raise_for_status()
+            return response.json()