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 and TorchVision wheels into the same env so local_gpu runs on the GPU:

uv pip install ads-bib "torch==2.6.0" "torchvision==0.21.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" "torchvision==0.21.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 Companion¶

The root Colab notebook is a small frontend for the same preset-driven runner path. It loads the local_gpu preset, sets the example query and run folder, and runs the resolved config. It does not define a separate configuration schema; the keys below are the YAML, CLI override, Python, and notebook 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*")'

Source Input¶

Use source_input when the publication/reference corpus already exists outside ADS, for example after preparing Semantic Scholar or INSPIRE exports in the repository. When both paths are set, the high-level runner loads those Parquet files as the initial corpus and starts from the first requested downstream stage; leave the paths unset for normal ADS search/export runs.

source_input:
  publications_path: data/source/publications.parquet
  references_path: data/source/references.parquet
  source_name: semantic_scholar
run:
  start_stage: translate

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¶

Use the simplest field that identifies the clusters you inspected:

Examples:

# 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:
  layered_clusters_to_remove:
    - layer: 1
      cluster_id: -1
    - layer: 0
      cluster_id: 12

clusters_to_remove is always a list. For one cluster, use clusters_to_remove: [7], not clusters_to_remove: 7. Cluster IDs are run-local, so inspect a completed run first and apply removals with a variant run from that same run.

layered_clusters_to_remove is also a list, but each list item is a mapping with both layer and cluster_id. Multiple selections are combined: a document is removed when it matches any selection. Coarser Toponymy layers can remove more documents than finer layers because their clusters group broader branches of the hierarchy.

For CLI overrides, quote the whole value. The quotes protect the YAML-style list or mapping from your shell; they are not part of the value:

ads-bib run --from-run <run_id> --set 'curation.clusters_to_remove=[7, 12]'
ads-bib run --from-run <run_id> --set 'curation.layered_clusters_to_remove=[{layer: 0, cluster_id: 12}, {layer: 1, cluster_id: 20}]'

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