SkyeAv · SkyeAv · Sep 8, 2026 · Sep 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable changes to this project are documented in this file.
 
+## Unreleased
+
+### Removed
+- **The `--threads` / `-t` CLI options (on `build-kg` and `build-fullmap`), the `threads` parameter on the Python API (`fullmap.resolve`, etc.), and the agent command's `--gepa-threads` option (`dspy.GEPA` evaluation pool) are gone.** All parallelism is now automatic: every parallel stage uses all available CPU threads, with the fullmap build still capped on Linux by available memory (~2 GB per thread, read from `/proc/meminfo`) to avoid OOMs, and entity-resolution lookups fanning out across the fullmap shards automatically only for batches of 1024+ terms (smaller batches stay serial). GEPA now uses its library default parallelism. Results are unchanged.
+
 ## 16.7.0 - 2026-09-04
 
 ### Changed

diff --git a/docs/agent.md b/docs/agent.md
@@ -519,15 +519,15 @@ Following GEPA best practice, the optimizer splits the models: a **strong reflec
 proposes the few instruction edits, and an optional **fast task LM** (`--task-model`) runs the many
 candidate program evaluations. Pointing `--task-model` at a cheap model (e.g. a flash model) keeps the
 run fast while the strong model does the thinking; without `--task-model` the reflection LM is used for
-both. `--gepa-threads` parallelizes GEPA's candidate **LM forward passes** only: the coverage-scoring
+both. GEPA runs its candidate evaluations with its library default parallelism; the coverage-scoring
 builds stay serialized on the process-wide `_GEPA_BUILD_LOCK` (`agent.py`, since `os.chdir` is
-process-global), so a higher thread count does not speed up the expensive build/coverage step.
+process-global), so extra parallelism does not speed up the expensive build/coverage step.
 
 ```bash
 # optimize the agent prompt over a dataset of examples, writing the result to a file
 tablassert agent PMC11708054 --configuration-file ./graph.yaml --optimize \
   --dataset examples/gepa-dataset.yaml --task-model qwen-flash \
-  --max-metric-calls 30 --gepa-threads 4 \
+  --max-metric-calls 30 \
   --instructions-out .tablassert/agent/optimized_instructions.yaml
 
 # later, run the supervisor with the optimized prompt

diff --git a/docs/api/fullmap.md b/docs/api/fullmap.md
@@ -21,7 +21,6 @@ def resolve(
   config_file: Optional[str] = None,
   column_context: bool = True,
   tag: str = "_two",
-  threads: Optional[int] = None,
 ) -> pl.LazyFrame
 ```
 
@@ -79,10 +78,6 @@ Suffix appended to `col` to locate the `level_two` output column.
 
 The default `"_two"` matches `level_two`'s default tag.
 
-**`threads: Optional[int]` (default: `None`)**
-
-Optional worker-thread count passed through to the Rust lookup for parallel term batching.
-
 ### Return Value
 
 Returns a Polars LazyFrame with these columns added:

diff --git a/docs/cli.md b/docs/cli.md
@@ -75,7 +75,6 @@ page lists the flags; see
 | `--max-metric-calls` | int | No | `8` | GEPA metric-call budget for `--optimize` |
 | `--dataset` | Path | No | `None` | YAML/JSON list of `{table_summary, coverage_feedback}` examples for `--optimize` (an example may also carry `fullmap`, `workdir`, and `head` to score each proposed config with real coverage) |
 | `--task-model` | str | No | `None` | Fast model id for GEPA's many program evaluations (cheap task LM + strong reflection LM); `--model-id` is the reflection LM. Defaults to the reflection LM |
