P. putida KT2440 Genome-wide Module Curation Plan

SCOPING BIOLOGY_DOMAINPIPELINE

Species: PSEPK

P. putida KT2440 Genome-wide Module Curation Plan

Goal

Curate the Pseudomonas putida KT2440 proteome pathway by pathway, using module
logic as the organizing structure. The project should simultaneously improve
gene reviews under genes/PSEPK/ and reusable module documents under
modules/.

The first pass is intentionally light: build a whole-proteome metadata table from
UniProt REST, group genes into pathway/module buckets, and identify holes or
over-annotations before running full fetch-gene, GOA review, or deep research.

First-pass data

Use the project-local downloader:

uv run python projects/P_PUTIDA/fetch_uniprot_metadata.py

Default output:

This is a lightweight UniProt REST TSV download for proteome UP000000556. It
does not create genes/PSEPK/<gene>/ folders, fetch GOA, fetch full UniProt text
records, seed YAML, or fetch publications.

Fields used for triage: accession, entry name, gene names, protein name, taxon,
length, reviewed status, annotation score, function comment, EC number, GO IDs,
InterPro, Pfam, PANTHER, KEGG, BioCyc, UniPathway, RefSeq, and UniProt keywords.

Build the curator-facing gene list from the metadata snapshot:

python3 projects/P_PUTIDA/build_gene_list.py

Default output:

Partition genes into first-pass pathway/module buckets:

python3 projects/P_PUTIDA/partition_pathways.py

Default output:

The partitioner treats organism-specific KEGG ppu pathways as the primary
pathway source. Broad KEGG overview maps are retained in the membership table
but excluded from primary assignment. When a gene is in multiple specific KEGG
pathways, the primary bucket is the pathway with the smallest PSEPK gene count,
which favors narrower curation units. UniPathway is used as a fallback pathway
source, followed by metadata heuristics for non-pathway systems such as
transport, regulation, motility, DNA repair, translation, cell envelope, stress
response, and mobile elements.

Build the PR-oriented pathway worklist:

python3 projects/P_PUTIDA/build_pathway_worklist.py

Default output:

Extract a per-pathway checklist for a PR batch:

uv run python projects/P_PUTIDA/extract_pathway_batch.py ppu00400 \
  --module tryptophan_biosynthesis \
  --research-provider openscientist

Default output for the first pilot:

After hand-curating the Markdown page, refresh provider and review statuses
without replacing it by adding --tsv-only.

Research provider policy

Current provider override (2026-07-18): while Edison is unavailable, use
OpenScientist for both gene-level and module-level deep research:

just deep-research-openscientist PSEPK <gene> --timeout 7200
just module-deep-research-openscientist <module> --timeout 7200
just module-pathway-deep-research openscientist "<module>" <pathway> PSEPK --timeout 7200

OpenScientist jobs commonly take 20 minutes or longer. A short polling window is
not a failure condition: keep a live client running to completion and allow the
two-hour timeout. Treat the generated report as retrieval support and verify
curation-changing claims against UniProt, GOA, PAINT, ontology definitions, and
primary literature.

The provider ladder below is the baseline policy. While this override is
active, replace its Asta/Falcon gene, module, and species-aware research steps
with the OpenScientist commands above.

Use the cheapest useful source first:

  1. UniProt metadata, local existing reviews, and module context.
  2. Full fetch-gene only after a module pass selects the gene for curation:
just fetch-gene PSEPK <gene>
  1. Current gene-level research uses OpenScientist while the Edison-backed
    Falcon route is unavailable. Use three iterations for batch throughput but
    retain a two-hour provider allowance:
just deep-research-openscientist PSEPK <gene> --timeout 8100 \
  --extra-args --param timeout=7200 --param max_iterations=3
  1. Use OpenScientist for the generic reusable-module synthesis as well:
just module-deep-research-openscientist <module> --timeout 8100 \
  --extra-args --param timeout=7200 --param max_iterations=3
  1. For species-aware module/pathway research, use the module + pathway + taxon
    wrapper. This keeps generic module research separate from PSEPK-specific
    satisfiability work and injects local candidate genes from the pathway
    partition table when available:
just module-pathway-deep-research openscientist "central carbon metabolism" \
  ppu00020 PSEPK --project P_PUTIDA --timeout 8100 \
  --extra-args --param timeout=7200 --param max_iterations=3

The report is written under the project support folder by default, e.g.
projects/P_PUTIDA/deep-research/PSEPK__central-carbon-metabolism__ppu00020-deep-research-openscientist.md.

  1. Asta remains a lightweight gene-level fallback, and Falcon remains the
    preferred module-level provider when its Edison route is available again.
  2. PaperBLAST remains an optional protein-specific lookup:
uv run python scripts/fetch_paperblast.py <uniprot_accession>
  1. Use perplexity-lite only as a secondary fallback when Asta is unavailable
    or comparison across providers is useful.
  2. Escalate to OpenAI/perplexity/full manual literature only when the first-pass
    provider output leaves a curation-changing question unresolved.

OpenScientist is a long-running research provider, not a short smoke test.
Successful jobs commonly take more than 20 minutes and difficult jobs can use
most or all of the two-hour provider allowance. Do not apply a 180-second
timeout or treat a quiet wrapper as failure. If a five-iteration run exhausts
the allowance, rerun with max_iterations=3 and the same full timeout.

Operational caveat: the repository has a PaperBLAST wrapper, but it depends on
Playwright and the PaperBLAST website can present a Cloudflare challenge. If the
script returns a timeout or challenge page, record that in the module checklist
and use an available provider rather than pretending PaperBLAST was queried.

Never create a fake -deep-research-{provider}.md by hand. If manual notes are
needed, write them as notes or a clearly named manual research file.

Module-hole-filling workflow

