morphsdk 0.2.5__py3-none-any.whl

morphsdk/adapters/openai.py

@@ -0,0 +1,500 @@
+"""OpenAI framework adapter -- generates ChatCompletionTool-compatible dicts.
+
+Each tool definition follows the OpenAI function-calling schema::
+
+    {
+        "type": "function",
+        "function": {
+            "name": "...",
+            "description": "...",
+            "parameters": { JSON Schema }
+        }
+    }
+
+The :class:`OpenAITool` wrapper pairs the definition with an ``execute()``
+method so callers can dispatch tool calls in a single object.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import ItemsView, Iterator, KeysView, ValuesView
+from typing import Any, Callable
+
+# ---------------------------------------------------------------------------
+# Tool descriptions -- mirrored from the TypeScript SDK
+# ---------------------------------------------------------------------------
+
+EDIT_FILE_DESCRIPTION = (
+    "Use this tool to make an edit to an existing file.\n\n"
+    "This will be read by a less intelligent model, which will quickly apply the edit. "
+    "You should make it clear what the edit is, while also minimizing the unchanged "
+    "code you write.\n\n"
+    "When writing the edit, you should specify each edit in sequence, with the special comment "
+    "// ... existing code ... to represent unchanged code in between edited lines.\n\n"
+    "For example:\n\n"
+    "// ... existing code ...\nFIRST_EDIT\n// ... existing code ...\nSECOND_EDIT\n"
+    "// ... existing code ...\nTHIRD_EDIT\n// ... existing code ...\n\n"
+    "You should still bias towards repeating as few lines of the original file as "
+    "possible to convey the change.\n"
+    "But, each edit should contain minimally sufficient context of unchanged lines around the code "
+    "you're editing to resolve ambiguity.\n\n"
+    "DO NOT omit spans of pre-existing code (or comments) without using the "
+    "// ... existing code ... "
+    "comment to indicate its absence. If you omit the existing code comment, the "
+    "model may inadvertently "
+    "delete these lines.\n\n"
+    "If you plan on deleting a section, you must provide context before and after to delete it.\n\n"
+    "Make sure it is clear what the edit should be, and where it should be applied.\n"
+    "Make edits to a file in a single edit_file call instead of multiple edit_file "
+    "calls to the same file. "
+    "The apply model can handle many distinct edits at once."
+)
+
+EDIT_FILE_SYSTEM_PROMPT = (
+    "When the user is asking for edits to their code, use the edit_file tool to "
+    "highlight the changes "
+    "necessary and add comments to indicate where unchanged code has been skipped. For example:\n\n"
+    "// ... existing code ...\n{{ edit_1 }}\n// ... existing code ...\n{{ edit_2 }}\n"
+    "// ... existing code ...\n\n"
+    "Often this will mean that the start/end of the file will be skipped, but that's okay! "
+    "Rewrite the entire file ONLY if specifically requested. Always provide a brief explanation of "
+    "the updates, unless the user specifically requests only the code.\n\n"
+    "These edit codeblocks are also read by a less intelligent language model, colloquially called "
+    "the apply model, to update the file. To help specify the edit to the apply model, you will be "
+    "very careful when generating the codeblock to not introduce ambiguity. You will specify all "
+    "unchanged regions (code and comments) of the file with \"// ... existing code ...\" comment "
+    "markers. This will ensure the apply model will not delete existing unchanged code or comments "
+    "when editing the file."
+)
+
+CODEBASE_SEARCH_DESCRIPTION = (
+    "Semantic search that finds code by meaning, not exact text.\n\n"
+    "Use this to explore unfamiliar codebases or ask \"how/where/what\" questions:\n"
+    "- \"How does X work?\" - Find implementation details\n"
+    "- \"Where is Y handled?\" - Locate specific functionality\n"
+    "- \"What happens when Z?\" - Understand flow\n\n"
+    "The tool uses two-stage retrieval (embedding similarity + reranking) to find the most "
+    "semantically relevant code chunks.\n\n"
+    "Returns code chunks with file paths, line ranges, and full content ranked by relevance."
+)
+
+WARP_GREP_DESCRIPTION = (
+    "Very fast code search exploration subagent (not a grep tool) that runs parallel grep "
+    "and file read calls over multiple turns to locate relevant files and line ranges. "
+    "The search term should be a targeted natural-language query describing what you are "
+    "trying to find or accomplish, e.g. "
+    "\"Find where authentication requests are handled in the Express routes\" or "
+    "\"How do callers of processOrder handle the error case?\". "
+    "Fill in extra context you can infer to make the query specific. "
+    "Do not pass bare keywords or symbol names -- use grep directly for exact symbol lookups. "
+    "Use this tool first when exploring unfamiliar code. The results may be partial -- "
+    "follow up with classical search tools or direct file reads if needed. "
+    "When a task requires exploration beyond a single known file, ALWAYS default to "
+    "warpgrep codebase search before other search mechanisms."
+)
+
+GITHUB_SEARCH_DESCRIPTION = (
+    "Always use this when debugging errors in third-party dependencies to check for "
+    "upstream fixes, open issues, or newer code paths. "
+    "Code search exploration subagent for public GitHub repositories (not your local "
+    "workspace -- use codebase_search for that). "
+    "Runs parallel grep and file read calls to locate relevant files and line ranges "
+    "in external github repositories without cloning the repository. "
+    "Pass a targeted natural-language query, not bare keywords. Useful for understanding "
+    "how a library works or investigating upstream bugs. "
+    "You must provide either github_url or owner_repo (at least one required)."
+)
+
+GITHUB_READ_FILE_DESCRIPTION = (
+    "Read a single file (or a line range) from a public GitHub repository. "
+    "ONLY USE THIS WHEN YOU ALREADY KNOW THE EXACT FILE PATH YOU WANT TO READ, "
+    "for example after finding it via github_codebase_search results. "
+    "Takes owner/repo shorthand and the file path within the repo. "
+    "Optionally specify startLine and endLine (1-based) to read a specific range. "
+    "Returns the file content with line numbers."
+)
+
+BROWSER_TOOL_DESCRIPTION = (
+    "Test and verify your implemented code in a live browser. This tool executes "
+    "natural language test instructions and returns a video recording plus detailed "
+    "logs to help you debug issues.\n\n"
+    "## When to Use\n"
+    "Use this AFTER coding is complete to verify your implementation:\n"
+    "- You've finished writing/modifying code and need to verify it works\n"
+    "- You need to test user interactions end-to-end (clicks, forms, navigation)\n"
+    "- You want to catch runtime errors, console warnings, or network failures\n"
+    "- You need visual confirmation that UI elements render and behave correctly\n\n"
+    "## Requirements\n"
+    "- URL: Must be publicly accessible (use tunnels like ngrok, Cloudflare, or "
+    "deploy to staging)\n"
+    "- Timing: Use this after implementation, not during coding\n"
+    "- Complexity: Set maxSteps higher (20-30) for multi-step user workflows"
+)
+
+MOBILE_TOOL_DESCRIPTION = (
+    "Execute mobile app automation tasks using natural language.\n\n"
+    "This tool automates iOS and Android mobile apps on real BrowserStack cloud devices. "
+    "It interprets your instructions and interacts with the app's UI to perform tasks."
+)
+
+
+# ---------------------------------------------------------------------------
+# Tool definition factories
+# ---------------------------------------------------------------------------
+
+def edit_file_tool_def(*, description: str | None = None) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for ``edit_file``."""
+    return {
+        "type": "function",
+        "function": {
+            "name": "edit_file",
+            "description": description or EDIT_FILE_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target_filepath": {
+                        "type": "string",
+                        "description": "The path of the target file to modify",
+                    },
+                    "instruction": {
+                        "type": "string",
+                        "description": (
+                            "A single sentence written in the first person describing "
+                            "what the agent is changing. Used to help disambiguate "
+                            "uncertainty in the edit."
+                        ),
+                    },
+                    "code_edit": {
+                        "type": "string",
+                        "description": (
+                            "Specify ONLY the precise lines of code that you wish to "
+                            "edit. Use `// ... existing code ...` for unchanged sections."
+                        ),
+                    },
+                },
+                "required": ["target_filepath", "instruction", "code_edit"],
+            },
+        },
+    }
+
+
+def codebase_search_tool_def(*, description: str | None = None) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for ``codebase_search``."""
+    return {
+        "type": "function",
+        "function": {
+            "name": "codebase_search",
+            "description": description or CODEBASE_SEARCH_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": (
+                            "A complete question or description about what you want to "
+                            "understand. Ask as if talking to a colleague: \"How does X "
+                            "work?\", \"What happens when Y?\", \"Where is Z handled?\""
+                        ),
+                    },
+                    "target_directories": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "Prefix directory paths to limit search scope "
+                            "(single directory only, no glob patterns). "
+                            "Use [] to search entire repo."
+                        ),
+                    },
+                    "explanation": {
+                        "type": "string",
+                        "description": (
+                            "One sentence explanation as to why this tool is being used, "
+                            "and how it contributes to the goal."
+                        ),
+                    },
+                    "limit": {
+                        "type": "number",
+                        "description": "Maximum results to return (default: 10)",
+                    },
+                },
+                "required": ["query", "target_directories", "explanation"],
+            },
+        },
+    }
+
+
+def grep_tool_def(
+    *,
+    name: str = "codebase_search",
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for the WarpGrep agent."""
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description or WARP_GREP_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "search_term": {
+                        "type": "string",
+                        "description": (
+                            "Search problem statement that this subagent is "
+                            "supposed to research for"
+                        ),
+                    },
+                },
+                "required": ["search_term"],
+            },
+        },
+    }
+
+
+def github_search_tool_def(*, description: str | None = None) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for ``github_codebase_search``."""
+    return {
+        "type": "function",
+        "function": {
+            "name": "github_codebase_search",
+            "description": description or GITHUB_SEARCH_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "search_term": {
+                        "type": "string",
+                        "description": (
+                            "A targeted natural-language query describing what to find "
+                            "(e.g. \"How does auth work for SSO users?\"). "
+                            "Not a keyword or symbol name."
+                        ),
+                    },
+                    "github_url": {
+                        "type": "string",
+                        "description": (
+                            "GitHub repository URL to search "
+                            "(e.g. \"https://github.com/vercel/next.js\"). "
+                            "You must provide either github_url or owner_repo."
+                        ),
+                    },
+                    "owner_repo": {
+                        "type": "string",
+                        "description": (
+                            "Repository owner/repo shorthand (e.g. \"vercel/next.js\"). "
+                            "You must provide either github_url or owner_repo."
+                        ),
+                    },
+                    "branch": {
+                        "type": "string",
+                        "description": (
+                            "Branch to search (defaults to the repository default branch)"
+                        ),
+                    },
+                },
+                "required": ["search_term"],
+            },
+        },
+    }
+
+
+def github_read_file_tool_def(*, description: str | None = None) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for ``readfile_github_search``."""
+    return {
+        "type": "function",
+        "function": {
+            "name": "readfile_github_search",
+            "description": description or GITHUB_READ_FILE_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "github": {
+                        "type": "string",
+                        "description": "owner/repo shorthand (e.g., \"vercel/next.js\")",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": (
+                            "File path within the repository (e.g., \"src/server/index.ts\")"
+                        ),
+                    },
+                    "startLine": {
+                        "type": "number",
+                        "description": "Start line number (1-based). Omit to start from beginning.",
+                    },
+                    "endLine": {
+                        "type": "number",
+                        "description": (
+                            "End line number (1-based, inclusive). Omit to read to the end."
+                        ),
+                    },
+                    "branch": {
+                        "type": "string",
+                        "description": (
+                            "Branch to read from (defaults to the repository default branch)"
+                        ),
+                    },
+                },
+                "required": ["github", "path"],
+            },
+        },
+    }
+
+
+def browser_tool_def(*, description: str | None = None) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for ``browser_task``."""
+    return {
+        "type": "function",
+        "function": {
+            "name": "browser_task",
+            "description": description or BROWSER_TOOL_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task": {
+                        "type": "string",
+                        "description": (
+                            "Natural language description of what to do "
+                            "(e.g., \"Test checkout flow for buying a pineapple\")"
+                        ),
+                    },
+                    "url": {
+                        "type": "string",
+                        "description": (
+                            "Starting URL (e.g., https://3000-xyz.e2b.dev). "
+                            "Required if navigating to a specific page."
+                        ),
+                    },
+                    "maxSteps": {
+                        "type": "number",
+                        "description": (
+                            "Maximum number of browser actions to take (1-50). "
+                            "Default: 10. Use 15-30 for complex flows."
+                        ),
+                    },
+                    "region": {
+                        "type": "string",
+                        "enum": ["sfo", "lon"],
+                        "description": (
+                            "Browserless region: sfo (US West Coast) or lon (Europe). Default: sfo."
+                        ),
+                    },
+                },
+                "required": ["task"],
+            },
+        },
+    }
+
+
+def mobile_tool_def(*, description: str | None = None) -> dict[str, Any]:
+    """Generate an OpenAI ChatCompletionTool dict for ``mobile_task``."""
+    return {
+        "type": "function",
+        "function": {
+            "name": "mobile_task",
+            "description": description or MOBILE_TOOL_DESCRIPTION,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task": {
+                        "type": "string",
+                        "description": (
+                            "Natural language description of what to do in the mobile app"
+                        ),
+                    },
+                    "app": {
+                        "type": "string",
+                        "description": (
+                            "Application identifier (bundle ID or BrowserStack bs:// URL)"
+                        ),
+                    },
+                    "platform": {
+                        "type": "string",
+                        "enum": ["ios", "android"],
+                        "description": "Target platform (default: ios)",
+                    },
+                    "max_steps": {
+                        "type": "number",
+                        "description": "Maximum agent steps (default: 50)",
+                    },
+                },
+                "required": ["task", "app"],
+            },
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# OpenAITool -- pairs a definition with an executor
+# ---------------------------------------------------------------------------
+
+class OpenAITool:
+    """A tool definition paired with an executor for OpenAI chat completions.
+
+    Behaves like a dict (can be passed directly to ``tools=[tool]``) while
+    also exposing ``execute()`` and ``format_result()`` methods.
+
+    Example::
+
+        tool = morph.edit.as_openai_tool(base_dir="./src")
+
+        # Pass to OpenAI
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            tools=[tool],  # works because OpenAITool acts as a dict
+            messages=[...],
+        )
+
+        # Execute
+        result = tool.execute(tool_call.function.arguments)
+        formatted = tool.format_result(result)
+    """
+
+    def __init__(
+        self,
+        definition: dict[str, Any],
+        executor: Callable[..., Any],
+        formatter: Callable[..., str],
+        system_prompt: str = "",
+    ) -> None:
+        self._definition = definition
+        self._executor = executor
+        self._formatter = formatter
+        self.system_prompt = system_prompt
+
+    # -- dict protocol so OpenAI SDK accepts this as a tool ---
+    def __getitem__(self, key: str) -> Any:
+        return self._definition[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._definition
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._definition)
+
+    def keys(self) -> KeysView[str]:
+        return self._definition.keys()
+
+    def items(self) -> ItemsView[str, Any]:
+        return self._definition.items()
+
+    def values(self) -> ValuesView[Any]:
+        return self._definition.values()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the raw tool definition dict."""
+        return self._definition
+
+    # -- execution ---
+    def execute(self, input: dict[str, Any] | str) -> Any:
+        """Execute the tool with the given input.
+
+        *input* may be a dict or a JSON string (as returned by
+        ``tool_call.function.arguments``).
+        """
+        args: dict[str, Any] = json.loads(input) if isinstance(input, str) else input
+        return self._executor(**args)
+
+    def format_result(self, result: Any) -> str:
+        """Format a result for passing back as a tool message."""
+        return self._formatter(result)