codex-sci-review-agent

KO | EN

gitlite — search

#sql #golang #computer-vision #csharp #macos #redis #automation #python #markdown #typescript

codex-sci-review-agent

(★ 9)

Auditable Codex skills workflow for SCI review manuscript automation

File Explorer

ZIP Download

- - write_sections.py
  - writing_engine.py
- - cardiovascular.yaml
  - general_biology.yaml
  - README.md
- artifact_registry_rules.json
- databases.yaml
- download_policy.yaml
- error_codes.json
- journal_sources.yaml
- qa_policy.json
- retry_policies.json
- skills_manifest.json
- thresholds.yaml
- zotero_credentials.example.yaml
- - .gitkeep
- - .gitkeep
- - .gitkeep
- - .gitkeep
- citation_manager.py
- crossref_client.py
- ezproxy_auth.py
- institution_auth.py
- live_config.py
- pdf_downloader.py
- pdf_text_extractor.py
- pmc_client.py
- pubmed_client.py
- skill_logger.py
- unpaywall_client.py
- zotero_client.py
- architecture.md
- artifact_contracts.md
- chinese_folder_and_usage_guide.md
- codex_execution_master_prompt_zh.md
- codex_sci_review_agent_zh_user_guide.docx
- failure_modes.md
- for_new_users.md
- quickstart_zh.md
- skill_index.md
- version_control_boundary.md
- - README.md
- - __init__.py
  - registry.py
  - registry_v2.py
- - __init__.py
  - checkpoint.py
- - __init__.py
  - execution_planner.py
- - __init__.py
  - retry.yaml
  - retry_engine.py
- - __init__.py
  - skill_router.py
- - __init__.py
  - gates.yaml
  - runner.py
  - states.yaml
  - transitions.yaml
- __init__.py
- orchestrator.py
- runtime_v2.py
- skill_adapters.py
- citation_map.schema.json
- claim_evidence_graph.schema.json
- evidence_matrix.schema.json
- evidence_units.schema.json
- figure_table_plan.schema.json
- fulltext_bundle.schema.json
- journal_fit_report.schema.json
- manuscript_package.schema.json
- manuscript_section.schema.json
- metadata_resolution.schema.json
- outline_graph.schema.json
- pdf_download_manifest.schema.json
- project_brief.schema.json
- qa_report.schema.json
- rebuttal_matrix.schema.json
- resubmission_readiness.schema.json
- retrieval_manifest.schema.json
- screening_decision.schema.json
- search_plan.schema.json
- submission_package.schema.json
- thesis_map.schema.json
- visual_claim_map.schema.json
- zotero_library_sync.schema.json
- zotero_write_plan.schema.json
- bootstrap_repo.py
- export_to_docx.py
- live_production_check.py
- live_source_smoke.py
- manage_outputs.py
- smoke_gate1.py
- upgrade_skills.py
- validate_repo.py
- cover_letter.template.md
- evidence_matrix.template.csv
- rebuttal_response.template.md
- SKILL.md.template
- target_journal_profile.template.yaml
- - test_pdf_acquisition.py
  - test_phase_a_pipeline.py
- - test_e2e_phase_a.py
  - test_live_source_contracts.py
  - test_manage_outputs.py
  - test_runtime_v2_contracts.py
- - test_schema_contracts.py
.env.example
.gitignore
AGENTS.md
build_prerequisites.py
LICENSE
Makefile
OPEN_SOURCE_PACKAGE.md
README.md
requirements.txt
run_full_pipeline.py
run_review.py
stage1_claude_driven.py
stage2_stage3_build.py
stage3_stage4_qa.py

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Submission-grade scientific review manuscript automation through auditable, stage-based, human-gated Codex skills.

## Overview

This repository implements an auditable pipeline for producing SCI review manuscripts using Codex skills and deterministic runtime adapters. The system decomposes the review writing process into **33 narrow skills** (27 business + 6 QA), orchestrated by a state machine with **4 human approval gates**.

## Quick Start

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
make doctor
make check
```

`make doctor` reports local setup status without running a review. `make check` runs the repo validator, compile check, and pytest without refreshing user-facing output links. Use `make regression` when you also want the deterministic happy path and expected-failure demos.

Daily workflow entrypoint:

```bash
.venv/bin/python run_review.py new --topic "ocular surface tight junction barrier integrity"
.venv/bin/python run_review.py outputs
```

For human-gated runs:

```bash
.venv/bin/python run_review.py new --topic "ocular surface tight junction barrier integrity" --human-gates
.venv/bin/python run_review.py approve <run_id> GATE_1
.venv/bin/python run_review.py resume <run_id>
```

Individual commands:

```bash
make verify
make doctor
make production-check
make demo-happy
make demo-fail-q02
make demo-fail-q03
make test
make check
make ready
make live-source-smoke
make live-production-check
make live-smoke
make outputs
make check-outputs
make prune-artifacts
```

## Architecture

```
4 Stages → 27 Business Skills + 6 QA Skills
         ↓
    Orchestrator (State Machine + Checkpoint Manager)
         ↓
    4 Human Gates (选题 → 证据 → 大纲 → 投稿)
         ↓
    Artifact Schemas (Cross-skill data contracts)
