txtcaptcha

https://jtrecenti.github.io/txtcaptcha/
Admin
txtcaptcha is a PyTorch library for text captcha recognition that uses a CRNN and CTC architecture...
Tokens:10,281
Snippets:105
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Commands to synchronize the environment and install the kernel for the notebook.

```bash
uv sync --extra dev --extra notebook
uv run python -m ipykernel install --user --name txtcaptcha
```

--------------------------------

### Install txtcaptcha

Source: https://jtrecenti.github.io/txtcaptcha

Install the library using pip.

```bash
pip install txtcaptcha
```

--------------------------------

### Download status output

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset_live.html

Example console output showing the status of the download process for specific sources.

```text
[cadesp] already has 16 files — skipping download
[esaj] fetching up to 16
```

```text
C:\Users\jtrec\Documents\jtrecenti\txtcaptcha\src\txtcaptcha\download\_base.py:145: UserWarning: [esaj] fetch failed (DownloadError): esaj: non-JSON response
  warnings.warn(f"[{source}] fetch failed ({type(e).__name__}): {e}")
```

```text
[esaj] saved 0
[jucesp] already has 16 files — skipping download
[rfb] fetching up to 16
```

```text
C:\Users\jtrec\Documents\jtrecenti\txtcaptcha\src\txtcaptcha\download\_base.py:145: UserWarning: [rfb] fetch failed (DownloadError): rfb session: HTTP 404
  warnings.warn(f"[{source}] fetch failed ({type(e).__name__}): {e}")
C:\Users\jtrec\Documents\jtrecenti\txtcaptcha\src\txtcaptcha\download\_base.py:145: UserWarning: [rfb] fetch failed (ConnectionError): ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
  warnings.warn(f"[{source}] fetch failed ({type(e).__name__}): {e}")
```

```text
[rfb] saved 0
[sei] fetching up to 16
```

```text
C:\Users\jtrec\Documents\jtrecenti\txtcaptcha\src\txtcaptcha\download\_base.py:145: UserWarning: [sei] fetch failed (DownloadError): sei start: HTTP 404
  warnings.warn(f"[{source}] fetch failed ({type(e).__name__}): {e}")
```

```text
[sei] saved 0
[tjmg] already has 16 files — skipping download
[tjpe] already has 16 files — skipping download
[tjrs] fetching up to 16
```

```text
C:\Users\jtrec\Documents\jtrecenti\txtcaptcha\src\txtcaptcha\download\_base.py:145: UserWarning: [tjrs] fetch failed (DownloadError): tjrs captcha: HTTP 404
  warnings.warn(f"[{source}] fetch failed ({type(e).__name__}): {e}")
```

```text
[tjrs] saved 0
[trf5] already has 16 files — skipping download
[trt] fetching up to 16
```

```text
C:\Users\jtrec\Documents\jtrecenti\txtcaptcha\src\txtcaptcha\download\_base.py:145: UserWarning: [trt] fetch failed (DownloadError): trt captcha: HTTP 405
  warnings.warn(f"[{source}] fetch failed ({type(e).__name__}): {e}")
```

```text
[trt] saved 0
```

--------------------------------

### Initialize environment and model

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset.html

Imports necessary libraries, sets configuration constants, and loads the pre-trained model.

```python
import random
from pathlib import Path

import matplotlib.pyplot as plt
import pandas as pd

from txtcaptcha import (
    Captcha,
    available_datasets,
    decrypt,
    load_model,
    read_captcha,
    sequence_accuracy,
)
from txtcaptcha.dataset import _label_from_path, _list_files

MODEL_PATH = Path('txtcaptcha_unified.pt')
DATA_ROOT = Path('data')
SAMPLE_SIZE = 200
SEED = 0

random.seed(SEED)
```

```python
model = load_model(MODEL_PATH)
model.eval()
print(f'Loaded model with vocab size {len(model.vocab)}')
```

--------------------------------

### Initialize environment and imports

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Imports necessary modules and verifies CUDA availability for GPU acceleration.

```python
import shutil
from pathlib import Path

import torch

from txtcaptcha import (
    available_datasets,
    download_dataset,
    fit_model,
    save_model,
    decrypt,
)

print('CUDA available:', torch.cuda.is_available())
if torch.cuda.is_available():
    print('Device:', torch.cuda.get_device_name(0))
```

--------------------------------

### Load the model

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset_live.html

Initializes the model from a specified path and sets it to evaluation mode.

```python
from txtcaptcha import load_model, read_captcha, decrypt

MODEL_PATH = Path('txtcaptcha_unified.pt')
model = load_model(MODEL_PATH)
model.eval()
print(f'Loaded model with vocab size {len(model.vocab)}')
```

--------------------------------

### Download live captchas

Source: https://jtrecenti.github.io/txtcaptcha/get-started.html

Use the CLI to fetch fresh, unlabeled samples from supported sources.

```bash
download_captchas --source tjmg --n 16 --out captchas/
```

--------------------------------

### Initialize CaptchaDataset

Source: https://jtrecenti.github.io/txtcaptcha/reference/CaptchaDataset.html

