langchain-openapi-tools 1.0.0__py3-none-any.whl

langchain_openapi/__init__.py

@@ -0,0 +1,143 @@
+"""LangChain OpenAPI package.
+
+Provides utilities for loading, parsing, converting OpenAPI specifications,
+executing HTTP requests asynchronously, configuring request providers,
+applying production middleware, and exporting dynamic LangChain tools.
+"""
+
+from langchain_openapi.enums import DataType, HTTPMethod, ParameterLocation
+from langchain_openapi.exceptions import (
+    AuthenticationError,
+    ExecutionTimeoutError,
+    HTTPExecutionError,
+    InvalidSpecError,
+    OpenAPIError,
+    ProviderError,
+    RequestValidationError,
+    ResponseParsingError,
+    SpecLoadError,
+    UnsupportedVersionError,
+)
+from langchain_openapi.executor import (
+    AsyncHTTPExecutor,
+    BuiltRequest,
+    RequestBuilder,
+    ResponseData,
+    ResponseParser,
+    create_async_client,
+)
+from langchain_openapi.loader import OpenAPILoader
+from langchain_openapi.middleware import (
+    CacheBackend,
+    CacheMiddleware,
+    InMemoryCacheBackend,
+    LoggingMiddleware,
+    Middleware,
+    MiddlewarePipeline,
+    NextCallable,
+    PaginationMiddleware,
+    RateLimitMiddleware,
+    RetryMiddleware,
+)
+from langchain_openapi.models import (
+    MediaType,
+    Operation,
+    Parameter,
+    RequestBody,
+    Response,
+    Schema,
+)
+from langchain_openapi.parser import (
+    OpenAPIParser,
+    OpenAPISpec,
+    ReferenceResolver,
+    generate_fallback_operation_name,
+)
+from langchain_openapi.providers import (
+    APIKeyHeaderProvider,
+    APIKeyQueryProvider,
+    BasicAuthProvider,
+    BearerAuthProvider,
+    CompositeProvider,
+    CookiesProvider,
+    NoAuthProvider,
+    RequestProvider,
+    StaticHeadersProvider,
+)
+from langchain_openapi.schema_converter import (
+    PydanticFactory,
+    SchemaConverter,
+    map_schema_type_to_python,
+)
+from langchain_openapi.toolkit import (
+    LangChainToolFactory,
+    OpenAPIToolCallbackHandler,
+    OpenAPIToolkit,
+    build_tool_description,
+    format_tool_name,
+)
+from langchain_openapi.utils import sanitize_request_log
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "APIKeyHeaderProvider",
+    "APIKeyQueryProvider",
+    "AsyncHTTPExecutor",
+    "AuthenticationError",
+    "BasicAuthProvider",
+    "BearerAuthProvider",
+    "BuiltRequest",
+    "CacheBackend",
+    "CacheMiddleware",
+    "CompositeProvider",
+    "CookiesProvider",
+    "DataType",
+    "ExecutionTimeoutError",
+    "HTTPExecutionError",
+    "HTTPMethod",
+    "InMemoryCacheBackend",
+    "InvalidSpecError",
+    "LangChainToolFactory",
+    "LoggingMiddleware",
+    "MediaType",
+    "Middleware",
+    "MiddlewarePipeline",
+    "NextCallable",
+    "NoAuthProvider",
+    "OpenAPIError",
+    "OpenAPILoader",
+    "OpenAPIParser",
+    "OpenAPISpec",
+    "OpenAPIToolCallbackHandler",
+    "OpenAPIToolkit",
+    "Operation",
+    "PaginationMiddleware",
+    "Parameter",
+    "ParameterLocation",
+    "ProviderError",
+    "PydanticFactory",
+    "RateLimitMiddleware",
+    "ReferenceResolver",
+    "RequestBody",
+    "RequestBuilder",
+    "RequestProvider",
+    "RequestValidationError",
+    "Response",
+    "ResponseData",
+    "ResponseParser",
+    "ResponseParsingError",
+    "RetryMiddleware",
+    "Schema",
+    "SchemaConverter",
+    "SpecLoadError",
+    "StaticHeadersProvider",
+    "UnsupportedVersionError",
+    "__version__",
+    "build_tool_description",
+    "create_async_client",
+    "format_tool_name",
+    "generate_fallback_operation_name",
+    "map_schema_type_to_python",
+    "sanitize_request_log",
+]

langchain_openapi/enums.py

