morphsdk 0.2.5__py3-none-any.whl

morphsdk/_agent/tools.py

@@ -0,0 +1,171 @@
+"""Tool execution against a :class:`WarpGrepProvider`.
+
+Faithful port of ``agent/tools/*.ts`` and the ``executeTool`` dispatcher in
+``agent/runner.ts``.  Each function turns a model-issued tool call into a single
+provider call and formats the output string exactly as the TS does (the strings
+are part of the model's training distribution).
+
+Note on ``glob``: the TypeScript ``WarpGrepProvider`` interface exposes a
+``glob`` method, but the **Python** provider base
+(:class:`morphsdk._providers.base.WarpGrepProvider`) intentionally does not.  The
+``glob`` tool is still advertised to the model (it is part of the wire tool
+schema, so we keep it byte-for-byte), but when the active provider lacks a
+``glob`` implementation we return the standard ``"no matches"`` string rather
+than inventing a second search backend.  See the port report.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from morphsdk._providers.base import WarpGrepProvider
+
+from .parser import extract_path_from_command, parse_read_lines
+
+
+async def _tool_grep(
+    provider: WarpGrepProvider,
+    *,
+    pattern: str,
+    path: str,
+    glob: str | None = None,
+    case_sensitive: bool | None = None,
+) -> str:
+    """Run grep and format like ``toolGrep``: error text, ``"no matches"``, or lines."""
+    res = await provider.grep(
+        pattern=pattern, path=path, glob=glob, case_sensitive=case_sensitive
+    )
+    if res.error:
+        return res.error
+    if not res.lines:
+        return "no matches"
+    return "\n".join(res.lines)
+
+
+async def _tool_read(
+    provider: WarpGrepProvider,
+    *,
+    path: str,
+    start: int | None = None,
+    end: int | None = None,
+    lines: list[tuple[int, int]] | None = None,
+) -> str:
+    """Read a file or ranges, formatted like ``toolRead`` (``\\n...\\n`` between blocks)."""
+    if lines:
+        valid_ranges = [
+            (s, e)
+            for s, e in lines
+            if isinstance(s, int) and isinstance(e, int) and s > 0 and e >= s
+        ]
+        if not valid_ranges:
+            res = await provider.read(path=path)
+            if res.error:
+                return res.error
+            return "\n".join(res.lines) if res.lines else "(empty file)"
+        chunks: list[str] = []
+        for s, e in valid_ranges:
+            res = await provider.read(path=path, start_line=s, end_line=e)
+            if res.error:
+                return res.error
+            chunks.append("\n".join(res.lines))
+        if all(c == "" for c in chunks):
+            return "(empty file)"
+        return "\n...\n".join(chunks)
+
+    res = await provider.read(path=path, start_line=start, end_line=end)
+    if res.error:
+        return res.error
+    return "\n".join(res.lines) if res.lines else "(empty file)"
+
+
+async def _tool_list_directory(
+    provider: WarpGrepProvider,
+    *,
+    path: str,
+    repo_root: str | None = None,
+) -> str:
+    """List a directory, returning absolute paths (one per line) like ``toolListDirectory``."""
+    import os
+
+    entries = await provider.list_directory(path=path)
+    if not entries:
+        return "empty"
+    if repo_root:
+        return "\n".join(os.path.join(repo_root, e.path) for e in entries)
+    return "\n".join(e.path for e in entries)
+
+
+async def _tool_glob(
+    provider: WarpGrepProvider,
+    *,
+    pattern: str,
+    path: str | None = None,
+) -> str:
+    """Glob fallback. The Python provider base has no ``glob``; if the concrete
+    provider supplies one (duck-typed, TS-shaped), use it; otherwise degrade to
+    the standard ``"no matches"`` string."""
+    glob_fn = getattr(provider, "glob", None)
+    if glob_fn is None:
+        return "no matches"
+    res = await glob_fn(pattern=pattern, path=path)
+    error = getattr(res, "error", None)
+    files = getattr(res, "files", [])
+    if error:
+        return str(error)
+    if not files:
+        return "no matches"
+    total_found = getattr(res, "total_found", len(files))
+    search_dir = getattr(res, "search_dir", path or ".")
+    header = (
+        f'Found {total_found} file(s) matching "{pattern}" within {search_dir}, '
+        "sorted by modification time (newest first):"
+    )
+    body = "\n".join(files)
+    truncated = (
+        f"\n[{total_found - len(files)} files truncated]" if total_found > len(files) else ""
+    )
+    return f"{header}\n---\n{body}\n---{truncated}"
+
+
+async def execute_tool(
+    provider: WarpGrepProvider,
+    name: str,
+    args: dict[str, Any],
+    repo_root: str | None = None,
+) -> str:
+    """Dispatch a single tool call to the provider (mirrors ``executeTool``)."""
+    if name == "grep_search":
+        output = await _tool_grep(
+            provider,
+            pattern=str(args.get("pattern", "")),
+            path=str(args.get("path") or "."),
+            glob=args["glob"] if args.get("glob") else None,
+            case_sensitive=(
+                bool(args["case_sensitive"]) if args.get("case_sensitive") is not None else None
+            ),
+        )
+        limit = args.get("limit")
+        if isinstance(limit, int):
+            out_lines = output.split("\n")
+            if len(out_lines) > limit:
+                output = "\n".join(out_lines[:limit]) + f"\n... (truncated at {limit} lines)"
+        return output
+
+    if name == "glob":
+        path = args.get("path")
+        return await _tool_glob(
+            provider, pattern=str(args.get("pattern", "")), path=str(path) if path else None
+        )
+
+    if name == "list_directory":
+        dir_path = extract_path_from_command(str(args.get("command") or "."))
+        return await _tool_list_directory(provider, path=dir_path, repo_root=repo_root)
+
+    if name == "read":
+        read_kwargs: dict[str, Any] = {"path": str(args.get("path", ""))}
+        lines_arg = args.get("lines")
+        if isinstance(lines_arg, str):
+            read_kwargs.update(parse_read_lines(lines_arg))
+        return await _tool_read(provider, **read_kwargs)
+
+    return f"Unknown tool: {name}"

morphsdk/_agent/types.py

@@ -0,0 +1,126 @@
+"""Core types for the WarpGrep multi-turn agent loop.
+
+Faithful port of ``tools/warp_grep/agent/types.ts``.  The chat-message and
+tool-call shapes mirror the OpenAI chat-completions wire format exactly, because
+they are serialized straight onto the request body sent to the Morph API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Union
+
+# A finish file spec: a path plus either "*" (whole file) or explicit line ranges.
+FinishLines = Union[Literal["*"], list[tuple[int, int]]]
+
+
+@dataclass
+class ToolCallRef:
+    """A single tool call emitted by the model (OpenAI function-call shape)."""
+
+    id: str
+    name: str
+    arguments: str  # raw JSON string, exactly as returned by the model
+    type: Literal["function"] = "function"
+
+
+@dataclass
+class ChatMessage:
+    """One message in the conversation, serializable to the OpenAI wire shape.
+
+    ``role`` is one of ``system`` | ``user`` | ``assistant`` | ``tool``.
+    Only ``assistant`` carries ``tool_calls``; only ``tool`` carries
+    ``tool_call_id``.
+    """
+
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str | None
+    tool_calls: list[ToolCallRef] | None = None
+    tool_call_id: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Serialize to the exact JSON the chat-completions endpoint expects."""
+        if self.role == "tool":
+            return {
+                "role": "tool",
+                "tool_call_id": self.tool_call_id,
+                "content": self.content,
+            }
+        if self.role == "assistant":
+            msg: dict[str, Any] = {"role": "assistant", "content": self.content}
+            if self.tool_calls:
+                msg["tool_calls"] = [
+                    {
+                        "id": tc.id,
+                        "type": tc.type,
+                        "function": {"name": tc.name, "arguments": tc.arguments},
+                    }
+                    for tc in self.tool_calls
+                ]
+            return msg
+        return {"role": self.role, "content": self.content}
+
+
+@dataclass
+class FinishFileSpec:
+    """A file the model wants returned, with full-file or ranged selection."""
+
+    path: str
+    lines: FinishLines
+
+
+@dataclass
+class ResolvedContext:
+    """A resolved finish file: ranges plus the actual concatenated content."""
+
+    path: str
+    ranges: FinishLines
+    content: str
+
+
+@dataclass
+class AgentFinish:
+    """The model's finish payload metadata (the files it selected)."""
+
+    files: list[FinishFileSpec]
+
+
+@dataclass
+class WarpGrepTurnMetrics:
+    turn: int
+    morph_api_ms: int = 0
+    local_tools_ms: int = 0
+
+
+@dataclass
+class WarpGrepExecutionMetrics:
+    timeout_ms: int = 0
+    total_ms: int = 0
+    initial_state_ms: int = 0
+    finish_resolution_ms: int = 0
+    turns: list[WarpGrepTurnMetrics] = field(default_factory=list)
+
+
+@dataclass
+class WarpGrepStep:
+    """A single streamed step: the turn number and the tool calls made."""
+
+    turn: int
+    tool_calls: list[dict[str, Any]]
+
+
+@dataclass
+class AgentRunResult:
+    """Final result of a complete agent run.
+
+    Mirrors the TS ``AgentRunResult``.  ``finish`` is populated only when
+    ``termination_reason == "completed"``.
+    """
+
+    termination_reason: Literal["completed", "terminated", "error"]
+    messages: list[ChatMessage]
+    finish_payload: str | None = None
+    finish_metadata: AgentFinish | None = None
+    resolved: list[ResolvedContext] | None = None
+    errors: list[dict[str, str]] = field(default_factory=list)
+    timings: WarpGrepExecutionMetrics | None = None

