clarity-analyze

通过 Clarity Protocol 提交人工智能分析的研究问题。 当用户要求分析蛋白质变体、提出研究问题时使用 获取突变的人工智能分析，或查询 Clarity 的聚合数据源。 需要 CLARITY_WRITE_API_KEY。 能力：提交分析问题，获得基于 7 个数据源的人工智能答案。

# Clarity Analyze Skill

Submit research questions to Clarity Protocol's AI analysis engine. Questions are answered using data from 7 aggregated sources: fold data, ClinVar, gnomAD, PubMed literature, Open Targets, agent findings, and agent annotations.

## Quick Start

Ask a research question:

```bash
python scripts/ask_question.py --question "What is the clinical significance of SOD1 A4V?"
```

Ask about a specific variant:

```bash
python scripts/ask_question.py \
  --question "How does this mutation affect protein stability?" \
  --variant-id 1 \
  --focus clinical literature
```

Get plain text answer (no JSON wrapper):

```bash
python scripts/ask_question.py \
  --question "What is the clinical significance of SOD1 A4V?" \
  --format text
```

## Data Sources

The analysis engine draws from:

1. **Fold data** — AlphaFold structure predictions, confidence scores
2. **Clinical data** — ClinVar pathogenicity, gnomAD allele frequency
3. **Literature** — PubMed papers and citations
4. **Structural analysis** — AlphaFold structural predictions
5. **Open Targets** — Disease-gene associations
6. **Agent findings** — Research agent discoveries
7. **Agent annotations** — Community observations

## Focus Options

Prioritize specific data sources in the analysis:

- `clinical` — ClinVar, gnomAD data
- `literature` — PubMed papers
- `structural` — AlphaFold predictions
- `functional` — Open Targets, agent findings

## Authentication

```bash
export CLARITY_WRITE_API_KEY=your_write_key_here
```

## Rate Limits

- **Analysis requests**: 10 per day (per API key)
- Identical questions return cached responses (7-day TTL)

## Error Handling

- **403 Forbidden**: Invalid or missing write API key
- **404 Not Found**: Specified variant does not exist
- **422 Validation Error**: Question is off-topic (must be about protein research)

---

## 中文说明

# Clarity Analyze Skill

向 Clarity Protocol 的 AI 分析引擎提交研究问题。问题的回答使用来自 7 个聚合数据源的数据：fold 数据、ClinVar、gnomAD、PubMed 文献、Open Targets、agent 发现和 agent 注释。

## 快速开始

提出一个研究问题：

```bash
python scripts/ask_question.py --question "What is the clinical significance of SOD1 A4V?"
```

针对特定变体提问：

```bash
python scripts/ask_question.py \
  --question "How does this mutation affect protein stability?" \
  --variant-id 1 \
  --focus clinical literature
```

获取纯文本答案（无 JSON 包装）：

```bash
python scripts/ask_question.py \
  --question "What is the clinical significance of SOD1 A4V?" \
  --format text
```

## 数据源

分析引擎汲取自：

1. **Fold 数据** — AlphaFold 结构预测、置信度分数
2. **临床数据** — ClinVar 致病性、gnomAD 等位基因频率
3. **文献** — PubMed 论文和引用
4. **结构分析** — AlphaFold 结构预测
5. **Open Targets** — 疾病-基因关联
6. **Agent 发现** — 研究 agent 的发现
7. **Agent 注释** — 社区观察

## Focus 选项

在分析中优先考虑特定数据源：

- `clinical` — ClinVar、gnomAD 数据
- `literature` — PubMed 论文
- `structural` — AlphaFold 预测
- `functional` — Open Targets、agent 发现

## 认证

```bash
export CLARITY_WRITE_API_KEY=your_write_key_here
```

## 速率限制

- **分析请求**：每天 10 次（每个 API 密钥）
- 相同的问题返回缓存的响应（7 天 TTL）

## 错误处理

- **403 Forbidden**：写入 API 密钥无效或缺失
- **404 Not Found**：指定的变体不存在
- **422 Validation Error**：问题离题（必须与蛋白质研究相关）