modis-py-tools 0.1.0__py3-none-any.whl

modis_py_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: modis-py-tools
+Version: 0.1.0
+Summary: Common MoDIS-compatible Python tools and tool-call execution helpers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: web
+Requires-Dist: valyu>=2.0.0; extra == "web"
+Provides-Extra: browser
+Requires-Dist: markdownify>=0.12.0; extra == "browser"
+Requires-Dist: playwright>=1.45.0; extra == "browser"
+Requires-Dist: readability-lxml>=0.8.1; extra == "browser"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+
+# MoDIS Python Tools
+
+`modis-py-tools` provides MoDIS-compatible function tool definitions, tool
+groups, and tool-call execution helpers for Python applications.
+
+The distribution name is currently `modis-py-tools`; the import package is
+`modis_tools`.
+
+## Install
+
+```bash
+python -m pip install modis-py-tools
+```
+
+Optional web provider dependency:
+
+```bash
+python -m pip install "modis-py-tools[web]"
+```
+
+Development:
+
+```bash
+python -m pip install -e ".[dev,web]"
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+.venv/bin/python -m ruff format --check .
+.venv/bin/python -m mypy src
+.venv/bin/python -m build
+```
+
+## Function Conversion
+
+```python
+from modis_tools import function_to_tool
+
+def lookup_order(order_id: str, include_history: bool = False) -> dict:
+    """Look up an order.
+
+    Args:
+        order_id: Order identifier.
+        include_history: Whether to include status history.
+    """
+    return {"order_id": order_id, "status": "processing"}
+
+tool = function_to_tool(lookup_order, name="orders.lookup")
+tool_definition = tool.to_wire()
+```
+
+## Registry Execution
+
+```python
+from modis_tools import ToolRegistry
+from modis_tools.builtins import python_group, shell_group
+
+registry = ToolRegistry()
+registry.include(shell_group())
+registry.include(python_group())
+
+tool_definitions = registry.definitions()
+results = registry.execute_tool_calls(model_tool_calls)
+messages = [result.to_chat_message() for result in results]
+```
+
+`execute_tool_call()` and `execute_tool_calls()` return failed `ToolResult`
+objects by default for unknown tools, invalid arguments, and tool exceptions.
+Pass `raise_on_error=True` when the host application should handle exceptions.
+
+For a fuller host integration guide, including unattended pipeline setup and
+future image generation extension notes, see `docs/INTEGRATION.md`.
+
+## Built-In Tools
+
+```python
+from modis_tools.builtins import python_group, shell_group, skills_group, web_group
+
+shell_tools = shell_group()
+python_tools = python_group()
+skill_tools = skills_group(skill_home="./skills")
+web_tools = web_group(api_key="...")
+```
+
+`shell.run` captures `stdout`, `stderr`, exit code, duration, timeout state,
+working directory, policy decision metadata, and truncation metadata.
+`python.run` executes Python source in a subprocess using the current
+interpreter by default.
+
+Shell and Python tools execute local code. Only expose them in trusted contexts
+where the caller owns policy, sandboxing, and approval decisions.
+
+Shell tools support host-owned policies. Policies are bound by the application
+when registering the group and are not exposed as model tool-call parameters.
+
+```python
+from modis_tools import ToolRegistry
+from modis_tools.builtins import ShellPolicy, shell_group
+
+registry = ToolRegistry()
+registry.include(shell_group(policy=ShellPolicy.readonly_project("./")))
+```
+
+Built-in shell policy profiles:
+
+| Profile | Purpose |
+| --- | --- |
+| `trusted_local` | Backward-compatible default for trusted local use. |
+| `disabled` | Denies every shell request. |
+| `restricted` | Deterministic allowlist for unattended pipelines. |
+| `readonly_project` | Read-oriented `argv` commands inside one project root. |
+
+`shell.run` accepts exactly one of `cmd` or `argv`. `cmd` executes with
+`shell=True`; `argv` executes with `shell=False`. Restricted policies should
+prefer `argv` mode. Policy controls are guardrails, not a strong OS sandbox; use
+containers, VMs, or other isolation for untrusted execution.
+
+## Skill Tools
+
+Skill support is split into runtime visibility, optional host-owned matching, and
+tool-based skill use. `modis-tools` provides the use layer: a registry, a prompt
+generator, and `skills.*` tools for progressive loading.
+
+`skill_home` is required in every mode because all skill files must resolve from
+a trusted root.
+
+```python
+from modis_tools import ToolRegistry
+from modis_tools.builtins import skills_group
+from modis_tools.skills import SkillRegistry, build_skill_system_prompt
+
+skill_home = "./skills"
+registry = ToolRegistry()
+registry.include(skills_group(skill_home=skill_home, mode="hybrid"))
+
+skill_registry = SkillRegistry.from_home(skill_home)
+system_prompt = build_skill_system_prompt(skill_registry, mode="hybrid")
+```
+
+The skills group exposes:
+
+- `skills.list()`
+- `skills.read(name)`
+- `skills.list_resources(name)`
+- `skills.read_resource(name, path)`
+- `skills.system_prompt(active_skill=None)`
+
+Execution modes:
+
+| Mode | Behavior |
+| --- | --- |
+| `tools_only` | Models use only `skills.*` tools to read instructions and resources. |
+| `shell_only` | Prompt tells the model where `skill_home` is; host shell/file policy must handle access. |
+| `hybrid` | Models use `skills.*` for reads and policy-gated shell for commands only when needed. |
+
+Skill matching is intentionally optional and host-owned. The package defines
+`PromptSkillEvaluator` as a protocol, but does not decide when a skill should be
+used.
+
+## Web Tools
+
+The web group exposes:
+
+- `web.search(query, num_results=10, search_type="all", relevance_threshold=0.5, included_sources=None, excluded_sources=None, country_code=None, response_length=None, category=None, start_date=None, end_date=None, max_price=None, fast_mode=False, url_only=False, source_biases=None, instructions=None)`
+- `web.open(id=None, cursor=-1, loc=-1, num_lines=-1)`
+- `web.find(pattern, cursor=-1, context_lines=3)`
+
+Valyu is the default provider when no provider is supplied. Search uses Valyu
+search, and direct URL opens use Valyu contents extraction.
+Opened pages and find results include source ids, URLs, and one-based line
+ranges so responses can be cited or re-opened later in the same tool session.
+
+```python
+from modis_tools import ToolRegistry
+from modis_tools.builtins import web_group
+
+registry = ToolRegistry()
+registry.include(web_group(api_key="..."))
+```
+
+Search options map to Valyu search controls. For example:
+
+```python
+result = registry.execute_tool_call({
+    "id": "search_1",
+    "type": "function",
+    "function": {
+        "name": "web.search",
+        "arguments": """
+        {
+          "query": "recent multimodal retrieval papers",
+          "num_results": 5,
+          "relevance_threshold": 0.45,
+          "included_sources": ["valyu/valyu-arxiv"],
+          "response_length": "medium",
+          "start_date": "2026-04-29",
+          "end_date": "2026-05-06",
+          "country_code": "US"
+        }
+        """
+    }
+})
+```
+
+Default search values are copied from the installed Valyu SDK where exposed:
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `num_results` | `10` | Sent to Valyu as `max_num_results`. |
+| `search_type` | `"all"` | Valyu scopes are `web`, `proprietary`, `all`, and `news`. |
+| `relevance_threshold` | `0.5` | Set to `None` to omit the threshold parameter. |
+| `included_sources` | `None` | Valyu source ids or arbitrary URLs. |
+| `excluded_sources` | `None` | Valyu source ids or arbitrary URLs. |
+| `country_code` | `None` | Optional ISO country code. |
+| `response_length` | `None` | Supports `short`, `medium`, `large`, `max`, integer, or numeric string. |
+| `category` | `None` | Provider-specific category. |
+| `start_date` / `end_date` | `None` | Optional `YYYY-MM-DD` bounds. |
+| `max_price` | `None` | Provider cost limit if used. |
+| `fast_mode` | `False` | Sent explicitly. |
+| `url_only` | `False` | Sent explicitly. |
+| `source_biases` | `None` | Optional per-source integer biases. |
+| `instructions` | `None` | Optional provider instructions. |
+
+`is_tool_call` is not exposed to the model; the Valyu provider sends it as
+`True`.
+
+Valyu provider metadata that is not part of the normalized result shape, such as
+scores or ranking fields when returned by the SDK, is preserved in each result's
+`metadata` object.
+
+Custom providers implement `SearchProvider`:
+
+```python
+from modis_tools.providers.web import Page, SearchResult
+
+class MyProvider:
+    def search(self, query: str, *, num_results: int = 10, **kwargs: object) -> list[SearchResult]:
+        return [SearchResult(title="Example", url="https://example.test", content="Page text")]
+
+    def fetch(self, url: str) -> Page:
+        return Page(title="Fetched", url=url, markdown="Fetched markdown")
+```
+
+`web.open` can open prior search results by index/result id/URL, or an arbitrary
+direct URL. Browser-backed fetching is still kept behind the optional `browser`
+extra for future extension.
+
+## Live Web Tests
+
+Live web tests are skipped unless `VALYU_API_KEY` is set and the `web` extra is
+installed:
+
+```bash
+python -m pip install -e ".[dev,web]"
+VALYU_API_KEY=... pytest -m live
+```
+
+The broader web quality eval is opt-in because it consumes live provider quota:
+
+```bash
+VALYU_API_KEY=... MODIS_TOOLS_RUN_WEB_EVAL=1 pytest -m "live and eval" -vv
+```
+
+See `docs/WEB_EVAL.md` for the current query set and comparison checklist.

