feat(explorer): accept the modelChemistry LevelOfTheory call form in the source guard

[alongd]

Stacked on #197 — based on i016-ts-positional, so this PR's diff shows only its own change. GitHub retargets it to main automatically when #197 merges. Review #197 first.

What this fixes

T3's PES loop writes a hybrid network in round 0 and reads it back in round 1. #197 fixed the first defect on that handoff. With #197 in place round 1 gets further and dies again, in a different reader, on line 1 of every hybrid T3 writes:

ValueError: Refusing to use '.../network0_reduced.py' as an Arkane explorer/network source:
line 1 assigns something that is not a literal ("modelChemistry = LevelOfTheory(
method='wb97xd2023',basis='def2tzvp',software='ga..."). This source's text is spliced verbatim
into a NEW file Arkane will exec, so a top-level assignment must be a plain literal value.

_validate_source_statements calls ast.literal_eval on every top-level assignment's value. The line is T3's own and deliberate: the source network has no modelChemistry at all, t3/pdep/hybrid.py introduces it, and that module names LevelOfTheory/CompositeLevelOfTheory as the two call forms an Arkane modelChemistry directive may legitimately take. ARC's independently generated Arkane inputs carry the identical spelling. Arkane execs these files, so the call resolves there.

The change

The literal-only rule stays, and so do its siblings (refusing ** unpacking, refusing to rebind names Arkane defines). One exception: when the target is modelChemistry and the value is a genuine ast.Call to one of the two known names, validate it with t3.pdep.hybrid._validate_model_chemistry_expression — the same structural checker T3 uses when it emits this directive — instead of refusing it as non-literal.

Reusing that checker rather than growing a second allowlist is deliberate: it already type-checks each keyword against Arkane's real LevelOfTheory schema, narrowed below it on purpose, and two copies of that rule would drift silently.

Gating on a real call node matters and is not incidental: the checker treats any non-call string as a plain label and only injection-checks it, so routing an arbitrary value there would accept modelChemistry = 1 + 2. Computed values keep falling through to the refusal. Pinned by test_a_computed_non_call_model_chemistry_value_is_still_refused.

Testing

• tests/test_pdep/test_explorer_input_file.py: 266 passed. The three accept-cases were red before the fix ("assigns something that is not a literal") and green after; the refusal cases were green throughout.
• tests/test_pdep: 1915 passed, 134 s.
• Regression: test_hybrid + test_energy_settings 137 passed; test_main_wiring + test_capture + test_pes_qm 215 passed. No circular import (hybrid imports parser and writer, never input_file).
• Driven on the real artifact. Seeding a loop run with the pilot's own round-0 hybrid now gets past write_arkane_explorer_input_file — verified end to end, no cluster, no quantum chemistry. It then stops further along at an unrelated seed-label mismatch, tracked separately.

[Copilot]

Pull request overview

This PR updates the Arkane explorer/network source guard to accept the real-world modelChemistry = LevelOfTheory(...) / CompositeLevelOfTheory(...) call form (while keeping the existing “literal-only top-level assignment” policy for everything else), aligning the explorer reader with T3/ARC’s writer behavior.

Changes:

• Allow modelChemistry assignments whose value is a validated LevelOfTheory(...) / CompositeLevelOfTheory(...) AST call (via the existing _validate_model_chemistry_expression structural checker).
• Add targeted tests covering accepted modelChemistry call forms and ensuring computed/non-call values remain refused.
• Ignore docs/contracts/ via .gitignore.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

File	Description
t3/pdep/explorer/input_file.py	Adds a narrow exception for modelChemistry assignments to permit validated call expressions while preserving the literal-only rule elsewhere.
tests/test_pdep/test_explorer_input_file.py	Adds regression tests for accepting valid modelChemistry call forms and refusing malformed/computed variants.
.gitignore	Adds docs/contracts/ to ignored paths.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.72%. Comparing base (8752bb3) to head (ab11884).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #198      +/-   ##
==========================================
- Coverage   82.73%   82.72%   -0.01%     
==========================================
  Files          72       72              
  Lines       11722    11729       +7     
  Branches     2527     2528       +1     
==========================================
+ Hits         9698     9703       +5     
- Misses       1433     1434       +1     
- Partials      591      592       +1     

Flag	Coverage Δ
unittests	82.72% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.