scAgent

<p align="center">
  <img src="web/logo.svg" alt="scAgent" width="320" />
</p>

<p align="center">Go control plane + Python analysis runtime + static frontend for interactive single-cell workflows.</p>

`scAgent` supports workspace-based object sharing, conversation-scoped job/message history, a three-phase LLM execution pipeline (decide → investigate → respond), background job execution, markdown-driven help docs, dynamic Skill Hub plugin bundles, and optional WeChat bridge integration.

## What Works Today

- Upload a real `.h5ad` file and assess its readiness, annotations, embeddings, and analysis state.
- Reuse one shared workspace across multiple conversations while keeping each conversation's jobs and messages isolated.
- Create, inspect, and delete workspaces and conversations through the REST API.
- Execute 32 `wired` skills covering the full single-cell analysis pipeline:
  - **Inspection**: `inspect_dataset`, `assess_dataset`
  - **Quality control**: `summarize_qc`, `plot_qc_metrics`, `filter_cells`, `filter_genes`
  - **Preprocessing**: `normalize_total`, `log1p_transform`, `select_hvg`, `scale_matrix`
  - **Dimensionality reduction**: `run_pca`, `compute_neighbors`, `run_umap`, `prepare_umap`
  - **Visualization**: `plot_umap`, `plot_gene_umap`, `plot_dotplot`, `plot_violin`, `plot_heatmap`, `plot_celltype_composition`
  - **Subsetting**: `subset_cells`, `score_gene_set`
  - **Clustering**: `subcluster_from_global`, `recluster`, `reanalyze_subset`, `subcluster_group`, `rename_clusters`
  - **Differential expression**: `find_markers`
  - **Custom**: `run_python_analysis`
  - **Export**: `export_h5ad`, `export_markers_csv`, `write_method`
- Run long tasks as background jobs. The web client streams plan updates, execution checkpoints, step results, and artifacts over SSE.
- Preview the planning context before execution through `/api/sessions/{id}/planner-preview`.
- Manage built-in bundles and uploaded plugin bundles from `/plugins.html` without restarting the server.
- Optionally bridge conversations to WeChat for voice and text message interaction.

Only `wired` skills are executable. `planned` skills remain registry placeholders until runtime support is added.

## Layout

- `cmd/scagent`: Go entrypoint and CLI flags.
- `internal/api`: HTTP handlers for workspaces, sessions, messages, docs, skills, and plugins.
- `internal/app`: server wiring.
- `internal/models`: workspace, session, object, job, artifact, checkpoint, and plan structs.
- `internal/orchestrator`: three-phase execution (decide/investigate/respond), planning, evaluation, and event publishing.
- `internal/runtime`: Go client for the Python runtime.
- `internal/session`: SQLite-backed store plus snapshot/event helpers.
- `internal/skill`: built-in registry plus Skill Hub plugin loading.
- `internal/weixin`: WeChat bridge client and protocol types.
- `runtime/server.py`: long-lived Python runtime service.
- `runtime/session_worker.py`: per-session worker process for isolated skill execution.
- `runtime/doctor.py`: environment health check utility.
- `skills/registry.json`: shared skill catalog and parameter schema.
- `web`: main SPA (`index.html`, `app.js`), modular CSS (`css/`) and JS modules (`js/`), help site, and plugin management UI.
- `docs/agent-architecture.md`: current execution flow and extension points.
- `docs/help-guide.md`: user-facing workflow guide.
- `docs/protocol.md`: control-plane, runtime, and web API contract.
- `docs/skill-hub.md`: plugin bundle format and Skill Hub behavior.
- `docs/skill-catalog.md`: skill descriptions and parameter reference.
- `docs/custom-tools.md`: custom tool integration guide.
- `docs/weixin-bridge.md`: WeChat bridge setup and protocol.
- `docs/pixi-environment.md`: Python environment pinning.
- `docs/roadmap.md`: project roadmap.
- `docs/commit-convention.md`: git commit style guide.

## Run

Install Pixi first, then create the pinned Python environment:

```bash
curl -fsSL https://pixi.sh/install.sh | sh
pixi install
pixi run doctor
```

If `pixi` is installed but not in `PATH`, `start.sh` also accepts `SCAGENT_PIXI_BIN=/absolute/path/to/pixi`.

For local development, the easiest path is:

```bash
cp .env.example .env
make dev
```

`make dev` / `start.sh` will:

- load `.env` if it exists
- ensure `data/samples/pbmc3k.h5ad` exists, downloading the default PBMC3K sample if needed
- start the Python runtime through `pixi run runtime` by default
- fail fast when Pixi is unavailable unless `SCAGENT_USE_PIXI=0`
- wait for the runtime health check
- start the Go control plane
- optionally start the WeChat bridge when `WEIXIN_BRIDGE_ENABLED=1`

Available Makefile targets:

```bash
make dev             # run via start.sh
make restore         # reset state and workspace data, preserve WeChat login state
make weixin          # run with WeChat bridge enabled
make weixin-login    # WeChat login flow
make weixin-logout   # WeChat logout flow
```

Data directory conventions:

- `data/samples`: default sample files such as `pbmc3k.h5ad`
- `data/state`: SQLite control-plane persistence
- `data/workspaces`: current workspace-scoped objects and artifacts
- `data/weixin-bridge`: WeChat login/session state that `make restore` intentionally preserves

Or run both processes manually:

```bash
pixi run runtime
go run ./cmd/scagent
```

`pixi run runtime` and `pixi run doctor` load `.env` when it exists, then fall back to `127.0.0.1:8081` if no runtime host/port is set.

Open:

- `http://127.0.0.1:8080/` for the main analysis console
- `http://127.0.0.1:8080/help.html` for the markdown-driven help site
- `http://127.0.0.1:8080/plugins.html` for Skill Hub / plugin management

## Environment Variables

All variables can be set in `.env` or passed as CLI flags. See `.env.example` for a template.

**Server & runtime:**

| Variable | Default | Description |
|----------|---------|-------------|
| `SCAGENT_ADDR` | `:8080` | HTTP listen address |
| `SCAGENT_RUNTIME_HOST` | `127.0.0.1` | Python runtime host |
| `SCAGENT_RUNTIME_PORT` | `8081` | Python runtime port |
| `SCAGENT_RUNTIME_URL` | `http://127.0.0.1:8081` | Full runtime URL |
| `SCAGENT_USE_PIXI` | `1` | Use Pixi to manage the Python runtime |
| `SCAGENT_PIXI_BIN` | (auto) | Absolute path to Pixi binary |

**LLM planner:**

| Variable | Default | Description |
|----------|---------|-------------|
| `SCAGENT_PLANNER_MODE` | `llm` | Planner backend (`llm`) |
| `SCAGENT_OPENAI_API_KEY` | — | API key for the LLM provider |
| `SCAGENT_OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible base URL |
| `SCAGENT_OPENAI_MODEL` | `gpt-5.4` | Model identifier |
| `SCAGENT_OPENAI_REASONING_EFFORT` | `low` | Reasoning effort level |

**Paths:**

| Variable | Default | Description |
|----------|---------|-------------|
| `SCAGENT_DATA_DIR` | `data` | Workspace and state storage root |
| `SCAGENT_WEB_DIR` | `web` | Static frontend directory |
| `SCAGENT_SKILLS_PATH` | `skills/registry.json` | Skill catalog file |
| `SCAGENT_DOCS_DIR` | `docs` | Markdown help content |
| `SCAGENT_SAMPLE_H5AD` | `data/samples/pbmc3k.h5ad` | Default sample `.h5ad` used to bootstrap an empty workspace |
| `SCAGENT_SAMPLE_H5AD_URL` | `https://exampledata.scverse.org/tutorials/scverse-getting-started-anndata-pbmc3k_processed.h5ad` | Download source used when the sample file is missing |
| `SCAGENT_SAMPLE_AUTO_DOWNLOAD` | `1` | Auto-download the default sample during `make dev` / `start.sh` when missing |
| `SCAGENT_PLUGIN_DIR` | `data/skill-hub/plugins` | Uploaded plugin bundles |
| `SCAGENT_PLUGIN_STATE_PATH` | `data/skill-hub/state.json` | Plugin enable/disable state |

**WeChat bridge:**

| Variable | Default | Description |
|----------|---------|-------------|
| `WEIXIN_BRIDGE_ENABLED` | `0` | Enable WeChat message bridge |
| `WEIXIN_BRIDGE_SESSION_LABEL` | — | Target session label for bridged messages |
| `WEIXIN_BRIDGE_TIMEOUT_MS` | — | Bridge request timeout in milliseconds |

## Three-Phase Execution

Each user reque

[truncated…]