-| `--gepa-threads` | int | No | `None` | Thread count for GEPA's evaluation pool (`--optimize`): parallelizes candidate LM forward passes only; coverage-scoring builds stay serialized on `_GEPA_BUILD_LOCK` |
 
 ```bash
 tablassert agent PMC11708054 --configuration-file ./graph.yaml
@@ -124,7 +123,6 @@ tablassert build-fullmap [ARGS]
 | `--output`, `-o` | Path | No | `./fullmap/data/fullmap.redb` | Path to write the redb file (prebuilt extraction or build output) |
 | `--cache`, `-c` | Path | No | `./fullmap/downloads` | Directory for downloaded BABEL files when building from scratch (`classes/`, `synonyms/`) |
 | `--version`, `-v` | str | No | `2026jul22` | BABEL snapshot date to fetch (a RENCI stamp, **not** Tablassert's version) |
-| `--threads`, `-t` | int | No | `None` (auto) | Worker threads for a from-scratch build; auto-capped by memory on Linux (`/proc/meminfo`), else ~90% of CPUs |
 | `--aria2c`, `-a` | Flag | No | `False` | Opt into the bundled `aria2c` binary from the `[aria2]` extra for resumable segmented downloads (the prebuilt archive **or** BABEL files); fails loud (exit 2, before any download starts) if the extra is missing or unsupported on the current platform, and on a non-zero aria2c exit |
 | `--force`, `-f` | Flag | No | `False` | Skip the prebuilt download and always rebuild from BABEL outputs |
 
@@ -148,6 +146,10 @@ prebuilt exists for this version (or the download or extraction fails), it falls
 from-scratch BABEL build and logs a warning. A database already present at `--output` is reused as-is;
 pass `--force` to rebuild.
 
+A from-scratch build parallelizes automatically across all available CPU threads — on Linux the
+worker count is capped by available memory (~2 GB per thread, read from `/proc/meminfo`) to avoid
+OOMs. There is no flag to tune.
+
 See [Fullmap](fullmap.md) for the data pipeline, output schema, and graph-config usage.
 
 ---
@@ -171,12 +173,16 @@ The positional `GRAPH-CONFIGURATION-FILE` (also `--configuration-file`, `-f`) is
 | `--log`, `-l` | Flag | No | `False` | Enable verbose per-section logging |
 | `--head`, `-hd` | Flag | No | `False` | Fast output-shape preview: ≤5 random rows/section, cached to `.head.parquet`, never clobbers a full build |
 | `--no-original`, `-no` | Flag | No | `False` | Omit the verbatim source-cell copies (`original_subject`, `original_object`, and any other `original_*` fields) from the final edge NDJSON |
-| `--threads`, `-t` | int | No | `None` (auto) | Worker threads for the parallel fullmap reads behind entity resolution. Readers fan out across the 16 record-shard files, and values above the (non-empty) shard count further split the busiest shards' term buckets across more concurrent readers of the same shard; redb readers share-lock, so they never contend with each other. Unset keeps the auto behavior: large batches (≥ 1024 terms) fan out, small ones stay serial. Results are identical at any worker count |
 
 ```bash
 tablassert build-kg graph.yaml --qc --log
 ```
 
+The parallel fullmap reads behind entity resolution are automatic: large lookup batches (≥ 1024
+terms) fan out across the record-shard files on all available CPU threads (redb readers share-lock,
+so they never contend), while smaller batches stay serial. There is no flag to tune, and results are
+identical at any worker count.
+
 Output is written to `rig.artifact_base_path` (created when missing) as `{name}_{version}.nodes.ndjson`,
 `{name}_{version}.edges.ndjson`, and `{name}_{version}.RIG.yaml`; intermediate parquet lands in
 `.tablassert/store/`. The RIG document is audited in memory before it is written: an invalid

diff --git a/docs/fullmap.md b/docs/fullmap.md
@@ -26,7 +26,7 @@ tablassert build-fullmap --aria2c
 ```
 
 See the [CLI Reference → build-fullmap](cli.md#build-fullmap) for the complete flag table (output path,
-cache directory, BABEL snapshot version, worker threads, the optional `--aria2c` / `-a` downloader,
+cache directory, BABEL snapshot version, the optional `--aria2c` / `-a` downloader,
 and the `--force` / `-f` rebuild flag), their defaults, and more examples.
 
 By default, `build-fullmap` first downloads a **prebuilt** database published for this Tablassert
@@ -49,9 +49,10 @@ Two facts matter most when planning a build:
 - The BABEL **version** flag selects a RENCI BABEL snapshot date (default `2026jul22`), *not*
   Tablassert's package version. Bumping it fetches a different snapshot and requires rebuilding; the
   value used is recorded in the primary's `meta` table (`source_version`).
-- With **threads** left unset, the Rust build caps workers at `min(available_CPUs, MemAvailable_GB / 2)`
-  on Linux (reading `MemAvailable:` from `/proc/meminfo`, each worker budgeting ~2 GB of local buffers)
-  and falls back to ~90% of CPUs elsewhere, so a large build stays within a fixed memory budget.
+- The build **parallelizes automatically** across all available CPU threads: the Rust build caps
+  workers at `min(available_CPUs, MemAvailable_GB / 2)` on Linux (reading `MemAvailable:` from
+  `/proc/meminfo`, each worker budgeting ~2 GB of local buffers) and falls back to ~90% of CPUs
+  elsewhere, so a large build stays within a fixed memory budget. There is no flag to tune.
 
 ### Data Pipeline
 

diff --git a/examples/agent/README.md b/examples/agent/README.md
@@ -44,16 +44,16 @@ export TABLASSERT_AGENT_API_KEY="sk-***"
 tablassert agent PMC11947420 --configuration-file /path/to/graph.yaml --optimize \
   --dataset examples/agent/gepa-dataset.yaml \
   --task-model qwen3.6-flash \
-  --max-metric-calls 30 --gepa-threads 4 \
+  --max-metric-calls 30 \
   --instructions-out examples/agent/optimized_instructions.yaml
 ```
 
 (`--task-model` is the fast LM for the many program evaluations.)
 
 GEPA best practice (and what the flags above do): a **strong reflection LM** (`--model-id`) proposes the
 few instruction edits, while a **fast task LM** (`--task-model`) runs the many candidate evaluations.
-`--max-metric-calls` bounds the budget; `--gepa-threads` parallelizes the candidate LM forward passes
-(the coverage-scoring builds stay serialized on the process-wide `_GEPA_BUILD_LOCK`).
+`--max-metric-calls` bounds the budget; GEPA parallelizes the candidate LM forward passes with its
+library default (the coverage-scoring builds stay serialized on the process-wide `_GEPA_BUILD_LOCK`).
 
 ## QC state-directory requirement