For each module:

  1. Define the expected pathway shape in modules/*.yaml or identify that a new
    module document is needed. A standalone module must have more than one
    substantive part. If a UniPathway/KEGG bucket is a single gene, single enzyme,
    or single reaction, record the curation in the batch page and fold it into a
    broader multi-step module later rather than creating or retaining a one-part
    ModuleReview.
  2. Pull candidate PSEPK genes from the metadata table using EC, KEGG ppu:*,
    BioCyc monomers, UniPathway, InterPro/Pfam/PANTHER families, GO IDs, keywords,
    protein names, and locus tags.
  3. Classify each pathway step as covered, candidate_uncertain, gap,
    not_expected_in_KT2440, or module_needs_revision.
  4. For covered steps, record representative UniProt groundings in the module
    where useful.
  5. For gaps and uncertain candidates, run targeted gene review and decide
    whether the gap is a real biological absence, a naming/paralog issue, a
    missing annotation, a bad propagated annotation, or a module-model error.
  6. Validate changed modules with:
uv run linkml-validate -s src/ai_gene_review/schema/gene_review.yaml -C ModuleReview modules/<module>.yaml

Initial module order

Phase Module area Existing module seed First-pass question Expected outputs
0 Whole-proteome inventory none What genes, accessions, ECs, pathways, families, and keywords are present in PSEPK? Metadata TSV; module-bucket table; selected first batch
1 Entner-Doudoroff, pentose phosphate, TCA, glyoxylate, anaplerosis modules/gluconeogenesis.yaml, modules/fatty_acid_beta_oxidation.yaml as style references Does the module set capture P. putida central-carbon logic, including no canonical EMP glycolysis? New or revised central-carbon modules; review selected ED/TCA gaps
2 Aromatic compound catabolism likely new beta-ketoadipate / aromatic-catabolism modules Are benzoate, catechol, protocatechuate, quinate/shikimate, phenylacetate, tyrosine, and ferulate routes satisfiable? Beta-ketoadipate and related modules; review missing or over-specific ring-cleavage annotations
3 Amino-acid biosynthesis and nitrogen assimilation modules/tryptophan_biosynthesis.yaml, modules/methionine_biosynthesis.yaml, modules/nitrogen_cycle.yaml Which biosynthetic pathways are complete and where do Pseudomonas-specific variants replace textbook enzymes? Update modules with PSEPK exemplars; review variant enzymes and broad nitrogen terms
4 Cofactors, vitamins, redox cofactors, metal handling possible new modules Are pyrroloquinoline quinone, heme, Fe-S, molybdenum cofactor, siderophore, and lanthanide-related systems represented? New cofactor/siderophore/REE modules; targeted ped/pvd/lut reviews
5 Energy metabolism and respiratory chains modules/oxphos.yaml Which terminal oxidases, dehydrogenases, and anaerobic respiration modules are encoded? PSEPK respiratory-chain module coverage; EC7/translocase convention checks
6 Cell envelope, secretion, transport, and efflux possible new modules Which outer-membrane porins, TonB receptors, RND pumps, secretion systems, and envelope biogenesis pathways need module treatment? Transport/envelope worklists; scrutiny of generic transporter annotations
7 Motility, chemotaxis, pili, biofilm, alginate possible new modules Are flagellar assembly, chemotaxis receptors, type IV pilus, alginate, and biofilm regulation wired consistently? Motility/biofilm modules; gene reviews for receptors/regulators selected by module gaps
8 Stress response, DNA repair, and regulatory networks modules/two_component_relay.yaml, modules/gtpase_switch.yaml as style references Which global regulators and repair/stress systems are already reviewed, and which are module-critical gaps? Regulator module updates; targeted sigma/two-component/DNA-repair reviews
9 Specialized metabolism and biotechnology traits possible new PHA, solvent tolerance, olefin, plant-interaction modules Which KT2440 signature traits are absent from reusable modules? New modules for PHA, solvent tolerance, olefin biosynthesis, and plant-associated traits
10 Dark proteome and orphan enzymes none Which high-confidence proteins remain unassigned to any module and which DUFs look curation-relevant? Prioritized orphan list; optional bioinformatics analyses

Module curation deliverables

Each module batch should leave behind:

Active batch: ppu00220 / arginine_biosynthesis

Batch files:

Status as of 2026-07-17:

Pilot status: ppu00400 / tryptophan_biosynthesis

Pilot batch files:

Status as of 2026-07-06:

uv run linkml-validate -s src/ai_gene_review/schema/gene_review.yaml -C ModuleReview modules/tryptophan_biosynthesis.yaml

Main curation conclusions from the pilot:

Previous batch: ppu00010 / entner_doudoroff_and_gluconeogenesis

Batch files:

Status as of 2026-07-06:

Main curation conclusions from the current batch:

Current batch: ppu00770 / coenzyme_a_biosynthesis

Batch files:

Status as of 2026-07-18:

Main curation conclusions from this batch:

Previous batch: ppu00622 / benzoate_upper_pathway

Batch files:

Status as of 2026-07-13:

Main curation conclusions from this batch:

Previous batch: ppu00740 / riboflavin_biosynthesis

Batch files:

Status as of 2026-07-15:

Main first-pass boundary decisions:

Previous batch: ppu00361 / catechol_ortho_cleavage

Batch files:

Status as of 2026-07-15:

Main curation conclusions from this batch:

First batch proposal

Start with central carbon plus aromatic catabolism, because these are core
KT2440 biology and the existing project already has reviewed genes in the
neighborhood (aceA, acnB, BenR, benA/B/C/D, catA/B/C, pcaG, fcs,
hpd, AAA biosynthesis genes). This gives an immediate test of the metadata
clustering, module satisfiability, and review-escalation workflow before scaling
to the rest of the genome.