modis_py_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+modis_tools/__init__.py,sha256=Ye_fTAwo4SkDe2fcWXxBrAfLfgMH6wx2EW50ibHOJko,1512
+modis_tools/_version.py,sha256=JeE2NWwTR2llH1GLrPqAzny93cCPCuOdnjwEs4d_sHA,55
+modis_tools/conversion.py,sha256=YwowtmyRrHtDsGdOk-4MJKES0I_hCqsP9FuqcZoWIvw,5789
+modis_tools/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+modis_tools/registry.py,sha256=np8DvLrreIsrzu1Jp3oO5QNr8uaNfCurECDrOmV-EHM,5577
+modis_tools/results.py,sha256=E95RVzYvLMVIOocV3bMDTViJlz0yF41ss2T9PoPWxDw,1150
+modis_tools/schemas.py,sha256=UPBsUp_fOT-KzWgfhOI_Vfmd0a_Mt_u6U4-SoAkcTT0,3363
+modis_tools/serialization.py,sha256=AzlP1tbVLrLyckUdgQIvNr7ODCbhuEWK5PwMMrdynBU,1888
+modis_tools/builtins/__init__.py,sha256=DsVV9LOcCV1J_zGekpnDBBOQ-CoGZmFfFiMiIixo7Ck,607
+modis_tools/builtins/python.py,sha256=z8vb1b3yfubVhxYxjLCd-Dz7DsvlJtj5ZLq0nIPCHj8,3786
+modis_tools/builtins/shell.py,sha256=Lks6PLRMTZAHKqYZJBvozO-K3f5FQNmW8tNDidGGwJc,7611
+modis_tools/builtins/shell_policy.py,sha256=6tG6b6JoBFx3pB4XghZLstdTGwWYK1gZBuEQ05BrbG4,9060
+modis_tools/builtins/web.py,sha256=v_bxA5dkobFddakd9CkdhLmcu0wcMd2OiKAK5vDTEGg,10638
+modis_tools/providers/__init__.py,sha256=VtLp_ZUsjA8u18Tk3Gz8GjGdBVD-PLMIPF3Xi8uVFnk,296
+modis_tools/providers/valyu.py,sha256=TJeekS6jRRxWhFoRhJYsgon4I774oaXRU3XBwGme1rg,9291
+modis_tools/providers/web.py,sha256=yvhKKwlRmrDulJ9aS_ogXehjWuhjVvu7l3KU-32NOqY,5833
+modis_tools/skills/__init__.py,sha256=sBv8-HLoGsfh9GhT-vybrOi2nZA5J0wI-X-gw4xiyC0,660
+modis_tools/skills/models.py,sha256=dvsyrojQmElWiLAk_Lz-JcC6OrISTExonzIztX9cI60,1320
+modis_tools/skills/prompt.py,sha256=dYk_3tYM-dBp4RNUAq6MTQ698lUzMXW5EWjMzt87eN0,1980
+modis_tools/skills/registry.py,sha256=TLa-uAEMIpXeoGLjvTIDcbAfBuF10ACPbl15UlLSKOY,5807
+modis_tools/skills/tools.py,sha256=Ryq4HHYwQS9UF8tRQAp5rucvdbNOENI-IWuXxOKF_cU,3861
+modis_py_tools-0.1.0.dist-info/METADATA,sha256=IFJLwMvNE41HM-9RfoEcsLFhFMpZ2XyiDZFyL1e_fts,9526
+modis_py_tools-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+modis_py_tools-0.1.0.dist-info/top_level.txt,sha256=Ledtj3ITdO0GXQpLc1HE7Un8N-XVo3sPskg8bxAjzfw,12
+modis_py_tools-0.1.0.dist-info/RECORD,,

