ReproLearn — Research Studio

Built with Codex + GPT-5.6

This project was developed in 7 days with Codex as the primary engineering partner. It was built through iterative investigate → implement → test → re-check loops, while product decisions about evidence, authority, and release stayed explicit and human-reviewed.

• 94 of 96 commits at the public-release snapshot 1b2dbda, were authored by the Codex agent zerabyte-x. Those changes span the local API contract, Docker sandbox, capsule and receiver workflow, browser and accessibility tests, release hardening, and judge documentation.
• GPT-5.6 Integration: GPT-5.6-powered Codex agents were used to reason through, implement, test, harden, and document the product. The application also includes a configurable OpenAI Responses API adapter: with explicit consent, GPT-5.6 can be selected to propose structured claim mappings or diagnose reproducibility gaps. Responses are schema-validated and provenance-recorded.
• Human-in-the-Loop Design: GPT-5.6 remains proposal-only by design. It cannot approve a claim, select the final command, execute code, validate evidence, or declare scientific truth. This keeps the core workflow deterministic and local-first while still making AI useful for structured metadata and diagnosis.
• Agent Configuration: see AGENTS.md for the exact Codex working rules and .codex/config.toml for this repository's trusted CodeGraph configuration. They make the operating workflow inspectable instead of leaving it implicit in chat history.
• Codex Session ID: 019f5d79-623c-7253-92cd-a6db7cc52c4f is the primary /feedback session in which core functionality, verification, and release evidence were built and checked.
• Where Codex accelerated the build: it decomposed the reproducibility PRD into claim, contract, evidence, receiver, learning, privacy, and release gates; connected the React journeys to the loopback API and deterministic validator; traced real UI and state-transition failures; and generated and exercised targeted API, browser, and accessibility checks.

For the concise, reproducible evidence trail behind these statements, read Codex Build & Verification Trace.

Judge start here

For the shortest working path, copy and run:

npm ci
npm run demo:prepare
npm start

Then open http://127.0.0.1:5173. The deterministic fixture creates separate author and receiver checkouts; it demonstrates the full Developer Tools workflow without an API key or a large training run. For the exact recording path, use Video Demo Flow. For the specific Codex build evidence judges are asked to inspect, start with Codex Build & Verification Trace.

A research capsule for the result that matters. Research Studio turns a paper claim, its reviewed source, governed data, environment, validator, and independent receiver rerun into evidence another person can inspect.

Most computational papers still arrive as a PDF, a repository link, scattered data instructions, and a promise that somebody else can make it work. That handoff asks the reviewer to reconstruct hidden context before they can evaluate the result. Research Studio makes the context explicit, preserves it locally, and refuses to turn a successful command into a broader scientific claim.

Local by default. Evidence before execution. Human approval before a canonical contract. Independent receiver evidence before release.

The problem is not just "can it run?"

The National Academies defines computational reproducibility as obtaining consistent results from the same input data, computational steps, methods, code, and conditions of analysis. It also notes that there is no universal system for structuring how computational research is reported and shared. National Academies, 2019

The practical cost appears during review, onboarding, and reuse: a reviewer must find the right commit, infer the command, locate governed inputs, repair an environment, decide what output matters, and then distinguish a green process from an actually checked result. In Nature's 2016 survey of 1,576 researchers, more than 70% reported having tried and failed to reproduce another scientist's experiments. Nature

Research Studio addresses that handoff gap with a claim-level evidence chain, rather than a generic "reproduce this paper" button.

flowchart LR
    P["Paper claim"] --> S["Reviewed source revision"]
    S --> D["Governed data boundary"]
    D --> E["Pinned environment"]
    E --> C["Approved command"]
    C --> O["Declared observable"]
    O --> V["Validator + tolerance"]
    V --> R["Receiver-owned rerun"]
    R --> K["Inspectable Research Capsule"]

Loading

Three entry points, three clear outcomes

