<p align="center">
<img src="logo.png" alt="SeismicX logo" width="180"/>
</p>
<h1 align="center">SAGE — Seismology AI-Guided Engine</h1>
<p align="center">
Conversational AI Platform for Seismology Research
</p>
<p align="center">
<img src="https://img.shields.io/badge/Python-3.9--3.12-blue" alt="Python"/>
<img src="https://img.shields.io/badge/Framework-Flask-lightgrey" alt="Flask"/>
<img src="https://img.shields.io/badge/LLM-Ollama%20%7C%20OpenAI%20Compatible-green" alt="LLM"/>
<img src="https://img.shields.io/badge/RAG-BGE--M3%20%2B%20FAISS-orange" alt="RAG"/>
<img src="https://img.shields.io/badge/License-GPLv3-blue" alt="License"/>
</p>
---
SAGE is a **web-first** AI workbench for seismology and geophysics. It brings chat-based Q&A, scientific analysis, parameter optimization, knowledge-base retrieval, OpenAI-style SKILLs, code execution, GMT/Python plotting, and paper writing into one interface. Users can upload data, papers, and notes, then let the system infer file roles, plan scientific questions, generate figures and tables, integrate evidence, and produce reproducible reports, Markdown papers, and LaTeX drafts.
The command-line tool `seismic_cli.py` is still available, but it is now mainly a scripting, batch-processing, and debugging interface. Daily workflows are best handled through the web UI.
---
## Start Here: One-Command Launch With `sagectl.sh`
For most users, `sagectl.sh` is the only command you need to remember. It checks the Python environment, installs missing dependencies when needed, preserves your last selected LLM backend, starts the SAGE web app in the background, and opens the browser.
```bash
git clone --recurse-submodules https://github.com/cangyeone/sage.git
cd sage
chmod +x sagectl.sh
./sagectl.sh
```
Open the web UI at:
```text
http://127.0.0.1:5010
```
### What `sagectl.sh` Does
- Finds a supported Python environment, preferring Python 3.9-3.12.
- Installs required dependencies into `.venv/` if the current environment is not ready.
- Runs lightweight backend configuration without interrupting startup for knowledge-base rebuild prompts.
- Keeps your previous backend choice, such as DeepSeek, instead of switching to Ollama just because Ollama is running.
- Starts `web_app/app.py` as a background service and writes logs to `.sage_runtime/logs/`.
- Stores SAGE runtime data in the project-local `.seismicx/` directory, including config, run records, local model paths, workflows, and knowledge metadata.
### Daily Commands
```bash
./sagectl.sh # setup if needed, configure, start, open browser
./sagectl.sh status # show service status, URL, runtime dir, and log path
./sagectl.sh logs # tail the web server log
./sagectl.sh stop # stop the background web app
./sagectl.sh start # start the background web app
./sagectl.sh restart # restart the web app
./sagectl.sh open # open the web UI in your browser
./sagectl.sh doctor # check Python, dependencies, port, and backend status
```
### Useful Options
Use another port:
```bash
SAGE_PORT=5011 ./sagectl.sh
```
Run without opening a browser:
```bash
SAGE_AUTO_OPEN=0 ./sagectl.sh
```
Choose script output language. English is the default:
```bash
./sagectl.sh --lang en
./sagectl.sh --lang zh
SAGE_LANG=zh ./sagectl.sh
```
Use a custom project runtime directory. By default this is `.seismicx/` inside the repository:
```bash
SAGE_HOME=/path/to/project/.seismicx ./sagectl.sh
```
If you use local Ollama models:
```bash
./sagectl.sh ollama-start
ollama pull qwen3:8b
```
SAGE is web-first: after the service is running, use `/chat`, `/knowledge`, `/skills`, `/llm-settings`, `/science-analysis-agent`, and `/parameter-optimization-agent` from the browser.
---
## Table of Contents
- [Start Here: One-Command Launch With `sagectl.sh`](#start-here-one-command-launch-with-sagectlsh)
- [Features Overview](#features-overview)
- [System Architecture](#system-architecture)
- [Software Structure Documentation](#software-structure-documentation)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuring LLM Backend](#configuring-llm-backend)
- [Web Interface](#web-interface)
- [Project Coding Workspaces](#project-coding-workspaces)
- [Built-in Coding Agent](#built-in-coding-agent)
- [Desktop GUI Control](#desktop-gui-control)
- [Command Line Tools (Advanced/Fallback)](#command-line-tools-advancedfallback)
- [Conversation Routing Mechanism](#conversation-routing-mechanism)
- [seismo\_skill Skill System](#seismo_skill-skill-system)
- [seismo\_script Workflow System](#seismo_script-workflow-system)
- [GMT Map Drawing](#gmt-map-drawing)
- [Core Modules Details](#core-modules-details)
- [Directory Structure](#directory-structure)
- [Configuration Files](#configuration-files)
- [FAQ](#faq)
- [Acknowledgements](#acknowledgements)
- [Contact](#contact)
- [License](#license)
---
## Features Overview
| Module | Current Role | Core Capabilities |
|------|--------------|-------------------|
| **Chat** | Everyday entry point | Streaming chat, temporary PDF reading, RAG Q&A, web search, image/table understanding, project-aware code execution, GMT/Python plotting, and multi-SKILL use |
| **Scientific Analysis Agent** | Main research entry point | Traverses project folders, identifies data/papers/notes, searches local and online literature, proposes scientific questions, plans figures/tables, runs CodeEngine, and drafts Markdown/LaTeX papers |
| **Parameter Optimization Agent** | Workflow/model optimization | Lets users define modules, inputs/outputs, parameters, and objectives; LLM understands the workflow while CodeEngine implements, debugs, monitors, and saves optimization traces |
| **Knowledge Base** | Persistent knowledge layer | Ingests PDFs, Markdown, projects, and chat exports; combines BGE-M3/FAISS or fallback retrieval with keyword search; supports deletion and incremental updates |
| **Skill System** | Capability extension | Supports OpenAI-style folder SKILLs, built-in SKILLs, documentation-generated SKILLs, and academic research SKILLs; usable by Chat, Science Analysis, Parameter Optimization, and CodeEngine |
| **CodeEngine** | Execution and debugging core | Generates Python/GMT/Bash scripts, edits project files, runs unit/full tests, performs self-debug loops, and saves figures, tables, logs, and engineering plans |
| **LLM/Config** | Global settings | Configures Ollama, local models, online APIs, OpenAI-compatible APIs, web search providers, workspaces, coding backends, and multimodal capabilities |
| **Seismology Toolkits** | Domain tools | Phase picking, event association, polarity analysis, b-value statistics, waveform processing, GMT maps, and 3D terrain/velocity visualization |
---
## System Architecture
```
┌──────────────────────────────────────────────────────────────────────┐
│ Web UI │
│ /chat /science-analysis-agent /parameter-optimization-agent │
│ /knowledge /skills /config │
└───────────────┬──────────────────────────────────────────────────────┘
│ REST + SSE streaming
┌───────────────▼──────────────────────────────────────────────────────┐
│ Agent Orchestration │
│ intent routing · project isolation · background jobs · stop/resume │
│ evidence tracking · reviewer-style iteration · multilingual prompts │
└───────┬───────────────┬──────────────────┬──────────────────────────┘
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌────────▼────────┐
│ CodeEngine │ │ RAG/Search │ │ Skill Loader │
│ Python/GMT │ │ BGE-M3/FAISS│ │ OpenAI-style │
│ Bash/LaTeX │ │ keywords │ │ built-in/user │
│ mini tests │ │ OpenAlex... │ │ nested subskills│
└───────┬──────┘ └──────┬──────┘ └────────┬────────┘
│ │ │
┌───────▼───────────────▼──────────────────▼──────────────────────────┐
│ LLM Backends │
│ Ollama · OpenAI-compatible APIs · DeepSeek · SiliconFlow · DashScope │
│ optional multimodal models for figure/table/image analysis │
└───────┬──────────────────────────────────────────────────────────────┘
│
┌───────▼──────────────────────────────────────────────────────────────┐
│ Domain Toolkits │
│ pnsn phase picking · GMT · ObsPy · statistics · document extraction │
│ science paper templates · parameter optimization workflows │
└──────────────────────────────────────────────────────────────────────┘
```
---
## Software Structure Documentation
The detailed software architecture and built-in coding-agent contract live in
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). That document explains the
Chat/RAG/SKILL/CodeEngine layers, the engineering-plan flow, persisted
`engineering_plan.md` files, debug-time plan revisions, and the unit-test
validation rules used by the coding agent. CodeEngine artifacts are registered
with their conversation; deleting a conversation or project cleans up recognized
CodeEngine temporary run directories and related `engineering_plan*.md` files.
---
## Quick Start
```bash
# 1. Clone the main repository and bundled submodules
git clone --recurse-submodules https://github.com/cangyeone/sage.git
cd sage
# If you already cloned without submodules, run:
# git submodule update --init --recursive
# 2. One-command setup: install dependencies, configure, start the web app in background
chmod +x sagectl.sh
./sagectl.sh
```
The default URL is `http://127.0.0.1:5010`. On first access, select or enter a model on the **Config page**, then save it to start using the full system.
Common controls:
```bash
./sagectl.sh status # Show web, port and log status
./sagectl.sh logs # Tail background logs
./sagectl.sh stop # Stop the background web app
./sagectl.sh start # Start it again
./sagectl.sh restart # Restart
```
Use another port:
```bash
SAGE_PORT=5011 ./sagectl.sh start
```
If you use local Ollama:
```bash
./sagectl.sh ollama-start
ollama pull qwen3:8b
```
Manual fallback:
```bash
pip install -r requirements.txt
python web_app/app.py --port 5010
```
---
## Installation
### System Requirements
| Resource | Minimum Requirements | Recommended Configuration |
|------|---------|---------|
| **Operating System** | macOS / Linux / Windows | macOS 13+ / Ubuntu 22.04+ |
| **Python** | 3.9 | 3.10 / 3.11 / 3.12 (avoid 3.13+ for now) |
| **Memory (RAM)** | 8 GB | 16 GB+ (for running local LLM) |
| **Storage Space** | 5 GB | 30 GB+ (models + knowledge base) |
| **GPU** | Optional | CUDA 11.8+ or Apple Metal (for accelerated inference) |
### Basic Installation
```bash
git clone https://github.com/cangyeone/sage.git
cd sage
# Complete installation (recommended)
pip install -r requirements.txt
# Or install parts on demand
pip install flask flask-cors # Web services
pip install obspy torch scipy numpy pandas # Seismic data processing
pip install matplotlib plotly # Visualization
pip install FlagEmbedding faiss-cpu pdfminer.six PyMuPDF # RAG Knowledge Base
```
### pnsn Phase Picking Module Location
pnsn is a deep learning model library specifically for phase picking, developed by [cangyeone](https://github.com/cangyeone). In SAGE, pnsn is managed as part of the OpenAI-style skill `pnsn_phase_detection`; the expected location is `seismo_skill/skills/pnsn_phase_detection/pnsn/`, so the code, configuration, and model files stay with the skill.
```bash
# Only needed if the skill-local pnsn folder is missing
git clone https://github.com/cangyeone/pnsn.git \
seismo_skill/skills/pnsn_phase_detection/pnsn
```
The current pnsn repository does not provide a separate `requirements.txt` and does not need to be installed as a Python package for SAGE usage. Install SAGE's top-level dependencies with `pip install -r requirements.txt`; SAGE then directly calls files such as `seismo_skill/skills/pnsn_phase_detection/pnsn/picker.py`, `fastlinker.py`, and `pickers/*.jit`.
**Directory Structure Confirmation:**
```
sage/
├── seismo_skill/
│ └── skills/
│ └── pnsn_phase_detection/
│ ├── SKILL.md
│ └── pnsn/ ← Skill-local pnsn code and models
│ ├── picker.py
│ ├── fastlinker.py
│ ├── gammalink.py
│ ├── pickers/ ← JIT / ONNX model files
│ └── config/
├── web_app/
└── ...
```
Main models provided by pnsn:
| Model | Purpose | Format |
|------|------|------|
| **PhaseNet** | P/S wave arrival picking | JIT / ONNX |
| **EQTransformer** | Event detection + phase picking integration | JIT / ONNX |
| **JMA Picker** | Picker based on JMA algorithm | JIT |
### RAG Dependencies
Knowledge base RAG functionality requires the `tokenizers` library, which on some systems requires Rust compilation environment:
```bash
# Install Rust (only needed when pip install reports compilation errors)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
# Reinstall embedding models library
pip install FlagEmbedding sentence-transformers
# On first use, BGE-M3 model (~2 GB) will automatically download from HuggingFace.
# If HuggingFace fails and `modelscope` is installed, SAGE automatically tries
# ModelScope and stores the model at open_models/bge-m3.
# Domestic network can also set mirror:
export HF_ENDPOINT=https://hf-mirror.com
```
#### Alternative: Download BGE-M3 via ModelScope (recommended for users in China)
If HuggingFace is inaccessible, install ModelScope. SAGE will then automatically try the fallback download. You can also download the model manually:
```bash
pip install modelscope
modelscope download --model BAAI/bge-m3 --local_dir open_models/bge-m3
```
Then configure the local path in SAGE so it uses the downloaded model instead of downloading from the internet. There are two ways:
**Option 1 — Web Interface** (Recommended):
Open the **Knowledge Base page** (`/knowledge`) → click the ⚙ gear icon next to "Embedding Model" → paste the absolute path (e.g. `/Users/yourname/open_models/bge-m3`) → click Save.
**Option 2 — Edit config directly**:
Add an `embedding` section to `~/.seismicx/config.json`:
```json
{
"llm": { "...": "..." },
"embedding": {
"model_path": "/Users/yourname/open_models/bge-m3"
}
}
```
Leave `model_path` as an empty string or omit the field entirely to revert to HuggingFace auto-download. The setting takes effect on the next document build — no restart required.
---
## Configuring LLM Backend
All AI functions require an LLM backend. The recommended path is **Web Interface → Config**, where you can configure local models, online APIs, web search providers, coding backends, and workspaces. Project-related settings are stored in the project directory when possible, making them easy to move or clean up; only a small set of user defaults is maintained globally.
### Method 1: Ollama (Recommended, local, no internet required)
```bash
# 1. Install Ollama
# macOS / Linux:
curl -fsSL https://ollama.ai/install.sh | sh
# Or visit https://ollama.ai/download
# 2. Start service
ollama serve
# 3. Pull model (select based on VRAM / Memory)
ollama pull qwen3:8b # ~6 GB, suitable for daily use
ollama pull qwen3:30b # ~20 GB, comprehensive capabilities
ollama pull deepseek-r1:8b # ~9 GB, strong reasoning capability
ollama pull llama3.3:latest # ~40 GB, strong English capability
```
Select the model on the Config page and click "Save Configuration" to complete setup.
### Method 2: Online API (OpenAI Compatible Format)
On the Config page → select "Custom API" and fill in:
| Field | Example (DeepSeek) | Example (SiliconFlow) |
|------|----------------|-------------------|
| **API Base URL** | `https://api.deepseek.com/v1` | `https://api.siliconflow.cn/v1` |
| **API Key** | `sk-xxxxxxxx` | `sk-xxxxxxxx` |
| **Model Name** | `deepseek-chat` | `Qwen/Qwen2.5-72B-Instruct` |
Supports any OpenAI compatible interface, including DeepSeek, SiliconFlow, Moonshot (Moonshot), Alibaba Tongyi (DashScope), Zhipu GLM, Anthropic, etc.
### Method 3: Command Line Configuration
```bash
# Ollama local model
python seismic_cli.py backend use ollama --model qwen3:30b
# Online API
python seismic_cli.py backend use online \
--provider deepseek \
--api-key sk-xxx \
--model deepseek-chat
# View all backend status
python seismic_cli.py backend status
# Auto-detect available backends
python seismic_cli.py backend auto
```
---
## Web Interface
After startup, visit `http://127.0.0.1:5010`. The web UI is the recommended primary entry point because it supports background jobs, real-time streaming, isolated chats/projects, persistent files, rich figure rendering, and bilingual UI.
### Chat (/chat)
Use Chat for daily Q&A, paper reading, quick plotting, and small data-processing tasks. It routes each request to QA, RAG, web search, SKILLs, or CodeEngine as needed. Long-running jobs can continue while you switch pages; returning to the chat shows accumulated output and resumes live streaming.
| Task | Example |
|------|---------|
| Paper Q&A | Upload a PDF, then ask “What are the core methods and equations?” |
| Data processing | “Bandpass this mseed file at 1-10 Hz and mark phase picks.” |
| GMT/Python plotting | “Draw a China topography map with GMT and put a red star at the center.” |
| Web research | “Search for current seismology foundation models and list the sources.” |
| Multi-SKILL use | “Use the GMT docs skill and 3D terrain skill to draw Sichuan terrain.” |
Uploaded chat files are temporary unless explicitly added to the knowledge base. Chats and projects can also be saved into the knowledge base for later retrieval.
## Project Coding Workspaces
Chat projects can be connected to a real local project directory. In the Chat sidebar:
1. Click **Projects → New** or select an existing project.
2. Click **Settings**.
3. Fill **Project path / coding workspace** with an absolute local directory, for example:
```text
/Users/you/Documents/GitHub/my-research-code
```
After this is set, executable coding requests in that project use the selected directory as the active workspace:
- Code search, file discovery, repo maps, and symbol lookup run inside the project path.
- Generated edit scripts modify files under that project directory, not the SAGE source tree.
- Unit tests and validation run with the project path as the working directory.
- External coding backends, when enabled, also receive the project path as their workspace.
- Each `chat session + project path` gets an isolated CodeEngine context, so different projects do not leak code history into each other.
If no project path is set, SAGE falls back to its own repository root, which is useful when you are developing SAGE itself.
Typical project prompts:
```text
帮我定位这个项目里读取 catalog 的代码，并给我修改建议。
实现一个 CSV catalog loader，写单元测试，然后运行相关测试。
重构这个项目的绘图模块，并跑全量测试。
Run the full test suite and fix any failures.
```
## Built-in Coding Agent
The built-in coding agent is designed for engineering-style work, not only one-off scripts. For repository tasks it follows this loop:
1. Search files with `rg`, build a compact repo/symbol map, and choose relevant files.
2. Write an `engineering_plan.md` that records route, files, API details, unit tests, and validation commands.
3. Generate an edit-and-test script that can modify multiple files.
4. Run the script, inspect failures, and debug with the same skill/RAG/API references.
5. Run validation:
- `py_compile` for changed Python files.
- Targeted `pytest` for changed or related tests.
- Full validation when explicitly requested, such as `全量测试`, `完整构建`, `all tests`, or `full build`.
6. Save generated figures, output files, code, debug traces, and engineering plans as downloadable artifacts.
The agent can add, update, insert, or delete focused tests when the task requires it. Test deletion is allowed only when the test is obsolete, asserts wrong behavior, or is replaced by equivalent or better coverage.
For simple requests such as “给我一个计算 b 值的程序”, SAGE may return a code draft without executing it. For requests such as “帮我运行 /data/catalog.csv 并计算 b 值” or “修改上一张图的标题”, SAGE routes to executable coding.
Full-project validation is conservative and uses common project conventions:
| Project type | Full validation command |
|-------------|-------------------------|
| Python project with `tests/` | `python -m pytest` |
| Node project with `package.json` | `npm test`, then `npm run build` |
Projects with custom build systems should include the desired command in the prompt or project shared prompt.
## Desktop GUI Control
SAGE includes a built-in GUI automation skill for tasks that explicitly need desktop control. Generated code can use:
```python
from seismo_code.gui_automation import (
backend_status, screenshot, click, drag, move_to,
type_text, hotkey, scroll, GuiAutomationError,
)
```
Supported actions include screenshots, coordinate clicks, dragging, typing, hotkeys, and scrolling. The backend is selected automatically:
- Preferred: optional `pyautogui`.
- macOS screenshot fallback: `screencapture`; mouse fallback: `cliclick` if installed.
- Linux X11 fallback: `xdotool`; screenshots via `gnome-screenshot` or ImageMagick `import`.
Notes:
- macOS may require Accessibility and Screen Recording permissions.
- Linux Wayland may block global mouse/keyboard automation.
- Browser pages should normally use browser automation rather than pixel clicks.
- Text/OCR clicking is not invented by the agent; when text targeting is unavailable, the agent should take a screenshot and use coordinates.
### Scientific Analysis (/science-analysis-agent)
This is the main page for “given data and papers, produce a scientific analysis.” Put data, papers, notes, scripts, and templates under one project directory; the agent recursively traverses the directory and infers file roles.
Core workflow:
1. Identify data, field notes, papers, existing figures, and LaTeX/Markdown templates.
2. Use local literature, the knowledge base, web search, and SKILLs to propose testable scientific questions.
3. Let the LLM plan paper figures, tables, statistics, and falsification paths.
4. Run CodeEngine to parse data, compute statistics, draw figures, and debug failures.
5. Draft a Markdown paper from figures and evidence; optionally generate LaTeX/PDF.
6. Run strict reviewer-style self-critique loops to add/remove figures and refine claims.
Scientific Analysis is intended to move beyond data-quality summaries and organize work around “question → evidence → figures/tables → paper conclusions.”
### Parameter Optimization (/parameter-optimization-agent)
Use this page to define optimizable workflows such as phase-picking model training, signal-processing parameter search, inversion parameter tuning, or custom scientific pipelines. Users define inputs, outputs, tunable parameters, and objectives; the LLM interprets the workflow while CodeEngine implements, runs, debugs, and monitors it. Optimization traces and results can feed back into Scientific Analysis.
### Knowledge Base (/knowledge)
The knowledge base stores long-term retrievable materials: PDFs, Markdown documents, chat/project exports, scientific-analysis projects, and SKILL/RAG helper indexes generated from documentation. Retrieval combines vector search and keyword search; Chinese text can use jieba tokenization. BGE-M3 is preferred for embeddings, with lightweight fallback when unavailable.
Deletion and incremental updates are supported. Removing an item also cleans related RAG entries, project records, and generated SKILL links where applicable.
### Skills (/skills)
The skill system uses OpenAI-style folder SKILLs and supports built-in skills plus user skills under `seismo_skill/user_skills/`. Files or folders under `seismo_skill/docs/` can be converted into skills through the web UI. For large documentation sets, SAGE can first use RAG/vector clustering to group similar content into `subskills/`, then ask an LLM to standardize the notes, examples, and constraints.
Skills can be jointly used by Chat, Scientific Analysis, Parameter Optimization, and CodeEngine. Failed or obsolete generated skills can be deleted from the UI.
#### SeismicX-Cont Continuous Monitoring Skill
SAGE includes the OpenAI-style skill `continuous_seismic_monitoring` for the `publish_mini` continuous-waveform benchmark code. Large waveform data, picker weights, and generated benchmark outputs are intentionally not committed. Download the SeismicX-Cont data from [ModelScope](https://www.modelscope.cn/datasets/cangyeone/SeismicX-Cont), then place it under `publish_mini/data/` or inside your project data directory.
The skill provides three skill-local workflows that can be invoked from Chat, Scientific Analysis, Parameter Optimization, and CodeEngine:
- `continuous_dataset_build`: convert user-provided waveform/catalog/station inputs into a continuous waveform dataset with HDF5/SQLite indexes.
- `continuous_picker_benchmark`: run a provided picker, evaluate phase-pick precision/recall, optionally associate events, and report earthquake recall statistics.
- `continuous_waveform_detection`: run continuous earthquake detection on waveform windows using the dataset/index artifacts from the dataset workflow.
Example prompts:
```text
Use the continuous seismic monitoring workflow to build a continuous waveform dataset from my project data.
Benchmark this PhaseNet picker on the SeismicX-Cont mini dataset and report P/S recall plus event association recall.
Use the continuous waveform detection workflow to detect earthquakes from the continuous data in this project.
```
### Config (/config)
The Config page manages models and system capabilities:
- Ollama, local models, online OpenAI-compatible APIs.
- DeepSeek, SiliconFlow, DashScope, Moonshot/Kimi, Zhipu, and custom APIs.
- Web search providers such as OpenAlex, Semantic Scholar, arXiv, and custom services.
- Chat/agent workspaces, extra authorized roots, coding backends, and multimodal capabilities.
- Thinking visibility, RAG, web search, and figure/table parsing switches.
---
## Command Line Tools (Advanced/Fallback)
`seismic_cli.py` remains available, but it is now intended for scripting, batch jobs, and debugging. For normal interaction, scientific analysis, parameter optimization, knowledge management, and skill management, use the web UI first.
Common commands:
```bash
# Inspect or auto-select model backend
python seismic_cli.py backend status
python seismic_cli.py backend auto
# Lightweight chat/code entry points
python seismic_cli.py chat
python seismic_cli.py run "bandpass /data/wave.mseed at 1-10 Hz and plot it"
# Batch phase picking and event association
python seismic_cli.py pick -i /data/seismic/2024/ --batch -o results/picks.csv
python seismic_cli.py associate -i results/picks.csv -s station_list.csv --method fastlink -o results/events.txt
# Seismic statistics scripts
python seismic_cli.py stats bvalue -i catalog.csv --mc auto
python seismic_cli.py stats report -i catalog.csv
```
Use the root launcher for the web service:
```bash
./sagectl.sh # install deps, configure, start in background
./sagectl.sh status # show status
./sagectl.sh logs # tail logs
./sagectl.sh stop # stop web service
```
---
## Conversation Routing Mechanism
SAGE determines message intent primarily through a dedicated LLM router, not broad QA keyword rules. QA is deliberately low-priority: requests that create, modify, run, plot, test, or continue a previous coding result are routed to CodeEngine even if they contain words such as "how", "注意", "支持", or "explain".
### Routing Flow
```
User message
│
├─ Explicit execution/artifact/refinement guard
│ ├─ paths, plotting, processing, GUI control, or file generation → code
│ └─ previous CodeEngine result + "modify/refine/support/change" → code
│
└─ LLM routing call (max_tokens=10, approximately <1s)
│
├─ code_draft → write code only, without execution
├─ code → CodeEngine generates and executes Python / GMT code
├─ chain → paper-method extraction followed by implementation
├─ qa → RAG retrieves knowledge base + LLM response
└─ chat → General conversation
```
### Routing Types
| Route | Trigger Condition | Example |
|------|---------|------|
| `code_draft` | User only asks for a program/script and does not ask SAGE to run it | "给我一个计算 b 值的程序" |
| `code` | Data processing, plotting, file operations, GUI control, repo edits, tests, builds | "帮我用 Python 绘制中国地形图", "把上一张图标题改成中文", "运行全量测试并修复失败" |
| `chain` | Uploaded paper/literature method reproduction | "复现这篇论文的方法并实现代码" |
| `qa` | Explicit concept explanation, summary, or method discussion with no requested output change | "What is Q-filter?", "Explain the principle of HVSR" |
| `chat` | Greetings, chatting, non-seismological content | "Hello", "How is the weather today" |
**Fallback rules when LLM routing is unavailable:**
- Strong code guards still route to `code`: paths, artifact creation, GUI control, or refinement of a previous CodeEngine result.
- Otherwise SAGE falls back to `chat`, not QA. This avoids accidentally turning code/figure modification requests into explanatory answers.
---
## seismo_skill Skill System
The skill system is SAGE's core extension mechanism. Each skill is a Markdown document describing function usage and code examples. **Skills documents are automatically retrieved and injected during AI conversation and code generation**, significantly improving the accuracy and standardization of generated code.
### Working Principle
```
User message (natural language)
│
▼
seismo_skill keyword retrieval
(Chinese-English mixed TF-IDF scoring)
│
├─ Matched skill → inject function signature + example code into LLM system prompt
│
▼
LLM generates code / responds
(prioritizes standardized writing in skill documents)
```
Retrieval points integrated into:
- `/api/chat/rag` (Web knowledge Q&A)
- `seismo_code/code_engine.py` (code generation engine)
- `seismo_agent/agent_loop.py` (autonomous agent code generation at each step)
### Built-in Skills
Built-in skills now use the OpenAI-style folder format: each skill directory contains `SKILL.md` and may include `agents/`, `references/`, `assets/`, `workflows/`, and `subskills/`.
| Skill Directory | Main Use |
|-----------------|----------|
| `waveform_io/` | Waveform file reading, directory scanning, metadata extraction |
| `waveform_processing/` | Detrending, tapering, filtering, resampling, response removal |
| `waveform_visualization/` | Waveform plots, spectrograms, PSD, particle motion |
| `spectral_analysis/` | Spectrum, HVSR, spectral ratios, and frequency-domain analysis |
| `b_value_analysis/` | b-value, magnitude completeness, G-R relation, seismicity statistics |
| `source_parameters/` | Magnitude, corner frequency, seismic moment, moment magnitude, stress drop |
| `gmt_plotting/` | GMT maps, topography, epicenters, sections, and focal mechanisms |
| `terrain_3d_plotting/` | Python/Plotly/Three.js-style 3D terrain visualization |
| `pnsn_phase_detection/` | PhaseNet/EQTransformer phase picking and monitoring workflows |
| `tabular_io/` | CSV/Excel/text table reading and field inference |
| `cartopy_plotting/` | Cartopy map plotting fallback |
| `nature-figure/`, `nature-data/`, `nature-polishing/` | Academic figures, data organization, and paper polishing |
### Creating Custom Skills
**Method 1: Web Interface** (Recommended)
Visit `/skills` → Click "Create Custom Skill" → Fill in basic information → Complete documentation in editor.
**Method 2: Command Line**
```bash
python seismic_cli.py skill new my_hypodd_tool \
--title "HypoDD Double Difference Location Tool" \
--keywords "double difference location, HypoDD, precise location, relocation" \
--desc "Package HypoDD input file generation and result parsing"
```
**Method 3: Write an OpenAI-style skill folder directly**
Create `SKILL.md` under `seismo_skill/user_skills/<skill_name>/`:
```text
seismo_skill/user_skills/my_skill/
├── SKILL.md
├── subskills/
│ └── station_metadata.md
├── references/
│ └── example_catalog.md
└── agents/
└── debug_notes.md
```
Recommended `SKILL.md` sections:
```markdown
# Skill Title / 技能标题
## When to use / 何时使用
## Inputs and outputs / 输入与输出
## Workflow / 工作步骤
## Examples / 代码示例
```
> **Override Rules:** When custom skill has same name as built-in skill, custom version takes priority automatically.
### Building Documentation and Skills
SAGE can convert external documentation into OpenAI-style folder skills. The typical workflow is: put a documentation folder under `seismo_skill/docs/`, open the web Knowledge page, choose a skill structure, and let the Skill Builder create a reusable skill under `seismo_skill/user_skills/`.
#### Example: Build a GMT Documentation Skill
1. **Download GMT Chinese documentation**
Download a release archive from [gmt-china/GMT_docs releases](https://github.com/gmt-china/GMT_docs/releases). Prefer a release archive that contains the built source files, examples, and documentation assets.
You can also download from the terminal, replacing `<release-asset-url>` with the asset URL from the release page:
```bash
cd /path/to/sage
mkdir -p seismo_skill/docs
curl -L "<release-asset-url>" -o /tmp/GMT_docs.zip
unzip /tmp/GMT_docs.zip -d seismo_skill/docs/
```
Make sure the final layout is a single documentation folder, for example:
```text
seismo_skill/docs/GMT_docs-6.5/
source/
README.md
...
```
2. **Start SAGE Web**
```bash
python web_app/app.py --port 5010
```
Open `http://localhost:5010/knowledge`.
3. **Generate the SKILL in the web UI**
In the **Skill Docs Directory** card:
- Click refresh and select `GMT_docs-6.5`.
- Set **SKILL structure** to **OpenAI-style folder SKILL**.
- Enable **RAG/vector-assisted build** if the folder has many files. This uses retrieval and clustering only as build assistance; the final result is still a SKILL, not a permanent RAG index.
- Optionally set the target topic cluster count. Leave it blank to let SAGE suggest one automatically.
- Click **Start Build**.
4. **Generated output**
The generated skill is written to:
```text
seismo_skill/user_skills/_gen_gmt_docs_zh/
SKILL.md
subskills/
references/
workflows/
agents/
```
The top-level `SKILL.md` is the entry point. The `subskills/` directory contains clustered reusable GMT subskills, and `references/manifest.md` records the source files used during construction.
5. **Verify the generated SKILL is used**
Ask in Chat or Code mode:
```text
GMT 的 -J 投影选项怎么用？给我几个常见投影示例。
```
```text
用 GMT grdimage 绘制地形图，并添加 colorbar，解释参数。
```
You do not need to explicitly mention `_gen_gmt_docs_zh`; GMT-related keywords such as `GMT`, `grdimage`, `makecpt`, `coast`, `-J`, `-R`, and `-B` should automatically retrieve the generated documentation skill together with the built-in `gmt_plotting` skill.
6. **Manage or delete generated skills**
Generated skills appear in the Knowledge/Skill management UI as skill assets and can be deleted from there. Deletion removes both the generated SKILL folder and its build metadata.
Supported documentation formats include PDF, Markdown (`.md`), reStructuredText (`.rst`), HTML, plain text, scripts, and mixed documentation folders.
#### Academic Research Skills
SAGE vendors [academic-research-skills](https://github.com/Imbad0202/academic-research-skills) under:
```text
third_party/academic-research-skills/
```
The bundled OpenAI-style skills include:
- `deep-research` — literature-grounded research planning and evidence synthesis
- `academic-paper` — academic manuscript drafting and revision
- `academic-paper-reviewer` — reviewer-style critique and revision guidance
- `academic-pipeline` — end-to-end research workflow planning
Install or refresh them from the web backend:
```bash
curl -X POST http://localhost:5010/api/skills/install-academic-research \
-H "Content-Type: application/json" \
-d '{"overwrite": true}'
```
After installation, Chat, Science Analysis, and CodeEngine can retrieve these skills automatically. You usually do not need to name a skill explicitly; research-oriented prompts such as "review this paper", "design a literature-backed study", or "write a JGR-style draft" should retrieve the relevant academic skills and combine them with local seismology skills and RAG.
### Science Analysis and Parameter Optimization
The old geologic-interpretation page and `/api/evidence_geo_agent*` APIs have been removed. The legacy `/evidence-geo-agent` URL now redirects to the Science Analysis page:
```text
http://localhost:5010/science-analysis-agent
```
For modular optimization workflows, use the Parameter Optimization Agent at:
```text
http://localhost:5010/parameter-optimization-agent
```
The optimizer is meant for workflows where the user defines modules, module inputs/outputs, tunable parameters, and the final objective. The agent then asks CodeEngine to inspect the project folder, generate and debug scripts, run smoke tests, perform a bounded optimization or dry run, and save:
- `optimization_plan.md`
- `best_parameters.json`
- `optimization_history.csv`
- figures and logs
- `optimization_report.md`
All outputs stay inside the selected project directory, so Science Analysis can later reuse the optimization trace, figures, and report when drafting a paper.
#### Building Progress Monitoring
The build process runs in the background and provides real-time progress updates:
- **Scanning Phase**: Detects new/modified/deleted files
- **Indexing Phase**: Processes documents and builds vector embeddings
- **Skill Generation Phase**: Creates skill documents from indexed content
- **Completion**: Updates knowledge base statistics
You can monitor progress through the web interface or check logs in the terminal.
---
## seismo_script Workflow System
The workflow system lets you define multi-step analysis pipelines as declarative `.md` files. Each workflow specifies which skills to load, which steps to execute, and how those steps depend on each other. The Code Engine handles all code generation and execution — the workflow simply acts as the coordination blueprint.
### Role Distribution
| Role | Responsibility |
|------|---------------|
| **Workflow** | Process blueprint: what steps to run, which skills to use, in what order |
| **Skill** | Specialist manual: how to use a specific tool or method |
| **Agent** | Dispatcher: matches user request to workflow, loads skills, decomposes task |
| **Code Engine** | Programmer: generates and fixes Python/GMT/Shell code for each step |
| **Tool** | Executor: Python sandbox, GMT, Shell |
### Workflow File Format
Workflows use `.md` files with YAML frontmatter — the same format as skills:
```markdown
---
name: seismicity_analysis
title: Seismicity Analysis Workflow
version: "1.0"
description: Complete seismicity analysis including catalog loading, spatial/temporal distribution, and b-value estimation
keywords:
- seismicity
- b-value
- epicenter map
skills:
- name: tabular_io
role: catalog loading and parsing
- name: gmt_plotting
role: epicenter map rendering
- name: b_value_analysis
role: b-value estimation and GR plots
steps:
- id: load_catalog
skill: tabular_io
description: Load earthquake catalog from file
- id: epicenter_map
skill: gmt_plotting
description: Draw epicenter distribution map
depends_on: [load_catalog]
- id: b_value
skill: b_value_analysis
description: Calculate b-value and plot GR distribution
depends_on: [load_catalog]
---
## Seismicity Analysis Workflow Guide
Step 1: Load the catalog using `load_catalog_file()`...
```
**Frontmatter fields:**
| Field | Type | Description |
|-------|------|-------------|
| `name` | str | Workflow identifier |
| `title` | str | Human-readable title |
| `description` | str | One-line summary |
| `keywords` | list[str] | Used for relevance search |
| `skills` | list[{name, role}] | Required skills and their roles in this workflow |
| `steps` | list[{id, skill, description, depends_on}] | Execution DAG |
The Markdown body is the **workflow guide** — injected into the LLM context to direct code generation at each step.
### Storage
| Location | Contents |
|----------|----------|
| `seismo_script/workflows/` | Built-in workflows (shipped with SAGE) |
| `seismo_skill/skills/*/workflows/` | Built-in skill-local workflows, loaded with their owning skill package |
| `seismo_skill/user_skills/*/workflows/` | User/generated skill-local workflows, loaded with generated skills |
| Project-local `workflows/` | Web project workflows, recommended for reproducible studies and parameter optimization |
| `~/.seismicx/workflows/` | Legacy user workflows; new projects should prefer project-local storage |
### Built-in Workflows
| Workflow | Description | Skills |
|----------|-------------|--------|
| `gmt_terrain_map` | Full GMT terrain map pipeline (7 steps: CPT → DEM cut → render → coast → contours → scale/legend → export) | `gmt_plotting`, `_gen_gmt_docs_6_5` |
| `seismicity_analysis` | Seismicity analysis (catalog → epicenter map → time series → b-value → cross-section) | `tabular_io`, `gmt_plotting`, `b_value_analysis` |
| `continuous_dataset_build` | Build a continuous waveform dataset from user data, station/catalog metadata, and labels | `continuous_seismic_monitoring` |
| `continuous_picker_benchmark` | Evaluate a user-supplied picker with phase-pick and event-level recall/statistics | `continuous_seismic_monitoring` |
| `continuous_waveform_detection` | Detect earthquakes from continuous waveform data using dataset/index artifacts | `continuous_seismic_monitoring` |
### `CodeEngine.run_workflow()` API
```python
result: WorkflowRunResult = engine.run_workflow(
workflow_name = "seismicity_analysis",
user_request = "Analyze the 2024 catalog at /data/catalog.csv",
data_hint = "/data/catalog.csv", # optional path hint injected into step prompts
max_debug_rounds = 3, # retries per step on failure
timeout = 120, # per-step execution timeout (seconds)
skip_on_failure = False, # if True, skip failed steps instead of aborting
on_progress = callback_fn, # optional: called with progress dicts
)
```
`run_workflow()` topo-sorts the step DAG, then for each step:
1. Checks all `depends_on` predecessors have succeeded
2. Scans the shared execution directory for available output files
3. Calls `build_skill_context_with_rag()` for the step's declared skill
4. Generates code via LLM (skill context + completed-steps summary injected)
5. Executes code in a shared directory (so step N+1 can read files written by step N)
6. On failure: re-queries RAG with the error text appended, retries up to `max_debug_rounds`
7. Records a `StepResult` and appends it to the shared conversation history
**`WorkflowRunResult`:**
```python
@dataclass
class WorkflowRunResult:
workflow_name: str
steps: List[StepResult] # one entry per executed step
shared_dir: str # directory where all step output files live
total_time: float # total wall-clock time (seconds)
@property
def failed_steps(self) -> List[StepResult]: ...
@property
def skipped_steps(self) -> List[StepResult]: ...
```
**`StepResult`:**
```python
@dataclass
class StepResult:
step_id: str
skill: str
description: str
success: bool
code: str
stdout: str = ""
stderr: str = ""
figures: List[str] = field(default_factory=list)
output_files: List[str] = field(default_factory=list)
attempts: int = 1
diagnosis: str = ""
skipped: bool = False
```
### Web API
**Trigger a workflow run:**
```
POST /api/chat/workflow
Content-Type: application/json
{
"workflow_name": "seismicity_analysis",
"message": "Analyze the 2024 Sichuan catalog at /data/catalog.csv",
"session_id": "optional-session-id",
"data_hint": "/data/catalog.csv",
"skip_on_failure": false
}
Response: { "ok": true, "job_id": "wf_xxxx" }
```
**Poll for results** (same endpoint as single-step code jobs):
```
GET /api/chat/code/poll/<job_id>
Response (completed):
{
"status": "completed",
"result": {
"step_results": [
{ "step_id": "load_catalog", "success": true, "figures": [...], "stdout": "..." },
{ "step_id": "epicenter_map","success": true, "figures": ["/path/map.png"], "stdout": "" },
{ "step_id": "b_value", "success": false, "diagnosis": "mc too high", "attempts": 3 }
],
"shared_dir": "/tmp/sage_wf_xxxxx"
}
}
```
### Creating Custom Workflows
**Method 1: Web Interface** (Recommended)
Visit `/skills` → **Workflows** tab → Click "New Workflow" → Fill in metadata → Edit the Markdown guide body. The step DAG preview updates live as you edit the frontmatter.
**Method 2: Write `.md` File Directly**
Save to the current project's `workflows/<name>.md` using the frontmatter format shown above. Legacy `~/.seismicx/workflows/<name>.md` files are still readable, but new projects should stay self-contained.
---
## GMT Map Drawing
SAGE directly calls GMT6 through the `run_gmt()` utility function to generate professional-grade seismological maps.
### Installing GMT
```bash
# macOS
brew install gmt
# Linux (Conda environment)
conda install -c conda-forge gmt
# Linux (apt)
sudo apt install gmt
```
### Usage
Directly describe requirements in conversation, SAGE automatically generates and executes GMT script:
```
> Help me draw a Chinese topographic map with GMT
> Draw epicenter distribution map for 90-120°E, 20-45°N
> Draw station distribution map with GMT, data in /data/stations.txt
```
Or call in code (`run_gmt` is pre-injected, no import needed):
```python
gmt_script = """
gmt begin china_topo PNG
gmt grdcut @earth_relief_01m -R70/140/15/55 -Gtopo.grd
gmt grdimage topo.grd -JM16c -Cetopo1 -I+d
gmt coast -W0.5p,gray40 -N1/0.8p -Baf -BWSne+t"China Topographic Map"
gmt colorbar -DJBC+w8c/0.4c -Baf+l"Elevation (m)"
gmt end
"""
run_gmt(gmt_script, outname="china_topo", title="China Topographic Map")
```
### Automatic Chinese Title Processing
GMT's PostScript engine does not support CJK characters. SAGE automatically handles this issue:
1. Extract Chinese titles/labels from script before execution
2. Replace with empty placeholders, allowing GMT to render map content without garbled characters
3. After execution, overlay Chinese titles back onto PNG with matplotlib
> **User does not need to care about this detail**, just write Chinese titles directly in the script.
### Image and Script Download
Toolbar below each GMT image provides:
- **⬇ Image**: Download PNG file
- **⬇ GMT Script**: Download `.sh` script file, can independently run in terminal to completely reproduce the map
---
## Core Modules Details
### `seismo_script/` — Workflow System
```
seismo_script/
├── workflow_runner.py # Workflow discovery, search, CRUD, and context building
├── workflows/ # Built-in workflow .md files (gmt_terrain_map, seismicity_analysis, ...)
└── __init__.py # Public API: list_workflows, search_workflows, load_workflow,
# save_user_workflow, delete_user_workflow, build_workflow_context
```
**Public API summary:**
| Function | Description |
|----------|-------------|
| `list_workflows()` | Return all workflow metadata (no guide body) |
| `search_workflows(query, top_k)` | Rank workflows by keyword relevance |
| `load_workflow(name)` | Return full workflow entry including guide text |
| `save_user_workflow(name, text)` | Save a `.md` workflow into the project directory; legacy user storage remains readable |
| `delete_user_workflow(name)` | Delete a user-defined workflow |
| `build_workflow_context(query)` | Return `(context_str, skill_names)` for LLM injection |
### `seismo_code/` — Code Generation and Execution Engine
```
seismo_code/
├── code_engine.py # LLM code generation (skill injection, multi-round history, error retry,
│ # run_workflow() multi-step DAG execution)
├── safe_executor.py # Sandbox execution (independent subprocess, 120s timeout, automatic image collection)
├── toolkit.py # Built-in seismological utility functions (no import needed, direct call)
└── doc_parser.py # Extract context snippets related to code tasks from PDF
```
**Built-in Toolkit (`toolkit.py`, automatically injected during code execution):**
| Category | Functions |
|------|------|
| Data Reading | `read_stream`, `read_stream_from_dir` |
| Waveform Processing | `detrend_stream`, `taper_stream`, `filter_stream`, `resample_stream`, `trim_stream`, `remove_response` |
| Visualization | `plot_stream`, `plot_spectrogram`, `plot_psd`, `plot_particle_motion`, `plot_travel_time_curve` |
| Travel Time Calculation | `taup_arrivals`, `p_travel_time`, `s_travel_time` |
| Spectrum Analysis | `compute_spectrum`, `compute_hvsr` |
| Source Parameters | `estimate_magnitude_ml`, `estimate_corner_freq`, `estimate_seismic_moment`, `moment_to_mw`, `estimate_stress_drop` |
| GMT Plotting | `run_gmt` |
| Utility Functions | `stream_info`, `picks_to_dict`, `savefig` |
**Sandbox Execution Mechanism:**
- Code runs in independent subprocess, main process unaffected by crashes
- Timeout protection (default 120 seconds)
- Generated images automatically collected via `[FIGURE] /path` marker and sent to frontend
- GMT scripts separately collected via `[GMT_SCRIPT] /path` marker, for frontend download provision
### `seismo_agent/` — Autonomous Agent
Complete automatic implementation flow from literature to code:
```
seismo_agent/
├── paper_reader.py # Literature loading (PDF / arXiv ID / DOI / plain text)
├── memory.py # Cross-step work memory (literature content, step results, generated variables)
├── planner.py # LLM task planning (goal + literature summary → JSON step list)
└── agent_loop.py # Main loop (planning → code → execution → failure retry → summary)
```
Execution flow:
```
User goal + literature source (PDF / arXiv / DOI)
│
Load and extract core literature content
│
LLM plans execution steps (3–8 steps, JSON format)
│
┌─── Each Step ───────────────────────────┐
│ Retrieve relevant skill documents (seismo_skill) │
│ LLM generates code (skill context injection) │ ← Retry up to 2 times on failure
│ Sandbox secure execution │
│ Record results and generated images │
└──────────────────────────────────────┘
│ Loop through all steps
Summary report + output directory
```
### `web_app/rag_engine.py` — Knowledge Base RAG Engine
| Stage | Implementation |
|------|------|
| PDF Parsing | pdfminer.six (priority) / PyMuPDF (fallback) |
| Text Chunking | 500 chars/chunk, 50 char sliding overlap |
| Vectorization | BGE-M3 (1024 dimensions, L2 normalized, Chinese-English bilingual) |
| Indexing | FAISS `IndexFlatIP` (inner product = cosine similarity) |
| Retrieval | Top-K recall + similarity threshold filtering, only showing truly matched literature |
| Persistence | `~/.seismicx/knowledge/`, automatic load on startup; automatic cleanup of orphaned vectors from deleted files on startup |
| Fallback | Automatic downgrade to TF-IDF cosine similarity retrieval when BGE-M3 unavailable |
### `seismo_stats/` — Seismic Statistical Analysis
```
seismo_stats/
├── bvalue.py # Mc (maximum curvature / goodness-of-fit) + b-value (MLE / LSQ) + σ_b uncertainty
├── catalog_loader.py # Directory loading: CSV / JSON / picks.txt, automatic column name recognition
└── plotting.py # F-M distribution plots, temporal activity plots, epicenter distribution plots
```
### `seismo_tools/` — External Tool Registry
Unified management of third-party seismological tools such as HypoDD, VELEST, HASH. Supports automatic control file generation, calling external executables, parsing output results, and can be triggered via conversation commands.
---
## Directory Structure
```
sage/
├── web_app/ # Web service
│ ├── app.py # Flask main application (40+ API routes)
│ ├── rag_engine.py # BGE-M3 + FAISS knowledge base engine
│ ├── simple_rag.py # TF-IDF fallback RAG
│ ├── simple_vector_db.py # Lightweight vector database (pickle persistence)
│ └── templates/
│ ├── chat.html # Conversation page (main interface)
│ ├── knowledge.html # Knowledge base management
│ ├── skills.html # Skill management
│ └── llm_settings.html # LLM configuration
│
├── seismo_skill/ # Skill documentation system
│ ├── skill_loader.py # Parse, retrieve, inject (Chinese-English mixed retrieval)
│ ├── __init__.py
│ ├── waveform_io.md # Waveform reading
│ ├── waveform_processing.md # Waveform preprocessing
│ ├── waveform_visualization.md # Waveform visualization
│ ├── spectral_analysis.md # Spectrum analysis & HVSR
│ ├── b_value_analysis.md # b-value statistical analysis
│ ├── source_parameters.md # Source parameter estimation
│ ├── tabular_io.md # CSV / TXT data reading
│ └── gmt_plotting.md # GMT map drawing
│
├── seismo_script/ # Workflow system
│ ├── workflow_runner.py # Workflow discovery, search, CRUD, context building
│ ├── workflows/ # Built-in workflow .md files
│ │ ├── gmt_terrain_map.md # GMT terrain map 7-step pipeline
│ │ └── seismicity_analysis.md # Seismicity analysis pipeline
│ └── __init__.py
│
├── seismo_code/ # Code generation and execution engine
│ ├── code_engine.py # LLM code generation (multi-round history + error retry
│ │ # + engineering_plan.md + run_workflow() DAG execution)
│ ├── safe_executor.py # Sandbox execution (subprocess + timeout protection)
│ ├── toolkit.py # Built-in seismological utility functions
│ └── doc_parser.py # PDF content extraction
│
├── seismo_agent/ # Autonomous Agent
│ ├── agent_loop.py # Main loop (SeismoAgent class)
│ ├── planner.py # Task planning (TaskPlanner)
│ ├── memory.py # Work memory (AgentMemory)
│ └── paper_reader.py # Literature loading (load_paper)
│
├── seismo_stats/ # Seismic statistical analysis
│ ├── bvalue.py # b-value / Mc calculation
│ ├── catalog_loader.py # Earthquake catalog loading
│ └── plotting.py # Statistical chart plotting
│
├── seismo_tools/ # External tool registry
│ └── tool_registry.py # HypoDD / VELEST / HASH etc.
│
├── docs/
│ └── ARCHITECTURE.md # Software structure and coding-agent design contract
│
├── seismo_skill/
│ ├── skills/ # Built-in OpenAI-style skills
│ │ └── pnsn_phase_detection/
│ │ ├── SKILL.md
│ │ └── pnsn/ # Skill-local pnsn code and models
│ ├── user_skills/ # Web-generated/imported user skills
│ │ └── _gen_gmt_docs_zh/
│ │ ├── SKILL.md
│ │ └── subskills/
│ └── docs/ # Documentation sources convertible to RAG/SKILL
│
├── conversational_agent.py # Conversation Agent core (intent classification + skill execution)
├── config_manager.py # LLM configuration management
├── backend_manager.py # Multi-backend support (Ollama / vLLM / online API)
├── seismic_cli.py # Command line entry point
├── requirements.txt # Python dependencies
└── logo.png
.sage_runtime/ # Local background PID, logs, env info, and plan cache (git ignored)
seismo_rag/ # Project knowledge indexes and project_config.json
```
---
## Configuration Files
Configuration is split into project-level and user-level files. The web Config page maintains them automatically, so manual editing is usually unnecessary.
```json
{
"llm": {
"provider": "ollama",
"model": "qwen3:30b",
"api_base": "http://localhost:11434",
"api_key": ""
},
"workspace": {
"enabled": true,
"path": "/data/seismic"
}
}
```
Common locations:
- `seismo_rag/project_config.json`: project-level settings such as search providers, coding backend preferences, and SKILL/RAG helper options.
- `.sage_runtime/`: local PID files, logs, and transient runtime environment data; this directory is ignored by git.
- Scientific Analysis / Parameter Optimization project folders: project inputs, outputs, figures, logs, Markdown/LaTeX drafts, and optimization traces.
- `~/.seismicx/config.json`: a small set of user-level defaults, such as the default LLM backend.
| Field | Description | Optional Values |
|------|------|--------|
| `llm.provider` | LLM provider | `ollama` / `openai` / `custom` |
| `llm.model` | Model name | Ollama tag or API model name |
| `llm.api_base` | API endpoint address | `http://localhost:11434` (Ollama default) |
| `llm.api_key` | API key | Not required for Ollama |
| `workspace.enabled` | Whether to allow LLM to access local file lists | `true` / `false` |
| `workspace.path` | Authorized root directory (LLM cannot access content outside this path) | Absolute path string |
---
## FAQ
**Q: Conversation returns "No available LLM model configured"**
Go to `/config` to select an installed Ollama model, or configure an online API and click "Save Configuration".
**Q: English questions like "what is filter algorithm?" are incorrectly routed to code execution**
Fixed. SAGE uses LLM rather than keyword regex to determine intent, conceptual questions (containing technical terms like filter, spectrum) will be correctly routed to knowledge Q&A, not code execution.
**Q: Knowledge base PDF vectorization is slow after upload**
First run will download BGE-M3 model (~2 GB) from HuggingFace. Speed will be normal after completion. Domestic network can set mirror acceleration:
```bash
export HF_ENDPOINT=https://hf-mirror.com
```
If HuggingFace is completely inaccessible, install ModelScope (`pip install modelscope`) so SAGE can automatically download `BAAI/bge-m3` from ModelScope into `open_models/bge-m3`, or download it manually (see [Alternative: Download BGE-M3 via ModelScope](#alternative-download-bge-m3-via-modelscope-recommended-for-users-in-china)).
**Q: Chinese titles in GMT images show as garbled characters**
No special handling required. SAGE has built-in CJK automatic processing: GMT execution stage replaces Chinese with empty placeholders, after execution matplotlib overlays Chinese titles back to PNG, ensuring correct Chinese display.
**Q: GMT plotting fails, prompting "GMT not installed"**
Install GMT >= 6.0:
```bash
# macOS
brew install gmt
# Linux (conda environment)
conda install -c conda-forge gmt
```
**Q: Batch picking is slow**
Default uses CPU. Add `--device cuda` to enable GPU acceleration (requires CUDA environment and corresponding PyTorch version).
**Q: Agent step execution fails**
Agent by default retries up to 2 times per step, failed steps will be skipped and subsequent steps continued. Can increase `--max-steps` limit, or check logs in output directory for details.
**Q: How to make AI use my own function library?**
Create an OpenAI-style `SKILL.md` under `seismo_skill/user_skills/<skill_name>/`, following [Creating Custom Skills](#creating-custom-skills) to describe when to use it, inputs/outputs, workflow steps, and minimal examples. Refresh the Skills page to manage it; Chat, CodeEngine, and Scientific Analysis Agent can retrieve and use it.
**Q: RAG function reports error "embedding model library not found"**
```bash
# 1. Confirm installation
pip list | grep -E "(FlagEmbedding|sentence-transformers)"
# 2. Try upgrade
pip install --upgrade FlagEmbedding sentence-transformers
# 3. If Rust compiler needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
pip install FlagEmbedding sentence-transformers
```
If none of the above methods can solve, the project's built-in lightweight TF-IDF vector database will automatically serve as fallback solution, basic RAG functionality still available.
---
## Acknowledgements
SAGE's integrated Aider backend builds on [Aider](https://github.com/Aider-AI/aider), an open-source AI pair programming tool for terminal and Git workflows. SAGE vendors the Aider source under `third_party/aider` and integrates it through its Python scripting API where available, with installed-package and CLI fallbacks for compatibility. The experimental OpenHands backend is designed to interoperate with [OpenHands](https://github.com/OpenHands/OpenHands). We thank these open-source communities for making stronger coding-agent workflows possible.
---
## Contact
SeismicX is developed by:
- **Yuqi Cai** - caiyuqiming@foxmail.com
- **Xin Liu** - xinliu_geo@outlook.com
- **Ziye Yu** - yuziye@cea-igp.ac.cn
---
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
**Q: How to add AI support for external tools like HypoDD?**
Call `register_tool()` in `seismo_tools/tool_registry.py` to register tool parameter templates and calling commands; simultaneously create corresponding skill document in `seismo_skill/`, describing input file format, allowing AI to automatically reference during code generation.
---
<p align="center">
<sub>Built with ❤️ for the seismology community</sub>
</p>