modis_py_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

modis_py_tools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+modis_tools

modis_tools/__init__.py

@@ -0,0 +1,65 @@
+"""Public API for MoDIS-compatible Python tools."""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .conversion import function_to_tool
+from .registry import ToolExecutor, ToolGroup, ToolRegistry
+from .results import failed_result, successful_result
+from .schemas import (
+    ProcessResult,
+    PythonResult,
+    ShellResult,
+    ToolCall,
+    ToolCallFunction,
+    ToolDefinition,
+    ToolError,
+    ToolFunctionDefinition,
+    ToolResult,
+)
+from .serialization import parse_arguments, to_content_string, to_json_compatible, truncate_text
+from .skills import (
+    PromptSkillEvaluator,
+    SkillExecutionMode,
+    SkillMetadata,
+    SkillNotFoundError,
+    SkillRegistry,
+    SkillResource,
+    SkillResourceError,
+    SkillRuntimeConfig,
+    build_skill_system_prompt,
+    skills_group,
+)
+
+__all__ = [
+    "__version__",
+    "PromptSkillEvaluator",
+    "ProcessResult",
+    "PythonResult",
+    "ShellResult",
+    "SkillExecutionMode",
+    "SkillMetadata",
+    "SkillNotFoundError",
+    "SkillRegistry",
+    "SkillResource",
+    "SkillResourceError",
+    "SkillRuntimeConfig",
+    "ToolCall",
+    "ToolCallFunction",
+    "ToolDefinition",
+    "ToolError",
+    "ToolExecutor",
+    "ToolFunctionDefinition",
+    "ToolGroup",
+    "ToolRegistry",
+    "ToolResult",
+    "build_skill_system_prompt",
+    "failed_result",
+    "function_to_tool",
+    "parse_arguments",
+    "skills_group",
+    "successful_result",
+    "to_content_string",
+    "to_json_compatible",
+    "truncate_text",
+]

