langchain-tabstack 0.1.0__py3-none-any.whl

langchain_tabstack/__init__.py

@@ -0,0 +1,66 @@
+"""Tabstack tools for LangChain.
+
+Schema-enforced web extraction and research, backed by the official Tabstack SDK.
+"""
+
+from __future__ import annotations
+
+from .client import (
+    create_async_tabstack_client,
+    create_tabstack_client,
+    get_default_async_client,
+    get_default_client,
+)
+from .errors import TabstackToolError, normalize_error
+from .schemas import (
+    AutomateBrowserTaskInput,
+    ExtractPageContentInput,
+    ExtractStructuredDataInput,
+    GenerateStructuredDataInput,
+    ResearchQuestionInput,
+)
+from .tools import (
+    TOOL_DESCRIPTIONS,
+    TOOL_NAMES,
+    create_tabstack_tools,
+)
+
+# Default-client tools. The client is resolved lazily on first tool call, so
+# importing this module never requires TABSTACK_API_KEY to be set.
+TABSTACK_TOOLS = create_tabstack_tools()
+(
+    extract_structured_data_tool,
+    extract_page_content_tool,
+    research_question_tool,
+    generate_structured_data_tool,
+    automate_browser_task_tool,
+) = TABSTACK_TOOLS
+
+# Alias matching the common LangChain naming convention.
+get_tabstack_tools = create_tabstack_tools
+
+__all__ = [
+    "create_tabstack_tools",
+    "get_tabstack_tools",
+    "TABSTACK_TOOLS",
+    "extract_structured_data_tool",
+    "extract_page_content_tool",
+    "research_question_tool",
+    "generate_structured_data_tool",
+    "automate_browser_task_tool",
+    "create_tabstack_client",
+    "create_async_tabstack_client",
+    "get_default_client",
+    "get_default_async_client",
+    "TabstackToolError",
+    "normalize_error",
+    "TOOL_NAMES",
+    "TOOL_DESCRIPTIONS",
+    "ExtractStructuredDataInput",
+    "ExtractPageContentInput",
+    "ResearchQuestionInput",
+    "GenerateStructuredDataInput",
+    "AutomateBrowserTaskInput",
+]
+
+__version__ = "0.1.0"

langchain_tabstack/client.py

