Skip to content

setup

Jump to bottom
github-actions[bot] edited this page Oct 11, 2026 · 5 revisions

Installation & API Keys

Requirements

  • Anki 25.x or newer (Qt 6, PyQt 6, Python 3.10+).
  • An account/key for at least one supported AI provider.

Install from AnkiWeb

The easiest way to install is through AnkiWeb:

  1. Open Anki.
  2. Go to Tools → Add-ons → Get Add-ons….
  3. Paste the code 2119980872 and press OK.
  4. Restart Anki.

Or install directly: https://ankiweb.net/shared/info/2119980872

Install from GitHub (development)

The repo is https://github.com/athulkrishna2015/AI-Hints. The packaged add-on lives in addon/, the user docs in docs/, and the regression tests in tests/. For the full code map, see Architecture & Code; for runtime files see Data Storage, Files & State.

1. Initial Setup (Clone + Submodules)

When cloning for the first time, initialize the ai-latex-fixer Git submodule so addon/latex_fixer/ is populated:

git clone https://github.com/athulkrishna2015/AI-Hints.git
cd AI-Hints
git submodule update --init --recursive

2. Local Testing (Symlinking)

The fastest way to test changes is to symlink the addon/ folder directly into your Anki add-ons directory so Anki loads your live code on every restart.

Linux / macOS:

ln -s "$(pwd)/addon" ~/.local/share/Anki2/addons21/ai_hints_dev

Windows (Admin PowerShell):

New-Item -ItemType SymbolicLink -Path "$env:APPDATA\Anki2\addons21\ai_hints_dev" -Target "$pwd\addon"

3. Reviewer & Mobile Script Sync

If you modify addon/web/template.js, sync it to your Anki profile's media folder as _ai_hints_template.js for the changes to take effect in the reviewer. The add-on syncs it automatically on startup (delayed), but manual sync is faster during development.

Linux example:

cp addon/web/template.js ~/.local/share/Anki2/default/collection.media/_ai_hints_template.js && echo "Synced successfully"

For the runtime globals, data contract, and pycmd protocol the script uses, see Frontend (JavaScript) Reference.

4. Vendored Dependencies

AI-Hints vendors third-party libraries and configurations directly in the addon/ tree to stay self-contained (no pip install required for users).

  • json_repair (addon/json_repair/) — robust AI response JSON parser.
  • latex_fixer (addon/latex_fixer/) — LaTeX/MathJax normalization engine.

To refresh every vendored dependency to its latest GitHub master/main:

python3 update_deps.py

While latex_fixer is initially set up as a Git submodule, update_deps.py syncs its core files without managing submodule pointers manually.

Building

# Auto-bump patch version and build:
python make_ankiaddon.py

# Set an explicit version:
python make_ankiaddon.py 8.5.1

# Remove older local packages before building:
python make_ankiaddon.py --clean

This produces a timestamped file like AI_Hints_v8.5.1_202610120017.ankiaddon in the repo root. Existing .ankiaddon packages are preserved by default; pass --clean to remove them.

What gets included in the package (all Python source under addon/, addon/latex_fixer/, addon/json_repair/, addon/config.json, VERSION, manifest.json).

What is excluded (__pycache__/, .pyc, .md, .png, meta.json, ai_hints.log*, tests/, and anything matched by .gitignore).

To bump the version without building:

python bump.py            # patch
python bump.py minor      # minor
python bump.py major      # major

bump.py follows major.minor.patch semver (e.g. 8.5.0 → 8.5.1).

Running Tests

The project includes a regression suite covering core logic, UI behavior, and network integrations.

1. Logic Verification (Quick Sanity)

Mocks the Anki / Qt environment. No API keys or internet required.

python3 -B scratch/local_verify.py

2. Specialized Logic Suites

Targeted unit tests for core internal engines.

python3 -B tests/test_latex_fixer.py
python3 tests/test_json_repair_integration.py
python3 tests/test_card_parser.py
python3 tests/test_sanitization_regex.py

3. Lifecycle and Integration

Verifies the orchestration of background processes and UI states.

python3 tests/test_generation_cycle.py
python3 tests/test_local_ai.py

4. Live Network Tests

Requires real API keys configured in addon/config.json or a local meta.json.

python3 scratch/live_test.py
python3 tests/test_raw_local.py

5. Live AnkiConnect Verification

