Metadata-Version: 2.4
Name: geoffrey-llm
Version: 0.3.0
Summary: A lightweight toolkit for LLM fine-tuning, inference optimization, and agent development
Author-email: Geoffrey <geoffrey@example.com>
License: MIT
Project-URL: Homepage, https://github.com/geoffrey-peng/geoffrey-llm
Project-URL: Repository, https://github.com/geoffrey-peng/geoffrey-llm
Project-URL: Issues, https://github.com/geoffrey-peng/geoffrey-llm/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.3; extra == "ml"
Requires-Dist: numpy>=1.24; extra == "ml"
Requires-Dist: pandas>=2.0; extra == "ml"
Requires-Dist: joblib>=1.3; extra == "ml"
Provides-Extra: dl
Requires-Dist: torch>=2.0; extra == "dl"
Requires-Dist: numpy>=1.24; extra == "dl"
Provides-Extra: finetune
Requires-Dist: torch>=2.0; extra == "finetune"
Requires-Dist: transformers>=4.40; extra == "finetune"
Requires-Dist: peft>=0.10; extra == "finetune"
Requires-Dist: datasets>=2.14; extra == "finetune"
Provides-Extra: geocode
Requires-Dist: rich>=13.0.0; extra == "geocode"
Requires-Dist: prompt-toolkit>=3.0.0; extra == "geocode"
Requires-Dist: httpx>=0.25.0; extra == "geocode"
Requires-Dist: pyyaml>=6.0; extra == "geocode"
Requires-Dist: requests>=2.31.0; extra == "geocode"
Provides-Extra: blog
Requires-Dist: httpx>=0.25.0; extra == "blog"
Provides-Extra: cloud-aws
Requires-Dist: boto3>=1.34; extra == "cloud-aws"
Provides-Extra: cloud-alibaba
Requires-Dist: alibabacloud-ecs20140526>=4.0; extra == "cloud-alibaba"
Requires-Dist: alibabacloud-credentials>=0.3; extra == "cloud-alibaba"
Requires-Dist: alibabacloud-tea-openapi>=0.3; extra == "cloud-alibaba"
Provides-Extra: cloud-tencent
Requires-Dist: tencentcloud-sdk-python-common>=3.0; extra == "cloud-tencent"
Requires-Dist: tencentcloud-sdk-python-cvm>=3.0; extra == "cloud-tencent"
Requires-Dist: tencentcloud-sdk-python-vpc>=3.0; extra == "cloud-tencent"
Requires-Dist: tencentcloud-sdk-python-cdb>=3.0; extra == "cloud-tencent"
Requires-Dist: cos-python-sdk-v5>=1.9; extra == "cloud-tencent"
Provides-Extra: cloud-huawei
Requires-Dist: huaweicloudsdkecs>=3.1; extra == "cloud-huawei"
Requires-Dist: huaweicloudsdkvpc>=3.1; extra == "cloud-huawei"
Requires-Dist: huaweicloudsdkrds>=3.1; extra == "cloud-huawei"
Requires-Dist: esdk-obs-python>=3.24; extra == "cloud-huawei"
Provides-Extra: cloud
Requires-Dist: boto3>=1.34; extra == "cloud"
Requires-Dist: alibabacloud-ecs20140526>=4.0; extra == "cloud"
Requires-Dist: alibabacloud-credentials>=0.3; extra == "cloud"
Requires-Dist: alibabacloud-tea-openapi>=0.3; extra == "cloud"
Requires-Dist: tencentcloud-sdk-python-common>=3.0; extra == "cloud"
Requires-Dist: tencentcloud-sdk-python-cvm>=3.0; extra == "cloud"
Requires-Dist: tencentcloud-sdk-python-vpc>=3.0; extra == "cloud"
Requires-Dist: tencentcloud-sdk-python-cdb>=3.0; extra == "cloud"
Requires-Dist: cos-python-sdk-v5>=1.9; extra == "cloud"
Requires-Dist: huaweicloudsdkecs>=3.1; extra == "cloud"
Requires-Dist: huaweicloudsdkvpc>=3.1; extra == "cloud"
Requires-Dist: huaweicloudsdkrds>=3.1; extra == "cloud"
Requires-Dist: esdk-obs-python>=3.24; extra == "cloud"
Provides-Extra: all
Requires-Dist: geoffrey-llm[blog,dev,dl,finetune,geocode,ml]; extra == "all"
Dynamic: license-file

# geoffrey-llm

