doc3gpp 0.3.2__tar.gz → 0.3.3__tar.gz

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/AGENTS.md

@@ -356,8 +356,8 @@ Workflows in one line (full prose in `docs/architecture.md`):
    with `--resume`, `--stale-only`, and `--batch`, or `IndexStatus` with no
    rebuild flag. Hybrid weighting comes from
    `Settings.semantic_search.fts5_weight`.
- - `doc3gpp spec doc parse --spec <id> [--release R] [--version V] [--force]` → `SpecDocService.parse_many` → resolve the numeric-newest `SpecVersion` with a non-empty `.zip` URL via `resolve_spec_doc_version` (after optional release filtering); explicit `--version` is strict and fails clearly when its ZIP link is missing. Fetch the ZIP with internal `fetch_spec_doc_zip` when absent (or use the zip cache at `{spec_doc.cache_dir}/zips/<spec_id>/<version>.zip`), and record the download. `--force` re-downloads before re-parsing, including pairs that already carry `parsed_at`.
- - `doc3gpp spec doc parse --spec <id> [--release R] [--version V] [--force]` → per spec: immutable-skip when `(spec_id, version)` already carries `parsed_at` (unless `--force`) → `parse` = fetch-if-missing + `list_spec_docx` + `convert_document_to_blocks` + `order_spec_files` + `extract_spec_toc` + `chunk_blocks` → `upsert_toc` + `replace_chunks` + per-file markdown cache (`{spec_doc.cache_dir}/markdown/<spec_id>/<version>/`) + `record_parsed` + best-effort auto-index (`upsert_for_version`) / auto-embed (`index_for_version`). Oversized zips → skip bucket; unknown spec/version or empty (no-docx) zips → failure bucket; one spec never aborts the batch (`SpecDocBatchResult(successes/skipped/failures)`). Prints `ok/skipped/failed` buckets only (`--format/--output/--compact` accepted but ignored). Background `parse_spec_docs` jobs log and store per-spec errors in `result.failure_details`; all-failed batches have job status `failed`, while partial successes remain `succeeded`. Chunk/search metadata uses newline-delimited combined `sections` and `tables`; TOC entries retain `section_no` / `title`.
+  - `doc3gpp spec doc parse --spec <id> [--release R] [--version V] [--force]` accepts exactly one spec and calls `SpecDocService.parse_many` with a one-item list → resolve the numeric-newest `SpecVersion` with a non-empty `.zip` URL via `resolve_spec_doc_version` (after optional release filtering); when both `--release` and `--version` are given, their release numbers must align (for example, `Rel-18` with `18.5.0`); explicit `--version` is strict and fails clearly when its ZIP link is missing. Fetch the ZIP with internal `fetch_spec_doc_zip` when absent (or use the zip cache at `{spec_doc.cache_dir}/zips/<spec_id>/<version>.zip`), and record the download. `--force` re-downloads before re-parsing, including pairs that already carry `parsed_at`.
+  - `doc3gpp spec doc parse --spec <id> [--release R] [--version V] [--force]` → immutable-skip when `(spec_id, version)` already carries `parsed_at` (unless `--force`) → `parse` = fetch-if-missing + `list_spec_docx` + `convert_document_to_blocks` + `order_spec_files` + `extract_spec_toc` + `chunk_blocks` → `upsert_toc` + `replace_chunks` + per-file markdown cache (`{spec_doc.cache_dir}/markdown/<spec_id>/<version>/`) + `record_parsed` + best-effort auto-index (`upsert_for_version`) / auto-embed (`index_for_version`). Oversized zips → skip bucket; unknown spec/version or empty (no-docx) zips → failure bucket. Prints `ok/skipped/failed` buckets only (`--format/--output/--compact` accepted but ignored). Background `parse_spec_docs` jobs use scalar `spec_id` / optional `release` / `version` / `force`, log and store the result in `result.failure_details`. Chunk/search metadata uses newline-delimited combined `sections` and `tables`; TOC entries retain `section_no` / `title`.
  - `doc3gpp spec doc toc show --spec <id> --version <v> [--fields] [--format/--output/--compact]` → `SpecDocService.get_toc` (stored `(spec_id, version)` rows; miss → `BadParameter`). Default fields `section_no, title, level, source_file` (`[output.fields] spec_doc_toc`).
   - `doc3gpp spec doc search [--text TEXT] [--semantic TEXT] [filters]` →
     `SpecDocSearchFacade.search` with the same four mode-selection rules and

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: doc3gpp
-Version: 0.3.2
+Version: 0.3.3
 Summary: Provide 3GPP TDoc information with full text search capability — a Python CLI/library, a local web UI, and an MCP server for AI clients.
 Project-URL: Homepage, https://github.com/jerrywang121/doc3gpp
 Project-URL: Repository, https://github.com/jerrywang121/doc3gpp