modis_tools/_version.py

@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "0.1.0"

modis_tools/builtins/__init__.py

@@ -0,0 +1,25 @@
+"""Built-in MoDIS tool groups."""
+
+from __future__ import annotations
+
+from ..skills import skills_group
+from .python import python_group
+from .python import run as run_python
+from .shell import run as run_shell
+from .shell import shell_group
+from .shell_policy import ShellDecision, ShellPolicy, ShellPolicyDeniedError, ShellRequest
+from .web import WebBrowser, web_group
+
+__all__ = [
+    "ShellDecision",
+    "ShellPolicy",
+    "ShellPolicyDeniedError",
+    "ShellRequest",
+    "WebBrowser",
+    "python_group",
+    "run_python",
+    "run_shell",
+    "shell_group",
+    "skills_group",
+    "web_group",
+]

modis_tools/builtins/python.py

@@ -0,0 +1,119 @@
+"""Python interpreter execution tool."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+
+from ..conversion import function_to_tool
+from ..registry import ToolExecutor, ToolGroup
+from ..schemas import PythonResult
+from ..serialization import truncate_text
+
+
+def run(
+    code: str,
+    python_executable: str | None = None,
+    workdir: str | None = None,
+    timeout_seconds: float = 30.0,
+    env: dict[str, str] | None = None,
+    max_output_chars: int = 20_000,
+) -> PythonResult:
+    """Execute Python code in a subprocess and capture its process result.
+
+    Args:
+        code: Python source code passed to the interpreter with `-c`.
+        python_executable: Optional interpreter path. Defaults to the current interpreter.
+        workdir: Optional working directory for the interpreter process.
+        timeout_seconds: Maximum execution time in seconds.
+        env: Optional environment variable overrides.
+        max_output_chars: Maximum characters retained for stdout and stderr.
+
+    Returns:
+        Captured stdout, stderr, exit code, timeout state, duration, and truncation metadata.
+    """
+
+    if timeout_seconds <= 0:
+        raise ValueError("timeout_seconds must be greater than 0.")
+
+    executable = python_executable or sys.executable
+    start = time.monotonic()
+    merged_env = _merged_env(env)
+    try:
+        completed = subprocess.run(
+            [executable, "-c", code],
+            cwd=workdir,
+            env=merged_env,
+            timeout=timeout_seconds,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        duration_seconds = time.monotonic() - start
+        stdout, stdout_truncated = truncate_text(completed.stdout or "", max_output_chars)
+        stderr, stderr_truncated = truncate_text(completed.stderr or "", max_output_chars)
+        return PythonResult(
+            command=executable,
+            code=code,
+            stdout=stdout,
+            stderr=stderr,
+            exitCode=completed.returncode,
+            durationSeconds=duration_seconds,
+            timedOut=False,
+            truncated=stdout_truncated or stderr_truncated,
+            workdir=workdir,
+        )
+    except subprocess.TimeoutExpired as exc:
+        duration_seconds = time.monotonic() - start
+        stdout, stdout_truncated = truncate_text(_coerce_output(exc.stdout), max_output_chars)
+        stderr, stderr_truncated = truncate_text(_coerce_output(exc.stderr), max_output_chars)
+        return PythonResult(
+            command=executable,
+            code=code,
+            stdout=stdout,
+            stderr=stderr,
+            exitCode=-1,
+            durationSeconds=duration_seconds,
+            timedOut=True,
+            truncated=stdout_truncated or stderr_truncated,
+            workdir=workdir,
+        )
+
+
+def python_group(**defaults: object) -> ToolGroup:
+    """Return the built-in Python interpreter tool group.
+
+    Args:
+        **defaults: Default arguments applied to every `python.run` invocation.
+
+    Returns:
+        A tool group containing `python.run`.
+    """
+
+    return ToolGroup(
+        name="python",
+        executors=(
+            ToolExecutor(
+                name="python.run",
+                exec=run,
+                definition=function_to_tool(run, name="python.run"),
+                defaults=defaults,
+            ),
+        ),
+    )
+
+
+def _merged_env(env: dict[str, str] | None) -> dict[str, str] | None:
+    if env is None:
+        return None
+    return {**os.environ, **{str(key): str(value) for key, value in env.items()}}
+
+
+def _coerce_output(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    return value