ellements 0.2.0__py3-none-any.whl

ellements/standard_tools/terminal.py

@@ -0,0 +1,205 @@
+"""Reusable terminal CLI tool for ellements applications."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shlex
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from ellements.core import ToolSpec
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class TerminalExecutionSpec(BaseModel):
+    """Trusted local terminal execution request."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: str | None = None
+    args: list[str] = Field(default_factory=list)
+    shell: bool = False
+    script: str | None = None
+    cwd: str | None = None
+    env: dict[str, str] = Field(default_factory=dict)
+    stdin: str | None = None
+    timeout_seconds: float = Field(default=300.0, gt=0)
+    max_output_bytes: int = Field(default=100_000, gt=0)
+
+    @model_validator(mode="after")
+    def _validate_command(self) -> TerminalExecutionSpec:
+        if self.shell:
+            if not self.script:
+                raise ValueError("shell terminal execution requires script")
+        elif not self.command:
+            raise ValueError("argv terminal execution requires command")
+        return self
+
+
+class TerminalExecutionResult(BaseModel):
+    """Captured result of a terminal execution."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command_line: list[str]
+    cwd: str | None
+    started_at: datetime
+    completed_at: datetime
+    duration_seconds: float
+    exit_code: int | None
+    timed_out: bool
+    stdout: str
+    stderr: str
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+
+
+async def run_terminal_execution(
+    spec: TerminalExecutionSpec,
+) -> TerminalExecutionResult:
+    """Run a local terminal command with bounded output."""
+    started_at = datetime.now(UTC)
+    start = time.monotonic()
+    env = {**os.environ, **spec.env}
+    stdin_bytes = spec.stdin.encode("utf-8") if spec.stdin is not None else None
+    command_line = (
+        [spec.script or ""] if spec.shell else [spec.command or "", *spec.args]
+    )
+    process = await _start_process(spec, env)
+    timed_out = False
+    try:
+        stdout_bytes, stderr_bytes = await asyncio.wait_for(
+            process.communicate(input=stdin_bytes),
+            timeout=spec.timeout_seconds,
+        )
+    except TimeoutError:
+        timed_out = True
+        process.kill()
+        stdout_bytes, stderr_bytes = await process.communicate()
+    completed_at = datetime.now(UTC)
+    stdout, stdout_truncated = _decode_bounded(stdout_bytes, spec.max_output_bytes)
+    stderr, stderr_truncated = _decode_bounded(stderr_bytes, spec.max_output_bytes)
+    return TerminalExecutionResult(
+        command_line=command_line,
+        cwd=spec.cwd,
+        started_at=started_at,
+        completed_at=completed_at,
+        duration_seconds=time.monotonic() - start,
+        exit_code=process.returncode,
+        timed_out=timed_out,
+        stdout=stdout,
+        stderr=stderr,
+        stdout_truncated=stdout_truncated,
+        stderr_truncated=stderr_truncated,
+    )
+
+
+def terminal_cli_tool(
+    *,
+    name: str = "terminal.run",
+    description: str = "Run a local terminal command with bounded output.",
+    timeout_seconds: float = 300.0,
+    max_output_bytes: int = 100_000,
+) -> ToolSpec:
+    """Return an ellements `ToolSpec` for local CLI execution."""
+
+    async def invoke(
+        command: str | None = None,
+        args: list[str] | None = None,
+        shell: bool = False,
+        script: str | None = None,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        stdin: str | None = None,
+        timeout_seconds: float | None = None,
+        max_output_bytes: int | None = None,
+    ) -> dict[str, Any]:
+        spec = TerminalExecutionSpec(
+            command=command,
+            args=args or [],
+            shell=shell,
+            script=script,
+            cwd=str(Path(cwd)) if cwd is not None else None,
+            env=env or {},
+            stdin=stdin,
+            timeout_seconds=timeout_seconds or terminal_cli_tool_timeout,
+            max_output_bytes=max_output_bytes or terminal_cli_tool_max_output,
+        )
+        return (await run_terminal_execution(spec)).model_dump(mode="json")
+
+    terminal_cli_tool_timeout = timeout_seconds
+    terminal_cli_tool_max_output = max_output_bytes
+    return ToolSpec(
+        name=name,
+        description=description,
+        params_json_schema={
+            "type": "object",
+            "properties": {
+                "command": {"type": "string"},
+                "args": {"type": "array", "items": {"type": "string"}},
+                "shell": {"type": "boolean", "default": False},
+                "script": {"type": "string"},
+                "cwd": {"type": "string"},
+                "env": {
+                    "type": "object",
+                    "additionalProperties": {"type": "string"},
+                },
+                "stdin": {"type": "string"},
+                "timeout_seconds": {"type": "number", "exclusiveMinimum": 0},
+                "max_output_bytes": {"type": "integer", "exclusiveMinimum": 0},
+            },
+        },
+        invoke=invoke,
+    )
+
+
+async def _start_process(
+    spec: TerminalExecutionSpec,
+    env: dict[str, str],
+) -> asyncio.subprocess.Process:
+    if spec.shell:
+        assert spec.script is not None
+        return await asyncio.create_subprocess_shell(
+            spec.script,
+            cwd=spec.cwd,
+            env=env,
+            stdin=asyncio.subprocess.PIPE if spec.stdin is not None else None,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+    assert spec.command is not None
+    return await asyncio.create_subprocess_exec(
+        spec.command,
+        *spec.args,
+        cwd=spec.cwd,
+        env=env,
+        stdin=asyncio.subprocess.PIPE if spec.stdin is not None else None,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+
+def _decode_bounded(data: bytes, max_bytes: int) -> tuple[str, bool]:
+    truncated = len(data) > max_bytes
+    if truncated:
+        data = data[:max_bytes]
+    return data.decode("utf-8", errors="replace"), truncated
+
+
+def terminal_command_text(spec: TerminalExecutionSpec) -> str:
+    """Return a display-safe command string."""
+    if spec.shell:
+        return spec.script or ""
+    return " ".join(shlex.quote(part) for part in [spec.command or "", *spec.args])
+
+
+__all__ = [
+    "TerminalExecutionResult",
+    "TerminalExecutionSpec",
+    "run_terminal_execution",
+    "terminal_cli_tool",
+    "terminal_command_text",
+]

ellements/standard_tools/web/__init__.py

@@ -0,0 +1,37 @@
+"""Web-oriented standard tools for search, crawling, and YouTube access."""
+
+from .browser_viewer import (
+    BrowserViewer,
+    BrowserViewResult,
+    LocalArtifactServer,
+    is_remote_url,
+)
+from .crawler import CrawlResult, ExtractionResult, WebCrawler, web_crawler_tools
+from .search import SearchResult, SearchResults, WebSearcher, web_search_tools
+from .youtube import (
+    RateLimitedYouTubeSearcher,
+    VideoMetadata,
+    VideoTranscript,
+    YouTubeSearcher,
+    youtube_search_tools,
+)
+
+__all__ = [
+    "BrowserViewer",
+    "BrowserViewResult",
+    "CrawlResult",
+    "ExtractionResult",
+    "LocalArtifactServer",
+    "RateLimitedYouTubeSearcher",
+    "SearchResult",
+    "SearchResults",
+    "VideoMetadata",
+    "VideoTranscript",
+    "WebCrawler",
+    "WebSearcher",
+    "YouTubeSearcher",
+    "is_remote_url",
+    "web_crawler_tools",
+    "web_search_tools",
+    "youtube_search_tools",
+]

ellements/standard_tools/web/browser_viewer.py

@@ -0,0 +1,214 @@
+"""Browser display helpers for local artifacts and remote URLs."""
+
+from __future__ import annotations
+
+import functools
+import http.server
+import threading
+import time
+import webbrowser
+from pathlib import Path
+from typing import Literal
+from urllib.parse import quote, urlparse
+
+from pydantic import BaseModel, Field
+
+SourceType = Literal["remote-url", "local-file", "local-directory"]
+
+
+class BrowserViewResult(BaseModel):
+    """Structured result for a browser display target."""
+
+    target: str = Field(description="Original resolved target URL/path.")
+    display_url: str = Field(description="URL to navigate a browser to.")
+    source_type: SourceType = Field(description="Kind of target being displayed.")
+    opened: bool = Field(description="Whether the system browser was opened.")
+    serve_root: str | None = Field(
+        default=None,
+        description="Local directory being served for local targets.",
+    )
+    host: str | None = Field(default=None, description="Local server host.")
+    port: int | None = Field(default=None, description="Local server port.")
+    duration: int | None = Field(
+        default=None,
+        description="Requested local-server lifetime in seconds.",
+    )
+
+
+def is_remote_url(target: str) -> bool:
+    """Return whether a target is an HTTP(S) URL."""
+    parsed = urlparse(target)
+    return parsed.scheme in {"http", "https"}
+
+
+def _url_path(path: Path) -> str:
+    return "/".join(quote(part) for part in path.parts)
+
+
+def _resolve_local_target(target: str | Path) -> tuple[Path, Path, str]:
+    path = Path(target).expanduser().resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Local target not found: {path}")
+
+    if path.is_dir():
+        return path, path, ""
+    return path, path.parent, _url_path(Path(path.name))
+
+
+class LocalArtifactServer:
+    """Small localhost HTTP server for browser-blocked local files/directories."""
+
+    def __init__(
+        self,
+        target: str | Path,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+    ) -> None:
+        self.target = target
+        self.host = host
+        self.port = port
+        self.resolved_target, self.serve_root, self._relative_url = (
+            _resolve_local_target(target)
+        )
+        self._server: http.server.ThreadingHTTPServer | None = None
+        self._thread: threading.Thread | None = None
+
+    @property
+    def source_type(self) -> SourceType:
+        """Return whether the target is a file or directory."""
+        return "local-directory" if self.resolved_target.is_dir() else "local-file"
+
+    @property
+    def display_url(self) -> str:
+        """Return the browser URL for the served target."""
+        if self._server is None:
+            raise RuntimeError("Local artifact server has not been started.")
+        port = int(self._server.server_address[1])
+        display_url = f"http://{self.host}:{port}/"
+        if self._relative_url:
+            display_url += self._relative_url
+        return display_url
+
+    def start(self) -> LocalArtifactServer:
+        """Start serving the target directory in a daemon thread."""
+        if self._server is not None:
+            return self
+
+        handler = functools.partial(
+            http.server.SimpleHTTPRequestHandler,
+            directory=str(self.serve_root),
+        )
+        self._server = http.server.ThreadingHTTPServer((self.host, self.port), handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        return self
+
+    def shutdown(self) -> None:
+        """Stop the local server if it is running."""
+        if self._server is None:
+            return
+        self._server.shutdown()
+        self._server.server_close()
+        self._server = None
+        self._thread = None
+
+    def __enter__(self) -> LocalArtifactServer:
+        return self.start()
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.shutdown()
+
+
+class BrowserViewer:
+    """Open remote URLs or serve local artifacts for browser display."""
+
+    def open_remote(
+        self, target: str, *, open_browser: bool = True
+    ) -> BrowserViewResult:
+        """Open a remote HTTP(S) URL or return the browser target."""
+        if not is_remote_url(target):
+            raise ValueError(f"Not an HTTP(S) URL: {target}")
+        if open_browser:
+            webbrowser.open(target)
+        return BrowserViewResult(
+            target=target,
+            display_url=target,
+            source_type="remote-url",
+            opened=open_browser,
+        )
+
+    def serve_local(
+        self,
+        target: str | Path,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        open_browser: bool = True,
+        duration: int | None = None,
+    ) -> tuple[LocalArtifactServer, BrowserViewResult]:
+        """Start serving a local file/directory and return the live server."""
+        server = LocalArtifactServer(target, host=host, port=port).start()
+        if open_browser:
+            webbrowser.open(server.display_url)
+        result = BrowserViewResult(
+            target=str(server.resolved_target),
+            display_url=server.display_url,
+            source_type=server.source_type,
+            opened=open_browser,
+            serve_root=str(server.serve_root),
+            host=host,
+            port=int(server.display_url.split(":", 2)[2].split("/", 1)[0]),
+            duration=duration,
+        )
+        return server, result
+
+    def serve_for_duration(
+        self,
+        target: str | Path,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        duration: int = 300,
+        open_browser: bool = True,
+    ) -> BrowserViewResult:
+        """Serve a local target for a bounded duration; 0 means until interrupted."""
+        server, result = self.serve_local(
+            target,
+            host=host,
+            port=port,
+            open_browser=open_browser,
+            duration=duration,
+        )
+        try:
+            if duration == 0:
+                while True:
+                    time.sleep(3600)
+            else:
+                time.sleep(duration)
+        except KeyboardInterrupt:
+            pass
+        finally:
+            server.shutdown()
+        return result
+
+    def open(
+        self,
+        target: str | Path,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        duration: int = 300,
+        open_browser: bool = True,
+    ) -> BrowserViewResult:
+        """Open a remote URL directly or serve a local target for browser display."""
+        target_text = str(target)
+        if is_remote_url(target_text):
+            return self.open_remote(target_text, open_browser=open_browser)
+        return self.serve_for_duration(
+            target,
+            host=host,
+            port=port,
+            duration=duration,
+            open_browser=open_browser,
+        )