Requires the AnkiConnect add-on (https://ankiweb.net/shared/info/2055492159) enabled and Anki running with the plugin listening on localhost:8765. These scripts talk to the live collection, so run them on a disposable profile / deck:

python3 tests/test_ankiconnect_live.py
python3 tests/test_live_ankiconnect.py

6. Full Suite

Run all discovery-compatible tests using Python's standard unittest runner:

python3 -B -m unittest discover -s tests -p "test_*.py"

(The two AnkiConnect scripts above are __main__-driven and are not auto-discovered here, so the full suite needs no live Anki running.)

Release Flow

  1. Make changes; commit on master (this repo does not use branches for releases).

  2. Bump + build:

    python3 make_ankiaddon.py

    This auto-bumps the patch version in addon/VERSION + addon/manifest.json and writes AI_Hints_v<version>_<timestamp>.ankiaddon in the repo root.

  3. Add a ## <version> (YYYY-MM-DD) entry to changelog.md (move anything in ## Unreleased into the new version section).

  4. Commit: release: AI-Hints vX.Y.Z.

  5. Tag and push (tag the exact release commit — CI builds from the tag, so any fix must be committed before tagging):

    git tag -a vX.Y.Z -m "AI-Hints vX.Y.Z"
git push origin master
git push origin vX.Y.Z

  6. Create the release as a draft, review it on the GitHub page, then publish. Never attach the file yourself — CI builds it:

    # Draft first: no workflow runs yet, so nothing reaches AnkiWeb.
gh release create vX.Y.Z \
  --title "AI-Hints vX.Y.Z" \
  --notes "<release notes>" \
  --draft

# Check the title, notes and tag on the page, then publish. This is the
# "go" — it fires the workflow.
gh release edit vX.Y.Z --draft=false

    Publishing fires the Release workflow (.github/workflows/release.yml), which runs the unit tests, rebuilds AI_Hints_vX.Y.Z_<timestamp>.ankiaddon from the tag, attaches it to the release, and uploads it to AnkiWeb (addon 2119980872, preserving its title/tags/support page/branch).

    The draft step is what keeps a mistake off your public listing: an untagged or mistyped version can be caught before anything is built or uploaded. If the workflow fails afterwards, the release stays published but asset-less (AnkiWeb is untouched) — fix, then re-run from Actions → Release → Run workflow.

  7. (Automatic) The workflow uploads to AnkiWeb right after attaching the asset. Verify the listing afterwards. Manual fallback: https://ankiweb.net/shared/upload.

One-time CI setup: repo Settings → Secrets and variables → Actions → Secrets must contain ANKIWEB_USERNAME (AnkiWeb login email) and ANKIWEB_PASSWORD (plain-password auth; interactive 2FA is unsupported).

The workflow can also be driven by hand from Actions → Release → Run workflow:

tag dry_run What happens
an existing release tag off Rebuilds, re-attaches, and re-uploads to AnkiWeb (the usual republish path).
an existing release tag on Tests + build + description check only; nothing is published.
a branch (e.g. master) on Same rehearsal, but built from the branch instead of a tag.
a branch off Refused. Nothing is ever published off an untagged commit.

Use a dry_run to rehearse a pipeline change before it ships. A ref that is neither a tag nor a branch fails immediately with a readable error, instead of surfacing later as a raw upload-pack: not our ref from actions/checkout.

CI notes worth knowing:

  • The test gate runs a stable subset (test_ai_undo, test_card_parser, test_cloze_scenarios, test_pregeneration_logic, test_race_condition_fix, test_edit_item.py), one interpreter per file. Runners have no Anki install, so the workflow provides a tiny anki.errors stub; everything else is mocked by the tests themselves.
  • Keep addon/latex_fixer pinned to a commit reachable upstream — an orphaned pin breaks recursive checkouts (and would silently ship CI artifacts without the fixer).
  • The listing description is the full README.md, uploaded on every release. AnkiWeb rejects descriptions over 65,535 bytes (it does not truncate — the listing silently keeps its previous text), so a pre-flight size check fails the build instead of shipping a stale description. Current README: ~22 KB.
  • addon/VERSION and manifest.json are the version of the last release. make_ankiaddon.py bumps them on the next build, so keep them in step with what is actually published — CI forces the tag's version anyway, but a local build without an argument uses these.

Get Your API Keys

AI-Hints is provider-agnostic. Get a key from one (or more) of the supported providers:

Provider Key page
Google Gemini https://aistudio.google.com/app/apikey
OpenAI https://platform.openai.com/api-keys
Anthropic https://console.anthropic.com/
Groq https://console.groq.com/keys
SambaNova https://cloud.sambanova.ai/apis
Hugging Face https://huggingface.co/settings/tokens
OpenRouter https://openrouter.ai/keys
DeepSeek, Grok (xAI), NVIDIA, Mistral, Cerebras visit each provider's developer portal

Where to Enter Your Keys

  1. Open Anki.
  2. Go to Tools → Add-ons → AI-Hints → Config.
  3. Open the AI Providers tab.
  4. Select a provider, paste your API key into its field, pick a model, and click Test to verify connectivity.

Multiple API Keys per Provider

Each provider key field supports multiple keys for automatic rotation and fallback:

  • name:key — a named key
  • key (name) — a named key
  • Separate multiple keys with commas, semicolons, or newlines.

You can also click the 🔑 button next to a provider to open the Manage Multiple API Keys dialog, where keys can be labeled, individually enabled/disabled, and rotated.

Custom Providers (local / OpenAI-compatible)

You can add any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, AIHubMix, etc.):

  1. In the AI Providers tab, click Add under Custom Providers.
  2. Fill in a Provider Name, Endpoint URL, and optionally an API Key.
  3. Click Fetch to load models, then select one.

Local endpoints without authentication can leave the API key blank.

Verify Your Setup

After entering a key:

  1. Click Test on the provider row. A ✅ status means the connection works.
  2. Optionally click Test All to check every configured provider.
  3. Review a card and click the Generate button (or use a shortcut) to confirm hints and options appear.

If you run into issues, see Troubleshooting.

Clone this wiki locally