PR: OPSIN verification by default in the CLI + Readme fix

[r-fedorov]

PR enables OPSIN verification by default in the CLI, improves trace segment metadata for parent/substituent parents, attaches parent selection/numbering decisions to trace output, updates tests, and cleans up outdated README/refactor documentation.

Summary by Sourcery

Enable OPSIN verification by default in the CLI and enrich trace metadata and debugging hooks across the naming, analysis, describe, and web APIs.

New Features:

• Add CLI, web, and public API support for a token_debug flag to include verbose emitted token metadata in traces and descriptions.
• Expose a verify_opsin option in the human-readable descriptor to optionally round-trip names via OPSIN and report failures.
• Introduce explicit CLI flags for toggling OPSIN verification and token-debug output on name, batch, and describe commands.

Enhancements:

• Distinguish parent and substituent parent skeleton segments in trace metadata and attach parent selection and numbering decisions directly to main parent trace segments.
• Extend numbering trace metadata with bond coverage and a per-atom atom_to_locant mapping.
• Gate emission of emitted_tokens and name_token_spans behind token_debug so normal traces stay lightweight while debug traces gain richer binding data.
• Update describe and human-like description APIs, CLI help, and README to reflect the new token_debug controls, OPSIN verification defaults, and additional dataset coverage.
• Relax parent-segment matching in substituent trees to recognize both parent and substituent parent labels and keys.

Tests:

• Add coverage for substituent parent and main parent trace segment metadata, including attached parent selection and numbering decisions.
• Add tests confirming that emitted_tokens and name_token_spans only appear when token_debug is enabled for both name and analyze_smiles.
• Update describer integration tests and CLI tests to use the new token_debug flag and validate exposure of token binding summaries in debug mode.

Summary by CodeRabbit

• New Features

  • Added a --token-debug option across the CLI and web API, plus support in Python calls, for viewing token-level debug details.
  • Batch naming and description outputs now support the same debug mode consistently.
  • Human-readable descriptions now include improved examples and updated output wording.

• Bug Fixes

  • Refined trace output so debug details appear only when enabled, keeping default results cleaner.
  • Updated OPSIN verification behavior to be enabled by default, with an option to turn it off.

[sourcery-ai]

Reviewer's Guide

Enables OPSIN verification by default in the CLI, introduces an explicit token_debug mode that gates emission of verbose token metadata, enriches trace segments with clearer parent/substituent parent information and attached parent selection/numbering decisions, wires these options through public, CLI, and web APIs, updates tests, and refreshes README docs (removing outdated refactor/debug sections and adding CLI/human-description docs).

Sequence diagram for CLI naming with default OPSIN verification and token_debug

sequenceDiagram
    actor User
    participant CLI as cli__cmd_name
    participant API as name
    participant Engine as NamingEngine_run

    User->>CLI: bluenamer name SMILES [no --verify]
    CLI->>API: name(smiles, include_trace, verify_opsin=True, token_debug)
    API->>Engine: run(NamingRequest)
    Engine-->>API: NamingResult
    API-->>CLI: NamingResult
    CLI-->>User: print name / JSON

    alt [--no-verify]
        User->>CLI: bluenamer name SMILES --no-verify
        CLI->>API: name(smiles, include_trace, verify_opsin=False, token_debug)
    end

    alt [--token-debug]
        User->>CLI: bluenamer name SMILES --token-debug
        CLI->>API: name(smiles, include_trace, verify_opsin, token_debug=True)
        API->>Engine: run(NamingRequest token_debug=True)
        Engine-->>API: NamingResult with verbose token metadata
    end

Loading

File-Level Changes

Change	Details	Files
Make OPSIN verification enabled by default in the CLI and expose a symmetric --no-verify flag across commands and APIs.	Switch CLI --verify flag for name/batch/describe subcommands to argparse.BooleanOptionalAction with default=True, allowing --no-verify to disable OPSIN verification. Thread verify_opsin through describe_human and emit a message when verification fails. Ensure web and public APIs respect verify_opsin defaults while keeping programmatic control unchanged.	src/bluenamer/cli.py src/bluenamer/human_descriptor.py src/bluenamer/web/app.py
Introduce an explicit token_debug mode and restrict emitted token metadata to that mode across naming, analysis, describe, and CLI/web APIs.	Add token_debug field to NamingRequest and thread it through the naming pipeline (engine.run, _analyze, name_many, _run_parallel, _name_one_for_worker, namer.name_component, component_namer.name_component/_shortcut_component_result). Change binding_trace_data and downstream callers to conditionally include emitted_tokens and name_token_spans only when token_debug=True, keeping default traces lighter. Update Description and describe() to use token_debug naming and to gate token summaries/spans behind this flag; update CLI describe command and tests accordingly. Add tests ensuring emitted_tokens and name_token_spans appear only when token_debug=True for both name() and analyze_smiles().	src/bluenamer/engine.py src/bluenamer/name_bindings.py src/bluenamer/component_namer.py src/bluenamer/namer.py src/bluenamer/describer.py src/bluenamer/__init__.py src/bluenamer/cli.py src/bluenamer/web/app.py src/bluenamer/tests/test_public_api.py tests/integration/test_describer.py
Improve trace segment metadata for parent and substituent parents and attach parent selection/numbering decisions directly to trace segments.	Adjust assembly_trace_segments to distinguish main parent vs substituent parent segments via key and label (parent/substituent_parent, parent skeleton/substituent parent skeleton). Introduce attach_main_parent_decisions to join parent selection and numbering DecisionTrace entries onto matching main parent trace segments, including atom_to_locant mapping and bond sets. Update substituent tree token extension logic to treat both parent and substituent_parent segments as parent-like via _is_parent_trace_segment. Expand numbering trace to include bonds (via bond_ids_within) and atom_to_locant in the decision data for better downstream analysis. Add tests validating substituent parent trace labels and that main parent segments carry the expected decisions and atom_to_locant mapping.	src/bluenamer/trace_helpers.py src/bluenamer/name_bindings.py src/bluenamer/component_namer.py src/bluenamer/tests/test_public_api.py
Expose analyze_smiles as a first-class public API with token_debug support and align tests/docs around it.	Re-export analyze_smiles from the public API and engine with a token_debug keyword-only parameter, delegating to the internal analysis pipeline. Write tests that verify analyze_smiles respects token_debug for name_token_spans and emitted_tokens. Update README to document analyze_smiles, add CLI usage examples, and move/refocus human-like description documentation.	src/bluenamer/engine.py src/bluenamer/namer.py src/bluenamer/__init__.py src/bluenamer/tests/test_public_api.py README.md
Refresh documentation by clarifying positioning, adding CLI/human-description examples, and removing obsolete debugging/refactor docs.	Change README wording to describe the tool as derived from Blue Book rules and mention ZINC22 coverage. Add a dedicated CLI section with name/batch examples and document OPSIN verification and --no-verify. Move and streamline the human-like description section, keeping one canonical example and removing duplicated content. Remove the outdated debugging/token-binding and NAMER_REFACTOR documentation files that no longer reflect current APIs.	README.md src/bluenamer/NAMER_REFACTOR.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Warning

