v1.1.1

.github/workflows/build.yml

@@ -23,9 +23,9 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 

.github/workflows/build_sphinx.yml

@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: 3.11.6
 

.github/workflows/install.yml

@@ -23,9 +23,9 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 

.github/workflows/lint.yml

@@ -27,9 +27,9 @@ jobs:
         python-version: ["3.12"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 

.github/workflows/sphinx.yml

@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: 3.11.6
 

.github/workflows/test.yml

@@ -30,9 +30,9 @@ jobs:
         python-version: ["3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

AGENTS.md

@@ -0,0 +1,41 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-01-13
+
+## OVERVIEW
+Python 3.8+ library for Capsolver service API. Supports both synchronous (`requests`) and asynchronous (`aiohttp`) operations. Uses `msgspec` for high-performance JSON serialization.
+
+## STRUCTURE
+```
+./
+├── src/python3_capsolver/    # Main library package
+│   ├── core/                 # Base classes, serializers, instruments
+│   └── *.py                  # Service-specific implementations (ReCaptcha, Cloudflare, etc.)
+├── tests/                    # Pytest suite
+└── docs/                     # Sphinx documentation
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **Base Logic** | `src/python3_capsolver/core/` | `base.py`, `serializer.py`, `enum.py` |
+| **Service Implementations** | `src/python3_capsolver/*.py` | `recaptcha.py`, `cloudflare.py`, etc. |
+| **Tests** | `tests/` | Matches source structure |
+| **Configuration** | `pyproject.toml` | Build, dependency, tool config |
+
+## CONVENTIONS
+- **Formatter**: `black` (line-length 120), `isort` (profile "black").
+- **Serialization**: `msgspec` preferred over `json` for performance.
+- **Concurrency**: Dual support (Sync/Async) required for all instruments.
+- **Retries**: `tenacity` library used for resilience.
+
+## COMMANDS
+```bash
+make tests          # Run test suite
+pip install .       # Install package locally
+```
+
+## NOTES
+- Dependencies: `requests`, `aiohttp`, `msgspec`, `tenacity`.
+- Requires `API_KEY` in environment for tests.
+

Makefile

@@ -1,3 +1,5 @@
+.PHONY: install remove refactor lint build upload tests doc
+
 install:
 	pip3 install -e .
 

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx==8.2.3
+sphinx==9.1.0
 pallets_sphinx_themes==2.3.0
 myst-parser==4.0.1

pyproject.toml

@@ -86,7 +86,7 @@ classifiers = [
 dependencies = [
     "requests>=2.21.0",
     "aiohttp>=3.9.2",
-    "msgspec>=0.18,<0.20",
+    "msgspec>=0.18,<=0.21",
     "tenacity>=8,<10"
 ]
 

requirements.style.txt

@@ -1,4 +1,4 @@
 # codestyle
-isort==6.*
-black==25.1.0
+isort==7.*
+black==25.12.0
 autoflake==2.*

requirements.test.txt

@@ -1,3 +1,3 @@
-pytest==8.*
+pytest==9.*
 coverage==7.*
 pytest-asyncio==1.*

src/python3_capsolver/AGENTS.md

@@ -0,0 +1,43 @@
+# PYTHON3_CAPSOLVER PACKAGE
+
+**Generated:** 2026-01-13
+
+## OVERVIEW
+Main library package containing service-specific captcha solving implementations. Provides high-level interfaces for various captcha types (ReCaptcha, Cloudflare Turnstile, DataDome, etc.) through a unified API.
+
+Each service class inherits from `core.CaptchaParams` and implements synchronous (`requests`) and asynchronous (`aiohttp`) solving methods with automatic retry logic and response polling.
+
+## STRUCTURE
+```
+src/python3_capsolver/
+├── core/                     # Base classes, instruments, serializers
+├── control.py                # Control class for direct API methods
+├── recaptcha.py              # ReCaptcha V2/V3/Enterprise implementations
+├── cloudflare.py             # Cloudflare Turnstile/Challenge solver
+├── vision_engine.py          # AI-based image recognition
+├── image_to_text.py          # OCR text extraction
+├── datadome_slider.py        # DataDome slider captcha
+├── mt_captcha.py             # MtCaptcha solver
+├── gee_test.py               # GeeTest solver
+├── aws_waf.py                # AWS WAF bypass
+├── friendly_captcha.py       # FriendlyCaptcha solver
+└── yandex.py                 # Yandex captcha solver
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **Direct API Access** | `control.py` | `Control.get_balance()`, `create_task()`, `get_task_result()` |
+| **ReCaptcha** | `recaptcha.py` | V2, V3, Enterprise variants |
+| **Cloudflare** | `cloudflare.py` | Turnstile, Challenge modes |
+| **Image-based** | `vision_engine.py`, `image_to_text.py` | AI recognition, OCR |
+| **Other Services** | `*.py` | DataDome, GeeTest, AWS WAF, etc. |
+| **Base Logic** | `core/` | `CaptchaParams`, instruments, serializers |
+
+## CONVENTIONS
+- **Service Pattern**: Each service class inherits from `CaptchaParams` with `api_key` and `captcha_type` params
+- **Dual Handlers**: All services provide `captcha_handler()` (sync) and `aio_captcha_handler()` (async)
+- **Retry Logic**: Built-in exponential backoff with configurable `sleep_time` (default: 5s)
+- **Task Payload**: Passed via `task_payload` dict, merged with internal task params
+- **Response Structure**: Returns dict with `errorId`, `taskId`, `status`, `solution` fields
+- **Context Managers**: Support `with` and `async with` for session cleanup

src/python3_capsolver/__version__.py

@@ -1 +1 @@
-__version__ = "1.1.0"
+__version__ = "1.1.1"

src/python3_capsolver/core/AGENTS.md

@@ -0,0 +1,40 @@
+# CORE MODULE
+
+**Generated:** 2026-01-13
+
+## OVERVIEW
+Core module provides foundational classes for synchronous (`requests`) and asynchronous (`aiohttp`) captcha solving operations.
+
+Base classes establish patterns for Sync/Async instruments, enabling dual concurrency support across the library. Serialization leverages `msgspec` for high-performance JSON handling.
+
+## STRUCTURE
+```
+src/python3_capsolver/core/
+├── base.py                    # CaptchaParams entry class (Sync/Async handlers)
+├── captcha_instrument.py      # CaptchaInstrumentBase, FileInstrument
+├── aio_captcha_instrument.py  # AIOCaptchaInstrument (async implementation)
+├── sio_captcha_instrument.py  # SIOCaptchaInstrument (sync implementation)
+├── serializer.py              # Request/Response msgspec Struct classes
+├── enum.py                    # EndpointPostfixEnm, CaptchaTypeEnm, ResponseStatusEnm
+├── const.py                   # API URLs, retry configurations
+└── utils.py                   # Utility functions (attempts_generator)
+```
+
+## WHERE TO LOOK
+| Task | File | Notes |
+|------|------|-------|
+| **Entry Point** | `base.py` | `CaptchaParams` class with `captcha_handler()` and `aio_captcha_handler()` |
+| **Base Classes** | `captcha_instrument.py` | `CaptchaInstrumentBase` for instruments, `FileInstrument` for file processing |
+| **Sync Instrument** | `sio_captcha_instrument.py` | `SIOCaptchaInstrument` - requests-based implementation |
+| **Async Instrument** | `aio_captcha_instrument.py` | `AIOCaptchaInstrument` - aiohttp-based implementation |
+| **Serialization** | `serializer.py` | `PostRequestSer`, `CaptchaResponseSer`, `MyBaseModel.to_dict()` |
+| **Enums** | `enum.py` | `CaptchaTypeEnm`, `ResponseStatusEnm`, `EndpointPostfixEnm` |
+| **Configuration** | `const.py` | `REQUEST_URL`, `RETRIES`, `VALID_STATUS_CODES` |
+
+## CONVENTIONS
+- **Base Classes**: All instruments inherit from `CaptchaInstrumentBase`
+- **Dual Support**: Every captcha operation provides both sync and async methods
+- **Serialization**: `msgspec.Struct` classes with `to_dict()` method for API payloads
+- **Retries**: `tenacity` for async, `requests.Retry` for sync (5 attempts, exponential backoff)
+- **File Processing**: `FileInstrument` handles local files, URLs, and base64 in both sync/async contexts
+- **Session Management**: Instruments maintain their own HTTP sessions with retry adapters

tests/AGENTS.md

@@ -0,0 +1,31 @@
+# TESTS SUITE
+
+## OVERVIEW
+Pytest-based test suite validating API integration, dual-mode (sync/async) operations, and error handling for all captcha services.
+
+## STRUCTURE
+```
+tests/
+├── conftest.py              # BaseTest class, fixtures, test utilities
+├── test_*.py                # Test modules (match source structure)
+└── files/                   # Test assets (e.g., captcha_example.jpeg)
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **Base Test Class** | `tests/conftest.py` | `BaseTest` with utilities (`get_random_string`, `read_image`) |
+| **Fixtures** | `tests/conftest.py` | `delay_func` (1s), `delay_class` (2s) for rate limiting |
+| **Core Tests** | `tests/test_core.py` | Base logic, retries, enums, context managers |
+| **Service Tests** | `tests/test_*.py` | Per-service tests (recaptcha, cloudflare, datadome, etc.) |
+| **Instrument Tests** | `tests/test_instrument.py` | File processing, instruments |
+| **Pytest Config** | `pyproject.toml` | `asyncio_mode = "auto"`, testpaths |
+
+## CONVENTIONS
+- **Framework**: Pytest 7.0+ with `pytest-asyncio` (auto mode).
+- **Dual Testing**: Every sync test (`def test_*`) has async counterpart (`async def test_aio_*`).
+- **Parametrization**: Use `@pytest.mark.parametrize` for multiple captcha types in single test.
+- **Base Class**: All tests inherit from `BaseTest` for common utilities and rate limiting.
+- **Context Managers**: Test both `with` and `async with` patterns for resource cleanup.
+- **Rate Limiting**: Default delays (1s function, 2s class) to avoid API throttling.
+- **Error Testing**: Verify `errorId`, `errorCode`, and `solution=None` for invalid keys.