solvecha 0.1.0__py3-none-any.whl

solvecha/__init__.py

@@ -0,0 +1,27 @@
+"""Solvecha: captcha solving for scripts and AI agents."""
+
+from .client import AsyncSolvecha, Solvecha
+from .errors import (
+    InvalidKeyError,
+    InvalidRequestError,
+    OutOfCreditError,
+    RateLimitError,
+    SolvechaError,
+    SolveTimeoutError,
+)
+from .results import GeetestResult, GridResult, TextResult
+
+__all__ = [
+    "AsyncSolvecha",
+    "Solvecha",
+    "GridResult",
+    "TextResult",
+    "GeetestResult",
+    "SolvechaError",
+    "InvalidKeyError",
+    "InvalidRequestError",
+    "OutOfCreditError",
+    "RateLimitError",
+    "SolveTimeoutError",
+]
+__version__ = "0.1.0"

solvecha/browser_use_action.py

@@ -0,0 +1,48 @@
+# No "from __future__ import annotations" here: Browser Use reads the real
+# annotation objects to inject its browser_session argument.
+import json
+from typing import Any, Optional
+
+from browser_use import ActionResult, BrowserSession, Tools
+
+from .client import AsyncSolvecha
+from .errors import SolvechaError
+
+FIND_CHALLENGE = """(() => {
+    const f = document.querySelector('iframe[src*="recaptcha/api2/bframe"], iframe[src*="recaptcha/enterprise/bframe"]');
+    if (!f) return null;
+    const r = f.getBoundingClientRect();
+    return r.width > 50 && r.height > 50 ? JSON.stringify({x: r.x, y: r.y, width: r.width, height: r.height}) : null;
+})()"""
+
+
+def register(client: AsyncSolvecha, tools: Optional[Any] = None) -> Any:
+    tools = tools or Tools()
+
+    @tools.action(
+        description=(
+            "Solve the reCAPTCHA v2 image challenge that is open in the current tab. Pass the instruction text "
+            "(e.g. 'Select all images with buses') and the grid ('3x3' or '4x4'). Returns the tile numbers to click, "
+            "counted from 1, left to right, top to bottom, and a job id."
+        )
+    )
+    async def solve_recaptcha_in_tab(task: str, grid: str, browser_session: BrowserSession) -> ActionResult:
+        clip = None
+        try:
+            page = await browser_session.must_get_current_page()
+            raw = await page.evaluate(FIND_CHALLENGE)
+            if isinstance(raw, str) and raw not in ("", "null"):
+                box = json.loads(raw)
+                clip = {"x": box["x"], "y": box["y"], "width": box["width"], "height": box["height"], "scale": 1}
+        except Exception:  # noqa: BLE001 - cropping is optional
+            clip = None
+        png = await browser_session.take_screenshot(clip=clip) if clip else await browser_session.take_screenshot()
+        try:
+            result = await client.solve_recaptcha(task, grid, png)
+        except (SolvechaError, ValueError) as error:
+            return ActionResult(error=str(error))
+        return ActionResult(
+            extracted_content=f"Click tiles {result.tiles} ({'; '.join(result.positions)}), then press Verify. job_id={result.job_id}"
+        )
+
+    return tools