Instantiate the dataset with a root directory, vocabulary, image height, and case sensitivity settings.

```python
CaptchaDataset(root, vocab=DEFAULT_VOCAB, height=32, case_sensitive=True)
```

--------------------------------

### from_pretrained(repo_id, *, revision, token, cache_dir)

Source: https://jtrecenti.github.io/txtcaptcha/reference/from_pretrained.html

Downloads and loads a txtcaptcha CRNN model from the Hugging Face Hub.

```APIDOC
## from_pretrained

### Description
Downloads and loads a txtcaptcha CRNN from the Hugging Face Hub. Downloaded files are cached in the global `huggingface_hub` cache.

### Signature
`from_pretrained(repo_id=DEFAULT_REPO_ID, *, revision=None, token=None, cache_dir=None)`

### Parameters
- **repo_id** (str) - Optional - The repository ID on the Hugging Face Hub. Defaults to `DEFAULT_REPO_ID`.
- **revision** (str) - Optional - A branch, tag, or commit SHA. Defaults to `main`.
- **token** (str) - Optional - Authentication token for the Hugging Face Hub.
- **cache_dir** (str) - Optional - Path to the directory where files should be cached.
```

--------------------------------

### Train a custom model

Source: https://jtrecenti.github.io/txtcaptcha/get-started.html

Download a dataset and train a new model using the fit_model function.

```python
from txtcaptcha import fit_model, save_model, download_dataset

data_dir = download_dataset("tjmg", "data")
model, history = fit_model(
    data_dir,
    epochs=30,
    batch_size=64,
    case_sensitive=False,
)
save_model(model, "tjmg.pt")
```

--------------------------------

### Initialize DownloadError

Source: https://jtrecenti.github.io/txtcaptcha/reference/DownloadError.html

Instantiate the DownloadError exception class.

```python
DownloadError()
```

--------------------------------

### Publish and load models

Source: https://jtrecenti.github.io/txtcaptcha/get-started.html

Push a trained model to the Hugging Face Hub and load it for later use.

```python
from txtcaptcha import push_to_hub

push_to_hub(
    model,
    repo_id="your-username/your-captcha-model",
    model_card="# My captcha model\n\n...",
    tag="v0.1.0",
)
```

```python
from txtcaptcha import from_pretrained, decrypt, read_captcha

model = from_pretrained("your-username/your-captcha-model", revision="v0.1.0")
decrypt(read_captcha("captcha.png"), model=model)
```

--------------------------------

### download_captchas(source, n, dest_dir, *, sleep=0.0, timeout=30.0, max_attempts=None, on_error='skip')

Source: https://jtrecenti.github.io/txtcaptcha/reference/download_captchas.html

Downloads up to n captchas from the specified source into the destination directory. Returns a list of the successfully written file paths.

```APIDOC
## download_captchas

### Description
Downloads up to `n` captchas from `source` into `dest_dir`. Each successful fetch is saved with a unique filename format.

### Parameters
- **source** (string) - Required - The source from which to download captchas.
- **n** (integer) - Required - The target number of captchas to download.
- **dest_dir** (string) - Required - The local directory where files will be saved.
- **sleep** (float) - Optional - Time in seconds to sleep between requests. Default is 0.0.
- **timeout** (float) - Optional - Request timeout in seconds. Default is 30.0.
- **max_attempts** (integer) - Optional - Maximum number of failed attempts before stopping. Default is max(10, n * 3).
- **on_error** (string) - Optional - Error handling strategy: 'skip' (default) or 'raise'.

### Returns
- **list** - A list of strings representing the paths of the written files.
```

--------------------------------

### CaptchaDataset(root, vocab=DEFAULT_VOCAB, height=32, case_sensitive=True)

Source: https://jtrecenti.github.io/txtcaptcha/reference/CaptchaDataset.html

Initializes the dataset for loading captcha images. The dataset expects files in the root directory to follow the naming convention <id>_<label>.<ext>.

```APIDOC
## CaptchaDataset

### Description
Initializes a dataset of labeled captcha images. This class is designed to handle variable-length labels using CTC.

### Constructor
`CaptchaDataset(root, vocab=DEFAULT_VOCAB, height=32, case_sensitive=True)`

### Parameters
- **root** (string) - Required - The root directory path containing the captcha image files.
- **vocab** (list/str) - Optional - The vocabulary of characters used in the captchas. Defaults to DEFAULT_VOCAB.
- **height** (int) - Optional - The height to which images are resized. Defaults to 32.
- **case_sensitive** (bool) - Optional - Whether the label matching should be case-sensitive. Defaults to True.
```

--------------------------------

### Download datasets

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Downloads all available datasets into the local data directory.

```python
DATA_ROOT = Path('data')
DATA_ROOT.mkdir(exist_ok=True)

for name in available_datasets():
    print(f'>>> {name}')
    download_dataset(name, DATA_ROOT)
```

--------------------------------

### fit_model(dir, dir_valid=None, prop_valid=0.2, vocab=DEFAULT_VOCAB, height=32, case_sensitive=True, batch_size=32, epochs=100, lr=0.001, weight_decay=0.0, dropout=0.25, early_stopping_patience=20, early_stopping_min_delta=0.01, device=None, num_workers=0, seed=0, verbose=True)

