morphsdk 0.2.5__py3-none-any.whl

morphsdk/_client.py

@@ -0,0 +1,245 @@
+"""Main client classes for the Morph SDK."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ._base import AsyncBaseClient, BaseClient, _configure_logging
+from ._config import ClientConfig, RetryConfig
+from ._constants import API_KEY_ENV_VAR, DEBUG_ENV_VAR, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from ._errors import AuthenticationError
+from .resources.browser import AsyncBrowserResource, BrowserResource
+from .resources.compact import acompact as _acompact_fn
+from .resources.compact import compact as _compact_fn
+from .resources.edit import AsyncEditResource, EditResource
+from .resources.explore import AsyncExploreResource, ExploreResource
+from .resources.git import AsyncGitResource, GitResource
+from .resources.github import AsyncGitHubResource, GitHubResource
+from .resources.grep import AsyncGrepResource, GrepResource
+from .resources.mobile import AsyncMobileResource, MobileResource
+from .resources.reflex import AsyncReflexResource, ReflexResource
+from .resources.router import AsyncRouterResource, RouterResource
+from .resources.search import AsyncSearchResource, SearchResource
+from .types.compact import CompactResult
+
+
+class Morph(BaseClient):
+    """Synchronous Morph SDK client.
+
+    Usage::
+
+        morph = Morph(api_key="sk-...")
+
+        # Edit files on disk
+        result = morph.edit.file(path="src/app.py", instruction="Fix bug", code_edit="...")
+
+        # Semantic codebase search
+        result = morph.search.code(query="auth middleware", repo_id="my-project")
+
+        # WarpGrep code search
+        result = morph.grep.read_github_file(github="vercel/next.js", path="package.json")
+
+        # Browser automation
+        result = morph.browser.run(task="Test login flow", url="https://app.example.com")
+
+        # Model routing
+        result = morph.router.select_model(input="Explain quicksort")
+
+        # Context compression
+        result = morph.compact(input="Long text to compress...")
+
+        # Framework tool creation
+        from morphsdk.adapters.openai import OpenAIAdapter
+        tools = OpenAIAdapter.edit_file_tool()
+    """
+
+    edit: EditResource
+    search: SearchResource
+    grep: GrepResource
+    browser: BrowserResource
+    git: GitResource
+    github: GitHubResource
+    mobile: MobileResource
+    router: RouterResource
+    explore: ExploreResource
+    reflex: ReflexResource
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        debug: bool = False,
+        github_installation_id: str | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get(API_KEY_ENV_VAR)
+        if not resolved_key:
+            raise AuthenticationError(
+                f"API key required. Pass api_key= or set {API_KEY_ENV_VAR} environment variable."
+            )
+
+        # Bridge debug=True to env var for logger
+        if debug and os.environ.get(DEBUG_ENV_VAR) != "1":
+            os.environ[DEBUG_ENV_VAR] = "1"
+            _configure_logging()
+
+        config = ClientConfig(
+            api_key=resolved_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            debug=debug,
+            retry_config=RetryConfig(max_retries=max_retries),
+            github_installation_id=github_installation_id,
+        )
+        super().__init__(config)
+
+        # Bind resources
+        self.edit = EditResource(self)
+        self.search = SearchResource(self)
+        self.grep = GrepResource(self)
+        self.browser = BrowserResource(self)
+        self.git = GitResource(self)
+        self.github = GitHubResource(
+            self, installation_id=github_installation_id
+        )
+        self.mobile = MobileResource(self)
+        self.router = RouterResource(self)
+        self.explore = ExploreResource(self)
+        self.reflex = ReflexResource(self)
+
+    def compact(
+        self,
+        *,
+        input: str | list[dict[str, Any]] | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        query: str | None = None,
+        compression_ratio: float = 0.5,
+        preserve_recent: int = 2,
+        include_line_ranges: bool = True,
+        include_markers: bool = True,
+        model: str | None = None,
+        timeout: float | None = None,
+    ) -> CompactResult:
+        """Compact messages or text for context compression.
+
+        Accepts either a plain string, a list of message dicts via *input*,
+        or a separate *messages* keyword. Returns per-message compacted and
+        kept line ranges.
+        """
+        return _compact_fn(
+            self,
+            input=input,
+            messages=messages,
+            query=query,
+            compression_ratio=compression_ratio,
+            preserve_recent=preserve_recent,
+            include_line_ranges=include_line_ranges,
+            include_markers=include_markers,
+            model=model,
+            timeout=timeout,
+        )
+
+
+class AsyncMorph(AsyncBaseClient):
+    """Asynchronous Morph SDK client.
+
+    Mirrors :class:`Morph` exactly, with every resource method as ``async def``
+    (streaming methods return an ``AsyncIterator``).
+
+    Usage::
+
+        async with AsyncMorph(api_key="sk-...") as morph:
+            result = await morph.edit.file(
+                path="src/app.py", instruction="Fix bug", code_edit="..."
+            )
+            result = await morph.search.code(query="auth middleware", repo_id="proj")
+            result = await morph.router.select_model(input="Explain quicksort")
+            result = await morph.compact(input="Long text to compress...")
+    """
+
+    edit: AsyncEditResource
+    search: AsyncSearchResource
+    grep: AsyncGrepResource
+    browser: AsyncBrowserResource
+    git: AsyncGitResource
+    github: AsyncGitHubResource
+    mobile: AsyncMobileResource
+    router: AsyncRouterResource
+    explore: AsyncExploreResource
+    reflex: AsyncReflexResource
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        debug: bool = False,
+        github_installation_id: str | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get(API_KEY_ENV_VAR)
+        if not resolved_key:
+            raise AuthenticationError(
+                f"API key required. Pass api_key= or set {API_KEY_ENV_VAR} environment variable."
+            )
+
+        # Bridge debug=True to env var for logger
+        if debug and os.environ.get(DEBUG_ENV_VAR) != "1":
+            os.environ[DEBUG_ENV_VAR] = "1"
+            _configure_logging()
+
+        config = ClientConfig(
+            api_key=resolved_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            debug=debug,
+            retry_config=RetryConfig(max_retries=max_retries),
+            github_installation_id=github_installation_id,
+        )
+        super().__init__(config)
+
+        # Bind async resources
+        self.edit = AsyncEditResource(self)
+        self.search = AsyncSearchResource(self)
+        self.grep = AsyncGrepResource(self)
+        self.browser = AsyncBrowserResource(self)
+        self.git = AsyncGitResource(self)
+        self.github = AsyncGitHubResource(self, installation_id=github_installation_id)
+        self.mobile = AsyncMobileResource(self)
+        self.router = AsyncRouterResource(self)
+        self.explore = AsyncExploreResource(self)
+        self.reflex = AsyncReflexResource(self)
+
+    async def compact(
+        self,
+        *,
+        input: str | list[dict[str, Any]] | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        query: str | None = None,
+        compression_ratio: float = 0.5,
+        preserve_recent: int = 2,
+        include_line_ranges: bool = True,
+        include_markers: bool = True,
+        model: str | None = None,
+        timeout: float | None = None,
+    ) -> CompactResult:
+        """Compact messages or text for context compression.
+
+        Accepts either a plain string, a list of message dicts via *input*,
+        or a separate *messages* keyword. Returns per-message compacted and
+        kept line ranges.
+        """
+        return await _acompact_fn(
+            self,
+            input=input,
+            messages=messages,
+            query=query,
+            compression_ratio=compression_ratio,
+            preserve_recent=preserve_recent,
+            include_line_ranges=include_line_ranges,
+            include_markers=include_markers,
+            model=model,
+            timeout=timeout,
+        )

morphsdk/_config.py

@@ -0,0 +1,37 @@
+"""Configuration types for the Morph SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from ._constants import (
+    DEFAULT_BACKOFF_MULTIPLIER,
+    DEFAULT_INITIAL_DELAY,
+    DEFAULT_MAX_DELAY,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+)
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for automatic request retries."""
+
+    max_retries: int = DEFAULT_MAX_RETRIES
+    initial_delay: float = DEFAULT_INITIAL_DELAY
+    max_delay: float = DEFAULT_MAX_DELAY
+    backoff_multiplier: float = DEFAULT_BACKOFF_MULTIPLIER
+    on_retry: Callable[[int, Exception], None] | None = None
+
+
+@dataclass
+class ClientConfig:
+    """Internal resolved configuration for the Morph client."""
+
+    api_key: str
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    debug: bool = False
+    retry_config: RetryConfig = field(default_factory=RetryConfig)
+    github_installation_id: str | None = None

morphsdk/_constants.py

@@ -0,0 +1,53 @@
+"""Constants for the Morph SDK."""
+
+# API base URLs
+API_BASE_URL = "https://api.morphllm.com"
+REPOS_BASE_URL = "https://repos.morphllm.com"
+BROWSER_BASE_URL = "https://browser.morphllm.com"
+
+# Default timeouts (seconds)
+DEFAULT_TIMEOUT = 30.0
+COMPACT_TIMEOUT = 120.0
+BROWSER_TIMEOUT = 1000.0
+ROUTER_TIMEOUT = 5.0
+
+# Default retry config
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_INITIAL_DELAY = 1.0
+DEFAULT_MAX_DELAY = 30.0
+DEFAULT_BACKOFF_MULTIPLIER = 2.0
+
+# Models
+FAST_APPLY_MODEL_FAST = "morph-v3-fast"
+FAST_APPLY_MODEL_LARGE = "morph-v3-large"
+WARP_GREP_MODEL = "morph-warp-grep-v2.1"
+COMPACT_MODEL = "morph-compactor"
+DEFAULT_BROWSER_MODEL = "morph-computer-use-v0"
+
+# WarpGrep agent config
+WARP_GREP_MAX_TURNS = 6
+# Matches the TS AGENT_CONFIG.TIMEOUT_MS default (60_000 ms). Overridable via
+# the MORPH_WARP_GREP_TIMEOUT env var (expressed in milliseconds, like TS).
+WARP_GREP_TIMEOUT = 60.0
+WARP_GREP_MAX_CONTEXT_CHARS = 321_600
+WARP_GREP_MAX_OUTPUT_LINES = 200
+WARP_GREP_MAX_LIST_RESULTS = 500
+WARP_GREP_MAX_READ_LINES = 800
+WARP_GREP_MAX_LIST_DEPTH = 3
+
+# Default excludes for grep
+DEFAULT_EXCLUDES = [
+    ".git", "node_modules", "__pycache__", "dist", "build",
+    ".next", ".cache", ".vscode", ".idea",
+    "*.lock", "*.min.js", "*.min.css",
+]
+
+# API key env var
+API_KEY_ENV_VAR = "MORPH_API_KEY"
+
+# Debug/logging env vars
+DEBUG_ENV_VAR = "MORPH_DEBUG"
+LOG_FILE_ENV_VAR = "MORPH_LOG_FILE"
+
+# Git proxy
+DEFAULT_GIT_PROXY_URL = "https://repos.morphllm.com"

morphsdk/_errors.py

@@ -0,0 +1,111 @@
+"""Error hierarchy for the Morph SDK.
+
+All SDK errors inherit from MorphError. HTTP errors are mapped to specific
+subclasses based on status code.
+"""
+
+from __future__ import annotations
+
+
+class MorphError(Exception):
+    """Base error for all Morph SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+
+    def __repr__(self) -> str:
+        parts = [f"message={self.message!r}"]
+        if self.status_code is not None:
+            parts.append(f"status_code={self.status_code}")
+        if self.code is not None:
+            parts.append(f"code={self.code!r}")
+        return f"{self.__class__.__name__}({', '.join(parts)})"
+
+
+class AuthenticationError(MorphError):
+    """401 - Invalid or missing API key."""
+
+    def __init__(self, message: str = "Invalid or missing API key") -> None:
+        super().__init__(message, status_code=401, code="authentication_error")
+
+
+class PermissionDeniedError(MorphError):
+    """403 - Insufficient permissions."""
+
+    def __init__(self, message: str = "Permission denied") -> None:
+        super().__init__(message, status_code=403, code="permission_denied")
+
+
+class NotFoundError(MorphError):
+    """404 - Resource not found."""
+
+    def __init__(self, message: str = "Resource not found") -> None:
+        super().__init__(message, status_code=404, code="not_found")
+
+
+class RateLimitError(MorphError):
+    """429 - Rate limit exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        *,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=429, code="rate_limit")
+        self.retry_after = retry_after
+
+
+class ValidationError(MorphError):
+    """400 - Invalid request parameters."""
+
+    def __init__(self, message: str = "Validation error") -> None:
+        super().__init__(message, status_code=400, code="validation_error")
+
+
+class APIConnectionError(MorphError):
+    """Network-level connection failure."""
+
+    def __init__(self, message: str = "Connection error") -> None:
+        super().__init__(message, code="connection_error")
+
+
+class APITimeoutError(MorphError):
+    """Request timed out."""
+
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message, code="timeout")
+
+
+class InternalError(MorphError):
+    """500+ - Server-side error."""
+
+    def __init__(self, message: str = "Internal server error", *, status_code: int = 500) -> None:
+        super().__init__(message, status_code=status_code, code="internal_error")
+
+
+def raise_for_status(status_code: int, message: str) -> None:
+    """Raise the appropriate MorphError subclass for an HTTP status code."""
+    if status_code == 401:
+        raise AuthenticationError(message)
+    elif status_code == 403:
+        raise PermissionDeniedError(message)
+    elif status_code == 404:
+        raise NotFoundError(message)
+    elif status_code == 429:
+        raise RateLimitError(message)
+    elif status_code == 400:
+        raise ValidationError(message)
+    elif status_code >= 500:
+        raise InternalError(message, status_code=status_code)
+    else:
+        raise MorphError(message, status_code=status_code)

morphsdk/_providers/__init__.py

@@ -0,0 +1,36 @@
+"""Provider implementations for WarpGrep and other multi-backend resources.
+
+A WarpGrep *provider* is the filesystem backend the agent loop searches:
+
+* :class:`LocalRipgrepProvider` -- a local checkout via ``rg``.
+* :class:`RemoteCommandsProvider` -- user-supplied command callables, including
+  the HTTP code-storage backend built by
+  :func:`create_code_storage_http_commands`.
+"""
+
+from __future__ import annotations
+
+from .base import (
+    GrepResult,
+    ListDirectoryEntry,
+    ReadResult,
+    WarpGrepProvider,
+)
+from .code_storage_http import (
+    CodeStorageHttpConfig,
+    create_code_storage_http_commands,
+)
+from .local import LocalRipgrepProvider
+from .remote import RemoteCommands, RemoteCommandsProvider
+
+__all__ = [
+    "WarpGrepProvider",
+    "GrepResult",
+    "ReadResult",
+    "ListDirectoryEntry",
+    "LocalRipgrepProvider",
+    "RemoteCommands",
+    "RemoteCommandsProvider",
+    "CodeStorageHttpConfig",
+    "create_code_storage_http_commands",
+]

morphsdk/_providers/_filter.py

@@ -0,0 +1,92 @@
+"""Shared filename-filtering and path helpers for WarpGrep providers.
+
+Ported from the TypeScript ``local.ts`` / ``remote.ts`` ``shouldSkip`` logic and
+``paths.ts`` repo-containment helpers.  Kept private to ``_providers``.
+"""
+
+from __future__ import annotations
+
+import os
+
+# Directories/files to always skip (exact name match).
+SKIP_NAMES = frozenset(
+    {
+        # Version control
+        ".git", ".svn", ".hg", ".bzr",
+        # Dependencies
+        "node_modules", "bower_components", ".pnpm", ".yarn",
+        "vendor", "Pods", ".bundle",
+        # Python
+        "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+        ".venv", "venv", ".tox", ".nox", ".eggs",
+        # Build outputs
+        "dist", "build", "out", "output", "target", "_build",
+        ".next", ".nuxt", ".output", ".vercel", ".netlify",
+        # Cache
+        ".cache", ".parcel-cache", ".turbo", ".nx", ".gradle",
+        # IDE
+        ".idea", ".vscode", ".vs",
+        # Coverage
+        "coverage", ".coverage", "htmlcov", ".nyc_output",
+        # Temp
+        "tmp", "temp", ".tmp", ".temp",
+        # Lock files
+        "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb",
+        "Cargo.lock", "Gemfile.lock", "poetry.lock",
+    }
+)
+
+# File extensions/suffixes to skip.
+SKIP_EXTENSIONS = frozenset(
+    {
+        ".min.js", ".min.css", ".bundle.js",
+        ".wasm", ".so", ".dll", ".pyc",
+        ".map", ".js.map",
+    }
+)
+
+
+def should_skip(name: str, allow_names: frozenset[str] | None = None) -> bool:
+    """Return ``True`` if a directory/file name should be skipped during listing."""
+    if allow_names is not None and name in allow_names:
+        return False
+    if name in SKIP_NAMES:
+        return True
+    if name.startswith("."):
+        return True
+    return any(name.endswith(ext) for ext in SKIP_EXTENSIONS)
+
+
+def resolve_under_repo(repo_root: str, target_path: str) -> str:
+    """Resolve *target_path* against *repo_root*, raising if it escapes the root.
+
+    Mirrors ``resolveUnderRepo`` + ``ensureWithinRepo`` from ``paths.ts``.  Like
+    Node's ``path.resolve`` this is purely lexical -- it does **not** dereference
+    symlinks, so callers can still detect a symlinked target afterwards.
+    """
+    abs_root = os.path.abspath(repo_root)
+    resolved = os.path.abspath(os.path.join(abs_root, target_path))
+    rel = os.path.relpath(resolved, abs_root)
+    if rel == ".." or rel.startswith(".." + os.sep) or os.path.isabs(rel):
+        raise ValueError(f"Path outside repository root: {resolved}")
+    return resolved
+
+
+def to_repo_relative(repo_root: str, abs_path: str) -> str:
+    """Return *abs_path* relative to *repo_root* (``toRepoRelative`` in ``paths.ts``)."""
+    return os.path.relpath(os.path.abspath(abs_path), os.path.abspath(repo_root))
+
+
+def is_textual_file(file_path: str, max_bytes: int = 2_000_000) -> bool:
+    """Heuristic: a regular, non-oversized file with no NUL byte in its first 512 bytes."""
+    try:
+        st = os.stat(file_path)
+        if not os.path.isfile(file_path):
+            return False
+        if st.st_size > max_bytes:
+            return False
+        with open(file_path, "rb") as fh:
+            chunk = fh.read(512)
+        return b"\x00" not in chunk
+    except OSError:
+        return False

morphsdk/_providers/base.py

@@ -0,0 +1,94 @@
+"""Provider abstraction for the WarpGrep agent loop.
+
+A :class:`WarpGrepProvider` is the filesystem backend the agent searches
+against.  Two implementations ship with the SDK:
+
+* :class:`~morphsdk._providers.local.LocalRipgrepProvider` -- shells out to
+  ``rg`` against a local checkout.
+* :class:`~morphsdk._providers.remote.RemoteCommandsProvider` -- delegates to
+  user-supplied command callables (e.g. a sandbox or the HTTP code-storage
+  backend via :func:`~morphsdk._providers.code_storage_http.create_code_storage_http_commands`).
+
+The method names mirror the TypeScript ``WarpGrepProvider`` interface and the
+result shapes match it byte-for-byte (the agent depends on the exact line
+formats: ``"path:line:content"`` for grep, ``"lineNumber|content"`` for read).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class GrepResult:
+    """Result of a :meth:`WarpGrepProvider.grep` call.
+
+    ``lines`` are ripgrep-style with context: ``"path:line:content"`` for
+    matches and ``"path-line-content"`` for context lines.  ``error`` carries a
+    graceful, agent-readable message (e.g. ripgrep not installed) instead of
+    raising.
+    """
+
+    lines: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+@dataclass
+class ReadResult:
+    """Result of a :meth:`WarpGrepProvider.read` call.
+
+    ``lines`` are in ``"lineNumber|content"`` format.  ``error`` carries a
+    graceful message (file not found, symlink, unreadable, ...).
+    """
+
+    lines: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+@dataclass
+class ListDirectoryEntry:
+    """A single entry returned by :meth:`WarpGrepProvider.list_directory`."""
+
+    name: str
+    path: str
+    type: Literal["file", "dir"]
+    depth: int
+
+
+class WarpGrepProvider(ABC):
+    """Filesystem backend the WarpGrep agent searches against."""
+
+    @abstractmethod
+    async def grep(
+        self,
+        *,
+        pattern: str,
+        path: str,
+        glob: str | None = None,
+        context_lines: int | None = None,
+        case_sensitive: bool | None = None,
+    ) -> GrepResult:
+        """Run a regex grep with an optional file glob filter."""
+
+    @abstractmethod
+    async def read(
+        self,
+        *,
+        path: str,
+        start_line: int | None = None,
+        end_line: int | None = None,
+    ) -> ReadResult:
+        """Read lines from a file (1-indexed, inclusive range)."""
+
+    @abstractmethod
+    async def list_directory(
+        self,
+        *,
+        path: str,
+        pattern: str | None = None,
+        max_results: int | None = None,
+        max_depth: int | None = None,
+    ) -> list[ListDirectoryEntry]:
+        """List directory contents as a flat, depth-annotated tree."""