Merge pull request #10 from rastagan-git/agent/complete-issue-8

Complete Issue #8 CLI and provenance semantics

Author: rastagan-git

.agents/skills/curate-aroma-data/SKILL.md

@@ -7,6 +7,8 @@ description: Use AromaNexus to validate, normalize, enrich, and export flavor, o
 
 Build traceable compound tables through the repository's `aromanexus` CLI. Keep the skill as an orchestration layer; modify provider behavior in the Python package, not here.
 
+If the console launcher is unavailable, replace `aromanexus ...` with the equivalent `python -m aromanexus ...` invocation.
+
 ## Workflow
 
 1. Inspect the input without modifying it.
@@ -21,12 +23,14 @@ Build traceable compound tables through the repository's `aromanexus` CLI. Keep
    - Use Pyrfume only for explicitly selected archives after reviewing each manifest note.
    - Use M2OR only when receptor bioassay evidence is relevant; label species and assay scope.
 3. Preview the operation.
-   - State the input, selected worksheet for XLSX, new output path, selected provider, expected columns, skip patterns, approximate request count, cache behavior, and material access caveats.
+   - State the input, selected worksheet for XLSX, new output path, selected provider, expected columns, skip patterns, whether odor annotations are requested, any existing-CAS confirmation column, approximate request count, cache behavior, and material access caveats.
    - Write a sibling output by default. Never reuse the input path as the output path; `--force` is only for a separate existing destination.
    - Keep XLSX input and output when worksheet formulas, formatting, or other workbook content must survive; CSV/TSV output is a flat export.
 4. Run one focused command.
    - Identity and odor metadata: `aromanexus pubchem INPUT --identifier-column "CAS Number"`
    - Name lookup with dataset-specific structural rows: `aromanexus pubchem INPUT --identifier-column "Name" --skip-pattern '^C\d+$'`
+   - Name lookup with a conservative existing-CAS signal: `aromanexus pubchem INPUT --identifier-column "Name" --existing-cas-column "Existing CAS"`
+   - Identity without PUG-View requests or odor-only output columns: `aromanexus pubchem INPUT --no-odor`
    - Retention indices: `aromanexus nist-ri INPUT --cas-column "CAS Number" --calculated-ri-column "Calculated RI"`
    - Names to CAS: `aromanexus resolve-cas INPUT --name-column "Name"`
    - Curated descriptors: `aromanexus pyrfume INPUT --archives aromadb,superscent`
@@ -35,10 +39,10 @@ Build traceable compound tables through the repository's `aromanexus` CLI. Keep
    - For XLSX only, append `--sheet "SHEET"` to any table command when the target is not the first worksheet. Never pass `--sheet` for CSV or TSV.
 5. Verify the result.
    - Re-run the inspection script on the same worksheet for XLSX, or without `--sheet` for CSV/TSV.
-   - Confirm identical row order and row count, expected new fields, typed status counts, source URL, retrieval time, version, and license/access fields.
+   - Confirm identical row order and row count, expected new fields, typed status counts, source URL, retrieval time, version, and license/access fields. Treat a blank retrieval time as correct when no provider or cached representation was obtained, including an explicit pre-request skip.
    - For XLSX output, also compare worksheet order and names, per-sheet content digests, workbook properties, non-target-sheet content, untargeted source formulas and cached values, styles, dimensions, and reported workbook features.
    - Treat `PubChem Status` as provider execution state, not proof of a uniquely resolved CAS. Check `PubChem CAS Resolution`, candidate count, and `Resolved CAS` separately.
-   - Leave `multiple` and `missing` CAS resolutions unresolved; retain all candidates and route only the affected rows to a targeted fallback source or manual review.
+   - Leave `multiple`, `missing`, `input_cas_conflict`, and `input_cas_invalid` CAS resolutions unresolved; retain all candidates and route only the affected rows to a targeted fallback source or manual review.
    - Treat `http_error`, `network_error`, `parse_error`, `missing_data`, `data_error`, `partial`, `blocked`, and `skipped` separately from `not_found`.
    - Consult [references/output-schema.md](references/output-schema.md) when reconciling columns or statuses.
 6. Report the output path, provider versions, status counts, partial failures, and any source terms the user must still review.
@@ -54,3 +58,4 @@ Build traceable compound tables through the repository's `aromanexus` CLI. Keep
 - Preserve merged cells outside the selected tabular rectangle; stop before provider calls when a merge intersects that rectangle.
 - Stop before provider calls if XLSX preflight reports a known unsafe feature or any OOXML package part that the in-memory trial write would discard.
 - Never select the first PubChem CAS candidate merely because the provider status is `ok`.