solvecha/client.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, Optional, Sequence, Union
+
+import httpx
+
+from . import core
+from .core import Image
+from .errors import SolveTimeoutError, error_for
+from .results import GeetestResult, GridResult, TextResult
+
+DEFAULT_TIMEOUT = 45.0
+POLL_INTERVAL = 1.0
+
+
+def _body(response: httpx.Response) -> Dict[str, Any]:
+    try:
+        parsed = response.json()
+    except ValueError:
+        return {"error": 9, "message": f"HTTP {response.status_code}"}
+    return parsed if isinstance(parsed, dict) else {"data": parsed}
+
+
+class Solvecha:
+    """Synchronous client. ``api_key`` defaults to the SOLVECHA_API_KEY environment variable."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = core.DEFAULT_BASE_URL,
+        http: Optional[httpx.Client] = None,
+        poll_interval: float = POLL_INTERVAL,
+    ):
+        self._key = core.resolve_key(api_key)
+        self._poll = poll_interval
+        self._http = http or httpx.Client(timeout=30)
+        self._base = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, json: Any = None) -> Dict[str, Any]:
+        response = self._http.request(method, self._base + path, json=json, headers=core.headers(self._key))
+        return _body(response)
+
+    def solve(self, kind: str, payload: Dict[str, Any], timeout: float = DEFAULT_TIMEOUT) -> tuple:
+        """Create a job and wait for the answer. Returns (job_id, data)."""
+        job_id = core.job_id_from(self._request("POST", f"/v1/recognition/{kind}", payload))
+        deadline = time.monotonic() + timeout
+        while True:
+            time.sleep(self._poll)
+            answer = self._request("GET", f"/v1/recognition/{kind}?id={job_id}")
+            code = core.error_code(answer)
+            if code == 0 and "data" in answer:
+                return job_id, answer["data"]
+            if code == 14:
+                pass
+            elif code == 11:
+                time.sleep(2)
+            else:
+                raise error_for(code or 9, str(answer.get("message", "")))
+            if time.monotonic() >= deadline:
+                raise SolveTimeoutError(job_id, timeout)
+
+    def solve_recaptcha(
+        self, task: str, grid: str, images: Union[Image, Sequence[Image]], timeout: float = DEFAULT_TIMEOUT
+    ) -> GridResult:
+        pictures = core.images_payload(images)
+        core.check_grid(grid, len(pictures))
+        job_id, data = self.solve("recaptcha", {"task": task, "grid": grid, "image_data": pictures}, timeout)
+        return GridResult(job_id, grid, list(data))
+
+    def solve_text(self, image: Image, timeout: float = DEFAULT_TIMEOUT) -> TextResult:
+        job_id, data = self.solve("textcaptcha", {"image_data": core.images_payload(image)}, timeout)
+        return TextResult(job_id, data[0])
+
+    def solve_geetest(
+        self, images: Union[Image, Sequence[Image]], task: str = "slide", timeout: float = DEFAULT_TIMEOUT
+    ) -> GeetestResult:
+        job_id, data = self.solve("geetest", {"task": task, "image_data": core.images_payload(images)}, timeout)
+        return GeetestResult(job_id, float(data["x"]))
+
+    def solve_funcaptcha(self, task: str, image: Image, match: bool = False, timeout: float = DEFAULT_TIMEOUT) -> GridResult:
+        kind = "funcaptcha_match" if match else "funcaptcha"
+        job_id, data = self.solve(kind, {"task": task, "image_data": core.images_payload(image)}, timeout)
+        return GridResult(job_id, "funcaptcha", list(data))
+
+    def status(self) -> Dict[str, Any]:
+        body = self._request("GET", "/v1/status")
+        if core.error_code(body):
+            raise error_for(core.error_code(body), str(body.get("message", "")))
+        return body
+
+    def report_result(self, job_id: str, verdict: str, grid: str, round_index: Optional[int] = None) -> bool:
+        payload: Dict[str, Any] = {"job_id": job_id, "verdict": verdict, "grid": grid}
+        if round_index is not None:
+            payload["round_index"] = round_index
+        body = self._request("POST", "/v1/feedback", payload)
+        if core.error_code(body):
+            raise error_for(core.error_code(body), str(body.get("message", "")))
+        return True
+
+    def close(self) -> None:
+        self._http.close()
+
+
+class AsyncSolvecha:
+    """Asynchronous client with the same methods as :class:`Solvecha`."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = core.DEFAULT_BASE_URL,
+        http: Optional[httpx.AsyncClient] = None,
+        poll_interval: float = POLL_INTERVAL,
+    ):
+        self._key = core.resolve_key(api_key)
+        self._poll = poll_interval
+        self._http = http or httpx.AsyncClient(timeout=30)
+        self._base = base_url.rstrip("/")
+
+    async def _request(self, method: str, path: str, json: Any = None) -> Dict[str, Any]:
+        response = await self._http.request(method, self._base + path, json=json, headers=core.headers(self._key))
+        return _body(response)
+
+    async def solve(self, kind: str, payload: Dict[str, Any], timeout: float = DEFAULT_TIMEOUT) -> tuple:
+        job_id = core.job_id_from(await self._request("POST", f"/v1/recognition/{kind}", payload))
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            await asyncio.sleep(self._poll)
+            answer = await self._request("GET", f"/v1/recognition/{kind}?id={job_id}")
+            code = core.error_code(answer)
+            if code == 0 and "data" in answer:
+                return job_id, answer["data"]
+            if code == 14:
+                pass
+            elif code == 11:
+                await asyncio.sleep(2)
+            else:
+                raise error_for(code or 9, str(answer.get("message", "")))
+            if loop.time() >= deadline:
+                raise SolveTimeoutError(job_id, timeout)
+
+    async def solve_recaptcha(
+        self, task: str, grid: str, images: Union[Image, Sequence[Image]], timeout: float = DEFAULT_TIMEOUT
+    ) -> GridResult:
+        pictures = core.images_payload(images)
+        core.check_grid(grid, len(pictures))
+        job_id, data = await self.solve("recaptcha", {"task": task, "grid": grid, "image_data": pictures}, timeout)
+        return GridResult(job_id, grid, list(data))
+
+    async def solve_text(self, image: Image, timeout: float = DEFAULT_TIMEOUT) -> TextResult:
+        job_id, data = await self.solve("textcaptcha", {"image_data": core.images_payload(image)}, timeout)
+        return TextResult(job_id, data[0])
+
+    async def solve_geetest(
+        self, images: Union[Image, Sequence[Image]], task: str = "slide", timeout: float = DEFAULT_TIMEOUT
+    ) -> GeetestResult:
+        job_id, data = await self.solve("geetest", {"task": task, "image_data": core.images_payload(images)}, timeout)
+        return GeetestResult(job_id, float(data["x"]))
+
+    async def solve_funcaptcha(
+        self, task: str, image: Image, match: bool = False, timeout: float = DEFAULT_TIMEOUT
+    ) -> GridResult:
+        kind = "funcaptcha_match" if match else "funcaptcha"
+        job_id, data = await self.solve(kind, {"task": task, "image_data": core.images_payload(image)}, timeout)
+        return GridResult(job_id, "funcaptcha", list(data))
+
+    async def status(self) -> Dict[str, Any]:
+        body = await self._request("GET", "/v1/status")
+        if core.error_code(body):
+            raise error_for(core.error_code(body), str(body.get("message", "")))
+        return body
+
+    async def report_result(self, job_id: str, verdict: str, grid: str, round_index: Optional[int] = None) -> bool:
+        payload: Dict[str, Any] = {"job_id": job_id, "verdict": verdict, "grid": grid}
+        if round_index is not None:
+            payload["round_index"] = round_index
+        body = await self._request("POST", "/v1/feedback", payload)
+        if core.error_code(body):
+            raise error_for(core.error_code(body), str(body.get("message", "")))
+        return True
+
+    async def aclose(self) -> None:
+        await self._http.aclose()

