studyforge-vocab 0.2.0__tar.gz

studyforge_vocab-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudyForge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

studyforge_vocab-0.2.0/PKG-INFO

@@ -0,0 +1,408 @@
+Metadata-Version: 2.4
+Name: studyforge-vocab
+Version: 0.2.0
+Summary: Extract reusable English vocabulary study data from PDF files.
+Author: StudyForge contributors
+License-Expression: MIT
+Project-URL: Homepage, https://studyforge-kpamprbzckvvgx4sz6fxvz.streamlit.app/
+Project-URL: Repository, https://github.com/gfr211306-crypto/StudyForge
+Project-URL: Issues, https://github.com/gfr211306-crypto/StudyForge/issues
+Project-URL: Changelog, https://github.com/gfr211306-crypto/StudyForge/blob/main/CHANGELOG.md
+Keywords: pdf,vocabulary,anki,ielts,cefr,streamlit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: data/LICENSE_ECDICT.txt
+License-File: data/NOTICE.md
+License-File: data/NOTICE_CEFR.md
+Requires-Dist: PyMuPDF<2.0,>=1.25
+Requires-Dist: opencc-python-reimplemented<0.2,>=0.1.7
+Provides-Extra: web
+Requires-Dist: streamlit<2.0,>=1.61; extra == "web"
+Requires-Dist: pandas<3.0,>=2.3; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9; extra == "dev"
+Requires-Dist: PyYAML<7,>=6; extra == "dev"
+Requires-Dist: build<2,>=1.5; extra == "dev"
+Dynamic: license-file
+
+# StudyForge
+
+[![CI](https://github.com/gfr211306-crypto/StudyForge/actions/workflows/ci.yml/badge.svg)](https://github.com/gfr211306-crypto/StudyForge/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Streamlit](https://img.shields.io/badge/Streamlit-1.61.1-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+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/)
+
+- 公開網址：<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
+
+```mermaid
+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](https://www.python.org/downloads/)，並勾選
+   **Add python.exe to PATH**。
+2. 下載或 clone 此儲存庫。
+3. 雙擊 `setup.bat`。
+4. 安裝完成後雙擊 `run.bat`。
+
+`run.bat` 會啟動網站並開啟 `http://localhost:8501`。
+
+### 安裝 CLI 與 Python package
+
+PyPI 套件尚未正式發布。從原始碼安裝：
+
+```bash
+git clone https://github.com/gfr211306-crypto/StudyForge.git
+cd StudyForge
+python -m pip install -e .
+```
+
+若也要執行 Web App：
+
+```bash
+python -m pip install -e ".[web]"
+```
+
+### Windows PowerShell
+
+```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
+
+```bash
+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 匯出：
+
+```bash
+studyforge extract file.pdf --limit 30 --format anki
+```
+
+IELTS mode 與 JSON：
+
+```bash
+studyforge extract file.pdf \
+  --mode ielts \
+  --limit 50 \
+  --format json \
+  --output ielts-vocabulary.json
+```
+
+支援的選項：
+
+```text
+--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：
+
+```bash
+python -m studyforge extract file.pdf --format csv
+```
+
+### Python API
+
+```python
+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：
+
+```text
+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 限制
+
+| 類型 | 支援狀態 |
+| --- | --- |
+| 一般文字型 PDF | 支援 |
+| 密碼保護 PDF | 請先解除密碼 |
+| 掃描圖片 PDF | 請先使用 OCR |
+| 超過 25 MB | 請先壓縮或分割 |
+| 超過 400 頁 | 請先分割 |
+
+## Streamlit Community Cloud deployment
+
+本儲存庫已符合 Community Cloud 的基本檔案配置：
+
+```text
+app.py
+requirements.txt
+.streamlit/config.toml
+studyforge/data/studyforge_dictionary.db
+studyforge/data/cefr_levels.json
+```
+
+部署時使用：
+
+| 設定 | 值 |
+| --- | --- |
+| Repository | `gfr211306-crypto/StudyForge` |
+| Branch | `main` |
+| Main file path | `app.py` |
+| Python version | `3.12` |
+| Secrets | 不需要 |
+
+`requirements.txt` 只包含網站執行依賴；pytest 位於
+`requirements-dev.txt`，不會增加 Community Cloud 的部署負擔。
+
+## Testing
+
+先安裝開發依賴：
+
+```bash
+python -m pip install -r requirements-dev.txt
+```
+
+執行完整檢查：
+
+```bash
+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：
+
+```bash
+python -m build
+```
+
+## Project structure
+
+```text
+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](SECURITY.md)。
+
+## Contributing
+
+歡迎 Bug 修正、測試、文件與功能改善。開始前請閱讀
+[CONTRIBUTING.md](CONTRIBUTING.md)，並使用專案提供的 Issue templates。
+
+基本流程：
+
+1. Fork 儲存庫並建立功能分支。
+2. 安裝 `requirements-dev.txt`。
+3. 修改程式並補充測試。
+4. 通過完整測試與 repository audit。
+5. 建立內容聚焦的 Pull Request。
+
+參與者請遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
+
+## Roadmap
+
+- [x] PDF 文字擷取
+- [x] 離線英中詞典與繁體中文轉換
+- [x] 原文例句與 Anki CSV
+- [x] GitHub Actions、Issue forms 與公開部署設定
+- [x] IELTS vocabulary mode
+- [x] CEFR A1–C2 可靠部分映射與 `unknown`
+- [x] CLI、Python API、普通 CSV 與 JSON
+- [x] 可建立 wheel 與 source distribution 的 `pyproject.toml`
+- [ ] OCR 掃描型 PDF 支援
+- [ ] 使用者自訂停用詞
+- [ ] 單字清單去重與手動新增功能
+- [ ] 更多 Anki 卡片模板
+- [ ] 無障礙與手機版操作改善
+- [ ] 多語言介面
+
+## Vocabulary data and CEFR policy
+
+離線詞典由 [ECDICT](https://github.com/skywind3000/ECDICT) 資料篩選轉換而成。
+詞典來源與授權說明請見 [data/NOTICE.md](data/NOTICE.md) 與
+[data/LICENSE_ECDICT.txt](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](data/NOTICE_CEFR.md)。
+
+## License
+
+StudyForge 程式碼採 [MIT License](LICENSE)。
+
+第三方詞典資料保留其原始 MIT 授權與版權聲明。