Corvex

AI-Powered Scientific Research Automation Platform

Corvex employs a system of intelligent agents to automate experimental design, data analysis, and iterative optimization workflows. Built around large language models with domain-specific tools, these agents act as AI research partners that can plan experiments, analyze results across multiple modalities, and suggest optimal next steps.

Overview

Corvex provides three complementary agent systems that cover the full scientific research cycle:

System	Purpose	Key Capabilities
Planning Agents	Experimental design & optimization	Hypothesis generation, Bayesian optimization, literature-aware planning
Analysis Agents	Multi-modal data analysis	Image analysis, spectroscopy, hyperspectral datacubes, curve fitting
Simulation Agents	Computational modeling	DFT calculations, classical MD (LAMMPS), structure recommendations

Core Capabilities

RAG over your knowledge base. User-supplied papers, project notes, instrument manuals, and prior results are indexed and retrieved to ground hypothesis generation and experiment design.
Agentic Knowledge Query. Complements RAG for structured data — tabular files and record databases. The agent generates and executes query code dynamically, no upfront schema definition required. Two depths share the same machinery: query_knowledge_data for ad-hoc exploration ("what fields exist?", "value range of X?") and screen_database for production filter-and-rank passes with a structured top-K output.
Tools + code. Pre-built or user-provided tools (such as pre-trained ML models) combine with on-the-fly code generation to produce runnable analysis scripts, simulation input decks, or lab-automation protocols. Executors run locally, on HPC, or on lab instruments.
Pluggable skill bundles. Domain experts extend the platform to new instrument data types or simulation methods by contributing self-contained markdown files (plus optional Python helpers). The platform discovers and routes to them automatically — no core-agent changes required.
Three autonomy levels. Co-Pilot (human leads, reviews every step), Autopilot (AI leads, human reviews major decisions), and Autonomous (no human review). The mode selects who holds the acceptance gate on agent commitments.
Simulated-annealing agentic pipelines. Hold domain priors strictly at first, then progressively thaw the lock on the implementation plan and domain-rule strictness only when iterative refinements fail to converge — inspired by Metropolis–Hastings, with verifier-driven acceptance.

Installation

pip install corvex

# With simulation dependencies (ASE, atomate2, etc.)
pip install corvex[sim]

The web UI (corvex ui) is included in the default installation.

The analysis agents work without additional dependencies, but installing Meta's Segment Anything Model (SAM) enables more advanced particle and grain segmentation. SAM is not available on PyPI and must be installed from source:

pip install git+https://github.com/facebookresearch/segment-anything.git

Environment Variables

Set API keys for your preferred LLM provider:

# Google Gemini (default)
export GEMINI_API_KEY="your-key"

# OpenAI
export OPENAI_API_KEY="your-key"

# Anthropic
export ANTHROPIC_API_KEY="your-key"

# OpenAI-compatible proxy (if applicable)
export CORVEX_API_KEY="your-key"

When using CORVEX_API_KEY, also provide a --base-url pointing to your OpenAI-compatible endpoint.

Quick Start

Corvex can be used via the CLI, web UI, MCP server, or Python API.

CLI

# Planning session
corvex plan
corvex plan --autonomy autopilot --data-dir ./results --knowledge-dir ./papers

# Analysis session
corvex analyze
corvex analyze --data ./sample.tif --metadata ./metadata.json

Web UI

corvex ui

MCP Server

corvex serve --model claude-opus-4-6

See MCP Integration for details.

Python API

from corvex.agents.planning_agents import PlanningAgent
from corvex.agents.exp_agents import AnalysisOrchestratorAgent, AnalysisMode

# Generate an experimental plan
planner = PlanningAgent(model_name="claude-opus-4-6")
plan = planner.propose_experiments(
    objective="Optimize lithium extraction yield",
    knowledge_paths=["./literature/"],
    primary_data_set={"file_path": "./composition_data.xlsx"}
)

