⚗️ ChemAgent

AI Agent for Chemistry Research

A local-first AI assistant for chemistry research — chat, tool calling, knowledge base, and a skill system. One codebase, runs in browser and desktop.

🌐 English · 简体中文

---

🧪 A local-first AI Agent built for chemistry research: not just a chatbot — it calls tools, searches a knowledge base, executes commands, and renders molecular structures.

✨ Features

	Capability	Description
💬	AI Chat	Streaming output, expandable reasoning traces, OpenAI-compatible APIs (DeepSeek / Qwen / OpenAI)
🛠️	Tool Calling	File I/O, command execution, chemvision molecular visualization, skill system
📚	Knowledge Base	Document ingestion → LLM cleaning → RAG retrieval with cited sources
🧩	Skill Management	List / detail / translate skill descriptions, extensible custom skills
🗂️	Workspaces	Local directory anchoring, artifact preview / execution / file reveal
✅	Human Approval	Result gate for sensitive actions (write_file / run_command) — Approval Card
📝	Selection Actions	Select text → explain / rewrite / summarize / follow-up
🎨	Dual Themes	Light (default) + dark AI-native mode, one-click toggle with persistence
🖥️	Desktop App	Electron shell + PyInstaller backend exe — no Python / Node required, Windows x64

🏗️ Architecture

┌───────────────┐   HTTP / SSE    ┌────────────────────────┐
│  Frontend     │ ──────────────▶ │  Backend (FastAPI)     │
│  React 19     │     /api/*      │  + uvicorn :8000       │
│  Tailwind 4   │                 │  + tools / KB / skills │
└───────────────┘                 └────────────────────────┘
        ▲
        │  Electron shell (desktop/): spawns backend exe,
        │  preload exposes native capabilities (folder picker, etc.)

Directory	Description
backend/	FastAPI + uvicorn; PyInstaller builds chemagent-backend.exe (bundles frontend dist, same-origin hosting)
frontend/	React 19 + Vite + Tailwind CSS 4 + shadcn-style components
desktop/	Electron shell + electron-builder packaging config

🚀 Quick Start

Development

# 1. Backend (port 8000)
cd backend
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt      # Windows
.venv\Scripts\uvicorn app.main:app --port 8000

# 2. Frontend (port 5173, proxies /api → 8000)
cd frontend
npm install
npm run dev        # http://localhost:5173

First run: open Model Settings (top-right) and enter your own LLM API Key (OpenAI-compatible — DeepSeek / Qwen / OpenAI).

Desktop App

cd desktop
npm install
npm run dev        # Electron + Vite dev

node build.mjs                                   # Full build: frontend → backend exe → NSIS installer
node build.mjs --skip-frontend --skip-backend    # Rebuild Electron shell only

Output: desktop/release/ChemAgent Setup <ver>.exe (NSIS installer) and win-unpacked/ (portable).

Note: installer is unsigned — Windows SmartScreen may warn on first run; click More info → Run anyway.

📊 Project Stats

Visit wangruichuan/ChemAgent for the latest stats.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/xxx
3. Commit your changes: git commit -m "feat: ..."
4. Push: git push origin feat/xxx
5. Open a Pull Request

📄 License

MIT © 2026 wangruichuan