langchain-openapi-tools 1.1.3__tar.gz → 2.0.0__tar.gz

{langchain_openapi_tools-1.1.3 → langchain_openapi_tools-2.0.0}/ARCHITECTURE.md

@@ -30,13 +30,24 @@ The library is structured as a linear transform pipeline with isolated responsib
  │                     OpenAPI Loader                     │
  │          - Parsing (JSON / YAML)                       │
  │          - Ref Resolution ($ref expansion)             │
+ │          - Remembers spec source URL                   │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                    Spec Adapter Layer                  │
+ │          - Version detection (swagger2 / 3.0 / 3.1)    │
+ │          - Swagger2Adapter → OpenAPI 3.0 normalization │
+ │          - OpenAPI3Adapter (pass-through, 3.0 & 3.1)   │
  └───────────────────────────┬────────────────────────────┘
                              │
                              ▼
  ┌────────────────────────────────────────────────────────┐
  │                    Internal Models                     │
  │          - Parsed Spec & Operation trees               │
- │          - Schema normalization                        │
+ │          - Schema normalization (incl. oneOf/anyOf/    │
+ │            allOf / const / read-write flags)           │
+ │          - `spec_family` tag preserved from adapter    │
  └───────────────────────────┬────────────────────────────┘
                              │
                              ▼
@@ -75,7 +86,31 @@ The library is structured as a linear transform pipeline with isolated responsib
 
 The **OpenAPI Loader** is responsible for reading OpenAPI specifications from local file paths, raw strings, or remote HTTP URLs. It handles format auto-detection (JSON vs. YAML), syntax validation, and recursively resolves relative and external `$ref` pointers into a unified, flattened schema representation.
 
-### 3.2 Internal Models & Specification Parser
+When loading from a URL, the loader preserves the source URL on the resulting `OpenAPISpec` (`spec.source_url`). This lets `OpenAPISpec.from_dict` and `SwaggerNormalizer` resolve relative `servers` entries and missing `host` fields to absolute URLs, so `RequestBuilder` always receives an absolute base URL — even for specs like `https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json` that omit the `servers` block entirely.
+
+### 3.2 Spec Adapter Layer
+
+The **Spec Adapter Layer** (`langchain_openapi_tools.adapters`) provides a
+uniform entry point across every supported specification family. It exposes:
+
+* `detect_spec_version(spec_dict) -> Literal["swagger2", "openapi30", "openapi31"]`
+* `SpecAdapter` (`typing.Protocol`) — the shared adapter interface.
+* `Swagger2Adapter` — wraps `SwaggerNormalizer` to lift Swagger 2.0 documents
+  into an OpenAPI 3.0-compatible dictionary while remembering the source URL
+  so `host`/`basePath` gaps can be filled in from the fetch location.
+* `OpenAPI3Adapter` — a pass-through adapter for both OpenAPI 3.0.x and
+  3.1.x documents.
+* `select_adapter(spec_dict)` and `normalize_spec(spec_dict, source_url)` —
+  convenience helpers that pick the right adapter and return a `(normalized
+  dict, spec_family)` tuple.
+
+`OpenAPISpec.from_dict` calls `normalize_spec` before parsing so downstream
+components (`OpenAPIParser`, `SchemaConverter`, `RequestBuilder`) only ever
+see a single canonical shape. `OpenAPISpec.spec_family` records which
+family the document originated from, which is useful for logging and for
+version-aware feature toggles in the future.
+
+### 3.3 Internal Models & Specification Parser
 
 The **OpenAPI Parser** (`OpenAPIParser`) transforms an `OpenAPISpec` into strongly typed, normalized Python dataclasses using the `ReferenceResolver` for local `$ref` pointer resolution:
 
@@ -99,16 +134,19 @@ OpenAPI Spec (File / URL / Dict)
 * **`RequestBody`**: Defines the payload expected by POST/PUT/PATCH operations (`required`, `description`, `content`).
 * **`Response`**: Defines an HTTP response status definition (`status_code`, `description`, `content`).
 * **`MediaType`**: Maps a MIME content-type string to its schema and example payloads (`content_type`, `schema`, `example`, `examples`).