Start here	Bring	Leave with	It never does silently
Prepare research	Paper, code, declared inputs	A reviewable, portable path for one or more results	Execute code, call a model, or publish private bytes
Verify a package	Capsule, manifest, or receiver link	A compatibility decision and independent evidence	Trust the author's screenshot or run before inspection
Learn a paper	A paper and curiosity	A guided path from plain language to a scoped result	Pretend reading completed a reproduction

The complete feature and workflow reference lives in the Workflow Atlas. The implementation-to-evidence map is in the Feature Evidence Matrix.

The competition story in one sentence

Research Studio makes research handoffs inspectable, private when necessary, and independently verifiable: it packages the conditions behind a result, not just the paper that describes it.

For the complete judge narrative, 90-second pitch, demo storyboard, and source-backed problem statement, see the Codex Competition Pitch. The copy-ready submission fields, Codex/GPT-5.6 provenance, publisher/student vision, OpenAI Sites alignment, and evidence boundary are in the Codex + GPT-5.6 Competition Submission Packet. The editable deck is published at outputs/Research-Studio-Codex-Competition-Pitch.pptx.

Run the decisive three-minute demo

Use the included deterministic minimal-attention study. It demonstrates the whole supported arc without pretending to reproduce a large training run:

npm run demo:prepare

This creates two clean, independent local Git repositories from the tracked fixture: the author source and receiver checkout used by the recording. It is safe to rerun and never downloads source or overwrites a divergent checkout.

1. Record the PDF, exact local source checkout, and declared input under Local only.
2. Review one extracted claim, bind its reviewed command, output, validator, and tolerance.
3. Run the approved Docker sandbox with network denied and inspect the validator result.
4. Seal the evidence, open it from a separate receiver checkout, confirm compatibility, rerun, and attach a fresh receiver receipt.
5. Enter the learner path to explain the same result and create a controlled learning fork.

The exact clicks, fields, files, expected value, and narration are frozen in docs/VIDEO-DEMO-FLOW.md. The fixed expected observable is 0.6697615493, checked by absolute-tolerance at 1e-6.

First run: what the interface will do

Research Studio explains each active workflow in the right-hand Before you continue panel. Hover or keyboard-focus any button to see what it does; hover a field to see the expected type of value. The interface also exposes the records written after intake and names the next possible action instead of silently moving between backend states.

On the landing page, the Optional OpenAI assistance panel tells you whether the local loopback API can use OpenAI:

• No key: paper intake, local parsing, manual claim mapping, contracts, Docker sandboxing, capsule construction, receiver compatibility, and learning paths remain available. No paper, source, or data is sent to a model.
• Key configured: after a server preview of the exact context and explicit consent, OpenAI can produce proposal-only candidate mappings. It cannot approve a claim, choose the final command, execute code, validate a result, or alter canonical evidence.

For a short demo, enter a key through the landing-page connection panel. It is sent only to the loopback API, held only in that server process, cleared from the input immediately, and discarded when the API restarts. For a recurring local setup, configure OPENAI_API_KEY in an ignored .env file instead. Neither path persists a key in browser storage, project files, evidence, or capsules.

Trying a different paper

1. Start Prepare research and capture a new local project instead of resuming the minimal-attention fixture.
2. Add the paper PDF and the local source folder or GitHub repository that produced the work. Add only the data that the selected result needs.
3. Research Studio extracts candidate paper claims when it can. If it cannot reliably identify one, it opens the manual claim form; this is an expected path for scanned PDFs, theoretical papers, figures, and incomplete repositories.
4. Select one bounded result, review the source passage, state assumptions and data requirements, approve the interpretation, then bind its exact command, source allowlist, output, validator, and tolerance.
5. Create a contract and run only that reviewed scope. A more capable machine may run a larger reviewed scope, but Research Studio does not infer absent methods or promise that every arbitrary paper is automatically reproducible.

Trust boundary

Research Studio uses Docker's portable packaging model while applying a deliberately narrow execution policy: reviewed commands only, read-only source and inputs, denied network, capability drops, and bounded resources. This aligns with the need to treat containers as a security boundary rather than a magic reproducibility claim. NIST SP 800-190

For governed data, the default is a project-local reference. A researcher can instead include encrypted material for a named receiver, with an X25519 public key and an out-of-band fingerprint check. The receiver private key stays on the receiver machine. RFC 7748

The resulting evidence is designed around the provenance questions of what entity, which activity, and whose responsibility, consistent with the goals of the W3C PROV model. W3C PROV Primer

What Research Studio truthfully supports

• A compact computational result can travel as a reviewed, checksum-bound contract instead of an informal set of setup instructions.
• A receiver can inspect the package, compare capabilities, map permitted data, rerun from a separate checkout, and produce receiver-owned evidence.
• A private lab can use the product without sending its paper, code, or data to an external model. OpenAI assistance is optional, consent-bound, proposal-only, schema-validated, and cannot approve, execute, or verify.
• A beginner can start with a plain-language paper path, make a prediction, inspect evidence, and only then transition into a scoped reproduction workflow.

What it does not claim

• It does not automatically reproduce every arbitrary paper, infer absent methods, or replace subject-matter review.
• It does not classify a successful process as a reproduced scientific result without a declared observable and validator.
• It does not put private research in an external model by default, or let a model mutate canonical evidence.
• It does not treat an author signature as independent verification; a receiver must rerun and attest from their own boundary.

These boundaries are product strengths: they make a demo credible and keep the evidence legible when the answer is "not yet reproducible."

Documentation map

Document	Use it for
Documentation Index	The role, authority, and current/proposed/historical status of every documentation set
Competition and ChatGPT Sites Strategy	The evidence-backed competition story, current product proof, and explicitly proposed ChatGPT Sites/MCP App direction
Workflow Atlas	Every major product workflow, release gate, failure route, and data boundary in Mermaid diagrams
Feature Evidence Matrix	Which product capability is implemented, where it lives, and how it is exercised
Codex Competition Pitch	Problem evidence, positioning, judge hooks, spoken pitch, and demo story
Codex + GPT-5.6 Competition Submission Packet	Copy-ready submission fields, Codex/GPT-5.6 build provenance, publisher/student vision, platform alignment, and honest proof boundaries
Research Studio Workflow	Supported product boundary and operational decision flow
PRD Conformance Audit	Honest implementation coverage and external validation still required
Video Demo Flow	Click-by-click recording flow with fixed files, truthful claims, and screenshot checkpoints
Minimal Attention Reference	Canonical study values and scope boundary behind the video flow

Six implemented capabilities worth judging

1. Claim-level intake — record a paper, exact source revision, and governed input before anything runs.
2. OpenAI proposal assistance — after a visible context preview and consent, propose claims and mappings in a strict schema; a human still decides.
3. Approved reproduction contract — bind the source allowlist, command, observable, validator, and tolerance into an immutable checksum.
4. Restricted Docker execution — run only approved commands with denied networking, read-only mounts, dropped capabilities, and bounded resources.
5. Independent receiver evidence — require a separate checkout, compatibility decision, fresh run, and receiver-owned receipt.
6. Research Capsule — seal the reviewed contract, evidence, receiver receipt, and learning path into one inspectable portable package.

Advanced capability reference

The full implementation surface—validators, reconstruction, code graph, capsule formats, operational adapters, learning, provenance records, and advanced failure analysis—is deliberately kept out of the first-read narrative. Inspect it in the Feature Evidence Matrix and the Workflow Atlas.

The control plane is local-first and its deterministic workflow requires no model. External model providers are used only after explicit, receipt-bound consent for the disclosed context; Local only mode denies model and external network access. The fixture adapter proves the contract lifecycle and deterministic validators; it never claims to execute untrusted research source. A Docker sandbox adapter executes reviewed commands with deny-network, read-only source/input mounts, capability drops, and explicit approval; it fails closed when Docker is unavailable. HTTPS GitHub repository intake is explicit and commit-pinned. Remote executor adapters export signed, contract-bound GitHub Actions, SLURM, or manual jobs and accept results only when their executor signature and immutable job binding verify; Research Studio does not host compute or store remote credentials.