Source: https://jtrecenti.github.io/txtcaptcha/reference/fit_model.html

Trains a CRNN captcha model on a directory of labeled images. Returns a tuple containing the model and the training history.

```APIDOC
## fit_model

### Description
Trains a CRNN captcha model on a directory of labeled images. Returns a tuple `(model, history)`.

### Parameters
- **dir** (str) - Directory containing labeled images.
- **dir_valid** (str, optional) - Directory containing validation images.
- **prop_valid** (float, optional) - Proportion of data to use for validation if dir_valid is not provided. Default: 0.2.
- **vocab** (str, optional) - Vocabulary used for the model. Default: DEFAULT_VOCAB.
- **height** (int, optional) - Image height. Default: 32.
- **case_sensitive** (bool, optional) - Whether the model is case sensitive. Default: True.
- **batch_size** (int, optional) - Batch size for training. Default: 32.
- **epochs** (int, optional) - Number of training epochs. Default: 100.
- **lr** (float, optional) - Learning rate. Default: 0.001.
- **weight_decay** (float, optional) - Weight decay for optimizer. Default: 0.0.
- **dropout** (float, optional) - Dropout rate. Default: 0.25.
- **early_stopping_patience** (int, optional) - Patience for early stopping. Default: 20.
- **early_stopping_min_delta** (float, optional) - Minimum delta for early stopping. Default: 0.01.
- **device** (str, optional) - Device to run training on.
- **num_workers** (int, optional) - Number of workers for data loading. Default: 0.
- **seed** (int, optional) - Random seed. Default: 0.
- **verbose** (bool, optional) - Whether to print training progress. Default: True.

### Returns
- **(model, history)** (tuple) - The trained model and the training history.
```

--------------------------------

### Initialize CRNN Model

Source: https://jtrecenti.github.io/txtcaptcha/reference/CRNN.html

Instantiate the CRNN model with specific architecture parameters including vocabulary, CNN channels, and RNN configuration.

```python
CRNN(
    vocab=DEFAULT_VOCAB,
    cnn_channels=(64, 128, 256, 256),
    rnn_hidden=256,
    rnn_layers=2,
    dropout=0.25,
)
```

--------------------------------

### Initialize Captcha Object

Source: https://jtrecenti.github.io/txtcaptcha/reference/Captcha.html

Constructor for creating a container for captcha images, labels, and paths.

```python
Captcha(images=list(), labels=list(), paths=list())
```

--------------------------------

### Download captchas via CLI

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset_live.html

Executes the captcha download process for all sources using the command line interface.

```bash
download_captchas --source all --n 16 --dest notebooks/data_live
```

--------------------------------

### save_pretrained(model, save_dir, *, model_card=None)

Source: https://jtrecenti.github.io/txtcaptcha/reference/save_pretrained.html

Saves the model weights and configuration to a local directory.

```APIDOC
## save_pretrained

### Description
Writes `model.safetensors` and `config.json` (with an optional `README.md`) into the specified `save_dir`. This prepares a local folder for uploading to the Hugging Face Hub or committing to a git LFS repository.

### Signature
`save_pretrained(model, save_dir, *, model_card=None)`

### Parameters
- **model** (object) - The model instance to be saved.
- **save_dir** (string) - The directory path where the files will be written.
- **model_card** (string, optional) - Optional content for a README.md file.

### Returns
- **directory path** (string) - Returns the path to the directory where the files were saved.
```

--------------------------------

### from_pretrained function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/from_pretrained.html

Defines the parameters for loading a model from the Hugging Face Hub, including repository ID, revision, and cache directory.

```python
from_pretrained(
    repo_id=DEFAULT_REPO_ID,
    *,
    revision=None,
    token=None,
    cache_dir=None,
)
```

--------------------------------

### Captcha(images=list(), labels=list(), paths=list())

Source: https://jtrecenti.github.io/txtcaptcha/reference/Captcha.html

Constructor for the Captcha class, used to initialize a container for captcha data.

```APIDOC
## Constructor: Captcha

### Description
Initializes a new container for one or more captcha images. This mirrors the R `captcha` S3 object structure.

### Parameters
- **images** (list) - Optional - A list of captcha images.
- **labels** (list) - Optional - A list of labels corresponding to the images.
- **paths** (list) - Optional - A list of file paths for the images.
```

--------------------------------

### Download captchas via Python

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset_live.html

Programmatically fetches captchas for all available sources, skipping those that already meet the required file count.

```python
from pathlib import Path

from txtcaptcha import available_sources, download_captchas

DATA_LIVE = Path('data_live')
N_PER_SOURCE = 16

for src in available_sources():
    target = DATA_LIVE / src
    existing = list(target.glob('*')) if target.exists() else []
    if len(existing) >= N_PER_SOURCE:
        print(f'[{src}] already has {len(existing)} files — skipping download')
        continue
    print(f'[{src}] fetching up to {N_PER_SOURCE}')
    saved = download_captchas(src, N_PER_SOURCE, target, timeout=20.0)
    print(f'[{src}] saved {len(saved)}')
```

