Skip to content
gitstqPublic

About

🦞 Zero-dependency classic RL environments & tabular agents in pure Python (bandits, GridWorld, FrozenLake, CliffWalking, Q-Learning/SARSA, DP). 零依赖纯Python经典强化学习工具箱。

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

🦞 tinyrl

零依赖纯 Python 的经典强化学习环境与表格型智能体工具箱

一个文件都不用装,python 就能跑通「环境 → 智能体 → 训练 → 评估 → 报告」的完整闭环。

Python Zero Dependencies License: MIT Tests

🌐 语言 / Language: 简体中文 | 繁體中文 | English


🎉 项目介绍

tinyrl 是一个零运行时依赖、纯标准库实现的经典强化学习(Reinforcement Learning)工具箱:内置多臂老虎机、网格世界、冰湖行走、悬崖行走等经典环境,并配套 ε-Greedy、UCB1、Thompson Sampling、Q-Learning、Sarsa、Expected Sarsa、价值迭代、策略迭代等开箱即用的算法。

😮‍💨 它解决了什么痛点

  • 主流 RL 环境栈(gymnasium + numpy + mujoco……)安装重、编译难,在离线机器、受限 CI、嵌入式 Python、教学机房里经常第一步就卡在环境配置;
  • 机器人/物理仿真环境依赖显示与原生二进制,想快速验证一个算法想法却跑不起来;
  • 框架封装层太厚,初学者看不清「一次交互」内部到底发生了什么;
  • 实验随机源散落各处,结果不可复现,教学演示与回归测试都很痛苦。

✅ 自研差异化亮点

  • 真·零依赖:只用 Python 3.8+ 标准库,不需要编译任何东西,拷贝整个目录即可运行;
  • 种子级可复现:所有随机性都来自显式 random.Random,同种子逐位复现实验轨迹;
  • 环境与算法双覆盖:既有「无模型」的 TD 控制,也有「基于模型」的动态规划,可以对照学习;
  • 教科书级对照实验:悬崖行走环境中可稳定复现「Q-Learning 走最短险路(-13)、Sarsa 走安全远路(-17)、Expected Sarsa 居中(-15)」的经典结论;
  • 双形态使用:既是可 import 的算法库,也提供 tinyrl 命令行,一行命令出对比报告;
  • 工程完备:71 个标准库单元测试、类型注解、ASCII 渲染、学习曲线、JSON/CSV 报告导出。

💡 灵感来源:本项目在 GitHub Trending 上关注到绑定 MuJoCo 物理引擎的机器人 RL 训练环境项目(需要重型原生依赖与显示环境)。我们没有复制其任何代码,而是反向思考其痛点,独立自研了一个在任何机器上秒级跑通的轻量替代形态,专注于经典表格型 RL 的学习、教学与快速实验。


✨ 核心特性

🎰 环境(Environments)

环境 说明 可配置点
MultiArmedBandit 多臂老虎机,单状态探索-利用问题 臂数量、伯努利/高斯/确定性分布
GridWorld 通用网格世界,到达目标即胜利 尺寸、墙体、起点终点、步惩罚、随机打滑
FrozenLake 冰湖行走(4×4 / 8×8 / 自定义地图) 地图、是否打滑、最大步数
CliffWalking Sutton 教科书悬崖行走 尺寸、悬崖惩罚、步惩罚

🤖 智能体与算法(Agents)

  • 多臂老虎机:EpsilonGreedy(支持乐观初始值 Q0 与固定学习率)、UCB1、ThompsonBernoulli
  • 时序差分控制:QLearningAgent(异策略)、SarsaAgent(同策略)、ExpectedSarsaAgent(低方差)
  • 动态规划:value_iteration(价值迭代)、policy_iteration(策略迭代),并可把策略渲染成箭头地图

🛠️ 工程能力

  • ⚙️ 实验引擎:train / evaluate / run_bandit,训练与评估严格分离
  • 📊 报告系统:指标汇总、Unicode 迷你学习曲线(▁▂▃▄▅▆▇█)、JSON / CSV 导出
  • 🖥️ 命令行工具:4 个子命令覆盖算法对比、训练演示、规划演示
  • 🔁 统一接口:接近 Gymnasium 风格的 reset / step,学到的概念可无缝迁移到主流框架
  • 🧪 零依赖测试:测试同样只用标准库 unittest,python -m unittest discover 即可

🧱 项目结构

tinyrl/
├── tinyrl/                  # 核心包
│   ├── core.py              # 环境抽象、离散空间、随机源、贪心工具
│   ├── envs/                # 环境:老虎机 / 网格世界 / 冰湖 / 悬崖
│   ├── agents/              # 智能体:老虎机算法 / TD 控制 / 动态规划
│   ├── engine.py            # 训练、评估、老虎机实验引擎
│   ├── report.py            # 指标统计、迷你曲线、JSON/CSV 导出
│   └── cli.py               # tinyrl 命令行入口
├── examples/                # 4 个可直接运行的示例
├── tests/                   # 71 个单元测试(标准库 unittest)
├── docs/                    # 繁體中文 / English 文档
├── pyproject.toml           # 打包配置(零运行时依赖)
└── LICENSE                  # MIT