# Analyze image data
analyzer = AnalysisOrchestratorAgent(analysis_mode=AnalysisMode.AUTOPILOT)
result = analyzer.chat("Analyze ./stem_image.tif and generate scientific claims")

MCP Integration

Corvex supports the Model Context Protocol (MCP) as both a server (exposing its tools/agents to external clients like Claude Code) and a client (connecting to external MCP servers for additional capabilities).

As an MCP Server

Expose Corvex's analysis and planning tools to any MCP-compatible client:

# Default (stdio transport, autonomous mode)
corvex serve --model claude-opus-4-6

# Analysis only, with human approval for major actions
corvex serve --mode analyze --autonomy co-pilot

# HTTP transport (SSE)
corvex serve --transport sse --host 127.0.0.1 --port 8000

The server exposes all orchestrator tools (prefixed corvex_ for analysis, corvex_plan_ for planning), plus job management tools for long-running operations. Autonomy modes control which tools require human approval before execution.

Client setup is one command — corvex serve --print-mcp-json emits a ready-to-paste, secret-free config entry (zero-install uvx spec when available) — and credentials live in one place, ~/.corvex/credentials.env, loaded by the server at startup. While tools run, their narration streams to the client as MCP log notifications; sessions and background jobs survive server restarts (a fixed --session-dir resumes the campaign). See docs/connecting_agent_clients.md for the unified guide — every client (Claude Code/Desktop, Deep Agents, VS Code, your own framework), the three server placements, and the container layouts — and docs/claude_code_integration.md for the Claude-specific walkthrough.

As an MCP Client

Connect external MCP servers to extend Corvex with additional tools:

# Python MCP server (e.g., arXiv paper search)
corvex analyze --mcp stdio:arxiv:python,-m,arxiv_mcp_server,--storage-path,/tmp/papers

# Remote streamable-HTTP server (e.g., a hosted lab platform with token auth)
corvex analyze --mcp mcp_config.json   # {"url": "...", "transport": "http", "headers": {...}}

Programmatically:

orchestrator = AnalysisOrchestratorAgent()
tool_count = orchestrator.connect_mcp_server(
    server_name="arxiv",
    command=["python", "-m", "arxiv_mcp_server", "--storage-path", "/tmp/papers"]
)

# or a remote server over streamable HTTP with bearer-token auth
tool_count = orchestrator.connect_mcp_server(
    server_name="lab-platform",
    url="https://mcp.example.com/mcp",
    transport="http",
    headers={"Authorization": f"Bearer {os.environ['LAB_PLATFORM_API_KEY']}"},
)

In the web UI, go to the Tools tab > MCP Servers section, select a transport (stdio/SSE/HTTP), enter the server name and command or URL (plus optional headers for authenticated servers), and click Connect.

See docs/mcp_client_integration.md for the full MCP guide.

Extensibility

Corvex supports custom tools, skills, and agents that can be added via CLI flags, the web UI, or programmatically.

Custom Tools

Provide a Python file with tool_schemas (list of OpenAI-format tool dicts) and a create_tool_functions(data) factory:

corvex analyze --tools ./my_image_tools.py

See docs/custom_tools_integration.md for the full guide, including how custom tool outputs flow into built-in agents and how to feed a preprocessed file back into the analysis pipeline.

Custom Skills

Add domain-specific analysis guidance via Markdown skill files:

corvex analyze --skills ./raman_skill.md ./ftir_skill.md

Built-in skills are available for image analysis (atomic-resolution STEM, etc.), curve fitting (XPS, Raman, etc.), and hyperspectral analysis (EELS, etc.).

Custom Agents

Register additional BaseAnalysisAgent subclasses:

corvex analyze --agents ./my_xrd_agent.py

Persistent Memory

Corvex agents learn from hard problems and keep that knowledge across sessions. Graduated and auto-distilled skills are stored under ~/.corvex/ (override with $CORVEX_HOME) — outside the installed package, so they survive a pip upgrade and are auto-discovered on every future run. Manage them with:

