Add development standards and enhance curation architecture

[iskoldt-X]

This PR completes the functional migration of the Interactive Curation Suite and extends it with a real-data regression layer. The new repository now reaches parity with the latest curated behavior from the legacy pdb-annotation project while continuing to enforce the architectural rules in developing_styles.md.

Key Features Ported

• Safety: Corrected the fix_mode bypass, added non-destructive field-level skip behavior, and preserved edited value types through typed coercion.
• Oligomer Radar: Integrated the unified oligomer_analysis display flow and promoted oligomer-derived issues into validation gating.
• Science Logic: Implemented multi-chain receptor truncation, orphaned-ligand detection, structure-note enrichment, and label_asym_id mapping.

Real PDB Regression Coverage

This PR also adds a committed real-data regression suite built from audited aggregated PDB fixtures checked into tests/fixtures/real_pdbs/.

Real fixture scope

• Added 9 real PDB fixtures with repo-local JSON bundles
• Added 5 voting logs and 9 validation logs
• No runtime dependence on local workstation paths or external fixture directories

New integration coverage

• Fixture integrity tests: verify committed real fixtures, expected sidecars, and workspace population
• Function-level pipeline tests: cover load_pdb_data, inject_oligomer_alerts, transform_for_csv, and append_to_csvs
• Gating tests: verify app.py accept-all / review / fix-mode availability against real validation and controversy data
• Review-engine prompt tests: verify selected real-data prompt flows using deterministic monkeypatching

Real behaviors now regression-tested

• Real DB TRUNCATION via 5G53
• Real chain_id_override + HALLUCINATION via 9M88
• Real HETEROMER, MISSED_PROTOMER, INCOMPLETE_7TM, and algo_conflicts
• Real auxiliary dispatch coverage for:
  • antibodies.csv
  • nanobodies.csv
  • scfv.csv
  • ramp.csv
  • other_aux_proteins.csv
• Real warning-routing coverage for:
  • UNIPROT_CLASH
  • Fake UniProt
  • Ghost Chain
  • GHOST_LIGAND

Architectural Improvements

• Decoupling: Kept csv_writer.py UI-free and preserved separation of concerns across loader, review, validation, and CSV layers.
• Robustness: Batch mode (auto-accept) continues to fail loudly on schema mismatches rather than silently skipping writes.
• Functional Purity: Preserved return-data-over-mutation patterns in review flows and science transforms.
• Repo portability: Real PDB tests now run entirely from committed fixtures in this repository.

Follow-up Hardening Included

A few small robustness fixes were added after review feedback:

• Normalized validation_display.py handling of explicit null validation buckets
• Hardened extract_validation_entries() against critical_warnings: null / algo_conflicts: null
• Added underscore-form ghost_ligand fatal matching so upstream-style GHOST_LIGAND warnings are treated consistently

Verification Results

• Pytest: 307/307 passed
• New real-data tests: 129 passed
• Linting: no linter errors in touched files
• Coverage: expanded from synthetic fixtures to audited real aggregated PDB data across pipeline, gating, and selected interactive review paths

Known Real-Data Gaps

The real-data audit also made the remaining uncovered paths explicit:

• grk.csv: no audited real fixture currently produces GRK rows
• CLEAN_ENTRIES via real fixture: not currently triggered by the audited real validation logs and remains uncovered by real-data tests

Copilot's summary

This pull request introduces several improvements and standards updates for the GPCR-annotation-tools codebase, focusing on documentation, CSV schema consistency, defensive coding, and user interface enhancements. The most significant changes include the addition of a comprehensive development standards document, updates to CSV schemas to support new data fields, stricter use of immutable constants, and a refactored approach to displaying oligomer analysis in the UI.

Documentation and Standards

• Added a new developing_styles.md file detailing development philosophy, code quality, testing, Git/PR standards, defensive coding idioms, and domain-specific conventions to guide contributors and maintain codebase consistency.

CSV Schema and Data Model Updates

• Updated CSV_SCHEMA in config.py to add label_asym_id columns for structures.csv, ligands.csv, arrestins.csv, and all relevant subunit columns in signaling_partners.csv, ensuring consistent support for asymmetric unit labeling across all data exports. [1] [2]

Defensive Coding and Constants