@@ -366,7 +366,7 @@ values on every version row.
 
 ```bash
 # use newest version with a published .zip, fetch-if-missing, convert every .docx, chunk, and auto-index
-doc3gpp spec doc parse --spec 38.331 --spec 38.523-1
+doc3gpp spec doc parse --spec 38.331 --release Rel-18 --version 18.5.0
 doc3gpp spec doc parse --spec 38.331 --force  # re-download and re-parse
 
 # inspect the stored TOC and search chunk text/combined metadata
@@ -377,10 +377,10 @@ doc3gpp spec doc index --rebuild
 doc3gpp spec doc schema --format json
 ```
 
-Background `parse_spec_docs` jobs retain per-spec failure reasons in the job
-result (`failure_details`) and log. A batch where every spec fails has status
-`failed`; a partial success retains status `succeeded` with the failed specs
-listed in the result.
+Background `parse_spec_docs` jobs retain the selected spec's failure reason in
+the job result (`failure_details`) and log. Each job targets one spec; when
+both release and version are supplied, their release numbers must align (for
+example, `Rel-18` with `18.5.0`).
 
 Spec-document rows live in a separate sibling database, normally
 `<main-stem>_specdata.db`, and are cached below the dedicated

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/README.md

@@ -283,7 +283,7 @@ values on every version row.
 
 ```bash
 # use newest version with a published .zip, fetch-if-missing, convert every .docx, chunk, and auto-index
-doc3gpp spec doc parse --spec 38.331 --spec 38.523-1
+doc3gpp spec doc parse --spec 38.331 --release Rel-18 --version 18.5.0
 doc3gpp spec doc parse --spec 38.331 --force  # re-download and re-parse
 
 # inspect the stored TOC and search chunk text/combined metadata
@@ -294,10 +294,10 @@ doc3gpp spec doc index --rebuild
 doc3gpp spec doc schema --format json
 ```
 
-Background `parse_spec_docs` jobs retain per-spec failure reasons in the job
-result (`failure_details`) and log. A batch where every spec fails has status
-`failed`; a partial success retains status `succeeded` with the failed specs
-listed in the result.
+Background `parse_spec_docs` jobs retain the selected spec's failure reason in
+the job result (`failure_details`) and log. Each job targets one spec; when
+both release and version are supplied, their release numbers must align (for
+example, `Rel-18` with `18.5.0`).
 
 Spec-document rows live in a separate sibling database, normally
 `<main-stem>_specdata.db`, and are cached below the dedicated

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/docs/architecture.md

@@ -622,12 +622,15 @@ and syncs each through the `--tsg` path below.
 
 ### Spec-document corpus (parse → TOC → search)
 
-1. `doc3gpp spec doc parse --spec <id>... [--release R] [--version V]
-   [--force]` calls `SpecDocService.parse_many`. The version resolves via
+1. `doc3gpp spec doc parse --spec <id> [--release R] [--version V]
+   [--force]` accepts exactly one spec and calls `SpecDocService.parse_many`
+   with a one-item list. The version resolves via
    `resolve_spec_doc_version` — for automatic selection, filters to rows with
    a non-empty `.zip` URL, then applies numeric sort on `SpecVersion.version`
    (segment-wise ints, non-numeric → 0); optional `release` filters before
-   selection. An explicit `version` is strict and raises
+    selection. When both `release` and `version` are supplied, their release
+    numbers must agree (for example, `Rel-18` with `18.5.0`). An explicit
+    `version` is strict and raises
    `SpecDocUnknownVersionError` if its ZIP link is missing. A miss raises
    `SpecDocUnknownSpecError` (no
    `spec_versions` rows — run `spec sync --spec-id` first) or
@@ -1093,8 +1096,8 @@ the `spec doc` / `toc` / `search` triplet, 40 commands) plus the `server` group
     - `sync` — `--tsg`
     - `list` — filters by `--tsg`, `--name`, `--acronym`, `--release`
  - `spec doc` (nested under `spec` as `spec doc ...`):
-     - `parse` — repeatable `--spec` (at least one required), `--release`,
-       `--version`, `--force/-f`; resolves the numeric-newest or pinned
+     - `parse` — exactly one `--spec` (required), `--release`, `--version`,
+        `--force/-f`; resolves the numeric-newest or pinned
        version, fetches the ZIP when missing, and records the download;
        `--force` re-downloads and re-parses, including already-parsed pairs.
        Also accepts `--format/--output/--compact` (currently ignored); prints

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/docs/cli.md

@@ -2415,12 +2415,12 @@ strict and fails clearly if that version has no ZIP link. Run
 
 Purpose:
 
-- Fetch-if-missing, convert, chunk, and index one or more specs; prints one
-  `ok` / `skipped <reason>` / `failed <reason>` (stderr) line per spec.
+- Fetch-if-missing, convert, chunk, and index one spec; prints one `ok`,
+  `skipped <reason>`, or `failed <reason>` (stderr) line.
 
 Options:
 
-- --spec: spec id to parse; repeat per spec (at least one required).
+- --spec: spec id to parse; exactly one is required.
 - --release: release marker, e.g. `Rel-18`. Optional pin.
 - --version: exact version, e.g. `18.5.0`. Optional pin.
 - --force, -f: re-download and re-parse the resolved version, including
@@ -2439,11 +2439,12 @@ Behavior:
   `spec_doc_sources.downloaded_at` before conversion.
 - `--force` re-downloads the resolved ZIP and then re-parses it, including when
   the `(spec_id, version)` pair already has `parsed_at`.
-- Per spec: immutable-skip when the `(spec_id, version)` source row already
-  carries `parsed_at` (unless `--force`); oversized zips land in the `skipped`
-  bucket; unknown spec/version, empty (no-`.docx`) zips, and every other error
-  land in the `failures` bucket. One spec never aborts the batch
-  (`SpecDocBatchResult(successes/skipped/failures)`).
+- The `(spec_id, version)` source row is skipped when it already carries
+  `parsed_at` (unless `--force`); oversized zips land in the `skipped` bucket;
+  unknown spec/version, empty (no-`.docx`) zips, and every other error land in
+  the `failures` bucket. When both `--release` and `--version` are supplied,
+  their release numbers must agree (for example, `Rel-18` requires a version
+  beginning with `18.`).
 - `parse` = fetch-if-missing + `list_spec_docx` (`.doc` entries warn-skip) +
   `convert_document_to_blocks` + `order_spec_files` (front-matter TOC file first,
   then section-tuple sort, TOC tiebreak, unnumbered lexicographic tail) +
@@ -2468,8 +2469,8 @@ Examples:
 # Parse the newest version of 38.331 with a published ZIP download link.
 doc3gpp spec doc parse --spec 38.331
 
-# Parse two specs at a pinned release.
-doc3gpp spec doc parse --spec 38.331 --spec 38.523-1 --release Rel-18
+# Parse one spec at a pinned release and version.
+doc3gpp spec doc parse --spec 38.331 --release Rel-18 --version 18.5.0
 
 # Re-parse even when already parsed.
 doc3gpp spec doc parse --spec 38.331 --force

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/docs/web-server.md

@@ -207,16 +207,15 @@ the target is missing or not `X-Doc3gpp-Managed` by doc3gpp.
 | POST | `/jobs/spec-docs/index` | Enqueue unified spec-doc FTS5/vector index maintenance. |
 | POST | `/jobs/cache/purge` | Enqueue `cache_purge` (requires `yes: true`). |
 | POST | `/jobs/parse/tdoc-url` | Enqueue `parse_tdoc_url` (a single 3GPP FTP URL or folder; `url` must be `https://www.3gpp.org/ftp/...`, `recursive` XOR `max_depth`). |
-| POST | `/jobs/parse/spec-docs` | Enqueue `parse_spec_docs` for one or more spec ids (`spec_ids`, optional `release`, `version`, and `force`); progress is streamed through the normal job SSE endpoint. This job is intentionally not a panel on the eleven-form `/sync` hub. |
+| POST | `/jobs/parse/spec-docs` | Enqueue `parse_spec_docs` for one spec id (`spec_id`, optional `release`, `version`, and `force`); progress is streamed through the normal job SSE endpoint. This job is intentionally not a panel on the eleven-form `/sync` hub. |
 | POST | `/jobs/{id}/cancel` | Cancel a queued/running job. Accepts `?format=html` to return the refreshed job row as an `outerHTML` swap target for the list page's per-row Cancel button. JSON otherwise. |
 | POST | `/jobs/sync_tdocs` | Flat alias for `sync_tdocs` (form or JSON). |
 | GET | `/sync` | Sync hub page: eleven enqueue forms (meetings, tdocs, all-tdocs, specs-by-tsg, specs-by-id, parse-tdocs, parse-tdoc-url, TDoc index maintenance, spec-document index maintenance, cache-purge, testcases) + a "Recent sync jobs" table. |
 | GET | `/sync?format=fragment` | Recent-jobs table fragment (wrapped in `<div id="recent-jobs">`) for HTMX `outerHTML` swap. |
 
-`parse_spec_docs` records per-spec errors in `result.failure_details` and the
-job log. If every requested spec fails, the job is `failed` with a populated
-`error` and result; partial successes remain `succeeded` with failure details
-in the result.
+`parse_spec_docs` records the spec error in `result.failure_details` and the
+job log. A failed parse job has a populated `error` and result; a successful or
+skipped parse reports its corresponding one-spec result.
 
 Append `?format=json` to any list/detail route to get the CLI-equivalent
 JSON. Append `?format=html` (or omit) for the browsable HTML view.
