morphsdk 0.2.5__py3-none-any.whl

morphsdk/__init__.py

@@ -0,0 +1,54 @@
+"""Morph SDK -- AI-powered code editing, search, browser automation, and more.
+
+Usage::
+
+    from morphsdk import Morph
+
+    morph = Morph(api_key="sk-...")
+
+    # Edit files
+    result = morph.edit.file(path="app.py", instruction="Fix bug", code_edit="...")
+
+    # Search code
+    result = morph.search.code(query="authentication", repo_id="my-project")
+
+    # Browser automation
+    result = morph.browser.run(task="Test login", url="https://app.example.com")
+
+    # Context compression
+    result = morph.compact(input="Long text to compress...")
+
+    # Model routing
+    result = morph.router.select_model(input="Explain quicksort")
+"""
+
+from ._client import AsyncMorph, Morph
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    InternalError,
+    MorphError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    # Clients
+    "Morph",
+    "AsyncMorph",
+    # Errors
+    "MorphError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "InternalError",
+]

morphsdk/_agent/__init__.py

@@ -0,0 +1,64 @@
+"""Agent orchestration internals (WarpGrep multi-turn loop, Explore subagent).
+
+The WarpGrep agent core is **async** -- it awaits the async providers and a
+single ``httpx`` chat-completions call per turn.  ``run_warp_grep`` /
+``run_warp_grep_streaming`` are the public entry points consumed by the sync
+``GrepResource`` (via :func:`asyncio.run` / a thread bridge) and, in a later
+wave, directly by the async client.
+"""
+
+from __future__ import annotations
+
+from .explore import (
+    DEFAULT_MAX_TURNS as EXPLORE_DEFAULT_MAX_TURNS,
+)
+from .explore import (
+    DEFAULT_THOROUGHNESS,
+    ExploreContext,
+    ExploreMessageEvent,
+    ExploreRunResult,
+    ExploreStepEvent,
+    ExploreThoroughness,
+    run_explore,
+    run_explore_streaming,
+)
+from .runner import (
+    TOOL_SPECS,
+    call_model,
+    run_warp_grep,
+    run_warp_grep_streaming,
+)
+from .types import (
+    AgentFinish,
+    AgentRunResult,
+    ChatMessage,
+    FinishFileSpec,
+    ResolvedContext,
+    ToolCallRef,
+    WarpGrepExecutionMetrics,
+    WarpGrepStep,
+)
+
+__all__ = [
+    "run_warp_grep",
+    "run_warp_grep_streaming",
+    "call_model",
+    "TOOL_SPECS",
+    "run_explore",
+    "run_explore_streaming",
+    "ExploreRunResult",
+    "ExploreStepEvent",
+    "ExploreMessageEvent",
+    "ExploreContext",
+    "ExploreThoroughness",
+    "EXPLORE_DEFAULT_MAX_TURNS",
+    "DEFAULT_THOROUGHNESS",
+    "AgentRunResult",
+    "AgentFinish",
+    "ChatMessage",
+    "FinishFileSpec",
+    "ResolvedContext",
+    "ToolCallRef",
+    "WarpGrepStep",
+    "WarpGrepExecutionMetrics",
+]

morphsdk/_agent/config.py

@@ -0,0 +1,52 @@
+"""Agent loop configuration constants.
+
+Cross-checked against the TypeScript ``AGENT_CONFIG`` (``agent/config.ts``).
+Every value here matches ``_constants.py`` **except the timeout**: the TS default
+is 60_000 ms, while ``_constants.WARP_GREP_TIMEOUT`` is 30.0 s.  The TS value is
+authoritative for the agent loop, so we override it module-locally here (the
+shared ``_constants`` module is owned elsewhere and intentionally left untouched).
+"""
+
+from __future__ import annotations
+
+import os
+
+from morphsdk._constants import (
+    WARP_GREP_MAX_CONTEXT_CHARS,
+    WARP_GREP_MAX_LIST_DEPTH,
+    WARP_GREP_MAX_LIST_RESULTS,
+    WARP_GREP_MAX_OUTPUT_LINES,
+    WARP_GREP_MAX_READ_LINES,
+    WARP_GREP_MAX_TURNS,
+    WARP_GREP_MODEL,
+)
+
+DEFAULT_MODEL = WARP_GREP_MODEL
+MAX_TURNS = WARP_GREP_MAX_TURNS
+MAX_CONTEXT_CHARS = WARP_GREP_MAX_CONTEXT_CHARS
+MAX_OUTPUT_LINES = WARP_GREP_MAX_OUTPUT_LINES
+MAX_LIST_RESULTS = WARP_GREP_MAX_LIST_RESULTS
+MAX_READ_LINES = WARP_GREP_MAX_READ_LINES
+MAX_LIST_DEPTH = WARP_GREP_MAX_LIST_DEPTH
+
+# TS AGENT_CONFIG.TIMEOUT_MS default is 60_000 ms (overridable via env). We expose
+# it in **seconds** to match the rest of the Python SDK's timeout convention.
+_DEFAULT_TIMEOUT_S = 60.0
+
+
+def _resolve_timeout_s() -> float:
+    """Mirror TS ``parseEnvTimeout(MORPH_WARP_GREP_TIMEOUT, 60_000)`` (ms env -> s)."""
+    raw = os.environ.get("MORPH_WARP_GREP_TIMEOUT")
+    if not raw:
+        return _DEFAULT_TIMEOUT_S
+    try:
+        ms = int(raw)
+    except ValueError:
+        return _DEFAULT_TIMEOUT_S
+    return ms / 1000.0 if ms > 0 else _DEFAULT_TIMEOUT_S
+
+
+DEFAULT_TIMEOUT_S = _resolve_timeout_s()
+
+# Default code-search host for GitHub repo resolution + code-storage commands.
+DEFAULT_CODE_SEARCH_URL = "https://morphllm.com"