morphsdk/_base.py

@@ -0,0 +1,309 @@
+"""Base HTTP client with retry, timeout, and auth.
+
+Provides both sync (BaseClient) and async (AsyncBaseClient) variants.
+All resource classes delegate HTTP calls to these.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+import httpx
+
+from ._config import ClientConfig, RetryConfig
+from ._constants import DEBUG_ENV_VAR, LOG_FILE_ENV_VAR
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    RateLimitError,
+    raise_for_status,
+)
+from ._version import __version__
+
+logger = logging.getLogger("morphsdk")
+
+_RETRYABLE_STATUS_CODES = {429, 503}
+
+
+def _configure_logging() -> None:
+    """Configure logging based on MORPH_DEBUG and MORPH_LOG_FILE env vars."""
+    if os.environ.get(DEBUG_ENV_VAR) == "1" or os.environ.get(LOG_FILE_ENV_VAR):
+        logger.setLevel(logging.DEBUG)
+
+        # Add stderr handler if not already present
+        has_stderr = any(
+            isinstance(h, logging.StreamHandler) and not isinstance(h, logging.FileHandler)
+            for h in logger.handlers
+        )
+        if not has_stderr:
+            sh = logging.StreamHandler()
+            sh.setFormatter(
+                logging.Formatter("[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s")
+            )
+            logger.addHandler(sh)
+
+        # Add file handler if MORPH_LOG_FILE is set
+        log_file = os.environ.get(LOG_FILE_ENV_VAR)
+        if log_file and not any(isinstance(h, logging.FileHandler) for h in logger.handlers):
+            fh = logging.FileHandler(log_file, mode="a")
+            fh.setFormatter(
+                logging.Formatter(
+                    '{"ts":"%(asctime)s","level":"%(levelname)s","component":"%(name)s","msg":"%(message)s"}'
+                )
+            )
+            logger.addHandler(fh)
+
+
+_configure_logging()
+
+
+def _default_headers() -> dict[str, str]:
+    return {
+        "X-Morph-SDK-Version": __version__,
+        "X-Morph-SDK-Lang": "python",
+    }
+
+
+class BaseClient:
+    """Synchronous HTTP client with retry and auth."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._http = httpx.Client(
+            timeout=httpx.Timeout(config.timeout),
+            headers=_default_headers(),
+        )
+
+    @property
+    def api_key(self) -> str:
+        return self._config.api_key
+
+    @property
+    def debug(self) -> bool:
+        return self._config.debug
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, str] | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+        retry_config: RetryConfig | None = None,
+    ) -> httpx.Response:
+        """Make an authenticated HTTP request with retry."""
+        rc = retry_config or self._config.retry_config
+        effective_timeout = timeout or self._config.timeout
+
+        req_headers = {"Authorization": f"Bearer {self._config.api_key}"}
+        if json is not None:
+            req_headers["Content-Type"] = "application/json"
+        if headers:
+            req_headers.update(headers)
+
+        last_exc: Exception | None = None
+        delay = rc.initial_delay
+
+        for attempt in range(rc.max_retries + 1):
+            try:
+                if self._config.debug:
+                    logger.debug(f"[morphsdk] {method} {url} (attempt {attempt + 1})")
+
+                response = self._http.request(
+                    method,
+                    url,
+                    json=json,
+                    params=params,
+                    headers=req_headers,
+                    timeout=effective_timeout,
+                )
+
+                if response.status_code in _RETRYABLE_STATUS_CODES and attempt < rc.max_retries:
+                    retry_after = response.headers.get("Retry-After")
+                    wait = float(retry_after) if retry_after else min(delay, rc.max_delay)
+                    if rc.on_retry:
+                        rc.on_retry(
+                            attempt + 1,
+                            RateLimitError(f"HTTP {response.status_code}"),
+                        )
+                    time.sleep(wait)
+                    delay *= rc.backoff_multiplier
+                    continue
+
+                if not response.is_success:
+                    text = response.text
+                    try:
+                        data = response.json()
+                        text = (
+                            data.get("error")
+                            or data.get("detail")
+                            or data.get("message")
+                            or text
+                        )
+                    except Exception:
+                        pass
+                    raise_for_status(response.status_code, str(text))
+
+                return response
+
+            except (httpx.ConnectError, httpx.RemoteProtocolError) as e:
+                last_exc = e
+                if attempt < rc.max_retries:
+                    if rc.on_retry:
+                        rc.on_retry(attempt + 1, e)
+                    time.sleep(min(delay, rc.max_delay))
+                    delay *= rc.backoff_multiplier
+                    continue
+                raise APIConnectionError(str(e)) from e
+
+            except httpx.TimeoutException as e:
+                last_exc = e
+                if attempt < rc.max_retries:
+                    if rc.on_retry:
+                        rc.on_retry(attempt + 1, e)
+                    time.sleep(min(delay, rc.max_delay))
+                    delay *= rc.backoff_multiplier
+                    continue
+                raise APITimeoutError(str(e)) from e
+
+        raise (
+            APIConnectionError(str(last_exc))
+            if last_exc
+            else APIConnectionError("Max retries exceeded")
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> BaseClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncBaseClient:
+    """Asynchronous HTTP client with retry and auth."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._http = httpx.AsyncClient(
+            timeout=httpx.Timeout(config.timeout),
+            headers=_default_headers(),
+        )
+
+    @property
+    def api_key(self) -> str:
+        return self._config.api_key
+
+    @property
+    def debug(self) -> bool:
+        return self._config.debug
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, str] | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+        retry_config: RetryConfig | None = None,
+    ) -> httpx.Response:
+        """Make an authenticated async HTTP request with retry."""
+        import asyncio
+
+        rc = retry_config or self._config.retry_config
+        effective_timeout = timeout or self._config.timeout
+
+        req_headers = {"Authorization": f"Bearer {self._config.api_key}"}
+        if json is not None:
+            req_headers["Content-Type"] = "application/json"
+        if headers:
+            req_headers.update(headers)
+
+        last_exc: Exception | None = None
+        delay = rc.initial_delay
+
+        for attempt in range(rc.max_retries + 1):
+            try:
+                if self._config.debug:
+                    logger.debug(f"[morphsdk] {method} {url} (attempt {attempt + 1})")
+
+                response = await self._http.request(
+                    method,
+                    url,
+                    json=json,
+                    params=params,
+                    headers=req_headers,
+                    timeout=effective_timeout,
+                )
+
+                if response.status_code in _RETRYABLE_STATUS_CODES and attempt < rc.max_retries:
+                    retry_after = response.headers.get("Retry-After")
+                    wait = float(retry_after) if retry_after else min(delay, rc.max_delay)
+                    if rc.on_retry:
+                        rc.on_retry(
+                            attempt + 1,
+                            RateLimitError(f"HTTP {response.status_code}"),
+                        )
+                    await asyncio.sleep(wait)
+                    delay *= rc.backoff_multiplier
+                    continue
+
+                if not response.is_success:
+                    text = response.text
+                    try:
+                        data = response.json()
+                        text = (
+                            data.get("error")
+                            or data.get("detail")
+                            or data.get("message")
+                            or text
+                        )
+                    except Exception:
+                        pass
+                    raise_for_status(response.status_code, str(text))
+
+                return response
+
+            except (httpx.ConnectError, httpx.RemoteProtocolError) as e:
+                last_exc = e
+                if attempt < rc.max_retries:
+                    if rc.on_retry:
+                        rc.on_retry(attempt + 1, e)
+                    await asyncio.sleep(min(delay, rc.max_delay))
+                    delay *= rc.backoff_multiplier
+                    continue
+                raise APIConnectionError(str(e)) from e
+
+            except httpx.TimeoutException as e:
+                last_exc = e
+                if attempt < rc.max_retries:
+                    if rc.on_retry:
+                        rc.on_retry(attempt + 1, e)
+                    await asyncio.sleep(min(delay, rc.max_delay))
+                    delay *= rc.backoff_multiplier
+                    continue
+                raise APITimeoutError(str(e)) from e
+
+        raise (
+            APIConnectionError(str(last_exc))
+            if last_exc
+            else APIConnectionError("Max retries exceeded")
+        )
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncBaseClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()