solvecha 0.1.0__tar.gz

solvecha-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.venv/

solvecha-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,63 @@
+# 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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solvecha"
+version = "0.1.0"
+description = "Python client and AI agent tools for the Solvecha captcha solving API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = ["httpx>=0.25"]
+
+[project.optional-dependencies]
+openai = ["openai-agents"]
+langchain = ["langchain-core"]
+crewai = ["crewai"]
+llamaindex = ["llama-index-core"]
+browser-use = ["browser-use"]
+test = ["pytest", "pytest-asyncio"]
+
+[project.urls]
+Homepage = "https://solvecha.com/docs/ai-agents"
+Repository = "https://github.com/Solvecha/solvecha-skills"
+Documentation = "https://solvecha.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/solvecha"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

solvecha-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,141 @@
+import base64
+import json
+
+import httpx
+import pytest
+
+from solvecha import (
+    AsyncSolvecha,
+    InvalidKeyError,
+    OutOfCreditError,
+    Solvecha,
+    SolveTimeoutError,
+)
+from solvecha.tools import functions, openai_tools
+
+PNG = base64.b64encode(b"\x89PNG\r\n\x1a\nxxxx").decode()
+KEY = "slv_" + "a" * 32
+
+
+class FakeAPI:
+    """Imitates the Solvecha API. ``polls_before`` answers are 'incomplete job'."""
+
+    def __init__(self, polls_before=1, answer=None, create_error=None):
+        self.requests = []
+        self.polls = 0
+        self.polls_before = polls_before
+        self.answer = answer if answer is not None else [False, True, False, True, True, False, False, False, False]
+        self.create_error = create_error
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else None
+        self.requests.append((request.method, request.url.path, request.url.query.decode(), body, request.headers.get("authorization")))
+        if request.headers.get("authorization") != f"Bearer {KEY}":
+            return httpx.Response(401, json={"error": 15, "message": "Invalid key"})
+        if request.url.path == "/v1/status":
+            return httpx.Response(200, json={"plan": "Free", "status": "Active", "credit": 99, "quota": 100, "balance_usd": "0.00", "ttl": 10})
+        if request.url.path == "/v1/feedback":
+            return httpx.Response(200, json={"data": "ok"})
+        if request.method == "POST":
+            if self.create_error:
+                return httpx.Response(403, json={"error": self.create_error, "message": "x"})
+            return httpx.Response(200, json={"data": "job-1"})
+        self.polls += 1
+        if self.polls <= self.polls_before:
+            return httpx.Response(409, json={"error": 14, "message": "Incomplete job"})
+        return httpx.Response(200, json={"data": self.answer})
+
+
+def client(fake, **kw):
+    return Solvecha(KEY, http=httpx.Client(transport=httpx.MockTransport(fake)), poll_interval=0, **kw)
+
+
+def test_solve_recaptcha_returns_tiles_and_never_sends_the_key_in_the_body():
+    fake = FakeAPI()
+    result = client(fake).solve_recaptcha("Select all images with buses", "3x3", PNG)
+    assert result.tiles == [2, 4, 5]
+    assert result.positions == ["row 1, column 2", "row 2, column 1", "row 2, column 2"]
+    method, path, _, body, auth = fake.requests[0]
+    assert (method, path) == ("POST", "/v1/recognition/recaptcha")
+    assert body == {"task": "Select all images with buses", "grid": "3x3", "image_data": [PNG]}
+    assert "key" not in body and auth == f"Bearer {KEY}"
+    assert fake.polls == 2
+
+
+def test_file_path_and_data_url_and_bytes(tmp_path):
+    path = tmp_path / "grid.png"
+    path.write_bytes(base64.b64decode(PNG))
+    for image in (str(path), path, base64.b64decode(PNG), "data:image/png;base64," + PNG):
+        fake = FakeAPI(polls_before=0)
+        client(fake).solve_recaptcha("t", "3x3", image)
+        assert fake.requests[0][3]["image_data"] == [PNG]
+
+
+def test_grid_validation_happens_before_any_request():
+    fake = FakeAPI()
+    with pytest.raises(ValueError):
+        client(fake).solve_recaptcha("t", "5x5", PNG)
+    with pytest.raises(ValueError):
+        client(fake).solve_recaptcha("t", "3x3", [PNG, PNG])
+    assert fake.requests == []
+
+
+def test_other_types():
+    c = client(FakeAPI(polls_before=0, answer=["x7k2p"]))
+    assert c.solve_text(PNG).text == "x7k2p"
+    assert client(FakeAPI(polls_before=0, answer={"x": 42.5})).solve_geetest([PNG, PNG]).offset_percent == 42.5
+    fake = FakeAPI(polls_before=0, answer=[True, False, False, False, False, False])
+    assert client(fake).solve_funcaptcha("Pick the sheep", PNG, match=True).tiles == [1]
+    assert fake.requests[0][1] == "/v1/recognition/funcaptcha_match"
+
+
+def test_errors_map_to_exceptions():
+    with pytest.raises(OutOfCreditError):
+        client(FakeAPI(create_error=16)).solve_recaptcha("t", "3x3", PNG)
+    bad = Solvecha("slv_wrong", http=httpx.Client(transport=httpx.MockTransport(FakeAPI())), poll_interval=0)
+    with pytest.raises(InvalidKeyError):
+        bad.status()
+
+
+def test_missing_key_raises(monkeypatch):
+    monkeypatch.delenv("SOLVECHA_API_KEY", raising=False)
+    with pytest.raises(InvalidKeyError):
+        Solvecha()
+
+
+def test_timeout_reports_the_job_id():
+    with pytest.raises(SolveTimeoutError) as info:
+        client(FakeAPI(polls_before=10**6)).solve("recaptcha", {}, timeout=0.05)
+    assert info.value.job_id == "job-1"
+
+
+def test_report_and_status():
+    fake = FakeAPI()
+    c = client(fake)
+    assert c.status()["plan"] == "Free"
+    assert c.report_result("job-1", "accepted", "3x3")
+    assert fake.requests[-1][3] == {"job_id": "job-1", "verdict": "accepted", "grid": "3x3"}
+
+
+async def test_async_client():
+    fake = FakeAPI()
+    c = AsyncSolvecha(KEY, http=httpx.AsyncClient(transport=httpx.MockTransport(fake)), poll_interval=0)
+    assert (await c.solve_recaptcha("t", "3x3", PNG)).tiles == [2, 4, 5]
+    assert (await c.status())["credit"] == 99
+
+
+def test_tool_functions_never_raise():
+    funcs = functions(client(FakeAPI(create_error=16)))
+    out = funcs["solve_recaptcha_grid"]("t", "3x3", PNG)
+    assert "Out of credit" in out["error"]
+    assert "grid must be" in funcs["solve_recaptcha_grid"]("t", "9x9", PNG)["error"]
+
+
+def test_openai_tools_dispatch():
+    tools, handle = openai_tools(client(FakeAPI()))
+    assert {t["function"]["name"] for t in tools} == {"solve_recaptcha_grid", "solve_text_captcha", "get_account_status", "report_result"}
+    out = json.loads(handle("solve_recaptcha_grid", json.dumps({"task": "t", "grid": "3x3", "image": PNG})))
+    assert out["selected_tiles"] == [2, 4, 5]
+    assert "unknown tool" in json.loads(handle("nope", "{}"))["error"]
+    assert "bad arguments" in json.loads(handle("solve_text_captcha", "{}"))["error"]
+    assert "not valid JSON" in json.loads(handle("get_account_status", "{oops"))["error"]