morphsdk/_agent/explore.py

@@ -0,0 +1,276 @@
+"""Explore subagent — async core.
+
+A higher-level codebase-exploration orchestration built directly on the WarpGrep
+agent. The WarpGrep agent runs on Morph's specialized ``morph-warp-grep-v2.1``
+model and already performs a multi-turn search loop (grep / read / list / glob /
+finish), so Explore drives *that* loop rather than a separate reasoning model:
+
+1. Explore runs the WarpGrep agent for the user's query against the chosen
+   provider, using the WarpGrep model.
+2. ``thoroughness`` scales how deep the WarpGrep loop is allowed to go by setting
+   its per-run turn cap (quick=3, medium=6, thorough=12).
+3. Each WarpGrep turn surfaces as an :class:`ExploreStepEvent` while streaming;
+   the resolved file contexts and the WarpGrep finish summary become the
+   :class:`ExploreRunResult`.
+
+Model note
+----------
+Explore intentionally uses the WarpGrep model end-to-end. The TS SDK runs the
+explore reasoning loop on a caller-supplied Anthropic/Vercel model and only calls
+WarpGrep for each search; the Python SDK has no such caller model, and the
+WarpGrep model is the right Morph-hosted engine for codebase search, so Explore
+delegates to the WarpGrep agent itself.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from morphsdk._providers.base import WarpGrepProvider
+
+from .runner import run_warp_grep_streaming
+from .types import AgentRunResult, WarpGrepStep
+
+# --- thoroughness ------------------------------------------------------------
+
+ExploreThoroughness = Literal["quick", "medium", "thorough"]
+
+#: Default thoroughness.
+DEFAULT_THOROUGHNESS: ExploreThoroughness = "medium"
+
+#: Per-run WarpGrep turn cap by thoroughness. Deeper thoroughness lets the
+#: WarpGrep loop take more search/read turns before it must finish.
+DEFAULT_MAX_TURNS: dict[ExploreThoroughness, int] = {
+    "quick": 3,
+    "medium": 6,
+    "thorough": 12,
+}
+
+#: Tool calls that count as a "search" for :attr:`ExploreRunResult.search_count`.
+_SEARCH_TOOLS = frozenset(("grep_search", "glob", "list_directory"))
+
+
+# --- result / event shapes (mirror subagents/types.ts) -----------------------
+
+
+@dataclass
+class ExploreContext:
+    """A resolved code context: file path, content, optional line ranges.
+
+    Mirrors ``WarpGrepContext`` so Explore inherits the exact context shape the
+    TS ``ExploreResult.contexts`` carries.
+    """
+
+    file: str
+    content: str
+    lines: Any | None = None
+
+
+@dataclass
+class ExploreRunResult:
+    """Port of TS ``ExploreResult``."""
+
+    success: bool
+    summary: str
+    contexts: list[ExploreContext]
+    search_count: int
+    duration_ms: float
+    error: str | None = None
+
+
+@dataclass
+class ExploreStepEvent:
+    """Port of TS ``ExploreStep`` / the ``step`` streaming event."""
+
+    step: int
+    search_request: str
+    contexts_found: int
+    is_final: bool
+
+
+@dataclass
+class ExploreMessageEvent:
+    """Port of the TS ``message`` streaming event.
+
+    Retained for API/type compatibility. Explore-on-WarpGrep has no host
+    round-trips, so the core never emits these; consumers may still type against
+    them.
+    """
+
+    sender: Literal["explore", "host"]
+    content: str
+    timestamp: float
+
+
+def _max_turns(thoroughness: ExploreThoroughness, max_turns: int | None) -> int:
+    return max_turns if max_turns is not None else DEFAULT_MAX_TURNS.get(thoroughness, 6)
+
+
+def _deduplicate_contexts(contexts: list[ExploreContext]) -> list[ExploreContext]:
+    """Port of ``deduplicateContexts``: keep, per file, the longest-content version."""
+    by_file: dict[str, ExploreContext] = {}
+    for ctx in contexts:
+        existing = by_file.get(ctx.file)
+        if existing is None or len(ctx.content) > len(existing.content):
+            by_file[ctx.file] = ctx
+    return list(by_file.values())
+
+
+def _step_label(step: WarpGrepStep) -> str:
+    """A concise human label for a WarpGrep turn, derived from its tool calls,
+    used as :attr:`ExploreStepEvent.search_request`."""
+    labels: list[str] = []
+    for call in step.tool_calls:
+        name = str(call.get("name") or "")
+        args = call.get("arguments") or {}
+        detail = ""
+        if isinstance(args, dict):
+            detail = str(
+                args.get("pattern")
+                or args.get("query")
+                or args.get("path")
+                or args.get("glob")
+                or ""
+            )
+        labels.append(f"{name}: {detail}".strip().rstrip(":").strip() if detail else name)
+    return "; ".join(label for label in labels if label)
+
+
+def _count_searches(step: WarpGrepStep) -> int:
+    return sum(1 for call in step.tool_calls if str(call.get("name") or "") in _SEARCH_TOOLS)
+
+
+def _contexts_from_result(result: AgentRunResult) -> list[ExploreContext]:
+    if result.termination_reason != "completed" or not result.resolved:
+        return []
+    return [
+        ExploreContext(file=r.path, content=r.content, lines=r.ranges)
+        for r in result.resolved
+    ]
+
+
+@dataclass
+class _LoopState:
+    search_count: int = 0
+    last_turn: int = 0
+    steps: list[WarpGrepStep] = field(default_factory=list)
+
+
+async def run_explore_streaming(
+    *,
+    query: str,
+    repo_root: str,
+    provider: WarpGrepProvider,
+    api_key: str,
+    api_url: str | None = None,
+    thoroughness: ExploreThoroughness = DEFAULT_THOROUGHNESS,
+    max_turns: int | None = None,
+    timeout: float | None = None,
+    max_retries: int = 3,
+) -> AsyncIterator[ExploreStepEvent | ExploreMessageEvent | ExploreRunResult]:
+    """Drive the WarpGrep agent for ``query`` and stream exploration events.
+
+    Yields an :class:`ExploreStepEvent` per WarpGrep turn, a final ``is_final``
+    step, then a single :class:`ExploreRunResult` (the last item). Python
+    generators cannot carry a separate return value, so the terminal result is
+    yielded last; consumers distinguish by type.
+    """
+    start = time.monotonic()
+    state = _LoopState()
+    cap = _max_turns(thoroughness, max_turns)
+
+    try:
+        async for item in run_warp_grep_streaming(
+            search_term=query,
+            repo_root=repo_root,
+            provider=provider,
+            api_key=api_key,
+            api_url=api_url,
+            timeout=timeout,
+            max_turns=cap,
+            max_retries=max_retries,
+        ):
+            if isinstance(item, WarpGrepStep):
+                state.search_count += _count_searches(item)
+                state.last_turn = item.turn
+                state.steps.append(item)
+                yield ExploreStepEvent(
+                    step=item.turn,
+                    search_request=_step_label(item),
+                    contexts_found=0,
+                    is_final=False,
+                )
+                continue
+
+            # Terminal AgentRunResult.
+            contexts = _deduplicate_contexts(_contexts_from_result(item))
+            yield ExploreStepEvent(
+                step=state.last_turn,
+                search_request="",
+                contexts_found=len(contexts),
+                is_final=True,
+            )
+            if item.termination_reason == "completed":
+                summary = item.finish_payload or "Exploration completed."
+                yield ExploreRunResult(
+                    success=True,
+                    summary=summary,
+                    contexts=contexts,
+                    search_count=state.search_count,
+                    duration_ms=(time.monotonic() - start) * 1000,
+                )
+            else:
+                error = item.errors[0]["message"] if item.errors else None
+                yield ExploreRunResult(
+                    success=False,
+                    summary=item.finish_payload or "",
+                    contexts=contexts,
+                    search_count=state.search_count,
+                    duration_ms=(time.monotonic() - start) * 1000,
+                    error=error,
+                )
+            return
+    except Exception as err:  # noqa: BLE001 - surface as an error result, like TS
+        yield ExploreRunResult(
+            success=False,
+            summary="",
+            contexts=[],
+            search_count=state.search_count,
+            duration_ms=(time.monotonic() - start) * 1000,
+            error=str(err),
+        )
+
+
+async def run_explore(
+    *,
+    query: str,
+    repo_root: str,
+    provider: WarpGrepProvider,
+    api_key: str,
+    api_url: str | None = None,
+    thoroughness: ExploreThoroughness = DEFAULT_THOROUGHNESS,
+    max_turns: int | None = None,
+    timeout: float | None = None,
+    max_retries: int = 3,
+) -> ExploreRunResult:
+    """Non-streaming convenience wrapper: drain the streaming loop and return the
+    terminal :class:`ExploreRunResult`."""
+    result: ExploreRunResult | None = None
+    async for item in run_explore_streaming(
+        query=query,
+        repo_root=repo_root,
+        provider=provider,
+        api_key=api_key,
+        api_url=api_url,
+        thoroughness=thoroughness,
+        max_turns=max_turns,
+        timeout=timeout,
+        max_retries=max_retries,
+    ):
+        if isinstance(item, ExploreRunResult):
+            result = item
+    assert result is not None  # the loop always yields a terminal result
+    return result

morphsdk/_agent/github.py

@@ -0,0 +1,57 @@
+"""GitHub repo resolution for WarpGrep code search.
+
+Faithful port of ``parseGitHubUrl`` (``utils/github.ts``) and
+``_resolveGitHubRepo`` (``client.ts``): parse an ``owner/repo`` shorthand or URL,
+then hit ``GET {base}/api/code-search/get-or-create?url=owner/repo`` to obtain the
+indexed ``repoId`` + ``defaultBranch`` used to build the code-storage commands.
+"""
+
+from __future__ import annotations
+
+import re
+
+import httpx
+
+_URL_PATTERN = re.compile(r"^(?:https?://)?github\.com/([^/]+)/([^/?#]+)")
+_SHORT_PATTERN = re.compile(r"^([^/]+)/([^/]+)$")
+
+
+def parse_github_url(value: str) -> tuple[str, str]:
+    """Parse ``owner/repo``, ``github.com/owner/repo``, or a full URL.
+
+    Returns ``(owner, repo)`` with any trailing ``.git`` stripped.  Rejects an
+    ``owner`` containing ``.`` in the shorthand form (mirrors the TS guard).
+    """
+    value = value.strip()
+    match = _URL_PATTERN.match(value)
+    if match:
+        return match.group(1), re.sub(r"\.git$", "", match.group(2))
+    short = _SHORT_PATTERN.match(value)
+    if short and "." not in short.group(1):
+        return short.group(1), re.sub(r"\.git$", "", short.group(2))
+    raise ValueError(
+        f'Invalid GitHub URL or shorthand: "{value}". '
+        'Expected "owner/repo" or "https://github.com/owner/repo"'
+    )
+
+
+async def resolve_github_repo(
+    github: str,
+    base_url: str,
+    *,
+    timeout: float | None = None,
+) -> tuple[str, str, str]:
+    """Resolve a GitHub reference to ``(repo, repo_id, default_branch)``.
+
+    Calls ``get-or-create`` to import/locate the indexed repo, exactly like the
+    TS ``_resolveGitHubRepo``.
+    """
+    owner, repo = parse_github_url(github)
+    url = f"{base_url}/api/code-search/get-or-create"
+    async with httpx.AsyncClient(timeout=httpx.Timeout(timeout or 30.0)) as client:
+        res = await client.get(url, params={"url": f"{owner}/{repo}"})
+        if not res.is_success:
+            text = res.text or res.reason_phrase
+            raise RuntimeError(f"Failed to import repo {owner}/{repo}: {text}")
+        data = res.json()
+    return repo, str(data["repoId"]), str(data["defaultBranch"])

morphsdk/_agent/helpers.py

@@ -0,0 +1,133 @@
+"""Conversation-assembly helpers for the WarpGrep agent loop.
+
+Faithful port of ``agent/helpers.ts``: the initial-state prompt, the turn-counter
+hint, the context-budget tag, and the hard context-limit enforcement.  The exact
+string formats matter -- they match the model's training distribution.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+
+from morphsdk._providers.base import WarpGrepProvider
+
+from .config import MAX_CONTEXT_CHARS, MAX_OUTPUT_LINES, MAX_TURNS
+from .types import ChatMessage
+
+_TRUNCATED_MARKER = "[truncated for context limit]"
+
+
+def _message_size(m: ChatMessage) -> int:
+    """Character size of a message (mirrors ``getMessageSize``)."""
+    if m.role == "tool":
+        return len(m.content or "")
+    if m.role == "assistant":
+        size = len(m.content) if isinstance(m.content, str) else 0
+        if m.tool_calls:
+            size += sum(len(tc.name) + len(tc.arguments) for tc in m.tool_calls)
+        return size
+    return len(m.content or "")
+
+
+def format_turn_message(turns_used: int, max_turns: int) -> str:
+    """Format the turn-counter hint appended after each tool round."""
+    turns_remaining = max_turns - turns_used
+    if turns_remaining == 1:
+        return (
+            f"\nYou have used {turns_used} turns, you only have 1 turn remaining. "
+            "You have run out of turns to explore the code base and MUST call the "
+            "finish tool now"
+        )
+    plural = "" if turns_used == 1 else "s"
+    return f"\nYou have used {turns_used} turn{plural} and have {turns_remaining} remaining"
+
+
+def calculate_context_budget(messages: list[ChatMessage]) -> str:
+    """Format the ``<context_budget>`` indicator (mirrors ``calculateContextBudget``)."""
+    total_chars = sum(_message_size(m) for m in messages)
+    max_chars = MAX_CONTEXT_CHARS
+    percent = math.floor((total_chars / max_chars) * 100)
+    used_k = math.floor(total_chars / 1000)
+    max_k = math.floor(max_chars / 1000)
+    return f"<context_budget>{percent}% ({used_k}K/{max_k}K chars)</context_budget>"
+
+
+async def build_initial_state(
+    repo_root: str,
+    search_term: str,
+    provider: WarpGrepProvider,
+    *,
+    search_type: str | None = None,
+) -> str:
+    """Build the first user message: repo structure + search string + budget/turn.
+
+    Faithful port of ``buildInitialState`` -- a flat list of absolute paths
+    (repo root first), matching the training format, then the search string and
+    the budget/turn tags.  Falls back to a root-only structure on listing errors.
+    """
+    budget = calculate_context_budget([])
+    turn_tag = f"You have used 0 turns and have {MAX_TURNS} remaining"
+    tree_depth = 1 if search_type == "node_modules" else 2
+    abs_root = repo_root
+
+    try:
+        entries = await provider.list_directory(
+            path=".",
+            max_results=MAX_OUTPUT_LINES,
+            max_depth=tree_depth,
+        )
+        lines = [abs_root]
+        for e in entries:
+            lines.append(os.path.join(abs_root, e.path))
+        structure = "\n".join(lines)
+    except Exception:  # noqa: BLE001 - mirror TS catch -> root-only fallback
+        structure = abs_root
+
+    return (
+        f"<repo_structure>\n{structure}\n</repo_structure>\n\n"
+        f"<search_string>\n{search_term}\n</search_string>\n{budget}\n{turn_tag}"
+    )
+
+
+def enforce_context_limit(
+    messages: list[ChatMessage],
+    max_chars: int = MAX_CONTEXT_CHARS,
+) -> list[ChatMessage]:
+    """Truncate tool/non-first-user messages in place until under *max_chars*.
+
+    Faithful port of ``enforceContextLimit``: the first user message (the search
+    query) and all assistant messages are preserved; tool results and later user
+    messages are replaced with a marker from oldest to newest until the total is
+    within budget.
+    """
+
+    def total() -> int:
+        return sum(_message_size(m) for m in messages)
+
+    if total() <= max_chars:
+        return messages
+
+    truncatable: list[int] = []
+    first_user_skipped = False
+    for i, m in enumerate(messages):
+        if m.role == "tool":
+            truncatable.append(i)
+        elif m.role == "user":
+            if not first_user_skipped:
+                first_user_skipped = True
+                continue
+            truncatable.append(i)
+
+    for idx in truncatable:
+        if total() <= max_chars:
+            break
+        m = messages[idx]
+        if m.role == "tool" and m.content != _TRUNCATED_MARKER:
+            messages[idx] = ChatMessage(
+                role="tool", content=_TRUNCATED_MARKER, tool_call_id=m.tool_call_id
+            )
+        elif m.role == "user" and m.content != _TRUNCATED_MARKER:
+            messages[idx] = ChatMessage(role="user", content=_TRUNCATED_MARKER)
+
+    return messages