Research Capsules

A Research Capsule is the portable product boundary, not merely a Docker image. It is generated only after the contract is human-reviewed and checksum-approved, a receiver-owned rerun completes, and a separately keyed receiver attestation verifies. An operator signature alone does not unlock release. The capsule contains:

• the reviewed source snapshot, excluding Git history, local runtime state, environments, build output, and environment files;
• the immutable Reproduction Contract, completed run, and signed attestation;
• a Dockerfile and deterministic entry script for every reviewed command stage;
• a six-stage learner path: Problem, Method, Prediction, Execute, Explain, and Transfer;
• a machine-readable research-capsule.json tying the image, evidence, and learning path together.

The Evidence workspace builds and smoke-tests the image with Docker networking disabled. Smoke execution uses a read-only root filesystem, dropped Linux capabilities, no-new-privileges, and bounded temporary output mounts.

The studio stores the active workspace identifier in browser-local storage and restores paper, repository, preflight, claims, canonical contract, latest run, and learning path from the local control plane. GET /v1/workspaces/{id}/pipeline exposes explicit blockers across intake, claim confirmation, contract approval, execution, independent verification, capsule construction, and guided learning.

The CLI and studio share .repro/api-state.json whenever a studio workspace exists. Use repro migrate --workspace <id> once to import an older .repro/contract.json and .repro/runs.json; canonical repositories are not written in parallel. Generated GitHub workflows run static claim audits on changes and hardened full execution on the weekly schedule or an explicit full/archival dispatch.

Strict PRD conformance and remaining external proof are tracked in docs/PRD-CONFORMANCE-AUDIT.md.

Supported boundary

Research Studio is engineered for compact computational papers with human-reviewed claim bindings. It does not promise to convert every arbitrary paper into reliable code, infer missing methodology, bypass restricted data, or call a successful process a reproduced claim. Python is the locally Docker-verified primary path; R and Jupyter intake, graphing, and command orchestration are implemented but still need broad corpus and cross-machine acceptance.

The PRD gap closure and release evidence are recorded in docs/PRODUCT-GAP-AUDIT-2026-07-14.md.

The practical product boundary, researcher decision flow, and edge-case outcomes are documented in docs/RESEARCH-STUDIO-WORKFLOW.md.

Run locally

Prerequisites

• Git
• Node.js 24.x (the version used by CI) and npm
• Docker Desktop, only for the Docker-backed capsule, sandbox, and receiver execution paths
• Python 3.12+, only for npm run test:paper and optional video tooling

Fresh clone

git clone https://github.com/Utkarsh-Sinha0/ReproLearn.git
Set-Location ReproLearn
npm ci
npm run repro:doctor
npm start

Open http://127.0.0.1:5173. The command starts the loopback API and UI together and stops both with Ctrl+C. Use npm run api and npm run dev separately when debugging either process.

For the built-in author/receiver fixture, run npm run demo:prepare after the clone. It creates matching local Git checkouts in the ignored gallery/ directory and prints their actual paths; do not copy a machine-specific path from a recording. The optional OpenAI proposal path needs a user-supplied key, but all deterministic prepare, verify, learn, and capsule paths work without one.

The standard npm start and npm run receiver launchers create a private, machine-local session token and require it on every /v1 request. Vite injects that token only while proxying from the loopback UI; it is never exposed to browser code or persisted in browser storage. Health and readiness probes are the only unauthenticated endpoints. Direct npm run api remains an explicit developer boundary; set REPRO_REQUIRE_AUTH=1 and REPRO_LOCAL_AUTH_TOKEN when exposing that process to anything beyond an isolated debugging session.

Engineering release gates