🚀 快速开始

📋 环境要求

  • Python 3.8 及以上(3.8 / 3.9 / 3.10 / 3.11 / 3.12 均验证通过)
  • 无需任何第三方运行时依赖,不联网、不编译

方式一:免安装,克隆即用(推荐先体验)

git clone https://github.com/gitstq/tinyrl.git
cd tinyrl
python -m tinyrl.cli demo-bandits

方式二:作为包安装

# 从源码安装(会注册 tinyrl 命令)
pip install .

# 之后在任意目录使用
tinyrl demo-grid --env frozenlake --agent q --episodes 4000

方式三:一键跑全部示例

python examples/01_bandits.py
python examples/02_frozenlake_qlearning.py
python examples/03_cliff_comparison.py
python examples/04_value_iteration.py

⚡ 30 秒最小示例

from tinyrl.envs import FrozenLake
from tinyrl.agents import QLearningAgent
from tinyrl.engine import train, evaluate

env = FrozenLake()                       # 打滑的 4×4 冰湖
agent = QLearningAgent(
    n_states=env.observation_space.n,
    n_actions=env.action_space.n,
    alpha=0.25, gamma=0.99, epsilon=0.1, seed=42,
)

train(env, agent, episodes=4000, seed=42)          # 训练
print(evaluate(FrozenLake(), agent, 500, 9999))    # 贪心评估
# {'episodes': 500, 'avg_return': 0.796, 'avg_steps': 49.8, 'success_rate': 0.796, ...}

📖 详细使用指南

💻 命令行(CLI)

子命令 作用
tinyrl demo-bandits 三种老虎机算法同台对比(平均奖励、最优臂选择率、累计遗憾)
tinyrl demo-grid 在指定网格环境训练一个 TD 智能体,输出学习曲线、评估指标与贪心轨迹
tinyrl demo-plan 价值迭代 / 策略迭代求解,并打印最优策略箭头地图
tinyrl compare Q-Learning / Sarsa / Expected Sarsa 横向对比,可导出 JSON、CSV

常用参数:

# 选择环境与算法、调节超参
tinyrl demo-grid --env cliff --agent sarsa --episodes 2000 \
                 --alpha 0.3 --gamma 0.99 --epsilon 0.1 --seed 7

# 三算法对比并落盘报告(便于 CI 或写实验报告)
tinyrl compare --env frozenlake --episodes 4000 \
               --json report.json --csv report.csv
参数 含义 默认值
--env 网格环境:gridworld / frozenlake / cliff frozenlake
--agent 算法:q / sarsa / expected q
--episodes 训练回合数 4000
--alpha 学习率 0.25
--gamma 折扣因子 0.99
--epsilon ε-贪心探索率 0.1
--seed 随机种子(保证可复现) 42

真实运行输出(悬崖环境三算法对比):

$ tinyrl compare --env cliff --episodes 2000 --seed 7
agent         tail_return  tail_succ%  eval_return  eval_succ%
--------------------------------------------------------------
q                 -52.610      100.0%      -13.000      100.0%
sarsa             -22.485      100.0%      -17.000      100.0%
expected          -21.020      100.0%      -15.000      100.0%

📌 输出解读:训练期(tail)因为 ε 随机探索会偶尔坠崖,回报偏低;评估期切换为纯贪心策略后,三种算法全部 100% 到达终点。Q-Learning 学到贴悬崖的最短路径(-13),Sarsa 因惧怕探索期坠崖而主动绕行(-17),Expected Sarsa 居中(-15)。

🧩 作为库使用

1)自定义网格世界(墙体 + 随机打滑):

from tinyrl.envs import GridWorld

env = GridWorld(
    rows=5, cols=5,
    start=(0, 0), goal=(4, 4),
    walls=frozenset({(1, 1), (2, 3)}),
    step_reward=-0.04,     # 时间惩罚,鼓励短路径
    slip_prob=0.1,         # 10% 概率滑向侧向
)

2)自定义冰湖地图:

from tinyrl.envs import FrozenLake

env = FrozenLake([
    "SFFF",
    "FHFH",
    "FFFH",
    "HFFG",
], slippery=True)         # slippery=False 可关闭打滑

3)多臂老虎机实验并查看遗憾曲线:

from tinyrl.envs import MultiArmedBandit
from tinyrl.agents import ThompsonBernoulli
from tinyrl.engine import run_bandit
from tinyrl.report import sparkline, summarize_bandit