corvex memory list                 # graduated/auto-distilled skills
corvex memory staged               # raw T=2 solutions awaiting distillation
corvex memory upgrade <domain>/<id> --into <domain>/<name>   # enrich an existing skill
corvex memory consolidate <domain>/<technique>              # distill N into a new skill
corvex memory promote <domain>/<name>                       # make a provisional skill auto-routable

Docker: the store lives in the container's home (~/.corvex), which is ephemeral — learned skills are lost when the container exits unless you mount a volume. The image declares it as a VOLUME; persist it with, e.g.:
docker run -v ~/.corvex:/home/corvexuser/.corvex corvex ...
# or: docker run -e CORVEX_HOME=/data -v corvex-mem:/data corvex ...
Without a mount, Corvex logs a one-time warning that memory won't persist.

Named Knowledge Bases

Knowledge bases — your papers, datasheets, and prior reports, embedded for retrieval-augmented planning — can be promoted to named, reusable artifacts stored under ~/.corvex/knowledge_bases/ (rides $CORVEX_HOME). Build one once (this embeds the documents, so it needs the embedding provider's API key); every later session reuses the persisted index from any directory:

corvex kb create produced-water --from ./papers ./composition_data \
    --description "Produced-water composition and criticality references"
corvex kb list                          # what exists, built with which embedding model
corvex kb add produced-water --from ./new_paper.pdf   # embeds only the new documents
corvex kb import legacy --from ./kb_storage --embedding-model gemini-embedding-001
corvex kb rebuild produced-water --embedding-model text-embedding-3-small

Use a KB by name wherever a knowledge directory is accepted:

corvex plan --knowledge-dir produced-water
corvex explore --knowledge-dir produced-water

In a meta (explore) session you don't need the flag: detached KBs — the launch directory's kb_storage, plus every named KB with its description and source list — are offered in chat. In autopilot the meta asks before the first planning delegation; in autonomous mode it attaches the KB whose sources are clearly relevant to the task (and leaves all detached otherwise). Growing a KB works from chat too — "add this datasheet to my produced-water knowledge base" embeds just that document (with the KB's own embedding model) and the running session picks it up immediately; additions happen only on your explicit request, since a named KB is shared across sessions. Sessions otherwise treat named KBs as read-only: in-session document use stays session-local and never mutates the store.

Each KB's manifest.json records the embedding model that built it, so a provider mismatch (e.g. a Gemini-built KB in an OpenAI-embedding session) warns upfront with a rebuild hint instead of failing opaquely at query time. And a KB is never unusable: when its embedding provider is unavailable, retrieval falls back to model-free keyword (BM25) search over the stored chunks — lower recall than dense retrieval, but real grounding from any KB in any session, with zero embedding dependency. A KB created with kb create keeps copies of its source documents and can be re-embedded with kb rebuild; an imported one cannot (no sources), so prefer create when you have the original documents.

Behavior changes (vs. releases before the KB store):

A meta/explore session no longer silently inherits whatever kb_storage/ sits in the launch directory. Grounding is always an explicit choice: the --knowledge-dir flag, a chat-time confirmation, or the autonomous relevance decision. Standalone corvex plan behavior is unchanged.
A planning-tool retrieval failure (e.g. missing embedding key) now degrades through tiers instead of aborting plan generation: dense retrieval → keyword (BM25) retrieval → no retrieved context, each step logged.
--knowledge-dir accepts a store name as well as a path; an existing directory always wins over a same-named KB.

Planning Agents

The Planning Agents module automates experimental design and iterative optimization workflows.

Architecture

Agent	Purpose
PlanningOrchestratorAgent	Coordinates the full experimental workflow via natural language
PlanningAgent	Generates experimental strategies using dual knowledge bases
ScalarizerAgent	Converts raw data (CSV, Excel) into optimization-ready metrics
BOAgent	Suggests optimal parameters via Bayesian Optimization

CLI Usage

corvex plan
corvex plan --autonomy autopilot --data-dir ./results --knowledge-dir ./papers
corvex plan --model claude-opus-4-5

Interactive Session Example

$ corvex plan

📋 What's your research objective?
Your objective: Optimize lithium extraction from brine

👤 You: Generate a plan using papers in ./literature/

🤖 Agent: ⚡ Generating Initial Plan...
    📚 Retrieved 8 document chunks.

🔬 EXPERIMENT 1: pH-Controlled Selective Precipitation
> 🎯 Hypothesis: Adjusting pH to 10-11 will selectively precipitate Mg(OH)₂ while retaining Li⁺

👤 You: Analyze ./results/batch_001.csv and run optimization

🤖 Agent: [calls analyze_file → {"metrics": {"yield": 78.5}}]
  [calls run_optimization → {"recommended_parameters": {"temp": 85.2, "pH": 6.8}}]

CLI Commands

Command	Description
`/help`	Show available commands
`/tools`	List all available agent tools
`/files`	List files in workspace
`/state`	Show current agent state
`/autonomy [level]`	Show or change autonomy level
`/checkpoint`	Save session checkpoint
`/quit`	Exit session

Python API

from corvex.agents.planning_agents.planning_orchestrator import (
    PlanningOrchestratorAgent, AutonomyLevel
)
from corvex.agents.planning_agents import PlanningAgent, ScalarizerAgent, BOAgent

# Using the orchestrator
orchestrator = PlanningOrchestratorAgent(
    objective="Optimize reaction yield",
    autonomy_level=AutonomyLevel.AUTOPILOT,
    data_dir="./experimental_results",
    knowledge_dir="./papers"
)
response = orchestrator.chat("Generate initial plan and analyze batch_001.csv")

# Direct agent usage
agent = PlanningAgent(model_name="claude-opus-4-6")
plan = agent.propose_experiments(
    objective="Screen precipitation conditions",
    knowledge_paths=["./literature/"],
    primary_data_set={"file_path": "./composition_data.xlsx"}
)

# Bayesian optimization
bo = BOAgent(model_name="claude-opus-4-6")
result = bo.run_optimization_loop(
    data_path="./optimization_data.csv",
    objective_text="Maximize yield while minimizing cost",
    input_cols=["Temperature", "pH", "Concentration"],
    input_bounds=[[20, 80], [6, 10], [0.1, 2.0]],
    target_cols=["Yield"],
    batch_size=1
)

Experimental Analysis Agents

The Analysis Agents module provides automated scientific data analysis across multiple modalities.

Architecture

ID	Agent	Use Case
0	CurveFittingAgent	1D fitting — XRD, UV-Vis, PL, DSC, TGA, kinetics
1	ImageAnalysisAgent	All image types — microscopy, SEM, TEM, AFM, optical. Handles atomic resolution, grains, particles, textures, defects, morphology
2	HyperspectralAnalysisAgent	Spectroscopic datacubes — EELS-SI, EDS, Raman imaging

Beta: ImageAnalysisAgent is under active development. Expect rough edges: verification scores and planner choices can vary across runs, and some domain-specific defaults are still being tuned. Feedback welcome.

CLI Usage

corvex analyze
corvex analyze --data ./sample.tif --metadata ./metadata.json
corvex analyze --mode autonomous --data ./spectrum.npy

Interactive Session Example

$ corvex analyze --data ./stem_image.tif

👤 You: Examine my data and suggest an analysis approach

🤖 Agent: ⚡ Examining data at ./stem_image.tif...
  • Type: microscopy, Shape: 2048 x 2048
  • Suggested agent: ImageAnalysisAgent (1)

👤 You: Run the analysis

🤖 Agent: ⚡ Running analysis...
  Tier 1: Detected atomic columns with two distinct intensity populations.
  Tier 2 recommended — sublattice separation and displacement field analysis.
  **Scientific Claims Generated:** 3

CLI Commands

Command	Description
`/help`	Show available commands
`/tools`	List orchestrator tools
`/agents`	List analysis agents with descriptions
`/status`	Show session state
`/mode [level]`	Show or change analysis mode
`/schema`	Show metadata JSON schema
`/quit`	Exit session

Python API

from corvex.agents.exp_agents import (
    AnalysisOrchestratorAgent, AnalysisMode,
    ImageAnalysisAgent, HyperspectralAnalysisAgent, CurveFittingAgent
)

# Using the orchestrator
orchestrator = AnalysisOrchestratorAgent(
    base_dir="./my_analysis",
    analysis_mode=AnalysisMode.AUTOPILOT
)
response = orchestrator.chat("Examine ./data/sample.tif")

# Direct image analysis with two-tier pipeline
agent = ImageAnalysisAgent(analysis_depth="auto")
result = agent.analyze(
    "stem_image.tif",
    system_info={"experiment": {"technique": "HAADF-STEM"}},
    objective="Identify crystal phases and defects"
)

# Image series with outlier detection
result = agent.analyze(
    ["img_001.tif", "img_002.tif", "img_003.tif"],
    series_metadata={"variable": "dose", "values": [1e14, 1e15, 1e16], "unit": "ions/cm²"}
)

# Curve fitting
agent = CurveFittingAgent(output_dir="./curve_output", use_literature=True)
result = agent.analyze(
    ["pl_300K.csv", "pl_350K.csv", "pl_400K.csv"],
    series_metadata={"variable": "temperature", "values": [300, 350, 400], "unit": "K"}
)

Metadata Conversion

from corvex.agents.exp_agents import generate_metadata_json_from_text

# "HAADF-STEM of MoS2 monolayer, 50nm FOV, 300kV"
# → {"experiment_type": "Microscopy", "experiment": {"technique": "HAADF-STEM"}, ...}
metadata = generate_metadata_json_from_text("./experiment_notes.txt")

Novelty Assessment

Corvex can automatically check experimental findings against the scientific literature to identify what's genuinely new. This is powered by integration with FutureHouse AI agents.

👤 You: Assess novelty of these claims

🤖 Agent: ⚡ Searching literature via FutureHouse...

  📚 [Score 2/5] Mixed 2H/1T phase coexistence → Well-documented
  🤔 [Score 3/5] Sulfur vacancy density of 3.2 × 10¹³ cm⁻² → Similar measurements exist
  🌟 [Score 4/5] 1T phase localized within 5nm of grain boundaries → Limited prior reports

  Summary: 1 HIGH-NOVELTY finding identified

The discovery loop: Analysis generates scientific claims → Novelty Assessment scores each against literature → Recommendations prioritize validation experiments for novel findings.

Output Structure

Planning Session

campaign_session/
├── optimization_data.csv      # Accumulated experimental data
├── plan.json                  # Current experimental plan
├── plan.html                  # Rendered plan visualization
├── checkpoint.json            # Session state for restoration
└── output_scripts/            # Generated automation code

Analysis Session

analysis_session/
├── results/
│   └── analysis_{dataset}_{agent}_{timestamp}/
│       ├── metadata_used.json
│       ├── analysis_results.json
│       ├── visualizations/
│       └── report.html
├── chat_history.json
└── checkpoint.json

Simulation Agents

Drive atomistic simulations from natural-language goals. The interactive chat surface is corvex simulate, backed by the engine-neutral SimulationOrchestratorAgent; the same pipeline is available programmatically as run_complete_workflow (one-shot: structure → inputs → optional validation → optional run). Every scale flows through one scale-agnostic path — the routing decision selects the scale (periodic DFT / molecular QC / classical MD / MLIP) and the engine is supplied by a markdown skill bundle, so no engine filenames are hardcoded in agent code.

Structure generation

StructurePipeline runs the build → validate → refine loop for five structure classes (crystal, molecular, condensed, biomolecular, aimsgb), each driven by a markdown skill bundle that supplies the build guidance, the output format (POSCAR / xyz / pdb / extxyz), and the class-specific validation rubric. StructurePlanner maps a free-text request onto the right structure_class and downstream simulation_scale.

Periodic DFT

PeriodicDFTAgent is engine-agnostic; the engine is selected by skill bundle. Two engines ship today — VASP and Quantum ESPRESSO — under corvex/skills/periodic_dft/{vasp,qe}/. Adding ABINIT or CP2K is a drop-in markdown bundle, no agent code changes.

Classical MD and MLIPs

MDSimulationAgent generates classical-MD inputs (engine selected by skill bundle — LAMMPS ships today), with ForceFieldAgent assigning the potential and StructurePipeline packing the condensed-phase box. MLIPAgent deploys machine-learned potentials as an engine-neutral runner. Force-field vs MLIP is chosen downstream of routing once the structure exists — an MLIP is a potential source, not a separate scale.

Post-run analysis

SimulationAnalysisAgent computes properties from a finished run's output via verified codegen (scalar values and non-scalar observables — curves, images, datacubes), engine-agnostic.

CLI

corvex simulate                                            # co-pilot chat
corvex simulate --mode autopilot                           # AI proceeds with defaults
corvex simulate --request "rutile TiO2 supercell with one O vacancy"

Python API

from corvex.agents.sim_agents import (
    StructurePipeline, PeriodicDFTAgent, run_complete_workflow,
)

# Structure-only build (engine-agnostic, class-aware)
sp = StructurePipeline(generator_model="claude-opus-4-6")
res = sp.build_structure("a single water molecule", structure_class="molecular")
# → res["final_structure_path"] points at structure.xyz

# Full one-shot pipeline (structure + inputs together), any scale/engine
run_complete_workflow(
    "diamond Si, 2-atom primitive cell, ground-state SCF",
    scale="periodic_dft", software="vasp",
)

# Quantum ESPRESSO inputs via the engine-agnostic agent
PeriodicDFTAgent().generate_inputs(
    structure_file="POSCAR",
    request="vc-relax of Cu fcc",
    software="qe",
)

Skill Graduation

Corvex's chat orchestrators (plan, analyze, simulate) don't just consume skills — they grow them. During a session, the agent records observations into a session-scoped knowledge store. When an observation looks like a recurring pattern (a recurring failure mode, a non-obvious parameter choice, a domain rule), it can be graduated into a Markdown skill bundle that's stored on disk and auto-loaded into agent context on every subsequent run. No code changes, no manual skill authoring.

The graduation tool is exposed in all three modes — analyze, plan, and simulate — under the same name (graduate_to_skill). In autopilot and autonomous modes the agent decides itself when an observation is worth graduating; in co-pilot it surfaces the candidate and asks first.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
corvex		corvex
docs		docs
examples		examples
misc		misc
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Dockerfile.corvex_mdanalysis		Dockerfile.corvex_mdanalysis
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

Corvex

Overview

Core Capabilities

Installation

Environment Variables

Quick Start

CLI

Web UI

MCP Server

Python API

MCP Integration

As an MCP Server

As an MCP Client

Extensibility

Custom Tools

Custom Skills

Custom Agents

Persistent Memory

Named Knowledge Bases

Planning Agents

Architecture

CLI Usage

Interactive Session Example

CLI Commands

Python API

Experimental Analysis Agents

Architecture

CLI Usage

Interactive Session Example

CLI Commands

Python API

Metadata Conversion

Novelty Assessment

Output Structure

Planning Session

Analysis Session

Simulation Agents

Structure generation

Periodic DFT

Classical MD and MLIPs

Post-run analysis

CLI

Python API

Skill Graduation

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages