Configuration¶

Complete reference of all configuration keys. For explanations and tuning guidance, see the Pipeline Guide.

CLI Presets¶

The primary runtime path is the CLI. ads-bib ships four official packaged starter presets:

ads-bib run --preset openrouter --set search.query='author:"Hawking, S*"'
ads-bib preset write openrouter --output ads-bib.yaml
ads-bib doctor --preset openrouter --set search.query='author:"Hawking, S*"'

From Python, you can use the same packaged presets as the CLI with ads_bib.run(...):

import ads_bib

ads_bib.run(
    preset="openrouter",
    query='author:"Hawking, S*"',
)

Each preset defines one runtime road. They are generic starter configs, so you must set search.query before running. The usual command to start a run is ads-bib run. preset write is optional when you want one editable YAML file, and doctor is the support command for printing the full preflight report without starting a run.

For the provider stack, default backend, and hardware requirements of each preset, see Runtime Roads. One install covers all four presets; the preset switch only changes providers and defaults at runtime.

Install¶

Use a Python 3.12 env. One base install covers every preset:

uv pip install ads-bib

On NVIDIA / CUDA machines, add the validated CUDA Torch wheel into the same env so local_gpu runs on the GPU:

uv pip install ads-bib "torch==2.6.0" --extra-index-url https://download.pytorch.org/whl/cu124

If you need to restore the validated CPU wheel explicitly for a local CPU env:

uv pip install "torch==2.6.0" --extra-index-url https://download.pytorch.org/whl/cpu

The validated local HF stack for this release is Torch 2.6.x with Transformers 4.56.x.

Optional algorithm extras are available when you intentionally switch defaults:

uv pip install "ads-bib[umap]"
uv pip install "ads-bib[hdbscan]"

See Install & First Run for the full first-run walk-through.

ads-bib run --from-run run_20260407_120000_ads_bib_openrouter \
  --set topic_model.embedding_model=google/gemini-embedding-001

Unless stated otherwise, the tables below describe the raw code defaults. The Preset Override column shows the value used by the four packaged starter presets when they deviate from the code default. Inspect src/ads_bib/_presets/*.yaml or write a preset locally with ads-bib preset write ... when you need the full road-specific starter config.

Notebook Section Dicts¶

The GitHub notebook uses ten inline configuration dicts:

RUN, SEARCH, TRANSLATE, LLAMA_SERVER, TOKENIZE, AUTHOR_DISAMBIGUATION, TOPIC_MODEL, VISUALIZATION, CURATION, CITATIONS

Each dict is passed to session.set_section(...). The keys below map directly to notebook dict keys and YAML config keys.

Run¶

Search¶

Example query compositions:

# Simple author query
query: 'author:"Hawking, S*"'

# Author + topic filter
query: '(author:"Hawking, S*") AND abs:"black hole"'

# Seed + forward citations
query: 'author:"Hawking, S*" OR citations(author:"Hawking, S*")'

Translate¶

Llama Server¶

Shared configuration for pipeline stages that use llama_server as provider. This is the default local labeling path for local_cpu and an optional local labeling path for local_gpu.

Tokenize¶

Author Disambiguation¶

enabled=true without further settings runs locally and does not start Modal. CPU is useful for small checks; use local GPU or Modal for larger corpora.

Topic Model¶

Core¶

Embeddings¶

Dimensionality Reduction¶

Default params_5d and params_2d used by the official presets:

params_5d:
  n_neighbors: 30
  metric: angular
  random_state: 42
params_2d:
  n_neighbors: 30
  metric: angular
  random_state: 42

LLM Labeling¶

BERTopic-Specific¶

Default cluster_params:

cluster_params:
  min_cluster_size: 15
  min_samples: 3
  cluster_selection_method: eom
  cluster_selection_epsilon: 0.05

Toponymy-Specific¶

Toponymy is validated with toponymy==0.4.0 and fast-hdbscan>=0.2.2,<0.3. The OpenRouter preset pins toponymy_embedding_model to qwen/qwen3-embedding-8b so swapping the main document embedding model does not accidentally make Toponymy keyphrase/name embeddings slower or more expensive. The toponymy_max_workers setting controls concurrent labeling and embedding requests; it does not change the internal HDBSCAN/Boruvka thread count.

Visualization¶

Curation¶

Example:

# BERTopic: remove clusters 3 and 4
curation:
  clusters_to_remove: [3, 4]

# Toponymy: remove noise from layer 1 and cluster 12 from layer 0
curation:
  cluster_targets:
    - layer: 1
      cluster_id: -1
    - layer: 0
      cluster_id: 12

Citations¶

The code default is 1 for every metric (everything keeps every edge). The four packaged presets raise those thresholds to practical starter values (2/3/2/3) so sparse author-focused corpora still retain usable structure. Override per metric via citations.min_counts.<metric>.

authors_filter and authors_filter_uids act on the source publication set. cited_authors_exclude and cited_author_uids_exclude act on the cited reference side by removing matching references from each publication before the direct, co-citation, bibliographic-coupling, and author-co-citation networks are computed.

For gexf, graphology, and network CSV exports, direct is exported as a directed graph. co_citation, bibliographic_coupling, and author_co_citation are exported as undirected weighted graphs. When a metric has richer edge provenance than the exported graph can carry compactly, ads-bib also writes a CSV evidence sidecar.

CLI Overrides¶

ads-bib run --config <file> --from <stage> --to <stage>
ads-bib run --config <file> --run-name <name>
ads-bib run --config <file> --set key.subkey=value

Scaling Formulas¶

These formulas auto-scale parameters based on corpus size. See the Pipeline Guide for when and why to override them.

Secrets¶

Keep API keys in .env only. Never commit them to notebook cells or YAML configs.

Read next¶

• Pipeline Guide — when to retune which stage
• Troubleshooting — if runs exit early
• Output Artifacts — what each file in runs/<run_id>/ is for