[![PyPI version](https://badge.fury.io/py/geoffrey-llm.svg)](https://pypi.org/project/geoffrey-llm/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

一个轻量的 LLM 与多云工具包，包含机器学习、深度学习、agent 构建、大模型微调和多云资源管理模块。每个模块依赖隔离，按需安装。

## 模块总览

| 模块 | 说明 | 安装 extras | 状态 |
|---|---|---|---|
| `geoffrey_llm.ml` | 机器学习(基于 sklearn,统一 API + 中文评估报表) | `[ml]` | ![Active](https://img.shields.io/badge/status-Active-green) |
| `geoffrey_llm.dl` | 深度学习(基于 torch,神经网络封装) | `[dl]` | ![Planned](https://img.shields.io/badge/status-Planned-lightgrey) |
| `geoffrey_llm.geocode` | 大模型 agent 构建(Claude Code 风格 REPL) | `[geocode]` | ![Alpha](https://img.shields.io/badge/status-Alpha-yellow) |
| `geoffrey_llm.blog` | 个人博客 REST API 客户端 | `[blog]` | ![Active](https://img.shields.io/badge/status-Active-green) |
| `geoffrey_llm.finetune` | 大模型微调(LoRA / QLoRA,基于 transformers/peft) | `[finetune]` | ![Planned](https://img.shields.io/badge/status-Planned-lightgrey) |
| `geoffrey_llm.cloud` | 多云核心资源统一入口(阿里云/腾讯云/华为云/AWS) | `[cloud-*]` | ![Alpha](https://img.shields.io/badge/status-Alpha-yellow) |

## 安装

```bash
# 只装机器学习
pip install geoffrey-llm[ml]

# 只装 agent REPL
pip install geoffrey-llm[geocode]

# 只装博客客户端
pip install geoffrey-llm[blog]

# 只装 AWS 多云适配器（其余厂商对应 cloud-alibaba/cloud-tencent/cloud-huawei）
pip install geoffrey-llm[cloud-aws]

# 装全部(含 dev 工具；云 SDK 请按需装 cloud 或单厂商 cloud-*)
pip install geoffrey-llm[all]
```

## 快速上手

### 机器学习模块

```python
from geoffrey_llm.ml import Trainer, Evaluator

# 训练(分类)
trainer = Trainer(task="classification", model_name="random_forest")
trainer.fit(X_train, y_train)
preds = trainer.predict(X_test)

# 评估(中文报表)
print(Evaluator.classification_report(y_test, preds, chinese=True))

# 持久化
trainer.save("model.pkl")
trainer2 = Trainer.load("model.pkl", task="classification", model_name="random_forest")
```

支持的算法:
- **分类**: `random_forest` / `logistic_regression` / `svm` / `gradient_boosting`
- **回归**: `random_forest` / `linear_regression` / `gradient_boosting`

### agent 构建模块(geocode)

```bash
# 命令行启动 REPL
geocode
geocode --provider deepseek --model deepseek-chat
```

```python
from geoffrey_llm.geocode import REPL, BaseModel
from geoffrey_llm.geocode.models.base import get_registry, ModelConfig

config = ModelConfig(model_name="moonshot-v1-8k")
model = get_registry().create("kimi", config)
repl = REPL(model=model)
```

geocode 特性:
- 多模型: Kimi / DeepSeek / Qwen / OpenAI 兼容
- 工具调用: FileRead / FileWrite / FileEdit / Bash(带白名单)
- 文件式记忆系统(yaml frontmatter)
- 会话持久化与 resume
- MCP (Model Context Protocol) 集成

### 博客客户端

博客客户端调用博客的 `API_TOKEN`，不是 Flask 的 `SECRET_KEY`。支持的环境变量优先级为 `BLOG_API_TOKEN`、`BLOG_SECRET`、`BLOG_SERCET`；`BLOG_SERCET` 用于兼容已有配置。

```bash
export BLOG_BASE_URL="https://blog.geoffrey-peng.cc"
export BLOG_SERCET="your-blog-api-token"
```

```python
from geoffrey_llm.blog import BlogClient

with BlogClient() as blog:
    posts = blog.list_posts(page=1, per_page=10)
    blog.create_post(
        title="SDK 发布",
        slug="sdk-release",
        content="通过 geoffrey-llm 发布。",
        category_id=1,
        is_public=True,
    )
```

支持分类、文章 CRUD 和分享链接管理：`list_categories`、`list_posts`、`get_post`、`create_post`、`update_post`、`delete_post`、`create_share`、`list_shares`、`revoke_share`。

### 多云客户端

`cloud` 提供实例、VPC/子网、安全组、对象存储和托管数据库的统一入口。默认只读；安全组规则变更还必须显式打开变更权限并关闭 dry-run。凭据仅由各官方 SDK 的环境变量、配置文件或工作负载角色链解析，不能写入代码或 `CloudConfig`。

```python
from geoffrey_llm.cloud import CloudClient, CloudConfig

cloud = CloudClient(CloudConfig(provider="aws", region="ap-southeast-1"))
instances = cloud.instances.list()
security_groups = cloud.security_groups.list()
buckets = cloud.object_storage.list_buckets()
```

本地无凭据验证可使用内存 Mock provider：

```python
cloud = CloudClient(CloudConfig(provider="mock", region="test-1"))
assert cloud.databases.list()[0].id == "db-demo"
```

官方资料与资源映射存放在仓库根目录 [`.cloud/`](.cloud/)，其中不允许保存密钥或真实资源标识。

## 设计原则

- **依赖隔离**:`import geoffrey_llm` 不拉任何重依赖,各模块按 extras 安装
- **中文友好**:错误信息、评估报表默认中文
- **统一 API**:不同后端(sklearn / lightgbm / xgboost)共用 `Trainer` 入口
- **混合实现**:核心算法用主流库,周边工具(评估/报表/记忆/会话)自己写

## 项目结构

```
geoffrey_llm/
├── common/         # 共享:Registry / BaseConfig / GeoffreyError
├── ml/             # 机器学习
│   ├── trainer.py
│   ├── evaluator.py
│   ├── report.py
│   ├── models.py
│   └── backends/
├── dl/             # 深度学习(占位)
├── geocode/        # agent 构建
│   ├── cli.py / repl.py
│   ├── models/ tools/ memory/ session/ cmd/ mcp/ prompts/
├── blog/           # 个人博客 REST API 客户端
└── finetune/       # 大模型微调(占位)
```

## License

MIT

## Roadmap

- [ ] `ml`: lightgbm / xgboost 后端
- [ ] `ml`: 场景化 pipeline(表格分类一键流程)
- [ ] `ml`: 特征工程 / 自动调参 / 模型解释性
- [ ] `dl`: CNN / RNN / Transformer 封装,DLTrainer
- [ ] `finetune`: LoRATrainer / QLoRATrainer / DatasetPreprocessor
- [ ] `geocode`: 更多 provider、工具系统增强
