monkeyscode 1.0.0__tar.gz

monkeyscode-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

monkeyscode-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MonkeysCloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monkeyscode-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: monkeyscode
+Version: 1.0.0
+Summary: MonkeysCode SDK — programmatic agent control for Python
+Project-URL: Homepage, https://monkeyscode.com
+Project-URL: Documentation, https://monkeyscode.com/docs/sdk/python
+Project-URL: Repository, https://github.com/MonkeysCloud/monkeyscode
+Project-URL: Issues, https://github.com/MonkeysCloud/monkeyscode/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,coding-agent,monkeyscode,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MonkeysCode Python SDK
+
+Programmatic agent control for Python. Run coding agents, stream events, define custom tools, and integrate with CI/CD pipelines.
+
+## Installation
+
+```bash
+pip install monkeyscode
+```
+
+## Quick Start
+
+```python
+from monkeyscode import MonkeysCode
+import asyncio
+
+async def main():
+    agent = MonkeysCode(api_key="mc_...")
+    result = await agent.run("Fix all Python type errors")
+    print(f"✓ {result.summary}")
+    print(f"  Files: {len(result.files_changed)}, Cost: ${result.cost:.4f}")
+
+asyncio.run(main())
+```
+
+## Streaming
+
+```python
+async for event in agent.stream("Refactor auth module"):
+    if event.type == "text":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool_call":
+        print(f"  🔧 {event.tool}")
+```
+
+## Custom Tools
+
+```python
+from monkeyscode import define_tool
+
+@define_tool(
+    name="deploy",
+    description="Deploy the application",
+    parameters={"env": {"type": "string", "enum": ["staging", "prod"]}},
+)
+async def deploy(env: str) -> dict:
+    return {"deployed": True, "url": f"https://{env}.example.com"}
+
+agent.add_tool(deploy)
+```
+
+## Goal Mode
+
+```python
+result = await agent.goal(
+    "All tests pass",
+    verify_command="pytest",
+    max_iterations=5,
+)
+print(f"Goal met: {result.goal_met} in {result.iterations} iterations")
+```
+
+## Sessions
+
+```python
+from monkeyscode import Session
+
+session = await Session.create(agent, workspace="/my/project")
+await session.run("Add auth module")
+await session.run("Now add tests for it")  # Carries context
+session.close()
+```
+
+## Local agent (`mc` subprocess)
+
+The client above calls the hosted API. To run the agent **on this machine**
+with your settings, permission rules, hooks and MCP servers, drive an
+installed `mc` (standard library only):
+
+```python
+from monkeyscode.cli_process import (
+    CliOptions, MonkeysCodeClient, PermissionAllow, PermissionDeny, ResultMessage, query,
+)
+
+async for event in query("explain src/main.ts"):
+    if isinstance(event, ResultMessage):
+        print(event.result, event.cost_usd)
+
+async def can_use_tool(tool, tool_input, ctx):
+    if str(tool_input.get("path", "")).startswith("docs/"):
+        return PermissionAllow()
+    return PermissionDeny(message="only docs/ may be written")
+
+async with MonkeysCodeClient(CliOptions(can_use_tool=can_use_tool, max_cost_usd=1)) as client:
+    await client.send("write docs/intro.md")
+    result = await client.receive_result()
+```
+
+`query_cli` and `MonkeysCodeClient` are also exported from `monkeyscode`.
+Guide: [docs/cli/sdk.md](../../docs/cli/sdk.md); a runnable three-turn
+example: [`examples/three_turn_approval.py`](examples/three_turn_approval.py).
+
+## CI/CD
+
+```python
+from monkeyscode.ci import ci_run, to_sarif
+import json
+
+result = await ci_run(
+    prompt="Review this PR for security issues",
+    diff=open("pr.diff").read(),
+)
+
+sarif = to_sarif(result)
+with open("results.sarif", "w") as f:
+    json.dump(sarif, f, indent=2)
+```
+
+## License
+
+MIT

monkeyscode-1.0.0/README.md

@@ -0,0 +1,121 @@
+# MonkeysCode Python SDK
+
+Programmatic agent control for Python. Run coding agents, stream events, define custom tools, and integrate with CI/CD pipelines.
+
+## Installation
+
+```bash
+pip install monkeyscode
+```
+
+## Quick Start
+
+```python
+from monkeyscode import MonkeysCode
+import asyncio
+
+async def main():
+    agent = MonkeysCode(api_key="mc_...")
+    result = await agent.run("Fix all Python type errors")
+    print(f"✓ {result.summary}")
+    print(f"  Files: {len(result.files_changed)}, Cost: ${result.cost:.4f}")
+
+asyncio.run(main())
+```
+
+## Streaming
+
+```python
+async for event in agent.stream("Refactor auth module"):
+    if event.type == "text":
+        print(event.content, end="", flush=True)
+    elif event.type == "tool_call":
+        print(f"  🔧 {event.tool}")
+```
+
+## Custom Tools
+
+```python
+from monkeyscode import define_tool
+
+@define_tool(
+    name="deploy",
+    description="Deploy the application",
+    parameters={"env": {"type": "string", "enum": ["staging", "prod"]}},
+)
+async def deploy(env: str) -> dict:
+    return {"deployed": True, "url": f"https://{env}.example.com"}
+
+agent.add_tool(deploy)
+```
+
+## Goal Mode
+
+```python
+result = await agent.goal(
+    "All tests pass",
+    verify_command="pytest",
+    max_iterations=5,
+)
+print(f"Goal met: {result.goal_met} in {result.iterations} iterations")
+```
+
+## Sessions
+
+```python
+from monkeyscode import Session
+
+session = await Session.create(agent, workspace="/my/project")
+await session.run("Add auth module")
+await session.run("Now add tests for it")  # Carries context
+session.close()
+```
+
+## Local agent (`mc` subprocess)
+
+The client above calls the hosted API. To run the agent **on this machine**
+with your settings, permission rules, hooks and MCP servers, drive an
+installed `mc` (standard library only):
+
+```python
+from monkeyscode.cli_process import (
+    CliOptions, MonkeysCodeClient, PermissionAllow, PermissionDeny, ResultMessage, query,
+)
+
+async for event in query("explain src/main.ts"):
+    if isinstance(event, ResultMessage):
+        print(event.result, event.cost_usd)
+
+async def can_use_tool(tool, tool_input, ctx):
+    if str(tool_input.get("path", "")).startswith("docs/"):
+        return PermissionAllow()
+    return PermissionDeny(message="only docs/ may be written")
+
+async with MonkeysCodeClient(CliOptions(can_use_tool=can_use_tool, max_cost_usd=1)) as client:
+    await client.send("write docs/intro.md")
+    result = await client.receive_result()
+```
+
+`query_cli` and `MonkeysCodeClient` are also exported from `monkeyscode`.
+Guide: [docs/cli/sdk.md](../../docs/cli/sdk.md); a runnable three-turn
+example: [`examples/three_turn_approval.py`](examples/three_turn_approval.py).
+
+## CI/CD
+
+```python
+from monkeyscode.ci import ci_run, to_sarif
+import json
+
+result = await ci_run(
+    prompt="Review this PR for security issues",
+    diff=open("pr.diff").read(),
+)
+
+sarif = to_sarif(result)
+with open("results.sarif", "w") as f:
+    json.dump(sarif, f, indent=2)
+```
+
+## License
+
+MIT

monkeyscode-1.0.0/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-1.0.0/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-1.0.0/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()