langchain-brewpage 0.1.0__tar.gz

langchain_brewpage-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

langchain_brewpage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Kochetkov
+
+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_brewpage-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: langchain-brewpage
+Version: 0.1.0
+Summary: LangChain tools for BrewPage: publish HTML, Markdown, JSON, KV stores and files to brewpage.app and get a shareable URL.
+Project-URL: Homepage, https://brewpage.app
+Project-URL: Repository, https://github.com/kochetkov-ma/langchain-brewpage
+Project-URL: Issues, https://github.com/kochetkov-ma/langchain-brewpage/issues
+Project-URL: Documentation, https://github.com/kochetkov-ma/langchain-brewpage#readme
+Author-email: Maksim Kochetkov <apmatypa88@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,brewpage,hosting,langchain,publish,tools
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx==0.28.1
+Requires-Dist: langchain-core==1.7.6
+Description-Content-Type: text/markdown
+
+# langchain-brewpage
+
+LangChain tools for [BrewPage](https://brewpage.app): let an agent publish an HTML page, a Markdown document, a JSON document, a key-value store or a file and get back a shareable URL. No account and no API key are needed.
+
+Each call returns the URL plus an owner token. The toolkit reuses that token for later publications, so everything the agent creates belongs to one owner. Publications are private and unlisted by default and expire after 15 days unless you set `ttl_days` (1-30).
+
+## Install
+
+```bash
+pip install langchain-brewpage
+```
+
+## Tools
+
+| Tool | API | Use |
+|---|---|---|
+| `BrewPagePublishPageTool` (`brewpage_publish_page`) | `POST /api/html` | HTML or Markdown page -> URL |
+| `BrewPagePublishJsonTool` (`brewpage_publish_json`) | `POST /api/json` | JSON document -> URL |
+| `BrewPageCreateKvStoreTool` (`brewpage_create_kv_store`) | `POST /api/kv` | Key-value store with one initial key -> URL |
+| `BrewPageUploadFileTool` (`brewpage_upload_file`) | `POST /api/files` | Local file -> download or page URL |
+
+`BrewPageToolkit` returns all four tools, sharing one client.
+
+Every tool also accepts `ttl_days`, `password` and `namespace`. Leave `namespace` empty for a private link. `public` lists pages in the public gallery and search engines, so never put secrets or personal data there.
+
+## Usage
+
+```python
+from langchain_brewpage import BrewPageToolkit
+
+tools = BrewPageToolkit().get_tools()
+page = tools[0].invoke({"content": "# Weekly report\n\nAll green.", "format": "markdown"})
+print(page["url"], page["owner_token"])
+```
+
+With an agent:
+
+```python
+from langchain.agents import create_agent
+from langchain_brewpage import BrewPageToolkit
+
+agent = create_agent(model, tools=BrewPageToolkit().get_tools())  # any tool-calling chat model
+agent.invoke({"messages": [{"role": "user", "content": "Write a one-page HTML changelog and publish it."}]})
+```
+
+The result of each tool is a dict: `url`, `id`, `namespace`, `owner_token`, `management_link`, `expires_at`.
+
+## Configuration
+
+| Setting | Constructor | Environment |
+|---|---|---|
+| API base URL | `BrewPageClient(base_url=...)` | `BREWPAGE_BASE_URL` (default `https://brewpage.app`) |
+| Owner token to reuse | `BrewPageClient(owner_token=...)` | `BREWPAGE_OWNER_TOKEN` |
+| Default namespace | `BrewPageClient(namespace=...)` | `BREWPAGE_NAMESPACE` |
+
+```python
+from langchain_brewpage import BrewPageClient, BrewPageToolkit
+
+toolkit = BrewPageToolkit(client=BrewPageClient(owner_token="..."))
+```
+
+API errors (rate limits, refused content) come back to the agent as tool messages instead of exceptions.
+
+## Links
+
+- API reference: https://kochetkov-ma.github.io/brewpage-openapi/
+- OpenAPI contract: https://github.com/kochetkov-ma/brewpage-openapi
+- Limits and terms: https://brewpage.app
+
+## Development
+
+```bash
+uv sync --group test
+uv run pytest
+BREWPAGE_LIVE=1 uv run pytest -m live   # one private page on production
+```
+
+## License
+
+MIT

langchain_brewpage-0.1.0/README.md

@@ -0,0 +1,80 @@
+# langchain-brewpage
+
+LangChain tools for [BrewPage](https://brewpage.app): let an agent publish an HTML page, a Markdown document, a JSON document, a key-value store or a file and get back a shareable URL. No account and no API key are needed.
+
+Each call returns the URL plus an owner token. The toolkit reuses that token for later publications, so everything the agent creates belongs to one owner. Publications are private and unlisted by default and expire after 15 days unless you set `ttl_days` (1-30).
+
+## Install
+
+```bash
+pip install langchain-brewpage
+```
+
+## Tools
+
+| Tool | API | Use |
+|---|---|---|
+| `BrewPagePublishPageTool` (`brewpage_publish_page`) | `POST /api/html` | HTML or Markdown page -> URL |
+| `BrewPagePublishJsonTool` (`brewpage_publish_json`) | `POST /api/json` | JSON document -> URL |
+| `BrewPageCreateKvStoreTool` (`brewpage_create_kv_store`) | `POST /api/kv` | Key-value store with one initial key -> URL |
+| `BrewPageUploadFileTool` (`brewpage_upload_file`) | `POST /api/files` | Local file -> download or page URL |
+
+`BrewPageToolkit` returns all four tools, sharing one client.
+
+Every tool also accepts `ttl_days`, `password` and `namespace`. Leave `namespace` empty for a private link. `public` lists pages in the public gallery and search engines, so never put secrets or personal data there.
+
+## Usage
+
+```python
+from langchain_brewpage import BrewPageToolkit
+
+tools = BrewPageToolkit().get_tools()
+page = tools[0].invoke({"content": "# Weekly report\n\nAll green.", "format": "markdown"})
+print(page["url"], page["owner_token"])
+```
+
+With an agent:
+
+```python
+from langchain.agents import create_agent
+from langchain_brewpage import BrewPageToolkit
+
+agent = create_agent(model, tools=BrewPageToolkit().get_tools())  # any tool-calling chat model
+agent.invoke({"messages": [{"role": "user", "content": "Write a one-page HTML changelog and publish it."}]})
+```
+
+The result of each tool is a dict: `url`, `id`, `namespace`, `owner_token`, `management_link`, `expires_at`.
+
+## Configuration
+
+| Setting | Constructor | Environment |
+|---|---|---|
+| API base URL | `BrewPageClient(base_url=...)` | `BREWPAGE_BASE_URL` (default `https://brewpage.app`) |
+| Owner token to reuse | `BrewPageClient(owner_token=...)` | `BREWPAGE_OWNER_TOKEN` |
+| Default namespace | `BrewPageClient(namespace=...)` | `BREWPAGE_NAMESPACE` |
+
+```python
+from langchain_brewpage import BrewPageClient, BrewPageToolkit
+
+toolkit = BrewPageToolkit(client=BrewPageClient(owner_token="..."))
+```
+
+API errors (rate limits, refused content) come back to the agent as tool messages instead of exceptions.
+
+## Links
+
+- API reference: https://kochetkov-ma.github.io/brewpage-openapi/
+- OpenAPI contract: https://github.com/kochetkov-ma/brewpage-openapi
+- Limits and terms: https://brewpage.app
+
+## Development
+
+```bash
+uv sync --group test
+uv run pytest
+BREWPAGE_LIVE=1 uv run pytest -m live   # one private page on production
+```
+
+## License
+
+MIT

langchain_brewpage-0.1.0/langchain_brewpage/__init__.py

@@ -0,0 +1,20 @@
+"""LangChain integration for BrewPage: publish HTML, Markdown, JSON, KV and files, get a URL."""
+
+from langchain_brewpage.client import BrewPageClient, BrewPageError
+from langchain_brewpage.tools import (
+    BrewPageCreateKvStoreTool,
+    BrewPagePublishJsonTool,
+    BrewPagePublishPageTool,
+    BrewPageToolkit,
+    BrewPageUploadFileTool,
+)
+
+__all__ = [
+    "BrewPageClient",
+    "BrewPageError",
+    "BrewPageCreateKvStoreTool",
+    "BrewPagePublishJsonTool",
+    "BrewPagePublishPageTool",
+    "BrewPageToolkit",
+    "BrewPageUploadFileTool",
+]

langchain_brewpage-0.1.0/langchain_brewpage/client.py

@@ -0,0 +1,88 @@
+"""Minimal synchronous client for the public BrewPage API (https://brewpage.app)."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://brewpage.app"
+USER_AGENT = "langchain-brewpage/0.1.0"
+
+
+class BrewPageError(RuntimeError):
+    """Raised when the BrewPage API answers with a non-2xx status."""
+
+
+class BrewPageClient:
+    """Publishes pages, JSON, KV stores and files; reuses one owner token for all of them."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        owner_token: Optional[str] = None,
+        namespace: Optional[str] = None,
+        timeout: float = 60.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get("BREWPAGE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.owner_token = owner_token or os.environ.get("BREWPAGE_OWNER_TOKEN") or None
+        self.namespace = namespace or os.environ.get("BREWPAGE_NAMESPACE") or None
+        self._http = httpx.Client(timeout=timeout, transport=transport, headers={"User-Agent": USER_AGENT})
+
+    def publish_page(self, content: str, format: str = "html", ttl_days: Optional[int] = None,
+                     password: Optional[str] = None, namespace: Optional[str] = None) -> Dict[str, Any]:
+        body = {"content": content, "format": format}
+        return self._post("/api/html", namespace, ttl_days, password, json_body=body)
+
+    def publish_json(self, data: Any, ttl_days: Optional[int] = None, password: Optional[str] = None,
+                     namespace: Optional[str] = None) -> Dict[str, Any]:
+        return self._post("/api/json", namespace, ttl_days, password, json_body=data)
+
+    def create_kv_store(self, key: str, value: str, ttl_days: Optional[int] = None,
+                        password: Optional[str] = None, namespace: Optional[str] = None) -> Dict[str, Any]:
+        return self._post("/api/kv", namespace, ttl_days, password, json_body={"key": key, "value": value})
+
+    def upload_file(self, path: str, ttl_days: Optional[int] = None, password: Optional[str] = None,
+                    namespace: Optional[str] = None) -> Dict[str, Any]:
+        file = Path(path)
+        mime = mimetypes.guess_type(file.name)[0] or "application/octet-stream"
+        files = {"file": (file.name, file.read_bytes(), mime)}
+        return self._post("/api/files", namespace, ttl_days, password, files=files)
+
+    def _post(self, path: str, namespace: Optional[str], ttl_days: Optional[int], password: Optional[str],
+              json_body: Any = None, files: Any = None) -> Dict[str, Any]:
+        params = {}
+        ns = namespace or self.namespace
+        if ns:
+            params["ns"] = ns
+        if ttl_days is not None:
+            params["ttl"] = str(ttl_days)
+        headers = {}
+        if self.owner_token:
+            headers["X-Owner-Token"] = self.owner_token
+        if password:
+            headers["X-Password"] = password
+        if files is None:
+            headers["Content-Type"] = "application/json"
+            response = self._http.post(self.base_url + path, params=params, headers=headers,
+                                       content=json.dumps(json_body).encode("utf-8"))
+        else:
+            response = self._http.post(self.base_url + path, params=params, headers=headers, files=files)
+        if response.status_code >= 300:
+            raise BrewPageError(f"BrewPage {path} failed with HTTP {response.status_code}: {response.text[:500]}")
+        payload = response.json()
+        if not self.owner_token and payload.get("ownerToken"):
+            self.owner_token = payload["ownerToken"]
+        return {
+            "url": payload.get("link"),
+            "id": payload.get("id"),
+            "namespace": payload.get("namespace"),
+            "owner_token": payload.get("ownerToken") or self.owner_token,
+            "management_link": payload.get("managementLink"),
+            "expires_at": payload.get("expiresAt"),
+        }

langchain_brewpage-0.1.0/langchain_brewpage/tools.py

@@ -0,0 +1,115 @@
+"""LangChain tools and toolkit for BrewPage publishing."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Literal, Optional, Type
+
+from langchain_core.tools import BaseTool, BaseToolkit, ToolException
+from pydantic import BaseModel, ConfigDict, Field
+
+from langchain_brewpage.client import BrewPageClient, BrewPageError
+
+_NS = ("Namespace: omit for a private unlisted link; 'public' lists pages in the public gallery and search. "
+       "Never put secrets or personal data in 'public'.")
+_TTL = "Lifetime in days (1-30); omit for the 15-day default."
+_PASSWORD = "Optional password readers must enter."
+
+
+class _CommonInput(BaseModel):
+    ttl_days: Optional[int] = Field(default=None, description=_TTL)
+    password: Optional[str] = Field(default=None, description=_PASSWORD)
+    namespace: Optional[str] = Field(default=None, description=_NS)
+
+
+class PublishPageInput(_CommonInput):
+    content: str = Field(description="HTML document or Markdown text to publish.")
+    format: Literal["html", "markdown"] = Field(default="html", description="'html' or 'markdown'.")
+
+
+class PublishJsonInput(_CommonInput):
+    json_text: str = Field(description="A valid JSON document as text.")
+
+
+class CreateKvStoreInput(_CommonInput):
+    key: str = Field(description="Initial key name.")
+    value: str = Field(description="Value for the initial key (max 1 MB).")
+
+
+class UploadFileInput(_CommonInput):
+    path: str = Field(description="Local path of the file to upload.")
+
+
+class _BrewPageTool(BaseTool):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    client: BrewPageClient = Field(default_factory=BrewPageClient, exclude=True)
+    handle_tool_error: bool = True
+
+    def _call(self, method: str, **kwargs: Any) -> Dict[str, Any]:
+        try:
+            return getattr(self.client, method)(**kwargs)
+        except (BrewPageError, OSError, ValueError) as error:
+            raise ToolException(str(error)) from error
+
+
+class BrewPagePublishPageTool(_BrewPageTool):
+    name: str = "brewpage_publish_page"
+    description: str = ("Publish an HTML page or Markdown document on brewpage.app and get a shareable URL "
+                        "plus an owner token for later edits. No account needed.")
+    args_schema: Type[BaseModel] = PublishPageInput
+
+    def _run(self, content: str, format: str = "html", ttl_days: Optional[int] = None,
+             password: Optional[str] = None, namespace: Optional[str] = None, **_: Any) -> Dict[str, Any]:
+        return self._call("publish_page", content=content, format=format, ttl_days=ttl_days,
+                          password=password, namespace=namespace)
+
+
+class BrewPagePublishJsonTool(_BrewPageTool):
+    name: str = "brewpage_publish_json"
+    description: str = "Host a JSON document on brewpage.app and get a URL that serves it."
+    args_schema: Type[BaseModel] = PublishJsonInput
+
+    def _run(self, json_text: str, ttl_days: Optional[int] = None, password: Optional[str] = None,
+             namespace: Optional[str] = None, **_: Any) -> Dict[str, Any]:
+        try:
+            data = json.loads(json_text)
+        except ValueError as error:
+            raise ToolException(f"json_text is not valid JSON: {error}") from error
+        return self._call("publish_json", data=data, ttl_days=ttl_days, password=password, namespace=namespace)
+
+
+class BrewPageCreateKvStoreTool(_BrewPageTool):
+    name: str = "brewpage_create_kv_store"
+    description: str = "Create a key-value store on brewpage.app with one initial key; returns its URL."
+    args_schema: Type[BaseModel] = CreateKvStoreInput
+
+    def _run(self, key: str, value: str, ttl_days: Optional[int] = None, password: Optional[str] = None,
+             namespace: Optional[str] = None, **_: Any) -> Dict[str, Any]:
+        return self._call("create_kv_store", key=key, value=value, ttl_days=ttl_days,
+                          password=password, namespace=namespace)
+
+
+class BrewPageUploadFileTool(_BrewPageTool):
+    name: str = "brewpage_upload_file"
+    description: str = ("Upload a local file (image, PDF, archive, document, HTML or Markdown) to brewpage.app "
+                        "and get a download or page URL.")
+    args_schema: Type[BaseModel] = UploadFileInput
+
+    def _run(self, path: str, ttl_days: Optional[int] = None, password: Optional[str] = None,
+             namespace: Optional[str] = None, **_: Any) -> Dict[str, Any]:
+        return self._call("upload_file", path=path, ttl_days=ttl_days, password=password, namespace=namespace)
+
+
+class BrewPageToolkit(BaseToolkit):
+    """All BrewPage tools sharing one client, so every publication groups under one owner token."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    client: BrewPageClient = Field(default_factory=BrewPageClient)
+
+    def get_tools(self) -> List[BaseTool]:
+        return [
+            BrewPagePublishPageTool(client=self.client),
+            BrewPagePublishJsonTool(client=self.client),
+            BrewPageCreateKvStoreTool(client=self.client),
+            BrewPageUploadFileTool(client=self.client),
+        ]

langchain_brewpage-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-brewpage"
+version = "0.1.0"
+description = "LangChain tools for BrewPage: publish HTML, Markdown, JSON, KV stores and files to brewpage.app and get a shareable URL."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Maksim Kochetkov", email = "apmatypa88@gmail.com" }]
+requires-python = ">=3.10,<4.0"
+keywords = ["langchain", "brewpage", "hosting", "publish", "agent", "tools"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "langchain-core==1.7.6",
+    "httpx==0.28.1",
+]
+
+[project.urls]
+Homepage = "https://brewpage.app"
+Repository = "https://github.com/kochetkov-ma/langchain-brewpage"
+Issues = "https://github.com/kochetkov-ma/langchain-brewpage/issues"
+Documentation = "https://github.com/kochetkov-ma/langchain-brewpage#readme"
+
+[dependency-groups]
+test = ["pytest==9.2.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_brewpage"]
+
+[tool.hatch.build.targets.sdist]
+include = ["langchain_brewpage", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+markers = ["live: hits production brewpage.app (set BREWPAGE_LIVE=1)"]

langchain_brewpage-0.1.0/tests/test_tools.py

@@ -0,0 +1,105 @@
+import json
+import os
+import re
+
+import httpx
+import pytest
+
+from langchain_brewpage import BrewPageClient, BrewPageToolkit
+
+API_REPLY = {
+    "link": "https://brewpage.app/my/abc123",
+    "id": "abc123",
+    "namespace": "my",
+    "ownerToken": "tok-1",
+    "managementLink": "https://brewpage.app/my/abc123?manage=k1",
+    "expiresAt": "2026-11-20T00:00:00Z",
+}
+BOUNDARY = re.compile(r"[0-9a-f]{32}")
+RESULT = {
+    "url": "https://brewpage.app/my/abc123",
+    "id": "abc123",
+    "namespace": "my",
+    "owner_token": "tok-1",
+    "management_link": "https://brewpage.app/my/abc123?manage=k1",
+    "expires_at": "2026-11-20T00:00:00Z",
+}
+
+
+def _recording_client(status, reply, seen):
+    def handler(request):
+        seen.append({
+            "method": request.method,
+            "url": str(request.url),
+            "content_type": BOUNDARY.sub("B", request.headers["content-type"]),
+            "owner_token": request.headers.get("x-owner-token"),
+            "password": request.headers.get("x-password"),
+            "body": BOUNDARY.sub("B", request.content.decode("utf-8")),
+        })
+        return httpx.Response(status, json=reply)
+
+    return BrewPageClient(owner_token="tok-1", namespace="my", transport=httpx.MockTransport(handler))
+
+
+@pytest.mark.parametrize(
+    ("tool_index", "schema", "args", "expected_request"),
+    [
+        (0, ("brewpage_publish_page", ["content"]), {"content": "# Hi", "format": "markdown", "ttl_days": 3},
+         {"method": "POST", "url": "https://brewpage.app/api/html?ns=my&ttl=3", "content_type": "application/json",
+          "owner_token": "tok-1", "password": None, "body": '{"content": "# Hi", "format": "markdown"}'}),
+        (1, ("brewpage_publish_json", ["json_text"]), {"json_text": '{"a": [1, 2]}', "password": "pw"},
+         {"method": "POST", "url": "https://brewpage.app/api/json?ns=my", "content_type": "application/json",
+          "owner_token": "tok-1", "password": "pw", "body": '{"a": [1, 2]}'}),
+        (2, ("brewpage_create_kv_store", ["key", "value"]), {"key": "status", "value": "green"},
+         {"method": "POST", "url": "https://brewpage.app/api/kv?ns=my", "content_type": "application/json",
+          "owner_token": "tok-1", "password": None, "body": '{"key": "status", "value": "green"}'}),
+        (3, ("brewpage_upload_file", ["path"]), {"path": "{tmp}/notes.txt"},
+         {"method": "POST", "url": "https://brewpage.app/api/files?ns=my", "content_type": "multipart/form-data; boundary=B",
+          "owner_token": "tok-1", "password": None,
+          "body": '--B\r\nContent-Disposition: form-data; name="file"; filename="notes.txt"\r\n'
+                  'Content-Type: text/plain\r\n\r\nhello\r\n--B--\r\n'}),
+    ],
+    ids=["page", "json", "kv", "file"],
+)
+def test_tool_posts_exact_request_and_returns_link(tmp_path, tool_index, schema, args, expected_request):
+    # GIVEN a toolkit whose client answers every POST with a fixed API reply
+    (tmp_path / "notes.txt").write_text("hello")
+    seen = []
+    tool = BrewPageToolkit(client=_recording_client(201, API_REPLY, seen)).get_tools()[tool_index]
+    resolved = json.loads(json.dumps(args).replace("{tmp}", str(tmp_path)))
+
+    # WHEN the agent invokes the tool
+    result = tool.invoke(resolved)
+
+    # THEN the tool schema, the single request and the mapped result match exactly
+    assert ((tool.name, tool.args_schema.model_json_schema()["required"]), seen, result) == (schema, [expected_request], RESULT), f"tool {tool.name} sent {seen} and returned {result}"
+
+
+def test_api_error_becomes_tool_message():
+    # GIVEN an API that rate-limits the caller
+    seen = []
+    tool = BrewPageToolkit(client=_recording_client(429, {"message": "slow down"}, seen)).get_tools()[2]
+
+    # WHEN the tool is invoked
+    result = tool.invoke({"key": "k", "value": "v"})
+
+    # THEN the agent receives the error text instead of an exception
+    assert result == 'BrewPage /api/kv failed with HTTP 429: {"message":"slow down"}', f"unexpected tool output {result!r}"
+
+
+@pytest.mark.live
+@pytest.mark.skipif(os.environ.get("BREWPAGE_LIVE") != "1", reason="set BREWPAGE_LIVE=1 to hit production")
+def test_live_private_markdown_page():
+    # GIVEN the real API and the private 'my' namespace
+    tool = BrewPageToolkit(client=BrewPageClient(namespace="my")).get_tools()[0]
+
+    # WHEN a short Markdown page is published for one day
+    result = tool.invoke({"content": "# langchain-brewpage smoke\n\nPrivate test page.", "format": "markdown", "ttl_days": 1})
+
+    # THEN a private brewpage.app link and an owner token come back
+    shape = {
+        "namespace": result["namespace"],
+        "url": bool(re.fullmatch(r"https://([a-z0-9-]+\.)*brewpage\.app/\S+", result["url"])),
+        "owner_token": bool(re.fullmatch(r"\S{16,}", result["owner_token"])),
+    }
+    assert shape == {"namespace": "my", "url": True, "owner_token": True}, f"live result {json.dumps(result)}"