StudyForge

StudyForge v0.2.0 是一個可重用的開源 PDF vocabulary toolkit。它提供 Streamlit Web App、CLI 與 Python API，可將英文 PDF 自動整理成可複習、 可編輯並能匯入 Anki 的單字資料：

PDF → 文字擷取 → 重要英文單字 → 繁體中文釋義／詞性／原文例句 → Anki CSV

全程不需要 API key，也不會把文件內容送往翻譯或 AI API。

Live Demo

🚀 立即開啟 StudyForge 公開版

• 公開網址：https://studyforge-kpamprbzckvvgx4sz6fxvz.streamlit.app/
• 本機示範：執行 streamlit run app.py 後開啟 http://localhost:8501
• 示範教材：samples/StudyForge_demo.pdf
• Community Cloud 入口檔：app.py
• 建議部署 Python：3.12

Features

• 使用 PyMuPDF 擷取文字型 PDF 的逐頁內容
• 依出現頻率、跨頁分布、字頻與學術標籤推薦重要單字
• 使用超過 50,000 個詞條的本機離線英中詞典
• 將簡體詞典釋義轉成繁體中文
• 合併常見詞形，例如 analyzed → analyze
• IELTS vocabulary mode 優先排列詞典中明確標記為 IELTS 的單字
• CEFR A1–C2 分級；來源無法可靠判定時明確標示 unknown
• 從 PDF 原文自動挑選例句
• 顯示音標、詞性、中文意思、出現次數與頁碼
• 可在匯出前直接編輯或取消單字
• 支援 Anki CSV、普通 CSV 與 JSON
• 提供 studyforge extract CLI
• 提供可供其他 Python 專案 import 的 public API
• 對空白、損壞、密碼保護與掃描型 PDF 提供中文錯誤訊息
• 防護公開部署資源：25 MB、400 頁、2,000,000 個擷取字元上限
• 對 PDF 與使用者輸入進行 HTML escaping
• 使用每個 Streamlit session 獨立的分析結果，不共用使用者 PDF 快取

Architecture

flowchart LR
    Web[Streamlit Web App] --> API[StudyForge public API]
    CLI[studyforge CLI] --> API
    Python[Other Python projects] --> API
    API --> PDF[PyMuPDF reader]
    API --> Dictionary[Offline ECDICT database]
    API --> CEFR[Reliable partial CEFR profile]
    API --> Ranker[Vocabulary ranking / IELTS mode]
    Ranker --> Exporters[Anki CSV / CSV / JSON exporters]

Web、CLI 與 Python API 共用同一套 reader、dictionary、CEFR、ranking 與 exporter，沒有複製三份邏輯。

StudyForge 不使用生成式 AI。中文意思、詞性、音標與詞形資料來自專案內的 離線詞典；例句取自使用者上傳的 PDF。

Installation

系統需求

• Python 3.11 或 3.12（公開部署建議 3.12）
• pip
• Git（只有 clone 或貢獻程式時需要）

Windows 快速安裝

1. 安裝 Python，並勾選 Add python.exe to PATH。
2. 下載或 clone 此儲存庫。
3. 雙擊 setup.bat。
4. 安裝完成後雙擊 run.bat。

run.bat 會啟動網站並開啟 http://localhost:8501。

安裝 CLI 與 Python package

PyPI 套件尚未正式發布。從原始碼安裝：

git clone https://github.com/gfr211306-crypto/StudyForge.git
cd StudyForge
python -m pip install -e .

若也要執行 Web App：

python -m pip install -e ".[web]"

Windows PowerShell

git clone https://github.com/gfr211306-crypto/StudyForge.git
cd StudyForge
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
streamlit run app.py

macOS / Linux

git clone https://github.com/gfr211306-crypto/StudyForge.git
cd StudyForge
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
streamlit run app.py

Usage

Web App

1. 啟動 StudyForge。
2. 上傳文字可以被反白選取的英文 PDF。
3. 在側邊欄選擇單字數量、難度與最低出現次數。
4. 等待 StudyForge 擷取文字並整理單字。
5. 在表格中修正中文意思、詞性或例句，取消不需要的項目。
6. 選擇 Anki CSV、普通 CSV 或 JSON 後下載。

CLI

最基本的 Anki 匯出：

studyforge extract file.pdf --limit 30 --format anki

IELTS mode 與 JSON：

studyforge extract file.pdf \
  --mode ielts \
  --limit 50 \
  --format json \
  --output ielts-vocabulary.json

支援的選項：

--mode balanced|basic|intermediate|advanced|ielts
--format anki|csv|json
--limit 1-500
--min-occurrences 1-100
--output FILE

未指定 --output 時，CLI 會在目前目錄建立 <pdf-name>_<format>.csv 或 .json。使用 --output - 可輸出至 stdout。

也可以不安裝 console script：

python -m studyforge extract file.pdf --format csv

Python API

from studyforge import StudyForge, analyze_pdf, export_vocabulary

# Convenience function
result = analyze_pdf(
    "file.pdf",
    limit=30,
    mode="ielts",
)

for item in result.items:
    print(item.word, item.cefr_level, item.is_ielts)

anki_bytes = export_vocabulary(result.items, "anki")
json_bytes = export_vocabulary(result.items, "json")

# Reuse one service instance for multiple PDFs
engine = StudyForge()
another_result = engine.analyze_file("another.pdf", mode="balanced")