--------------------------------

### download_dataset(name, dest_dir, extract=True, force=False)

Source: https://jtrecenti.github.io/txtcaptcha/reference/download_dataset.html

Downloads and optionally unzips a specified R captcha dataset. Returns the path to the extracted directory or the downloaded file.

```APIDOC
## download_dataset(name, dest_dir, extract=True, force=False)

### Description
Downloads and optionally unzips one of the R captcha datasets. Returns the path to the extracted directory or the .zip file if extract is set to False.

### Parameters
- **name** (string) - Required - The name of the dataset to download.
- **dest_dir** (string) - Required - The destination directory for the download.
- **extract** (boolean) - Optional - Whether to unzip the file after downloading. Defaults to True.
- **force** (boolean) - Optional - Whether to force the download even if the file exists. Defaults to False.
```

--------------------------------

### push_to_hub(model, repo_id, *, token, commit_message, private, model_card, tag)

Source: https://jtrecenti.github.io/txtcaptcha/reference/push_to_hub.html

Uploads model artifacts to the Hugging Face Hub and optionally creates a git tag for versioning.

```APIDOC
## push_to_hub

### Description
Creates a repository if needed and uploads weights, configuration, and model card. Returns the public repository URL.

### Parameters
- **model** (Any) - Required - The model object to upload.
- **repo_id** (str) - Optional - The identifier for the repository on the Hub. Defaults to DEFAULT_REPO_ID.
- **token** (str) - Optional - Authentication token for the Hub.
- **commit_message** (str) - Optional - The commit message for the upload. Defaults to 'Upload txtcaptcha CRNN'.
- **private** (bool) - Optional - Whether the repository should be private. Defaults to False.
- **model_card** (str) - Optional - Content for the model card.
- **tag** (str) - Optional - A git tag to create pointing at the new commit, useful for stable releases.
```

--------------------------------

### Flatten datasets for training

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Consolidates images from multiple datasets into a single directory with unique prefixes.

```python
import re

MERGED = Path('data_merged')
if MERGED.exists():
    shutil.rmtree(MERGED)
MERGED.mkdir()

label_re = re.compile(r'(?<=_)[0-9a-zA-Z]+')
exts = {'.png', '.jpg', '.jpeg', '.bmp'}

n_total = 0
for name in available_datasets():
    src = DATA_ROOT / name
    n = 0
    for f in src.rglob('*'):
        if f.suffix.lower() not in exts:
            continue
        if not label_re.search(f.stem):
            continue
        new_name = f'{name}-{f.name}'
        shutil.copy2(f, MERGED / new_name)
        n += 1
    print(f'{name}: {n} images')
    n_total += n
print('Total:', n_total)
```

--------------------------------

### Visualize labeled sample grids

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset.html

Displays a grid of captcha images with color-coded titles indicating prediction accuracy.

```python
def show_predictions(result, n_show: int = 12, cols: int = 4):
    cap = result['captcha']
    preds = result['preds']
    golds = result['golds']
    rng = random.Random(SEED)
    idxs = rng.sample(range(len(cap)), min(n_show, len(cap)))
    rows = (len(idxs) + cols - 1) // cols
    fig, axes = plt.subplots(rows, cols, figsize=(cols * 2.2, rows * 1.4))
    axes = axes.flatten() if hasattr(axes, 'flatten') else [axes]
    for ax, idx in zip(axes, idxs):
        ax.imshow(cap.images[idx])
        ax.axis('off')
        p, g = preds[idx], golds[idx]
        ok = p == g
        title = p if ok else f'{p} / {g}'
        ax.set_title(title, fontsize=9, color='green' if ok else 'red')
    for ax in axes[len(idxs):]:
        ax.axis('off')
    fig.suptitle(
        f"{result['dataset']}  "
        f"captcha_acc={result['captcha_acc']:.2%}  "
        f"char_acc={result['char_acc']:.2%}",
        fontsize=11,
    )
    fig.tight_layout()
    return fig

for name in available_datasets():
    show_predictions(results[name])
plt.show()
```

--------------------------------

### transform_image(files, height=32, max_width=None)

Source: https://jtrecenti.github.io/txtcaptcha/reference/transform_image.html

Loads and resizes image(s) to a fixed height, preserving aspect ratio. Returns a 4D tensor (B, 3, H, W).

```APIDOC
## transform_image

### Description
Loads and resizes image(s) to a fixed height, preserving aspect ratio. Returns a 4D tensor (B, 3, H, W). When passing a batch with different widths, images are padded to the maximum width in the batch (or `max_width` if given).

### Parameters
- **files** (list/array) - Required - The image file(s) to process.
- **height** (int) - Optional - The target height for the images. Defaults to 32.
- **max_width** (int) - Optional - The maximum width for padding. If not provided, uses the maximum width found in the batch.
```

--------------------------------

### CRNN Constructor

Source: https://jtrecenti.github.io/txtcaptcha/reference/CRNN.html

