academic-commercialization-agent: Instructions file for Codex

AGENTS.md — working on this project

An index, not a summary. Almost everything worth knowing is already in the repository — the point of this file is to tell you where, and to stop you redoing a handful of things that have already been tried and measured.

What it is

A six-agent CrewAI pipeline that assesses whether a piece of academic research is commercially viable. Three evidence agents (academic / patent / market) run in parallel, then a report writer, a reviewer, and a scorer. Served two ways from one codebase: a FastAPI + vanilla-JS web client and a CLI.

Live at https://academic-commercialization-agent.up.railway.app

Baseline at 0fdaa76 (2026-09-05 documentation audit): 2071 tests and 678 subtests. CI covers Linux + Windows × Python 3.11/3.12; Railway hosts the demo. See current evidence status for qualified results, not an ever-growing chronological paragraph here.

Commands

uv run pytest -q                       # the whole suite; zero provider calls
uv run --with ruff ruff check .        # CI uses latest ruff, the local pin is older
uv sync --group e2e                    # opt-in real-browser dependency; not part of the default suite
uv run --group e2e playwright install chromium
uv run --group e2e python -m e2e.browser_smoke   # loopback only; zero provider calls
uv run --group e2e python -m e2e.composer_smoke  # static-only server; intercepted paid POSTs
uv run uvicorn api.main:app --reload   # web client on :8000
uv run academic_agent --topic "<topic>"          # one run from the CLI

uv run --with ruff is deliberate. The pinned local ruff is 0.12.0 and CI resolves latest; they disagree, and the flag is what makes a local check mean what CI will say.

Hard conventions

• filterwarnings = ["error::UserWarning"]. What it mainly guards: code paths that would reach a paid API warn and fall back rather than raising, so a test that leaks would otherwise pass silently. When a test trips it, read which warning fired before concluding anything. If it is the network one, the test is calling something real — fix the test's isolation, never add an ignore. But the project also warns deliberately on an unrecognised weight profile and on an audit screen that failed, and two test files assert those on purpose (assertWarns), so not every UserWarning is a leak.
• No bare except Exception without a # noqa: BLE001 and a reason. This is a review convention; the current Ruff selection does not enable BLE001. Do not assume a green lint job enforces it.
• CI also runs pylint, narrowly, for bad exception order, unreachable code, used-before-assignment and undefined variables. The exception-order check caught HTTPError placed after URLError: dead code that retried auth failures as transient. Use the exact command in CONTRIBUTING.md.
• Commit messages carry the reasoning. They are long on purpose and are a primary record — see below. Do not add Co-Authored-By lines.
• Reply to the user in Chinese. The code, comments, and commit messages stay in English.