Add aggregation & validation pipeline with oligomer analysis

[iskoldt-X]

Summary

• New aggregator/ package — loads AI annotation runs per PDB, selects the best by score, applies majority-vote consensus with per-field controversy detection, and injects ground truth from enriched PDB metadata
• New validator/ package — chimera detection, receptor identity validation (UniProt API cross-check), ligand PDB-CCD validation, oligomer analysis (classification, 7TM completeness, chain-ID override, primary protomer suggestion), structural integrity checker, API clients, and persistent JSON cache
• CLI aggregate subcommand with --force and --skip-api-checks flags
• Hardened csv_generator/ — replaced all .get(key, {}) anti-patterns with None-safe idioms, centralized 20+ magic strings into config.py constants
• Updated README — full pipeline documentation with architecture diagram, workspace layout, and design principles

Architecture highlights

Principle	Implementation
Atomic writes	tempfile + os.replace + try/finally cleanup
Mutation isolation	deepcopy() boundary in runner before passing data to validators
None-safety	(data.get(key) or {}).get(child) — no .get(key, {}) anywhere
No magic strings	All cross-module strings as constants in config.py
Immutability	frozenset, tuple, MappingProxyType for module-level constants
Error isolation	Each PDB wrapped in try/except; failures logged, never crash the batch

Stats

• ~2,650 lines of new production code across 13 new modules
• ~3,400 lines of new tests across 11 new test files
• 685 tests passing (unit + integration + 9 canonical real-PDB fixtures)
• 0 ruff, mypy, or format issues

Test plan

• ruff check src/ tests/ — all checks passed
• ruff format --check src/ tests/ — all files formatted
• mypy src/ — no issues (with ignore_missing_imports = false)
• pytest tests/ -v — 685 passed
• Smoke-test gpcr-tools aggregate <workspace> on a real workspace with 10 AI runs per PDB

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Introduces an aggregation + validation pipeline backed by enriched PDB metadata, adds supporting CLI/workflow wiring, and expands real-PDB AI-run fixtures to exercise the end-to-end path.

Changes:

• Added offline validators (receptor identity, ligand validation) plus API client + persistent caching utilities.
• Added aggregation helpers (enriched loader, ground-truth injector, AI-run loader) and exposed an aggregate CLI subcommand.
• Updated CI/Docker workflows and substantially expanded real-PDB fixture coverage (multi-run AI outputs).

Reviewed changes

Copilot reviewed 117 out of 141 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/fixtures/real_pdbs/ai_results/9O38/run_1.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_2.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_3.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_4.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_5.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_6.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_7.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_8.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9O38/run_10.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_1.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_2.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_3.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_4.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_5.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_6.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_7.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_8.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_9.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9NOR/run_10.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_1.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_2.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_3.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_4.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_5.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_6.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_7.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_8.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_9.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9IQS/run_10.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_1.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_2.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_3.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_4.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_5.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_6.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_7.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_8.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_9.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9BLW/run_10.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_2.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_3.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_4.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_5.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_8.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_9.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/9AS1/run_10.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_1.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_2.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_3.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_4.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_5.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_6.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_7.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_8.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_9.json	Add real-PDB AI run fixture for aggregation/validation tests
tests/fixtures/real_pdbs/ai_results/8TII/run_10.json	Add real-PDB AI run fixture for aggregation/validation tests
src/gpcr_tools/validator/receptor_validator.py	Add offline receptor identity validation against enriched polymer entities
src/gpcr_tools/validator/ligand_validator.py	Add offline ligand validation + chemical identifier enrichment
src/gpcr_tools/validator/cache.py	Add persistent JSON caches with atomic writes
src/gpcr_tools/validator/api_clients.py	Add UniProt/PubChem/RCSB GraphQL client wrappers
src/gpcr_tools/validator/init.py	Declare validator subpackage
src/gpcr_tools/csv_generator/validation_display.py	Update validation display/oligomer alert injection + None-safety improvements
src/gpcr_tools/csv_generator/review_engine.py	Replace .get(..., {}) patterns with None-safe idioms
src/gpcr_tools/csv_generator/logic.py	Add constants usage + None-safe access in CSV note/oligomer handling
src/gpcr_tools/csv_generator/csv_writer.py	Harden CSV transformation against None/missing dicts
src/gpcr_tools/csv_generator/app.py	Wire oligomer alerts into the interactive curation path
src/gpcr_tools/aggregator/ground_truth.py	Inject authoritative method/resolution/release_date from enriched metadata
src/gpcr_tools/aggregator/enriched_loader.py	Load and validate enriched entry JSON structure
src/gpcr_tools/aggregator/ai_results_loader.py	Load multi-run AI results and compute pending PDB IDs
src/gpcr_tools/aggregator/init.py	Declare aggregator subpackage
src/gpcr_tools/main.py	Add aggregate CLI subcommand + flags
pyproject.toml	Bump version and add runtime/dev deps + stricter mypy setting
future_plan.md	Document follow-up work items and migration ordering caveats
developing_styles.md	Update testing layout/docs incl. real-data strategy
.github/workflows/docker-publish.yml	Update Docker publish workflow triggers/action versions
.github/workflows/ci.yml	Update CI action versions and artifact upload step

---

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

[Copilot]

setdefault('structure_info', {}) does not guarantee structure_info is a dict (it returns the existing value unchanged). If upstream data contains a non-dict structure_info (e.g., a string/list), the subsequent item assignments will raise at runtime. Recommendation (mandatory): after retrieving structure_info, validate it is a dict and replace it with {} (and/or log) when it is not.

