gbert 0.1.0__tar.gz

gbert-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README_PYPI.md
+recursive-include gbert/add *.csv
+include gbert/preprocess_meta.joblib

gbert-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.1
+Name: gbert
+Version: 0.1.0
+Summary: Simple multilingual policy text analysis with GBERT, optimized for notebooks and Kaggle.
+Project-URL: Homepage, https://pypi.org/project/gbert/
+Keywords: nlp,bert,text-classification,kaggle,policy-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huggingface_hub<2,>=0.30
+Requires-Dist: joblib<2,>=1.4
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: scikit-learn<2,>=1.5
+Requires-Dist: torch<2.6,>=2.5
+Requires-Dist: transformers<5,>=4.46
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+
+# gbert
+
+`gbert` 是一个尽量简单的多语言文本分析包，适合：
+
+- Kaggle Notebook
+- 单条文本快速预测
+- 大批量文本批处理
+
+它默认不包含网页、Flask 或服务端代码，只保留推理必需内容。
+
+## 安装
+
+```bash
+pip install gbert
+```
+
+如果你在 Kaggle 里使用，推荐先安装再直接在 Notebook 里跑：
+
+```python
+!pip -q install gbert
+```
+
+## 最简单用法
+
+```python
+from gbert import GbertClassifier
+
+model = GbertClassifier(
+    model_repo_id="your-hf-model-repo",
+    hf_token="your_hf_token_if_needed",
+)
+
+result = model.predict(
+    "The government will expand industrial policy and labour training.",
+    country="Japan",
+    year=2026,
+)
+
+result["predictions"][:3]
+```
+
+## 批量分析
+
+```python
+from gbert import GbertClassifier
+
+model = GbertClassifier(model_repo_id="your-hf-model-repo")
+
+results = model.predict_batch(
+    texts=[
+        "We will invest in industry.",
+        "Healthcare access must improve.",
+        "Tax reform should support growth.",
+    ],
+    country="Japan",
+    year=2026,
+    batch_size=16,
+)
+```
+
+如果你更喜欢 `pandas.DataFrame`：
+
+```python
+df = model.predict_batch(
+    texts=["text a", "text b"],
+    country=["Japan", "Germany"],
+    year=[2026, 2024],
+    return_df=True,
+)
+```
+
+## API
+
+### `GbertClassifier`
+
+常用参数：
+
+- `model_path`: 本地模型权重路径
+- `model_repo_id`: Hugging Face Hub 模型仓库
+- `model_filename`: 默认是 `causal_nam_best.pt`
+- `hf_token`: 私有仓库时可传
+- `device`: `cpu` / `cuda` / 自动检测
+- `batch_size`: 批量推理默认 batch 大小
+
+### 方法
+
+- `predict(text, country, year, top_k=5)`
+- `predict_batch(texts, country, year, top_k=5, batch_size=None, return_df=False)`
+- `list_countries()`
+- `list_years(country)`
+- `runtime_info()`
+
+## 设计目标
+
+- Notebook first
+- Kaggle friendly
+- 单次加载，多次复用
+- 单条和批量接口统一
+
+## 模型说明
+
+这个包会打包：
+
+- `preprocess_meta.joblib`
+- `add/` 下的宏观变量 CSV
+
+它不会打包大模型权重文件。运行时会按以下顺序寻找模型：
+
+1. 你显式传入的 `model_path`
+2. 环境变量 `GBERT_MODEL_PATH`
+3. 包目录下的 `causal_nam_best.pt`
+4. Hugging Face Hub (`model_repo_id`)
+
+如果你想通过环境变量控制，也支持：
+
+- `GBERT_MODEL_PATH`
+- `GBERT_MODEL_REPO_ID`
+- `GBERT_MODEL_FILENAME`
+- `HF_TOKEN`
+- `TEXT_MODEL_NAME_OR_PATH`
+- `TORCH_NUM_THREADS`
+
+## 命令行
+
+```bash
+gbert --text "Industrial policy matters." --country Japan --year 2026
+```
+
+## 备注
+
+- 当前宏观数据可支持到 `2026`
+- 对超出训练年份的输入，年份 embedding 会自动回退到模型训练期的最后一年
+- 批量分析建议复用同一个 `GbertClassifier` 实例，不要每条文本重新初始化模型

gbert-0.1.0/README.md

