LLM Provider Configuration

Supported Providers

Recommended Setup

OpenRouter + Llama 3.3 70B Instruct — best quality-to-cost ratio in the project’s model benchmark.

• Returned a usable category for 13 of 15 benchmark URLs (non-error rate — ground-truth accuracy was not scored).
• ~$0.47 per 1,000 bookmarks classified (~$3 for a 6,430-bookmark collection).
• Sign up at openrouter.ai, get an API key, enter it in Settings.

Configuration

Via UI (Recommended)

Settings → LLM Provider → select provider → enter API key → Test Connection.

Via Environment Variables

# OpenRouter
export OPENROUTER_API_KEY=sk-or-v1-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Custom (any OpenAI-compatible endpoint)
export CUSTOM_API_KEY=...
# The custom base URL has no env var — set it in Settings (custom_api_base_url).

UI settings take precedence over environment variables.

Ollama (Local)

Ollama runs LLMs on your own hardware. No API key, no cost, full privacy.

1. Install Ollama from ollama.com.
2. Pull a model: ollama pull llama3.3.
3. In Settings → LLM Provider, select Ollama and enter the model name you pulled (default: gemma3:12b), then test the connection.

Tradeoffs: Slower than cloud APIs on modest hardware. Quality depends on the model and your GPU.

How Classification Works

Markcat classifies each bookmark in three LLM stages:

1. Stage 1 — Summarize. The LLM reads the extracted page content, checks that it is usable, writes a short summary in your configured summary languages, extracts search tags, and detects the content type. If the content is unusable (cookie wall, error page), Markcat escalates to a stronger fetch engine and retries.
2. Stage 2 — Main category. Using the Stage 1 summary and your existing category tree, the LLM picks the top-level category.
3. Stage 3 — Subcategory. The LLM refines the pick into a full path like Tech / Programming / Python.

When a page cannot be fetched at all (dead link, hard bot protection), Stage 1 runs a title-only variant that infers the summary from the URL and title alone; classification continues with a capped confidence score.

Summary Languages

Stage 1 writes the bookmark summary (and a translated title) in your configured languages — defaults English, Hungarian, German, configurable under Settings → Content & Pipeline. On the hosted service, Free and Basic plans generate 1 summary language; Pro generates up to 3. Settings → Appearance → Display language selects which one you see on bookmark cards.

Cost Estimates

Measured in the project’s model benchmark (full 3-stage pipeline, 3 summary languages):

OpenAI and custom endpoints work but have not been benchmarked — cost depends on the model you pick. Costs vary by page content length; title-only classification is significantly cheaper.

Changing Providers

You can switch providers at any time. Existing classifications are preserved — only new/unclassified bookmarks use the new provider. Re-classification of existing bookmarks is not automatic; use the “Reclassify” action on individual bookmarks or bulk-select to re-run.