env = MultiArmedBandit.bernoulli([0.2, 0.5, 0.8, 0.35, 0.6])
record = run_bandit(env, ThompsonBernoulli(5, seed=42), pulls=2000, seed=42)
print(summarize_bandit(record))
print(sparkline(record.cumulative_regret))   # ▁▄▅▆▇█████

4)已知模型时直接动态规划,无需采样:

from tinyrl.envs import FrozenLake
from tinyrl.agents import value_iteration, policy_as_arrows

env = FrozenLake()
V, policy, sweeps = value_iteration(env, gamma=0.99)
print(policy_as_arrows(env, policy))

🎬 演示截图 / 动图占位

终端演示动图将在后续版本补充,可先用下面命令复现全部效果:

tinyrl demo-bandits      # 算法对比表 + 遗憾曲线
tinyrl demo-plan --env gridworld   # 箭头形式的最优策略

🎯 典型使用场景

  • 🎓 课堂教学 / 自学:从老虎机到 TD 控制,每个算法都能在 1 秒内看到结果
  • 🧪 算法原型验证:先在表格环境验证想法,再迁移到大规模深度 RL
  • 🤖 编码 Agent 基准:确定性、零依赖,适合作为 AI 编程智能体的可复现评测沙盒
  • 🔬 实验报告:compare --json/--csv 直接产出可画图的原始数据

💡 设计思路与迭代规划

🧠 设计理念

  1. 可读即文档:每个模块控制在单文件可通读的规模,算法实现贴近 Sutton & Barto《Reinforcement Learning: An Introduction》的符号体系(Q、α、γ、ε)。
  2. 显式随机源:环境与智能体各自持有独立的 random.Random,由种子派生,杜绝全局随机状态带来的不可复现。
  3. 模型/无模型对照:网格环境同时提供 step()(交互)与 model()(转移概率),让「Q-Learning 学出来的策略」和「价值迭代算出来的最优策略」可以直接对照。
  4. 零依赖是特性而非妥协:标准库足以清晰表达全部经典表格型算法,也因此获得跨平台、秒级启动、永久可运行的稳定性。

🗺️ 迭代路线图(Roadmap)

  • v1.1:新增 Blackjack、Windy Gridworld、Shortcut MDP 等经典环境
  • v1.1:TD(λ)、n-step Sarsa、Double Q-Learning 算法
  • v1.2:策略评估的自包含 SVG 学习曲线导出(仍保持零依赖)
  • v1.2:Gymnasium 适配层(可选导入,不破坏零依赖核心)
  • v1.3:简单函数逼近接口(线性函数近似,纯 Python)
  • 持续补充多语言文档与教学 Notebook(不引入运行时依赖)

🙋 社区贡献方向

欢迎认领 Roadmap 条目,或贡献新的经典环境、算法、教学示例;提交前请阅读 CONTRIBUTING.md。


📦 打包与部署指南

本项目属于工具库 / CLI 类项目(纯 Python、跨平台、无原生产物),无需下载可执行文件,按以下方式集成分发:

构建分发包

# 需要构建工具(仅构建期使用,不是运行时依赖)
python -m pip install build
python -m build           # 产出 dist/*.whl 与 dist/*.tar.gz

构建出的 wheel 为 py3-none-any,一份包通用于 Windows / macOS / Linux。

离线环境部署

# 在有网机器下载 wheel,拷贝到目标机器后
pip install tinyrl_lab-1.0.0-py3-none-any.whl

兼容性说明

项 支持范围
操作系统 Windows / macOS / Linux(纯 Python,与平台无关)
Python 版本 3.8 – 3.12
运行时依赖 无
安装方式 源码目录直接运行 / pip 安装 / wheel 离线安装

🧪 测试

测试同样零第三方依赖,使用标准库 unittest:

# 运行全部 71 个测试
python -m unittest discover -s tests -v

# 语法编译检查
python -m compileall tinyrl examples

测试覆盖:环境转移正确性与概率闭合、奖励语义、算法收敛性(含多种子稳健性)、 动态规划 Bellman 残差、同种子可复现/异种子不同、报告导出往返、CLI 端到端。


🤝 贡献指南

  • 🐛 问题反馈请附最小复现代码 + 随机种子;
  • 🔀 PR 提交信息遵循 Angular 规范:feat: / fix: / docs: / test: / refactor:;
  • 📐 新功能必须附带单元测试,且不得引入第三方运行时依赖;
  • 🌐 改动公开 API 时,请同步更新三份语言文档。

完整约定见 CONTRIBUTING.md。


📄 开源协议

本项目基于 MIT License 开源,可自由用于学习、教学、科研与商业项目,保留版权声明即可。


如果这个项目对你有帮助,欢迎 ⭐ Star 支持!

Happy Learning, Happy Reinforcement! 🦞🎰

About

🦞 Zero-dependency classic RL environments & tabular agents in pure Python (bandits, GridWorld, FrozenLake, CliffWalking, Q-Learning/SARSA, DP). 零依赖纯Python经典强化学习工具箱。

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages