arcade-serve 2.0.0__tar.gz

arcade_serve-2.0.0/.gitignore

@@ -0,0 +1,175 @@
+.DS_Store
+credentials.yaml
+docker/credentials.yaml
+
+*.lock
+
+# example data
+examples/data
+scratch
+
+
+docs/source
+
+# From https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

arcade_serve-2.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: arcade-serve
+Version: 2.0.0
+Summary: Arcade Serve - Serving infrastructure for Arcade tools and workers
+Author-email: Arcade <dev@arcade.dev>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: arcade-core<3.0.0,>=2.0.0
+Requires-Dist: fastapi>=0.115.3
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: watchfiles>=1.0.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5.1; extra == 'dev'
+Requires-Dist: pre-commit>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.7; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.1.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Arcade Serve
+
+Serving infrastructure for Arcade tools and workers.
+
+## Overview
+
+Arcade Serve provides the infrastructure for serving Arcade tools:
+
+- **FastAPI Worker**: High-performance FastAPI-based worker implementation
+- **MCP Server**: Model Context Protocol server for tool integration
+- **Core Abstractions**: Base worker classes and components
+- **Authentication**: Auth utilities and routing
+- **Runtime Management**: Tool execution and lifecycle management
+
+## Installation
+
+```bash
+pip install arcade-serve
+```
+
+## Usage
+
+To add a toolkit to a hosted worker such as FastAPI, you can register them in the worker itself.
+This allows you to explicitly define which tools should be included on a particular worker.
+
+
+Here is an example of adding the math toolkit (pip install arcade-math) to a FastAPI Worker:
+```python
+import arcade_math
+from fastapi import FastAPI
+from arcade_tdk import Toolkit
+from arcade_serve.fastapi import FastAPIWorker
+
+app = FastAPI()
+
+worker_secret = os.environ.get("ARCADE_WORKER_SECRET")
+worker = FastAPIWorker(app, secret=worker_secret)
+
+worker.register_toolkit(Toolkit.from_module(arcade_math))
+```
+
+Here is an example of adding the math toolkit (pip install arcade-math) to a MCP Worker
+```python
+import arcade_math
+from arcade_core.catalog import ToolCatalog
+from arcade_serve.mcp.stdio import StdioServer
+
+# 1. Create and populate the tool catalog
+catalog = ToolCatalog()
+catalog.add_module(arcade_math)
+
+
+# 2. Main entrypoint
+async def main():
+    # Create the worker with the tool catalog
+    worker = StdioServer(catalog)
+
+    # Run the worker
+    await worker.run()
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())
+```
+
+## License
+
+MIT License - see LICENSE file for details.

arcade_serve-2.0.0/README.md

@@ -0,0 +1,70 @@
+# Arcade Serve
+
+Serving infrastructure for Arcade tools and workers.
+
+## Overview
+
+Arcade Serve provides the infrastructure for serving Arcade tools:
+
+- **FastAPI Worker**: High-performance FastAPI-based worker implementation
+- **MCP Server**: Model Context Protocol server for tool integration
+- **Core Abstractions**: Base worker classes and components
+- **Authentication**: Auth utilities and routing
+- **Runtime Management**: Tool execution and lifecycle management
+
+## Installation
+
+```bash
+pip install arcade-serve
+```
+
+## Usage
+
+To add a toolkit to a hosted worker such as FastAPI, you can register them in the worker itself.
+This allows you to explicitly define which tools should be included on a particular worker.
+
+
+Here is an example of adding the math toolkit (pip install arcade-math) to a FastAPI Worker:
+```python
+import arcade_math
+from fastapi import FastAPI
+from arcade_tdk import Toolkit
+from arcade_serve.fastapi import FastAPIWorker
+
+app = FastAPI()
+
+worker_secret = os.environ.get("ARCADE_WORKER_SECRET")
+worker = FastAPIWorker(app, secret=worker_secret)
+
+worker.register_toolkit(Toolkit.from_module(arcade_math))
+```
+
+Here is an example of adding the math toolkit (pip install arcade-math) to a MCP Worker
+```python
+import arcade_math
+from arcade_core.catalog import ToolCatalog
+from arcade_serve.mcp.stdio import StdioServer
+
+# 1. Create and populate the tool catalog
+catalog = ToolCatalog()
+catalog.add_module(arcade_math)
+
+
+# 2. Main entrypoint
+async def main():
+    # Create the worker with the tool catalog
+    worker = StdioServer(catalog)
+
+    # Run the worker
+    await worker.run()
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())
+```
+
+## License
+
+MIT License - see LICENSE file for details.

arcade_serve-2.0.0/arcade_serve/core/auth.py

@@ -0,0 +1,45 @@
+import logging
+from dataclasses import dataclass
+from enum import Enum
+
+import jwt
+
+SUPPORTED_TOKEN_VER = "1"  # noqa: S105 Possible hardcoded password assigned (false positive)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TokenValidationResult:
+    valid: bool
+    error: str | None = None
+
+
+class SigningAlgorithm(str, Enum):
+    HS256 = "HS256"
+
+
+def validate_engine_token(worker_secret: str, token: str) -> TokenValidationResult:
+    try:
+        payload = jwt.decode(
+            token,
+            worker_secret,
+            algorithms=[SigningAlgorithm.HS256],
+            verify=True,
+            audience="worker",
+        )
+    except jwt.InvalidSignatureError as e:
+        logger.warning(
+            "Invalid signature. Is the Arcade Engine configured with the Worker secret '%s'?",
+            worker_secret,
+        )
+        return TokenValidationResult(valid=False, error=str(e))
+
+    except jwt.InvalidTokenError as e:
+        return TokenValidationResult(valid=False, error=str(e))
+
+    token_ver = payload.get("ver")
+    if token_ver != SUPPORTED_TOKEN_VER:
+        return TokenValidationResult(valid=False, error=f"Unsupported token version: {token_ver}")
+
+    return TokenValidationResult(valid=True)

arcade_serve-2.0.0/arcade_serve/core/base.py

