monkeyscode 1.0.0__py3-none-any.whl

monkeyscode/telemetry.py

@@ -0,0 +1,204 @@
+"""
+MonkeysCode SDK — Telemetry (Opt-in).
+
+Anonymous usage telemetry for understanding SDK adoption.
+Disabled by default — must be explicitly enabled.
+
+No PII is ever collected. Only:
+  - SDK version
+  - Model used
+  - Event counts (not content)
+  - Duration and token totals
+  - Error codes (not messages)
+
+Usage::
+
+    from monkeyscode.telemetry import TelemetryCollector, with_telemetry
+
+    agent = with_telemetry(agent, TelemetryOptions(enabled=True))
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+SDK_VERSION = "1.0.0"
+
+
+# ── Types ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class TelemetryOptions:
+    """Telemetry configuration."""
+
+    endpoint: str = "https://telemetry.monkeyscode.com/v1/events"
+    enabled: bool = False
+    metadata: dict[str, str] = field(default_factory=dict)
+    flush_interval_ms: int = 30_000
+
+
+@dataclass
+class TelemetryEvent:
+    """A telemetry event (anonymous)."""
+
+    type: str  # "run_start" | "run_complete" | "run_error"
+    timestamp: str = ""
+    sdk_version: str = SDK_VERSION
+    model: str = ""
+    event_counts: dict[str, int] = field(default_factory=dict)
+    tokens: dict[str, int] = field(default_factory=dict)
+    duration_ms: float = 0
+    error_code: str = ""
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+# ── Collector ────────────────────────────────────────────────────────
+
+
+class TelemetryCollector:
+    """
+    Collects and sends anonymous telemetry events.
+
+    Events are buffered and flushed periodically or on close.
+    """
+
+    def __init__(self, options: TelemetryOptions | None = None) -> None:
+        self._options = options or TelemetryOptions()
+        self._buffer: list[TelemetryEvent] = []
+        self._task: asyncio.Task[None] | None = None
+
+        if self._options.enabled:
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    self._task = loop.create_task(self._flush_loop())
+            except RuntimeError:
+                pass
+
+    @property
+    def enabled(self) -> bool:
+        return self._options.enabled
+
+    @property
+    def buffer_size(self) -> int:
+        return len(self._buffer)
+
+    def record_run_start(self, model: str) -> None:
+        """Record a run start event."""
+        if not self._options.enabled:
+            return
+        self._buffer.append(TelemetryEvent(
+            type="run_start",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            model=model,
+            metadata=self._options.metadata,
+        ))
+
+    def record_run_complete(
+        self,
+        model: str,
+        *,
+        tokens: dict[str, int] | None = None,
+        duration_ms: float = 0,
+        event_counts: dict[str, int] | None = None,
+    ) -> None:
+        """Record a run completion event."""
+        if not self._options.enabled:
+            return
+        self._buffer.append(TelemetryEvent(
+            type="run_complete",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            model=model,
+            tokens=tokens or {},
+            duration_ms=duration_ms,
+            event_counts=event_counts or {},
+            metadata=self._options.metadata,
+        ))
+
+    def record_error(self, model: str, error_code: str) -> None:
+        """Record a run error (code only, no PII)."""
+        if not self._options.enabled:
+            return
+        self._buffer.append(TelemetryEvent(
+            type="run_error",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            model=model,
+            error_code=error_code,
+            metadata=self._options.metadata,
+        ))
+
+    async def flush(self) -> None:
+        """Flush buffered events to the telemetry endpoint."""
+        if not self._options.enabled or not self._buffer:
+            return
+
+        events = self._buffer[:]
+        self._buffer.clear()
+
+        try:
+            async with httpx.AsyncClient() as client:
+                payload = {
+                    "events": [
+                        {
+                            "type": e.type,
+                            "timestamp": e.timestamp,
+                            "sdkVersion": e.sdk_version,
+                            "model": e.model,
+                            "eventCounts": e.event_counts,
+                            "tokens": e.tokens,
+                            "durationMs": e.duration_ms,
+                            "errorCode": e.error_code,
+                            "metadata": e.metadata,
+                        }
+                        for e in events
+                    ],
+                }
+                await client.post(
+                    self._options.endpoint,
+                    json=payload,
+                    timeout=5.0,
+                )
+        except Exception:
+            pass  # Telemetry should never break the app
+
+    async def close(self) -> None:
+        """Stop collecting and flush remaining events."""
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+        await self.flush()
+
+    async def _flush_loop(self) -> None:
+        """Background loop to flush events periodically."""
+        interval = self._options.flush_interval_ms / 1000
+        while True:
+            await asyncio.sleep(interval)
+            await self.flush()
+
+
+# ── Agent Integration ────────────────────────────────────────────────
+
+
+def with_telemetry(agent: Any, options: TelemetryOptions | None = None) -> Any:
+    """
+    Wrap a MonkeysCode agent with telemetry collection.
+
+    Non-invasive — the original agent is returned unchanged,
+    but event listeners are attached to collect anonymous usage data.
+    """
+    opts = options or TelemetryOptions()
+    if not opts.enabled:
+        return agent
+
+    collector = TelemetryCollector(opts)
+
+    agent.on("start", lambda e: collector.record_run_start(getattr(e, "model", "unknown")))
+    agent.on("error", lambda e: collector.record_error("unknown", getattr(e, "code", "UNKNOWN")))
+
+    return agent

monkeyscode/tools.py

@@ -0,0 +1,133 @@
+"""
+MonkeysCode SDK — Custom Tool Definitions.
+
+Define tools that the agent can call during a run.
+
+Usage::
+
+    from monkeyscode import define_tool, MonkeysCode
+
+    @define_tool(
+        name="deploy",
+        description="Deploy the application to an environment",
+        parameters={"env": {"type": "string", "enum": ["staging", "prod"]}},
+    )
+    async def deploy(env: str) -> dict:
+        return {"deployed": True, "url": f"https://{env}.example.com"}
+
+    agent = MonkeysCode(api_key="mc_...")
+    agent.add_tool(deploy)
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolDefinition:
+    """A custom tool that the agent can invoke."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+    handler: Callable[..., Any] | None = None
+
+    def to_json_schema(self) -> dict[str, Any]:
+        """Convert to the JSON Schema format expected by the model proxy."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": self.parameters,
+            },
+        }
+
+    async def execute(self, args: dict[str, Any]) -> Any:
+        """Execute the tool with the given arguments."""
+        if self.handler is None:
+            raise RuntimeError(f"Tool '{self.name}' has no handler")
+
+        if inspect.iscoroutinefunction(self.handler):
+            return await self.handler(**args)
+        else:
+            return self.handler(**args)
+
+
+def define_tool(
+    *,
+    name: str,
+    description: str,
+    parameters: dict[str, Any] | None = None,
+) -> Callable[[Callable[..., Any]], ToolDefinition]:
+    """
+    Decorator to define a custom tool.
+
+    Args:
+        name: Unique tool name (e.g., 'deploy', 'send_email').
+        description: Human-readable description for the agent.
+        parameters: JSON Schema for the tool's parameters.
+
+    Returns:
+        A ToolDefinition wrapping the decorated function.
+
+    Example::
+
+        @define_tool(
+            name="deploy",
+            description="Deploy to staging",
+            parameters={"env": {"type": "string"}},
+        )
+        async def deploy(env: str) -> dict:
+            return {"deployed": True}
+    """
+
+    def decorator(func: Callable[..., Any]) -> ToolDefinition:
+        tool = ToolDefinition(
+            name=name,
+            description=description,
+            parameters=parameters or _infer_parameters(func),
+            handler=func,
+        )
+        # Preserve function metadata
+        functools.update_wrapper(tool, func)  # type: ignore[arg-type]
+        return tool
+
+    return decorator
+
+
+def _infer_parameters(func: Callable[..., Any]) -> dict[str, Any]:
+    """
+    Infer JSON Schema parameters from function type hints.
+    Falls back to 'string' for unannotated parameters.
+    """
+    sig = inspect.signature(func)
+    properties: dict[str, Any] = {}
+
+    type_map = {
+        str: "string",
+        int: "integer",
+        float: "number",
+        bool: "boolean",
+        list: "array",
+        dict: "object",
+    }
+
+    for param_name, param in sig.parameters.items():
+        if param_name in ("self", "cls"):
+            continue
+
+        annotation = param.annotation
+        json_type = "string"  # default
+
+        if annotation != inspect.Parameter.empty:
+            json_type = type_map.get(annotation, "string")
+
+        properties[param_name] = {"type": json_type}
+
+    return properties

