langchain-openapi-tools 1.0.0__tar.gz

langchain_openapi_tools-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+name: Bug Report
+description: Create a report to help us fix a bug or unexpected behavior.
+title: "[BUG]: "
+labels: ["bug"]
+assignees: []
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: Clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior or code sample.
+      placeholder: |
+        from langchain_openapi import OpenAPIToolkit
+        toolkit = OpenAPIToolkit.from_url("...")
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, langchain-openapi version.
+      placeholder: |
+        - Python version: 3.11.0
+        - OS: Linux / macOS / Windows
+        - langchain-openapi version: 0.1.0
+    validations:
+      required: false

langchain_openapi_tools-1.0.0/.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,20 @@
+name: Documentation Improvement
+description: Suggest improvements or report errors in documentation.
+title: "[DOCS]: "
+labels: ["documentation"]
+assignees: []
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What section of the documentation needs improvement?
+    validations:
+      required: true
+  - type: textarea
+    id: content
+    attributes:
+      label: Suggested Changes
+      description: Describe the changes or corrections you would like to see.
+    validations:
+      required: true

langchain_openapi_tools-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+name: Feature Request
+description: Suggest an idea or enhancement for langchain-openapi.
+title: "[FEATURE]: "
+labels: ["enhancement"]
+assignees: []
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: Clear and concise description of what the problem is.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: Clear description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: Description of any alternative solutions or features considered.
+    validations:
+      required: false

langchain_openapi_tools-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Description
+
+Brief summary of the changes made in this pull request.
+
+## Related Issue
+
+Fixes #(issue_number)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change fixing an issue)
+- [ ] New feature (non-breaking change adding functionality)
+- [ ] Breaking change (fix or feature causing existing functionality to change)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] Code formatted with `uv run ruff format .`
+- [ ] Linting checked with `uv run ruff check .`
+- [ ] Static type checking passed with `uv run mypy langchain_openapi tests examples`
+- [ ] Tests passed with `uv run pytest`
+- [ ] Added/updated relevant unit or e2e tests

langchain_openapi_tools-1.0.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"

