# ChatVasp

**Repository Path**: tang-kan/ChatVasp

## Basic Information

- **Project Name**: ChatVasp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-09
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChatVasp

[![LangGraph](https://img.shields.io/badge/LangGraph-Powered-blue)](https://github.com/langchain-ai/langgraph)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-orange.svg)](https://www.python.org/downloads/)

[English](README.md) | **中文**

---

**ChatVasp** 是基于 **LangGraph** 和 **LangChain** 构建的下一代多智能体协作系统，专为 VASP 第一性原理计算打造的自动化 Agent 平台。

## 项目愿景

ChatVasp 旨在通过 Agentic AI 将复杂的材料计算流程标准化、自动化。它不仅是一个由 LLM 驱动的问答助手，更是能够直接操作 VASP 输入/输出文件、提交作业、分析报错并自我修正的智能科研助理。

## 核心架构 (LangGraph)

ChatVasp 采用有向循环图 (StateGraph) 组织智能体协作，确保工作流的确定性与状态管理的统一性。

### 工作流拓扑

```mermaid
graph TD
    Start[User Request] --> Intent{Intent Agent}
    Intent -->|General Query| General[General Agent]
    Intent -->|VASP Task| Task[Task Agent]
    
    Task --> Inputs[Inputs Agent]
    Inputs --> Submit[Submit Agent]
    Submit --> Wait[Wait Node]
    Wait --> Review{Review Agent}
    
    Review -->|Success & More Tasks| Task
    Review -->|Success & Finished| End[End]
    Review -->|Failure & Retry| Task
    Review -->|Fatal Error| End
    
    subgraph Inputs Workflow
    Inputs --> Poscar[POSCAR Agent]
    Poscar --> Potcar[POTCAR Agent]
    Potcar --> Kpoints[KPOINTS Agent]
    Kpoints --> Incar[INCAR Agent]
    end
```

### 智能体分工

| 智能体 | 职责描述 | 核心工具 |
| :--- | :--- | :--- |
| **INTENT_AGENT** | 意图识别，将用户请求分类为通用问答或 VASP 任务。 | 无 (纯推理) |
| **TASK_AGENT** | 任务规划，将复杂需求分解为标准的计算步骤（如 Relax -> SCF -> DOS）。 | `get_task_examples`, `file_system` |
| **POSCAR_AGENT** | 结构建模，负责晶体结构获取、超胞构建、掺杂改性等。 | `pymatgen` structure tools |
| **POTCAR_AGENT** |根据结构自动匹配赝势文件。 | `pymatgen` potcar tools |
| **KPOINTS_AGENT**| 根据任务京都要求生成 K 点网格。 | K-grid generation |
| **INCAR_AGENT** | 生成计算参数文件，根据精度自动设定 ENCUT/EDIFF 等。 | `get_incar_examples` |
| **SUBMIT_AGENT** | 作业提交，自动检测并支持 **local/pbs/torque/slurm** 四种运行模式。 | `job_tools` |
| **REVIEW_AGENT** | 结果检查与错误修复，以及**后处理（如画图）**。 | `python code exec`, `file_system` |

## 系统特性

- **全局状态管理 (`ChatVaspState`)**: 摒弃文件传递，所有上下文（任务列表、文件路径、作业 ID）均在 Graph State 中流转。
- **动态 Prompt 中间件**: 支持运行时动态注入任务示例和环境上下文，大幅提升 Agent 的指令遵循能力。
- **环境自适应**: 自动检测本地或集群环境，调整作业提交策略。
- **LangSmith 集成**: 通过 **LangSmith / LangGraph Studio** 提供全链路的可观测性、调试追踪和交互界面。

## 快速开始

### 1. 环境准备

推荐使用 `uv` 进行依赖管理：

```bash
# 安装项目依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows
```

### 2. 配置密钥

复制配置文件并填入 DeepSeek/OpenAI API Key、Materials Project API Key 以及 **LangSmith Key**：

```bash
cp .env.example .env
```

确保 `.env` 包含 LangChain 追踪配置：
```env
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langchain_api_key
```

### 3. 启动应用 (LangGraph Studio)

本项目已配置 LangGraph Studio 支持。

```bash
# 启动 LangGraph 开发服务器
langgraph dev
```

打开本地 LangGraph Studio 链接（通常为 `http://localhost:2024`）即可与 Agent 进行交互。

## 技术栈

- **框架**: [LangGraph](https://github.com/langchain-ai/langgraph) & [LangChain](https://github.com/langchain-ai/langchain)
- **可观测性与 UI**: [LangSmith](https://smith.langchain.com/)
- **材料计算**: [Pymatgen](https://github.com/materialsproject/pymatgen)

## License

MIT