Initializes the Convolutional Recurrent Neural Network with specified vocabulary, CNN channels, and RNN parameters.

```APIDOC
## CRNN Constructor

### Signature
`CRNN(vocab=DEFAULT_VOCAB, cnn_channels=(64, 128, 256, 256), rnn_hidden=256, rnn_layers=2, dropout=0.25)`

### Parameters
- **vocab** (Sequence[str]) - Optional - Vocabulary for the model, defaults to DEFAULT_VOCAB.
- **cnn_channels** (Sequence[int]) - Optional - Channel configuration for the CNN layers, defaults to (64, 128, 256, 256).
- **rnn_hidden** (int) - Optional - Number of hidden units in the RNN, defaults to 256.
- **rnn_layers** (int) - Optional - Number of RNN layers, defaults to 2.
- **dropout** (float) - Optional - Dropout rate, defaults to 0.25.
```

--------------------------------

### push_to_hub function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/push_to_hub.html

Defines the parameters for uploading a model to the hub, including repository identification, authentication, and commit metadata.

```python
push_to_hub(
    model,
    repo_id=DEFAULT_REPO_ID,
    *,
    token=None,
    commit_message='Upload txtcaptcha CRNN',
    private=False,
    model_card=None,
    tag=None,
)
```

--------------------------------

### available_datasets()

Source: https://jtrecenti.github.io/txtcaptcha/reference/available_datasets.html

Retrieves a list of dataset names published in the R captcha release.

```APIDOC
## available_datasets()

### Description
Returns a list of dataset names published in the R captcha release.

### Signature
`available_datasets()`
```

--------------------------------

### Load a CRNN model

Source: https://jtrecenti.github.io/txtcaptcha/reference/load_model.html

Restores a model saved with save_model using the specified file path and optional device mapping.

```python
load_model(path, map_location=None)
```

--------------------------------

### Summarize and visualize results

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset.html

Aggregates evaluation results into a DataFrame and generates a horizontal bar chart for comparison.

```python
summary = pd.DataFrame([
    {k: r[k] for k in ('dataset', 'n', 'captcha_acc', 'char_acc')}
    for r in results.values()
]).sort_values('captcha_acc', ascending=False).reset_index(drop=True)
summary
```

```python
fig, ax = plt.subplots(figsize=(8, 4))
ax.barh(summary['dataset'], summary['captcha_acc'], label='captcha exact-match')
ax.barh(summary['dataset'], summary['char_acc'], alpha=0.35, label='char accuracy')
ax.set_xlim(0, 1)
ax.set_xlabel('accuracy')
ax.invert_yaxis()
ax.legend(loc='lower right')
ax.set_title(f'Unified model @ {SAMPLE_SIZE} random samples per dataset')
fig.tight_layout()
```

--------------------------------

### Visualize training curves

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Plots loss and validation accuracy history using matplotlib.

```python
import matplotlib.pyplot as plt

fig, axes = plt.subplots(1, 2, figsize=(10, 3))
axes[0].plot(history.train_loss, label='train')
axes[0].plot(history.valid_loss, label='valid')
axes[0].set_title('Loss'); axes[0].legend()
axes[1].plot(history.valid_acc, color='green')
axes[1].set_title('Validation sequence accuracy')
fig.tight_layout()
```

--------------------------------

### Execute evaluation across datasets

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset.html

Iterates through all available datasets to compute accuracy metrics and store results.

```python
def evaluate_dataset(name: str):
    cap = sample_dataset(name, SAMPLE_SIZE, seed=SEED)
    golds = [lab.lower() for lab in cap.labels]
    preds = decrypt(cap, model, case_sensitive=False)
    return {
        'dataset': name,
        'n': len(cap),
        'captcha_acc': sequence_accuracy(preds, golds),
        'char_acc': char_accuracy(preds, golds),
        'captcha': cap,
        'preds': preds,
        'golds': golds,
    }

results = {name: evaluate_dataset(name) for name in available_datasets()}
```

--------------------------------

### Train the unified model

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Trains a CRNN model using CTC loss and saves the resulting weights.

```python
model, history = fit_model(
    dir=MERGED,
    prop_valid=0.1,
    batch_size=64,
    epochs=80,
    lr=1e-3,
    weight_decay=1e-4,
    dropout=0.3,
    early_stopping_patience=10,
    case_sensitive=True,
    num_workers=4,
    verbose=True,
)
save_model(model, 'txtcaptcha_unified.pt')
```

--------------------------------

### pad_collate(batch)

Source: https://jtrecenti.github.io/txtcaptcha/reference/pad_collate.html

Collates a batch of data by padding images to the maximum width and stacking targets.

```APIDOC
## pad_collate(batch)

### Description
This function collates a batch of data. It pads images to the maximum width and stacks targets into a 1D tensor.

### Parameters
- **batch** (Any) - The input batch to be collated.

### Returns
- **images** ((B, 3, H, W_max)) - The padded images tensor.
- **targets** (1D tensor) - A 1D tensor concatenating all label sequences.
- **target_lengths** ((B,)) - The lengths of the targets for CTC loss.
```

--------------------------------

### load_model(path, map_location=None)