• Replaced mutable module-level constants (set, list) with immutable types (frozenset, tuple) for BLACKLISTED_KEYS, AUTO_RESOLVE_KEYS, and TOPLEVEL_BLOCK_KEYS in config.py to prevent accidental mutation and cross-test contamination. [1] [2] [3]
• Expanded VALIDATION_FATAL_KEYWORDS to include "ghost ligand" for improved validation alert matching.

User Interface and Validation Improvements

• Replaced legacy heteromer and 7TM completeness panels with a unified display_oligomer_analysis_panel in the main app UI, and introduced inject_oligomer_alerts to centralize validation alert injection for oligomer analysis. This streamlines the user experience and validation logic. [1] [2]
• Fixed a logic bug by changing if final_data: to if final_data is not None: to correctly distinguish between "user quit" and "user accepted with empty data," following defensive coding best practices.

Other Changes

• Bumped the package version from 0.1.0 to 0.1.1 in pyproject.toml to reflect schema and standards changes.

These changes collectively improve code reliability, maintainability, and contributor onboarding, while reducing common sources of bugs in collaborative scientific software development.

[Copilot]

Pull request overview

This PR completes migration work for the Interactive Curation Suite by porting legacy fixes and introducing/standardizing the new oligomer_analysis + label_asym_id architecture across CSV generation, UI display, validation gating, and review safety.

Changes:

• Add a pure-logic transformation layer (logic.py) for label mapping, DB truncation, and note enrichment; wire it into CSV generation.
• Introduce unified oligomer analysis UI + validation warning injection to gate fix-mode/accept-all appropriately.
• Add schema-mismatch detection for CSV appends (new exception + header check) and expand unit tests/fixtures to cover the new paths.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/gpcr_tools/csv_generator/logic.py	New pure transformation helpers (label mapping, truncation, note assembly).
src/gpcr_tools/csv_generator/csv_writer.py	Use new logic layer; emit label_asym_id fields; enforce header/schema validation on append.
src/gpcr_tools/csv_generator/ui.py	New unified oligomer analysis panel and highlight logic.
src/gpcr_tools/csv_generator/validation_display.py	Inject oligomer-derived warnings into validation_data["critical_warnings"].
src/gpcr_tools/csv_generator/review_engine.py	Add coerce_type() and new skip paths; reduce mutation by returning new decision-unit dicts on edit.
src/gpcr_tools/csv_generator/app.py	Replace legacy heteromer/7TM panels with unified oligomer panel; handle schema mismatch in auto-accept; audit “decline write”.
src/gpcr_tools/csv_generator/exceptions.py	New CsvSchemaMismatchError.
src/gpcr_tools/config.py	Add new schema columns + blacklist key update (oligomer_analysis).
tests/*	New fixtures + unit tests for NE1/NE2/NE3 logic and CSV schema behavior.
developing_styles.md	New development standards and architectural guidance.
pyproject.toml	Version bump to 0.1.1.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

src/gpcr_tools/csv_generator/review_engine.py:660

• Top-level block action s currently breaks out of the loop without assigning final_data[key], which effectively removes the block from the returned data. That makes s destructive (and differs from the non-destructive s behavior added at leaf/block review levels). If the intent is “skip reviewing but keep current data”, set final_data[key] = current_block (or the original block) before breaking; if the intent is deletion, consider labeling it explicitly as delete to avoid confusion.

                if action == "q":
                    return None
                if action == "s":
                    core_blocks = {"receptor_info", "ligands", "signaling_partners"}
                    if key in core_blocks and not Confirm.ask(
                        f"[bold red]'{key}' is a core block. "
                        f"Skipping will leave its CSV fields empty. Continue?[/]",
                        default=False,
                    ):
                        continue
                    console.print(f"[yellow]Skipping/Deleting block '{key}'[/yellow]")
                    log_audit_trail(
                        pdb_id,
                        key,
                        "skip_block",
                        create_display_copy(current_block),
                        "SKIPPED",
                    )
                    break

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

extract_validation_entries() can still raise TypeError if validation_data["critical_warnings"] or validation_data["algo_conflicts"] is explicitly None in the loaded JSON, because the function iterates validation_data.get(bucket, []) (default only applies when key is missing). Consider iterating over (validation_data.get(bucket) or []) to be robust to nulls.

[iskoldt-X]

@copilot apply changes based on this feedback