Tom's rewrite

.github/workflows/ci.yml

@@ -61,11 +61,11 @@ jobs:
       with:
         name: dist
 
-    - name: Install package and pytest
+    - name: Install package and test dependencies
       shell: bash
       run: |
         WHL_NAME=$(ls molecule_resolver-*.whl)
-        pip install ${WHL_NAME} pytest
+        pip install ${WHL_NAME} pytest pytest-mock
 
     - name: Run tests
       shell: bash

docs/context_lifecycle.md

@@ -0,0 +1,21 @@
+# Runtime Context Lifecycle
+
+`MoleculeResolver` context management is intentionally limited to runtime resources.
+
+## Enter
+
+The `with MoleculeResolver() as mr:` enter step performs only:
+
+1. RDKit log suppression context setup.
+2. Molecule cache context setup.
+3. OPSIN temp folder creation (when OPSIN batch support is enabled).
+
+## Exit
+
+The exit step performs only:
+
+1. Molecule cache context teardown.
+2. RDKit log suppression context teardown.
+3. OPSIN temp folder cleanup (skipped when an exception is bubbling up).
+
+This separation keeps search and resolution logic outside lifecycle handling, so runtime setup/teardown stays predictable and easier to maintain.

docs/evidence.md

@@ -0,0 +1,20 @@
+# Evidence Output (`include_evidence`)
+
+`find_single_molecule_crosschecked(..., include_evidence=True)` returns a
+`ResolutionResult` instead of only a `Molecule`.
+
+## Response fields
+
+- `best_molecule`: Selected molecule (or `None` for unresolved ties).
+- `ranked_candidates`: List of `CandidateEvidence` entries sorted by score.
+- `grouped_by_structure`: Raw grouped molecules by SMILES.
+- `selected_smiles`: SMILES selected as best candidate.
+- `selection_reason`: Why this result form was returned.
+
+## CandidateEvidence fields
+
+- `service_agreement_count`: Number of unique supporting services.
+- `identifier_concordance_count`: Number of unique supporting identifiers.
+- `synonym_overlap_count`: Repeated synonym matches across supporting molecules.
+- `score_breakdown`: Explicit points per evidence component.
+- `total_score`: Sum of `score_breakdown`.

docs/scoring.md

@@ -0,0 +1,27 @@
+# Consensus Scoring
+
+`find_single_molecule_crosschecked(..., resolution_mode="consensus")` uses an
+explicit score model for grouped structure candidates.
+
+## Score Components
+
+- `crosscheck_points`: `crosscheck_count * 100`
+- `opsin_bonus`: `30` if at least one supporting OPSIN name match exists
+- `stereo_specificity_bonus`: RDKit-derived stereochemistry signal:
+  - defined chiral centers: `20` points each
+  - stereochemical bonds: `15` points each
+  - unresolved chiral centers: `5` points each
+
+## Deterministic Tie-Breaking
+
+When total score ties, the selector orders by:
+
+1. Higher crosscheck count
+2. Higher OPSIN bonus
+3. Higher stereo specificity bonus
+4. Higher defined chirality bonus
+5. Higher bond stereo bonus
+6. Lexicographical SMILES fallback
+
+This removes raw SMILES length from score weighting while preserving a stable
+deterministic result.

docs/search_strategy.md

@@ -0,0 +1,25 @@
+# Search Strategy
+
+`find_single_molecule`, `find_single_molecule_crosschecked`, and
+`find_multiple_molecules_parallelized` now support `search_strategy`.
+
+## Options
+
+- `first_hit` (default): preserves the previous behavior and returns as soon as
+  the first matching candidate is found in service order.
+- `exhaustive`: evaluates all provided identifier/mode combinations across the
+  selected services, deduplicates candidates, and chooses the best supported
+  structure group.
+
+## Example
+
+```python
+from moleculeresolver import MoleculeResolver
+
+with MoleculeResolver() as mr:
+    molecule = mr.find_single_molecule(
+        identifiers=["ethanol", "ethyl alcohol"],
+        modes=["name", "name"],
+        search_strategy="exhaustive",
+    )
+```