@@ -0,0 +1,72 @@
+"""Tabstack client construction.
+
+The API key is read from ``TABSTACK_API_KEY`` by default and can be overridden
+explicitly. Every network call in this package goes through this client.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from tabstack import AsyncTabstack, Tabstack
+
+__all__ = [
+    "create_tabstack_client",
+    "get_default_client",
+    "create_async_tabstack_client",
+    "get_default_async_client",
+]
+
+
+def _client_kwargs(api_key: Optional[str], base_url: Optional[str]) -> dict:
+    resolved_key = api_key if api_key is not None else os.environ.get("TABSTACK_API_KEY")
+    kwargs: dict = {"api_key": resolved_key}
+    if base_url is not None:
+        kwargs["base_url"] = base_url
+    return kwargs
+
+
+def create_tabstack_client(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Tabstack:
+    """Construct a configured synchronous Tabstack client.
+
+    Args:
+        api_key: Tabstack API key. Falls back to ``TABSTACK_API_KEY`` when omitted.
+        base_url: Override the API base URL. Uses the SDK default when omitted.
+    """
+    return Tabstack(**_client_kwargs(api_key, base_url))
+
+
+def create_async_tabstack_client(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> AsyncTabstack:
+    """Construct a configured asynchronous Tabstack client."""
+    return AsyncTabstack(**_client_kwargs(api_key, base_url))
+
+
+_default_client: Optional[Tabstack] = None
+_default_async_client: Optional[AsyncTabstack] = None
+
+
+def get_default_client() -> Tabstack:
+    """Lazily construct and reuse a single default sync client.
+
+    The client is only built on first use, so importing this package never
+    requires an API key to be set.
+    """
+    global _default_client
+    if _default_client is None:
+        _default_client = create_tabstack_client()
+    return _default_client
+
+
+def get_default_async_client() -> AsyncTabstack:
+    """Lazily construct and reuse a single default async client."""
+    global _default_async_client
+    if _default_async_client is None:
+        _default_async_client = create_async_tabstack_client()
+    return _default_async_client

langchain_tabstack/errors.py

@@ -0,0 +1,35 @@
+"""Normalised error surfaced consistently by the Tabstack tools."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from tabstack import APIError, APIStatusError
+
+__all__ = ["TabstackToolError", "normalize_error"]
+
+
+class TabstackToolError(Exception):
+    """A small normalised error wrapping the SDK's exceptions.
+
+    Consumers can catch this without depending on SDK internals.
+    """
+
+    def __init__(self, message: str, *, status: Optional[int] = None, cause: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.__cause__ = cause if isinstance(cause, BaseException) else None
+        self.cause = cause
+
+
+def normalize_error(err: Any) -> TabstackToolError:
+    """Map any raised value into a :class:`TabstackToolError`."""
+    if isinstance(err, TabstackToolError):
+        return err
+    if isinstance(err, APIStatusError):
+        return TabstackToolError(str(err), status=err.status_code, cause=err)
+    if isinstance(err, APIError):
+        return TabstackToolError(str(err), cause=err)
+    if isinstance(err, Exception):
+        return TabstackToolError(str(err), cause=err)
+    return TabstackToolError("Unknown Tabstack error", cause=err)

langchain_tabstack/schemas.py

@@ -0,0 +1,100 @@
+"""Pydantic input schemas for the Tabstack tools.
+
+These are the single source of truth for each tool's input surface and mirror
+the TypeScript ``@tabstack/langchain`` and ``@tabstack/ai`` packages so the
+cross-language story stays consistent.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+__all__ = [
+    "ExtractStructuredDataInput",
+    "ExtractPageContentInput",
+    "ResearchQuestionInput",
+    "GenerateStructuredDataInput",
+    "AutomateBrowserTaskInput",
+]
+
+_EFFORT_DESCRIPTION = (
+    'Optional fetch effort: "min" (fastest), "standard" (default, balanced), '
+    '"max" (full browser rendering for JS-heavy pages).'
+)
+_NOCACHE_DESCRIPTION = "Optional: bypass cache and force fresh retrieval"
+_COUNTRY_DESCRIPTION = 'Optional ISO 3166-1 alpha-2 country code for geotargeting (e.g. "US")'
+
+
+class ExtractStructuredDataInput(BaseModel):
+    url: str = Field(description="URL to fetch and extract structured data from")
+    json_schema_json: str = Field(
+        description=(
+            "A JSON-encoded JSON Schema object with concrete properties and descriptions "
+            "for each field to extract."
+        )
+    )
+    effort: Optional[Literal["min", "standard", "max"]] = Field(
+        default=None, description=_EFFORT_DESCRIPTION
+    )
+    nocache: Optional[bool] = Field(default=None, description=_NOCACHE_DESCRIPTION)
+    country: Optional[str] = Field(default=None, description=_COUNTRY_DESCRIPTION)
+
+
+class ExtractPageContentInput(BaseModel):
+    url: str = Field(description="URL to fetch and convert to clean markdown")
+    effort: Optional[Literal["min", "standard", "max"]] = Field(
+        default=None, description=_EFFORT_DESCRIPTION
+    )
+    nocache: Optional[bool] = Field(default=None, description=_NOCACHE_DESCRIPTION)
+    country: Optional[str] = Field(default=None, description=_COUNTRY_DESCRIPTION)
+
+
+class ResearchQuestionInput(BaseModel):
+    query: str = Field(description="The research question to answer using multiple web sources")
+    mode: Optional[Literal["fast", "balanced"]] = Field(
+        default=None,
+        description='Optional research mode: "fast" (quick) or "balanced" (default, more thorough)',
+    )
+    nocache: Optional[bool] = Field(default=None, description=_NOCACHE_DESCRIPTION)
+
+
+class GenerateStructuredDataInput(BaseModel):
+    url: str = Field(description="URL whose content should be fetched and transformed")
+    instructions: str = Field(
+        description="Natural-language instructions describing how to transform the page content"
+    )
+    json_schema_json: str = Field(
+        description=(
+            "A JSON-encoded JSON Schema object describing the shape of the generated output, "
+            "with concrete properties and descriptions for each field."
+        )
+    )
+    effort: Optional[Literal["min", "standard", "max"]] = Field(
+        default=None, description=_EFFORT_DESCRIPTION
+    )
+    nocache: Optional[bool] = Field(default=None, description=_NOCACHE_DESCRIPTION)
+    country: Optional[str] = Field(default=None, description=_COUNTRY_DESCRIPTION)
+
+
+class AutomateBrowserTaskInput(BaseModel):
+    task: str = Field(description="The browser automation task to perform, in natural language")
+    url: Optional[str] = Field(default=None, description="Optional starting URL for the task")
+    guardrails: Optional[str] = Field(
+        default=None, description="Optional safety constraints on what the agent is allowed to do"
+    )
+    data: Optional[Dict[str, Any]] = Field(
+        default=None, description="Optional JSON context data for form filling or complex tasks"
+    )
+    country: Optional[str] = Field(
+        default=None,
+        description='Optional ISO 3166-1 alpha-2 country code for geotargeted browsing (e.g. "US")',
+    )
+    max_iterations: Optional[int] = Field(
+        default=None, description="Optional cap on the number of agent iterations"
+    )
+    max_validation_attempts: Optional[int] = Field(
+        default=None, description="Optional cap on the number of result validation attempts"
+    )

langchain_tabstack/tools.py

@@ -0,0 +1,386 @@
+"""Framework-agnostic Tabstack tool bodies plus the LangChain tool factory.
+
+The tool names and descriptions are the single source of truth, kept in lockstep
+with the TypeScript ``@tabstack/langchain`` and ``@tabstack/ai`` packages. Each
+tool is exposed with both a synchronous implementation and a native async
+coroutine, so ``invoke`` and ``ainvoke`` both run without a thread-pool bounce.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from langchain_core.tools import BaseTool, StructuredTool
+from tabstack import AsyncTabstack, Tabstack
+
+from .client import get_default_async_client, get_default_client
+from .errors import normalize_error
+from .schemas import (
+    AutomateBrowserTaskInput,
+    ExtractPageContentInput,
+    ExtractStructuredDataInput,
+    GenerateStructuredDataInput,
+    ResearchQuestionInput,
+)
+
+__all__ = [
+    "TOOL_NAMES",
+    "TOOL_DESCRIPTIONS",
+    "extract_structured_data",
+    "extract_page_content",
+    "research_question",
+    "generate_structured_data",
+    "automate_browser_task",
+    "create_tabstack_tools",
+]
+
+TOOL_NAMES = {
+    "extract_structured_data": "extract_structured_data",
+    "extract_page_content": "extract_page_content",
+    "research_question": "research_question",
+    "generate_structured_data": "generate_structured_data",
+    "automate_browser_task": "automate_browser_task",
+}
+
+TOOL_DESCRIPTIONS = {
+    "extract_structured_data": (
+        "Extract structured JSON data from a URL. Use when you need specific fields from a web "
+        "page. 'json_schema_json' must be a JSON-encoded JSON Schema object with concrete "
+        "properties and descriptions for each field to extract. See the schema-design guide for "
+        "patterns that produce reliable results. Returns the extracted data as JSON."
+    ),
+    "extract_page_content": (
+        "Fetch a URL and return its content as clean markdown. Use when you need to read a page's "
+        "full content for summarization or when you don't know what specific fields to extract. "
+        "Returns clean markdown text."
+    ),
+    "research_question": (
+        "Research a question using multiple web sources. Use when you need a synthesized answer "
+        "from multiple sources, not just data from a single known page. Returns an answer with "
+        "cited sources."
+    ),
+    "generate_structured_data": (
+        "Fetch a URL, then transform and restructure its content with AI into structured JSON. "
+        "Use when you need derived or reshaped data (summaries, categorizations, computed "
+        "fields), not just verbatim extraction. 'instructions' tells the AI how to transform the "
+        "content; 'json_schema_json' must be a JSON-encoded JSON Schema object describing the "
+        "output shape. Returns the generated data as JSON."
+    ),
+    "automate_browser_task": (
+        "Run an AI browser automation task described in natural language. Use for multi-step web "
+        "workflows: navigating, filling forms, gathering, and extracting across pages. Provide a "
+        "clear 'task' and optionally a starting 'url', 'guardrails' to constrain the agent, "
+        "'data' as context for form filling, a 'country' code for geotargeted browsing, and caps "
+        "via 'max_iterations' and 'max_validation_attempts'. Runs non-interactively and returns "
+        "the final answer plus any extracted data and the pages visited."
+    ),
+}
+
+
+def _fetch_options(inp: Any) -> Dict[str, Any]:
+    """Shared fetch options (effort, cache bypass, geotargeting) for the extract
+    and generate endpoints. Omitted values fall back to SDK defaults."""
+    options: Dict[str, Any] = {}
+    if inp.effort is not None:
+        options["effort"] = inp.effort
+    if inp.nocache is not None:
+        options["nocache"] = inp.nocache
+    if inp.country is not None:
+        options["geo_target"] = {"country": inp.country}
+    return options
+
+
+def _research_kwargs(inp: ResearchQuestionInput) -> Dict[str, Any]:
+    kwargs: Dict[str, Any] = {"query": inp.query, "mode": inp.mode or "balanced"}
+    if inp.nocache is not None:
+        kwargs["nocache"] = inp.nocache
+    return kwargs
+
+
+def _automate_kwargs(inp: AutomateBrowserTaskInput) -> Dict[str, Any]:
+    # Interactive mode is intentionally left off: a one-shot tool cannot service
+    # the human-in-the-loop form-data callback (``agent.automate_input``).
+    kwargs: Dict[str, Any] = {"task": inp.task}
+    if inp.url is not None:
+        kwargs["url"] = inp.url
+    if inp.guardrails is not None:
+        kwargs["guardrails"] = inp.guardrails
+    if inp.data is not None:
+        kwargs["data"] = inp.data
+    if inp.country is not None:
+        kwargs["geo_target"] = {"country": inp.country}
+    if inp.max_iterations is not None:
+        kwargs["max_iterations"] = inp.max_iterations
+    if inp.max_validation_attempts is not None:
+        kwargs["max_validation_attempts"] = inp.max_validation_attempts
+    return kwargs
+
+
+def _research_complete(event: Any) -> Dict[str, Any]:
+    cited = event.data.metadata.cited_pages or []
+    return {
+        "answer": event.data.report,
+        "sources": [{"title": page.title or "", "url": page.url} for page in cited],
+    }
+
+
+def _automate_complete(
+    event: Any, extracted: List[str], pages_visited: List[Dict[str, str]]
+) -> Dict[str, Any]:
+    data = event.data
+    if not data.success and data.error:
+        raise RuntimeError(f"Automation failed: {data.error.message}")
+    return {
+        "answer": data.final_answer,
+        "success": data.success,
+        "iterations": data.stats.iterations,
+        "actions": data.stats.actions,
+        "duration_ms": data.stats.duration_ms,
+        "extracted": extracted,
+        "pages_visited": pages_visited,
+    }
+
+
+def _automate_incomplete(
+    extracted: List[str], pages_visited: List[Dict[str, str]]
+) -> Dict[str, Any]:
+    return {
+        "answer": None,
+        "success": False,
+        "iterations": 0,
+        "actions": 0,
+        "duration_ms": 0,
+        "extracted": extracted,
+        "pages_visited": pages_visited,
+    }
+
+
+# --- Synchronous tool bodies -------------------------------------------------
+
+
+def extract_structured_data(inp: ExtractStructuredDataInput, client: Tabstack) -> Dict[str, Any]:
+    """Extract structured data from a URL via ``client.extract.json``."""
+    try:
+        schema = json.loads(inp.json_schema_json)
+        return client.extract.json(url=inp.url, json_schema=schema, **_fetch_options(inp))
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+def extract_page_content(inp: ExtractPageContentInput, client: Tabstack) -> str:
+    """Fetch a URL and return clean markdown via ``client.extract.markdown``."""
+    try:
+        result = client.extract.markdown(url=inp.url, **_fetch_options(inp))
+        return result.content
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+def research_question(inp: ResearchQuestionInput, client: Tabstack) -> Dict[str, Any]:
+    """Research a question across multiple web sources via ``client.agent.research``."""
+    try:
+        stream = client.agent.research(**_research_kwargs(inp))
+        for event in stream:
+            if event.event == "error":
+                message = getattr(event.data, "message", None) or "unknown error"
+                raise RuntimeError(f"Research failed: {message}")
+            if event.event == "complete":
+                return _research_complete(event)
+        return {"answer": "Research did not complete", "sources": []}
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+def generate_structured_data(inp: GenerateStructuredDataInput, client: Tabstack) -> Dict[str, Any]:
+    """Fetch a URL and AI-transform its content via ``client.generate.json``."""
+    try:
+        schema = json.loads(inp.json_schema_json)
+        return client.generate.json(
+            url=inp.url,
+            json_schema=schema,
+            instructions=inp.instructions,
+            **_fetch_options(inp),
+        )
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+def automate_browser_task(inp: AutomateBrowserTaskInput, client: Tabstack) -> Dict[str, Any]:
+    """Run a browser automation task via ``client.agent.automate``.
+
+    Consumes the SSE stream non-interactively and returns the final answer plus
+    any extracted data and the pages visited.
+    """
+    try:
+        stream = client.agent.automate(**_automate_kwargs(inp))
+        extracted: List[str] = []
+        pages_visited: List[Dict[str, str]] = []
+        for event in stream:
+            if event.event == "agent:extracted":
+                extracted.append(event.data.extracted_data)
+            elif event.event == "browser:navigated":
+                pages_visited.append({"url": event.data.url, "title": event.data.title})
+            elif event.event == "error":
+                raise RuntimeError(f"Automation failed: {event.data.error.message}")
+            elif event.event == "complete":
+                return _automate_complete(event, extracted, pages_visited)
+        return _automate_incomplete(extracted, pages_visited)
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+# --- Asynchronous tool bodies ------------------------------------------------
+
+
+async def aextract_structured_data(
+    inp: ExtractStructuredDataInput, client: AsyncTabstack
+) -> Dict[str, Any]:
+    try:
+        schema = json.loads(inp.json_schema_json)
+        return await client.extract.json(url=inp.url, json_schema=schema, **_fetch_options(inp))
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+async def aextract_page_content(inp: ExtractPageContentInput, client: AsyncTabstack) -> str:
+    try:
+        result = await client.extract.markdown(url=inp.url, **_fetch_options(inp))
+        return result.content
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+async def aresearch_question(inp: ResearchQuestionInput, client: AsyncTabstack) -> Dict[str, Any]:
+    try:
+        stream = await client.agent.research(**_research_kwargs(inp))
+        async for event in stream:
+            if event.event == "error":
+                message = getattr(event.data, "message", None) or "unknown error"
+                raise RuntimeError(f"Research failed: {message}")
+            if event.event == "complete":
+                return _research_complete(event)
+        return {"answer": "Research did not complete", "sources": []}
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+async def agenerate_structured_data(
+    inp: GenerateStructuredDataInput, client: AsyncTabstack
+) -> Dict[str, Any]:
+    try:
+        schema = json.loads(inp.json_schema_json)
+        return await client.generate.json(
+            url=inp.url,
+            json_schema=schema,
+            instructions=inp.instructions,
+            **_fetch_options(inp),
+        )
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+async def aautomate_browser_task(
+    inp: AutomateBrowserTaskInput, client: AsyncTabstack
+) -> Dict[str, Any]:
+    try:
+        stream = await client.agent.automate(**_automate_kwargs(inp))
+        extracted: List[str] = []
+        pages_visited: List[Dict[str, str]] = []
+        async for event in stream:
+            if event.event == "agent:extracted":
+                extracted.append(event.data.extracted_data)
+            elif event.event == "browser:navigated":
+                pages_visited.append({"url": event.data.url, "title": event.data.title})
+            elif event.event == "error":
+                raise RuntimeError(f"Automation failed: {event.data.error.message}")
+            elif event.event == "complete":
+                return _automate_complete(event, extracted, pages_visited)
+        return _automate_incomplete(extracted, pages_visited)
+    except Exception as err:
+        raise normalize_error(err) from err
+
+
+def _dumps(value: Any) -> str:
+    return value if isinstance(value, str) else json.dumps(value)
+
+
+def create_tabstack_tools(
+    client: Optional[Tabstack] = None,
+    *,
+    async_client: Optional[AsyncTabstack] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> List[BaseTool]:
+    """Build the Tabstack LangChain tools.
+
+    Pass a ready ``client`` / ``async_client``, or ``api_key`` / ``base_url`` to
+    construct them. When nothing is given, each tool resolves the lazily-built
+    default client at call time, so building the tools never requires an API key.
+    Both sync (``invoke``) and async (``ainvoke``) execution are supported.
+
+    Returns:
+        A list of LangChain tools ready to pass to ``create_agent`` /
+        ``AgentExecutor``.
+    """
+    if api_key is not None or base_url is not None:
+        from .client import create_async_tabstack_client, create_tabstack_client
+
+        if client is None:
+            client = create_tabstack_client(api_key=api_key, base_url=base_url)
+        if async_client is None:
+            async_client = create_async_tabstack_client(api_key=api_key, base_url=base_url)
+
+    def sync() -> Tabstack:
+        return client if client is not None else get_default_client()
+
+    def asyncc() -> AsyncTabstack:
+        return async_client if async_client is not None else get_default_async_client()
+
+    def _build(name: str, schema, body, abody) -> StructuredTool:
+        def func(**kwargs: Any) -> str:
+            return _dumps(body(schema(**kwargs), sync()))
+
+        async def coroutine(**kwargs: Any) -> str:
+            return _dumps(await abody(schema(**kwargs), asyncc()))
+
+        return StructuredTool.from_function(
+            func=func,
+            coroutine=coroutine,
+            name=TOOL_NAMES[name],
+            description=TOOL_DESCRIPTIONS[name],
+            args_schema=schema,
+        )
+
+    return [
+        _build(
+            "extract_structured_data",
+            ExtractStructuredDataInput,
+            extract_structured_data,
+            aextract_structured_data,
+        ),
+        _build(
+            "extract_page_content",
+            ExtractPageContentInput,
+            extract_page_content,
+            aextract_page_content,
+        ),
+        _build(
+            "research_question",
+            ResearchQuestionInput,
+            research_question,
+            aresearch_question,
+        ),
+        _build(
+            "generate_structured_data",
+            GenerateStructuredDataInput,
+            generate_structured_data,
+            agenerate_structured_data,
+        ),
+        _build(
+            "automate_browser_task",
+            AutomateBrowserTaskInput,
+            automate_browser_task,
+            aautomate_browser_task,
+        ),
+    ]

langchain_tabstack-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: langchain-tabstack
+Version: 0.1.0
+Summary: Tabstack tools for LangChain. Schema-enforced web extraction and research, backed by the official Tabstack SDK.
+Project-URL: Homepage, https://tabstack.ai
+Project-URL: Documentation, https://docs.tabstack.ai
+Project-URL: Source, https://github.com/Mozilla-Ocho/tabstack-langchain-python
+Author: Tabstack
+License: MIT
+Keywords: agent,extraction,langchain,tabstack,tools,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: pydantic>=2
+Requires-Dist: tabstack>=2.6.1
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-mock>=3; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-tabstack
+
+Give your [LangChain](https://python.langchain.com) agents reliable web access. Schema-enforced
+extraction, multi-source research, AI transformation, and browser automation, all as native
+LangChain tools backed by the official [Tabstack SDK](https://pypi.org/project/tabstack/).
+
+## Why Tabstack
+
+LangChain's built-in loaders (`WebBaseLoader`, `PlaywrightURLLoader`) are fine for prototypes and
+brittle in production: unpredictable parsing, Playwright binaries to install and maintain, and
+behaviour that drifts across LangChain releases.
+
+Tabstack replaces them with a hosted API:
+
+- **Schema-enforced output.** You define the shape, you get that shape back. No prompt-engineering
+  the JSON out of raw text.
+- **No browser to run.** JS-heavy pages render server-side. No Playwright, no binaries.
+- **Version-independent.** It is an SDK call, not a loader coupled to your LangChain version.
+- **Sync and async.** Every tool supports `invoke` and native `ainvoke`.
+
+## Install
+
+```bash
+pip install langchain-tabstack
+```
+
+Requires Python 3.9+. For the agent example below you also need a chat model, for example
+`pip install langchain langchain-openai`. Set your API key (get one at
+[console.tabstack.ai](https://console.tabstack.ai)):
+
+```bash
+export TABSTACK_API_KEY="your-key-here"
+```
+
+## Quickstart
+
+```python
+from langchain.agents import create_agent
+from langchain_tabstack import TABSTACK_TOOLS
+
+agent = create_agent(
+    "openai:gpt-4o",
+    tools=TABSTACK_TOOLS,
+    system_prompt=(
+        "You are a research assistant with web intelligence tools. "
+        "Use extract_structured_data for specific fields from a URL, "
+        "extract_page_content for full page text, and research_question for multi-source research."
+    ),
+)
+
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "What are Vercel's pricing plans?"}]}
+)
+print(result["messages"][-1].content)
+```
+
+`TABSTACK_TOOLS` reads `TABSTACK_API_KEY` from the environment and is ready to drop into any agent.
+
+> Using LangChain 0.x? `create_agent` is the LangChain 1.x replacement for `AgentExecutor` +
+> `create_tool_calling_agent`. The tools themselves work with either.
+
+## The tools
+
+| Tool | What it does |
+| --- | --- |
+| `extract_structured_data` | Pull specific fields from a URL into a JSON shape you define. |
+| `extract_page_content` | Fetch a page as clean markdown. |
+| `research_question` | Synthesised answer with cited sources across multiple pages. |
+| `generate_structured_data` | Fetch a page, then AI-transform it into derived or reshaped JSON. |
+| `automate_browser_task` | Run a multi-step, natural-language browser task. |
+
+Every tool is exported individually too, so you can use one directly without an agent. Tools return
+a JSON string (use `json.loads`); `extract_page_content` returns markdown text directly.
+
+### extract_structured_data
+
+```python
+import json
+from langchain_tabstack import extract_structured_data_tool
+
+raw = extract_structured_data_tool.invoke(
+    {
+        "url": "https://news.ycombinator.com",
+        # json_schema_json is a JSON-encoded JSON Schema describing the fields you want.
+        "json_schema_json": json.dumps(
+            {
+                "type": "object",
+                "properties": {
+                    "stories": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "title": {"type": "string"},
+                                "points": {"type": "number", "description": "Story points"},
+                            },
+                        },
+                    }
+                },
+            }
+        ),
+    }
+)
+data = json.loads(raw)
+print(data["stories"])
+```
+
+### extract_page_content
+
+```python
+from langchain_tabstack import extract_page_content_tool
+
+markdown = extract_page_content_tool.invoke({"url": "https://example.com/blog/article"})
+```
+
+### research_question
+
+```python
+import json
+from langchain_tabstack import research_question_tool
+
+result = json.loads(
+    research_question_tool.invoke(
+        {"query": "What are the latest developments in quantum error correction?"}
+    )
+)
+print(result["answer"])
+for source in result["sources"]:  # [{"title": ..., "url": ...}, ...]
+    print(source["url"])
+```
+
+### generate_structured_data
+
+```python
+import json
+from langchain_tabstack import generate_structured_data_tool
+
+raw = generate_structured_data_tool.invoke(
+    {
+        "url": "https://news.ycombinator.com",
+        "instructions": "For each story, categorize it and write a one-sentence summary.",
+        "json_schema_json": json.dumps(
+            {
+                "type": "object",
+                "properties": {
+                    "summaries": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "title": {"type": "string"},
+                                "category": {"type": "string"},
+                                "summary": {"type": "string"},
+                            },
+                        },
+                    }
+                },
+            }
+        ),
+    }
+)
+```
+
+### automate_browser_task
+
+```python
+import json
+from langchain_tabstack import automate_browser_task_tool
+
+result = json.loads(
+    automate_browser_task_tool.invoke(
+        {
+            "task": "Find the top 3 trending repositories and their star counts",
+            "url": "https://github.com/trending",
+            "guardrails": "browse and extract only, do not submit forms",
+        }
+    )
+)
+# {"answer", "success", "iterations", "actions", "duration_ms", "extracted", "pages_visited"}
+```
+
+## Optional inputs
+
+Pass these alongside the required inputs for finer control. They are sent only when provided, so
+omitting them keeps Tabstack's defaults.
+
+- `extract_structured_data`, `extract_page_content`, `generate_structured_data`:
+  - `effort`: `"min"` | `"standard"` | `"max"`. Use `"max"` for JS-heavy pages (full server-side
+    browser rendering, the `PlaywrightURLLoader` replacement).
+  - `nocache`: `True` to bypass the cache.
+  - `country`: ISO 3166-1 alpha-2 code (for example `"US"`) for geotargeted fetches.
+- `research_question`: `mode` (`"fast"` | `"balanced"`), `nocache`.
+- `automate_browser_task`: `data` (context for form filling), `country`, `max_iterations`,
+  `max_validation_attempts`.
+
+```python
+# Render a JS-heavy SPA, fresh, from the UK:
+extract_page_content_tool.invoke(
+    {"url": url, "effort": "max", "nocache": True, "country": "GB"}
+)
+```
+
+## Async
+
+Every tool supports `ainvoke` natively, backed by `AsyncTabstack`, so it runs in your event loop
+without a thread-pool bounce:
+
+```python
+markdown = await extract_page_content_tool.ainvoke({"url": "https://example.com"})
+```
+
+## Configuration
+
+For a custom API key or base URL, or to reuse one client, build the tools explicitly:
+
+```python
+from langchain_tabstack import create_tabstack_tools
+
+tools = create_tabstack_tools(api_key="...")
+# or pass clients you already have:
+# create_tabstack_tools(client=..., async_client=...)
+```
+
+## Error handling
+
+Tool calls raise `TabstackToolError` with a normalised message and, for API failures, an HTTP
+`status`:
+
+```python
+from langchain_tabstack import TabstackToolError, extract_page_content_tool
+
+try:
+    extract_page_content_tool.invoke({"url": "https://example.com"})
+except TabstackToolError as err:
+    print(f"Tabstack failed ({err.status or 'no status'}): {err}")
+```
+
+## Good to know
+
+- **`automate_browser_task` runs non-interactively.** It does not pause for human-in-the-loop form
+  input, so it never blocks. It returns the final answer plus the data it extracted and the pages it
+  visited.
+- The client is created lazily, so importing the package never requires an API key to be set.
+- The tool names, descriptions, and inputs match the
+  [`@tabstack/langchain`](https://www.npmjs.com/package/@tabstack/langchain) (LangChain.js) and
+  [`@tabstack/ai`](https://www.npmjs.com/package/@tabstack/ai) (Vercel AI SDK) packages, so
+  behaviour is consistent across languages and frameworks. Those return native objects with
+  camelCase keys; this package returns JSON strings with snake_case keys, the LangChain-Python
+  convention. The data is the same.
+
+## Links
+
+- [Tabstack docs](https://docs.tabstack.ai)
+- [Tabstack SDK (`tabstack`)](https://pypi.org/project/tabstack/)
+- [Get an API key](https://console.tabstack.ai)

langchain_tabstack-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+langchain_tabstack/__init__.py,sha256=Vag5MQOP_d2ZZ7vFklSw4PSRFdaUF5FXCei-s9m1anU,1746
+langchain_tabstack/client.py,sha256=9pGF7m1mwM1T6m3HVjocAkL7_IzOXXSXMdNS0lHFolA,2161
+langchain_tabstack/errors.py,sha256=2A3H5-9TGALCct17CLhUGSDi98FJRa07VGZJYIoTHJk,1221
+langchain_tabstack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_tabstack/schemas.py,sha256=BRRS12w6bL8hfCEZy4FYKALWHQXvtSz3YzvqIeaMd5g,4137
+langchain_tabstack/tools.py,sha256=4UhMdU5NE7nmfEjmrb71esY3mJrRm_NWEB5BzuwvGtc,14758
+langchain_tabstack-0.1.0.dist-info/METADATA,sha256=Uj4xrivZeqnelsDQG4fC0NWbEv4byd1MTC9ZslMmLec,9750
+langchain_tabstack-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+langchain_tabstack-0.1.0.dist-info/RECORD,,

langchain_tabstack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any