Suggested change

	structure_info: dict[str, Any] = best_run_data.setdefault("structure_info", {})
	structure_info_raw = best_run_data.get("structure_info")
	if not isinstance(structure_info_raw, dict):
	if structure_info_raw is not None:
	logger.warning(
	"[%s] structure_info is %s, replacing with empty dict before ground truth injection",
	pdb_id,
	type(structure_info_raw).__name__,
	)
	structure_info_raw = {}
	best_run_data["structure_info"] = structure_info_raw
	structure_info: dict[str, Any] = structure_info_raw

[Copilot]

setdefault('structure_info', {}) does not guarantee structure_info is a dict (it returns the existing value unchanged). If upstream data contains a non-dict structure_info (e.g., a string/list), the subsequent item assignments will raise at runtime. Recommendation (mandatory): after retrieving structure_info, validate it is a dict and replace it with {} (and/or log) when it is not.

[Copilot]

This module imports _first_list_entry, a private helper (leading underscore) from another module. That creates a fragile coupling: refactors in voting.py can break ground_truth.py without a public API contract. Recommendation: either make the helper public (rename to first_list_entry and export it) or move it into a shared utils module used by both.

Suggested change

	from gpcr_tools.aggregator.voting import _first_list_entry
	logger = logging.getLogger(__name__)
	logger = logging.getLogger(__name__)
	def _first_list_entry(entry: dict[str, Any], key: str) -> Any:
	"""Return the first element from a list-valued field, else ``None``."""
	value = entry.get(key)
	if isinstance(value, list) and value:
	return value[0]
	return None

[Copilot]

pdb_id is currently unused in this function. Recommendation (optional): either remove it from the signature (if not part of a common validator interface), or use it in log messages / warning strings to improve diagnosability.

[Copilot]

Atomic os.replace prevents partial-file reads, but without an explicit flush() + os.fsync() on the temp file, a sudden power loss can still leave a zero-length/truncated file that gets renamed into place (depending on OS/filesystem buffering). Recommendation: explicitly flush and fsync the temp file before os.replace to harden cache durability.

Suggested change

	json.dump(data, fd, indent=2)
	json.dump(data, fd, indent=2)
	fd.flush()
	os.fsync(fd.fileno())

[Copilot]

Pull request overview

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

---

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

[Copilot]

setdefault('structure_info', {}) does not guarantee a dict: if best_run_data['structure_info'] exists but is not a dict (e.g., None or a string), setdefault returns the existing non-dict value and later assignments will fail. Prefer normalizing with a type check (replace non-dicts with {}) before writing method/resolution/release_date.

Suggested change

	structure_info: dict[str, Any] = best_run_data.setdefault("structure_info", {})
	structure_info_value = best_run_data.get("structure_info")
	if not isinstance(structure_info_value, dict):
	structure_info_value = {}
	best_run_data["structure_info"] = structure_info_value
	structure_info: dict[str, Any] = structure_info_value

[Copilot]

The UniProt existence check builds /uniprotkb/{clean_name}.txt from a uniprot_entry_name slug (e.g., GPCRdb-style ts1r2_human). UniProt REST commonly expects an accession or a UniProtKB identifier (e.g., P63092 or P53_HUMAN), so this is likely to return 404 for valid proteins and poison the cache with false negatives. Consider switching to a UniProt search query endpoint (querying by UniProtKB ID vs accession explicitly) and only caching False when the API definitively indicates 'not found' for the intended identifier type.

Suggested change

	clean_name = entry_name.split(".")[0].lower()
	key = f"uniprot:{clean_name}"
	cached = cache.get(key)
	if cached is not None:
	return cached
	url = f"https://rest.uniprot.org/uniprotkb/{clean_name}.txt"
	for attempt in range(API_MAX_RETRIES):
	try:
	resp = requests.head(url, timeout=5, allow_redirects=True)
	is_valid = resp.status_code == 200
	cache.set(key, is_valid)
	return is_valid
	except (requests.RequestException, OSError) as exc:
	if attempt == API_MAX_RETRIES - 1:
	clean_name = entry_name.split(".")[0].upper()
	key = f"uniprot:{clean_name}"
	cached = cache.get(key)
	if cached is not None:
	return cached
	url = "https://rest.uniprot.org/uniprotkb/search"
	params = {
	"query": f"id:{clean_name}",
	"format": "json",
	"size": 1,
	}
	for attempt in range(API_MAX_RETRIES):
	try:
	resp = requests.get(url, params=params, timeout=5)
	if resp.status_code == 200:
	payload: dict[str, Any] = resp.json()
	is_valid = bool(payload.get("results"))
	cache.set(key, is_valid)
	return is_valid
	if attempt == API_MAX_RETRIES - 1:
	logger.warning(
	"UniProt API returned status %s for '%s'",
	resp.status_code,
	entry_name,
	)
	return None
	time.sleep(1)
	except (requests.RequestException, OSError, ValueError) as exc:
	if attempt == API_MAX_RETRIES - 1:

[Copilot]

Pull request overview

Copilot reviewed 117 out of 141 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

The receptor chain_id is treated as a single chain when locating the polymer entity (if ai_chain in auth_asym_ids:). Several real fixtures use comma-separated chain IDs (e.g., \"B, F\"), which will never match auth_asym_ids and causes receptor validation to silently skip (returns no warnings). Parse ai_chain as a list (split on commas, strip whitespace) and treat the receptor as matched if any chain is found; optionally include which chain matched in api_reality/warning text.

[Copilot]

Pull request overview

Copilot reviewed 117 out of 141 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

The pdb_id parameter is unused here as well. Consider either removing it or incorporating it into the GHOST_LIGAND warnings (and any logger output) so that batch validation logs remain self-identifying when multiple PDBs are processed together.