solvecha-0.1.0/tests/test_frameworks.py

@@ -0,0 +1,60 @@
+"""Build the tools with each real framework. Skipped when the framework is not installed."""
+import base64
+import json
+
+import httpx
+import pytest
+
+from solvecha import AsyncSolvecha, Solvecha
+from solvecha.tools import (
+    browser_use_tools,
+    crewai_tools,
+    langchain_tools,
+    llamaindex_tools,
+    openai_agents_tools,
+)
+from test_client import KEY, PNG, FakeAPI
+
+
+def make():
+    return Solvecha(KEY, http=httpx.Client(transport=httpx.MockTransport(FakeAPI())), poll_interval=0)
+
+
+def test_langchain():
+    pytest.importorskip("langchain_core")
+    tools = {t.name: t for t in langchain_tools(make())}
+    assert set(tools) == {"solve_recaptcha_grid", "solve_text_captcha", "get_account_status", "report_result"}
+    out = tools["solve_recaptcha_grid"].invoke({"task": "t", "grid": "3x3", "image": PNG})
+    assert out["selected_tiles"] == [2, 4, 5]
+    assert tools["solve_recaptcha_grid"].args["grid"]["type"] == "string"
+
+
+def test_llamaindex():
+    pytest.importorskip("llama_index.core")
+    tools = {t.metadata.name: t for t in llamaindex_tools(make())}
+    out = tools["solve_recaptcha_grid"](task="t", grid="3x3", image=PNG)
+    assert "[2, 4, 5]" in str(out)
+
+
+def test_crewai():
+    pytest.importorskip("crewai")
+    tools = {t.name: t for t in crewai_tools(make())}
+    assert any("solve_recaptcha_grid" in n.replace(" ", "_").lower() for n in tools)
+    tool = next(t for n, t in tools.items() if "recaptcha" in n.lower())
+    assert "[2, 4, 5]" in str(tool.run(task="t", grid="3x3", image=PNG))
+
+
+def test_openai_agents():
+    pytest.importorskip("agents")
+    tools = openai_agents_tools(make())
+    names = {t.name for t in tools}
+    assert "solve_recaptcha_grid" in names
+    schema = next(t for t in tools if t.name == "solve_recaptcha_grid").params_json_schema
+    assert set(schema["required"]) == {"task", "grid", "image"}
+
+
+async def test_browser_use_action_is_registered():
+    pytest.importorskip("browser_use")
+    client = AsyncSolvecha(KEY, http=httpx.AsyncClient(transport=httpx.MockTransport(FakeAPI())), poll_interval=0)
+    tools = browser_use_tools(client)
+    assert "solve_recaptcha_in_tab" in tools.registry.registry.actions