capsolver-agent 0.1.0__py3-none-any.whl

capsolver_agent/__init__.py

@@ -0,0 +1,28 @@
+"""CapSolver Agent — tool definitions for AI agent frameworks.
+
+Provides two integration layers:
+  - ``schema``  : Framework-agnostic tool definitions (JSON schemas + executor)
+  - ``langchain_tools`` : LangChain BaseTool implementations
+
+Usage (framework-agnostic):
+    from capsolver_agent.schema import get_all_tools, execute_tool
+
+    tools = get_all_tools()           # list of ToolDef with JSON schemas
+    result = await execute_tool("solve_captcha", {...})
+
+Usage (LangChain):
+    from capsolver_agent.langchain_tools import get_langchain_tools
+
+    tools = get_langchain_tools(api_key="your-key")
+    agent = create_react_agent(llm, tools)
+"""
+
+from capsolver_agent.schema import ToolDef, get_all_tools, execute_tool, create_executor
+
+__all__ = [
+    "ToolDef",
+    "get_all_tools",
+    "execute_tool",
+    "create_executor",
+]
+__version__ = "0.1.0"

capsolver_agent/__main__.py

@@ -0,0 +1,112 @@
+"""CLI entry point for ``python -m capsolver_agent`` and the ``capsolver-agent`` console script.
+
+Usage:
+    capsolver-agent list                         # list all available tools
+    capsolver-agent schema solve_captcha          # show JSON Schema for a tool
+    capsolver-agent schema --format openai        # export all tools in OpenAI format
+    capsolver-agent schema --format openai solve_captcha  # export one tool in OpenAI format
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _cmd_list(_args: argparse.Namespace) -> None:
+    """List all tools with name and description."""
+    from capsolver_agent.schema import get_all_tools
+
+    tools = get_all_tools()
+    for i, t in enumerate(tools, 1):
+        print(f"{i}. {t.name}")
+        # Wrap description at 72 chars
+        desc_lines = _wrap(t.description, width=72)
+        for line in desc_lines:
+            print(f"   {line}")
+        if i < len(tools):
+            print()
+
+
+def _cmd_schema(args: argparse.Namespace) -> None:
+    """Show JSON Schema for one or all tools."""
+    from capsolver_agent.schema import get_all_tools
+
+    tools = get_all_tools()
+    fmt = args.format
+
+    if args.tool:
+        # Single tool
+        found = next((t for t in tools if t.name == args.tool), None)
+        if found is None:
+            names = ", ".join(t.name for t in tools)
+            print(f"Error: unknown tool '{args.tool}'. Available: {names}", file=sys.stderr)
+            sys.exit(1)
+        if fmt == "openai":
+            print(json.dumps(found.to_openai_function(), indent=2, ensure_ascii=False))
+        else:
+            print(json.dumps(found.to_json_schema(), indent=2, ensure_ascii=False))
+    else:
+        # All tools
+        if fmt == "openai":
+            data = [t.to_openai_function() for t in tools]
+        else:
+            data = [t.to_json_schema() for t in tools]
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def _wrap(text: str, width: int = 72) -> list[str]:
+    """Simple word-wrap helper."""
+    words = text.split()
+    lines: list[str] = []
+    current: list[str] = []
+    length = 0
+    for w in words:
+        if length + len(w) + 1 > width and current:
+            lines.append(" ".join(current))
+            current = [w]
+            length = len(w)
+        else:
+            current.append(w)
+            length += len(w) + 1
+    if current:
+        lines.append(" ".join(current))
+    return lines
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="capsolver-agent",
+        description="CapSolver Agent — inspect available tools and their schemas.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # list
+    sub.add_parser("list", help="List all available tools.")
+
+    # schema
+    schema_p = sub.add_parser("schema", help="Show JSON Schema for tools.")
+    schema_p.add_argument("tool", nargs="?", default=None, help="Tool name (omit for all).")
+    schema_p.add_argument(
+        "--format",
+        choices=["json", "openai"],
+        default="json",
+        help="Output format: json (default) or openai (OpenAI function-calling).",
+    )
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    dispatch = {
+        "list": _cmd_list,
+        "schema": _cmd_schema,
+    }
+    dispatch[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

capsolver_agent/langchain_tools.py

@@ -0,0 +1,213 @@
+"""LangChain BaseTool implementations for CapSolver.
+
+Provides ready-to-use LangChain tools that can be plugged directly
+into any LangChain Agent (ReAct, OpenAI Functions, etc.).
+
+Usage:
+    from capsolver_agent.langchain_tools import get_langchain_tools
+
+    tools = get_langchain_tools(api_key="your-api-key")
+    # Pass `tools` to your LangChain agent
+    agent = create_react_agent(llm, tools, ...)
+
+Or import individual tools:
+    from capsolver_agent.langchain_tools import SolveCaptchaTool
+    tool = SolveCaptchaTool(api_key="your-api-key")
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional, Type
+
+try:
+    from langchain_core.tools import BaseTool
+    from pydantic import BaseModel, Field
+
+    _HAS_LANGCHAIN = True
+except ImportError:
+    _HAS_LANGCHAIN = False
+
+    # Provide stubs so the module can be imported without langchain
+    class BaseModel:  # type: ignore[no-redef]
+        pass
+
+    class BaseTool:  # type: ignore[no-redef]
+        def __init_subclass__(cls, **kwargs: Any) -> None:
+            raise ImportError(
+                "langchain-core is required for LangChain tools. Install with: pip install capsolver-agent[langchain]"
+            )
+
+    def Field(*args: Any, **kwargs: Any) -> Any:  # type: ignore[no-redef]
+        return None
+
+
+def _ensure_langchain() -> None:
+    if not _HAS_LANGCHAIN:
+        raise ImportError(
+            "langchain-core is required for LangChain tools. Install with: pip install capsolver-agent[langchain]"
+        )
+
+
+# ── Input Schemas ─────────────────────────────────────────────────
+
+
+class SolveCaptchaInput(BaseModel):
+    """Input schema for SolveCaptchaTool."""
+
+    captcha_type: str = Field(
+        description="Captcha family: reCaptchaV2, reCaptchaV3, or cloudflare."
+    )
+    website_url: str = Field(description="URL of the page where the captcha appears.")
+    website_key: str = Field(description="Site key used by the captcha widget.")
+    version: Optional[str] = Field(default=None, description="reCAPTCHA version: v2 or v3.")
+    page_action: Optional[str] = Field(default=None, description="Action name for reCAPTCHA v3.")
+    min_score: Optional[float] = Field(default=None, description="Minimum score for reCAPTCHA v3 (0.0-1.0).")
+    invisible: Optional[bool] = Field(default=None, description="Whether reCAPTCHA is invisible.")
+    enterprise: Optional[bool] = Field(default=None, description="Whether this is an Enterprise captcha.")
+    s_token: Optional[str] = Field(default=None, description="Enterprise 's' token.")
+    cdata: Optional[str] = Field(default=None, description="Cloudflare Turnstile cdata.")
+    proxy: Optional[str] = Field(default=None, description="Proxy (e.g. http://user:pass@ip:port).")
+    user_agent: Optional[str] = Field(default=None, description="User-Agent string.")
+    timeout: Optional[float] = Field(default=None, description="Max wait time in seconds.")
+    polling_interval: Optional[float] = Field(default=None, description="Polling interval in seconds.")
+
+
+class DetectCaptchasInput(BaseModel):
+    """Input schema for DetectCaptchasTool."""
+
+    page_url: str = Field(description="URL of the page to scan for captchas.")
+
+
+class SolveOnPageInput(BaseModel):
+    """Input schema for SolveOnPageTool."""
+
+    page_url: str = Field(description="URL of the page to solve captchas on.")
+    autofill: Optional[bool] = Field(default=True, description="Autofill solved tokens into the page.")
+    timeout: Optional[float] = Field(default=None, description="Max wait time per captcha.")
+    polling_interval: Optional[float] = Field(default=None, description="Polling interval in seconds.")
+
+
+class EmptyInput(BaseModel):
+    """Empty input for tools that take no parameters."""
+
+    pass
+
+
+# ── Tool Implementations ──────────────────────────────────────────
+
+
+if _HAS_LANGCHAIN:
+    from capsolver_agent.schema import ToolExecutor
+
+    class _CapsolverToolBase(BaseTool):
+        """Shared base for all CapSolver LangChain tools.
+
+        Holds a cached ``ToolExecutor`` so repeated calls reuse the same
+        Capsolver instance instead of constructing a new one each time.
+        """
+
+        api_key: str = ""
+        _executor: ToolExecutor | None = None
+
+        def _get_executor(self) -> ToolExecutor:
+            if self._executor is None:
+                from capsolver_agent.schema import create_executor
+
+                self._executor = create_executor(api_key=self.api_key)
+            return self._executor
+
+        def _run(self, **kwargs: Any) -> dict[str, Any]:
+            raise NotImplementedError("Use arun() — CapSolver tools are async.")
+
+    class SolveCaptchaTool(_CapsolverToolBase):
+        """Solve a captcha via CapSolver API (token mode, no browser required)."""
+
+        name: str = "solve_captcha"
+        description: str = (
+            "Solve a captcha using the CapSolver API. Supports reCaptchaV2, "
+            "reCaptchaV3, and Cloudflare Turnstile. Returns the solved token."
+        )
+        args_schema: Type[BaseModel] = SolveCaptchaInput
+
+        async def _arun(self, **kwargs: Any) -> dict[str, Any]:
+            return await self._get_executor().execute("solve_captcha", kwargs)
+
+    class DetectCaptchasTool(_CapsolverToolBase):
+        """Detect captcha types on a web page (requires playwright)."""
+
+        name: str = "detect_captchas"
+        description: str = (
+            "Scan a web page and detect which captcha types are present. "
+            "Returns a list of detected captcha families. Requires playwright."
+        )
+        args_schema: Type[BaseModel] = DetectCaptchasInput
+
+        async def _arun(self, **kwargs: Any) -> dict[str, Any]:
+            return await self._get_executor().execute("detect_captchas", kwargs)
+
+    class SolveOnPageTool(_CapsolverToolBase):
+        """Detect, solve, and autofill captchas on a page (requires playwright)."""
+
+        name: str = "solve_on_page"
+        description: str = (
+            "One-shot: open a page, detect all captchas, solve them, and autofill tokens. Requires playwright."
+        )
+        args_schema: Type[BaseModel] = SolveOnPageInput
+
+        async def _arun(self, **kwargs: Any) -> dict[str, Any]:
+            return await self._get_executor().execute("solve_on_page", kwargs)
+
+    class GetBalanceTool(_CapsolverToolBase):
+        """Get CapSolver account balance."""
+
+        name: str = "get_balance"
+        description: str = "Get the current CapSolver account balance and package information."
+        args_schema: Type[BaseModel] = EmptyInput
+
+        async def _arun(self, **kwargs: Any) -> dict[str, Any]:
+            return await self._get_executor().execute("get_balance", kwargs)
+
+    class GetSupportedCaptchasTool(_CapsolverToolBase):
+        """List supported captcha types."""
+
+        name: str = "get_supported_captchas"
+        description: str = "List all captcha types supported by this CapSolver instance."
+        args_schema: Type[BaseModel] = EmptyInput
+
+        async def _arun(self, **kwargs: Any) -> dict[str, Any]:
+            return await self._get_executor().execute("get_supported_captchas", kwargs)
+
+else:
+    # Stubs when langchain is not installed
+    SolveCaptchaTool = None  # type: ignore[assignment,misc]
+    DetectCaptchasTool = None  # type: ignore[assignment,misc]
+    SolveOnPageTool = None  # type: ignore[assignment,misc]
+    GetBalanceTool = None  # type: ignore[assignment,misc]
+    GetSupportedCaptchasTool = None  # type: ignore[assignment,misc]
+
+
+# ── Factory ───────────────────────────────────────────────────────
+
+
+def get_langchain_tools(api_key: str | None = None) -> list[Any]:
+    """Create all LangChain tools, ready to pass to an Agent.
+
+    Args:
+        api_key: CapSolver API key. Falls back to CAPSOLVER_API_KEY env var.
+
+    Returns:
+        A list of BaseTool instances.
+
+    Raises:
+        ImportError: If langchain-core is not installed.
+    """
+    _ensure_langchain()
+    key = api_key or os.environ.get("CAPSOLVER_API_KEY", "")
+    return [
+        SolveCaptchaTool(api_key=key),
+        DetectCaptchasTool(api_key=key),
+        SolveOnPageTool(api_key=key),
+        GetBalanceTool(api_key=key),
+        GetSupportedCaptchasTool(api_key=key),
+    ]

