langchain-doccheap 0.1.0__tar.gz

langchain_doccheap-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

langchain_doccheap-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+First release: five LangChain tools for the doc.cheap API – scan a document,
+get, list and delete stored results, and read the account's usage – and a
+toolkit that returns them sharing one client.

langchain_doccheap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Document Cheap Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_doccheap-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: langchain-doccheap
+Version: 0.1.0
+Summary: LangChain tools for doc.cheap: read passports, ID cards and driver's licences into JSON.
+Project-URL: Homepage, https://doc.cheap
+Project-URL: Documentation, https://doc.cheap/docs
+Project-URL: Source, https://gitlab.com/doccheap/langchain-doccheap
+Project-URL: Changelog, https://gitlab.com/doccheap/langchain-doccheap/-/blob/main/CHANGELOG.md
+Author-email: Teoh Chin Heng <admin@doc.cheap>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: doc.cheap,document-recognition,id-card,kyc,langchain,mrz,ocr,passport,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: doc-cheap<1,>=0.1.0
+Requires-Dist: langchain-core<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: langchain-tests<2,>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: langchain-tests<2,>=1.0; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-doccheap
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-doccheap.svg)](https://pypi.org/project/langchain-doccheap/)
+
+[LangChain](https://python.langchain.com/) tools for
+[doc.cheap](https://doc.cheap): an agent gives them a photo or scan of a
+passport, national ID card or driving licence and gets back the printed fields –
+name, date of birth, document number, expiry, the machine-readable zone – as
+JSON.
+
+One recognised document costs one credit, $0.01. Registering gives 100 free
+documents every month. An unreadable image, an empty frame or an unsupported
+document type costs nothing, and every answer says whether it was billed.
+
+The package needs Python 3.10 or later. It is built on the
+[doc-cheap](https://pypi.org/project/doc-cheap/) client and `langchain-core` 1.x.
+
+## Installation
+
+```sh
+pip install langchain-doccheap
+```
+
+## The tools
+
+| Tool | Name the model sees | What it does |
+| --- | --- | --- |
+| `DocCheapScanDocument` | `doc_cheap_scan_document` | Reads one JPEG or PNG image, from `image_path` or `image_base64`, with an optional `reference` label and `expect_country` (ISO 3166-1 alpha-3). |
+| `DocCheapGetScan` | `doc_cheap_get_scan` | Returns a stored result by `scan_id`. |
+| `DocCheapListScans` | `doc_cheap_list_scans` | Returns one page of stored results (`limit`, `cursor`). |
+| `DocCheapDeleteScan` | `doc_cheap_delete_scan` | Deletes a stored result by `scan_id`. |
+| `DocCheapGetUsage` | `doc_cheap_get_usage` | Returns this month's free credits, the paid credits, the credits spent and the scan counters. |
+
+Every tool returns the API's answer as a JSON string. An API error – an unknown
+scan, a used-up rate limit, a wrong key – comes back to the model as a short
+text such as `doc.cheap error: 404 scan_not_found: …` instead of stopping the
+agent; pass `handle_tool_error=False` to have it raised as a `ToolException`.
+
+## Quick start
+
+```python
+from langchain_doccheap import DocCheapScanDocument
+
+scan = DocCheapScanDocument(api_key="sk_sandbox_public")
+print(scan.invoke({"image_path": "passport.jpg"}))
+```
+
+With an agent, take all five tools from the toolkit. They share one client and
+its connections:
+
+```python
+from langchain.agents import create_agent
+from langchain_doccheap import DocCheapToolkit
+
+tools = DocCheapToolkit().get_tools()  # reads DOC_CHEAP_API_KEY
+agent = create_agent("openai:gpt-4.1-mini", tools)
+agent.invoke({"messages": [{"role": "user", "content": "Read the passport in ./passport.jpg"}]})
+```
+
+`DocCheapToolkit(include_delete=False)` leaves out the tool that deletes stored
+results.
+
+## API keys
+
+- **Live key** – `sk_live_…`, created in the
+  [doc.cheap cabinet](https://doc.cheap/docs/concepts/api-keys-and-sessions).
+- **Sandbox key** – `sk_sandbox_public` works without an account. It gives 10
+  free recognised documents per address in all, and at most 10 requests per
+  address an hour, whatever their answer.
+
+Without `api_key` the tools read the key from the `DOC_CHEAP_API_KEY`
+environment variable. `base_url` (or `DOC_CHEAP_API_BASE`) points them at
+another address. To control timeouts, proxies or connection pooling, build a
+`doc_cheap.Client` yourself and pass it as `client=`; the tools leave it open.
+
+**Stored results.** A result is stored only when the scan was made with a live
+key under a non-zero retention window. Under the sandbox key nothing is stored,
+so getting or deleting a scan answers `scan_not_found`.
+
+## Resources
+
+- [doc.cheap documentation](https://doc.cheap/docs)
+- [Your first recognition](https://doc.cheap/docs/start/first-recognition)
+- [API reference](https://doc.cheap/docs/reference)
+- [The doc-cheap Python client](https://pypi.org/project/doc-cheap/)
+
+## License
+
+[MIT](LICENSE)

langchain_doccheap-0.1.0/README.md

@@ -0,0 +1,89 @@
+# langchain-doccheap
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-doccheap.svg)](https://pypi.org/project/langchain-doccheap/)
+
+[LangChain](https://python.langchain.com/) tools for
+[doc.cheap](https://doc.cheap): an agent gives them a photo or scan of a
+passport, national ID card or driving licence and gets back the printed fields –
+name, date of birth, document number, expiry, the machine-readable zone – as
+JSON.
+
+One recognised document costs one credit, $0.01. Registering gives 100 free
+documents every month. An unreadable image, an empty frame or an unsupported
+document type costs nothing, and every answer says whether it was billed.
+
+The package needs Python 3.10 or later. It is built on the
+[doc-cheap](https://pypi.org/project/doc-cheap/) client and `langchain-core` 1.x.
+
+## Installation
+
+```sh
+pip install langchain-doccheap
+```
+
+## The tools
+
+| Tool | Name the model sees | What it does |
+| --- | --- | --- |
+| `DocCheapScanDocument` | `doc_cheap_scan_document` | Reads one JPEG or PNG image, from `image_path` or `image_base64`, with an optional `reference` label and `expect_country` (ISO 3166-1 alpha-3). |
+| `DocCheapGetScan` | `doc_cheap_get_scan` | Returns a stored result by `scan_id`. |
+| `DocCheapListScans` | `doc_cheap_list_scans` | Returns one page of stored results (`limit`, `cursor`). |
+| `DocCheapDeleteScan` | `doc_cheap_delete_scan` | Deletes a stored result by `scan_id`. |
+| `DocCheapGetUsage` | `doc_cheap_get_usage` | Returns this month's free credits, the paid credits, the credits spent and the scan counters. |
+
+Every tool returns the API's answer as a JSON string. An API error – an unknown
+scan, a used-up rate limit, a wrong key – comes back to the model as a short
+text such as `doc.cheap error: 404 scan_not_found: …` instead of stopping the
+agent; pass `handle_tool_error=False` to have it raised as a `ToolException`.
+
+## Quick start
+
+```python
+from langchain_doccheap import DocCheapScanDocument
+
+scan = DocCheapScanDocument(api_key="sk_sandbox_public")
+print(scan.invoke({"image_path": "passport.jpg"}))
+```
+
+With an agent, take all five tools from the toolkit. They share one client and
+its connections:
+
+```python
+from langchain.agents import create_agent
+from langchain_doccheap import DocCheapToolkit
+
+tools = DocCheapToolkit().get_tools()  # reads DOC_CHEAP_API_KEY
+agent = create_agent("openai:gpt-4.1-mini", tools)
+agent.invoke({"messages": [{"role": "user", "content": "Read the passport in ./passport.jpg"}]})
+```
+
+`DocCheapToolkit(include_delete=False)` leaves out the tool that deletes stored
+results.
+
+## API keys
+
+- **Live key** – `sk_live_…`, created in the
+  [doc.cheap cabinet](https://doc.cheap/docs/concepts/api-keys-and-sessions).
+- **Sandbox key** – `sk_sandbox_public` works without an account. It gives 10
+  free recognised documents per address in all, and at most 10 requests per
+  address an hour, whatever their answer.
+
+Without `api_key` the tools read the key from the `DOC_CHEAP_API_KEY`
+environment variable. `base_url` (or `DOC_CHEAP_API_BASE`) points them at
+another address. To control timeouts, proxies or connection pooling, build a
+`doc_cheap.Client` yourself and pass it as `client=`; the tools leave it open.
+
+**Stored results.** A result is stored only when the scan was made with a live
+key under a non-zero retention window. Under the sandbox key nothing is stored,
+so getting or deleting a scan answers `scan_not_found`.
+
+## Resources
+
+- [doc.cheap documentation](https://doc.cheap/docs)
+- [Your first recognition](https://doc.cheap/docs/start/first-recognition)
+- [API reference](https://doc.cheap/docs/reference)
+- [The doc-cheap Python client](https://pypi.org/project/doc-cheap/)
+
+## License
+
+[MIT](LICENSE)

langchain_doccheap-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-doccheap"
+version = "0.1.0"
+description = "LangChain tools for doc.cheap: read passports, ID cards and driver's licences into JSON."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Teoh Chin Heng", email = "admin@doc.cheap" }]
+keywords = ["langchain", "tools", "ocr", "passport", "id-card", "mrz", "document-recognition", "kyc", "doc.cheap"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["doc-cheap>=0.1.0,<1", "langchain-core>=1.0,<2"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-cov>=5", "langchain-tests>=1.0,<2"]
+dev = ["pytest>=8", "pytest-cov>=5", "langchain-tests>=1.0,<2", "ruff>=0.6", "mypy>=1.11"]
+
+[project.urls]
+Homepage = "https://doc.cheap"
+Documentation = "https://doc.cheap/docs"
+Source = "https://gitlab.com/doccheap/langchain-doccheap"
+Changelog = "https://gitlab.com/doccheap/langchain-doccheap/-/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_doccheap"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/langchain_doccheap", "tests", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.coverage.run]
+branch = true
+source = ["langchain_doccheap"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["langchain_doccheap"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests"]

langchain_doccheap-0.1.0/src/langchain_doccheap/__init__.py

@@ -0,0 +1,29 @@
+"""LangChain tools for the doc.cheap document-recognition API."""
+
+from ._version import __version__
+from .toolkit import DocCheapToolkit
+from .tools import (
+    DocCheapDeleteScan,
+    DocCheapGetScan,
+    DocCheapGetUsage,
+    DocCheapListScans,
+    DocCheapScanDocument,
+    ListScansInput,
+    ScanDocumentInput,
+    ScanIdInput,
+    UsageInput,
+)
+
+__all__ = [
+    "DocCheapDeleteScan",
+    "DocCheapGetScan",
+    "DocCheapGetUsage",
+    "DocCheapListScans",
+    "DocCheapScanDocument",
+    "DocCheapToolkit",
+    "ListScansInput",
+    "ScanDocumentInput",
+    "ScanIdInput",
+    "UsageInput",
+    "__version__",
+]

langchain_doccheap-0.1.0/src/langchain_doccheap/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

langchain_doccheap-0.1.0/src/langchain_doccheap/toolkit.py

@@ -0,0 +1,56 @@
+"""All doc.cheap tools behind one client."""
+
+from __future__ import annotations
+
+from doc_cheap import API_KEY_ENV, Client
+from langchain_core.tools import BaseTool, BaseToolkit
+from langchain_core.utils import secret_from_env
+from pydantic import ConfigDict, Field, PrivateAttr, SecretStr
+
+from .tools import (
+    _USER_AGENT,
+    DocCheapDeleteScan,
+    DocCheapGetScan,
+    DocCheapGetUsage,
+    DocCheapListScans,
+    DocCheapScanDocument,
+)
+
+
+class DocCheapToolkit(BaseToolkit):
+    """The five doc.cheap tools, sharing one client and its connections.
+
+    The API key is the ``api_key`` argument, else the ``DOC_CHEAP_API_KEY``
+    environment variable. Pass ``include_delete=False`` to leave out the tool
+    that deletes stored results.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    api_key: SecretStr | None = Field(default_factory=secret_from_env(API_KEY_ENV, default=None))
+    base_url: str | None = None
+    client: Client | None = Field(default=None, exclude=True)
+    include_delete: bool = True
+
+    _owned_client: Client | None = PrivateAttr(default=None)
+
+    def _shared_client(self) -> Client:
+        if self.client is not None:
+            return self.client
+        if self._owned_client is None:
+            key = self.api_key.get_secret_value() if self.api_key is not None else None
+            self._owned_client = Client(key, base_url=self.base_url, user_agent=_USER_AGENT)
+        return self._owned_client
+
+    def get_tools(self) -> list[BaseTool]:
+        """Returns the tools, all sending their requests through one client."""
+        client = self._shared_client()
+        tools: list[BaseTool] = [
+            DocCheapScanDocument(client=client),
+            DocCheapGetScan(client=client),
+            DocCheapListScans(client=client),
+            DocCheapGetUsage(client=client),
+        ]
+        if self.include_delete:
+            tools.append(DocCheapDeleteScan(client=client))
+        return tools

langchain_doccheap-0.1.0/src/langchain_doccheap/tools.py

@@ -0,0 +1,207 @@
+"""LangChain tools that call the doc.cheap document-recognition API."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from doc_cheap import API_KEY_ENV, Client, DocCheapError
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool, ToolException
+from langchain_core.utils import secret_from_env
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, SecretStr, model_validator
+
+from ._version import __version__
+
+_USER_AGENT = f"langchain-doccheap/{__version__}"
+
+
+def _to_json(value: Any) -> str:
+    # Tool output goes back to a chat model as text, so the API's JSON answer
+    # is passed through as JSON rather than as a Python repr.
+    return json.dumps(value, ensure_ascii=False)
+
+
+class _DocCheapTool(BaseTool):
+    """Shared configuration of the doc.cheap tools.
+
+    The API key is the ``api_key`` argument, else the ``DOC_CHEAP_API_KEY``
+    environment variable. A ``client`` passed in is used as given and stays
+    the caller's to close; otherwise the tool creates one on first use.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    api_key: SecretStr | None = Field(default_factory=secret_from_env(API_KEY_ENV, default=None))
+    """The doc.cheap API key; ``sk_sandbox_public`` works without an account."""
+
+    base_url: str | None = None
+    """The API address; the client's default when omitted."""
+
+    client: Client | None = Field(default=None, exclude=True)
+    """A ready ``doc_cheap.Client`` to send the requests through."""
+
+    _owned_client: Client | None = PrivateAttr(default=None)
+
+    def __init__(self, **kwargs: Any) -> None:
+        # An API error goes back to the model as the tool's answer, so an
+        # agent can react to it, unless the caller chose otherwise.
+        kwargs.setdefault("handle_tool_error", True)
+        super().__init__(**kwargs)
+
+    def _client(self) -> Client:
+        if self.client is not None:
+            return self.client
+        if self._owned_client is None:
+            key = self.api_key.get_secret_value() if self.api_key is not None else None
+            self._owned_client = Client(key, base_url=self.base_url, user_agent=_USER_AGENT)
+        return self._owned_client
+
+    def _call(self, operation: str, **kwargs: Any) -> str:
+        try:
+            result = getattr(self._client(), operation)(**kwargs)
+        except DocCheapError as err:
+            raise ToolException(f"doc.cheap error: {err}") from err
+        return _to_json(result)
+
+
+class ScanDocumentInput(BaseModel):
+    """Arguments of :class:`DocCheapScanDocument`."""
+
+    image_path: str | None = Field(
+        default=None,
+        description="Path of a local JPEG or PNG file holding the document.",
+    )
+    image_base64: str | None = Field(
+        default=None,
+        description="The JPEG or PNG image as base64 text, with or without a data: prefix.",
+    )
+    reference: str | None = Field(
+        default=None,
+        max_length=128,
+        description="An optional label of your own, stored with the result.",
+    )
+    expect_country: str | None = Field(
+        default=None,
+        pattern=r"^[A-Z]{3}$",
+        description="Optional ISO 3166-1 alpha-3 code of the issuing country, e.g. GBR.",
+    )
+
+    @model_validator(mode="after")
+    def _one_image(self) -> ScanDocumentInput:
+        if (self.image_path is None) == (self.image_base64 is None):
+            raise ValueError("give exactly one of image_path or image_base64")
+        return self
+
+
+class DocCheapScanDocument(_DocCheapTool):
+    """Reads a passport, national ID card or driving licence into JSON."""
+
+    name: str = "doc_cheap_scan_document"
+    description: str = (
+        "Reads a photo or scan of a passport, national ID card or driving licence "
+        "and returns the printed fields (name, date of birth, document number, "
+        "expiry, machine-readable zone) as JSON. Give image_path or image_base64. "
+        "One recognised document costs one credit; an image with no readable "
+        "document costs nothing and comes back with billed set to false."
+    )
+    args_schema: type[BaseModel] = ScanDocumentInput
+
+    def _run(
+        self,
+        image_path: str | None = None,
+        image_base64: str | None = None,
+        reference: str | None = None,
+        expect_country: str | None = None,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        return self._call(
+            "recognize",
+            path=image_path,
+            image_base64=image_base64,
+            reference=reference,
+            expect_country=expect_country,
+        )
+
+
+class ScanIdInput(BaseModel):
+    """Arguments of the tools that act on one stored scan."""
+
+    scan_id: str = Field(min_length=1, description="The id of a scan, as returned by a scan.")
+
+
+class DocCheapGetScan(_DocCheapTool):
+    """Returns a stored scan result."""
+
+    name: str = "doc_cheap_get_scan"
+    description: str = (
+        "Returns a stored doc.cheap scan result by its id, as JSON. Results are "
+        "stored only for live keys with a retention window. Costs nothing."
+    )
+    args_schema: type[BaseModel] = ScanIdInput
+
+    def _run(self, scan_id: str, run_manager: CallbackManagerForToolRun | None = None) -> str:
+        return self._call("get_scan", scan_id=scan_id)
+
+
+class ListScansInput(BaseModel):
+    """Arguments of :class:`DocCheapListScans`."""
+
+    limit: int | None = Field(
+        default=None, ge=1, le=100, description="How many results to return, 1 to 100."
+    )
+    cursor: str | None = Field(
+        default=None,
+        max_length=256,
+        description="The next_cursor value of the previous page, for the next page.",
+    )
+
+
+class DocCheapListScans(_DocCheapTool):
+    """Lists stored scan results, newest first."""
+
+    name: str = "doc_cheap_list_scans"
+    description: str = (
+        "Lists stored doc.cheap scan results, newest first, as JSON with a "
+        "next_cursor for the next page. Costs nothing."
+    )
+    args_schema: type[BaseModel] = ListScansInput
+
+    def _run(
+        self,
+        limit: int | None = None,
+        cursor: str | None = None,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        return self._call("list_scans", limit=limit, cursor=cursor)
+
+
+class DocCheapDeleteScan(_DocCheapTool):
+    """Deletes a stored scan result."""
+
+    name: str = "doc_cheap_delete_scan"
+    description: str = (
+        "Deletes a stored doc.cheap scan result by its id. It cannot be undone. Costs nothing."
+    )
+    args_schema: type[BaseModel] = ScanIdInput
+
+    def _run(self, scan_id: str, run_manager: CallbackManagerForToolRun | None = None) -> str:
+        return self._call("delete_scan", scan_id=scan_id)
+
+
+class UsageInput(BaseModel):
+    """The usage tool takes no arguments."""
+
+
+class DocCheapGetUsage(_DocCheapTool):
+    """Returns the account's credits and scan counters."""
+
+    name: str = "doc_cheap_get_usage"
+    description: str = (
+        "Returns this month's free doc.cheap credits, the paid credits, the "
+        "credits spent and the scan counters, as JSON. Costs nothing."
+    )
+    args_schema: type[BaseModel] = UsageInput
+
+    def _run(self, run_manager: CallbackManagerForToolRun | None = None) -> str:
+        return self._call("usage")

langchain_doccheap-0.1.0/tests/conftest.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+import pytest
+from doc_cheap import Client
+
+
+class Recorder:
+    """Answers every request with a queued response and remembers the requests."""
+
+    def __init__(self) -> None:
+        self.requests: list[httpx.Request] = []
+        self.responses: list[httpx.Response] = []
+
+    def queue(self, status: int, body: Any) -> None:
+        self.responses.append(httpx.Response(status, json=body))
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return self.responses.pop(0)
+
+    def body(self, index: int = -1) -> Any:
+        return json.loads(self.requests[index].content)
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("DOC_CHEAP_API_KEY", raising=False)
+    monkeypatch.delenv("DOC_CHEAP_API_BASE", raising=False)
+
+
+@pytest.fixture
+def recorder() -> Recorder:
+    return Recorder()
+
+
+@pytest.fixture
+def client(recorder: Recorder) -> Iterator[Client]:
+    http = httpx.Client(transport=httpx.MockTransport(recorder))
+    with Client("sk_test_key", base_url="https://api.test", http_client=http) as c:
+        yield c
+    http.close()

langchain_doccheap-0.1.0/tests/test_standard.py

@@ -0,0 +1,78 @@
+"""LangChain's own standard checks for a tool package."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.tools import BaseTool
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_doccheap import (
+    DocCheapDeleteScan,
+    DocCheapGetScan,
+    DocCheapGetUsage,
+    DocCheapListScans,
+    DocCheapScanDocument,
+)
+
+_ENV: tuple[dict[str, str], dict[str, Any], dict[str, Any]] = (
+    {"DOC_CHEAP_API_KEY": "sk_env_key"},
+    {},
+    {"api_key": "sk_env_key"},
+)
+
+
+class _Base(ToolsUnitTests):
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"api_key": "sk_test_key"}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict[str, str], dict[str, Any], dict[str, Any]]:
+        return _ENV
+
+
+class TestScanDocument(_Base):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return DocCheapScanDocument
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"image_base64": "aGVsbG8=", "expect_country": "GBR"}
+
+
+class TestGetScan(_Base):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return DocCheapGetScan
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"scan_id": "scn_1"}
+
+
+class TestListScans(_Base):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return DocCheapListScans
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"limit": 10}
+
+
+class TestDeleteScan(_Base):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return DocCheapDeleteScan
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"scan_id": "scn_1"}
+
+
+class TestGetUsage(_Base):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return DocCheapGetUsage

langchain_doccheap-0.1.0/tests/test_tools.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+from doc_cheap import Client
+from langchain_core.tools import ToolException
+from pydantic import SecretStr, ValidationError
+
+from langchain_doccheap import (
+    DocCheapDeleteScan,
+    DocCheapGetScan,
+    DocCheapGetUsage,
+    DocCheapListScans,
+    DocCheapScanDocument,
+    DocCheapToolkit,
+    ScanDocumentInput,
+    __version__,
+)
+
+from .conftest import Recorder
+
+SCAN = {"id": "scn_1", "meta": {"status": "unsupported_document", "billed": False}}
+ERROR = {"error": {"code": "scan_not_found", "message": "No such scan.", "request_id": "req_1"}}
+
+
+def test_scan_from_base64_sends_the_image_and_returns_json(
+    client: Client, recorder: Recorder
+) -> None:
+    recorder.queue(201, SCAN)
+    tool = DocCheapScanDocument(client=client)
+    out = tool.invoke({"image_base64": "aGVsbG8=", "reference": "case-7", "expect_country": "GBR"})
+    assert json.loads(out) == SCAN
+    request = recorder.requests[0]
+    assert request.method == "POST"
+    assert request.url.path == "/v1/scans"
+    assert recorder.body() == {
+        "image": "aGVsbG8=",
+        "reference": "case-7",
+        "options": {"expect_country": "GBR"},
+    }
+
+
+def test_scan_from_path_reads_the_file(client: Client, recorder: Recorder, tmp_path: Path) -> None:
+    image = tmp_path / "doc.png"
+    image.write_bytes(b"\x89PNG-bytes")
+    recorder.queue(201, SCAN)
+    DocCheapScanDocument(client=client).invoke({"image_path": str(image)})
+    assert recorder.body() == {"image": base64.b64encode(b"\x89PNG-bytes").decode()}
+
+
+@pytest.mark.parametrize(
+    "args",
+    [{}, {"image_path": "a.png", "image_base64": "aGVsbG8="}],
+)
+def test_scan_needs_exactly_one_image(args: dict[str, str]) -> None:
+    with pytest.raises(ValidationError, match="exactly one of image_path or image_base64"):
+        ScanDocumentInput(**args)
+
+
+def test_scan_input_refuses_a_bad_country() -> None:
+    with pytest.raises(ValidationError):
+        ScanDocumentInput(image_base64="aGVsbG8=", expect_country="gb")
+
+
+def test_get_scan(client: Client, recorder: Recorder) -> None:
+    recorder.queue(200, SCAN)
+    out = DocCheapGetScan(client=client).invoke({"scan_id": "scn_1"})
+    assert json.loads(out) == SCAN
+    assert recorder.requests[0].url.path == "/v1/scans/scn_1"
+
+
+def test_list_scans_passes_limit_and_cursor(client: Client, recorder: Recorder) -> None:
+    page: dict[str, object] = {"scans": [], "next_cursor": None}
+    recorder.queue(200, page)
+    out = DocCheapListScans(client=client).invoke({"limit": 5, "cursor": "c1"})
+    assert json.loads(out) == page
+    params = recorder.requests[0].url.params
+    assert params["limit"] == "5"
+    assert params["cursor"] == "c1"
+
+
+def test_list_scans_without_arguments(client: Client, recorder: Recorder) -> None:
+    recorder.queue(200, {"scans": [], "next_cursor": None})
+    DocCheapListScans(client=client).invoke({})
+    assert str(recorder.requests[0].url) == "https://api.test/v1/scans"
+
+
+def test_delete_scan(client: Client, recorder: Recorder) -> None:
+    recorder.queue(200, {"id": "scn_1", "deleted": True})
+    out = DocCheapDeleteScan(client=client).invoke({"scan_id": "scn_1"})
+    assert json.loads(out) == {"id": "scn_1", "deleted": True}
+    assert recorder.requests[0].method == "DELETE"
+
+
+def test_usage(client: Client, recorder: Recorder) -> None:
+    usage = {"free_allowance": {"remaining": 100}}
+    recorder.queue(200, usage)
+    out = DocCheapGetUsage(client=client).invoke({})
+    assert json.loads(out) == usage
+    assert recorder.requests[0].url.path == "/v1/usage"
+
+
+def test_api_error_is_returned_to_the_model_as_text(client: Client, recorder: Recorder) -> None:
+    recorder.queue(404, ERROR)
+    out = DocCheapGetScan(client=client).invoke({"scan_id": "scn_x"})
+    assert out == "doc.cheap error: 404 scan_not_found: No such scan."
+
+
+def test_api_error_is_raised_when_handling_is_off(client: Client, recorder: Recorder) -> None:
+    recorder.queue(404, ERROR)
+    tool = DocCheapGetScan(client=client, handle_tool_error=False)
+    with pytest.raises(ToolException, match="scan_not_found"):
+        tool.invoke({"scan_id": "scn_x"})
+
+
+def test_missing_key_is_reported_not_raised() -> None:
+    out = DocCheapGetUsage().invoke({})
+    assert "no API key" in out
+    assert "sk_sandbox_public" in out
+
+
+def test_tool_creates_its_own_client_once(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return httpx.Response(200, json={})
+
+    transport = httpx.MockTransport(handler)
+    original = httpx.Client.__init__
+
+    def patched(self: httpx.Client, *args: object, **kwargs: object) -> None:
+        kwargs["transport"] = transport
+        original(self, *args, **kwargs)  # type: ignore[arg-type]
+
+    monkeypatch.setattr(httpx.Client, "__init__", patched)
+    monkeypatch.setenv("DOC_CHEAP_API_KEY", "sk_env_key")
+    tool = DocCheapGetUsage(base_url="https://api.example")
+    tool.invoke({})
+    tool.invoke({})
+    assert len(seen) == 2
+    assert seen[0].headers["authorization"] == "Bearer sk_env_key"
+    assert str(seen[0].url) == "https://api.example/v1/usage"
+    assert seen[0].headers["user-agent"].startswith(f"langchain-doccheap/{__version__} ")
+
+
+def test_toolkit_shares_the_given_client(client: Client) -> None:
+    tools = DocCheapToolkit(client=client).get_tools()
+    assert [t.name for t in tools] == [
+        "doc_cheap_scan_document",
+        "doc_cheap_get_scan",
+        "doc_cheap_list_scans",
+        "doc_cheap_get_usage",
+        "doc_cheap_delete_scan",
+    ]
+    assert all(getattr(t, "client", None) is client for t in tools)
+
+
+def test_toolkit_can_leave_out_delete() -> None:
+    tools = DocCheapToolkit(api_key=SecretStr("sk_test_key"), include_delete=False).get_tools()
+    assert "doc_cheap_delete_scan" not in [t.name for t in tools]
+    clients = {id(getattr(t, "client", None)) for t in tools}
+    assert len(clients) == 1
+
+
+def test_toolkit_creates_its_client_once() -> None:
+    toolkit = DocCheapToolkit(api_key=SecretStr("sk_test_key"), base_url="https://api.example")
+    first = toolkit.get_tools()[0]
+    second = toolkit.get_tools()[0]
+    assert getattr(first, "client", None) is getattr(second, "client", None)
+    assert getattr(first, "client").base_url == "https://api.example"  # noqa: B009