```

See [docs/architecture.md](docs/architecture.md) for full details.
See [docs/version_control_boundary.md](docs/version_control_boundary.md) for what belongs in Git versus local generated outputs.

## Stages

| Stage | Phase | Skills | Gate |
|-------|-------|--------|------|
| A | Scoping & Search | S01–S05 | Gate 1 |
| B | Literature & Evidence | S06–S12 | Gate 2 |
| C | Structure & Writing | S13–S20 | Gate 3 |
| D | Submission & Revision | S21–S27 | Gate 4 |
| QA | Quality Assurance | Q01–Q06 | — |

## Directory Structure

```
├── AGENTS.md              # Project constitution (Codex reads this)
├── .agents/skills/        # 33 skill directories
├── orchestrator/          # State machine, routers, checkpoint mgr
├── schemas/               # JSON Schema contracts
├── templates/             # SKILL.md, cover letter, rebuttal templates
├── configs/               # DB configs, journal sources, manifest
├── scripts/               # validator, smoke checks, utility scripts
├── docs/                  # Architecture, skill index, failure modes
└── artifacts/             # Run outputs (versioned by timestamp)
```

`make outputs` refreshes `outputs/latest-*` and `outputs/INDEX.md`. Validation
commands intentionally do not refresh tracked output docs. `make prune-artifacts`
is a dry-run; use `make prune-artifacts-apply` only when you are ready to delete
old run directories.

## Key Design Principles

1. **Narrow skills** — Each skill does one thing; no monolithic agents
2. **Schema-first** — Every artifact has a JSON Schema; skills communicate through validated contracts
3. **Evidence-to-claim traceability** — Q02 enforces that manuscript claims map through `claim_evidence_graph.json` to evidence units
4. **Human gates, not human workflows** — Humans decide at 4 checkpoints; the system does the rest
5. **Zotero as literature hub** — Metadata-first ingestion with PDF fallback
6. **Resumable pipeline** — Checkpoint manager enables restart from any state

## Current Runtime Contract

`run_review.py` is the user-facing CLI. `orchestrator/runtime_v2.py` is the lower-level acceptance runtime. The deterministic path is intentionally offline and fixture-backed, but it must still consume upstream artifacts, register versioned outputs, and let QA failures block the run.

Expected CLI behavior:

| Command | Expected status | Purpose |
|---------|-----------------|---------|
| `.venv/bin/python run_review.py new --topic "..."` | `completed` / `DONE` | Verifies the end-to-end deterministic artifact chain |
| `.venv/bin/python run_review.py new --scenario fail-q02 --topic "..."` | `blocked` | Verifies unsupported evidence-claim failures stop the run |
| `.venv/bin/python run_review.py new --scenario fail-q03 --topic "..."` | `blocked` | Verifies screening/PRISMA failures stop the run |
| `.venv/bin/python run_review.py new --topic "..." --human-gates` | `blocked` at `GATE_1` | Writes a gate review file and waits for approval |

Unknown business or QA adapters fail closed. Do not reintroduce stub-success fallbacks; future live PubMed/Zotero/PDF implementations should replace the deterministic adapter for the same skill ID while preserving the artifact names, schemas, checksums, and QA blocking semantics.

## Live PubMed / Zotero / Full Text Mode

The v2 runtime now supports a networked path:

```bash
.venv/bin/python run_review.py new \
  --mode live \
  --topic "ocular surface tight junction barrier integrity" \
  --pubmed-retmax 25 \
  --max-fulltext 5
