capsolver-agent 0.1.0__tar.gz

capsolver_agent-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution
+dist/
+build/
+*.egg-info/
+*.egg
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+.cursor/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+
+# Environment
+.env
+.env.local
+.python-version
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

capsolver_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning where practical. Public releases are
+tagged in Git as `vX.Y.Z` and published to PyPI with the same version.
+
+## [0.1.0] - 2026-09-01
+
+### Added
+
+- Initial public release of `capsolver-agent`.
+- Framework-agnostic tool definitions for CapSolver captcha solving.
+- Async tool executor for use in custom agent loops.
+- LangChain tool implementations behind the `langchain` extra.
+- Optional browser-based tools behind the `browser` extra.
+- `capsolver-agent` CLI for inspecting tools and schemas.
+

capsolver_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thank you for your interest in `capsolver-agent`.
+
+This repository is maintained by the CapSolver team. Issues and pull requests
+are welcome when they are focused on bugs, documentation, compatibility, or
+small improvements to the public agent integration surface.
+
+## Before You Start
+
+- Search existing issues before opening a new one.
+- Open an issue before starting a large change or adding a new framework
+  integration.
+- Do not include real API keys, cookies, private URLs, prompts, tool traces, or
+  customer data in issues, tests, examples, or screenshots.
+- Keep examples token-mode focused and use placeholder credentials.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+If you do not use `uv`, install the development dependencies from
+`requirements-dev.txt` and run the equivalent commands with Python.
+
+## Pull Requests
+
+Pull requests should include:
+
+- A clear description of the change.
+- Tests or a short explanation of why tests are not needed.
+- Documentation updates for user-facing behavior.
+
+Maintainers may close changes that are outside the public agent integration
+scope or require private service-side details.
+

capsolver_agent-0.1.0/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.

capsolver_agent-0.1.0/PKG-INFO

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

@@ -0,0 +1,118 @@
+# Publishing
+
+Release target: `capsolver-agent` version `0.1.0`, prepared for public release
+on 2026-09-01.
+
+This checklist is for maintainers syncing the prepared public files to the
+official open-source repository, testing the package on TestPyPI, and then
+publishing the final package to PyPI.
+
+Publish `capsolver-core==0.1.0` first. This package depends on
+`capsolver-core>=0.1.0`.
+
+## Preconditions
+
+- The source is the prepared public copy, not a private development checkout.
+- `capsolver-core==0.1.0` has already passed TestPyPI testing before this
+  package is tested.
+- `capsolver-core==0.1.0` is already available on PyPI before this package is
+  formally published.
+- `pyproject.toml` has `version = "0.1.0"`.
+- `CHANGELOG.md` has `## [0.1.0] - 2026-09-01`.
+- `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and `SUPPORT.md`
+  are present.
+- Documentation examples use placeholder credentials only.
+- The tree does not contain `.git`, `.venv`, `uv.lock`, caches, local path
+  overrides, real API keys, browser profiles, prompts, tool traces, or private
+  service data.
+
+## Sync to the Official Open-Source Repository
+
+Copy this directory into the official `agent-capsolver` public repository
+working tree, then review the diff before committing.
+
+```bash
+git status
+git diff
+git add .
+git commit -m "Release v0.1.0"
+git status
+```
+
+Do not tag until the build, TestPyPI upload, and install test have passed.
+
+## Verify Locally
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+## Build and Check
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Inspect the source distribution and wheel before upload. Confirm that no
+private files, local paths, secrets, browser profiles, caches, prompts, tool
+traces, or test output are included.
+
+## TestPyPI Test Release
+
+Upload the exact distribution files to TestPyPI first.
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI in a clean environment and smoke-test the CLI import path.
+Use PyPI as an extra index so normal third-party dependencies can still resolve.
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ capsolver-agent==0.1.0
+python -c "import capsolver_agent; print(capsolver_agent.__version__)"
+capsolver-agent --help
+```
+
+PyPI and TestPyPI distributions cannot be overwritten. If the test upload is
+wrong, fix the issue and publish a new version.
+
+## Formal PyPI Release
+
+After TestPyPI passes and `capsolver-core==0.1.0` is available from PyPI, upload
+the same checked distribution files to PyPI.
+
+```bash
+python -m twine upload dist/*
+```
+
+Then verify installation from PyPI.
+
+```bash
+python -m pip install capsolver-agent==0.1.0
+python -c "import capsolver_agent; print(capsolver_agent.__version__)"
+capsolver-agent --help
+```
+
+## Tag and GitHub Release
+
+When the PyPI release is verified, create the release tag and push it from the
+official public repository.
+
+```bash
+git tag v0.1.0
+git push origin main
+git push origin v0.1.0
+```
+
+Create a GitHub Release for `v0.1.0` using the `CHANGELOG.md` entry.
+
+Prefer PyPI Trusted Publishing from the official public GitHub repository for
+future releases. If manual upload is used, use a project-scoped PyPI API token
+instead of an account password.
+

capsolver_agent-0.1.0/README.md

@@ -0,0 +1,159 @@
+# 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/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest public release line.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+Please do not open public issues for vulnerabilities, leaked credentials, or
+reports that include private target URLs, API keys, prompts, tool traces, or
+customer data.
+
+Report security issues by emailing `dev@capsolver.ai` with:
+
+- The affected package and version.
+- A concise description of the issue.
+- Reproduction steps or a minimal proof of concept.
+- The impact you believe the issue has.
+
+We will acknowledge valid reports as soon as possible and coordinate a fix or
+mitigation before public disclosure.
+
+## Handling API Keys and Agent Data
+
+Never commit real `CAPSOLVER_API_KEY` values, browser profiles, cookies,
+captured tokens, prompts, or agent traces. Documentation examples must use
+placeholder values only.
+

capsolver_agent-0.1.0/SUPPORT.md

@@ -0,0 +1,25 @@
+# Support
+
+Use the right channel for the type of help you need.
+
+## Package Bugs and Documentation
+
+Open a GitHub issue for:
+
+- Installation problems.
+- Runtime errors in this package.
+- Documentation mistakes.
+- Compatibility issues with supported Python versions, agent frameworks, or
+  optional browser tooling.
+
+Include the package version, Python version, operating system, framework name
+and version, and a minimal reproduction when possible.
+
+## CapSolver Account or API Service Issues
+
+For account access, billing, API key, balance, or service availability issues,
+use the support options available from `https://capsolver.com`.
+
+Do not post API keys, account identifiers, cookies, browser profiles, prompts,
+tool traces, or target site credentials in public issues.
+