-* **`Schema`**: Normalized schema structure representing primitive and complex types (`type`, `format`, `properties`, `items`, `required`, `enum`, `default`, `nullable`, `description`).
+* **`Schema`**: Normalized schema structure representing primitive and complex types (`type`, `format`, `properties`, `items`, `required`, `enum`, `default`, `nullable`, `description`, `const`, `one_of`, `any_of`, `all_of`, `read_only`, `write_only`, `deprecated`).
 
 #### Current Scope Limitations
 
-The Milestone 3 parser intentionally skips:
-- Polymorphic composition keywords (`oneOf`, `anyOf`, `allOf`, `discriminator`).
+The parser handles JSON Schema union keywords (`oneOf`, `anyOf`, `allOf`) and
+OpenAPI 3.1 features such as list-form `type` and `const`, but intentionally
+skips:
+- `discriminator`-driven union routing.
 - OpenAPI callbacks, links, and webhooks.
+- `patternProperties`, `$dynamicRef`, `$dynamicAnchor`.
 - Advanced example inheritance chains.
 
-### 3.3 Schema Converter
+### 3.4 Schema Converter
 
 The **Schema Converter** (`SchemaConverter` and `PydanticFactory`) converts internal schema models (`Schema`) into dynamic Pydantic `BaseModel` classes using `pydantic.create_model()`.
 
@@ -135,6 +173,11 @@ Dynamic Pydantic Model (type[BaseModel])
 | `array` | `list[T]` | Recursively typed items (e.g. `list[str]`) |
 | `object` | Dynamic `BaseModel` | Dynamic nested models (e.g. `SearchWorksInput_Address`) |
 | `enum` | Dynamic `Enum` | String Enum subclass (e.g. `SortEnum`) |
+| `oneOf` / `anyOf` | `typing.Union[...]` | Variants are recursively converted |
+| `allOf` | Merged `BaseModel` | Properties and `required` sets are combined |
+| `type: [X, "null"]` | `Optional[X]` | 3.1-style nullable union |
+| `nullable: true` | `Optional[X]` | 3.0-style nullable flag |
+| `const` | `Literal[value]` | Fixed constant value |
 
 #### Model Naming Conventions
 
@@ -144,13 +187,14 @@ Dynamic Pydantic Model (type[BaseModel])
 
 #### Current Limitations
 
-The converter currently skips:
-- Polymorphic composition keywords (`oneOf`, `anyOf`, `allOf`, `discriminator`).
+The converter now covers `oneOf` / `anyOf` / `allOf`, list-form `type`,
+`nullable`, and `const`. It intentionally does not yet cover:
+- `discriminator`-driven union routing (variants are unions without tag dispatch).
 - Recursive schemas.
-- XML schema options.
-- Complex union types beyond `Optional`.
+- XML schema-driven request serialization.
+- `patternProperties`, `$dynamicRef`, `$dynamicAnchor`.
 
-### 3.4 Async HTTP Executor Engine
+### 3.5 Async HTTP Executor Engine
 
 The **Async HTTP Executor** (`AsyncHTTPExecutor`) executes an `Operation` asynchronously using `httpx.AsyncClient`, transforming inputs into normalized `ResponseData` instances.
 
