darknight (dk)

Install

pip install darknight

If your project tracks dependencies in requirements.txt:

darknight

or in pyproject.toml:

dependencies = [
    "darknight",
]

Configure

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

cp .env.example .env

DK_ENDPOINT=openai          # any OpenAI-API-compatible endpoint
DK_BASE_URL=http://YOUR.OPENAI-API-COMPATIBLE-BACKEND.com/v1
DK_API_KEY=YOUR_API_KEY
DK_MODEL=qwen3-vl-4b-instruct

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

import dk

dk.configure(
    endpoint="openai",                                        # any OpenAI-API-compatible endpoint
    base_url="http://YOUR.OPENAI-API-COMPATIBLE-BACKEND.com/v1",
    api_key="YOUR_API_KEY",
    model="qwen3-vl-4b-instruct",
)

Solve a single CAPTCHA

import dk

res = dk.solve("/path/to/your/captcha.png")   # pass a file path in .png / .jpg / .jpeg
res = dk.solve("captcha_b64string")           # or a base64 / data-URI image string
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("/path/to/your/captcha.png")   # pass a file path in .png / .jpg / .jpeg
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