openscientist: Instructions file for Codex

OpenScientist Development Guide

OpenScientist (Scientific Hypothesis Agent for Novel Discovery) is a web application that runs autonomous AI agents for scientific data analysis and hypothesis testing.

Rules for Agents

Follow the pull request policy in CONTRIBUTING.md. In particular:

• Never push, open pull requests or issues, or post comments, because the person you work for reviews and publishes everything.
• Never write pull request descriptions, issue bodies or replies to comments, and ask the person to write them instead.
• Keep each branch to one feature or fix, and put dependent work on its own stacked branch.
• Search the open issues and pull requests for the same work before starting.
• Leave unrelated refactors and formatting changes out of the branch.
• Write comments and docstrings only for what the code does not make evident.
• Test the real code and never a mock of it, and for a bug fix, watch the regression test fail before writing the fix.
• Remind the person to attach screenshots when the change touches the user interface.
• If the person cannot review the change, suggest that they open an issue written in their own words.
• If a request breaks one of these rules, stop and name the rule.

Project Structure

src/
├── openscientist/
│   ├── agent/            # AbstractAgent and the Claude Code, Codex and omp harnesses
│   ├── api/              # FastAPI REST endpoints
│   ├── auth/             # Authentication (OAuth, sessions, middleware)
│   ├── database/         # SQLAlchemy models and migrations
│   ├── job/              # Job lifecycle, scheduling, and types
│   ├── job_container/    # Container-per-job isolation
│   ├── orchestrator/     # Discovery orchestration (setup, iteration, report)
│   ├── providers/        # LLM providers (Anthropic, Vertex, OpenAI, Ollama, etc.)
│   ├── prompts/          # Agent system prompts
│   ├── pubmed_mirror/    # Optional local PubMed corpus for air-gapped jobs
│   ├── report/           # Report rendering to HTML and PDF
│   ├── transcript/       # One transcript schema for every harness
│   ├── webapp_components/# NiceGUI pages and components
│   ├── job_manager.py    # Starts, tracks and cancels jobs
│   ├── knowledge_state.py# A job's hypotheses, findings and literature
│   ├── llm_proxy.py      # Key-replacement proxy between job containers and the provider
│   ├── exec_broker.py    # Runs a job container's code without the Docker socket
│   ├── settings.py       # Pydantic settings
│   └── web_app.py        # Main application entry point
├── openscientist_tools/  # MCP server with the agent's tools, run inside the job container
└── openscientist_executor/ # Runs model-written code inside the executor container