darknight (dk)

Install

1. Unzip the folder:

unzip darknight-pkg.zip

2. Install it by local path:

pip install /path/to/darknight-pkg
# or editable
pip install -e /path/to/darknight-pkg

If project tracks dependencies in requirements.txt:

-e /path/to/darknight-pkg

or in pyproject.toml:

dependencies = [
    "darknight @ file:///path/to/darknight-pkg",
]

Configure

Copy the example env file and fill in your own values:

cp .env.example .env

DK_ENDPOINT=openai          # or "anthropic"
DK_BASE_URL=https://api.openai.com/v1
DK_API_KEY=sk-...
DK_MODEL=gpt-4o

Or configure programmatically instead of / on top of .env:

import dk

dk.configure(
    endpoint="openai",
    base_url="https://api.openai.com/v1",
    api_key="sk-...",
    model="qwen3-vl-",
)

Solve a single CAPTCHA

import dk

res = dk.solve("captcha.png")     # or .jpg / .jpeg
res = dk.solve("captcha_b64string")
print(res)   # eg: "Cx5b"

Solve a batch (.json dataset)

results = dk.solve("dataset.json")  

Dataset format:

[
  {"id": "001", "label": "4vNf", "b64_string": "<base64 PNG/JPEG>"}
]

RAG memory + feedback

Every dk.solve() call automatically reads from a single, universal, disk-persisted RAG store (~/.darknight/rag/rag.json) for hints from past captchas. But correctness isn't knowable at solve() time, so nothing is written until you report the real outcome:

import dk

res = dk.solve("captcha.png")
correct = submit_to_website(res)   # verification step
dk.feedback(correct)               # writes this records into the RAG store

dk.feedback() always applies to the most recent dk.solve() call. If you call dk.solve() again before giving feedback on the previous one, only captchas that received feedback will be stored.

dk.clear_rag()   # clear the RAG store