autoforge-trainer 1.0.2__tar.gz

autoforge_trainer-1.0.2/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+runs/
+dist/
+site/

autoforge_trainer-1.0.2/AGENTS.md

@@ -0,0 +1,100 @@
+# AGENTS.md — 給 AI 的使用說明
+
+You are operating AutoForge, a tool that trains AI models on the user's machine.
+Prefer the MCP server (`autoforge mcp`, tools listed in docs/MCP.md) when your client supports MCP;
+the CLI below offers the same operations with `--json`.
+
+## Rules
+1. Always call `autoforge doctor --json` first to learn the hardware.
+2. Every command accepts `--json` and returns `{"ok": bool, "data": ..., "error": {"code","message","hint"}}`.
+   Branch on `error.code`, and follow `error.hint`.
+3. Read data contracts with `autoforge schema <Name> --json` instead of guessing fields.
+4. Privacy: if an error has code `PRIVACY_DENIED`, do not retry. Tell the user the dataset
+   is sensitive and needs a local-model brain.
+5. Training is asynchronous: `run start` returns a `run_id` at once; poll `run status <id>`.
+6. Identify yourself: pass `--actor ai:<your-name>` (or set AUTOFORGE_ACTOR) so the audit log
+   shows who did what. Humans and AI share the same controls.
+
+## Data and privacy
+- `autoforge data profile <path> --json` (MCP: `data_profile`): rows, columns, dtypes, missing values.
+- Data is `internal` unless a human marked it. Cloud AI sees statistics only; `public` data adds
+  sample rows; `sensitive` data is refused with PRIVACY_DENIED. Never try to change sensitivity.
+
+## Finding and learning a training method
+1. `autoforge pack search [keywords] --task <task-type> --fit --json`
+   `--fit` keeps only recipes this machine can run. Each hit lists `runnable_recipes`.
+2. `autoforge pack install <name> --json` installs the commit pinned in the index.
+3. `autoforge pack info <name> --json` returns the manifest, recipes (defaults, search space)
+   and `knowledge` (KNOWLEDGE.md). **Read `knowledge` before planning.**
+4. If `missing_dependencies` is non-empty, tell the user to `pip install` them.
+
+## Training (P3)
+1. Write a plan file (schema: `autoforge schema TrainingPlan --json`). Paths are relative to the plan file.
+   Example: `examples/churn_plan.yaml`.
+2. `autoforge plan validate plan.yaml --json`: deterministic checks (pack/recipe/task match,
+   data and target column exist, GPU/VRAM, missing packages). Fix every `problems` item.
+3. `autoforge run start plan.yaml --json --actor ai:<name>` → `data.run_id`
+4. Poll `autoforge run status <id> --json` (status: pending/running/paused/succeeded/failed/stopped).
+   For progress use `autoforge run metrics <id> --json` (last/min/max/count/recent per metric);
+   on failure read `autoforge run logs <id> --tail 50 --json`.
+5. Control: `run pause | resume | stop <id>`; `run retry <id>` reruns the plan and resumes from checkpoints.
+6. Custom trainers: set `custom_code_path: my_trainer.py[:function]` instead of pack+recipe.
+   The code is copied into the run and committed to the run's git repo. Contract: docs/PACK_SPEC.md §5.
+
+## Improving a model (P5)
+- `run diagnose <id>` / MCP `run_diagnose`: findings (failure cause, divergence, plateau, overfitting,
+  leakage) with suggestions and the tunable hyperparameters.
+- `hpo start plan.yaml -m <metric> -n <trials>` / MCP `hpo_start` → `hpo_wait`: search; trial 0 is the
+  plan's own hyperparameters (baseline); report `improvement`.
+- `run adjust <id> --set k=v` / MCP `run_adjust`: change a live run (trainer must call ctx.check_updates()).
+- `run compare <ids...> -m <metric>` / MCP `run_compare`: pick the best run.
+
+## Deploying a model (P6)
+- `model register <run_id> --name <name>` / MCP `model_register`: versioned model (name:vN) with a card
+  (features, labels, metrics). Only succeeded runs; servable when the recipe has a predictor.
+- `model predict <name> --rows '[{...}]'` / MCP `model_predict`: rows need every feature from `model info`.
+- `model export <name> --format bundle|onnx` / MCP `model_export`.
+- Humans run `autoforge serve` (REST) and `autoforge serve-mcp` (each model as tool `predict_<name>`).
+
+## Writing a new pack (P7)
+- MCP `pack_create(name, files)` writes a pack into the workspace and validates it (nothing runs);
+  `pack_test(path)` runs its tests; `pack_install(path)` installs it. CLI: `pack new`, `pack test`.
+- To turn a GitHub training repo into a pack: read the repo, write pack.yaml + KNOWLEDGE.md + recipes +
+  a trainer using the TrainContext contract (docs/PACK_SPEC.md §5) + a CPU smoke test, then create/test/install.
+
+## Error codes
+| code | meaning | what to do |
+|---|---|---|
+| PACK_NOT_FOUND | name not in index / not installed | search again |
+| PACK_EXISTS | already installed | use it, or reinstall with `--force` |
+| PACK_INVALID | pack fails validation; `data.problems` lists why | do not use it |
+| SHA_MISMATCH | source changed after indexing | do not install; tell the user |
+| INDEX_UNAVAILABLE | index unreachable and no cache | retry later or set AUTOFORGE_INDEX_URL |
+| PACK_SOURCE_ERROR | bad source string or git failure | check the source |
+| PLAN_INVALID | plan fails checks; `data.problems` lists why | fix the plan, validate again |
+| RUN_NOT_FOUND | unknown run_id | `run list` |
+| RUN_STATE_ERROR | action not possible in the run's current state | check `run status` |
+| PRIVACY_DENIED | dataset is sensitive and you are not a local model | stop; tell the user |
+| BAD_REQUEST | invalid argument (e.g. trainer filename, syntax error) | fix and retry |
+| STUDY_NOT_FOUND | unknown study_id | `hpo list` |
+| HPO_UNAVAILABLE | optuna not installed | tell the user: pip install optuna |
+| MODEL_NOT_FOUND | unknown model or version | `model list` |
+| MODEL_NOT_SERVABLE | recipe has no predictor | train with a recipe that has one |
+| INVALID_INPUT | rows missing features / wrong types; `data.features` lists them | fix the rows |
+| MODEL_ERROR | register/export/predict failed | read the message |
+| PACK_AUTHORING_ERROR | bad name, unsafe path, pack exists | fix and retry (overwrite=true to replace) |
+| PACK_TEST_FAILED | pack smoke tests failed; `data.output_tail` | fix the pack |
+
+## Commands available now (1.0)
+- `quickstart` (end-to-end demo on bundled data)
+- `gui` (local web interface for humans; actor "human")
+- `pack new | test`
+- `model register | list | info | predict | export | import | remove`, `serve`, `serve-mcp`
+- `hpo start | status | list | stop`, `run diagnose | adjust | compare`
+- `train "<goal>" --data <path> --brain <provider:model>` (built-in agent; see docs/AGENT.md)
+- `mcp` (MCP server over stdio), `data mark | list | profile`
+- `version`, `doctor`, `schema [Name]`
+- `plan validate`
+- `run start | status | list | pause | resume | stop | retry | logs | metrics | audit`
+- `pack search | install | info | list | remove | validate`
+- `index entry | add | validate` (for index maintainers)

autoforge_trainer-1.0.2/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 變更紀錄
+
+## 1.0.2 — 2026-10
+
+- **PyPI 套件名稱改為 `autoforge-trainer`**：`autoforge-ml` 在我們發佈前被別人註冊了。指令和 `import autoforge` 都不變。1.0.1 沒有上傳到 PyPI。
+
+## 1.0.1 — 2026-10
+
+- **PyPI 套件名稱改為 `autoforge-ml`**：`autoforge-ai` 和 PyPI 上既有的 `autoforgeai` 太相似，無法註冊。指令和 `import autoforge` 都不變。
+- 修正：`run adjust` 的參數修改偶爾沒有寫進訓練資料夾的 git 紀錄（稽核紀錄不受影響）。原因是 `git add -A` 剛好碰到訓練程式寫檔時暫時產生的檔案；現在只加入需要保存版本的檔案。這個問題是 CI 發現的。
+
+## 1.0.0 — 2026-10
+
+第一個正式版本。PyPI 套件名稱為 `autoforge-ai`，指令仍是 `autoforge`。
+
+### 功能（依開發階段）
+- **P1 骨架**：硬體偵測（NVIDIA GPU / CUDA），所有指令都能輸出 JSON，資料結構可匯出 JSON Schema。
+- **P2 方法包**：`pack.yaml` 格式、驗證（不執行程式碼）；從本地資料夾或 GitHub 安裝並鎖定 commit；索引放在 `packs-index` 分支。
+- **P3 執行引擎**：每次訓練在獨立行程執行；可以暫停、繼續、停止，也能從 checkpoint 重跑；稽核紀錄寫明是人還是 AI 操作；計畫和程式碼用 git 保存版本。
+- **P4a MCP**：`autoforge mcp`，讓訂閱制 AI（Claude Desktop、Claude Code）直接操作；隱私守衛：敏感資料只給本地模型使用。
+- **P4b 內建 AI 代理**：`autoforge train "需求"`，支援 Claude（官方 SDK）、OpenAI 相容 API、Ollama 和本地模型；開始訓練前會請人確認。
+- **P5 改進模型**：診斷、自動調參（Optuna，第 0 次為基準）、訓練中途調整參數、比較多次訓練。
+- **P6 部署**：模型倉庫（模型會連同訓練它的程式碼一起保存）、REST API、每個模型變成一個 MCP 工具、匯出 bundle 或 ONNX。
+- **P7 方法包**：tabular-classic、text-classification、llm-finetune（LoRA/QLoRA）、image-classification、timeseries-forecast、anomaly-detection；另有 `pack new`、`pack test`、MCP `pack_create`。
+- **P8 網頁介面**：`autoforge gui`，只在本機開放，用一次性 token 保護。
+- **P9 發佈**：`autoforge quickstart`、PyPI 打包、Docker 映像（CPU 和 CUDA）、文件網站、自動發佈流程。
+
+### 已知限制
+- GPU 方法（Transformer、LLM LoRA/QLoRA、timm）只用極小模型在 CPU 上驗證過程式能跑通，尚未在真的 NVIDIA GPU 上實測。
+- 自動調參的最佳分數是用同一份驗證資料挑出來的，會稍微偏樂觀。
+- 內建 AI 代理選方法的品質，還沒用真的 Claude API 做系統性評估。

autoforge_trainer-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Honguan and AutoForge 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.

autoforge_trainer-1.0.2/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: autoforge-trainer
+Version: 1.0.2
+Summary: AI that trains AI: analyse your data and hardware, pick a method, train, tune and deploy models on your own machine — from a CLI, MCP, a web GUI or one sentence.
+Project-URL: Homepage, https://github.com/Honguan/autoforge
+Project-URL: Documentation, https://honguan.github.io/autoforge/
+Project-URL: Source, https://github.com/Honguan/autoforge
+Project-URL: Issues, https://github.com/Honguan/autoforge/issues
+Project-URL: Changelog, https://github.com/Honguan/autoforge/blob/main/CHANGELOG.md
+Author: Honguan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,automl,fine-tuning,llm,lora,machine-learning,mcp,training
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Chinese (Traditional)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.0
+Requires-Dist: joblib>=1.3
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: optuna<6,>=5.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: starlette>=0.40
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: all
+Requires-Dist: accelerate>=0.30; extra == 'all'
+Requires-Dist: anthropic<2,>=1.14; extra == 'all'
+Requires-Dist: nvidia-ml-py>=12.0; extra == 'all'
+Requires-Dist: onnx>=1.16; extra == 'all'
+Requires-Dist: onnxruntime>=1.18; extra == 'all'
+Requires-Dist: onnxscript>=0.1; extra == 'all'
+Requires-Dist: peft>=0.12; extra == 'all'
+Requires-Dist: pillow>=10.0; extra == 'all'
+Requires-Dist: skl2onnx>=1.17; extra == 'all'
+Requires-Dist: timm>=1.0; extra == 'all'
+Requires-Dist: torch>=2.3; extra == 'all'
+Requires-Dist: torchvision>=0.18; extra == 'all'
+Requires-Dist: transformers>=4.45; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic<2,>=1.14; extra == 'anthropic'
+Provides-Extra: deep
+Requires-Dist: accelerate>=0.30; extra == 'deep'
+Requires-Dist: nvidia-ml-py>=12.0; extra == 'deep'
+Requires-Dist: peft>=0.12; extra == 'deep'
+Requires-Dist: pillow>=10.0; extra == 'deep'
+Requires-Dist: timm>=1.0; extra == 'deep'
+Requires-Dist: torch>=2.3; extra == 'deep'
+Requires-Dist: torchvision>=0.18; extra == 'deep'
+Requires-Dist: transformers>=4.45; extra == 'deep'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: playwright>=1.45; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: nvidia-ml-py>=12.0; extra == 'gpu'
+Requires-Dist: torch>=2.3; extra == 'gpu'
+Provides-Extra: hpo
+Provides-Extra: onnx
+Requires-Dist: onnx>=1.16; extra == 'onnx'
+Requires-Dist: onnxruntime>=1.18; extra == 'onnx'
+Requires-Dist: onnxscript>=0.1; extra == 'onnx'
+Requires-Dist: skl2onnx>=1.17; extra == 'onnx'
+Description-Content-Type: text/markdown
+
+# AutoForge
+
+讓 AI 自己分析需求、選擇方法、訓練、評估、部署 AI 模型的可安裝平台。
+
+- **三種 AI 大腦**：訂閱制 AI（透過 MCP）、雲端 API、本地模型
+- **硬體**：NVIDIA GPU（CUDA），沒有 GPU 時自動改用 CPU
+- **方法包**：從 GitHub 安裝的「教學包」，AI 讀了就知道怎麼訓練
+- **隱私**：敏感資料只允許本地模型指揮
+
+> **1.0.2** · 文件網站：<https://honguan.github.io/autoforge/> · [變更紀錄](CHANGELOG.md)
+
+## 安裝與第一次使用
+
+```bash
+pip install autoforge-trainer          # 需要 Python 3.11 以上
+autoforge quickstart              # 約 1 分鐘：檢查硬體 → 安裝方法包 → 訓練 → 註冊 → 預測
+autoforge gui                     # 網頁介面
+```
+
+| 安裝方式 | 包含 |
+|---|---|
+| `pip install autoforge-trainer` | 表格、文字（TF-IDF）、時間序列、異常偵測、自動調參、網頁介面、MCP、REST |
+| `pip install "autoforge-trainer[deep]"` | 再加上 Transformer、LLM 微調（LoRA/QLoRA）、圖片分類（NVIDIA GPU） |
+| `pip install "autoforge-trainer[all]"` | 再加上 Claude 代理、ONNX 匯出 |
+| `docker run --rm -p 127.0.0.1:8800:8800 -v autoforge:/data ghcr.io/honguan/autoforge:cpu` | CPU 映像，預設啟動網頁介面 |
+| `docker run --rm --gpus all -p 127.0.0.1:8800:8800 -v autoforge:/data ghcr.io/honguan/autoforge:cuda` | NVIDIA CUDA 映像，所有方法包 |
+
+PyPI 上的 `autoforge` 是另一個不相關的專案（`autoforge-ai`、`autoforge-ml` 也都無法使用），請安裝 **`autoforge-trainer`**；裝好之後指令一樣是 `autoforge`。
+
+操作方式：[網頁介面](docs/GUI.md) · [一句話訓練](docs/AGENT.md) · [讓訂閱制 AI 透過 MCP 操作](docs/MCP.md) · [改進模型](docs/IMPROVE.md) · [部署](docs/DEPLOY.md) · [架構](docs/ARCHITECTURE.md) · [路線圖](docs/ROADMAP.md)
+
+## 內建方法包
+
+| 方法包 | 用途 | 方法 | 硬體 |
+|---|---|---|---|
+| `tabular-classic` | 表格分類、回歸 | 邏輯迴歸、隨機森林（可匯出 ONNX） | CPU |
+| `text-classification` | 文字分類（情緒、意圖、主題、垃圾訊息） | TF-IDF + 線性模型；Transformer 微調 | CPU / GPU |
+| `llm-finetune` | 大型語言模型微調 | LoRA / QLoRA（可匯出合併後的權重） | GPU（8GB+） |
+| `image-classification` | 圖片分類 | timm 預訓練模型微調（可匯出 ONNX） | GPU 建議，CPU 可跑小模型 |
+| `timeseries-forecast` | 時間序列預測（銷量、用電、流量） | 落後特徵 + 梯度提升，和「明天＝今天」的基準比較 | CPU |
+| `anomaly-detection` | 異常偵測（詐欺、故障、離群值） | Isolation Forest | CPU |
+
+每個方法包都附給 AI 讀的 `KNOWLEDGE.md`，以及在 CPU 上 30 秒內跑完的測試。自己做方法包：`autoforge pack new`（見 [docs/PACK_SPEC.md](docs/PACK_SPEC.md)）。
+
+## 從原始碼開發
+
+```bash
+git clone https://github.com/Honguan/autoforge && cd autoforge
+pip install -e ".[dev]"            # 加上 ,deep 安裝深度學習方法包的依賴
+pytest -q
+```
+
+## 網頁介面
+
+```bash
+autoforge gui      # 打開瀏覽器：上傳資料 → 選任務 → 選方法 → 訓練 → 調參 → 註冊 → 預測
+```
+
+## 使用
+
+```bash
+autoforge doctor               # 偵測硬體
+autoforge doctor --json        # 給 AI 讀的 JSON
+autoforge schema               # 列出所有資料結構
+autoforge schema TrainingPlan --json
+
+# 方法包
+autoforge pack search csv --fit            # 搜尋這台電腦跑得動的方法包
+autoforge pack install tabular-classic    # 從索引安裝（鎖定 commit）
+autoforge pack install ./packs/tabular-classic   # 從本地資料夾安裝
+autoforge pack install github:owner/repo/subdir@v1.0.0
+autoforge pack info tabular-classic --json       # 給 AI 讀的知識和方法
+autoforge pack list
+
+# 訓練
+autoforge plan validate examples/churn_plan.yaml     # 檢查訓練計畫
+autoforge run start examples/churn_plan.yaml --wait  # 訓練並即時顯示進度
+autoforge run start plan.yaml --json                 # 背景訓練，立即回傳 run_id（給 AI 用）
+autoforge run status <run_id>
+autoforge run pause|resume|stop <run_id>
+autoforge run metrics|logs|audit <run_id>
+autoforge run retry <run_id>                         # 同計畫重跑，從 checkpoint 接續
+```
+
+每次訓練的所有檔案都在 `~/.autoforge/runs/<run_id>/`：計畫、模型、checkpoint、日誌、指標、稽核紀錄，計畫和 AI 寫的程式會用 git 版本管理。
+
+方法包格式見 [docs/PACK_SPEC.md](docs/PACK_SPEC.md)，索引放在本 repo 的 [`packs-index` 分支](https://github.com/Honguan/autoforge/tree/packs-index)。
+
+## 改進模型
+
+```bash
+autoforge run diagnose <run_id>                                       # 找問題、給建議
+autoforge hpo start examples/churn_plan.yaml -m f1_macro -n 20 --wait # 自動調參（trial 0 = 基準）
+autoforge run adjust <run_id> --set learning_rate=0.0003              # 訓練中途改參數
+autoforge run compare <id1> <id2> -m f1_macro                         # 比較
+```
+
+## 部署
+
+```bash
+autoforge model register <run_id> --name churn      # 註冊成模型（v1、v2…）
+autoforge model predict churn --rows '[{...}]'       # 預測
+autoforge serve                                      # REST API（127.0.0.1:8000）
+autoforge serve-mcp                                  # 每個模型變成 MCP 工具 predict_<名稱>，給其他 AI 呼叫
+autoforge model export churn --format onnx           # 匯出
+```
+
+## 一句話訓練（內建 AI 代理）
+
+```bash
+pip install -e ".[anthropic]"
+autoforge train "預測 churned 欄位" --data examples/data/churn.csv                   # Claude（預設）
+autoforge train "預測 churned 欄位" --data examples/data/churn.csv --brain ollama:qwen3   # 本地模型
+```
+
+詳見 [docs/AGENT.md](docs/AGENT.md)。
+
+## 讓 AI 操作（MCP）
+
+```bash
+claude mcp add autoforge -- autoforge mcp --actor ai:claude-code   # Claude Code
+```
+
+Claude Desktop 和隱私設定見 [docs/MCP.md](docs/MCP.md)。
+
+```bash
+autoforge data mark ~/data/customers -s sensitive   # 敏感資料：雲端 AI 不能使用
+```
+
+## 測試
+
+```bash
+pytest
+```

autoforge_trainer-1.0.2/README.md

@@ -0,0 +1,134 @@
+# AutoForge
+
+讓 AI 自己分析需求、選擇方法、訓練、評估、部署 AI 模型的可安裝平台。
+
+- **三種 AI 大腦**：訂閱制 AI（透過 MCP）、雲端 API、本地模型
+- **硬體**：NVIDIA GPU（CUDA），沒有 GPU 時自動改用 CPU
+- **方法包**：從 GitHub 安裝的「教學包」，AI 讀了就知道怎麼訓練
+- **隱私**：敏感資料只允許本地模型指揮
+
+> **1.0.2** · 文件網站：<https://honguan.github.io/autoforge/> · [變更紀錄](CHANGELOG.md)
+
+## 安裝與第一次使用
+
+```bash
+pip install autoforge-trainer          # 需要 Python 3.11 以上
+autoforge quickstart              # 約 1 分鐘：檢查硬體 → 安裝方法包 → 訓練 → 註冊 → 預測
+autoforge gui                     # 網頁介面
+```
+
+| 安裝方式 | 包含 |
+|---|---|
+| `pip install autoforge-trainer` | 表格、文字（TF-IDF）、時間序列、異常偵測、自動調參、網頁介面、MCP、REST |
+| `pip install "autoforge-trainer[deep]"` | 再加上 Transformer、LLM 微調（LoRA/QLoRA）、圖片分類（NVIDIA GPU） |
+| `pip install "autoforge-trainer[all]"` | 再加上 Claude 代理、ONNX 匯出 |
+| `docker run --rm -p 127.0.0.1:8800:8800 -v autoforge:/data ghcr.io/honguan/autoforge:cpu` | CPU 映像，預設啟動網頁介面 |
+| `docker run --rm --gpus all -p 127.0.0.1:8800:8800 -v autoforge:/data ghcr.io/honguan/autoforge:cuda` | NVIDIA CUDA 映像，所有方法包 |
+
+PyPI 上的 `autoforge` 是另一個不相關的專案（`autoforge-ai`、`autoforge-ml` 也都無法使用），請安裝 **`autoforge-trainer`**；裝好之後指令一樣是 `autoforge`。
+
+操作方式：[網頁介面](docs/GUI.md) · [一句話訓練](docs/AGENT.md) · [讓訂閱制 AI 透過 MCP 操作](docs/MCP.md) · [改進模型](docs/IMPROVE.md) · [部署](docs/DEPLOY.md) · [架構](docs/ARCHITECTURE.md) · [路線圖](docs/ROADMAP.md)
+
+## 內建方法包
+
+| 方法包 | 用途 | 方法 | 硬體 |
+|---|---|---|---|
+| `tabular-classic` | 表格分類、回歸 | 邏輯迴歸、隨機森林（可匯出 ONNX） | CPU |
+| `text-classification` | 文字分類（情緒、意圖、主題、垃圾訊息） | TF-IDF + 線性模型；Transformer 微調 | CPU / GPU |
+| `llm-finetune` | 大型語言模型微調 | LoRA / QLoRA（可匯出合併後的權重） | GPU（8GB+） |
+| `image-classification` | 圖片分類 | timm 預訓練模型微調（可匯出 ONNX） | GPU 建議，CPU 可跑小模型 |
+| `timeseries-forecast` | 時間序列預測（銷量、用電、流量） | 落後特徵 + 梯度提升，和「明天＝今天」的基準比較 | CPU |
+| `anomaly-detection` | 異常偵測（詐欺、故障、離群值） | Isolation Forest | CPU |
+
+每個方法包都附給 AI 讀的 `KNOWLEDGE.md`，以及在 CPU 上 30 秒內跑完的測試。自己做方法包：`autoforge pack new`（見 [docs/PACK_SPEC.md](docs/PACK_SPEC.md)）。
+
+## 從原始碼開發
+
+```bash
+git clone https://github.com/Honguan/autoforge && cd autoforge
+pip install -e ".[dev]"            # 加上 ,deep 安裝深度學習方法包的依賴
+pytest -q
+```
+
+## 網頁介面
+
+```bash
+autoforge gui      # 打開瀏覽器：上傳資料 → 選任務 → 選方法 → 訓練 → 調參 → 註冊 → 預測
+```
+
+## 使用
+
+```bash
+autoforge doctor               # 偵測硬體
+autoforge doctor --json        # 給 AI 讀的 JSON
+autoforge schema               # 列出所有資料結構
+autoforge schema TrainingPlan --json
+
+# 方法包
+autoforge pack search csv --fit            # 搜尋這台電腦跑得動的方法包
+autoforge pack install tabular-classic    # 從索引安裝（鎖定 commit）
+autoforge pack install ./packs/tabular-classic   # 從本地資料夾安裝
+autoforge pack install github:owner/repo/subdir@v1.0.0
+autoforge pack info tabular-classic --json       # 給 AI 讀的知識和方法
+autoforge pack list
+
+# 訓練
+autoforge plan validate examples/churn_plan.yaml     # 檢查訓練計畫
+autoforge run start examples/churn_plan.yaml --wait  # 訓練並即時顯示進度
+autoforge run start plan.yaml --json                 # 背景訓練，立即回傳 run_id（給 AI 用）
+autoforge run status <run_id>
+autoforge run pause|resume|stop <run_id>
+autoforge run metrics|logs|audit <run_id>
+autoforge run retry <run_id>                         # 同計畫重跑，從 checkpoint 接續
+```
+
+每次訓練的所有檔案都在 `~/.autoforge/runs/<run_id>/`：計畫、模型、checkpoint、日誌、指標、稽核紀錄，計畫和 AI 寫的程式會用 git 版本管理。
+
+方法包格式見 [docs/PACK_SPEC.md](docs/PACK_SPEC.md)，索引放在本 repo 的 [`packs-index` 分支](https://github.com/Honguan/autoforge/tree/packs-index)。
+
+## 改進模型
+
+```bash
+autoforge run diagnose <run_id>                                       # 找問題、給建議
+autoforge hpo start examples/churn_plan.yaml -m f1_macro -n 20 --wait # 自動調參（trial 0 = 基準）
+autoforge run adjust <run_id> --set learning_rate=0.0003              # 訓練中途改參數
+autoforge run compare <id1> <id2> -m f1_macro                         # 比較
+```
+
+## 部署
+
+```bash
+autoforge model register <run_id> --name churn      # 註冊成模型（v1、v2…）
+autoforge model predict churn --rows '[{...}]'       # 預測
+autoforge serve                                      # REST API（127.0.0.1:8000）
+autoforge serve-mcp                                  # 每個模型變成 MCP 工具 predict_<名稱>，給其他 AI 呼叫
+autoforge model export churn --format onnx           # 匯出
+```
+
+## 一句話訓練（內建 AI 代理）
+
+```bash
+pip install -e ".[anthropic]"
+autoforge train "預測 churned 欄位" --data examples/data/churn.csv                   # Claude（預設）
+autoforge train "預測 churned 欄位" --data examples/data/churn.csv --brain ollama:qwen3   # 本地模型
+```
+
+詳見 [docs/AGENT.md](docs/AGENT.md)。
+
+## 讓 AI 操作（MCP）
+
+```bash
+claude mcp add autoforge -- autoforge mcp --actor ai:claude-code   # Claude Code
+```
+
+Claude Desktop 和隱私設定見 [docs/MCP.md](docs/MCP.md)。
+
+```bash
+autoforge data mark ~/data/customers -s sensitive   # 敏感資料：雲端 AI 不能使用
+```
+
+## 測試
+
+```bash
+pytest
+```

autoforge_trainer-1.0.2/autoforge/__init__.py

@@ -0,0 +1,3 @@
+"""AutoForge: AI that trains AI."""
+
+__version__ = "1.0.2"