OpenMPRA

OpenMPRA finds candidate papers from the established OpenAlex selector, triages them with the OpenAI API, and packages confirmed MPRA studies with one isolated Codex task per paper.

The repository contains code and small configuration files only. Runtime classification results, evidence caches, Codex transcripts, packaging state, and study packages live under ignored paths and are preserved separately from Git history.

Setup

Requires Python 3.12+ and uv:

uv sync
cp .env.example .env

Add OPENAI_API_KEY to .env. This key is used only by the original OpenAI-backed filtering pass in find_mpra.py; the packaging runner explicitly removes it before launching Codex and relies on the authenticated Codex account. OPENALEX_API_KEY is optional but recommended for the selector's request budget. Never commit .env.

Classification

Run the resumable candidate classifier:

uv run python agentic-indexer/find_mpra.py

It uses one worker by default, saves the abstract for every candidate, and retrieves full text only when the model requests it. The selector output, classification JSONL, evidence cache, and retries are documented in agentic-indexer/README.md.

MPRA packaging

After classification, the packaging runner launches one codex exec task at a time:

uv run python agentic-indexer/run_mpra_packaging.py

Each paper is attempted at most once per runner invocation. A successful Codex process exit is a completed task even when the agent decides that a paper is not MPRA or cannot be packaged. Failed invocations remain resumable for a later --retry-failed run. The runner keeps its state in agentic-workspace/packaging_state.json and saves final Codex messages in agentic-workspace/codex_outputs/.

The agent-owned study packages are under agentic-workspace/db/. At the start of each real runner invocation, direct study directories without a regular finalized marker are removed; the marker is cleanup-only and is not the runner's completion signal.

Running the queue with PM2

ecosystem.config.cjs starts the queue through agentic-indexer/pm2_packaging_guard.py:

pm2 start ecosystem.config.cjs --only openmpra-packaging
pm2 save
pm2 status
pm2 logs openmpra-packaging

The PM2 app has autorestart: false. The guard removes the app from PM2's saved list after the queue exits by itself, whether it exits successfully or with an error, so an ordinary completion/error is not restarted. If the machine crashes or loses power, that cleanup cannot happen; PM2's startup hook then resurrects the saved app after reboot. A planned stop should be followed by pm2 delete openmpra-packaging && pm2 save if it should not resume at the next boot.

The deployed PM2 configuration resumes interrupted work without deleting failed records or old transcripts. Run the queue manually with --retry-failed when those records should be deliberately retried and cleaned.

To enable PM2's boot-time startup on a new host, run pm2 startup, execute the sudo ... command it prints, then run pm2 save. The exact command is host specific.

Runtime files and Git

.gitignore excludes .env, virtual environments, evidence caches, classification outputs, and agentic-workspace/. Do not use git add -f on those paths: they can contain API credentials, large data, or live processing state.