Review limit reached

@r-fedorov, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Free

Run ID: 7826b8d8-07e7-4fe3-a46a-bee97053e984

📥 Commits

Reviewing files that changed from the base of the PR and between f9d45db and 507fa74.

📒 Files selected for processing (6)

• README.md
• pyproject.toml
• src/bluenamer/cli.py
• src/bluenamer/human_descriptor.py
• src/bluenamer/tests/test_analysis.py
• src/bluenamer/trace_helpers.py

📝 Walkthrough

Walkthrough

The PR renames debugging_tokens to token_debug across the entire codebase and threads a new token_debug: bool = False flag through NamingRequest, engine, component namer, describer, CLI, and web API. It also adds attach_main_parent_decisions to enrich parent trace segments, distinguishes substituent vs. main parent skeleton keys, adds verify_opsin to describe_human, and updates the README with a CLI section.

token_debug flag, trace enrichment, and API surface changes

Layer / File(s)	Summary
NamingRequest field, trace_helpers enrichment, name_bindings predicate src/bluenamer/engine.py, src/bluenamer/trace_helpers.py, src/bluenamer/name_bindings.py	NamingRequest gains token_debug; trace_helpers adds attach_main_parent_decisions to enrich parent segments with filtered decisions, and distinguishes substituent_parent vs parent keys; binding_trace_data gains include_emitted_tokens flag; _is_parent_trace_segment predicate added.
Engine token_debug propagation and worker wiring src/bluenamer/engine.py	NamingEngine.analyze, analyze_smiles, run, name_many, _analyze, _name_one_for_worker, and _run_parallel all accept and forward token_debug through serial and parallel paths.
component_namer and namer threading src/bluenamer/component_namer.py, src/bluenamer/namer.py	name_component and _shortcut_component_result accept token_debug, gate emitted_tokens/name_token_spans behind it; numbering trace gains bonds and atom_to_locant; assembly trace similarly gated.
Description rename and describe_human verify_opsin src/bluenamer/describer.py, src/bluenamer/human_descriptor.py	Description field, to_dict parameter, and describe() renamed from debugging_tokens to token_debug; describe_human gains verify_opsin parameter with conditional OPSIN-failure paragraph.
Public API, CLI, and web surface src/bluenamer/__init__.py, src/bluenamer/cli.py, src/bluenamer/web/app.py	name/name_many gain token_debug; CLI adds --token-debug and changes --verify to BooleanOptionalAction defaulting to True; web NameRequest/BatchRequest gain token_debug; endpoints wired.
Tests, integration tests, and README src/bluenamer/tests/test_analysis.py, src/bluenamer/tests/test_public_api.py, tests/integration/test_describer.py, README.md	Tests wrap analyze_smiles with token_debug=True; new tests assert presence/absence of emitted_tokens and name_token_spans; integration tests updated to --token-debug; README adds CLI section and describe_human example.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 Hoppin' through the tokens with a flag so neat,
token_debug=True makes the traces complete!
The parent skeleton now knows its place,
attach_main_parent_decisions joins the race.
No more debugging_tokens to confuse the hare—
clean names and rich spans fill the warren with care! 🌿

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="README.md" line_range="94" />
<code_context>
+bluenamer name "CC(=O)Nc1ccccc1" --json     # JSON with trace + rules
+bluenamer batch smiles.txt --output names.jsonl --processes auto
+```
+The CLI tool has a OPSIN verification turned on by default. It can be turned-off with
+
+```bash
</code_context>
<issue_to_address>
**suggestion (typo):** Fix minor grammatical issues in the CLI verification sentence.

Consider rephrasing to: `The CLI tool has OPSIN verification turned on by default. It can be turned off with` (using `OPSIN` without an article and `turned off` without the hyphen) for clearer grammar.

```suggestion
The CLI tool has OPSIN verification turned on by default. It can be turned off with
```
</issue_to_address>

---

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}