PR 5: GEO extraction agent (vertical slice)

[mengerj]

Scope (roadmap PR 5)

GEO is the project's first unstructured source, so this is the first path with an LLM in it. One focused vertical slice: GEO adapter → agent-backed extraction normalizer → existing ontology grounding → canonical KG.

Branched off the latest origin/main (4dcd5b7, post PR 4 + PR 4b). The routine worktree's local main was 2 merges stale and its roadmap wrongly showed PR 4 as "Next up"; caught via git fetch + compare, so PR 4 was not rebuilt.

What's here

• sources/geo.py — GeoAdapter (deterministic). Fetches GEO Series+Sample SOFT text from the GEO accession endpoint and parses it with a small focused parser (no GEOparse dependency). Carries characteristics_ch1 verbatim in the RawRecord — no interpretation. discover() is the identity on a GSEnnnnn (mirrors CELLxGENE's DOI identity; Entrez keyword search → backlog).
• normalize/geo.py — GeoNormalizer (agent-backed) + GeoExtraction/SampleExtraction schemas. The LLM fills the schema via response_format — design covariates only; the schema has no field for any data-inferred annotation, so leakage is structurally impossible. SampleNodes are now populated (one per real GSM): organism + data_uri are read deterministically from structured SOFT fields, condition/perturbation/timepoint/subject come from the LLM. Facets grounded through the existing OntologyResolver.
• agent/base.py — StructuredExtractor: a narrow synchronous Protocol the normalizers depend on (inject a fake → offline tests).
• agent/extraction.py — AzureExtractionAgent (the only Azure-touching module): bridges the async agent-framework API to the sync seam. make_ontology_fallback wires the agent in as the resolver's opt-in LLM fallback (accepts a result only if the CURIE prefix matches the facet's ontology).
• Removed the parce.agent.* mypy exemption — all of src/parce is now type-checked (28 files).
• main.py: parce geo GSEnnnnn path (Azure import deferred so the default CELLxGENE path needs no creds). Settings: optional ncbi_email/ncbi_api_key (+ .env.example).

Key design decisions (full rationale in ROADMAP/ARCHITECTURE)

• Deterministic where GEO is structured, LLM only for the free text. Organism + suppl URI are read straight from SOFT; the LLM only parses characteristics_ch1 and the series prose.
• No DatasetNode for GEO — a series is the study, so design-context + HAS_SAMPLE edges originate at the StudyNode. Cross-source merge keys on entity ontology_id targets, so the differing origin vs CELLxGENE doesn't matter (ARCHITECTURE §4).
• Sample set is the record's, not the LLM's — extraction matched in by sample_id; a dropped/hallucinated sample can't change graph shape. Extraction failure degrades to samples-without-covariates (logged), never a crash.

Verification (all four CI gates, hermetic — no .env in the worktree)

• ruff check . ✅ · ruff format --check . ✅ (47 files)
• mypy src/parce ✅ (28 files)
• pytest -m "not integration" ✅ 168 passed, 13 deselected
• Live TestLiveGeoFetch run against the real GEO endpoint — passes (SOFT parser validated on GSE10072).

⚠️ Blocker (integration boundary, per session protocol)

The live Azure extraction round-trip is unverified: this headless env has az login but no AZURE_AI_PROJECT_ENDPOINT configured (no worktree .env), so TestLiveGeoExtraction skips. The Azure call shape mirrors the previously-working agent/curator.py (agent.run(prompt, response_format=Model) → result.value). Before relying on the GEO path: with Azure creds, run uv run pytest -m integration tests/test_geo_integration.py.

🤖 Generated with Claude Code

[mengerj]

✅ Integration boundary verified — blocker cleared

Follow-up scheduled session (2026-06-29). The one documented blocker on this PR — the live Azure extraction round-trip was unverified — is now resolved.

What was run (creds: active az login + AZURE_AI_* sourced from the repo-root .env; Settings reads the worktree root, which has no .env, which is why the prior session saw it as unconfigured):

uv run pytest -m integration tests/test_geo_integration.py
# 2 passed in 48.34s
#   TestLiveGeoFetch::test_fetch_real_series          PASSED
#   TestLiveGeoExtraction::test_fetch_extract_normalize PASSED  ← live gpt-4o extraction

All four CI gates re-confirmed green on the branch tip, hermetically (no .env):

gate	result
ruff check .	✅
ruff format --check .	✅ 47 files
mypy src/parce	✅ 28 files
pytest -m "not integration"	✅ 168 passed, 13 deselected

Non-blocking follow-up: agent_framework emits a DeprecationWarning — agent/extraction.py passes temperature via run(options=...) runtime kwargs; the new API wants client_kwargs / function_invocation_kwargs. Works today; worth tidying when PR 7 (PRIDE) next touches that module.

The GEO vertical slice is verified end-to-end and ready for review/merge. Left as draft, not merged, per the session protocol — a human should merge. Roadmap session log updated in ea72f76.

🤖 Generated with Claude Code