Metadata-Version: 2.4
Name: monadscholar
Version: 0.1.0
Summary: Local deterministic research CLI for WorkBuddy
Author: MonadScholar
Project-URL: Repository, https://github.com/daisyluvr42/monad_scholarkit
Project-URL: Documentation, https://github.com/daisyluvr42/monad_scholarkit/blob/main/docs/WORKBUDDY.md
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.13
Requires-Dist: statsmodels>=0.14
Requires-Dist: lifelines>=0.30
Requires-Dist: matplotlib>=3.9
Requires-Dist: networkx>=3.3
Requires-Dist: openpyxl>=3.1

# MonadScholar

MonadScholar 是面向 WorkBuddy 的外部 CLI 连接器与单一科研 Skill。它保留原 Scholar 的文献、设计、统计、图表、Meta、临床研究、写作、润色、投稿和科研辅助能力，同时把确定性计算收口到本地 `monadscholar` CLI。

用户安装连接器后只需用自然语言提出科研任务，不需要理解命令行。WorkBuddy 负责理解意图、读取用户上传的 PDF/Word/PPT/TXT/Markdown，并调用 Skill；CLI 负责真实题录、样本量、统计、Table One、Meta、数据图和期刊公开元数据。

## 形态

```text
用户自然语言
  -> WorkBuddy
     -> monadscholar-research Skill：任务规划、证据边界、结果解释
     -> WorkBuddy 原生文件读取：PDF / Word / PPT / TXT / Markdown
     -> 官方 ima：大量论文或长期全文资料库
     -> monadscholar CLI：文献元数据 / 引文 / 统计 / Meta / 数据图
```

这是本地 CLI 连接器，不需要为每位用户提供 MonadScholar 云端服务。PubMed、Crossref 和 OpenAlex 请求由用户设备直接访问相应公开接口；数据表和生成产物默认留在本机。

## 能力

对外提供一个 `monadscholar-research` Skill，内部覆盖 40 项能力：

| 模块 | 能力 |
|---|---|
| 文献、阅读与选题 | PubMed、检索式、题录去重与导出、单篇精读、证据矩阵、综述、选题、创新点、立项与开题框架 |
| 设计、统计与图表 | 研究设计、随机与对照、统计方案、样本量、参数/非参数检验、回归、生存分析、Table One、数据图与图表复现 |
| 临床、循证与网络 | PICO/PECO、逐篇数据提取、偏倚风险、Meta、森林图、漏斗图、PRISMA、临床预测、诊断试验、真实世界研究、网络图 |
| 写作、投稿与辅助 | IMRaD、摘要、润色、翻译、选刊、投稿清单、cover letter、审稿回复、邮件、术语表、周报、纪要与 PPT 大纲 |

统计命令支持：

- `describe`
- `independent_t`、`paired_t`、`one_sample_t`
- `mann_whitney`、`wilcoxon`
- `chi_square`、`fisher_exact`
- `one_way_anova`、`kruskal`
- `pearson`、`spearman`
- `linear_regression`、`logistic_regression`
- `kaplan_meier`、`cox_regression`
- `table_one`
- `sample_size`

绘图支持 scatter、line、bar、box、violin、histogram、heatmap、Kaplan–Meier 和 network；数据图导出 300 dpi PNG 与可编辑 SVG。

## 用户体验

连接器发布到 WorkBuddy 后，用户的典型流程是：

1. 在连接器市场找到“MonadScholar 科研助手”并安装。
2. WorkBuddy 初始化 Python CLI，并加载 `monadscholar-research` Skill。
3. 用户直接上传材料并描述目标。
4. WorkBuddy 读取证据文档；如果是 CSV/TSV/XLSX/XLSM，则把原始本地路径交给 CLI。
5. MonadScholar 返回结构化 JSON 和产物路径，WorkBuddy 将其解释成研究结论、表格或可下载文件。

例如：

