smithy-engine 0.6.0__py3-none-any.whl

smithy/__init__.py

@@ -0,0 +1,75 @@
+"""Smithy — Free Python RPA engine for creating automation bots."""
+
+from smithy.core.config import Config, load_config
+from smithy.core.errors import (
+    BusinessError,
+    Cancelled,
+    ConfigError,
+    ElementNotFound,
+    InfrastructureError,
+    InvalidInput,
+    PlatformError,
+    ToolError,
+)
+from smithy.core.http_queue import HttpQueue, HttpQueueError
+from smithy.core.logging import JsonlEventLogger
+from smithy.core.queue import (
+    ClaimedItem,
+    InMemoryQueue,
+    LeaseRenewable,
+    Queue,
+    QueueInfo,
+    QueueItem,
+    SqliteQueue,
+)
+from smithy.core.retry import RetryTool
+from smithy.core.schema import validate_against_schema
+from smithy.core.tool import AbstractTool, Tool, tool
+from smithy.core.transactions import (
+    ItemOutcome,
+    TransactionContextMiddleware,
+    TransactionReport,
+    current_transaction_id,
+    run_transactions,
+    run_transactions_async,
+)
+from smithy.facade import ClickResult, ProcessHandle, Smithy
+
+__version__ = "0.6.0"
+
+__all__ = [
+    "AbstractTool",
+    "BusinessError",
+    "Cancelled",
+    "ClaimedItem",
+    "ClickResult",
+    "Config",
+    "ConfigError",
+    "ElementNotFound",
+    "HttpQueue",
+    "HttpQueueError",
+    "InMemoryQueue",
+    "InvalidInput",
+    "ItemOutcome",
+    "JsonlEventLogger",
+    "LeaseRenewable",
+    "PlatformError",
+    "ProcessHandle",
+    "Queue",
+    "QueueInfo",
+    "QueueItem",
+    "RetryTool",
+    "Smithy",
+    "SqliteQueue",
+    "InfrastructureError",
+    "Tool",
+    "ToolError",
+    "TransactionContextMiddleware",
+    "TransactionReport",
+    "current_transaction_id",
+    "load_config",
+    "run_transactions",
+    "run_transactions_async",
+    "tool",
+    "validate_against_schema",
+]

smithy/core/__init__.py

@@ -0,0 +1,28 @@
+"""Core traits, types, and error definitions."""
+
+from smithy.core.errors import (
+    BusinessError,
+    Cancelled,
+    ConfigError,
+    ElementNotFound,
+    InfrastructureError,
+    InvalidInput,
+    PlatformError,
+    ToolError,
+)
+from smithy.core.registry import ToolRegistry
+from smithy.core.tool import AbstractTool, Tool
+
+__all__ = [
+    "AbstractTool",
+    "BusinessError",
+    "Cancelled",
+    "ConfigError",
+    "ElementNotFound",
+    "InfrastructureError",
+    "InvalidInput",
+    "PlatformError",
+    "Tool",
+    "ToolError",
+    "ToolRegistry",
+]

smithy/core/blocking.py

@@ -0,0 +1,53 @@
+"""Offload blocking calls to a worker thread with a hard timeout.
+
+UIA/COM calls can hang indefinitely (dead dialogs, stalled COM apartments).
+Every blocking offload in the windows tools goes through :func:`run_blocking`,
+which bounds the wait: default 30 s, tunable via the ``SMITHY_BLOCKING_TIMEOUT``
+environment variable. A timeout raises :class:`PlatformError` instead of
+leaving the bot blocked forever on a starved thread pool.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import os
+from collections.abc import Callable
+from typing import Any
+
+from smithy.core.errors import PlatformError
+
+
+def _default_timeout() -> float:
+    raw = os.environ.get("SMITHY_BLOCKING_TIMEOUT", "30")
+    try:
+        value = float(raw)
+    except ValueError:
+        return 30.0
+    return value if value > 0 else 30.0
+
+
+async def run_blocking(
+    fn: Callable[..., Any],
+    /,
+    *args: Any,
+    timeout: float | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Run ``fn(*args, **kwargs)`` in the default executor with a timeout.
+
+    Raises:
+        PlatformError: If the call does not finish within *timeout* seconds
+            (default: ``SMITHY_BLOCKING_TIMEOUT`` env var, else 30 s).
+    """
+    limit = timeout if timeout is not None else _default_timeout()
+    loop = asyncio.get_running_loop()
+    future = loop.run_in_executor(None, functools.partial(fn, *args, **kwargs))
+    try:
+        return await asyncio.wait_for(future, limit)
+    except TimeoutError as exc:
+        name = getattr(fn, "__qualname__", None) or repr(fn)
+        raise PlatformError(
+            f"blocking call {name} timed out after {limit:g}s "
+            "(tune SMITHY_BLOCKING_TIMEOUT if this is expected)",
+        ) from exc