npm run lint
npm run api:contract:check
npm run test:coverage
npm run test:api
npm run test:api-server
npm run test:operational
npm run test:external
npm run test:browser
npm run test:docker-e2e
npm run build

The API inventory is generated into contracts/api.openapi.json and src/api/generated-route-contract.ts; CI fails when either artifact drifts from the implemented HTTP and SSE routes. Mutation requests use exact method/path/body idempotency fingerprints. The local state boundary serializes cross-process mutations, uses atomic durable writes, and exposes revisioned state rather than allowing concurrent request handlers to overwrite each other. Requests are rate/concurrency limited, ordinary responses are capped, paper uploads are capped at 25 MiB, artifact collection rejects traversal and symlinks, and external archive/identifier requests require approved HTTPS hosts without redirect following. Optional model proposals run in a bounded queue with schema validation, timeouts, output limits, and proposal-only authority.

Sender-to-receiver capsule handoff

Both parties run the same open-source control plane. A receiver can prepare a fresh machine with:

git clone https://github.com/Utkarsh-Sinha0/ReproLearn.git
Set-Location ReproLearn
npm ci
npm run receiver

The sender captures the reviewed source revision, lockfiles, container image digest, contract, signatures, and governed-data manifest. Small private assets may be encrypted inside the capsule; large datasets and model weights remain in the researcher-controlled vault as encrypted chunks referenced by a signed manifest. The resulting capsule can travel as an email attachment, a private GitHub release, an arXiv or repository supplement, removable media, or a scoped object-store link. The transport is not trusted and receives no plaintext secrets.

Before handoff, the receiver generates an X25519 key pair locally and sends only the public key and fingerprint to the sender. The parties verify that fingerprint through a trusted or out-of-band channel. Research Studio encrypts each asset with a random data key and wraps that key to the verified receiver public key. The receiver private key never leaves the receiver machine and is never compared over the internet.

On receipt, the receiver opens http://127.0.0.1:5173/#verify/open and inspects the signed manifest before approving any execution. Research Studio checks capsule and contract checksums, signer policy, source revision, image digest, data references, runtime, OS, architecture, CPU, memory, and disk. Matching immutable inputs and capabilities can be classified Exact; architecture substitutions require the contract-defined calibration suite before they can be classified Validated equivalent. The final evidence is produced by a fresh receiver-owned rerun, not by trusting the sender's screenshots or prior process status.

For file-based CLI handoff, use the sealed manifest and an independently checked-out repository at its declared commit:

node scripts/repro.mjs receive "<sealed-manifest>" --repo "<separate-receiver-checkout>" --rerun --approve

Optional OpenAI intelligence

The deterministic control plane works without a model. Optional proposal-only assistance uses the official OpenAI Responses API only. For a session-only demo connection, use the landing-page panel; for a recurring local setup, copy .env.example, set OPENAI_API_KEY, and restart npm run api. The UI shows the exact context categories and requires a current, explicit consent receipt before any context leaves the local control plane. Model output is schema-validated, provenance-recorded, and never authorizes execution or mutates a canonical contract.

Copy-Item .env.example .env
# Edit .env locally, then restart the API process.
npm run api

The default model is REPRO_OPENAI_MODEL=gpt-5.4; override it only when deliberately selecting another OpenAI model available to the project key. Connecting checks that exact configured model, not merely that a credential can list models. A landing-page key is transmitted only to the loopback API, held in server memory for that session, and never persisted in browser storage or evidence; an .env key remains in the local server environment. Calls use the Responses API with store: false and strict structured output. A repository secret scan runs before model access, and credential-like context fields are removed before any request or provenance hash is created. Model output can create candidate records and non-executable mapping proposals, but cannot approve a claim, mutate a canonical contract, execute code, or mark a result verified.

MCP run requests require a signed passport bound to the exact contract. A fixture request needs request-run; an approved sandbox execution additionally needs execute-sandbox. MCP returns a permission receipt derived from passport verification and a hash-bound action receipt. To sign action receipts, start npm run mcp with REPRO_AGENT_ACTION_RECEIPT_PRIVATE_KEY set to an Ed25519 PEM key in that process environment; without it, the action receipt remains hash-bound to the signed permission receipt but is not independently signed.