@@ -190,11 +234,11 @@ OpenAPIError
       └── ExecutionTimeoutError
 ```
 
-### 3.5 Authentication Provider
+### 3.6 Authentication Provider
 
 The **Authentication Provider** manages auth headers and query parameters dynamically. It supports multiple authentication schemes (API Key, HTTP Bearer, HTTP Basic, OAuth2) and securely injects credentials into outbound HTTP requests without exposing secret values to the LLM agent or tool definitions.
 
-### 3.6 Tool Generator
+### 3.7 Tool Generator
 
 The **Tool Generator** acts as the high-level factory interface for end users. It converts parsed operations into `langchain_core.tools.BaseTool` instances. It supports configuration options such as filtering by HTTP method, operation tags, or path patterns, as well as customizing tool naming conventions and prompt description templates.
 

langchain_openapi_tools-2.0.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to `langchain-openapi` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+- **Spec Adapter Architecture (`langchain_openapi_tools.adapters`)**: Introduced a `SpecAdapter` protocol plus concrete `Swagger2Adapter` and `OpenAPI3Adapter` implementations that provide a uniform pipeline entry for Swagger 2.0, OpenAPI 3.0.x, and OpenAPI 3.1.x documents. New public helpers: `detect_spec_version`, `select_adapter`, and `normalize_spec`. `OpenAPISpec.spec_family` records the source family, and `OpenAPISpec.from_dict` now routes through the adapter layer.
+- **OpenAPI 3.1 Schema Support**: Parser and `SchemaConverter` now understand union `type` arrays (`["string", "null"]`), `const`, `oneOf` / `anyOf` (rendered as `typing.Union`), `allOf` (merged into a single Pydantic model), and the `readOnly` / `writeOnly` / `deprecated` field flags. `Schema` gained `const`, `one_of`, `any_of`, `all_of`, `read_only`, `write_only`, and `deprecated` attributes.
+- **Full Media-Type Dispatch**: `RequestBuilder` now inspects each operation's declared `requestBody` content types and dispatches to the correct httpx encoding path — `application/json` (and `+json` vendor variants), `application/x-www-form-urlencoded`, `multipart/form-data` (with file-part support), `text/*`, and `application/xml`. Pydantic-model bodies produced by the dynamic args schema are coerced back to JSON-safe primitives before serialization. `BuiltRequest` gained `data`, `files`, and `content` fields.
+- **Real-World Compatibility Tests**: Added `tests/test_adapters.py`, `tests/test_openapi_31.py`, `tests/test_media_types.py`, and `tests/test_compat_matrix.py` (Petstore, Crossref, GitHub, Stripe, Kubernetes, ASP.NET fakerestapi excerpts) exercising the full pipeline end-to-end via `respx`.
+
+### Fixed
+- **Base URL Resolution Across the Pipeline**: The specification's source URL is now propagated from `OpenAPILoader.from_url` → `OpenAPISpec` → `OpenAPIParser` → `RequestBuilder`. This closes an architectural gap where relative or missing `servers` entries produced relative request URLs.
+  - OpenAPI 3.x specs that omit the `servers` block (e.g. `https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json`) now default to the document's `scheme://host` origin, matching the OpenAPI 3.x specification.
+  - OpenAPI 3.x relative server URLs (e.g. `"/api/v2"`) are resolved against the document location via `urllib.parse.urljoin`.
+  - Swagger 2.0 specs that omit `host` fall back to the source URL's host and scheme.
+  - `OpenAPISpec` gained a `source_url` field; `OpenAPISpec.from_dict` and `SwaggerNormalizer` accept an optional `source_url` argument for programmatic use.
+  - Redundant Swagger normalization calls in `OpenAPILoader.load` and `OpenAPIParser.__init__` were removed — `OpenAPISpec.from_dict` is now the single normalization site.
+- No changes to `RequestBuilder` or `AsyncHTTPExecutor` were required to fix base-URL resolution; they transparently receive an absolute base URL because `spec.servers[0]` is guaranteed absolute whenever the spec was loaded from a URL.
+
+### Compatibility
+- All previously public APIs (`OpenAPIToolkit`, `OpenAPILoader`, `OpenAPIParser`, `OpenAPISpec`, `SwaggerNormalizer`, `RequestBuilder`, `AsyncHTTPExecutor`, middleware, providers) retain their original signatures. New parameters (`source_url`, `spec_family`) are optional.
+
+---
+
+## [1.0.2] - 2026-08-01
+
+### Fixed
+- **Base URL Generation**: Fixed Swagger 2.0 base URL generation (e.g. Crossref host/basePath/schemes resolution) to prevent relative URL execution errors.
+- **URL Resolution**: Updated `RequestBuilder` to use `urllib.parse.urljoin` for safe URL concatenation.
+
+### Added
+- **Package Naming Clarification**: Clarified PyPI package name (`langchain-openapi-tools`) vs import module name (`langchain_openapi`) across documentation.
+- **Prompt Optimization & Config**: Introduced `OpenAPIToolkitConfig` for user-controlled description modes (`full`, `compact`, `minimal`) and description prompt compression (`compress_descriptions=True`).
+- **Tool Description Customization**: Added `tool_description_overrides` dict and custom `description_builder` callback functions.
+- **Operation & Tag Filtering**: Added tag filtering (`include_tags`, `exclude_tags`) and operation filtering (`include_operations`, `exclude_operations`) at initial toolkit construction level.
+
+---
+
+## [1.0.0] - 2026-08-01
+
+### Added
+- **First Production Release (v1.0.0)**.
+- **OpenAPI Loader**: Load specs from remote URLs, local JSON/YAML files, or Python dictionaries.
+- **OpenAPI Parser**: Strongly typed internal data models for operations, parameters, request bodies, and responses with local `$ref` resolution.
+- **Schema Converter Engine**: Convert JSON Schema parameters and request bodies to dynamic Pydantic models at runtime with optional multi-page pagination controls.
+- **Async HTTP Executor Engine**: Asynchronous execution using `httpx.AsyncClient` with dynamic parameter formatting and response parsing.
+- **LangChain Tool Factory**: Convert OpenAPI operations into dynamic LangChain `StructuredTool` collections with filtering options.
+- **Authentication & Request Providers**: Pluggable provider system (`BearerAuthProvider`, `APIKeyHeaderProvider`, `APIKeyQueryProvider`, `BasicAuthProvider`, `CompositeProvider`).
+- **Production Middleware**: Onion-style pipeline (`RetryMiddleware`, `RateLimitMiddleware`, `CacheMiddleware`, `PaginationMiddleware`, `LoggingMiddleware`).
+- **Documentation & Examples**: Comprehensive MkDocs site, complete example applications (Crossref, GitHub, Petstore, JSONPlaceholder), and benchmark suite.
+- **CI/CD & Release Automation**: GitHub Actions for CI, Release generation, PyPI Trusted Publishing, and GitHub Pages deployment.

{langchain_openapi_tools-1.1.3 → langchain_openapi_tools-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-openapi-tools
-Version: 1.1.3
+Version: 2.0.0
 Summary: Convert OpenAPI specifications into native, production-grade LangChain tools.
 Project-URL: Homepage, https://github.com/abhaywani114/langchain-openapi
 Project-URL: Documentation, https://abhaywani114.github.io/langchain-openapi/
@@ -109,9 +109,38 @@ from langchain_openapi_tools import OpenAPIToolkit
 
 ## Supported Specifications
 
-- ✅ **Swagger 2.0** (Automatically normalized to OpenAPI 3.0)
+- ✅ **Swagger 2.0** (Automatically normalized to OpenAPI 3.0 via the built-in adapter layer)
 - ✅ **OpenAPI 3.0.x** (JSON and YAML)
-- ✅ **OpenAPI 3.1.x** (JSON and YAML)
+- ✅ **OpenAPI 3.1.x** (JSON and YAML, including union `type` arrays, `oneOf` / `anyOf` / `allOf`, and `const`)
+
+> **Note:** Swagger 2.0 is commonly referred to as OpenAPI 2.0.
+
+### Compatibility Matrix
+
+| Feature                                | Swagger 2.0 | OpenAPI 3.0 | OpenAPI 3.1 |
+| -------------------------------------- | :---------: | :---------: | :---------: |
+| Path / query / header / cookie params  | ✅          | ✅          | ✅          |
+| `$ref` resolution (internal)           | ✅          | ✅          | ✅          |
+| Base URL from `host` + `basePath`      | ✅          | —           | —           |
+| Base URL from `servers[]`              | —           | ✅          | ✅          |
+| Fallback base URL from spec source URL | ✅          | ✅          | ✅          |
+| `application/json` request bodies      | ✅          | ✅          | ✅          |
+| `application/x-www-form-urlencoded`    | ✅          | ✅          | ✅          |
+| `multipart/form-data` (incl. files)    | ✅          | ✅          | ✅          |
+| `text/*` and `application/xml`         | ✅          | ✅          | ✅          |
+| Vendor `+json` media types             | ✅          | ✅          | ✅          |
+| `oneOf` / `anyOf` (as Python `Union`)  | —           | ✅          | ✅          |
+| `allOf` merge into single model        | —           | ✅          | ✅          |
+| `nullable: true` (3.0)                 | —           | ✅          | —           |
+| `type: ["string", "null"]` (3.1)       | —           | —           | ✅          |
+| `const`                                | —           | —           | ✅          |
+| `readOnly` / `writeOnly` / `deprecated`| ✅          | ✅          | ✅          |
+| Security: Bearer / API key / Basic     | ✅          | ✅          | ✅          |
+| Async execution (`httpx.AsyncClient`)  | ✅          | ✅          | ✅          |
+
+Not yet supported: `discriminator`-driven union routing, `patternProperties`,
+`$dynamicRef` / `$dynamicAnchor`, callbacks, links, webhooks, and XML request-body
+serialization from Python dicts.
 
 ---
 
@@ -256,3 +285,27 @@ toolkit = OpenAPIToolkit.from_url(
                      ▼
           LangChain StructuredTools
 ```
+
+### Example:
+
+```python
+from langchain_openapi_tools import OpenAPIToolkit
+from langchain.agents import create_agent
+from langchain.chat_models import init_chat_model
+
+toolkit = OpenAPIToolkit.from_url(
+    "https://api.crossref.org/swagger-docs"
+)
+
+model = init_chat_model("openrouter:qwen/qwen3-32b:free")
+
+agent = create_agent(
+    model=model,
+    tools=toolkit.get_tools(tags=["Works"]),
+)
+
+response = agent.invoke({
+    "messages": "Find papers about Kashmir"
+})
+
+```

{langchain_openapi_tools-1.1.3 → langchain_openapi_tools-2.0.0}/README.md

@@ -69,9 +69,38 @@ from langchain_openapi_tools import OpenAPIToolkit
 
 ## Supported Specifications
 
-- ✅ **Swagger 2.0** (Automatically normalized to OpenAPI 3.0)
+- ✅ **Swagger 2.0** (Automatically normalized to OpenAPI 3.0 via the built-in adapter layer)
 - ✅ **OpenAPI 3.0.x** (JSON and YAML)
-- ✅ **OpenAPI 3.1.x** (JSON and YAML)
+- ✅ **OpenAPI 3.1.x** (JSON and YAML, including union `type` arrays, `oneOf` / `anyOf` / `allOf`, and `const`)
+
+> **Note:** Swagger 2.0 is commonly referred to as OpenAPI 2.0.
+
+### Compatibility Matrix
+
+| Feature                                | Swagger 2.0 | OpenAPI 3.0 | OpenAPI 3.1 |
+| -------------------------------------- | :---------: | :---------: | :---------: |
+| Path / query / header / cookie params  | ✅          | ✅          | ✅          |
+| `$ref` resolution (internal)           | ✅          | ✅          | ✅          |
+| Base URL from `host` + `basePath`      | ✅          | —           | —           |
+| Base URL from `servers[]`              | —           | ✅          | ✅          |
+| Fallback base URL from spec source URL | ✅          | ✅          | ✅          |
+| `application/json` request bodies      | ✅          | ✅          | ✅          |
+| `application/x-www-form-urlencoded`    | ✅          | ✅          | ✅          |
+| `multipart/form-data` (incl. files)    | ✅          | ✅          | ✅          |
+| `text/*` and `application/xml`         | ✅          | ✅          | ✅          |
+| Vendor `+json` media types             | ✅          | ✅          | ✅          |
+| `oneOf` / `anyOf` (as Python `Union`)  | —           | ✅          | ✅          |
+| `allOf` merge into single model        | —           | ✅          | ✅          |
+| `nullable: true` (3.0)                 | —           | ✅          | —           |
+| `type: ["string", "null"]` (3.1)       | —           | —           | ✅          |
+| `const`                                | —           | —           | ✅          |
+| `readOnly` / `writeOnly` / `deprecated`| ✅          | ✅          | ✅          |
+| Security: Bearer / API key / Basic     | ✅          | ✅          | ✅          |
+| Async execution (`httpx.AsyncClient`)  | ✅          | ✅          | ✅          |
+
+Not yet supported: `discriminator`-driven union routing, `patternProperties`,
+`$dynamicRef` / `$dynamicAnchor`, callbacks, links, webhooks, and XML request-body
+serialization from Python dicts.
 
 ---
 
@@ -216,3 +245,27 @@ toolkit = OpenAPIToolkit.from_url(
                      ▼
           LangChain StructuredTools
 ```
+
+### Example:
+
+```python
+from langchain_openapi_tools import OpenAPIToolkit
+from langchain.agents import create_agent
+from langchain.chat_models import init_chat_model
+
+toolkit = OpenAPIToolkit.from_url(
+    "https://api.crossref.org/swagger-docs"
+)
+
+model = init_chat_model("openrouter:qwen/qwen3-32b:free")
+
+agent = create_agent(
+    model=model,
+    tools=toolkit.get_tools(tags=["Works"]),
+)
+
+response = agent.invoke({
+    "messages": "Find papers about Kashmir"
+})
+
+```

langchain_openapi_tools-2.0.0/docs/architecture.md

@@ -0,0 +1,72 @@
+# Architecture & Core Pipeline
+
+`langchain-openapi` processes raw OpenAPI specs into native LangChain tools using a clean, modular pipeline.
+
+---
+
+## Execution Pipeline
+
+```text
+OpenAPI Spec (JSON / YAML / Dict)
+              │
+              ▼
+       OpenAPILoader
+              │
+              ▼
+      Spec Adapter Layer  (Swagger 2.0 → 3.0 normalization; 3.0/3.1 pass-through)
+              │
+              ▼
+        OpenAPIParser
+              │
+              ▼
+      SchemaConverter ────► Pydantic Dynamic Models
+              │              (oneOf/anyOf → Union, allOf → merged model,
+              │               const → Literal, nullable → Optional)
+              ▼
+    LangChainToolFactory
+              │
+              ▼
+      AsyncHTTPExecutor
+              │
+              ▼
+     Media-type dispatch (application/json, x-www-form-urlencoded,
+                          multipart/form-data, text/*, application/xml,
+                          vendor +json variants)
+              │
+              ▼
+     Middleware Pipeline (Retry, Cache, RateLimit, Logging, Pagination)
+              │
+              ▼
+      Request Providers (Authentication & Header Mutations)
+              │
+              ▼
+         httpx.AsyncClient (Target HTTP API)
+```
+
+---
+
+## Pipeline Components
+
+### 1. OpenAPILoader
+In-gests raw JSON/YAML specifications from local disk files, remote HTTP endpoints, or in-memory dictionaries. Normalizes encoding and format. When loading from a URL, the loader retains the source URL on the resulting `OpenAPISpec` so relative `servers` entries (OpenAPI 3.x) and missing `host` values (Swagger 2.0) can be resolved to absolute request URLs downstream.
+
+### 2. Spec Adapter Layer
+`langchain_openapi_tools.adapters` provides `SpecAdapter` implementations for every supported family: `Swagger2Adapter` normalizes Swagger 2.0 documents into OpenAPI 3.0 shape (using the source URL to fill in a missing `host`), and `OpenAPI3Adapter` accepts both 3.0.x and 3.1.x without modification. `detect_spec_version()`, `select_adapter()`, and `normalize_spec()` provide the public entry points. The resulting family tag is preserved on `OpenAPISpec.spec_family`.
+
+### 3. OpenAPIParser
+Translates raw specification dictionaries into strongly-typed internal data models (`Operation`, `Parameter`, `RequestBody`, `Response`, `Schema`). Resolves internal `$ref` pointers using `ReferenceResolver`, and extracts polymorphic keywords (`oneOf`, `anyOf`, `allOf`), `const` values, and `readOnly`/`writeOnly`/`deprecated` markers.
+
+### 4. SchemaConverter & PydanticFactory
+Converts JSON Schema representations into dynamic Pydantic models at runtime using `pydantic.create_model()`. Union keywords become `typing.Union`s, `allOf` merges into a single model, list-form `type` becomes a `Union` of Python types, and `nullable` / `type: [X, "null"]` become `Optional[X]`. Incoming LLM tool arguments are validated against the resulting schema before dispatch.
+
+### 5. LangChainToolFactory
+Translates parsed `Operation` models into executable LangChain `StructuredTool` instances.
+
+### 6. AsyncHTTPExecutor
+Orchestrates request building, middleware execution, provider transformations, and asynchronous network transport. `RequestBuilder` inspects the operation's request-body content-types and dispatches to the correct httpx encoding (JSON, form-urlencoded, multipart with files, or raw text/XML), and coerces validated Pydantic body models back to JSON-safe primitives before serialization.
+
+### 7. Middleware Pipeline
+Intercepts outgoing requests and incoming responses to apply retries, rate limiting, caching, result aggregation, and sanitized telemetry.
+
+### 8. Request Providers
+Applies authentication schemes (Bearer tokens, API Keys, Basic Auth) and static headers before network transport.

{langchain_openapi_tools-1.1.3 → langchain_openapi_tools-2.0.0}/docs/toolkit.md

@@ -36,6 +36,18 @@ toolkit = OpenAPIToolkit.from_dict(
 
 ---
 
+## Base URL Resolution
+
+The toolkit determines the base URL used for HTTP requests in this order of precedence:
+
+1. Explicit `base_url` argument passed to `OpenAPIToolkit.__init__` / `from_url` / `from_file` / `from_dict`.
+2. The first entry in the spec's `servers` block (OpenAPI 3.x) or the URL synthesized from `host`/`basePath`/`schemes` (Swagger 2.0).
+3. When `OpenAPIToolkit.from_url(...)` is used and the spec has no `servers` (or Swagger 2.0 has no `host`), the source URL is used as a fallback: relative server URLs are resolved against it via `urljoin`, and a missing `servers` block defaults to the document's `scheme://host` origin — matching the OpenAPI 3.x specification.
+
+This means self-describing endpoints such as `https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json` (an OpenAPI 3.0.1 document that omits the `servers` block) work out of the box without a manual `base_url`. For local files or in-memory dicts with no `servers`, pass `base_url` explicitly.
+
+---
+
 ## Tool Filtering & Selection
 
 Filter generated tools by HTTP methods, tags, or operation names:

{langchain_openapi_tools-1.1.3 → langchain_openapi_tools-2.0.0}/langchain_openapi_tools/__init__.py

@@ -5,6 +5,14 @@ executing HTTP requests asynchronously, configuring request providers,
 applying production middleware, and exporting dynamic LangChain tools.
 """
 
+from langchain_openapi_tools.adapters import (
+    OpenAPI3Adapter,
+    SpecAdapter,
+    Swagger2Adapter,
+    detect_spec_version,
+    normalize_spec,
+    select_adapter,
+)
 from langchain_openapi_tools.enums import DataType, HTTPMethod, ParameterLocation
 from langchain_openapi_tools.exceptions import (
     AuthenticationError,
@@ -107,6 +115,7 @@ __all__ = [
     "MiddlewarePipeline",
     "NextCallable",
     "NoAuthProvider",
+    "OpenAPI3Adapter",
     "OpenAPIError",
     "OpenAPILoader",
     "OpenAPIParser",
@@ -133,15 +142,20 @@ __all__ = [
     "RetryMiddleware",
     "Schema",
     "SchemaConverter",
+    "SpecAdapter",
     "SpecLoadError",
     "StaticHeadersProvider",
+    "Swagger2Adapter",
     "SwaggerNormalizer",
     "UnsupportedVersionError",
     "__version__",
     "build_tool_description",
     "create_async_client",
+    "detect_spec_version",
     "format_tool_name",
     "generate_fallback_operation_name",
     "map_schema_type_to_python",
+    "normalize_spec",
     "sanitize_request_log",
+    "select_adapter",
 ]

langchain_openapi_tools-2.0.0/langchain_openapi_tools/adapters.py

@@ -0,0 +1,126 @@
+"""Specification adapter layer.
+
+This module implements the unified ingestion pipeline that transforms any
+supported API specification (Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1) into a
+single normalized OpenAPI 3.x dictionary. Every downstream component
+(``OpenAPIParser``, ``SchemaConverter``, ``RequestBuilder``, ...) operates
+against the normalized shape and never inspects the original spec version.
+
+Layering::
+
+                    API Specification
+                           │
+          ┌────────────────┴────────────────┐
+          │                                 │
+     Swagger 2.0                     OpenAPI 3.x
+          │                                 │
+          ▼                                 ▼
+   Swagger2Adapter                 OpenAPI3Adapter
+          └──────────────┬──────────────────┘
+                         ▼
+              Normalized Internal Spec
+
+Adapters are stateless and receive an optional ``source_url`` for base-URL
+resolution when the spec omits ``servers`` / ``host``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class SpecAdapter(Protocol):
+    """Protocol for specification-version adapters.
+
+    An adapter accepts a raw specification dictionary and returns a
+    normalized OpenAPI 3.x dictionary. The returned document is the sole
+    input consumed by the rest of the pipeline.
+    """
+
+    def normalize(
+        self, spec_dict: dict[str, Any], source_url: str | None = None
+    ) -> dict[str, Any]:
+        """Return a normalized OpenAPI 3.x dictionary."""
+
+
+class Swagger2Adapter:
+    """Adapter for Swagger 2.0 (a.k.a. OpenAPI 2.0) specifications.
+
+    Delegates to ``SwaggerNormalizer`` for the actual field-by-field
+    translation, then relies on the pipeline's OpenAPI 3.x processing for
+    everything downstream.
+    """
+
+    def normalize(
+        self, spec_dict: dict[str, Any], source_url: str | None = None
+    ) -> dict[str, Any]:
+        from langchain_openapi_tools.swagger import SwaggerNormalizer
+
+        return SwaggerNormalizer(spec_dict, source_url=source_url).normalize()
+
+
+class OpenAPI3Adapter:
+    """Adapter for OpenAPI 3.0 and 3.1 specifications.
+
+    OpenAPI 3.x documents already match the internal normalized shape, so
+    the adapter primarily performs the following:
+
+    * Ensures the document has an ``openapi`` field.
+    * Backfills ``jsonSchemaDialect`` for 3.1 documents that omit it.
+    * Leaves ``servers`` / ``components`` untouched; base-URL resolution is
+      handled by :class:`langchain_openapi_tools.parser.OpenAPISpec`.
+    """
+
+    def normalize(
+        self, spec_dict: dict[str, Any], source_url: str | None = None
+    ) -> dict[str, Any]:
+        return spec_dict
+
+
+def detect_spec_version(spec_dict: dict[str, Any]) -> str:
+    """Detect the spec version family: ``"swagger2"``, ``"openapi30"``, ``"openapi31"``.
+
+    Raises ``UnsupportedVersionError`` for anything else.
+    """
+    from langchain_openapi_tools.exceptions import UnsupportedVersionError
+
+    swagger = str(spec_dict.get("swagger", ""))
+    if swagger == "2.0" or swagger.startswith("2."):
+        return "swagger2"
+
+    openapi = str(spec_dict.get("openapi", ""))
+    if openapi.startswith("3.0"):
+        return "openapi30"
+    if openapi.startswith("3.1"):
+        return "openapi31"
+
+    raise UnsupportedVersionError(
+        f"Unsupported specification version: swagger={swagger!r}, openapi={openapi!r}."
+    )
+
+
+def select_adapter(spec_dict: dict[str, Any]) -> SpecAdapter:
+    """Return the correct :class:`SpecAdapter` for the given raw spec dict."""
+    family = detect_spec_version(spec_dict)
+    if family == "swagger2":
+        return Swagger2Adapter()
+    return OpenAPI3Adapter()
+
+
+def normalize_spec(
+    spec_dict: dict[str, Any], source_url: str | None = None
+) -> tuple[dict[str, Any], str]:
+    """Normalize any supported spec into an OpenAPI 3.x dictionary.
+
+    Args:
+        spec_dict: Raw specification dictionary (Swagger 2.0 or OpenAPI 3.x).
+        source_url: Optional URL the specification was fetched from.
+
+    Returns:
+        Tuple of ``(normalized_dict, family)`` where ``family`` is one of
+        ``"swagger2"``, ``"openapi30"``, ``"openapi31"``.
+    """
+    family = detect_spec_version(spec_dict)
+    adapter = select_adapter(spec_dict)
+    normalized = adapter.normalize(spec_dict, source_url=source_url)
+    return normalized, family