Source: https://jtrecenti.github.io/txtcaptcha/reference/load_model.html

Loads a CRNN model that was previously saved using the save_model function.

```APIDOC
## load_model

### Description
Loads a CRNN model previously saved with the save_model function.

### Signature
`load_model(path, map_location=None)`

### Parameters
- **path** (string) - Required - The file path to the saved model.
- **map_location** (optional) - Optional - A function, torch.device, string or a dict specifying how to remap storage locations.
```

--------------------------------

### Download Dataset Function Signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/download_dataset.html

The function signature for downloading and extracting captcha datasets.

```python
download_dataset(name, dest_dir, extract=True, force=False)
```

--------------------------------

### Perform batch decoding

Source: https://jtrecenti.github.io/txtcaptcha/get-started.html

Process a list of captcha files in a single operation.

```python
from pathlib import Path
from txtcaptcha import decrypt

files = list(Path("captchas/").glob("*.png"))
predictions = decrypt(files)
for f, pred in zip(files, predictions):
    print(f.name, "→", pred)
```

--------------------------------

### download_captchas function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/download_captchas.html

Defines the parameters for the download_captchas function, including source, destination, and retry configuration.

```python
download_captchas(
    source,
    n,
    dest_dir,
    *,
    sleep=0.0,
    timeout=30.0,
    max_attempts=None,
    on_error='skip',
)
```

--------------------------------

### Define captcha lengths

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset_live.html

Maps source identifiers to their expected captcha character lengths.

```python
captcha_length = {
    'cadesp': 4,
    'jucesp': 5,
    'tjmg': 5,
    'tjpe': 5,
    'trf5': 6,
    'esaj': 4,
    'rfb': 5,
    'sei': 4,
    'tjrs': 4,
    'trt': 5
}
```

--------------------------------

### Predict and display captchas

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset_live.html

Defines helper functions to list files and visualize predictions using matplotlib.

```python
import matplotlib.pyplot as plt

_IMG_EXTS = {'.png', '.jpg', '.jpeg', '.bmp', '.gif', '.tiff', '.webp'}

def list_live_files(src: str) -> list[Path]:
    root = DATA_LIVE / src
    if not root.exists():
        return []
    return sorted(p for p in root.iterdir() if p.suffix.lower() in _IMG_EXTS)

def show_live(src: str, cols: int = 4):
    files = list_live_files(src)
    if not files:
        print(f'[{src}] no live captchas found — skipping')
        return None
    cap = read_captcha(files)
    preds = decrypt(cap, model, case_sensitive=False, length=captcha_length[src])
    rows = (len(cap) + cols - 1) // cols
    fig, axes = plt.subplots(rows, cols, figsize=(cols * 2.2, rows * 1.4))
    axes = axes.flatten() if hasattr(axes, 'flatten') else [axes]
    for ax, img, pred in zip(axes, cap.images, preds):
        ax.imshow(img)
        ax.axis('off')
        ax.set_title(pred, fontsize=9)
    for ax in axes[len(cap):]:
        ax.axis('off')
    fig.suptitle(f'{src}  ({len(cap)} live captchas)', fontsize=11)
    fig.tight_layout()
    return fig

for src in available_sources():
    show_live(src)
plt.show()
```

--------------------------------

### Retrieve available datasets

Source: https://jtrecenti.github.io/txtcaptcha/reference/available_datasets.html

Call this function to obtain a list of all datasets published in the R captcha release.

```R
available_datasets()
```

--------------------------------

### Define evaluation helper functions

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/eval_per_dataset.html

Utility functions for sampling datasets and calculating character-level accuracy.

```python
def sample_dataset(name: str, n: int, seed: int = 0) -> Captcha:
    """Pick `n` random labeled files from the dataset directory and load them."""
    root = DATA_ROOT / name
    files = [p for p in _list_files(root) if _label_from_path(p) is not None]
    if not files:
        raise FileNotFoundError(f'No labeled files in {root}')
    rng = random.Random(seed)
    picked = rng.sample(files, min(n, len(files)))
    return read_captcha(picked, lab_in_path=True)

def char_accuracy(preds, golds) -> float:
    """Position-wise character accuracy, normalized by total gold characters.
    Length mismatches count every position up to max(len_p, len_g) as wrong."""
    total = 0
    correct = 0
    for p, g in zip(preds, golds):
        m = max(len(p), len(g))
        total += m
        correct += sum(1 for i in range(m) if i < len(p) and i < len(g) and p[i] == g[i])
    return correct / max(1, total)
```

--------------------------------

### encode_label(label, vocab=DEFAULT_VOCAB)

Source: https://jtrecenti.github.io/txtcaptcha/reference/encode_label.html

Encodes a string label into a 1D LongTensor of vocabulary indices.

```APIDOC
## encode_label(label, vocab=DEFAULT_VOCAB)

### Description
Encodes a string label into a 1D LongTensor of vocabulary indices (no blanks).

### Parameters
- **label** (string) - Required - The string label to encode.
- **vocab** (object) - Optional - The vocabulary mapping to use. Defaults to DEFAULT_VOCAB.

### Returns
- **LongTensor** - A 1D LongTensor representing the encoded indices.
```