@@ -0,0 +1,276 @@
+---
+title: Manifesto Model Demo
+sdk: docker
+app_port: 7860
+---
+
+# Manifesto Model Web Demo
+
+这个项目现在已经补上了一个可直接启动的网站版本，访问者可以：
+
+- 输入一段政策文本
+- 选择国家和年份
+- 由系统自动从 `add/` 目录读取 6 个宏观变量
+- 调用训练好的 `causal_nam_best.pt` 模型返回 Top-5 预测类别
+
+## 新增文件
+
+- `app.py`: Flask 网站入口
+- `inference_service.py`: 推理服务，负责读取 `preprocess_meta.joblib`、`add/` 和模型
+- `templates/index.html`: 页面模板
+- `static/style.css`: 页面样式
+- `static/app.js`: 前端交互
+- `render.yaml`: Render 部署配置
+- `Procfile`: Railway / 通用 PaaS 启动命令
+- `.env.example`: 环境变量模板
+
+## 启动方式
+
+建议先准备一个可正常运行 `torch` 和 `transformers` 的 Python 环境，再执行：
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+启动后访问：
+
+```text
+http://127.0.0.1:8000
+```
+
+本地环境变量可以参考 `.env.example`。
+
+## 作为 Python 包使用
+
+现在仓库也可以直接作为 Python 包安装：
+
+```bash
+pip install .
+```
+
+安装后可以在 Python 里直接调用：
+
+```python
+from manifesto_model import create_service, predict
+
+service = create_service()
+result = service.predict(
+    text="The government will expand industrial policy and labour training.",
+    country="Japan",
+    year=2026,
+    top_k=5,
+)
+
+# 或者直接：
+result = predict(
+    text="The government will expand industrial policy and labour training.",
+    country="Japan",
+    year=2026,
+)
+```
+
+如果你想作为 Flask API 使用，也可以：
+
+```python
+from manifesto_model.web import create_app
+
+app = create_app()
+```
+
+## 发布到 PyPI
+
+这个仓库现在已经补成标准 `pyproject.toml` 包结构，可以直接发布到 PyPI。
+
+建议流程：
+
+1. 先确认 PyPI 上还没有同名包 `manifesto-model`
+2. 安装构建与上传工具：
+
+```bash
+pip install build twine
+```
+
+3. 构建发布文件：
+
+```bash
+python -m build
+```
+
+4. 先上传到 TestPyPI 测试：
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+5. 测试没问题后，再上传到正式 PyPI：
+
+```bash
+python -m twine upload dist/*
+```
+
+6. 上传成功后，其他人就可以直接安装：
+
+```bash
+pip install manifesto-model
+```
+
+当前包发布时不会包含 `causal_nam_best.pt` 大模型权重；运行时需要通过 `MODEL_PATH` 或 Hugging Face Hub 环境变量提供模型文件。
+
+## 让其他用户访问
+
+现在最直接的做法是把这个项目部署到一个公开 URL。这个仓库已经补了 `Dockerfile`，适合直接部署到支持 Docker 的平台。
+
+## GitHub Pages 前端 + 独立后端 API
+
+现在项目已经拆成了两层：
+
+1. `docs/` 目录下是纯静态前端，可以直接发布到 GitHub Pages
+2. Flask 只负责独立后端 API，主要接口是 `/api/health`、`/api/options`、`/api/predict`
+
+前端不会依赖 Flask 模板，也不会依赖同域部署。访问者第一次打开 GitHub Pages 页面时，只需要填写一次后端地址，浏览器会自动保存。
+如果你已经有固定的线上后端地址，也可以直接把它写进 `docs/assets/app.js`，这样普通用户打开页面就能直接使用。
+
+### GitHub Pages 部署
+
+1. 把代码推到 GitHub 仓库
+2. 在仓库设置里打开 Pages
+3. 选择从 `main` 分支的 `/docs` 目录发布
+4. 等 GitHub 生成公开网址
+
+### 后端 API 部署
+
+后端继续部署到 Render、Railway 或 Hugging Face Spaces 都可以。由于前端是跨域调用，后端已经默认加好了 CORS。
+
+如果你想限制只允许自己的 GitHub Pages 域名访问，可以配置：
+
+```text
+CORS_ALLOW_ORIGINS=https://your-name.github.io
+```
+
+如果不配置，当前默认允许公开前端调用。
+
+## 上线前必须注意
+
+`causal_nam_best.pt` 现在大约 683MB。GitHub 官方对普通仓库单文件有 100MB 限制，所以它不能作为普通文件直接推送到 GitHub。
+
+现在代码支持两种上线方式：
+
+1. 使用 Git LFS 管理模型文件
+2. 更推荐：把网站代码和模型文件分开，代码仓库只放网站，模型放到 Hugging Face 模型仓库，部署时通过环境变量自动下载
+
+如果你选择“模型仓库分离”方案，需要配置：
+
+```text
+MODEL_REPO_ID=your-username/your-model-repo
+MODEL_FILENAME=causal_nam_best.pt
+HF_TOKEN=
+TEXT_MODEL_NAME_OR_PATH=bert-base-multilingual-cased
+```
+
+如果模型文件就在部署机器本地，只需要：
+
+```text
+MODEL_PATH=./causal_nam_best.pt
+```
+
+### 方案 1：Hugging Face Spaces（更适合模型演示）
+
+- 官方说明：Hugging Face 支持 Docker Spaces，可以直接运行自定义 `Dockerfile`
+- 本项目已经按这种方式准备好了，默认暴露端口 `7860`
+- 适合做公开 demo，后续如果 CPU 不够，也可以升级硬件
+
+基本流程：
+
+1. 新建一个 Hugging Face Space
+2. 选择 `Docker` 作为 SDK
+3. 把当前项目代码推上去
+4. 在 Space 里配置环境变量；如果模型不在代码仓库中，就配置 `MODEL_REPO_ID` 和 `MODEL_FILENAME`
+5. 等待构建完成后，平台会给你一个公开链接
+
+### 方案 2：Render / Railway（更像常规网站部署）
+
+- 两个平台都支持从 GitHub 仓库直接部署 Python/Flask 应用
+- Render 官方要求服务监听 `0.0.0.0` 和平台端口
+- Railway 官方的 Flask 指南建议使用 `gunicorn`
+- 这些要求我已经在代码里处理好了
+
+如果你走这条路，通常只需要：
+
+1. 把项目推到 GitHub
+2. 在平台里选择该仓库
+3. 配置环境变量，例如：
+
+```text
+MODEL_REPO_ID=your-username/your-model-repo
+MODEL_FILENAME=causal_nam_best.pt
+TEXT_MODEL_NAME_OR_PATH=bert-base-multilingual-cased
+```
+
+4. 使用 Docker 部署，或直接使用：
+
+```text
+Build: pip install -r requirements.txt
+Start: gunicorn --bind 0.0.0.0:$PORT app:app
+```
+
+### 当前更推荐哪个
+
+- 如果你的目标是“让别人在线试这个模型”，我更推荐 Hugging Face Spaces
+- 如果你的目标是“做成普通网站，后面还想加账号、数据库、API 管理”，我更推荐 Render 或 Railway
+
+## 推荐上线结构
+
+建议按下面的结构上线：
+
+1. GitHub 仓库：只放网站代码
+2. Hugging Face 模型仓库：只放 `causal_nam_best.pt`
+3. 部署平台：Hugging Face Spaces 或 Render
+
+这样能避开 GitHub 大文件限制，也更方便后续更新模型。
+
+## 速度和内存
+
+如果你在线上看到 `Ran out of memory (used over 512MB)`，根因通常不是页面，而是模型本体太大。
+
+当前项目已经做了几项部署优化：
+
+- Docker 默认安装 CPU 版 PyTorch，不再拉取 CUDA 大包
+- Gunicorn 改成 `1 worker + 1 thread`
+- 推理进程默认 `TORCH_NUM_THREADS=1`
+- 模型 backbone 用更省内存的加载方式
+- 权重加载优先使用 `weights_only` / `mmap`
+
+即便这样，`683MB` 权重加上 `bert-base-multilingual-cased` 在 `512MB RAM` 上依然很容易不稳定。  
+如果你要“速度明显更快且稳定”，最有效的方法通常是：
+
+1. 把实例内存升到至少 `2GB`
+2. 后续改成模型常驻内存
+3. 或者换更小的模型
+
+## 说明
+
+- 页面不会让用户手填宏观变量，推理时会自动从 `add/` 的 World Bank CSV 中按 `国家 + 年份` 读取。
+- `add/` 中的 6 个宏观变量文件现在已经扩展到 `2026`；其中 `2025`、`2026` 当前采用 `2024` 数值前向延续，便于网站先支持未来年份推理。
+- 少数国家名称和 World Bank 的命名不完全一致，代码里已经做了别名映射，例如：
+  - `South Korea -> Korea, Rep.`
+  - `Turkey -> Turkiye`
+  - `Czech Republic -> Czechia`
+- 如果某个国家年份在 `add/` 里该指标缺失，当前实现会按训练阶段的做法补 `0`，然后再按 `preprocess_meta.joblib` 里的均值和标准差做标准化。
+- 模型训练时的年份编码目前只到 `2023`，因此当页面选择 `2024-2026` 时，宏观变量会读取对应年份的新列，但模型内部年份 embedding 仍兼容回退到 `2023`。
+
+## 当前环境提醒
+
+我在这台机器上检查时，当前 Anaconda 环境里的 `torch` 启动就报了底层 OpenMP 错误，因此还不能在这里完成真实推理验证。
+
+网页和服务代码已经接好；只要换到一个可正常运行 `torch` 的环境，或者修复当前 Python 环境后，就可以直接启动并调用模型。
+
+## 参考资料
+
+- [Hugging Face Spaces 概览](https://huggingface.co/docs/hub/en/spaces)
+- [Hugging Face Docker Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Hugging Face Hub 文件下载](https://huggingface.co/docs/huggingface_hub/v0.30.2/en/guides/download)
+- [GitHub 大文件限制](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github)
+- [Render Web Services 文档](https://render.com/docs/web-services)
+- [Render Blueprints / render.yaml](https://render.com/docs/infrastructure-as-code)
+- [Railway Flask 部署指南](https://docs.railway.com/guides/flask)

gbert-0.1.0/README_PYPI.md

@@ -0,0 +1,133 @@
+# gbert
+
+`gbert` 是一个尽量简单的多语言文本分析包，适合：
+
+- Kaggle Notebook
+- 单条文本快速预测
+- 大批量文本批处理
+
+它默认不包含网页、Flask 或服务端代码，只保留推理必需内容。
+
+## 安装
+
+```bash
+pip install gbert
+```
+
+如果你在 Kaggle 里使用，推荐先安装再直接在 Notebook 里跑：
+
+```python
+!pip -q install gbert
+```
+
+## 最简单用法
+
+```python
+from gbert import GbertClassifier
+
+model = GbertClassifier(
+    model_repo_id="your-hf-model-repo",
+    hf_token="your_hf_token_if_needed",
+)
+
+result = model.predict(
+    "The government will expand industrial policy and labour training.",
+    country="Japan",
+    year=2026,
+)
+
+result["predictions"][:3]
+```
+
+## 批量分析
+
+```python
+from gbert import GbertClassifier
+
+model = GbertClassifier(model_repo_id="your-hf-model-repo")
+
+results = model.predict_batch(
+    texts=[
+        "We will invest in industry.",
+        "Healthcare access must improve.",
+        "Tax reform should support growth.",
+    ],
+    country="Japan",
+    year=2026,
+    batch_size=16,
+)
+```
+
+如果你更喜欢 `pandas.DataFrame`：
+
+```python
+df = model.predict_batch(
+    texts=["text a", "text b"],
+    country=["Japan", "Germany"],
+    year=[2026, 2024],
+    return_df=True,
+)
+```
+
+## API
+
+### `GbertClassifier`
+
+常用参数：
+
+- `model_path`: 本地模型权重路径
+- `model_repo_id`: Hugging Face Hub 模型仓库
+- `model_filename`: 默认是 `causal_nam_best.pt`
+- `hf_token`: 私有仓库时可传
+- `device`: `cpu` / `cuda` / 自动检测
+- `batch_size`: 批量推理默认 batch 大小
+
+### 方法
+
+- `predict(text, country, year, top_k=5)`
+- `predict_batch(texts, country, year, top_k=5, batch_size=None, return_df=False)`
+- `list_countries()`
+- `list_years(country)`
+- `runtime_info()`
+
+## 设计目标
+
+- Notebook first
+- Kaggle friendly
+- 单次加载，多次复用
+- 单条和批量接口统一
+
+## 模型说明
+
+这个包会打包：
+
+- `preprocess_meta.joblib`
+- `add/` 下的宏观变量 CSV
+
+它不会打包大模型权重文件。运行时会按以下顺序寻找模型：
+
+1. 你显式传入的 `model_path`
+2. 环境变量 `GBERT_MODEL_PATH`
+3. 包目录下的 `causal_nam_best.pt`
+4. Hugging Face Hub (`model_repo_id`)
+
+如果你想通过环境变量控制，也支持：
+
+- `GBERT_MODEL_PATH`
+- `GBERT_MODEL_REPO_ID`
+- `GBERT_MODEL_FILENAME`
+- `HF_TOKEN`
+- `TEXT_MODEL_NAME_OR_PATH`
+- `TORCH_NUM_THREADS`
+
+## 命令行
+
+```bash
+gbert --text "Industrial policy matters." --country Japan --year 2026
+```
+
+## 备注
+
+- 当前宏观数据可支持到 `2026`
+- 对超出训练年份的输入，年份 embedding 会自动回退到模型训练期的最后一年
+- 批量分析建议复用同一个 `GbertClassifier` 实例，不要每条文本重新初始化模型

gbert-0.1.0/gbert/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .service import GbertClassifier, load_default_model, predict, predict_batch
+
+
+__all__ = [
+    "GbertClassifier",
+    "load_default_model",
+    "predict",
+    "predict_batch",
+]

gbert-0.1.0/gbert/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()