```text
读取这个 Excel，先说明变量、编码和缺失情况，再比较两组主要结局，
生成带 SMD 的 Table One，并画一张叠加原始散点和样本量的箱线图。
```

```text
精读我上传的三篇 PDF，整理研究设计、样本、主要结果、局限和与我课题的关系。
```

单次上传的 PDF 等文档由 WorkBuddy 原生解析；大量论文或希望长期复用的全文资料使用官方 ima。

## CLI

本地开发安装：

```bash
python3 -m pip install -e .
monadscholar doctor
```

命令：

```text
monadscholar doctor
monadscholar capabilities
monadscholar literature search
monadscholar references run
monadscholar stats run
monadscholar plot run
monadscholar meta run
monadscholar journal match
```

短参数可以直接传入；复杂参数使用 JSON request：

```bash
monadscholar stats run --request "/path/to/request.json"
```

成功结果：

```json
{
  "ok": true,
  "command": "stats.run",
  "data": {},
  "artifacts": []
}
```

错误结果：

```json
{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Column 'outcome' was not found.",
    "retryable": false
  }
}
```

退出码：

- `0`：成功
- `2`：参数、输入文件或数据问题
- `3`：本地运行环境问题
- `4`：公开元数据网络请求失败
- `5`：分析或绘图失败

默认输出目录：

```text
~/.workbuddy/workspace/monadscholar/
```

## 连接器包

连接器源码位于 `workbuddy-connector/`：

```text
workbuddy-connector/
├── connector-meta.json
├── cli.json
├── icon.svg
└── skills/
    └── monadscholar-research/
        ├── SKILL.md
        └── references/
```

构建市场上传 ZIP：

```bash
python3 scripts/build_workbuddy_connector.py
```

输出：

```text
dist/monadscholar-workbuddy-0.1.0.zip
```

`cli.json` 当前从 PyPI 安装固定版本 `monadscholar==0.1.0`，因此正式提交连接器前必须先发布对应 Python 包。

## 测试

```bash
.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
tests/smoke_cli.sh
MONADSCHOLAR_ACCEPTANCE_OUTPUT_DIR=/tmp/monadscholar-acceptance \
  .venv/bin/python tests/run_acceptance.py
python3 scripts/build_workbuddy_connector.py
```

`tests/run_acceptance.py` 会真实访问 PubMed，并从该次检索返回的元数据与摘要生成阅读卡；其余单元测试和 CLI 冒烟可离线运行。

## 数据与证据边界

- 所有样本量、描述值、P 值、效应量、置信区间、回归结果、Meta 合并值和数据图必须来自 CLI。
- CSV、TSV、XLSX、XLSM 必须让 CLI 读取原文件，不能先由模型转录数值。
- PDF、Word、PPT、TXT、Markdown 的正文证据来自 WorkBuddy 实际解析内容；读不到的内容不猜。
- DOI、PMID、作者、年份和期刊名来自 CLI 返回或用户提供的可核对来源。
- 期刊匹配使用公开元数据初筛；最新 scope、费用、索引和投稿要求仍需核对期刊官网。
- 医学内容用于科研支持，不替代个体化诊疗或专业统计复核。

## 公开期刊数据

`data/journals.json` 基于 OpenAlex Sources API 和本地主题标签构建。刷新时会同步更新 Python 包内副本：

```bash
.venv/bin/python data/build_journals.py
```

可选环境变量：

```text
NCBI_EMAIL
NCBI_API_KEY
OPENALEX_EMAIL
OPENALEX_API_KEY
CROSSREF_EMAIL
```

JCR 影响因子和中科院分区不打包、不推测。

## 发布前待确认

WorkBuddy 开放文档中仍有几项协议细节未给出完整字段定义，已整理在 [docs/OFFICIAL_QUESTIONS.md](docs/OFFICIAL_QUESTIONS.md)。这些问题不影响本地 CLI 和 Skill 验收，但在正式提交市场前应由官方确认。
