openscientist CLAUDE.md

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.

Project Structure

src/openscientist/
├── agent/            # AgentExecutor protocol and ClaudeCodeAgent
├── 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
├── mcp_server/       # MCP server for agent tools
├── orchestrator/     # Discovery orchestration (setup, iteration, report)
├── providers/        # LLM provider abstractions (Anthropic, Vertex, etc.)
├── tools/            # @tool-decorated callables for SDK agent path
├── webapp_components/# NiceGUI pages and components
├── prompts.py        # Agent system prompts
├── settings.py       # Pydantic settings with TOML support
└── web_app.py        # Main application entry point

Development Setup

# Install dependencies
uv sync

# Set up environment variables (see .env.example)
export DATABASE_URL="postgresql+asyncpg://..."
export OPENSCIENTIST_SECRET_KEY="$(openssl rand -hex 32)"
export ANTHROPIC_API_KEY="..."  # or other provider credentials

# Run database migrations
uv run alembic upgrade head

# Start development server
uv run python -m openscientist.web_app --reload

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=openscientist

Testing Conventions

Use real database objects, not mocks. Tests use testcontainers to spin up a real PostgreSQL database. Always create real SQLAlchemy model instances instead of mock classes:

# GOOD: Create real database records
@pytest_asyncio.fixture
async def test_job(db_session: AsyncSession, webapp_user: User) -> Job:
    job = Job(
        owner_id=webapp_user.id,
        title="Test research question",
        status="pending",
    )
    db_session.add(job)
    await db_session.commit()
    return job

# BAD: Don't create mock classes that bypass the database
class MockJobInfo:  # Don't do this
    job_id = "fake-id"
    status = "pending"