solvecha/core.py

@@ -0,0 +1,71 @@
+"""Pure helpers shared by the sync and the async client."""
+from __future__ import annotations
+
+import base64
+import os
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .errors import SolvechaError, error_for
+
+DEFAULT_BASE_URL = "https://api.solvecha.com"
+GRIDS = ("3x3", "4x4", "1x1")
+Image = Union[str, bytes, "os.PathLike[str]"]
+
+
+def to_base64(image: Image) -> str:
+    """Accept a file path, raw bytes, base64 text or a data: URL and return plain base64."""
+    if isinstance(image, (bytes, bytearray)):
+        return base64.b64encode(bytes(image)).decode()
+    text = os.fspath(image)
+    if text.startswith("data:"):
+        return text.split(",", 1)[1]
+    if len(text) < 1024 and os.path.isfile(text):
+        with open(text, "rb") as handle:
+            return base64.b64encode(handle.read()).decode()
+    return "".join(text.split())
+
+
+def images_payload(images: Union[Image, Sequence[Image]]) -> List[str]:
+    if isinstance(images, (str, bytes, bytearray)) or hasattr(images, "__fspath__"):
+        images = [images]  # type: ignore[list-item]
+    return [to_base64(i) for i in images]  # type: ignore[union-attr]
+
+
+def check_grid(grid: str, count: int) -> None:
+    if grid not in GRIDS:
+        raise ValueError(f"grid must be one of {GRIDS}, got {grid!r}")
+    if grid != "1x1" and count != 1:
+        raise ValueError(f"grid {grid} needs exactly one picture of the whole grid, got {count}")
+    if grid == "1x1" and not 1 <= count <= 9:
+        raise ValueError("grid 1x1 needs 1 to 9 tile pictures")
+
+
+def error_code(body: Dict[str, Any]) -> int:
+    value = body.get("error")
+    if value is None:
+        return 0
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 9
+
+
+def job_id_from(body: Dict[str, Any]) -> str:
+    code = error_code(body)
+    if code:
+        raise error_for(code, str(body.get("message", "")))
+    data = body.get("data")
+    if not isinstance(data, str) or not data:
+        raise SolvechaError(9, "no job id in the answer")
+    return data
+
+
+def headers(api_key: str) -> Dict[str, str]:
+    return {"Authorization": f"Bearer {api_key}", "User-Agent": "solvecha-python/0.1"}
+
+
+def resolve_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("SOLVECHA_API_KEY", "")
+    if not key:
+        raise error_for(15, "no key")
+    return key