主要 public API：

StudyForge
analyze_pdf
analyze_pdf_bytes
AnalysisResult
VocabularyItem
CEFRProfile
export_vocabulary
export_rows

匯入 Anki

1. 在 Anki 選擇 檔案 → 匯入。
2. 選擇 StudyForge 下載的 CSV。
3. 對應欄位：Front、Back、Tags。
4. 勾選允許欄位使用 HTML。
5. 確認分隔符號為逗號後匯入。

PDF 限制

Streamlit Community Cloud deployment

本儲存庫已符合 Community Cloud 的基本檔案配置：

app.py
requirements.txt
.streamlit/config.toml
studyforge/data/studyforge_dictionary.db
studyforge/data/cefr_levels.json

部署時使用：

requirements.txt 只包含網站執行依賴；pytest 位於 requirements-dev.txt，不會增加 Community Cloud 的部署負擔。

Testing

先安裝開發依賴：

python -m pip install -r requirements-dev.txt

執行完整檢查：

python -m pip check
python scripts/audit_repository.py
python -m pytest -q
python -m compileall -q app.py studyforge scripts tests

GitHub Actions 會在每次 push、pull request 與手動觸發時，於 Python 3.11 及 3.12 執行相同的依賴檢查、儲存庫掃描、pytest、編譯檢查、package build 與 CLI smoke test。

建立 wheel 與 source distribution：

python -m build

Project structure

StudyForge/
├─ .github/
│  ├─ ISSUE_TEMPLATE/             # Bug 與功能建議表單
│  ├─ workflows/ci.yml            # GitHub Actions CI
│  └─ dependabot.yml
├─ .streamlit/config.toml         # Streamlit 公開部署設定
├─ app.py                         # Streamlit 入口檔
├─ data/
│  ├─ NOTICE.md
│  ├─ NOTICE_CEFR.md
│  └─ LICENSE_ECDICT.txt
├─ samples/                       # 可直接上傳測試的教材
├─ scripts/
│  ├─ audit_repository.py         # 敏感檔案與秘密掃描
│  ├─ build_cefr_data.py           # 重建可靠 CEFR mapping
│  └─ build_dictionary.py         # 從 ECDICT 重建詞典
├─ studyforge/
│  ├─ api.py                       # Web／CLI 共用 public API
│  ├─ cli.py                       # studyforge extract
│  ├─ cefr.py                      # CEFR 查詢與 unknown policy
│  ├─ exporter.py                  # Anki CSV／CSV／JSON
│  ├─ vocabulary.py                # 排序與 IELTS mode
│  └─ data/                        # wheel 內含詞典與 CEFR mapping
├─ tests/                         # pytest 測試
├─ pyproject.toml                 # PyPI package metadata
├─ CONTRIBUTING.md
├─ SECURITY.md
├─ requirements.txt              # 公開部署執行依賴
└─ requirements-dev.txt          # 開發與測試依賴

Privacy and security

• 本機執行： PDF 只在你的電腦處理。
• 公開部署： PDF 會傳送至執行 StudyForge 的 Streamlit 伺服器。
• PDF 不會被送往外部翻譯服務或 AI API。
• 專案不會主動把 PDF 或擷取文字寫入永久檔案。
• 分析結果只保留於目前使用者的 Streamlit session。
• 公開部署不適合機密、醫療、法律或含大量個資的文件。
• 回報問題時，請勿把真實敏感 PDF 上傳到公開 GitHub Issue。

安全問題請參閱 SECURITY.md。

Contributing

歡迎 Bug 修正、測試、文件與功能改善。開始前請閱讀 CONTRIBUTING.md，並使用專案提供的 Issue templates。

基本流程：

1. Fork 儲存庫並建立功能分支。
2. 安裝 requirements-dev.txt。
3. 修改程式並補充測試。
4. 通過完整測試與 repository audit。
5. 建立內容聚焦的 Pull Request。

參與者請遵守 CODE_OF_CONDUCT.md。

Roadmap

• PDF 文字擷取
• 離線英中詞典與繁體中文轉換
• 原文例句與 Anki CSV
• GitHub Actions、Issue forms 與公開部署設定
• IELTS vocabulary mode
• CEFR A1–C2 可靠部分映射與 unknown
• CLI、Python API、普通 CSV 與 JSON
• 可建立 wheel 與 source distribution 的 pyproject.toml
• OCR 掃描型 PDF 支援
• 使用者自訂停用詞
• 單字清單去重與手動新增功能
• 更多 Anki 卡片模板
• 無障礙與手機版操作改善
• 多語言介面

Vocabulary data and CEFR policy

離線詞典由 ECDICT 資料篩選轉換而成。 詞典來源與授權說明請見 data/NOTICE.md 與 data/LICENSE_ECDICT.txt。

CEFR mapping 由 CEFR-J 1.5 與 Octanove C1/C2 1.0 建置。StudyForge 只保留 同一 normalized headword 在來源中一致的級別；若不同詞性或語義對應不同級別， 就不做猜測並輸出 unknown。目前 bundled mapping 有約 7,900 個無歧義詞條。 來源、授權與處理規則請見 data/NOTICE_CEFR.md。

License

StudyForge 程式碼採 MIT License。

第三方詞典資料保留其原始 MIT 授權與版權聲明。