--------------------------------

### read_captcha(files, lab_in_path=False)

Source: https://jtrecenti.github.io/txtcaptcha/reference/read_captcha.html

Reads one or more captcha image files into a Captcha object.

```APIDOC
## read_captcha

### Description
Reads one or more captcha image files into a Captcha object.

### Parameters
- **files** (Union[PathLike, Sequence[PathLike]]) - Required - The path or sequence of paths to the captcha image files.
- **lab_in_path** (bool) - Optional - Whether the label is included in the file path. Defaults to False.
```

--------------------------------

### Decrypt a captcha

Source: https://jtrecenti.github.io/txtcaptcha

Load a captcha image and decrypt it using the pretrained model.

```python
from txtcaptcha import read_captcha, decrypt

cap = read_captcha("path/to/captcha.png")
print(decrypt(cap))
```

--------------------------------

### transform_image function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/transform_image.html

The function signature for resizing images to a fixed height with optional maximum width constraints.

```python
transform_image(files, height=32, max_width=None)
```

--------------------------------

### Plot Captcha Images

Source: https://jtrecenti.github.io/txtcaptcha/reference/Captcha.html

Displays captcha images in a grid format using matplotlib.

```python
Captcha.plot(cols=4, max_rows=25)
```

--------------------------------

### Perform inference smoke test

Source: https://jtrecenti.github.io/txtcaptcha/notebooks/train_unified_model.html

Tests the trained model on a random sample of images with character masking.

```python
import random
sample = random.sample(list(MERGED.iterdir()), 16)
preds = decrypt(sample, model, mask='[0-9a-zA-Z]')
for p, f in zip(preds, sample):
    print(f'{f.name:40s} -> {p}')
```

--------------------------------

### Apply decode-time masking

Source: https://jtrecenti.github.io/txtcaptcha/get-started.html

Restrict the output to specific character sets without retraining the model.

```python
decrypt(cap, mask="[0-9]")                  # digits only
decrypt(cap, mask="[a-z0-9]")               # lowercase + digits
decrypt(cap, mask=list("abc123"))           # explicit list
decrypt(cap, mask="[A-Z]", case_sensitive=True)
```

--------------------------------

### Perform CRNN Forward Pass

Source: https://jtrecenti.github.io/txtcaptcha/reference/CRNN.html

Execute the forward pass to obtain logits in (T, B, num_classes) format, which are compatible with CTC loss calculations.

```python
CRNN.forward(x)
```

--------------------------------

### decode_indices(indices, vocab=DEFAULT_VOCAB, collapse=True)

Source: https://jtrecenti.github.io/txtcaptcha/reference/decode_indices.html

Decodes a CTC index sequence to a string. If collapse is set to True, it applies CTC collapse by removing repeats and blanks.

```APIDOC
## decode_indices

### Description
Decodes a CTC index sequence to a string. If `collapse` is True, it applies CTC collapse by removing repeats and blanks.

### Parameters
- **indices** (array) - Required - The sequence of CTC indices to decode.
- **vocab** (list) - Optional - The vocabulary used for decoding. Defaults to `DEFAULT_VOCAB`.
- **collapse** (boolean) - Optional - Whether to apply CTC collapse. Defaults to `True`.
```

--------------------------------

### save_pretrained function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/save_pretrained.html

The function signature for saving a model to a specified directory.

```python
save_pretrained(model, save_dir, *, model_card=None)
```

--------------------------------

### fit_model function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/fit_model.html

Defines the parameters for training a CRNN captcha model, including directory paths, hyperparameters, and training configuration.

```python
fit_model(
    dir,
    dir_valid=None,
    prop_valid=0.2,
    vocab=DEFAULT_VOCAB,
    height=32,
    case_sensitive=True,
    batch_size=32,
    epochs=100,
    lr=0.001,
    weight_decay=0.0,
    dropout=0.25,
    early_stopping_patience=20,
    early_stopping_min_delta=0.01,
    device=None,
    num_workers=0,
    seed=0,
    verbose=True,
)
```

--------------------------------

### Annotate captcha files

Source: https://jtrecenti.github.io/txtcaptcha/reference/annotate.html

Use this function to rename captcha files by appending a label suffix. It supports interactive labeling if no labels are provided.

```python
annotate.annotate(files, labels=None, path=None, rm_old=False, prompt=None)
```

--------------------------------

### read_captcha function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/read_captcha.html

The function signature for reading captcha files.

```python
read_captcha(files, lab_in_path=False)
```

--------------------------------

### annotate.annotate

Source: https://jtrecenti.github.io/txtcaptcha/reference/annotate.html

Annotates captcha files by appending a label to the filename. This function supports batch processing with provided labels or interactive labeling via a prompt.