solvecha/errors.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+KEY_HELP = "Create a key at https://solvecha.com/dashboard and set SOLVECHA_API_KEY."
+
+_ADVICE = {
+    9: "Temporary error, or the image could not be solved. Retry once with a fresh image. You are not charged.",
+    10: "Invalid request. Check the task text, the grid and the images.",
+    11: "Rate limit reached. Wait 10 to 60 seconds and try again.",
+    15: "The API key is missing or wrong. " + KEY_HELP,
+    16: "Out of credit. Top up the balance or pick a plan at https://solvecha.com/dashboard. Do not retry.",
+}
+
+
+class SolvechaError(Exception):
+    """An error answer of the Solvecha API. ``code`` is the API error code."""
+
+    def __init__(self, code: int, message: str = ""):
+        self.code = code
+        self.api_message = message
+        super().__init__(f"Solvecha error {code}: {_ADVICE.get(code, message or 'unexpected answer')}")
+
+
+class InvalidRequestError(SolvechaError):
+    pass
+
+
+class RateLimitError(SolvechaError):
+    pass
+
+
+class InvalidKeyError(SolvechaError):
+    pass
+
+
+class OutOfCreditError(SolvechaError):
+    pass
+
+
+class SolveTimeoutError(SolvechaError, TimeoutError):
+    def __init__(self, job_id: str, seconds: float):
+        self.job_id = job_id
+        SolvechaError.__init__(self, 14, "")
+        self.args = (f"No answer within {seconds:g} seconds (job {job_id}). You were not charged.",)
+
+
+_BY_CODE = {10: InvalidRequestError, 11: RateLimitError, 15: InvalidKeyError, 16: OutOfCreditError}
+
+
+def error_for(code: int, message: str = "") -> SolvechaError:
+    return _BY_CODE.get(code, SolvechaError)(code, message)

solvecha/results.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+_COLUMNS = {"3x3": 3, "4x4": 4}
+
+
+@dataclass
+class GridResult:
+    """Answer for an image grid. ``tiles`` are counted from 1, left to right, top to bottom."""
+
+    job_id: str
+    grid: str
+    answer: List[bool]
+    tiles: List[int] = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.tiles = [i + 1 for i, picked in enumerate(self.answer) if picked]
+
+    @property
+    def positions(self) -> List[str]:
+        columns = _COLUMNS.get(self.grid)
+        if not columns:
+            return []
+        return [f"row {(t - 1) // columns + 1}, column {(t - 1) % columns + 1}" for t in self.tiles]
+
+
+@dataclass
+class TextResult:
+    job_id: str
+    text: str
+
+
+@dataclass
+class GeetestResult:
+    """``offset_percent`` is the drag distance as a percentage of the background width."""
+
+    job_id: str
+    offset_percent: float