smithy/core/config.py

@@ -0,0 +1,171 @@
+"""TOML robot config — load once in Init, fail fast, frozen afterwards.
+
+The file replaces the legacy two-column Excel sheet: same idea (one config
+per robot, values differ per environment), but diffable in git, typed, and
+validated up front. Secrets never live here — only *references* to
+orchestrator assets (names, GUIDs); values are fetched at runtime.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from smithy.core.errors import ConfigError
+
+_MISSING = object()
+
+
+class Config:
+    """Immutable attribute-style view over a loaded TOML document.
+
+    Nested tables become nested :class:`Config`, lists become tuples —
+    nothing inside can be reassigned after loading. Access by attribute
+    (``config.paths.workdir``) or by item (``config[\"paths\"][\"workdir\"]``).
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        object.__setattr__(self, "_data", data)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError(f"Config is frozen; cannot set {name!r}")
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self._data[name]
+        except KeyError:
+            raise AttributeError(f"Unknown config key: {name!r}") from None
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._data
+
+    def __repr__(self) -> str:
+        return f"Config({self._data!r})"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Plain deep copy of the document (logging, debugging)."""
+        return {key: _thaw(value) for key, value in self._data.items()}
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, dict):
+        return Config({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+def _thaw(value: Any) -> Any:
+    if isinstance(value, Config):
+        return value.to_dict()
+    if isinstance(value, tuple):
+        return [_thaw(item) for item in value]
+    return value
+
+
+def _lookup(config: Config, dotted: str) -> Any:
+    current: Any = config
+    for part in dotted.split("."):
+        if isinstance(current, Config) and part in current:
+            current = current[part]
+        else:
+            return _MISSING
+    return current
+
+
+def _parse_env_value(raw: str) -> Any:
+    """Interpret an env value with TOML scalar syntax; fall back to string.
+
+    ``"8080"`` becomes ``8080``, ``"true"`` becomes ``True``,
+    ``"C:\\temp"`` (not valid TOML) stays a plain string.
+    """
+    try:
+        return tomllib.loads(f"value = {raw}")["value"]
+    except ValueError:
+        return raw
+
+
+def _deep_set(document: dict[str, Any], parts: list[str], value: Any) -> None:
+    """Set a nested key, creating intermediate tables as needed."""
+    current = document
+    for part in parts[:-1]:
+        child = current.get(part)
+        if not isinstance(child, dict):
+            child = {}
+            current[part] = child
+        current = child
+    current[parts[-1]] = value
+
+
+def _apply_env_overlay(document: dict[str, Any], prefix: str) -> None:
+    """Overlay ``<prefix>*`` env vars onto the TOML document (in place).
+
+    ``SMITHY_ROBOT__QUEUE`` sets ``robot.queue``; double underscore nests,
+    single underscores stay literal (``SMITHY_ROBOT_NAME`` → ``robot_name``).
+    Values are typed with TOML scalar syntax (ints, bools, quoted strings).
+    """
+    for name, raw in os.environ.items():
+        if not name.startswith(prefix):
+            continue
+        rest = name[len(prefix) :].lower()
+        if not rest:
+            continue
+        _deep_set(document, rest.split("__"), _parse_env_value(raw))
+
+
+def load_config(
+    path: str | Path,
+    *,
+    required: tuple[str, ...] | list[str] = (),
+    must_exist: tuple[str, ...] | list[str] = (),
+    env_prefix: str | None = "SMITHY_",
+) -> Config:
+    """Load *path* as TOML and validate it.
+
+    Raises one :class:`ConfigError` listing *every* problem at once —
+    the robot fails in Init, never mid-run. *required* are dotted keys
+    that must be present (``\"robot.queue\"``); *must_exist* are dotted
+    keys whose values must be existing filesystem paths.
+
+    When *env_prefix* is set (default ``\"SMITHY_\"``), matching env vars
+    override file values — per-environment tweaks without editing TOML.
+    ``SMITHY_ROBOT__QUEUE`` sets ``robot.queue`` (``__`` nests, values are
+    TOML-typed). Checks run *after* the overlay, so env can satisfy
+    *required*. Pass ``env_prefix=None`` to disable.
+    """
+    file = Path(path)
+    try:
+        raw = file.read_bytes()
+    except OSError as exc:
+        raise ConfigError(f"Cannot read config file: {file}", input_value=str(file)) from exc
+    try:
+        document = tomllib.loads(raw.decode("utf-8"))
+    except ValueError as exc:
+        raise ConfigError(f"Invalid TOML in {file}: {exc}", input_value=str(file)) from exc
+    if env_prefix:
+        _apply_env_overlay(document, env_prefix)
+    frozen = _freeze(document)
+    assert isinstance(frozen, Config)
+    problems: list[str] = []
+    for key in required:
+        if _lookup(frozen, key) is _MISSING:
+            problems.append(f"missing required key: {key!r}")
+    for key in must_exist:
+        value = _lookup(frozen, key)
+        if value is _MISSING:
+            problems.append(f"missing path key: {key!r}")
+        elif not isinstance(value, (str, Path)) or not Path(value).exists():
+            problems.append(f"path does not exist: {key!r} = {value!r}")
+    if problems:
+        raise ConfigError(
+            f"Invalid config {file}:\n" + "\n".join(f"  - {item}" for item in problems),
+            input_value=str(file),
+        )
+    return frozen

smithy/core/errors.py

@@ -0,0 +1,105 @@
+"""Error types for tool execution and the agent framework."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ToolError(Exception):
+    """Structured error for tool execution.
+
+    Subclasses:
+        InvalidInput — invalid or missing input parameters.
+        ElementNotFound — UI element not found or inaccessible.
+        Cancelled — operation cancelled by user or authority.
+        PlatformError — platform or UIA error with underlying cause.
+        BusinessError — transaction data is invalid, retry is pointless.
+        InfrastructureError — infrastructure failure, retry may help.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class InvalidInput(ToolError):
+    """Invalid or missing input parameters."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        param: str | None = None,
+        input_value: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.param = param
+        self.input_value = input_value
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}({str(self)!r}, "
+            f"param={self.param!r}, input_value={self.input_value!r})"
+        )
+
+
+class ElementNotFound(ToolError):
+    """UI element not found or inaccessible."""
+
+    def __init__(
+        self,
+        message: str = "Element not found",
+        *,
+        selector: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.selector = selector
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({str(self)!r}, selector={self.selector!r})"
+
+
+class Cancelled(ToolError):
+    """Operation cancelled by user or authority."""
+
+    def __init__(self) -> None:
+        super().__init__("Operation cancelled")
+
+
+class PlatformError(ToolError):
+    """Platform or UIA error with underlying cause."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        source: BaseException | None = None,
+        input_value: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.source = source
+        self.input_value = input_value
+
+
+class BusinessError(ToolError):
+    """Transaction data is invalid — retrying the same payload is pointless.
+
+    Raised by ``process_fn`` inside the transaction runner to mark the
+    item as ``business_failed`` (terminal, no requeue).
+    """
+
+
+class InfrastructureError(ToolError):
+    """Infrastructure failure — retrying may help.
+
+    Raised by ``process_fn`` (or produced by the runner from unexpected
+    exceptions) to mark the item as ``system_failed`` (requeued until
+    the queue's ``max_attempts`` budget is exhausted).
+    """
+
+
+class ConfigError(InvalidInput):
+    """Robot config is missing, unreadable, or fails validation.
+
+    Raised once with every problem listed — the robot must not start
+    with a half-valid config.
+    """

smithy/core/events.py

@@ -0,0 +1,67 @@
+"""Middleware event system for tool observability."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class ToolEvent:
+    """Event emitted after each tool execution.
+
+    Attributes:
+        tool_name: Fully-qualified tool name (e.g. ``"windows.click"``).
+        config: The config dict passed to the tool.
+        result: Tool return value (``None`` on error).
+        error: Exception if the tool raised, else ``None``.
+        duration_ms: Wall-clock execution time in milliseconds.
+        timestamp: UTC timestamp of event creation.
+        metadata: Arbitrary data — middleware can attach session IDs,
+            tracing info, etc.  Merged from ``__meta__`` in tool results.
+    """
+
+    tool_name: str
+    config: dict[str, Any]
+    result: Any = None
+    error: Exception | None = None
+    duration_ms: float = 0.0
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Middleware(Protocol):
+    """Protocol for event middleware.
+
+    A middleware receives a :class:`ToolEvent`, may transform it, and
+    returns it for the next middleware.  Return ``None`` to stop
+    propagation.
+    """
+
+    async def __call__(self, event: ToolEvent) -> ToolEvent | None: ...
+
+
+class EventBus:
+    """Ordered middleware pipeline for tool events."""
+
+    def __init__(self) -> None:
+        self._middlewares: list[Middleware] = []
+
+    def add_middleware(self, middleware: Middleware) -> None:
+        """Append a middleware to the pipeline."""
+        self._middlewares.append(middleware)
+
+    async def emit(self, event: ToolEvent) -> ToolEvent | None:
+        """Run *event* through the middleware pipeline.
+
+        Returns the final (possibly transformed) event, or ``None`` if
+        a middleware stopped propagation.
+        """
+        current: ToolEvent | None = event
+        for mw in self._middlewares:
+            if current is None:
+                return None
+            current = await mw(current)
+        return current