```APIDOC
## annotate.annotate

### Description
Annotate captcha files by appending `_<label>` to the filename.

### Signature
`annotate.annotate(files, labels=None, path=None, rm_old=False, prompt=None)`

### Parameters
- **files** (Union[PathLike, Sequence[PathLike]]) - Required - The files to be annotated.
- **labels** (Optional[Sequence[str]]) - Optional - Labels for each file to obtain interactively. Defaults to `None`.
- **path** (Optional[PathLike]) - Optional - The path context for the files. Defaults to `None`.
- **rm_old** (bool) - Optional - Whether to remove the original files. Defaults to `False`.
- **prompt** (Optional[Callable[[Path], str]]) - Optional - A function to handle the labeling prompt. Defaults to interactive `input()`.
```

--------------------------------

### CRNN.forward

Source: https://jtrecenti.github.io/txtcaptcha/reference/CRNN.html

Performs a forward pass through the network to produce logits suitable for CTC loss calculation.

```APIDOC
## CRNN.forward

### Description
Returns logits (T, B, num_classes) suitable for CTC loss.

### Signature
`CRNN.forward(x)`
```

--------------------------------

### encode_label function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/encode_label.html

The function signature for encoding labels into vocabulary indices.

```python
encode_label(label, vocab=DEFAULT_VOCAB)
```

--------------------------------

### pad_collate function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/pad_collate.html

The basic function signature for the pad_collate collator.

```python
pad_collate(batch)
```

--------------------------------

### Captcha.plot(cols=4, max_rows=25)

Source: https://jtrecenti.github.io/txtcaptcha/reference/Captcha.html

Method to display the stored captcha images in a grid format using matplotlib.

```APIDOC
## Method: plot

### Description
Displays the captcha images stored in the container in a grid layout using matplotlib.

### Parameters
- **cols** (int) - Optional - The number of columns in the grid (default: 4).
- **max_rows** (int) - Optional - The maximum number of rows to display (default: 25).
```

--------------------------------

### Enforce fixed-length decoding

Source: https://jtrecenti.github.io/txtcaptcha/get-started.html

Force the decoder to return a specific number of characters.

```python
decrypt(cap, length=5)                      # exactly 5 chars
decrypt(cap, length=4, mask="[0-9]")        # 4-digit captcha
```

--------------------------------

### sequence_accuracy(preds, targets)

Source: https://jtrecenti.github.io/txtcaptcha/reference/sequence_accuracy.html

Calculates the accuracy of predicted sequences against target sequences.

```APIDOC
## sequence_accuracy(preds, targets)

### Description
Calculates the fraction of sequences where the full predicted string equals the target string.

### Parameters
- **preds** (array/list) - The predicted sequences.
- **targets** (array/list) - The ground truth target sequences.
```

--------------------------------

### Calculate sequence accuracy

Source: https://jtrecenti.github.io/txtcaptcha/reference/sequence_accuracy.html

Computes the accuracy of predicted sequences against target sequences.

```python
sequence_accuracy(preds, targets)
```

--------------------------------

### Decrypt function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/decrypt.html

The primary interface for predicting labels from captcha images using a CRNN model.

```python
decrypt.decrypt(
    files,
    model=None,
    mask=None,
    case_sensitive=True,
    length=None,
    device=None,
)
```

--------------------------------

### decode_indices function signature

Source: https://jtrecenti.github.io/txtcaptcha/reference/decode_indices.html

The function signature for decoding CTC index sequences.

```python
decode_indices(indices, vocab=DEFAULT_VOCAB, collapse=True)
```

--------------------------------

### decrypt.decrypt

Source: https://jtrecenti.github.io/txtcaptcha/reference/decrypt.html

Predict labels for one or more captcha images using a trained CRNN model.

```APIDOC
## decrypt.decrypt

### Description
Predict labels for one or more captcha images. This function uses a trained CRNN model to perform inference on provided image files.

### Signature
`decrypt.decrypt(files, model=None, mask=None, case_sensitive=True, length=None, device=None)`

### Parameters
- **files** (Union[PathLike, Sequence[PathLike], Captcha]) - Required - The captcha image file(s) to process.
- **model** (Optional[Union[CRNN, str]]) - Optional - The model to use. Defaults to the unified checkpoint from HF Hub.
- **mask** (MaskType) - Optional - Character constraints for the prediction, such as a list of characters, a regex string, or a compiled pattern.
- **case_sensitive** (bool) - Optional - Whether the prediction should be case-sensitive. Defaults to True.
- **length** (Optional[int]) - Optional - The expected length of the captcha. Uses exact CTC DP if provided, otherwise defaults to greedy CTC decoding.
- **device** (Optional[Union[str, torch.device]]) - Optional - The device to run the model on.
```

--------------------------------

### CRNN.features

Source: https://jtrecenti.github.io/txtcaptcha/reference/CRNN.html

Extracts sequence features from the input tensor, returning a representation ready for the RNN component.

```APIDOC
## CRNN.features

### Description
Returns sequence features (B, T, C) ready for the RNN.

### Signature
`CRNN.features(x)`
```

--------------------------------

### Extract CRNN Features

Source: https://jtrecenti.github.io/txtcaptcha/reference/CRNN.html

Extract sequence features from the input tensor, resulting in a (B, T, C) shape suitable for the RNN component.

```python
CRNN.features(x)
```
Tokens:
Raw