solvecha/tools.py

@@ -0,0 +1,186 @@
+"""Ready-made agent tools for Solvecha.
+
+Every function returns a plain dict. Errors never raise inside a tool: the dict
+holds an ``error`` text that tells the model what to do next.
+
+    from solvecha import Solvecha
+    from solvecha.tools import langchain_tools
+    tools = langchain_tools(Solvecha())
+
+The framework packages are imported only when you call its function.
+"""
+import functools
+import json
+from typing import Any, Callable, Dict, List, Optional
+
+from .client import AsyncSolvecha, Solvecha
+from .errors import SolvechaError
+
+Func = Callable[..., Dict[str, Any]]
+
+TOOL_SPECS: List[Dict[str, Any]] = [
+    {
+        "name": "solve_recaptcha_grid",
+        "description": (
+            "Solve a reCAPTCHA v2 image challenge from a picture of the grid. Returns selected_tiles: the tiles "
+            "to click, counted from 1, left to right, top to bottom. Costs one credit per successful solve."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "task": {"type": "string", "description": "The instruction text, e.g. 'Select all images with buses'."},
+                "grid": {"type": "string", "enum": ["3x3", "4x4", "1x1"], "description": "Layout of the challenge."},
+                "image": {"type": "string", "description": "Path of a PNG/JPEG file, or base64 of the grid picture."},
+            },
+            "required": ["task", "grid", "image"],
+        },
+    },
+    {
+        "name": "solve_text_captcha",
+        "description": "Read a picture of distorted text. Returns the case-sensitive text. Costs one credit per successful solve.",
+        "parameters": {
+            "type": "object",
+            "properties": {"image": {"type": "string", "description": "Path of a picture file, or base64."}},
+            "required": ["image"],
+        },
+    },
+    {
+        "name": "get_account_status",
+        "description": "Show the plan, the solves left today and the balance. Free.",
+        "parameters": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "report_result",
+        "description": "Tell Solvecha whether a reCAPTCHA answer was accepted or rejected. Free and optional.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "job_id": {"type": "string"},
+                "verdict": {"type": "string", "enum": ["accepted", "rejected"]},
+                "grid": {"type": "string", "enum": ["3x3", "4x4", "1x1"]},
+            },
+            "required": ["job_id", "verdict", "grid"],
+        },
+    },
+]
+
+
+def _guard(fn: Func) -> Func:
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Dict[str, Any]:
+        try:
+            return fn(*args, **kwargs)
+        except (SolvechaError, ValueError, OSError) as error:
+            return {"error": str(error)}
+
+    return wrapper
+
+
+def functions(client: Solvecha) -> Dict[str, Func]:
+    """The tools as plain Python functions (with type hints and docstrings)."""
+
+    @_guard
+    def solve_recaptcha_grid(task: str, grid: str, image: str) -> Dict[str, Any]:
+        """Solve a reCAPTCHA v2 image challenge. Returns selected_tiles: tiles to click, counted from 1, left to right, top to bottom.
+
+        Args:
+            task: The instruction text, e.g. 'Select all images with buses'.
+            grid: '3x3', '4x4' or '1x1'.
+            image: Path of a PNG/JPEG file, or base64 of the grid picture.
+        """
+        result = client.solve_recaptcha(task, grid, image)
+        return {"job_id": result.job_id, "selected_tiles": result.tiles, "positions": result.positions}
+
+    @_guard
+    def solve_text_captcha(image: str) -> Dict[str, Any]:
+        """Read a picture of distorted text and return the case-sensitive text.
+
+        Args:
+            image: Path of a picture file, or base64.
+        """
+        result = client.solve_text(image)
+        return {"job_id": result.job_id, "text": result.text}
+
+    @_guard
+    def get_account_status() -> Dict[str, Any]:
+        """Show the plan, the solves left today and the balance. Free."""
+        body = client.status()
+        return {k: body.get(k) for k in ("plan", "status", "credit", "quota", "balance_usd", "ttl")}
+
+    @_guard
+    def report_result(job_id: str, verdict: str, grid: str) -> Dict[str, Any]:
+        """Tell Solvecha whether a reCAPTCHA answer was accepted or rejected. Free.
+
+        Args:
+            job_id: The job_id from solve_recaptcha_grid.
+            verdict: 'accepted' or 'rejected'.
+            grid: '3x3', '4x4' or '1x1'.
+        """
+        return {"recorded": client.report_result(job_id, verdict, grid)}
+
+    return {f.__name__: f for f in (solve_recaptcha_grid, solve_text_captcha, get_account_status, report_result)}
+
+
+# ---- OpenAI function calling (Chat Completions and Responses) ----
+
+def openai_tools(client: Solvecha) -> tuple:
+    """Return (tools, handle). Pass ``tools`` to the API; call ``handle(name, arguments_json)`` for each tool call.
+
+    ``tools`` uses the Chat Completions shape. For the Responses API flatten it:
+    ``[{"type": "function", **t["function"]} for t in tools]``.
+    """
+    funcs = functions(client)
+    tools = [{"type": "function", "function": dict(spec)} for spec in TOOL_SPECS]
+
+    def handle(name: str, arguments: str) -> str:
+        if name not in funcs:
+            return json.dumps({"error": f"unknown tool {name}"})
+        try:
+            kwargs = json.loads(arguments or "{}")
+        except ValueError:
+            return json.dumps({"error": "arguments are not valid JSON"})
+        try:
+            return json.dumps(funcs[name](**kwargs))
+        except TypeError as error:
+            return json.dumps({"error": f"bad arguments: {error}"})
+
+    return tools, handle
+
+
+def openai_agents_tools(client: Solvecha) -> list:
+    """Tools for the OpenAI Agents SDK (``pip install openai-agents``)."""
+    from agents import function_tool
+
+    return [function_tool(f) for f in functions(client).values()]
+
+
+def langchain_tools(client: Solvecha) -> list:
+    """Tools for LangChain and LangGraph (``pip install langchain-core``)."""
+    from langchain_core.tools import StructuredTool
+
+    return [StructuredTool.from_function(f, name=f.__name__, description=(f.__doc__ or "").split("\n\n")[0]) for f in functions(client).values()]
+
+
+def crewai_tools(client: Solvecha) -> list:
+    """Tools for CrewAI (``pip install crewai``)."""
+    from crewai.tools import tool
+
+    return [tool(f.__name__)(f) for f in functions(client).values()]
+
+
+def llamaindex_tools(client: Solvecha) -> list:
+    """Tools for LlamaIndex (``pip install llama-index-core``)."""
+    from llama_index.core.tools import FunctionTool
+
+    return [FunctionTool.from_defaults(fn=f) for f in functions(client).values()]
+
+
+def browser_use_tools(client: AsyncSolvecha, tools: Optional[Any] = None) -> Any:
+    """Add a "solve the reCAPTCHA in the current tab" action to a Browser Use ``Tools`` object.
+
+    The action screenshots the reCAPTCHA challenge window (or the whole viewport when
+    none is found), solves it and returns the tiles to click. The agent clicks them.
+    """
+    from .browser_use_action import register
+
+    return register(client, tools)