@@ -0,0 +1,35 @@
+"""Enumerations for OpenAPI specification entities."""
+
+from enum import StrEnum
+
+
+class HTTPMethod(StrEnum):
+    """Supported HTTP request methods."""
+
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    PATCH = "PATCH"
+    DELETE = "DELETE"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+
+
+class ParameterLocation(StrEnum):
+    """Locations where parameters can be supplied in an HTTP request."""
+
+    PATH = "path"
+    QUERY = "query"
+    HEADER = "header"
+    COOKIE = "cookie"
+
+
+class DataType(StrEnum):
+    """Core data types supported in OpenAPI schemas."""
+
+    STRING = "string"
+    INTEGER = "integer"
+    NUMBER = "number"
+    BOOLEAN = "boolean"
+    ARRAY = "array"
+    OBJECT = "object"

langchain_openapi/exceptions.py

@@ -0,0 +1,41 @@
+"""Custom exceptions for langchain-openapi."""
+
+
+class OpenAPIError(Exception):
+    """Base exception for all langchain-openapi errors."""
+
+
+class SpecLoadError(OpenAPIError):
+    """Raised when an OpenAPI specification cannot be loaded from a source."""
+
+
+class InvalidSpecError(OpenAPIError):
+    """Raised when a loaded specification fails validation requirements."""
+
+
+class UnsupportedVersionError(OpenAPIError):
+    """Raised when the specification uses an unsupported OpenAPI or Swagger version."""
+
+
+class HTTPExecutionError(OpenAPIError):
+    """Base exception for HTTP request execution errors."""
+
+
+class AuthenticationError(HTTPExecutionError):
+    """Raised when authentication credentials fail or cannot be applied."""
+
+
+class ProviderError(HTTPExecutionError):
+    """Raised when a request provider fails during request mutation."""
+
+
+class RequestValidationError(HTTPExecutionError):
+    """Raised when request arguments are invalid or missing required parameters."""
+
+
+class ResponseParsingError(HTTPExecutionError):
+    """Raised when an HTTP response payload cannot be parsed."""
+
+
+class ExecutionTimeoutError(HTTPExecutionError):
+    """Raised when an HTTP request times out."""

langchain_openapi/executor.py

