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

{langchain_openapi_tools-1.0.2 → 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.0.2 → langchain_openapi_tools-2.0.0}/Makefile

@@ -10,7 +10,7 @@ lint:
 	uv run ruff check .
 
 typecheck:
-	uv run mypy langchain_openapi tests examples
+	uv run mypy langchain_openapi_tools langchain_openapi tests examples
 
 format:
 	uv run ruff format .

langchain_openapi_tools-2.0.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: langchain-openapi-tools
+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/
+Project-URL: Repository, https://github.com/abhaywani114/langchain-openapi
+Project-URL: Issues, https://github.com/abhaywani114/langchain-openapi/issues
+Author: langchain-openapi contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,langchain,llm,openapi,swagger,tools
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: langchain-core>=1.5.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pytest-asyncio>=1.4.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langchain-openapi
+
+<p align="center">
+  <!-- Logo Placeholder -->
+  <img src="docs/assets/logo.png" alt="langchain-openapi logo" width="200" onerror="this.style.display='none'"/>
+</p>
+
+<p align="center">
+  <em>Convert OpenAPI v3.0 & v3.1 and Swagger 2.0 specifications into native, production-grade LangChain tools.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/abhaywani114/langchain-openapi/actions/workflows/ci.yml"><img src="https://github.com/abhaywani114/langchain-openapi/actions/workflows/ci.yml/badge.svg" alt="CI Status"/></a>
+  <a href="https://pypi.org/project/langchain-openapi-tools/"><img src="https://img.shields.io/pypi/v/langchain-openapi-tools.svg" alt="PyPI Version"/></a>
+  <a href="https://abhaywani114.github.io/langchain-openapi/"><img src="https://img.shields.io/badge/docs-mkdocs-blue.svg" alt="Documentation"/></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"/></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code Style: Ruff"/></a>
+  <a href="http://mypy-lang.org/"><img src="https://img.shields.io/badge/mypy-checked-blue.svg" alt="Checked with MyPy"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"/></a>
+</p>
+
+---
+
+`langchain_openapi` is a modern Python library designed to seamlessly convert OpenAPI v3.0, v3.1, and Swagger 2.0 specifications into native, type-safe [LangChain](https://github.com/langchain-ai/langchain) tools for AI agents and LLM applications.
+
+No python code generation is required—tools are generated dynamically at runtime with strict Pydantic input schemas, prompt optimization options, and production-ready middleware.
+
+---
+
+## Installation & Importing
+
+Install the PyPI package:
+
+```bash
+pip install langchain-openapi-tools
+# or using uv
+uv add langchain-openapi-tools
+```
+
+Import in Python:
+
+```python
+from langchain_openapi_tools import OpenAPIToolkit, OpenAPIToolkitConfig
+```
+
+### Migration Note
+
+```python
+# Old (deprecated, but still works for backward compatibility):
+from langchain_openapi import OpenAPIToolkit
+
+# New (recommended):
+from langchain_openapi_tools import OpenAPIToolkit
+```
+
+---
+
+## Features
+
+- ⚡ **Zero-Code Tool Generation**: Runtime conversion of OpenAPI specs (YAML/JSON) into LangChain `StructuredTool`s.
+- 🚀 **Swagger 2.0 & OpenAPI 3.x**: Native normalization of legacy Swagger 2.0 and modern OpenAPI 3.0/3.1 specs.
+- 🗜️ **Prompt Optimization & Filtering**: Description modes (`full`, `compact`, `minimal`), description compression, overrides, callbacks, and operation/tag filtering to drastically reduce context window usage.
+- 🔒 **Pluggable Authentication**: Built-in support for Bearer Tokens, API Key Headers, Query Parameters, Basic Auth, and custom request providers.
+- 🛡️ **Production Middleware**: Composable middleware architecture for Retries (exponential backoff), Rate Limiting (token-bucket), Caching (TTL), Pagination aggregation, and Sanitized Logging.
+- 🎯 **Type-Safe Validation**: Dynamically generated Pydantic input schemas ensure LLM arguments adhere strictly to specification types before network transport.
+- 🌐 **Async Engine**: Non-blocking asynchronous network transport powered by `httpx.AsyncClient`.
+
+---
+
+## Supported Specifications
+
+- ✅ **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, 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.
+
+---
+
+## Quick Start
+
+```python
+from langchain_openapi_tools import OpenAPIToolkit
+
+# Load spec from remote URL or local file
+toolkit = OpenAPIToolkit.from_url("https://api.crossref.org/swagger-docs")
+
+# Extract generated tools
+tools = toolkit.get_tools()
+
+print(f"Generated {len(tools)} tools:")
+for tool in tools[:3]:
+    print(f"- {tool.name}: {tool.description}")
+```
+
+### Agent Integration
+
+```python
+import asyncio
+from langchain_openapi_tools import OpenAPIToolkit
+
+
+async def main():
+    toolkit = OpenAPIToolkit.from_url("https://api.crossref.org/swagger-docs")
+    search_tool = toolkit.get_tool("get_works")
+
+    if search_tool:
+        result = await search_tool.ainvoke({"query": "LangGraph"})
+        print("Search Result:", result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Prompt Optimization & Tool Customization
+
+Large OpenAPI specifications can generate extensive tool descriptions that exceed model context windows. `langchain_openapi_tools` provides full control over description generation and context footprint.
+
+### Configuration Object (`OpenAPIToolkitConfig`)
+
+```python
+from langchain_openapi_tools import OpenAPIToolkit, OpenAPIToolkitConfig
+
+config = OpenAPIToolkitConfig(
+    description_mode="compact",
+    compress_descriptions=True,
+    include_tags=["Works"],
+    tool_description_overrides={
+        "get_works": "Search scholarly papers registered with Crossref."
+    },
+)
+
+toolkit = OpenAPIToolkit.from_url(
+    "https://api.crossref.org/swagger-docs", config=config
+)
+```
+
+### Description Modes (`description_mode`)
+
+- `full` *(default)*: Complete summary, description, HTTP method, path, and schema parameter details.
+- `compact`: Summary and short parameter list without response schemas or redundant examples.
+- `minimal`: A single-sentence summary ideal for large specifications with dozens of tools.
+
+```python
+toolkit = OpenAPIToolkit.from_url(url, description_mode="minimal")
+```
+
+### Description Compression (`compress_descriptions=True`)
+
+Removes duplicate text, redundant whitespace, and empty sections without altering tool semantics:
+
+```python
+toolkit = OpenAPIToolkit.from_url(url, compress_descriptions=True)
+```
+
+### Custom Overrides & Callbacks
+
+Override descriptions for specific tools:
+
+```python
+toolkit = OpenAPIToolkit.from_url(
+    url, tool_description_overrides={"get_works": "Search scholarly papers."}
+)
+```
+
+Or pass a custom builder callback:
+
+```python
+def my_builder(operation):
+    return f"Execute {operation.name} on path {operation.path}."
+
+
+toolkit = OpenAPIToolkit.from_url(url, description_builder=my_builder)
+```
+
+### Operation Filtering
+
+Filter tools before they are created to reduce context window overhead:
+
+```python
+# Filter by Tags
+toolkit = OpenAPIToolkit.from_url(url, include_tags=["Works"], exclude_tags=["Admin"])
+
+# Filter by Operations
+toolkit = OpenAPIToolkit.from_url(
+    url, include_operations=["get_works"], exclude_operations=["delete_work"]
+)
+```
+
+---
+
+## Architecture Pipeline
+
+```text
+          Swagger 2.0 / OpenAPI 3.x
+                     │
+                     ▼
+            Swagger Normalizer
+                     │
+                     ▼
+          Normalized OpenAPI Model
+                     │
+                     ▼
+              Existing Parser
+                     │
+                     ▼
+           Internal Operation Models
+                     │
+                     ▼
+            Schema Converter
+                     │
+                     ▼
+              HTTP Executor
+                     │
+                     ▼
+          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"
+})
+
+```