@@ -0,0 +1,185 @@
+import logging
+import os
+import time
+from datetime import datetime
+from typing import Any, Callable, ClassVar
+
+from arcade_core.catalog import ToolCatalog, Toolkit
+from arcade_core.executor import ToolExecutor
+from arcade_core.schema import (
+    ToolCallRequest,
+    ToolCallResponse,
+    ToolDefinition,
+)
+from opentelemetry import trace
+from opentelemetry.metrics import Meter
+
+from arcade_serve.core.common import Router, Worker
+from arcade_serve.core.components import (
+    CallToolComponent,
+    CatalogComponent,
+    HealthCheckComponent,
+    WorkerComponent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BaseWorker(Worker):
+    """
+    A base worker class that provides a default implementation for registering tools and invoking them.
+    Worker implementations for specific web frameworks will inherit from this class.
+    """
+
+    base_path = "/worker"  # By default, prefix all our routes with /worker
+
+    default_components: ClassVar[tuple[type[WorkerComponent], ...]] = (
+        CatalogComponent,
+        CallToolComponent,
+        HealthCheckComponent,
+    )
+
+    def __init__(
+        self, secret: str | None = None, disable_auth: bool = False, otel_meter: Meter | None = None
+    ) -> None:
+        """
+        Initialize the BaseWorker with an empty ToolCatalog.
+        If no secret is provided, the worker will use the ARCADE_WORKER_SECRET environment variable.
+        """
+        self.catalog = ToolCatalog()
+        self.disable_auth = disable_auth
+        if disable_auth:
+            logger.warning(
+                "Warning: Worker is running without authentication. Not recommended for production."
+            )
+
+        self.secret = self._set_secret(secret, disable_auth)
+        self.environment = os.environ.get("ARCADE_ENVIRONMENT", "local")
+
+        self.tool_counter = None
+        if otel_meter:
+            self.tool_counter = otel_meter.create_counter(
+                "tool_call", "requests", "Total number of tools called"
+            )
+
+    def _set_secret(self, secret: str | None, disable_auth: bool) -> str:
+        if disable_auth:
+            return ""
+
+        # If secret is provided, use it
+        if secret:
+            return secret
+
+        # If secret is not provided, try to get it from environment variables
+        env_secret = os.environ.get("ARCADE_WORKER_SECRET")
+        if env_secret:
+            return env_secret
+
+        raise ValueError(
+            "No secret provided for worker. Set the ARCADE_WORKER_SECRET environment variable."
+        )
+
+    def get_catalog(self) -> list[ToolDefinition]:
+        """
+        Get the catalog as a list of ToolDefinitions.
+        """
+        return [tool.definition for tool in self.catalog]
+
+    def register_tool(self, tool: Callable, toolkit_name: str) -> None:
+        """
+        Register a tool to the catalog.
+        """
+        self.catalog.add_tool(tool, toolkit_name)
+
+    def register_toolkit(self, toolkit: Toolkit) -> None:
+        """
+        Register a toolkit to the catalog.
+        """
+        self.catalog.add_toolkit(toolkit)
+
+    async def call_tool(self, tool_request: ToolCallRequest) -> ToolCallResponse:
+        """
+        Call (invoke) a tool using the ToolExecutor.
+        """
+        tool_fqname = tool_request.tool.get_fully_qualified_name()
+
+        try:
+            materialized_tool = self.catalog.get_tool(tool_fqname)
+        except KeyError:
+            raise ValueError(
+                f"Tool {tool_fqname} not found in catalog with toolkit version {tool_request.tool.version}."
+            )
+
+        start_time = time.time()
+
+        if self.tool_counter:
+            self.tool_counter.add(
+                1,
+                {
+                    "tool_name": tool_fqname.name,
+                    "toolkit_version": str(tool_fqname.toolkit_version),
+                    "toolkit_name": tool_fqname.toolkit_name,
+                    "environment": self.environment,
+                },
+            )
+        execution_id = tool_request.execution_id or ""
+        logger.info(
+            f"{execution_id} | Calling tool: {tool_fqname} version: {tool_request.tool.version}"
+        )
+        logger.debug(f"{execution_id} | Tool inputs: {tool_request.inputs}")
+
+        tracer = trace.get_tracer(__name__)
+        with tracer.start_as_current_span("RunTool"):
+            output = await ToolExecutor.run(
+                func=materialized_tool.tool,
+                definition=materialized_tool.definition,
+                input_model=materialized_tool.input_model,
+                output_model=materialized_tool.output_model,
+                context=tool_request.context,
+                **tool_request.inputs or {},
+            )
+
+        end_time = time.time()  # End time in seconds
+        duration_ms = (end_time - start_time) * 1000  # Convert to milliseconds
+
+        if output.error:
+            logger.warning(
+                f"{execution_id} | Tool {tool_fqname} version {tool_request.tool.version} failed"
+            )
+            logger.warning(f"{execution_id} | Tool error: {output.error.message}")
+            logger.warning(
+                f"{execution_id} | Tool developer message: {output.error.developer_message}"
+            )
+            logger.debug(
+                f"{execution_id} | duration: {duration_ms}ms | Tool output: {output.value}"
+            )
+            if output.error.traceback_info:
+                logger.debug(f"{execution_id} | Tool traceback: {output.error.traceback_info}")
+        else:
+            logger.info(
+                f"{execution_id} | Tool {tool_fqname} version {tool_request.tool.version} success"
+            )
+            logger.debug(
+                f"{execution_id} | duration: {duration_ms}ms | Tool output: {output.value}"
+            )
+
+        return ToolCallResponse(
+            execution_id=execution_id,
+            duration=duration_ms,
+            finished_at=datetime.now().isoformat(),
+            success=not output.error,
+            output=output,
+        )
+
+    def health_check(self) -> dict[str, Any]:
+        """
+        Provide a health check that serves as a heartbeat of worker health.
+        """
+        return {"status": "ok", "tool_count": str(len(self.catalog))}
+
+    def register_routes(self, router: Router) -> None:
+        """
+        Register the necessary routes to the application.
+        """
+        for component_cls in self.default_components:
+            component_cls(self).register(router)

arcade_serve-2.0.0/arcade_serve/core/common.py

@@ -0,0 +1,93 @@
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from arcade_core.schema import ToolCallRequest, ToolCallResponse, ToolDefinition
+from pydantic import BaseModel
+
+CatalogResponse = list[ToolDefinition]
+HealthCheckResponse = dict[str, str]
+JSONResponse = dict[str, Any]
+ResponseData = CatalogResponse | ToolCallResponse | HealthCheckResponse
+
+
+class RequestData(BaseModel):
+    """
+    The raw data for a request to a worker.
+    This is not intended to represent everything about an HTTP request,
+    but just the essential info a framework integration will need to extract from the request.
+    """
+
+    path: str
+    """The path of the request."""
+    method: str
+    """The method of the request."""
+    body_json: JSONResponse | None = None
+    """The deserialized body of the request (e.g. JSON)"""
+
+
+class Router(ABC):
+    """
+    A router is responsible for adding routes to the underlying framework hosting the worker.
+    """
+
+    @abstractmethod
+    def add_route(
+        self,
+        endpoint_path: str,
+        handler: Callable,
+        method: str,
+        require_auth: bool = True,
+        response_type: type[ResponseData] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Add a route to the router.
+        """
+        pass
+
+
+class Worker(ABC):
+    """
+    A Worker represents a collection of tools that is hosted inside a web framework
+    and can be called by an Engine.
+    """
+
+    @abstractmethod
+    def get_catalog(self) -> CatalogResponse:
+        """
+        Get the catalog of tools available in the worker.
+        """
+        pass
+
+    @abstractmethod
+    async def call_tool(self, request: ToolCallRequest) -> ToolCallResponse:
+        """
+        Send a request to call a tool to the Worker
+        """
+        pass
+
+    @abstractmethod
+    def health_check(self) -> HealthCheckResponse:
+        """
+        Perform a health check of the worker
+        """
+        pass
+
+
+class WorkerComponent(ABC):
+    def __init__(self, worker: Worker) -> None:
+        self.worker = worker
+
+    @abstractmethod
+    def register(self, router: Router) -> None:
+        """
+        Register the component with the given router.
+        """
+        pass
+
+    @abstractmethod
+    async def __call__(self, request: RequestData) -> ResponseData:
+        """
+        Handle the request.
+        """
+        pass