The API binds only to 127.0.0.1:8787. It uses project-local .repro/api-state.json, requires an Idempotency-Key for mutations, and returns an X-Trace-Id for every response. The first operator integrity signature creates a project-scoped Ed25519 identity under .repro/identity/; receiver verification uses a separate identity boundary.

Verification

npm ci
npm run repro:doctor
npm run repro:validate
npm run test:cli
npm run test:ci
npm run test:operational
npm run test:external
npm run test:api
npm run test:api-server
npm run test:graph
npm run test:viewer
npm run test:oci
npm run test:sdk
npm run test:sandbox
npm run test:remote
python -m pip install -r requirements-dev.txt
python -m unittest scripts.test_paper_intelligence
npm test
npm run test:a11y
npm run test:browser
npm run test:docker-e2e
npm run benchmark
npm run build

Local CLI lifecycle

node scripts/repro.mjs init reproducibility-control-plane-prd.md --repo . --fixture
node scripts/repro.mjs doctor --repo .
node scripts/repro.mjs paper paper.pdf --repo .
node scripts/repro.mjs graph --repo . --claim "Method A reaches 91.4% accuracy"
node scripts/repro.mjs map --repo . --approve table-2-accuracy --actor local-human-reviewer
node scripts/repro.mjs run --repo . --tier smoke
node scripts/repro.mjs sandbox --repo . --image python:3.12-slim --command "python -m experiments.table2" --execute --approve
node scripts/repro.mjs repair --repo . --level technical
node scripts/repro.mjs verify --repo .
node scripts/repro.mjs attestation-verify --repo .
node scripts/repro.mjs diff --repo .
node scripts/repro.mjs learn --repo .
node scripts/repro.mjs seal --repo .
node scripts/repro.mjs view --repo .
node scripts/repro.mjs receive "<sealed-manifest>" --repo "<separate-receiver-checkout>" --rerun --approve
node scripts/repro.mjs capsule --repo . --receiver-evidence "<receiver-evidence-packet>"
node scripts/repro.mjs export binder --repo .
node scripts/repro.mjs export ro-crate --repo .
node scripts/repro.mjs export reprozip --repo .
node scripts/repro.mjs export zenodo --repo .

The commands produce inspectable, project-local state under .repro/ and exports/. repro verify creates operator integrity evidence, not independent verification. repro receive must run from an explicit checkout at the sealed commit and emits a receiver evidence packet; final capsule construction requires that packet. repro view writes exports/viewer/index.html, a local static evidence viewer. The fixture run is suitable for the included demo only; it is not a sandbox for arbitrary repositories.

Published reproducibility capsule

The repository includes the exact, public-safe minimal-attention capsule built for the demo, its signed receiver evidence, source snapshot, Docker recipe, validator output, and integrity manifest. Its scope, verification command, Docker rerun, and limitations are in the published capsule guide. This is a compact deterministic witness, not a claim to reproduce a full Transformer training run.

PDFs selected in the app are capped at 25 MB, checked for PDF magic bytes, and never uploaded beyond the loopback API. Repository preflight and code-graph scans run only against the local repository explicitly bound to the workspace.

Project layout

src/domain/          deterministic claim, policy, and diff logic
src/components/      evidence, execution, and learning surfaces
src/data/            local demonstration workspace
exports/research-capsules/contract-eed699a5-31d/  published minimal-attention capsule
scripts/lib/         preflight, policy, validation, run, and sealing core
scripts/repro.mjs    local lifecycle CLI
.github/workflows/   reproducibility CI workflow
.venv/               isolated Python tooling environment, ignored by Git

reproducibility-control-plane-prd.md is the immutable source of truth and is not modified by the application.

License

ReproLearn is released under the MIT License.