@@ -0,0 +1,266 @@
+"""Asynchronous HTTP execution engine for OpenAPI Operations."""
+
+import logging
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from langchain_openapi.enums import ParameterLocation
+from langchain_openapi.exceptions import (
+    ExecutionTimeoutError,
+    HTTPExecutionError,
+    RequestValidationError,
+    ResponseParsingError,
+)
+from langchain_openapi.middleware import Middleware, MiddlewarePipeline
+from langchain_openapi.models import Operation
+from langchain_openapi.providers import NoAuthProvider, RequestProvider
+from langchain_openapi.utils import sanitize_request_log
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BuiltRequest:
+    """Container for constructed request metadata ready for execution."""
+
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    params: dict[str, Any] = field(default_factory=dict)
+    json_body: Any = None
+    cookies: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ResponseData:
+    """Normalized response payload."""
+
+    status_code: int
+    headers: dict[str, str]
+    body: Any
+    raw: httpx.Response
+
+
+def create_async_client(
+    timeout: float = 30.0,
+    headers: dict[str, str] | None = None,
+    cookies: dict[str, str] | None = None,
+    **kwargs: Any,
+) -> httpx.AsyncClient:
+    """Create a configured httpx.AsyncClient instance."""
+    return httpx.AsyncClient(
+        timeout=timeout,
+        headers=headers,
+        cookies=cookies,
+        **kwargs,
+    )
+
+
+class RequestBuilder:
+    """Translates Operation models into BuiltRequest instances."""
+
+    def __init__(self, base_url: str | None = None) -> None:
+        self.base_url = base_url.rstrip("/") if base_url else ""
+
+    def build(
+        self,
+        operation: Operation,
+        arguments: dict[str, Any],
+        base_url_override: str | None = None,
+    ) -> BuiltRequest:
+        method = operation.method.value.upper()
+        base_url = base_url_override.rstrip("/") if base_url_override else self.base_url
+
+        path_template = operation.path
+        query_params: dict[str, Any] = {}
+        headers: dict[str, str] = {}
+        cookies: dict[str, str] = {}
+        consumed_args: set[str] = set()
+
+        if arguments.get("paginate") or arguments.get("__paginate__"):
+            headers["X-LangChain-Paginate"] = "true"
+            consumed_args.add("paginate")
+            consumed_args.add("__paginate__")
+
+        for param in operation.parameters:
+            name = param.name
+            val = arguments.get(name)
+
+            if param.location == ParameterLocation.PATH:
+                if val is None:
+                    raise RequestValidationError(
+                        f"Missing required path parameter '{name}' "
+                        f"for operation '{operation.name}'."
+                    )
+                path_template = path_template.replace(f"{{{name}}}", str(val))
+                consumed_args.add(name)
+
+            elif param.location == ParameterLocation.QUERY:
+                if val is not None:
+                    query_params[name] = val
+                    consumed_args.add(name)
+
+            elif param.location == ParameterLocation.HEADER:
+                if val is not None:
+                    headers[name] = str(val)
+                    consumed_args.add(name)
+
+            elif param.location == ParameterLocation.COOKIE:
+                if val is not None:
+                    cookies[name] = str(val)
+                    consumed_args.add(name)
+
+        full_url = (
+            f"{base_url}/{path_template.lstrip('/')}" if base_url else path_template
+        )
+
+        json_body: Any = None
+        if operation.request_body:
+            if "body" in arguments:
+                json_body = arguments["body"]
+            else:
+                unconsumed = {
+                    k: v for k, v in arguments.items() if k not in consumed_args
+                }
+                if unconsumed:
+                    json_body = unconsumed
+
+            if json_body is not None and "Content-Type" not in headers:
+                headers["Content-Type"] = "application/json"
+
+        return BuiltRequest(
+            method=method,
+            url=full_url,
+            headers=headers,
+            params=query_params,
+            json_body=json_body,
+            cookies=cookies,
+        )
+
+
+class ResponseParser:
+    """Attempts JSON decoding and standardizes HTTP responses."""
+
+    def parse(self, response: httpx.Response) -> ResponseData:
+        try:
+            status_code = response.status_code
+            headers = dict(response.headers)
+
+            if response.content:
+                try:
+                    body: Any = response.json()
+                except Exception:
+                    body = response.text
+            else:
+                body = None
+
+            return ResponseData(
+                status_code=status_code,
+                headers=headers,
+                body=body,
+                raw=response,
+            )
+        except Exception as exc:
+            raise ResponseParsingError(
+                f"Failed to parse HTTP response from '{response.url}': {exc}"
+            ) from exc
+
+
+class AsyncHTTPExecutor:
+    """Generic asynchronous HTTP executor for executing OpenAPI operations."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        client: httpx.AsyncClient | None = None,
+        provider: RequestProvider | None = None,
+        middleware: Sequence[Middleware] | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url
+        self._client = client
+        self.provider = provider if provider is not None else NoAuthProvider()
+        self.pipeline = MiddlewarePipeline(middleware)
+        self.timeout = timeout
+        self._builder = RequestBuilder(base_url=base_url)
+        self._parser = ResponseParser()
+
+    async def execute(
+        self,
+        operation: Operation,
+        arguments: dict[str, Any],
+        base_url_override: str | None = None,
+    ) -> ResponseData:
+        built_req = self._builder.build(
+            operation=operation,
+            arguments=arguments,
+            base_url_override=base_url_override,
+        )
+
+        start_time = time.monotonic()
+
+        try:
+            if self._client is not None:
+                response = await self._send_request(self._client, built_req)
+            else:
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    response = await self._send_request(client, built_req)
+        except httpx.TimeoutException as exc:
+            logger.error(
+                "Request timed out for %s after %.1fs",
+                sanitize_request_log(built_req.method, built_req.url),
+                self.timeout,
+            )
+            raise ExecutionTimeoutError(
+                f"HTTP request to '{built_req.url}' timed out after {self.timeout}s."
+            ) from exc
+        except (RequestValidationError, ResponseParsingError):
+            raise
+        except httpx.HTTPError as exc:
+            logger.error(
+                "HTTP execution failed for %s: %s",
+                sanitize_request_log(built_req.method, built_req.url),
+                exc,
+            )
+            raise HTTPExecutionError(
+                f"HTTP request execution failed for '{built_req.url}': {exc}"
+            ) from exc
+
+        elapsed = time.monotonic() - start_time
+        logger.info(
+            "Executed HTTP %s -> Status %d (%.3fs)",
+            sanitize_request_log(built_req.method, built_req.url),
+            response.status_code,
+            elapsed,
+        )
+
+        return self._parser.parse(response)
+
+    async def _send_request(
+        self, client: httpx.AsyncClient, req_data: BuiltRequest
+    ) -> httpx.Response:
+        kwargs: dict[str, Any] = {
+            "method": req_data.method,
+            "url": req_data.url,
+            "headers": req_data.headers,
+            "params": req_data.params,
+            "json": req_data.json_body,
+            "timeout": self.timeout,
+        }
+
+        request = client.build_request(**kwargs)
+
+        if req_data.cookies:
+            cookie_hdr = "; ".join(f"{k}={v}" for k, v in req_data.cookies.items())
+            request.headers["Cookie"] = cookie_hdr
+
+        request = await self.provider.apply(request)
+
+        async def transport_call(req: httpx.Request) -> httpx.Response:
+            return await client.send(req)
+
+        return await self.pipeline.execute(request, transport_call)

langchain_openapi/loader.py

@@ -0,0 +1,148 @@
+"""OpenAPI Specification Loader."""
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from langchain_openapi.exceptions import SpecLoadError
+from langchain_openapi.parser import OpenAPISpec
+from langchain_openapi.utils import parse_json_or_yaml, validate_raw_spec
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAPILoader:
+    """Loader for obtaining normalized OpenAPI specifications from various sources.
+
+    Supported sources include local JSON/YAML files, remote URLs, and in-memory dicts.
+    """
+
+    def __init__(
+        self,
+        load_fn: Callable[[], dict[str, Any]],
+        source_info: str,
+    ) -> None:
+        """Initialize loader with a fetch callable and a source description string.
+
+        Args:
+            load_fn: A zero-argument callable that returns a raw spec dictionary.
+            source_info: Human-readable description of the source for logging.
+        """
+        self._load_fn = load_fn
+        self._source_info = source_info
+
+    @classmethod
+    def from_url(
+        cls,
+        url: str,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+    ) -> "OpenAPILoader":
+        """Create an OpenAPILoader for a remote URL source.
+
+        Args:
+            url: HTTP or HTTPS URL of the OpenAPI specification.
+            timeout: Request timeout in seconds (default: 30.0).
+            headers: Optional dictionary of HTTP headers for the request.
+
+        Returns:
+            An OpenAPILoader instance configured for URL fetching.
+        """
+
+        def _fetch_from_url() -> dict[str, Any]:
+            logger.info("Loading OpenAPI specification from URL: %s", url)
+            req_headers = {"User-Agent": "langchain-openapi"}
+            if headers:
+                req_headers.update(headers)
+
+            try:
+                with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+                    response = client.get(url, headers=req_headers)
+                    response.raise_for_status()
+                    content = response.text
+            except httpx.HTTPError as exc:
+                logger.error("Failed to fetch OpenAPI spec from URL '%s': %s", url, exc)
+                raise SpecLoadError(
+                    f"Failed to fetch specification from URL '{url}': {exc}"
+                ) from exc
+
+            return parse_json_or_yaml(content)
+
+        return cls(load_fn=_fetch_from_url, source_info=f"URL '{url}'")
+
+    @classmethod
+    def from_file(cls, file_path: str | Path) -> "OpenAPILoader":
+        """Create an OpenAPILoader for a local JSON or YAML file source.
+
+        Args:
+            file_path: Path to the local OpenAPI specification file.
+
+        Returns:
+            An OpenAPILoader instance configured for file loading.
+        """
+        path = Path(file_path)
+
+        def _read_from_file() -> dict[str, Any]:
+            logger.info("Loading OpenAPI specification from file: %s", path)
+            if not path.exists():
+                logger.error("Specification file does not exist: %s", path)
+                raise SpecLoadError(f"Specification file not found: '{path}'")
+
+            if not path.is_file():
+                logger.error("Path is not a regular file: %s", path)
+                raise SpecLoadError(f"Path is not a regular file: '{path}'")
+
+            try:
+                content = path.read_text(encoding="utf-8")
+            except OSError as exc:
+                logger.error("Error reading specification file '%s': %s", path, exc)
+                raise SpecLoadError(
+                    f"Error reading specification file '{path}': {exc}"
+                ) from exc
+
+            return parse_json_or_yaml(content)
+
+        return cls(load_fn=_read_from_file, source_info=f"file '{path}'")
+
+    @classmethod
+    def from_dict(cls, spec_dict: dict[str, Any]) -> "OpenAPILoader":
+        """Create an OpenAPILoader from an in-memory dictionary.
+
+        Args:
+            spec_dict: Raw Python dictionary containing the OpenAPI specification.
+
+        Returns:
+            An OpenAPILoader instance configured for dictionary loading.
+        """
+
+        def _get_from_dict() -> dict[str, Any]:
+            logger.info("Loading OpenAPI specification from in-memory dictionary")
+            return spec_dict
+
+        return cls(load_fn=_get_from_dict, source_info="in-memory dictionary")
+
+    def load(self) -> OpenAPISpec:
+        """Load, validate, and normalize the OpenAPI specification.
+
+        Returns:
+            An OpenAPISpec instance containing the normalized specification data.
+
+        Raises:
+            SpecLoadError: If loading from source or parsing JSON/YAML fails.
+            InvalidSpecError: If required fields ('openapi', 'paths') are missing.
+            UnsupportedVersionError: If the OpenAPI version is unsupported.
+        """
+        raw_data = self._load_fn()
+        validate_raw_spec(raw_data)
+        spec = OpenAPISpec.from_dict(raw_data)
+
+        logger.info(
+            "Successfully loaded OpenAPI spec '%s' (OpenAPI version %s) from %s",
+            spec.title,
+            spec.version,
+            self._source_info,
+        )
+        return spec