monkeyscode/watcher.py

@@ -0,0 +1,137 @@
+"""
+MonkeysCode SDK — File Watcher.
+
+Debounced, recursive file watcher for watch mode.
+Uses asyncio + os.walk polling (works cross-platform).
+
+Usage::
+
+    from monkeyscode.watcher import watch_files
+
+    async for batch in watch_files(directory="."):
+        print("Changed:", batch)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass, field
+
+# ── Types ────────────────────────────────────────────────────────────
+
+DEFAULT_IGNORES = [
+    "node_modules", ".git", "dist", "build", ".next", ".nuxt",
+    "target", "__pycache__", ".monkeyscode", ".DS_Store",
+    "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "Cargo.lock",
+    ".venv", "venv", ".mypy_cache", ".ruff_cache", ".pytest_cache",
+]
+
+
+@dataclass
+class WatchOptions:
+    """Options for the file watcher."""
+
+    directory: str = "."
+    ignore: list[str] = field(default_factory=list)
+    debounce_ms: int = 500
+    poll_interval_ms: int = 1000
+
+
+# ── Watcher ──────────────────────────────────────────────────────────
+
+
+async def watch_files(
+    directory: str = ".",
+    *,
+    ignore: list[str] | None = None,
+    debounce_ms: int = 500,
+    poll_interval_ms: int = 1000,
+) -> AsyncGenerator[list[str], None]:
+    """
+    Watch a directory recursively and yield batches of changed file paths.
+
+    Uses polling for cross-platform compatibility.
+    Batches changes within the debounce window.
+    """
+    all_ignores = set(DEFAULT_IGNORES + (ignore or []))
+    poll_interval = poll_interval_ms / 1000
+    debounce = debounce_ms / 1000
+
+    # Build initial snapshot
+    snapshot = _build_snapshot(directory, all_ignores)
+
+    while True:
+        await asyncio.sleep(poll_interval)
+
+        new_snapshot = _build_snapshot(directory, all_ignores)
+        changed = _diff_snapshots(snapshot, new_snapshot)
+
+        if changed:
+            # Debounce: wait and collect more changes
+            await asyncio.sleep(debounce)
+            final_snapshot = _build_snapshot(directory, all_ignores)
+            all_changed = _diff_snapshots(snapshot, final_snapshot)
+            snapshot = final_snapshot
+
+            if all_changed:
+                yield sorted(all_changed)
+        else:
+            snapshot = new_snapshot
+
+
+def _build_snapshot(directory: str, ignores: set[str]) -> dict[str, float]:
+    """Build a snapshot of file modification times."""
+    snapshot: dict[str, float] = {}
+
+    for root, dirs, files in os.walk(directory, topdown=True):
+        # Filter ignored directories in-place
+        dirs[:] = [d for d in dirs if not _should_ignore(d, ignores)]
+
+        for f in files:
+            if _should_ignore(f, ignores):
+                continue
+            path = os.path.join(root, f)
+            try:
+                snapshot[path] = os.path.getmtime(path)
+            except OSError:
+                pass
+
+    return snapshot
+
+
+def _diff_snapshots(old: dict[str, float], new: dict[str, float]) -> list[str]:
+    """Find changed files between two snapshots."""
+    changed: list[str] = []
+
+    # Modified or new files
+    for path, mtime in new.items():
+        old_mtime = old.get(path)
+        if old_mtime is None or mtime > old_mtime:
+            changed.append(path)
+
+    # Deleted files
+    for path in old:
+        if path not in new:
+            changed.append(path)
+
+    return changed
+
+
+def _should_ignore(name: str, ignores: set[str]) -> bool:
+    """Check if a file/directory should be ignored."""
+    if name.startswith("."):
+        # Allow .env files but ignore other dotfiles
+        if name not in (".env", ".env.local", ".env.development"):
+            return True
+    return name in ignores
+
+
+def format_change_batch(batch: list[str]) -> str:
+    """Format a batch of changed files for display."""
+    if not batch:
+        return "No changes"
+    if len(batch) == 1:
+        return f"Changed: {batch[0]}"
+    return f"Changed {len(batch)} files:\n" + "\n".join(f"  {f}" for f in batch[:20])

monkeyscode-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,25 @@
+monkeyscode/__init__.py,sha256=gWwGIwUJxcgZPXqnsl3z4JJ7JOMMQzhx4BD6CeR-fSY,4218
+monkeyscode/_http.py,sha256=6fsUcxAHgufWNg-e-VAvFTYoqVCRQl4xXQdykwNdUIE,2237
+monkeyscode/admin.py,sha256=7-1bLQjYMt9lf5rG6Y5k1-JQzbCpPFoLnb9TeV7NoDI,4717
+monkeyscode/agent.py,sha256=S-zHhcos-J1mZeNCKOnHUwIltQHdSKjjkLIBKJpy3Q8,27938
+monkeyscode/ci.py,sha256=dWz2t0At6H-rLL6X2l7dcLPIH6uMe2skWyTraeZQbqg,8912
+monkeyscode/cli_process.py,sha256=ZjCtvogo5hsTT5uRuQzpYlzdS9SBSAuEsN1AUl2wfPA,25644
+monkeyscode/daemon.py,sha256=MBjm-xgVq8jvlVf5QyR9IcyT7jB_u_iRGSVBr5tH4c4,6205
+monkeyscode/events.py,sha256=JIOOq0V5sJEQ7BxXMHL39k_stiBndij7rRuaNJC3uR8,8467
+monkeyscode/export.py,sha256=zw5kZGAEtVsMEINHQw9WJRoLcbSCrAkVY9_MOIfxE40,10234
+monkeyscode/hooks.py,sha256=Hv3u_3RF-u1BdKsuGRdDUEYzPihBSj-S-RwvDnC97Rw,5938
+monkeyscode/mcp.py,sha256=bpBsK2iFgfKE_nCqPNn8dgV0bWh_BJTKK9IpvtrqU_U,8431
+monkeyscode/orchestrator.py,sha256=BWbpvLU36GQmCqc0Ynh_p95e1S-gA8DM4odY76_yDWQ,5164
+monkeyscode/otel.py,sha256=1t5MvKur2Q_AAgU3Og1ToFdjhNoJyZIxi71Stsbm9_8,5696
+monkeyscode/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+monkeyscode/runs.py,sha256=HFdbmFqKYEAmrkZKArcCtRtBRbKZsf2ciiJcyivKdNE,4386
+monkeyscode/sandbox.py,sha256=-AkdU34MDckmIyU-cve-TF5czJK5HR301b9bR1bsc4Q,3247
+monkeyscode/session.py,sha256=y0r-jDAzTRwczkhUgw-Vw_Avle40tY5wYlK4BAfqnAk,6673
+monkeyscode/subagent.py,sha256=_hQ6fw0mlmgCB2da7vTqPXG41rDjPciejw9wwQcLL7A,6271
+monkeyscode/telemetry.py,sha256=Tw99XDYb7hunHUlpDCfy31lbhoqmH12hco5zFYRtsYw,6510
+monkeyscode/tools.py,sha256=wpEtCqA6QxfJAQ6RG39ydu3kfx-in5VXA6ff-erJ6i8,3625
+monkeyscode/watcher.py,sha256=s0ComQf3-OgpdCo280IALY1LL9tMeD7dbL219oiVcYM,4231
+monkeyscode-1.0.0.dist-info/METADATA,sha256=1E4CmiI3sYmU-ssRzxrkfFhjQipGe151R7pfiVL_B5U,4307
+monkeyscode-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+monkeyscode-1.0.0.dist-info/licenses/LICENSE,sha256=mW62yNQJrqKgXhs8vhcQ97KRUOg6RpIMzncFlFOmPW4,1069
+monkeyscode-1.0.0.dist-info/RECORD,,

monkeyscode-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

monkeyscode-1.0.0.dist-info/licenses/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.