```

Modes:

| Mode | Behavior |
|------|----------|
| `deterministic` | Offline fixture-backed acceptance path; default for regression commands |
| `hybrid` | Default for `run_review.py new`; uses live PubMed/Zotero/PDF/PMC when available, falls back when a source is unavailable |
| `live` | Fails closed when required live network/credential steps fail |

Live source behavior:

- `S04` uses NCBI E-utilities to run PubMed search, ESummary, and PubMed XML abstract retrieval, then writes `raw_exports_pubmed_records.json`, RIS, and `retrieval_manifest.json`.
- `S05` consumes live PubMed records to build `master_records.csv`, `screening_pack.csv`, and `prisma_seed.json`.
- `S07` connects to Zotero Web API in read-only mode by default. It checks whether DOI records already exist and writes `zotero_sync_report.json`, `zotero_write_plan.json`, and `zotero_import.ris`. To create missing Zotero records, pass `--zotero-write` or set `CODEX_REVIEW_ZOTERO_WRITE=1`; writes are batched at Zotero's 50-item request boundary and remain fully reported.
- `S09` normalizes PMC OA TGZ/JATS, PMC/HTML text, PDF-derived text, and abstract fallback into one `fulltext_bundles/*.json` contract. Bundles carry parse status, parser metadata, acquisition provenance, section/figure/table indices, normalization warnings, and explicit fallback reasons when full text is unavailable.
- `S10` extracts section-aware evidence units from fulltext bundles before aggregating study-level `evidence_matrix.json`. Evidence units include section type, span offsets, provenance confidence, extraction method, subject model, intervention, outcome, evidence strength, and quantitative payload when numeric findings are actually present in the source text.
- `S20` writes `claim_evidence_graph.json`; `Q02` checks that each cited claim links to an evidence matrix row and existing evidence units, respects required evidence profiles, and validates quantitative claims against evidence-unit measurements instead of accepting free-text numeric claims.

Credentials:

- PubMed: optional `NCBI_API_KEY` and `NCBI_EMAIL`.
- Zotero: use environment variables (`ZOTERO_API_KEY`, `ZOTERO_LIBRARY_ID`, `ZOTERO_LIBRARY_TYPE`) or ignored local file `configs/zotero_credentials.local.yaml`.
- Local credentials are redacted in artifacts; reports only show whether credentials are present.

Authorized full text:

- Put PDFs you already obtained through legal institutional or publisher access in `data/authorized_fulltext/`, or pass `--authorized-pdf-dir /path/to/pdfs`, or set `CODEX_REVIEW_AUTHORIZED_PDF_DIR`.
- File names should contain a normalized DOI, PMID, source_id, or recognizable title words, for example `10_1000_demo.pdf` or `pmid_12345678.pdf`.
- `authorized_fulltext` is the first S09 PDF channel. It does not bypass paywalls; it only reuses locally available authorized PDFs.
- For authorized publisher sessions, export cookies yourself to an ignored local file such as `data/cache/authorized_session.cookies.json`, then pass `--authorized-cookie-file data/cache/authorized_session.cookies.json` or set `CODEX_REVIEW_AUTHORIZED_COOKIE_FILE`.
- Cookie files may be JSON (`{"cookies":{"sid":"..."}}`), browser-exported cookie lists (`[{"name":"sid","value":"..."}]`), Netscape `cookies.txt`, or `name=value` lines. Do not commit cookie files.
- Add `--interactive-fulltext` when you want S09 to stop instead of falling back to abstract-only records. On missing full text, it writes `stage-2/manual_fulltext_queue.csv` and `stage-2/manual_fulltext_instructions.md`, then blocks the run so you can log in, add PDFs, or provide an authorized cookie file before rerunning.
- To resume after a blocked full-text gate, rerun `run_review.py resume <run_id>` with any new authorized PDF/cookie options:

```bash
.venv/bin/python run_review.py resume <run_id> \
  --authorized-pdf-dir data/authorized_fulltext
```

- To attach verified local PDFs to Zotero records after S09, pass `--zotero-attach-pdfs` or set `CODEX_REVIEW_ZOTERO_ATTACH_PDFS=1`. This creates linked-file attachment metadata for PDFs already present on your machine; it does not upload paywalled PDFs or bypass publisher access.

The implementation follows NCBI E-utilities usage patterns, PMC ID Converter, PMC Open Access retrieval constraints, and Zotero Web API v3 write boundaries. For large-scale PMC PDF/text mining, use PMC OA file lists, OA Web Service, FTP, or Cloud datasets rather than scraping per-article PDF pages.

## Non-Negotiables

See [AGENTS.md](AGENTS.md) for the full project constitution. Key rules:
- Never fabricate DOI, PMID, statistics, or study conclusions
- Every claim must map to evidence
- Production review runs should use `--human-gates` so human approval is required at all 4 gates
- Never overwrite prior artifacts

## MVP Path

The present acceptance path is `S01` through `S27` in `runtime_v2`, with deterministic adapters for all 27 business skills and 6 QA skills. The older `run_full_pipeline.py` remains a legacy exploration script and is not the acceptance gate for this repository.

Near-term implementation work should replace deterministic fixtures with live adapters in this order: search/retrieval (`S03`/`S04`), PDF and metadata acquisition (`S07`-`S09`), evidence extraction (`S10`-`S12`), then journal/submission packaging (`S21`-`S24`). Each replacement must keep `make regression` green.

codex-sci-review-agent

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README