Skip to content

CSPilot Documentation

Computational chemistry agentic workflow package.

Created by Sandip Giri.

CSPilot is a command-line package for reproducible molecular structure workflows. It combines deterministic local tools, OpenRouter-backed planning, LangGraph orchestration, JSON verification, and polished terminal reports.

Quick Install

python -m pip install -e .

For documentation builds:

python -m pip install -e ".[docs]"
mkdocs build --strict

For stk support:

python -m pip install -e ".[stk]"

First Command

cspilot inspect tests/examples/input.xyz

This reads an XYZ file with ASE and writes a timestamped result.json.

Agentic Start

Single-agent graph:

cspilot graph-run "inspect tests/examples/input.xyz" \
  --workdir runs/water --profile chem --agent-mode single

Routed multi-agent graph:

cspilot graph-run "build water from SMILES O with stk" \
  --profile auto --agent-mode multi --workdir runs/water

Documentation Map

  • Installation: install with uv or pip.
  • Configuration: .env.cspilot, OpenRouter, ORCA, xTB, and MACE.
  • CLI Usage: every implemented command and output file.
  • Agent Usage: direct agent, planner/executor, LangGraph.
  • Workflows: xTB, ORCA, stk, NWPESSe, and result extraction.
  • Tools: Python and agent tools grouped by domain.
  • Agentic Audit: current autonomy and orchestration assessment.
  • Examples: copy-paste workflows.
  • Safety: execution boundaries and scientific integrity.
  • Code Documentation: public orchestration entry points.

Current Status

Implemented:

  • ASE inspection.
  • xTB optimization.
  • ORCA calcultions.
  • xTB to ORCA workflows.
  • MACE to ORCA workflow.
  • stk build/edit/export and stk to xTB.
  • NWPESSe fragment-cluster search.
  • OpenRouter direct agent and JSON planner/executor.
  • LangGraph single mode and routed multi mode.
  • Opt-in independent child loops with --multiagent; see usage and limits.
  • Local Multiwfn Mulliken/Hirshfeld charges and Mayer bond orders.
  • Rich terminal reports and Markdown/HTML final reports.

Planned:

  • Checkpoint/resume and request-level completion validation.
  • Additional validated Multiwfn post-processing operations.
  • Expanded stk topology presets.
  • torch-sim MLIP molecular dynamics.
  • MongoDB job database.
  • MCP server.
  • Streamlit UI.

Build Notes

The documentation site uses MkDocs and mkdocstrings. Reference pages document the real import package, cspilot, not chemagent.