+- Use an existing CAS column only to confirm a returned candidate for a non-CAS query. Never overwrite it or use a conflicting/invalid value to force resolution.

.agents/skills/curate-aroma-data/references/output-schema.md

@@ -15,11 +15,14 @@ Keep provider execution and CAS curation in separate columns:
 - `PubChem CAS Numbers`: every checksum-valid candidate retained for review.
 - `PubChem CAS Candidate Count`: the number of distinct valid candidates.
 - `PubChem CAS Resolution`: the conservative resolution decision.
-- `Resolved CAS`: populate only for `query_confirmed` or `unique`.
+- `Resolved CAS`: populate only for `query_confirmed`, `input_cas_confirmed`, or `unique`.
 
 Interpret `PubChem CAS Resolution` as follows:
 
 - `query_confirmed`: the input was a checksum-valid CAS and PubChem resolved its record.
+- `input_cas_confirmed`: for a non-CAS query, the optional existing CAS was valid and appeared among the returned candidates.
+- `input_cas_conflict`: the optional existing CAS was valid but absent from the returned candidates; keep `Resolved CAS` empty.
+- `input_cas_invalid`: the optional existing CAS was nonblank but invalid; keep `Resolved CAS` empty.
 - `unique`: a successful name lookup returned exactly one valid CAS candidate.
 - `multiple`: more than one valid candidate remains; keep `Resolved CAS` empty.
 - `missing`: a successful record returned no valid CAS candidate; keep `Resolved CAS` empty.
@@ -43,10 +46,20 @@ Interpret `PubChem CAS Resolution` as follows:
 
 Do not merge an access, transport, HTTP, snapshot, parse, or partial failure into `not_found`.
 
+When the optional existing-CAS cell is blank or missing, use the normal `unique`, `multiple`, or `missing` rule. A valid CAS query itself always takes precedence as `query_confirmed`. Never modify the existing-CAS column or remove candidates from `PubChem CAS Numbers`.
+
+For a `partial` provider result, accept only positive `query_confirmed` or `input_cas_confirmed` evidence. Do not infer `unique`, `multiple`, `missing`, `input_cas_conflict`, or `input_cas_invalid` from a potentially incomplete secondary response; use `not_evaluated` instead.
+
+## Optional odor columns
+
+PubChem odor enrichment is enabled by default. With `--no-odor`, skip PUG-View requests and do not add or update `PubChem Odor`, `PubChem Odor Annotations`, `PubChem Odor Sources`, `PubChem Odor Source URLs`, or `PubChem Odor License URLs`. Preserve any such columns already present in the input.
+
 ## Provenance
 
 Keep provider status, source URL, retrieval time, cache-hit flag, pinned version or snapshot, license URL, and message columns. For PubChem odor text, also keep contributor source names, URLs, and license URLs.
 
+`Retrieved At` is the timestamp of an actual provider or cached representation. Leave it empty for outcomes decided before any representation was obtained, including explicit skips, local input validation failures, and transport failures before a response. A received HTTP or parse-error response retains its retrieval timestamp.
+
 ## Workbook QA
 
 After every run, confirm:
@@ -57,7 +70,7 @@ After every run, confirm:
 4. Every processed row has a typed status.
 5. Remote strings beginning with `=`, `+`, `-`, or `@` are stored as literal text.
 6. Partial outputs are reported separately if a run is interrupted.
-7. `multiple`, `missing`, `not_evaluated`, and `skipped` PubChem CAS resolutions never contain an automatic `Resolved CAS`.
+7. `multiple`, `missing`, `input_cas_conflict`, `input_cas_invalid`, `not_evaluated`, and `skipped` PubChem CAS resolutions never contain an automatic `Resolved CAS`.
 8. XLSX worksheet order and names match the input, and supported non-target worksheet content and features are unchanged.
 9. Source formulas and cached results outside explicitly targeted output cells, plus styles, dimensions, freeze panes, filters, tables, data validation, conditional formatting, and workbook properties, remain present where applicable.
 10. Merged cells outside the selected tabular rectangle remain present; a merge intersecting that rectangle is rejected before provider access.

README-CN.md

@@ -57,6 +57,9 @@ python -m pip install -e .
 ```bash
 aromanexus --version
 aromanexus sources
+
+# 控制台启动器不可用时，可使用等价的模块入口
+python -m aromanexus --version
 ```
 
 ## 快速开始
@@ -70,6 +73,12 @@ aromanexus pubchem compounds.xlsx --identifier-column "CAS Number"
 # 在名称查询前跳过当前数据集中的结构标签
 aromanexus pubchem compounds.xlsx --identifier-column "Name" --skip-pattern '^C\d+$'
 
+# 只把已有 CAS 列作为名称查询候选的保守确认信号
+aromanexus pubchem compounds.xlsx --identifier-column "Name" --existing-cas-column "Existing CAS"
+
+# 跳过 PUG-View 请求，并省略仅用于气味信息的输出列组
+aromanexus pubchem compounds.xlsx --no-odor
+
 # 按精确名称选择工作表
 aromanexus pubchem compounds.xlsx --sheet "Data" --identifier-column "Name"
 
@@ -125,7 +134,11 @@ aromanexus --cache-dir .cache/aromanexus --timeout 30 pubchem compounds.xlsx
 
 [Openpyxl 无法保留所有 OOXML 功能](https://openpyxl.readthedocs.io/en/3.1/tutorial.html)。因此，AromaNexus 会先在内存中试写一遍；若检测到绘图形状、批注、ActiveX/OLE 控件、切片器、线程批注、VML、数字签名等已知高风险内容，或任何会被试写丢弃的 OOXML 包部件，就会在调用数据源前停止。Excel 的可选计算链可能会被移除，以便表格软件重新生成。若显式输出 CSV/TSV，结果只是扁平表格，无法保留 Excel 专属内容。
 
-默认来源记录包括数据源状态、来源 URL、获取时间、是否命中缓存、固定版本、许可 URL 与诊断信息。PubChem 会单独报告 CAS 解析状态；仅当输入 CAS 得到确认，或只剩一个校验有效的候选时，才填入 `Resolved CAS`。多个或缺失候选会保持未解析。只有在确实需要旧版形状时才使用 `--no-provenance`。
+默认来源记录包括数据源状态、来源 URL、获取时间、是否命中缓存、固定版本、许可 URL 与诊断信息。`Retrieved At` 只表示真正取得数据源响应或缓存表示的时间；显式 `skipped`、请求前发现的无效输入、尚未收到响应的网络失败等本地结果会留空。只有在确实需要旧版形状时才使用 `--no-provenance`。
+
+PubChem 会单独报告 CAS 解析状态。仅当查询本身是已确认的 CAS、名称查询只剩一个校验有效的候选，或 `--existing-cas-column` 中的有效 CAS 确实出现在返回候选里时，才填入 `Resolved CAS`。已有 CAS 与候选冲突或本身无效时保持未解析；空单元格会回退到原有的 `unique`、`multiple` 或 `missing` 规则。对于 `partial` 数据源结果，只接受查询或已有 CAS 的正向确认；依赖完整候选集合的判断会保持 `not_evaluated`。原始标识符列和已有 CAS 列都不会被改写；若已有 CAS 列名与当前输出列重叠，CLI 会在请求前拒绝运行。
+
+PubChem 气味扩充默认开启。`--no-odor` 会跳过 PUG-View 请求，并且不新增或更新 `PubChem Odor`、`PubChem Odor Annotations`、`PubChem Odor Sources`、`PubChem Odor Source URLs`、`PubChem Odor License URLs`。如果输入中原本就有这些列，它们会原样保留。
 
 ```bash
 # 明确指定输出位置

README.md

@@ -57,6 +57,9 @@ Confirm the installation and review provider modes before a live run:
 ```bash
 aromanexus --version
 aromanexus sources
+
+# Equivalent module entry when the console launcher is unavailable
+python -m aromanexus --version
 ```
 
 ## Quick start
@@ -70,6 +73,12 @@ aromanexus pubchem compounds.xlsx --identifier-column "CAS Number"
 # Skip dataset-specific structural labels before a name lookup
 aromanexus pubchem compounds.xlsx --identifier-column "Name" --skip-pattern '^C\d+$'
 
+# Use an existing CAS column only to confirm candidates from a name lookup
+aromanexus pubchem compounds.xlsx --identifier-column "Name" --existing-cas-column "Existing CAS"
+
+# Skip PUG-View requests and omit the odor-only output column group
+aromanexus pubchem compounds.xlsx --no-odor
+
 # Select a worksheet by its exact name
 aromanexus pubchem compounds.xlsx --sheet "Data" --identifier-column "Name"
 
@@ -125,7 +134,11 @@ For XLSX-to-XLSX runs, AromaNexus starts from an immutable copy of the source pa
 
 [Openpyxl cannot preserve every OOXML feature](https://openpyxl.readthedocs.io/en/3.1/tutorial.html). AromaNexus therefore performs an in-memory trial round trip and stops before provider calls when it detects known unsafe content—such as drawing shapes, comments, ActiveX/OLE controls, slicers, threaded comments, VML, or digital signatures—or any package part that the trial would discard. Excel's optional calculation chain may be removed so spreadsheet software can rebuild it. An explicit CSV/TSV output is a flat export and cannot retain Excel-only content.
 
-By default, provenance columns include provider status, source URL, retrieval timestamp, cache hit, pinned version, license URL, and a diagnostic message. PubChem reports CAS resolution separately and populates `Resolved CAS` only when the input is a confirmed CAS or exactly one checksum-valid candidate remains. Multiple or missing candidates stay unresolved. Use `--no-provenance` only for legacy-shaped output.
+By default, provenance columns include provider status, source URL, retrieval timestamp, cache hit, pinned version, license URL, and a diagnostic message. `Retrieved At` records when a provider or cached representation was actually obtained. It stays empty for local pre-request outcomes such as an explicit `skipped` row, invalid input, or a network failure before any response. Use `--no-provenance` only for legacy-shaped output.
+
+PubChem reports CAS resolution separately and populates `Resolved CAS` only when the query itself is a confirmed CAS, a name lookup has exactly one checksum-valid candidate, or `--existing-cas-column` supplies a valid CAS that appears among the returned candidates. A conflicting or invalid existing CAS keeps the result unresolved; a blank cell falls back to the normal `unique`, `multiple`, or `missing` decision. For a `partial` provider result, only positive query or existing-CAS confirmation can resolve the row; decisions that depend on a complete candidate set remain `not_evaluated`. The original identifier and existing-CAS columns are never rewritten, and the CLI rejects an existing-CAS column name that overlaps an active output column.
+
+PubChem odor enrichment is enabled by default. `--no-odor` skips PUG-View requests and does not add or update `PubChem Odor`, `PubChem Odor Annotations`, `PubChem Odor Sources`, `PubChem Odor Source URLs`, or `PubChem Odor License URLs`. If those columns already exist in the input, they are preserved unchanged.
 
 ```bash
 # Choose an output explicitly

aromanexus/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for ``python -m aromanexus``."""
+
+from aromanexus.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aromanexus/cli.py

@@ -118,9 +118,24 @@ def build_parser() -> argparse.ArgumentParser:
     pubchem.add_argument(
         "--resolved-cas-column",
         default="Resolved CAS",
-        help="Output column populated only for query-confirmed or unique CAS resolution",
+        help=(
+            "Output column populated only when the query, an existing CAS, or one unique "
+            "candidate is confirmed"
+        ),
+    )
+    pubchem.add_argument(
+        "--existing-cas-column",
+        metavar="COLUMN",
+        help=(
+            "Optional existing CAS column used to confirm name-query candidates; "
+            "invalid or conflicting values remain unresolved"
+        ),
+    )
+    pubchem.add_argument(
+        "--no-odor",
+        action="store_true",
+        help="Skip PUG-View requests and do not add or update odor-only output columns",
     )
-    pubchem.add_argument("--no-odor", action="store_true", help="Skip PUG-View odor annotations")
     pubchem.set_defaults(handler=_handle_pubchem)
 
     pyrfume = subparsers.add_parser(
@@ -221,6 +236,7 @@ def _handle_pubchem(args: argparse.Namespace) -> RunSummary:
         args.input,
         client,
         identifier_column=args.identifier_column,
+        existing_cas_column=args.existing_cas_column,
         resolved_cas_column=args.resolved_cas_column,
         skip_patterns=args.skip_pattern,
         include_odor=not args.no_odor,

aromanexus/models.py

@@ -35,12 +35,14 @@ def failure(
         status: str,
         message: str,
         source_url: str = "",
+        retrieved_at: str = "",
     ) -> LookupResult:
         return cls(
             provider=provider,
             status=status,
             message=message,
             source_url=source_url,
+            retrieved_at=retrieved_at,
         )
 
     def provenance_columns(self, prefix: str | None = None) -> dict[str, Any]:

aromanexus/sources/pubchem.py

@@ -411,6 +411,7 @@ def _failure(self, *, status: str, message: str, source_url: str = "") -> Lookup
             status=status,
             message=message,
             source_url=source_url,
+            retrieved_at="",
             version=PUBCHEM_VERSION,
             license_url=PUBCHEM_LICENSE_URL,
         )