capsolver_agent/schema.py

@@ -0,0 +1,468 @@
+"""Framework-agnostic tool schema definitions and executor.
+
+Each tool is described as a ``ToolDef`` — a simple dataclass carrying the
+tool's name, description, and JSON Schema for parameters.  Any agent
+framework (OpenAI function calling, custom orchestrators, etc.) can
+consume these definitions directly.
+
+Usage:
+    from capsolver_agent.schema import get_all_tools, create_executor
+
+    executor = create_executor(api_key="your-key")
+    tools = get_all_tools()
+
+    # Feed tool schemas to your LLM
+    schemas = [t.to_openai_function() for t in tools]
+
+    # Execute a tool call from the LLM response
+    result = await executor.execute("solve_captcha", {
+        "captcha_type": "reCaptchaV2",
+        "website_url": "https://example.com",
+        "website_key": "6Le-wvkSAAAAAPBMRT...",
+    })
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from capsolver_core import Capsolver, CaptchaInfo, CaptchaType
+from capsolver_core.core.errors import CapsolverError, CapsolverTimeoutError, NetworkError, RateLimitError
+
+
+def _error_response(exc: Exception) -> dict[str, Any]:
+    """Build a consistent error dict from an exception.
+
+    Extracts structured fields from CapsolverError when available.
+    """
+    base: dict[str, Any] = {"success": False, "error": str(exc)}
+    if isinstance(exc, CapsolverTimeoutError) and exc.task_id is not None:
+        base["task_id"] = exc.task_id
+    if isinstance(exc, NetworkError) and exc.cause is not None:
+        base["cause"] = str(exc.cause)
+    if isinstance(exc, RateLimitError):
+        base["error_type"] = "rate_limit"
+    if isinstance(exc, CapsolverError):
+        if exc.error_id is not None:
+            base["error_id"] = exc.error_id
+        if exc.error_code:
+            base["error_code"] = exc.error_code
+        if exc.error_description:
+            base["error_description"] = exc.error_description
+        if exc.http_status is not None:
+            base["http_status"] = exc.http_status
+    return base
+
+
+# ── Tool Schema ───────────────────────────────────────────────────
+
+
+@dataclass
+class ToolDef:
+    """Framework-agnostic definition of a single tool."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema object
+
+    def to_openai_function(self) -> dict[str, Any]:
+        """Convert to OpenAI function-calling format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_json_schema(self) -> dict[str, Any]:
+        """Return the full tool spec as a JSON-schema-compatible dict."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.parameters,
+        }
+
+
+# ── Tool Definitions ─────────────────────────────────────────────
+
+
+_SOLVE_CAPTCHA_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "captcha_type": {
+            "type": "string",
+            "enum": ["reCaptchaV2", "reCaptchaV3", "cloudflare"],
+            "description": "The captcha family to solve.",
+        },
+        "website_url": {
+            "type": "string",
+            "description": "The URL of the page where the captcha appears.",
+        },
+        "website_key": {
+            "type": "string",
+            "description": "The site key used by the captcha widget.",
+        },
+        "version": {
+            "type": ["string", "null"],
+            "enum": ["v2", "v3", None],
+            "description": "reCAPTCHA version (v2 or v3). Only for reCAPTCHA.",
+        },
+        "page_action": {
+            "type": ["string", "null"],
+            "description": "The action name for reCAPTCHA v3.",
+        },
+        "min_score": {
+            "type": ["number", "null"],
+            "description": "Minimum score for reCAPTCHA v3 (0.0 - 1.0).",
+        },
+        "invisible": {
+            "type": ["boolean", "null"],
+            "description": "Whether the reCAPTCHA widget uses invisible mode.",
+        },
+        "enterprise": {
+            "type": ["boolean", "null"],
+            "description": "Whether this is an Enterprise captcha.",
+        },
+        "s_token": {
+            "type": ["string", "null"],
+            "description": "Enterprise 's' token.",
+        },
+        "cdata": {
+            "type": ["string", "null"],
+            "description": "Cloudflare Turnstile cdata parameter.",
+        },
+        "proxy": {
+            "type": ["string", "null"],
+            "description": "Proxy string (e.g. http://user:pass@ip:port).",
+        },
+        "user_agent": {
+            "type": ["string", "null"],
+            "description": "User-Agent string to use for solving.",
+        },
+        "timeout": {
+            "type": ["number", "null"],
+            "description": "Max seconds to wait for a solution (default: 120).",
+        },
+        "polling_interval": {
+            "type": ["number", "null"],
+            "description": "Seconds between polling attempts (default: 5).",
+        },
+    },
+    "required": ["captcha_type", "website_url", "website_key"],
+}
+
+_DETECT_CAPTCHAS_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "page_url": {
+            "type": "string",
+            "description": "URL of the page to scan for captchas.",
+        },
+    },
+    "required": ["page_url"],
+}
+
+_SOLVE_ON_PAGE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "page_url": {
+            "type": "string",
+            "description": "URL of the page to solve captchas on.",
+        },
+        "autofill": {
+            "type": ["boolean", "null"],
+            "description": "Whether to autofill solved tokens into the page (default: true).",
+        },
+        "timeout": {
+            "type": ["number", "null"],
+            "description": "Max seconds to wait per captcha.",
+        },
+        "polling_interval": {
+            "type": ["number", "null"],
+            "description": "Seconds between polling attempts.",
+        },
+    },
+    "required": ["page_url"],
+}
+
+_GET_BALANCE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {},
+    "required": [],
+}
+
+_GET_SUPPORTED_CAPTCHAS_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {},
+    "required": [],
+}
+
+
+def get_all_tools() -> list[ToolDef]:
+    """Return framework-agnostic definitions for all CapSolver tools."""
+    return [
+        ToolDef(
+            name="solve_captcha",
+            description=(
+                "Solve a captcha via the CapSolver API (token mode, no browser required). "
+                "Supports reCaptchaV2, reCaptchaV3, and Cloudflare Turnstile. "
+                "Returns the solved token that can be submitted with a form or injected into a page."
+            ),
+            parameters=_SOLVE_CAPTCHA_SCHEMA,
+        ),
+        ToolDef(
+            name="detect_captchas",
+            description=(
+                "Scan a web page and detect which captcha types are present. "
+                "Returns a list of captcha families found on the page. "
+                "Requires browser automation support (playwright)."
+            ),
+            parameters=_DETECT_CAPTCHAS_SCHEMA,
+        ),
+        ToolDef(
+            name="solve_on_page",
+            description=(
+                "One-shot operation: open a page in a browser, detect all captchas, "
+                "solve them, and optionally autofill the solved tokens back into the page. "
+                "Requires browser automation support (playwright)."
+            ),
+            parameters=_SOLVE_ON_PAGE_SCHEMA,
+        ),
+        ToolDef(
+            name="get_balance",
+            description="Get the current CapSolver account balance and package information.",
+            parameters=_GET_BALANCE_SCHEMA,
+        ),
+        ToolDef(
+            name="get_supported_captchas",
+            description="List all captcha types and handler names supported by this CapSolver instance.",
+            parameters=_GET_SUPPORTED_CAPTCHAS_SCHEMA,
+        ),
+    ]
+
+
+# ── Executor ──────────────────────────────────────────────────────
+
+
+class ToolExecutor:
+    """Executes tool calls against a Capsolver instance.
+
+    This is the bridge between LLM-generated tool calls and the SDK.
+    """
+
+    def __init__(self, capsolver: Capsolver) -> None:
+        self._capsolver = capsolver
+
+    async def execute(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        """Dispatch a tool call by name and return the result.
+
+        Args:
+            tool_name: One of the registered tool names.
+            arguments: Keyword arguments matching the tool's JSON schema.
+
+        Returns:
+            A JSON-serializable dict with the result or error.
+        """
+        dispatch = {
+            "solve_captcha": self._solve_captcha,
+            "detect_captchas": self._detect_captchas,
+            "solve_on_page": self._solve_on_page,
+            "get_balance": self._get_balance,
+            "get_supported_captchas": self._get_supported_captchas,
+        }
+
+        handler = dispatch.get(tool_name)
+        if handler is None:
+            return {"success": False, "error": f"Unknown tool: {tool_name}. Available: {list(dispatch.keys())}"}
+
+        try:
+            return await handler(arguments)
+        except Exception as e:
+            return _error_response(e)
+
+    # ── private handlers ──────────────────────────────────────────
+
+    async def _solve_captcha(self, args: dict[str, Any]) -> dict[str, Any]:
+        try:
+            ct = CaptchaType(args["captcha_type"])
+        except (ValueError, KeyError) as e:
+            return {"success": False, "error": f"Invalid captcha_type: {e}"}
+
+        info = CaptchaInfo(
+            type=ct,
+            website_url=args.get("website_url", ""),
+            website_key=args.get("website_key", ""),
+            version=args.get("version"),
+            page_action=args.get("page_action"),
+            min_score=args.get("min_score"),
+            invisible=args.get("invisible"),
+            enterprise=args.get("enterprise"),
+            s=args.get("s_token"),
+            cdata=args.get("cdata"),
+            proxy=args.get("proxy"),
+            user_agent=args.get("user_agent"),
+        )
+
+        from capsolver_core.core.client import WaitOptions
+
+        wait_opts = None
+        timeout = args.get("timeout")
+        interval = args.get("polling_interval")
+        if timeout is not None or interval is not None:
+            wait_opts = WaitOptions(timeout=timeout, polling_interval=interval)
+
+        solution = await self._capsolver.solve(info, wait_options=wait_opts)
+        return {
+            "success": True,
+            "solution": {
+                "captcha_type": solution.captcha_type.value,
+                "token": solution.token,
+                "expire_time": solution.expire_time,
+                "user_agent": solution.user_agent,
+            },
+        }
+
+    async def _detect_captchas(self, args: dict[str, Any]) -> dict[str, Any]:
+        page_url = args.get("page_url", "")
+        if not page_url:
+            return {"success": False, "error": "page_url is required"}
+
+        try:
+            driver = await _launch_browser(page_url)
+        except ImportError:
+            return {"success": False, "error": "playwright is required. Install: pip install capsolver-agent[browser]"}
+
+        try:
+            detected = await self._capsolver.detect(driver)
+            return {
+                "success": True,
+                "url": page_url,
+                "detected_captchas": [t.value for t in detected],
+            }
+        finally:
+            await _close_browser(driver)
+
+    async def _solve_on_page(self, args: dict[str, Any]) -> dict[str, Any]:
+        page_url = args.get("page_url", "")
+        if not page_url:
+            return {"success": False, "error": "page_url is required"}
+
+        try:
+            driver = await _launch_browser(page_url)
+        except ImportError:
+            return {"success": False, "error": "playwright is required. Install: pip install capsolver-agent[browser]"}
+
+        try:
+            from capsolver_core.capsolver import SolveOnPageOptions
+
+            opts = SolveOnPageOptions(
+                autofill=args.get("autofill", True),
+                throw_on_error=False,
+                timeout=args.get("timeout"),
+                polling_interval=args.get("polling_interval"),
+            )
+            results = await self._capsolver.solve_on_page(driver, options=opts)
+            return {
+                "success": True,
+                "url": page_url,
+                "results": [
+                    {
+                        "captcha_type": r.info.type.value,
+                        "solved": r.solution is not None,
+                        "token": r.solution.token if r.solution else None,
+                        "filled": r.filled,
+                        "error": r.error,
+                    }
+                    for r in results
+                ],
+            }
+        finally:
+            await _close_browser(driver)
+
+    async def _get_balance(self, _args: dict[str, Any]) -> dict[str, Any]:
+        balance = await self._capsolver.get_balance()
+        return {"success": True, "balance": balance.balance, "packages": balance.packages}
+
+    async def _get_supported_captchas(self, _args: dict[str, Any]) -> dict[str, Any]:
+        handlers = self._capsolver.get_supported_captchas()
+        return {
+            "success": True,
+            "registered_handlers": handlers,
+            "captcha_types": [t.value for t in CaptchaType],
+        }
+
+
+def create_executor(
+    api_key: str | None = None,
+    **capsolver_kwargs: Any,
+) -> ToolExecutor:
+    """Create a ToolExecutor backed by a Capsolver instance.
+
+    Args:
+        api_key: CapSolver API key. Falls back to CAPSOLVER_API_KEY env var.
+        **capsolver_kwargs: Extra arguments forwarded to Capsolver(...).
+    """
+    key = api_key or os.environ.get("CAPSOLVER_API_KEY", "")
+    capsolver = Capsolver(api_key=key, **capsolver_kwargs)
+    return ToolExecutor(capsolver)
+
+
+# Convenience: module-level executor for quick usage
+async def execute_tool(
+    tool_name: str,
+    arguments: dict[str, Any],
+    api_key: str | None = None,
+) -> dict[str, Any]:
+    """One-shot convenience: create an executor and run a single tool call.
+
+    For repeated calls, prefer ``create_executor()`` to reuse the same instance.
+    """
+    executor = create_executor(api_key=api_key)
+    return await executor.execute(tool_name, arguments)
+
+
+# ── Browser helpers (shared with MCP server) ──────────────────────
+
+
+async def _launch_browser(page_url: str) -> Any:
+    """Launch headless Chromium and navigate to page_url. Returns a PageDriver."""
+    try:
+        from playwright.async_api import async_playwright
+    except ImportError:
+        raise
+
+    from capsolver_core.browser.adapter import from_playwright_page
+
+    pw = await async_playwright().start()
+    browser = await pw.chromium.launch(headless=True)
+    page = await browser.new_page()
+    await page.goto(page_url, wait_until="domcontentloaded", timeout=30_000)
+
+    # Captcha widgets (reCAPTCHA api.js, Turnstile) load asynchronously after
+    # DOMContentLoaded. Wait for the network to settle so their scripts can
+    # register before we detect — bounded so pages with long-lived
+    # connections don't hang. Best-effort: ignore timeout.
+    try:
+        await page.wait_for_load_state("networkidle", timeout=5_000)
+    except Exception:
+        pass
+
+    driver = from_playwright_page(page)
+    setattr(driver, "_pw", pw)
+    setattr(driver, "_browser", browser)
+    return driver
+
+
+async def _close_browser(driver: Any) -> None:
+    """Clean up browser resources."""
+    try:
+        if hasattr(driver, "_browser") and driver._browser:
+            await driver._browser.close()
+        if hasattr(driver, "_pw") and driver._pw:
+            await driver._pw.stop()
+    except Exception:
+        pass

capsolver_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: capsolver-agent
+Version: 0.1.0
+Summary: Agent integrations for CapSolver — framework-agnostic tool definitions + LangChain tools.
+Project-URL: Homepage, https://capsolver.com
+Project-URL: Repository, https://github.com/capsolver-ai/agent-capsolver
+Project-URL: Issues, https://github.com/capsolver-ai/agent-capsolver/issues
+Project-URL: Documentation, https://github.com/capsolver-ai/agent-capsolver/blob/main/docs/agent-integration.md
+Project-URL: Changelog, https://github.com/capsolver-ai/agent-capsolver/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/capsolver-ai/agent-capsolver/blob/main/SECURITY.md
+Author-email: capsolver-ai <dev@capsolver.ai>
+License-Expression: ISC
+License-File: LICENSE
+Keywords: agent,ai-agent,capsolver,captcha,langchain,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: capsolver-core>=0.1.0
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# capsolver-agent
+
+Agent integrations for [CapSolver](https://capsolver.com) — framework-agnostic tool definitions and LangChain BaseTool implementations.
+
+See the [capsolver-ai](https://github.com/capsolver-ai/capsolver-ai) hub repo for integration examples and the full documentation.
+
+For framework integration guides (OpenAI, LangChain, LlamaIndex, CrewAI, Google ADK, and more), see [docs/agent-integration.md](docs/agent-integration.md).
+
+## Install
+
+```bash
+pip install capsolver-agent
+pip install capsolver-agent[langchain]   # with LangChain support
+pip install capsolver-agent[browser]     # with Playwright support (for detect/solve_on_page)
+```
+
+All packages read the API key from the environment:
+
+```bash
+# bash / zsh
+export CAPSOLVER_API_KEY="your-capsolver-api-key"
+
+# PowerShell
+$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
+
+# cmd
+set CAPSOLVER_API_KEY=your-capsolver-api-key
+```
+
+## Framework-agnostic tools (any LLM / agent framework)
+
+Use `schema.py` to get tool schemas as JSON and an async executor to run tool calls. Works with OpenAI function calling, OpenAI Agents SDK, Browser Use, or any custom agent loop.
+
+```python
+import asyncio
+from capsolver_agent.schema import get_all_tools, create_executor
+
+async def main():
+    # 1. Get tool schemas — feed to your LLM's function-calling API
+    tools = get_all_tools()
+    openai_functions = [t.to_openai_function() for t in tools]
+
+    # 2. Execute a tool call returned by the LLM
+    executor = create_executor(api_key="YOUR_API_KEY")
+    result = await executor.execute("solve_captcha", {
+        "captcha_type": "reCaptchaV2",
+        "website_url": "https://example.com",
+        "website_key": "6Le-wvkSAAAAAPBMRT...",
+    })
+    print(result)
+    # {"success": True, "solution": {"token": "03AF...", ...}}
+
+asyncio.run(main())
+```
+
+Each `ToolDef` provides two export formats:
+
+```python
+tool = get_all_tools()[0]
+tool.to_openai_function()  # → OpenAI function-calling schema
+tool.to_json_schema()      # → MCP-style tool descriptor (name + inputSchema)
+```
+
+For a quick one-shot call without creating an executor:
+
+```python
+from capsolver_agent.schema import execute_tool
+
+result = await execute_tool("solve_captcha", {
+    "captcha_type": "reCaptchaV2",
+    "website_url": "https://example.com",
+    "website_key": "6Le-wvkSAAAAAPBMRT...",
+}, api_key="YOUR_API_KEY")
+```
+
+## LangChain integration
+
+Pre-built `BaseTool` subclasses with Pydantic input schemas — plug directly into any LangChain agent.
+
+```python
+import asyncio
+from capsolver_agent.langchain_tools import get_langchain_tools
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+tools = get_langchain_tools(api_key="YOUR_API_KEY")
+
+llm = ChatOpenAI(model="gpt-4o")
+agent = create_react_agent(llm, tools)
+
+async def main():
+    result = await agent.ainvoke({"messages": [...]})
+
+asyncio.run(main())
+```
+
+Or import individual tools:
+
+```python
+from capsolver_agent.langchain_tools import SolveCaptchaTool, GetBalanceTool
+
+solver = SolveCaptchaTool(api_key="YOUR_API_KEY")
+balance = GetBalanceTool(api_key="YOUR_API_KEY")
+```
+
+## CLI
+
+The `capsolver-agent` command lets you inspect available tools and their schemas from the terminal.
+
+```bash
+# List all tools with descriptions
+capsolver-agent list
+
+# Show JSON Schema for a specific tool
+capsolver-agent schema solve_captcha
+
+# Export all tools in OpenAI function-calling format
+capsolver-agent schema --format openai
+
+# Export one tool in OpenAI format
+capsolver-agent schema --format openai detect_captchas
+```
+
+Also works via `python -m capsolver_agent list`.
+
+## Available tools
+
+| Tool | Browser? | Description |
+|---|---|---|
+| `solve_captcha` | No | Token-mode solving — provide type + URL + site key, get a token back |
+| `detect_captchas` | Yes | Scan a page URL and return which captcha types are present |
+| `solve_on_page` | Yes | One-shot: detect + solve + autofill all captchas on a page |
+| `get_balance` | No | Check account balance and packages |
+| `get_supported_captchas` | No | List all supported captcha types and handler names |
+
+Browser-based tools require `pip install capsolver-agent[browser]` and `playwright install chromium`.
+
+## Integration examples
+
+See the [capsolver-ai examples](https://github.com/capsolver-ai/capsolver-ai/tree/main/examples) for runnable demos:
+
+- `openai_function_calling.py` — agentic loop with OpenAI function calling
+- `openai_agents.py` — OpenAI Agents SDK with `@function_tool`
+- `langchain_agent.py` — LangChain ReAct agent
+- `browser_use_agent.py` — Browser Use with `@tools.action()`
+
+## Development
+
+```bash
+git clone https://github.com/capsolver-ai/agent-capsolver.git
+cd agent-capsolver
+uv sync --all-extras          # or: pip install -r requirements-dev.txt
+uv run pytest                 # run tests
+uv run ruff check src tests   # lint
+```
+
+## License
+
+ISC

capsolver_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+capsolver_agent/__init__.py,sha256=zsm76h8RrmBl_zp6oaFqxbI07vcns_6HzomurF0Tb8k,889
+capsolver_agent/__main__.py,sha256=doKy3xdhM5PVUo7Yjluj14mCjzfjjETWT9eSKv_NrMg,3516
+capsolver_agent/langchain_tools.py,sha256=OxZAhuxKmkxaUQqYPbkBBiRlkCiPVQKun8AZJvfovRA,8732
+capsolver_agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+capsolver_agent/schema.py,sha256=5K7AQehx41vZ18Zzf5UQ2dPyTzxhdhmzBlW5ewakkuY,17032
+capsolver_agent-0.1.0.dist-info/METADATA,sha256=HNewsp4sqs0-yteLcT5BfrXJeGjoxClW5no2rUXO09k,6675
+capsolver_agent-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+capsolver_agent-0.1.0.dist-info/entry_points.txt,sha256=C-Y78xkd0ECZQfs6qXJUXJDHE7x6Vs24Jy3HK3dvi5M,66
+capsolver_agent-0.1.0.dist-info/licenses/LICENSE,sha256=p65mlslnCknoxoEoP3lESj40mUaZRt2xzgMlrGE72hM,763
+capsolver_agent-0.1.0.dist-info/RECORD,,

capsolver_agent-0.1.0.dist-info/WHEEL

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

capsolver_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+capsolver-agent = capsolver_agent.__main__:main

capsolver_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 capsolver-ai
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.