solvecha-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: solvecha
+Version: 0.1.0
+Summary: Python client and AI agent tools for the Solvecha captcha solving API
+Project-URL: Homepage, https://solvecha.com/docs/ai-agents
+Project-URL: Repository, https://github.com/Solvecha/solvecha-skills
+Project-URL: Documentation, https://solvecha.com/docs
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: browser-use
+Requires-Dist: browser-use; extra == 'browser-use'
+Provides-Extra: crewai
+Requires-Dist: crewai; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core; extra == 'llamaindex'
+Provides-Extra: openai
+Requires-Dist: openai-agents; extra == 'openai'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Description-Content-Type: text/markdown
+
+# solvecha (Python)
+
+A small client for the [Solvecha](https://solvecha.com) captcha API, plus ready-made tools for AI agent frameworks: OpenAI function calling and the Agents SDK, LangChain, CrewAI, LlamaIndex and Browser Use.
+
+```bash
+pip install solvecha                  # client only (needs httpx)
+pip install "solvecha[langchain]"     # or openai, crewai, llamaindex, browser-use
+export SOLVECHA_API_KEY=slv_...       # create a key at https://solvecha.com/dashboard
+```
+
+## Client
+
+```python
+from solvecha import Solvecha
+
+client = Solvecha()  # reads SOLVECHA_API_KEY
+result = client.solve_recaptcha("Select all images with buses", "3x3", "grid.png")
+print(result.tiles)      # [2, 4, 5], counted from 1, left to right, top to bottom
+print(result.positions)  # ['row 1, column 2', ...]
+client.report_result(result.job_id, "accepted", "3x3")  # optional, free
+```
+
+`images` can be a file path, bytes, base64 text or a data URL. `AsyncSolvecha` has the same methods. Other methods: `solve_text`, `solve_geetest`, `solve_funcaptcha`, `status`. Errors raise `SolvechaError` subclasses with the API code (`InvalidKeyError` 15, `OutOfCreditError` 16, `RateLimitError` 11).
+
+## Agent tools
+
+```python
+from solvecha import Solvecha
+from solvecha.tools import openai_tools, openai_agents_tools, langchain_tools, crewai_tools, llamaindex_tools
+
+client = Solvecha()
+tools, handle = openai_tools(client)     # Chat Completions: pass tools=tools, answer calls with handle(name, args_json)
+agents_sdk = openai_agents_tools(client) # OpenAI Agents SDK
+lc = langchain_tools(client)             # LangChain / LangGraph
+crew = crewai_tools(client)              # CrewAI
+li = llamaindex_tools(client)            # LlamaIndex
+```
+
+Tools never raise: a failure comes back as `{"error": "..."}` with advice for the model.
+
+### Browser Use
+
+```python
+from browser_use import Agent, Browser, ChatBrowserUse
+from solvecha import AsyncSolvecha
+from solvecha.tools import browser_use_tools
+
+tools = browser_use_tools(AsyncSolvecha())   # adds the action solve_recaptcha_in_tab
+agent = Agent(task="...", llm=ChatBrowserUse(), browser=Browser(), tools=tools)
+```
+
+The action crops the screenshot to the reCAPTCHA challenge window and returns the tiles to click.
+
+## Or use MCP
+
+No code needed: `https://api.solvecha.com/mcp` with `Authorization: Bearer <key>`. See https://solvecha.com/docs/mcp-server.
+
+## Develop
+
+```bash
+pip install -e ".[test]" && pytest
+python -m build   # needs: pip install build
+```

solvecha-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+solvecha/__init__.py,sha256=X-hzAtoophvarrOOJ2c90dyY2O612-sv_cxI5Ztfq3U,590
+solvecha/browser_use_action.py,sha256=YgaIaksOBUEAqoU3Sg4Al0q44MPp3TZHZ_aULwoh110,2181
+solvecha/client.py,sha256=T2IDlfIdXboK77HkLlzm4VTH9kWA4wZcl9TmnvERsxY,8102
+solvecha/core.py,sha256=tv3OAUYmLSmt924zd-JZHbltnS1IoEiebc85VD-rHMU,2352
+solvecha/errors.py,sha256=vwiI2xnq5K-My1s84xQi08ste0q1stPgwkVt_Yxzzj0,1599
+solvecha/results.py,sha256=LXt_HtUA48879rw1F91L8aja4a-V8sL3sh9dcGjOH-o,944
+solvecha/tools.py,sha256=AZjUrR5GDZcqpJowUaPeHPz8DLslymt4y3apGgm_jRI,7201
+solvecha-0.1.0.dist-info/METADATA,sha256=WG97P61rKkwDoVTdp4GSQCVVQv3aDrm2rFYsvyQq70U,3385
+solvecha-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+solvecha-0.1.0.dist-info/RECORD,,

solvecha-0.1.0.dist-info/WHEEL

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