@@ -279,8 +278,8 @@ specdata source row has not been downloaded or parsed; a downloaded source is
 waiting for parsing; and a parsed source shows its parse timestamp, DOCX and
 chunk counts. The only document action is `Parse document` (or `Force
 re-parse`, available only for a parsed source. It enqueues the existing
-`POST /jobs/parse/spec-docs` job with `spec_ids`, the selected exact `version`,
-and `force`, then
+`POST /jobs/parse/spec-docs` job with scalar `spec_id`, the selected exact
+`version`, and `force`, then
 polls the normal job status. The parser downloads a missing ZIP internally;
 there is intentionally no standalone spec-document fetch route or fetch
 control.
@@ -530,8 +529,8 @@ The spec-document tools use the separate specdata database. `get_spec_toc`
 reads one parsed `(spec_id, version)` TOC, `search_spec_docs` selects among
 FTS5, vector, hybrid, and filter-only chunk search, and `get_spec_doc_index`
 reports index status. `parse_spec_docs` enqueues the same
-`PARSE_SPEC_DOCS` job as `POST /jobs/parse/spec-docs`; it accepts
-`spec_ids`, optional `release`/`version`, and `force`.
+`PARSE_SPEC_DOCS` job as `POST /jobs/parse/spec-docs`; it accepts one
+`spec_id`, optional `release`/`version`, and `force`.
 
 The MCP `serverInfo` block returned on every `initialize` handshake carries `name` ("doc3gpp"), `version` (from `importlib.metadata.version("doc3gpp")`, falling back to `doc3gpp.__version__`), `title`, `description`, and `website_url`. Clients do not need a tool call to read the version.
 

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/pyproject.toml

@@ -7,7 +7,7 @@ allow-direct-references = true
 
 [project]
 name = "doc3gpp"
-version = "0.3.2"
+version = "0.3.3"
 description = "Provide 3GPP TDoc information with full text search capability — a Python CLI/library, a local web UI, and an MCP server for AI clients."
 readme = "README.md"
 requires-python = ">=3.10"

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/cli.py

@@ -36,7 +36,7 @@ from doc3gpp.config import get_settings
 from doc3gpp.models.meeting import Meeting
 from doc3gpp.models.schema_info import SCHEMA_FIELDS, schema_payload
 from doc3gpp.models.spec import Spec, SpecVersion
-from doc3gpp.models.spec_doc import SpecDocSearchFilters
+from doc3gpp.models.spec_doc import SpecDocSearchFilters, SpecDocSelectionError
 from doc3gpp.models.sync import BulkSyncOutcome, SyncOutcome
 from doc3gpp.models.tdoc import TDoc, TDocWithMeeting
 from doc3gpp.models.tdoc_cr import (
@@ -55,6 +55,7 @@ from doc3gpp.parsers.docx_converter import PythonDocxNotInstalledError
 from doc3gpp.parsers.normalizers import normalize_ftp_path
 from doc3gpp.scraping.cache import CacheStatus, TDocCache
 from doc3gpp.scraping.cache_keys import derive_cache_file
+from doc3gpp.scraping.spec_doc_source import validate_release_version_alignment
 from doc3gpp.scraping.tdoc_zip_source import canonicalise_tdoc_id
 from doc3gpp.services.factory import (
     build_meeting_service,
@@ -5132,7 +5133,7 @@ def spec_doc_parse(
     spec: list[str] | None = typer.Option(  # noqa: B008 - Typer option declaration
         None,
         "--spec",
-        help="Spec id to parse; repeat per spec (at least one required).",
+        help="Spec id to parse (exactly one required).",
     ),
     release: str | None = typer.Option(
         None, "--release", help="Release marker, e.g. Rel-18.",
@@ -5160,10 +5161,16 @@ def spec_doc_parse(
         help="Strip output formatting: JSON drops indent and operator-space. No-op for ``table``.",
     ),
 ) -> None:
-    """Batch form: --spec may repeat; success/skip/failure buckets printed."""
+    """Parse one spec; print its success/skip/failure result."""
     create_schema("all")
     if not spec:
-        raise typer.BadParameter("pass at least one --spec <id>")
+        raise typer.BadParameter("pass exactly one --spec <id>")
+    if len(spec) != 1:
+        raise typer.BadParameter("--spec may be provided only once")
+    try:
+        validate_release_version_alignment(release, version)
+    except SpecDocSelectionError as exc:
+        raise typer.BadParameter(str(exc)) from exc
     svc = build_spec_doc_service()
     result = svc.parse_many(spec, release=release, version=version, force=force)
     for sid in result.successes:

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/data/skills/doc3gpp/SKILL.md

@@ -20,7 +20,7 @@ Read tools return a single text item containing JSON (except `get_tdoc_content`,
 | Meeting calendar | `list_meetings` with `tsg`, `name`, or `year`; `get_meeting` with numeric `meeting_id` | `sync_meetings({"tsg":"R5"})` fetches and parses that TSG's calendar | Re-list, then use `get_meeting` to obtain its meeting ID and FTP URL. There is no separate meeting-parse tool. |
 | Meeting TDocs | `list_tdocs` with `meeting_id`, `tdoc_id`, `title`, `spec`, etc.; `get_tdoc` with `tdoc_id` or `ftp_url` | `sync_tdocs({"meeting_id":260013})` after the meeting exists; alternatively `sync_tdocs_by_meeting({"meeting":"RAN5#106"})`. For document extraction, `parse_tdocs({"filter":{"tdoc_id":"R5-260013"}})`; for a direct 3GPP FTP URL use `parse_tdoc_url({"url":"https://www.3gpp.org/ftp/..."})`. | `get_tdoc` for cover/extract metadata; `get_tdoc_content({"tdoc_id":"R5-260013"})` for cached markdown if available; `search_tdoc` for indexed content and filters. |
 | Specifications | `list_specs` with `tsg`, `spec_id`, `title`, or `parsed`; `get_spec` with dotted `spec_id` | `sync_specs({"tsg":"R5"})` or `sync_specs({"spec_id":"38.331"})` (exactly one selector). `force` bypasses the sync interval; `per_version_details` fetches extra PDF/CR-list details. | `get_spec` returns versions, release markers, ZIP URLs, and per-version `parsed` state. Paginate versions with `limit`/`offset` if needed. |
-| Specification documents | Start with `get_spec` to identify a version with a ZIP URL; `get_spec_toc` needs an already parsed exact `(spec_id, version)` | `parse_spec_docs({"spec_ids":["38.331"],"version":"18.5.0"})` downloads if needed and parses; omit `version` to resolve a suitable stored version (optionally constrain with `release`). `force` re-downloads and re-parses. | `get_spec_toc({"spec_id":"38.331","version":"18.5.0"})`; `search_spec_docs` with `spec_id`, `version`, `text` or `semantic`, `sections`, `tables`. Note '%' wildcards to match section / table titles to improve search. If search section numbers or table numbers, use '%' at the end to match sub-sections or sub-tables. e.g. `"section":"5.3.2%"` or `"table":"6.1.1.2.3-%"`. |
+| Specification documents | Start with `get_spec` to identify a version with a ZIP URL; `get_spec_toc` needs an already parsed exact `(spec_id, version)` | `parse_spec_docs({"spec_id":"38.331","version":"18.5.0"})` downloads if needed and parses one spec; omit `version` to resolve a suitable stored version (optionally constrain with `release`). When both `release` and `version` are supplied, their release numbers must align, e.g. `Rel-18` with `18.5.0`. `force` re-downloads and re-parses. | `get_spec_toc({"spec_id":"38.331","version":"18.5.0"})`; `search_spec_docs` with `spec_id`, `version`, `text` or `semantic`, `sections`, `tables`. Note '%' wildcards to match section / table titles to improve search. If search section numbers or table numbers, use '%' at the end to match sub-sections or sub-tables. e.g. `"section":"5.3.2%"` or `"table":"6.1.1.2.3-%"`. |
 | RAN5 testcases | `list_testcases` with `testcase` (ID pattern), `title`, `spec`, `group`, `status` (TTCN), or `gcf_status` (GCF/PTCRB) | `sync_testcases({})` fetches and parses the latest RAN5 status snapshot in one job; `{"force":true}` re-downloads and re-parses a snapshot already recorded. No separate testcase parse tool. | `get_testcase({"testcase_id":"<id>"})` returns all stored groups; pass `group` for one group. Each result has nested `statuses` entries containing `path`, `gcf_ptcrb`, and `ttcn_status`. |
 
 Filters on list/search tools generally accept SQL-LIKE `%` wildcards (for example `title:"%handover%"`); plain values match exactly. Testcase `group` is an exact match: `5G`, `LTE`, `IMS`, `UTRA`, `POS`, or `MCX`. `list_meetings`, `list_tdocs`, `list_specs`, and `list_testcases` default to 50 rows: use `limit` and `offset` to page. `search_tdoc` and `search_spec_docs` select FTS5 with `text`, vector search with `semantic`, hybrid with both, and filter-only with neither. Semantic search requires its configured embedding service. If text search reports an unavailable or corrupt index, inspect `get_tdoc_index` or `get_spec_doc_index`; use `index_tdocs({"rebuild":true})` or `index_spec_docs({"rebuild":true})` when rebuilding is needed, then poll that job. Parse normally attempts automatic indexing, but indexing can fail independently.
@@ -44,7 +44,7 @@ search_tdoc         {"text":"handover","meeting_id":<meeting_id>}
 sync_specs          {"spec_id":"38.331"}
 get_job             {"job_id":"<spec-sync job_id>"}    # poll until terminal
 get_spec            {"spec_id":"38.331"}
-parse_spec_docs     {"spec_ids":["38.331"],"version":"<ZIP-backed version from get_spec>"}
+parse_spec_docs     {"spec_id":"38.331","version":"<ZIP-backed version from get_spec>"}
 get_job             {"job_id":"<spec-doc-parse job_id>"} # poll until terminal
 get_spec_toc        {"spec_id":"38.331","version":"<parsed version>"}
 search_spec_docs    {"text":"handover","spec_id":"38.331","version":"<parsed version>", "sections":"5.2.2.3%"}

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/models/spec_doc.py

@@ -1,5 +1,6 @@
 """DTOs for the spec-document corpus (separate specdata sqlite file)."""
 from __future__ import annotations
+
 from dataclasses import dataclass, field
 from datetime import datetime
 
@@ -18,6 +19,10 @@ class SpecDocUnknownVersionError(SpecDocError):
         self.available = available or []
 
 
+class SpecDocSelectionError(SpecDocError):
+    """Raised when a release/version selection is internally inconsistent."""
+
+
 class SpecDocNoDocxError(SpecDocError):
     pass
 

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/scraping/spec_doc_source.py

@@ -2,13 +2,43 @@
 from __future__ import annotations
 
 import logging
+import re
 
 from doc3gpp.models.spec import SpecVersion
-from doc3gpp.models.spec_doc import SpecDocUnknownVersionError
+from doc3gpp.models.spec_doc import SpecDocSelectionError, SpecDocUnknownVersionError
 
 logger = logging.getLogger(__name__)
 
 
+def validate_release_version_alignment(
+    release: str | None,
+    version: str | None,
+) -> None:
+    """Ensure an explicitly selected release agrees with the version major."""
+    if release is None or version is None:
+        return
+
+    release_match = re.fullmatch(r"Rel-(\d+)", release)
+    if release_match is None:
+        raise SpecDocSelectionError(
+            f"release {release!r} must use the form 'Rel-<number>' when paired with a version"
+        )
+
+    version_match = re.match(r"(\d+)(?:\.|$)", version)
+    if version_match is None:
+        raise SpecDocSelectionError(
+            f"version {version!r} must begin with a numeric release when paired with {release!r}"
+        )
+
+    release_major = release_match.group(1)
+    version_major = version_match.group(1)
+    if release_major != version_major:
+        raise SpecDocSelectionError(
+            f"release {release!r} does not match version {version!r}; "
+            f"expected a version beginning with {release_major}."
+        )
+
+
 def _version_key(v: SpecVersion) -> tuple[int, ...]:
     parts: list[int] = []
     for seg in v.version.split("."):
@@ -22,6 +52,7 @@ def _version_key(v: SpecVersion) -> tuple[int, ...]:
 def resolve_spec_doc_version(
     versions: list[SpecVersion], release: str | None = None, version: str | None = None
 ) -> SpecVersion:
+    validate_release_version_alignment(release, version)
     if not versions:
         raise SpecDocUnknownVersionError("no versions stored for this spec", available=[])
 

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/web/errors.py

@@ -38,6 +38,7 @@ from doc3gpp.models.semantic_search import (
 )
 from doc3gpp.models.spec_doc import (
     SpecDocNoDocxError,
+    SpecDocSelectionError,
     SpecDocTooLargeError,
     SpecDocUnknownSpecError,
     SpecDocUnknownVersionError,
@@ -137,6 +138,7 @@ _MCP_RESOURCE_BY_EXC: dict[type[Exception], tuple[str, int]] = {
     SpecUnknownOnUpstreamError: ("spec", MCP_CODE_NOT_FOUND),
     SpecDocUnknownSpecError: ("spec_doc", MCP_CODE_NOT_FOUND),
     SpecDocUnknownVersionError: ("spec_doc", MCP_CODE_NOT_FOUND),
+    SpecDocSelectionError: ("spec_doc", MCP_CODE_INVALID_PARAMS),
     SpecDocTooLargeError: ("spec_doc", MCP_CODE_TOO_LARGE),
     SpecDocNoDocxError: ("spec_doc", MCP_CODE_INVALID_PARAMS),
     JobNotFoundError: ("job", MCP_CODE_NOT_FOUND),
@@ -184,6 +186,7 @@ _ERROR_SLUGS: dict[type[Exception], str] = {
     SpecUnknownOnUpstreamError: "spec_unknown_on_upstream",
     SpecDocUnknownSpecError: "spec_doc_unknown_spec",
     SpecDocUnknownVersionError: "spec_doc_unknown_version",
+    SpecDocSelectionError: "spec_doc_invalid_selection",
     SpecDocTooLargeError: "spec_doc_too_large",
     SpecDocNoDocxError: "spec_doc_no_docx",
     InvalidFilterError: "invalid_filter",
@@ -210,6 +213,7 @@ _STATUS_BY_EXC: dict[type[Exception], int] = {
     SpecUnknownOnUpstreamError: 404,
     SpecDocUnknownSpecError: 404,
     SpecDocUnknownVersionError: 404,
+    SpecDocSelectionError: 400,
     SpecDocTooLargeError: 422,
     SpecDocNoDocxError: 422,
     InvalidFilterError: 400,

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/web/mcp_server.py

@@ -33,12 +33,13 @@ from doc3gpp.models.semantic_search import (
     SemanticSearchUnavailableError,
     VectorIndexUnavailableError,
 )
-from doc3gpp.models.spec_doc import SpecDocSearchFilters
+from doc3gpp.models.spec_doc import SpecDocSearchFilters, SpecDocSelectionError
 from doc3gpp.models.unified_search import (
     spec_doc_search_result_to_dict,
     tdoc_search_result_to_dict,
 )
 from doc3gpp.parsers.direct_extractor import is_3gpp_ftp_url
+from doc3gpp.scraping.spec_doc_source import validate_release_version_alignment
 from doc3gpp.web import render
 from doc3gpp.web.errors import (
     MCP_CODE_INTERNAL_ERROR,
@@ -915,18 +916,22 @@ def build_mcp_server(state: WebState) -> MCPServer:
     ) -> str:
         return _enqueue(state, JobKind.SYNC_TESTCASES, {"force": force}, "queued sync_testcases")
 
-    @server.tool(name="parse_spec_docs", description="Enqueue a spec-doc parse batch (mirrors `doc3gpp spec doc parse`). Each spec resolves its version via the stored spec_versions rows; results land as {requested, successes, skipped, failures}. Returns a job_id; poll `get_job` for progress and `cancel_job` to abort.")
+    @server.tool(name="parse_spec_docs", description="Enqueue a spec-doc parse (mirrors `doc3gpp spec doc parse`). The spec resolves its version via the stored spec_versions rows; results land as {requested, successes, skipped, failures}. Returns a job_id; poll `get_job` for progress and `cancel_job` to abort.")
     @_mcp_error_guard
     def parse_spec_docs(
-        spec_ids: Annotated[list[str], Field(description="Spec ids to parse (at least one, e.g. ['38.331']).")],
+        spec_id: Annotated[str, Field(description="Spec id to parse (e.g. '38.331').")],
         release: Annotated[str | None, Field(description="Release marker (e.g. 'Rel-18').")] = None,
         version: Annotated[str | None, Field(description="Exact version (e.g. '18.5.0').")] = None,
         force: Annotated[bool, Field(description="Re-parse already-parsed pairs.")] = False,
     ) -> str:
-        if not spec_ids:
-            raise InvalidFilterError("spec_ids is required")
+        if not spec_id.strip():
+            raise InvalidFilterError("spec_id is required")
+        try:
+            validate_release_version_alignment(release, version)
+        except SpecDocSelectionError as exc:
+            raise InvalidFilterError(str(exc)) from exc
         params: dict[str, Any] = {
-            "spec_ids": list(spec_ids),
+            "spec_id": spec_id,
             "force": force,
         }
         if release is not None:
@@ -935,7 +940,7 @@ def build_mcp_server(state: WebState) -> MCPServer:
             params["version"] = version
         return _enqueue(
             state, JobKind.PARSE_SPEC_DOCS, params,
-            f"queued parse_spec_docs for {len(spec_ids)} spec(s)",
+            f"queued parse_spec_docs for {spec_id}",
         )
 
     @server.tool(name="index_tdocs", description="Enqueue TDoc FTS5/vector index maintenance.")

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/web/routes/jobs.py

@@ -20,7 +20,9 @@ from fastapi.responses import JSONResponse, StreamingResponse
 from pydantic import BaseModel
 
 from doc3gpp.models.jobs import Job, JobKind, JobStatus, JSONValue
+from doc3gpp.models.spec_doc import SpecDocSelectionError
 from doc3gpp.repository.protocols import JobRepository
+from doc3gpp.scraping.spec_doc_source import validate_release_version_alignment
 from doc3gpp.web.deps import get_job_repo, get_job_worker
 from doc3gpp.web.errors import (
     InvalidFilterError,
@@ -143,7 +145,7 @@ class _ParseTDocURLBody(BaseModel):
 
 
 class _ParseSpecDocsBody(BaseModel):
-    spec_ids: list[str]
+    spec_id: str
     release: str | None = None
     version: str | None = None
     force: bool = False
@@ -324,13 +326,17 @@ async def post_parse_spec_docs(
     body: _ParseSpecDocsBody,
     job_repo: JobRepository = Depends(get_job_repo),
 ) -> JSONResponse:
-    """Enqueue a spec-doc parse batch (mirrors ``doc3gpp spec doc parse``)."""
-    if not body.spec_ids:
+    """Enqueue a single spec-doc parse (mirrors ``doc3gpp spec doc parse``)."""
+    if not body.spec_id.strip():
         raise InvalidFilterError(
-            "parse/spec-docs requires a non-empty 'spec_ids' list in the body"
+            "parse/spec-docs requires a non-empty 'spec_id' string in the body"
         )
+    try:
+        validate_release_version_alignment(body.release, body.version)
+    except SpecDocSelectionError as exc:
+        raise InvalidFilterError(str(exc)) from exc
     params: dict[str, JSONValue] = {
-        "spec_ids": list(body.spec_ids),
+        "spec_id": body.spec_id,
         "force": body.force,
     }
     if body.release is not None:

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/web/static/js/spec_doc_parse.js

@@ -16,7 +16,7 @@
       buildBody: function (form) {
         var forceEl = form.querySelector('input[name="force"]');
         return JSON.stringify({
-          "spec_ids": [specId],
+          "spec_id": specId,
           "version": version,
           "force": sourceParsed && !!forceEl && forceEl.checked,
         });

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/src/doc3gpp/web/workers/handlers.py

@@ -24,7 +24,9 @@ from doc3gpp.cli_auto_sync import (
 )
 from doc3gpp.models.index import IndexRequest
 from doc3gpp.models.jobs import Job, JobKind, JSONValue
+from doc3gpp.models.spec_doc import SpecDocSelectionError
 from doc3gpp.parsers.direct_extractor import is_3gpp_ftp_url
+from doc3gpp.scraping.spec_doc_source import validate_release_version_alignment
 from doc3gpp.settings.schema import Settings
 from doc3gpp.web.state import ServiceContainer
 
@@ -456,24 +458,26 @@ async def _parse_spec_docs(
     progress: ProgressFn,
     cancel_event: asyncio.Event,
 ) -> Mapping[str, JSONValue]:
-    spec_ids = job.params.get("spec_ids")
-    if not isinstance(spec_ids, list) or not spec_ids or not all(
-        isinstance(s, str) for s in spec_ids
-    ):
+    spec_id = job.params.get("spec_id")
+    if not isinstance(spec_id, str) or not spec_id.strip():
         raise ValueError(
-            "parse_spec_docs job requires a non-empty 'spec_ids' list parameter"
+            "parse_spec_docs job requires a non-empty 'spec_id' string parameter"
         )
     release = job.params.get("release")
     version = job.params.get("version")
     force = bool(job.params.get("force", False))
     release = release if isinstance(release, str) else None
     version = version if isinstance(version, str) else None
+    try:
+        validate_release_version_alignment(release, version)
+    except SpecDocSelectionError as exc:
+        raise ValueError(str(exc)) from exc
 
     service = getattr(services, "spec_doc", None)
     if service is None:
         raise RuntimeError("spec-doc parse is not available in this build")
 
-    progress(f"parsing {len(spec_ids)} spec doc(s)")
+    progress(f"parsing spec doc {spec_id}")
 
     def on_progress(event: str, data: Mapping[str, object]) -> None:
         if event == "spec_done":
@@ -483,7 +487,7 @@ async def _parse_spec_docs(
         raise asyncio.CancelledError()
     result = await asyncio.to_thread(
         service.parse_many,
-        list(spec_ids),
+        [spec_id],
         release=release,
         version=version,
         force=force,
@@ -499,7 +503,7 @@ async def _parse_spec_docs(
         force=True,
     )
     return {
-        "requested": len(spec_ids),
+        "requested": 1,
         "successes": len(result.successes),
         "skipped": len(result.skipped),
         "failures": len(result.failures),

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/tests/integration/test_mcp_end_to_end.py

@@ -113,6 +113,21 @@ def test_list_tools_exposes_read_and_job_tools(sqlite_env) -> None:
     assert not any(name.startswith("fetch_spec") for name in names)
 
 
+def test_parse_spec_docs_uses_scalar_spec_id(sqlite_env) -> None:
+    import asyncio
+
+    _, server = _state_and_server()
+
+    async def run():
+        tools = await server.list_tools()
+        return next(tool for tool in tools if tool.name == "parse_spec_docs")
+
+    tool = asyncio.run(run())
+    properties = tool.input_schema["properties"]
+    assert "spec_id" in properties
+    assert "spec_ids" not in properties
+
+
 def test_call_list_meetings_empty(sqlite_env) -> None:
     """Empty result is a single ``[]`` JSON string (not zero content items)."""
     import asyncio

{doc3gpp-0.3.2 → doc3gpp-0.3.3}/tests/integration/test_spec_doc_cli.py

@@ -59,3 +59,64 @@ def test_spec_doc_parse_forwards_force(monkeypatch):
 
     assert result.exit_code == 0, result.output
     assert calls == [(["38.331"], None, None, True)]
+
+
+def test_spec_doc_parse_rejects_repeated_spec(monkeypatch):
+    calls = []
+
+    class FakeResult:
+        successes = {}
+        skipped = {}
+        failures = {}
+
+    class FakeService:
+        def parse_many(self, spec_ids, *, release, version, force):
+            calls.append((spec_ids, release, version, force))
+            return FakeResult()
+
+    monkeypatch.setattr("doc3gpp.cli.create_schema", lambda _scope: None)
+    monkeypatch.setattr("doc3gpp.cli.build_spec_doc_service", lambda: FakeService())
+
+    result = CliRunner().invoke(
+        app,
+        ["spec", "doc", "parse", "--spec", "38.331", "--spec", "38.523-1"],
+    )
+
+    assert result.exit_code != 0, result.output
+    assert calls == []
+
+
+def test_spec_doc_parse_rejects_misaligned_release_and_version(monkeypatch):
+    calls = []
+
+    class FakeResult:
+        successes = {}
+        skipped = {}
+        failures = {}
+
+    class FakeService:
+        def parse_many(self, spec_ids, *, release, version, force):
+            calls.append((spec_ids, release, version, force))
+            return FakeResult()
+
+    monkeypatch.setattr("doc3gpp.cli.create_schema", lambda _scope: None)
+    monkeypatch.setattr("doc3gpp.cli.build_spec_doc_service", lambda: FakeService())
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "spec",
+            "doc",
+            "parse",
+            "--spec",
+            "38.331",
+            "--release",
+            "Rel-18",
+            "--version",
+            "17.5.0",
+        ],
+    )
+
+    assert result.exit_code != 0, result.output
+    assert "does not match" in result.output
+    assert calls == []