langchain_openapi_tools-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    name: Lint & Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Run Ruff (lint)
+        run: |
+          uv run ruff check .
+
+      - name: Run Ruff (format check)
+        run: |
+          uv run ruff format --check .
+
+      - name: Run MyPy (type check)
+        run: |
+          uv run mypy langchain_openapi tests examples
+
+      - name: Run Pytest
+        run: |
+          uv run pytest
+
+      - name: Build Documentation (MkDocs)
+        run: |
+          uv run mkdocs build
+
+  build-package:
+    name: Package Build & Twine Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build & twine
+        run: |
+          uv sync --extra dev
+
+      - name: Build distribution packages
+        run: |
+          uv run python -m build
+
+      - name: Check package artifacts with twine
+        run: |
+          uv run twine check dist/*

langchain_openapi_tools-1.0.0/.github/workflows/pages.yml

@@ -0,0 +1,32 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    name: Deploy MkDocs to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Deploy documentation to GitHub Pages
+        run: |
+          uv run mkdocs gh-deploy --force

langchain_openapi_tools-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Build sdist and wheel
+        run: |
+          uv run python -m build
+
+      - name: Check distribution artifacts
+        run: |
+          uv run twine check dist/*
+
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

langchain_openapi_tools-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: GitHub Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Build sdist and wheel
+        run: |
+          uv run python -m build
+
+      - name: Check distribution artifacts
+        run: |
+          uv run twine check dist/*
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false

langchain_openapi_tools-1.0.0/.gitignore

@@ -0,0 +1,91 @@
+# 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
+*.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.xml
+.hypothesis/
+.pytest_cache/
+pytestdebug.log
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# MyPy & Ruff cache
+.mypy_cache/
+.ruff_cache/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

langchain_openapi_tools-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.1
+    hooks:
+      - id: mypy
+        additional_dependencies: []

langchain_openapi_tools-1.0.0/ARCHITECTURE.md

@@ -0,0 +1,224 @@
+# `langchain-openapi` Architecture Specification
+
+This document details the planned software architecture for `langchain-openapi`.
+
+---
+
+## 1. Design Goals
+
+* **Framework Native**: Seamless integration with `langchain-core` tool interfaces (`BaseTool`), ensuring drop-in compatibility with LangChain agents and LangGraph workflows.
+* **Type Safety & Reliability**: Full static typing across the pipeline, converting OpenAPI definitions into strict Pydantic schemas to validate LLM tool calls before network invocation.
+* **Robust Spec Support**: Comprehensive parsing of OpenAPI v3.0 and v3.1 specifications, including complete parameter locations (path, query, header, cookie) and `$ref` schema resolution.
+* **Decoupled Architecture**: Clear separation of concerns between specification parsing, internal model representation, schema generation, and network execution.
+* **Security First**: Safe isolation of authentication credentials so API secrets are never exposed to LLM prompts or output logs.
+* **Extensibility**: Modular interfaces allowing custom HTTP transports, custom authentication handlers, and custom tool filtering strategies.
+
+---
+
+## 2. High-Level Architecture
+
+The library is structured as a linear transform pipeline with isolated responsibilities:
+
+```text
+ ┌────────────────────────────────────────────────────────┐
+ │                      OpenAPI Spec                      │
+ │                   (File / URL / Dict)                  │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                     OpenAPI Loader                     │
+ │          - Parsing (JSON / YAML)                       │
+ │          - Ref Resolution ($ref expansion)             │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                    Internal Models                     │
+ │          - Parsed Spec & Operation trees               │
+ │          - Schema normalization                        │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                   Schema Converter                     │
+ │          - JSON Schema ──► Pydantic Model              │
+ │          - Parameter & Body validation schemas         │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                     HTTP Executor                      │
+ │          - Async Transport (httpx)                     │
+ │          - Auth Injection                              │
+ │          - Request Serialization & Response Parsing    │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                     Tool Generator                     │
+ │          - langchain_core.tools.BaseTool Factory       │
+ │          - Selective filtering (tags, endpoints)       │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+ ┌────────────────────────────────────────────────────────┐
+ │                LangChain / Agent Loop                  │
+ └────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Core Components
+
+### 3.1 OpenAPI Loader
+
+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
+
+The **OpenAPI Parser** (`OpenAPIParser`) transforms an `OpenAPISpec` into strongly typed, normalized Python dataclasses using the `ReferenceResolver` for local `$ref` pointer resolution:
+
+```text
+OpenAPI Spec (File / URL / Dict)
+               │
+               ▼
+       [ OpenAPISpec ]
+               │
+               ▼
+      [ OpenAPIParser ] ◄── [ ReferenceResolver ($ref resolution) ]
+               │
+               ▼
+     [ Operation Models ]
+```
+
+#### Public Model Definitions
+
+* **`Operation`**: Represents a single executable API endpoint for a specific HTTP method (`name`, `method`, `path`, `summary`, `description`, `operation_id`, `tags`, `parameters`, `request_body`, `responses`, `deprecated`, `security`).
+* **`Parameter`**: Defines an input parameter supplied in a request (`name`, `location` [`path`, `query`, `header`, `cookie`], `required`, `description`, `schema`, `default`, `example`, `style`, `explode`).
+* **`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`).
+
+#### Current Scope Limitations
+
+The Milestone 3 parser intentionally skips:
+- Polymorphic composition keywords (`oneOf`, `anyOf`, `allOf`, `discriminator`).
+- OpenAPI callbacks, links, and webhooks.
+- Advanced example inheritance chains.
+
+### 3.3 Schema Converter
+
+The **Schema Converter** (`SchemaConverter` and `PydanticFactory`) converts internal schema models (`Schema`) into dynamic Pydantic `BaseModel` classes using `pydantic.create_model()`.
+
+```text
+OpenAPI Schema
+
+       │
+       ▼
+Internal Schema Model
+
+       │
+       ▼
+Dynamic Pydantic Model (type[BaseModel])
+```
+
+#### OpenAPI to Python / Pydantic Mapping Table
+
+| OpenAPI Type | Python / Pydantic Target Type | Notes / Examples |
+|---|---|---|
+| `string` | `str` | Includes optional field descriptions |
+| `integer` | `int` | Maps default values |
+| `number` | `float` | Supports floats |
+| `boolean` | `bool` | True / False |
+| `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`) |
+
+#### Model Naming Conventions
+
+* **Operation Models**: `{CamelCaseOperationName}Input` (e.g., `SearchWorksInput`).
+* **Nested Object Models**: `{ParentModel}_{CamelCaseFieldName}` (e.g., `SearchWorksInput_Address`).
+* **Dynamic Enums**: `{ParentModel}_{CamelCaseFieldName}Enum` (e.g., `SearchWorksInput_SortEnum`).
+
+#### Current Limitations
+
+The converter currently skips:
+- Polymorphic composition keywords (`oneOf`, `anyOf`, `allOf`, `discriminator`).
+- Recursive schemas.
+- XML schema options.
+- Complex union types beyond `Optional`.
+
+### 3.4 Async HTTP Executor Engine
+
+The **Async HTTP Executor** (`AsyncHTTPExecutor`) executes an `Operation` asynchronously using `httpx.AsyncClient`, transforming inputs into normalized `ResponseData` instances.
+
+```text
+Operation + Validated Arguments
+               │
+               ▼
+       [ RequestBuilder ]
+               │
+               ▼
+        [ AuthProvider ]
+               │
+               ▼
+     [ AsyncHTTPExecutor ] ──► ( httpx.AsyncClient )
+               │
+               ▼
+       [ ResponseParser ]
+               │
+               ▼
+          ResponseData
+```
+
+#### Key Architecture Components
+
+* **`RequestBuilder`**: Translates path, query, header, cookie, and JSON body parameters into a `BuiltRequest` object.
+* **`AuthProvider`**: Abstract interface (`NoAuth`, `BearerAuth`, `APIKeyHeaderAuth`, `APIKeyQueryAuth`, `BasicAuth`) for injecting security credentials.
+* **`ResponseParser`**: Normalizes HTTP response payloads into `ResponseData` (`status_code`, `headers`, `body`, `raw`), attempting JSON decoding with graceful plain text fallback.
+
+#### Exception Hierarchy
+
+```text
+OpenAPIError
+ └── HTTPExecutionError
+      ├── AuthenticationError
+      ├── RequestValidationError
+      ├── ResponseParsingError
+      └── ExecutionTimeoutError
+```
+
+### 3.5 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
+
+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.
+
+---
+
+## 4. Data Flow
+
+1. **Initialization**: The user passes an OpenAPI spec source (path, URL, or dict) to the `OpenAPIToolset` factory.
+2. **Ingestion & Parsing**: The `OpenAPI Loader` reads the spec, resolves reference pointers, and creates an immutable `OpenAPISpec` internal model.
+3. **Tool Creation**:
+   * For each selected operation in the specification, the `Schema Converter` builds a Pydantic input model (`args_schema`).
+   * The `Tool Generator` constructs a native `BaseTool` wrapping the operation metadata, input schema, and bound `HTTP Executor`.
+4. **Agent Invocation**:
+   * An LLM agent invokes the tool with generated JSON arguments.
+   * LangChain validates the arguments against the tool's Pydantic `args_schema`.
+   * The tool forwards validated parameters to the `HTTP Executor`.
+   * The `Authentication Provider` attaches necessary headers/credentials.
+   * The `HTTP Executor` performs the request asynchronously and returns formatted response content back to the agent.
+
+---
+
+## 5. Future Extensibility
+
+* **Custom Transport Adapters**: Ability to plug in alternative HTTP execution engines (e.g., custom `aiohttp` or enterprise proxy clients).
+* **Response Summarizers / Truncators**: Middleware hooks to format or summarize large API responses before returning them to LLM context windows.
+* **Custom Auth Handlers**: Support for enterprise authentication mechanisms like AWS SigV4 or custom HMAC header signing.
+* **GraphQL / gRPC Adapters**: Future extension of the tool generator interface to support multi-protocol tool synthesis alongside OpenAPI.

langchain_openapi_tools-1.0.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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).
+
+---
+
+## [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.