[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-kossisoroyce--timber":3,"tool-kossisoroyce--timber":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",150037,2,"2026-04-10T23:33:47",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":78,"owner_email":79,"owner_twitter":73,"owner_website":80,"owner_url":81,"languages":82,"stars":103,"forks":104,"last_commit_at":105,"license":106,"difficulty_score":107,"env_os":108,"env_gpu":109,"env_ram":108,"env_deps":110,"category_tags":115,"github_topics":116,"view_count":32,"oss_zip_url":79,"oss_zip_packed_at":79,"status":17,"created_at":131,"updated_at":132,"faqs":133,"releases":134},6412,"kossisoroyce\u002Ftimber","timber","Ollama for classical ML models. AOT compiler that turns XGBoost, LightGBM, scikit-learn, CatBoost & ONNX models into native C99 inference code. One command to load, one command to serve. 336x faster than Python inference.","Timber 是一款专为经典机器学习模型打造的高性能推理工具，被誉为“传统机器学习的 Ollama\"。它能够将 XGBoost、LightGBM、scikit-learn、CatBoost 及 ONNX 等主流框架训练好的模型，通过先进的预编译（AOT）技术，直接转换为无运行时依赖的原生 C99 代码。\n\n在机器学习落地过程中，基于 Python 的推理往往面临速度慢、环境配置复杂以及部署包体积大等痛点。Timber 完美解决了这些问题：它将模型编译为独立的二进制文件，无需安装庞大的 Python 环境或任何第三方库即可运行。实测数据显示，其单次样本推理耗时仅约 2 微秒，速度比原生 Python 推理快达 336 倍，且生成的产物小巧至约 48 KB。\n\n这款工具非常适合追求极致性能与便携性的后端工程师、嵌入式开发者以及需要大规模部署模型的算法团队。无论是资源受限的边缘设备，还是对延迟极其敏感的高并发服务场景，Timber 都能提供稳定高效的解决方案。其独特的亮点在于“一行命令完成加载与服务”，内置兼容 Ollama 的 HTTP 服务器，支持从本地文件或远程 URL 直接下载、编译","Timber 是一款专为经典机器学习模型打造的高性能推理工具，被誉为“传统机器学习的 Ollama\"。它能够将 XGBoost、LightGBM、scikit-learn、CatBoost 及 ONNX 等主流框架训练好的模型，通过先进的预编译（AOT）技术，直接转换为无运行时依赖的原生 C99 代码。\n\n在机器学习落地过程中，基于 Python 的推理往往面临速度慢、环境配置复杂以及部署包体积大等痛点。Timber 完美解决了这些问题：它将模型编译为独立的二进制文件，无需安装庞大的 Python 环境或任何第三方库即可运行。实测数据显示，其单次样本推理耗时仅约 2 微秒，速度比原生 Python 推理快达 336 倍，且生成的产物小巧至约 48 KB。\n\n这款工具非常适合追求极致性能与便携性的后端工程师、嵌入式开发者以及需要大规模部署模型的算法团队。无论是资源受限的边缘设备，还是对延迟极其敏感的高并发服务场景，Timber 都能提供稳定高效的解决方案。其独特的亮点在于“一行命令完成加载与服务”，内置兼容 Ollama 的 HTTP 服务器，支持从本地文件或远程 URL 直接下载、编译并发布模型 API，极大地简化了从实验到生产的部署流程，让高性能推理变得触手可及。","# Timber\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Compile classical ML models to native C. Serve them in microseconds.\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg?branch=main\" alt=\"CI\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Ftimber-compiler.svg\" alt=\"PyPI version\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Ftimber-compiler.svg\" alt=\"Python versions\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Ftimber-compiler.svg\" alt=\"Monthly downloads\">\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-blue.svg\" alt=\"License: Apache-2.0\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fcodecov.io\u002Fgh\u002Fkossisoroyce\u002Ftimber\">\u003Cimg src=\"https:\u002F\u002Fcodecov.io\u002Fgh\u002Fkossisoroyce\u002Ftimber\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg\" alt=\"Coverage\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fkossisoroyce.github.io\u002Ftimber\u002F\">Documentation\u003C\u002Fa> ·\n  \u003Ca href=\"CHANGELOG.md\">Changelog\u003C\u002Fa> ·\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">PyPI\u003C\u002Fa> ·\n  \u003Ca href=\"paper\u002Ftimber_paper.pdf\">Technical Paper\u003C\u002Fa> ·\n  \u003Ca href=\"skill.md\">Agent Skill\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\nTimber takes a trained ML model — XGBoost, LightGBM, scikit-learn, CatBoost, ONNX (tree ensembles, linear models, SVMs), or a **URDF robot description** — runs it through a multi-pass optimizing compiler, and emits a **self-contained C99 inference artifact** with zero runtime dependencies. A built-in HTTP server (Ollama-compatible API) lets you serve any model — local file or remote URL — in one command.\n\n> **~2 µs single-sample inference · ~336× faster than Python XGBoost · ~48 KB artifact · zero runtime dependencies**\n\n---\n\n## See it in action\n\n> **Point Timber at any URL and it downloads, compiles, and serves in one command — no setup required.**\n\n```console\n$ pip install timber-compiler\n$ timber serve https:\u002F\u002Fraw.githubusercontent.com\u002Fkossisoroyce\u002Ftimber\u002Fmain\u002Fexamples\u002Fbreast_cancer_model.json\n\n  ✓ Downloaded              breast_cancer_model.json\n  ✓ Format detected         xgboost\n  ✓ Parsed model            50 trees · 30 features · binary:logistic\n  ✓ Optimized               3\u002F5 passes applied\n  ✓ Generated C99           169 lines\n  ✓ Compiled binary         47.9 KB\n\n  Serving    breast_cancer_model\n  Endpoint   http:\u002F\u002Flocalhost:11434\n  Framework  xgboost  ·  50 trees  ·  30 features\n\n  POST  http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict\n  GET   http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fmodels\n  GET   http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fhealth\n```\n\n**Predict immediately:**\n\n```console\n$ curl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n    -H 'Content-Type: application\u002Fjson' \\\n    -d '{\"model\": \"breast_cancer_model\", \"inputs\": [[1.799e+01, 1.038e+01, 1.228e+02, 1.001e+03, 0.1184, 0.2776, 0.3001, 0.1471, 0.2419, 0.07871, 1.095, 0.9053, 8.589, 153.4, 0.006399, 0.04904, 0.05373, 0.01587, 0.03003, 0.006193, 2.538e+01, 1.733e+01, 1.846e+02, 2.019e+03, 0.1622, 0.6656, 0.7119, 0.2654, 0.4601, 0.1189]]}'\n\n{\"model\": \"breast_cancer_model\", \"outputs\": [[0.9971]], \"n_samples\": 1}\n```\n\n**Or load from a local file and serve by name:**\n\n```console\n$ timber load fraud_model.json --name fraud-detector\n$ timber serve fraud-detector\n```\n\n---\n\n## Table of Contents\n\n- [Who is this for?](#who-is-this-for)\n- [How it works](#how-it-works)\n- [Quick Start](#quick-start)\n- [Supported Formats](#supported-formats)\n- [Performance](#performance)\n- [Runtime Comparison](#runtime-comparison)\n- [API Reference](#api-reference)\n- [CLI Reference](#cli-reference)\n- [Examples](#examples)\n- [Limitations](#limitations)\n- [Roadmap](#roadmap)\n- [Development](#development)\n- [Citation](#citation)\n- [Community & Governance](#community--governance)\n- [License](#license)\n\n---\n\n## Who is this for?\n\nTimber is built for teams that need **fast, predictable, and portable inference**:\n\n- **Fraud & risk teams** — run classical models in sub-millisecond transaction paths without Python overhead\n- **Edge & IoT deployments** — ship a ~48 KB C artifact to gateways, microcontrollers, or ARM Cortex-M targets\n- **Regulated industries** — finance, healthcare, and automotive teams that need deterministic, auditable inference artifacts\n- **Platform & infra teams** — eliminate the Python model-serving stack from your critical path entirely\n\n---\n\n## How it works\n\n```\n  ┌─────────────────────────────────────────────────────────┐\n  │                     timber load                         │\n  │                                                         │\n  │  Model file  ──►  Parser  ──►  Timber IR  ──►  Optimizer│\n  │  (.json\u002F.pkl\u002F                  (typed AST)   (dead-leaf  │\n  │   .txt\u002F.onnx)                               elim, quant, │\n  │                                              branch-sort) │\n  │                                     │                    │\n  │                                     ▼                    │\n  │                               C99 Emitter                │\n  │                                     │                    │\n  │                    ┌────────────────┼────────────────┐   │\n  │                    ▼                ▼                ▼   │\n  │               model.c         model.h        model_data.c│\n  │               (inference)     (public API)   (tree data)  │\n  │                    │                                     │\n  │                    └──► gcc \u002F clang ──► model.so         │\n  └─────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n                      timber serve \u003Cname>\n                   http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict\n```\n\nThe compiler pipeline:\n1. **Parse** — reads the native model format into a framework-agnostic Timber IR\n2. **Optimize** — dead-leaf elimination, threshold quantization, constant-feature folding, branch sorting\n3. **Emit** — generates deterministic, portable C99 with no dynamic allocation and no recursion\n4. **Compile** — `gcc`\u002F`clang` produces a shared library loaded via `ctypes`\n5. **Serve** — an Ollama-compatible HTTP API wraps the binary for drop-in integration\n\n---\n\n## Quick Start\n\n```bash\npip install timber-compiler\n```\n\n**Serve any model directly from a URL — no pre-download step:**\n\n```bash\ntimber serve https:\u002F\u002Fyourhost.com\u002Fmodels\u002Ffraud_model.json\n```\n\n**Or load a local model and serve by name:**\n\n```bash\ntimber load fraud_model.json --name fraud-detector\ntimber serve fraud-detector\n```\n\n**Predict:**\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"model\": \"fraud-detector\", \"inputs\": [[1.2, 0.4, 3.1, 0.9]]}'\n```\n\n```json\n{\"model\": \"fraud-detector\", \"outputs\": [[0.031]], \"latency_us\": 1.8}\n```\n\n**That's it.** No model server configuration, no Python runtime in the hot path.\n\n**Or serve a robot's forward kinematics from a URDF file:**\n\n```bash\ntimber serve robot.urdf\n```\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"model\": \"robot\", \"inputs\": [[0.1, 0.2, 0.3, -0.4, 0.5, -0.6, 0.7]]}'\n```\n\n```json\n{\"model\": \"robot\", \"outputs\": [[0.082, -0.982, 0.170, 0.310, 0.959, 0.031, -0.283, 0.053, 0.272, 0.187, 0.944, 1.180, 0.0, 0.0, 0.0, 1.0]], \"latency_us\": 65.0}\n```\n\n---\n\n## Supported Formats\n\n| Framework | File format | Notes |\n|-----------|-------------|-------|\n| XGBoost | `.json` | All objectives; multiclass, binary, regression; XGBoost 3.1+ per-class base_score |\n| LightGBM | `.txt`, `.model`, `.lgb` | All objectives including multiclass |\n| scikit-learn | `.pkl`, `.pickle` | GradientBoostingClassifier\u002FRegressor, RandomForest, ExtraTrees, DecisionTree, Pipeline |\n| ONNX | `.onnx` | `TreeEnsembleClassifier\u002FRegressor`, `LinearClassifier\u002FRegressor`, `SVMClassifier\u002FRegressor`, `Normalizer`, `Scaler` |\n| CatBoost | `.json` | JSON export (`save_model(..., format='json')`) |\n| URDF | `.urdf` | Robot description → forward kinematics; outputs 4×4 homogeneous transform; inputs are joint angles |\n\n---\n\n## Performance\n\n> Benchmarks run on Apple M2 Pro · 16 GB RAM · macOS · XGBoost binary classifier · 50 trees · max depth 4 · 30 features (sklearn `breast_cancer`) · 10,000 timed iterations after 1,000 warmup.\n\n| Runtime | Single-sample latency | Throughput | Speedup vs Python |\n|---------|----------------------|------------|-------------------|\n| **Timber (native C)** | **~2 µs** | **~500,000 \u002F sec** | **336×** |\n| ONNX Runtime | ~80–150 µs | ~10,000 \u002F sec | ~5× |\n| Treelite (compiled) | ~10–30 µs | ~50,000 \u002F sec | ~20× |\n| Python XGBoost | ~670 µs | ~1,500 \u002F sec | 1× (baseline) |\n| Python scikit-learn | ~900 µs | ~1,100 \u002F sec | 0.7× |\n\nLatency is **in-process** (not HTTP round-trip). Network overhead adds ~50–200 µs depending on your stack.\n\n### Reproduce these numbers\n\n```bash\npython benchmarks\u002Frun_benchmarks.py --output benchmarks\u002Fresults.json\npython benchmarks\u002Frender_table.py   --input  benchmarks\u002Fresults.json\n```\n\nSee [`benchmarks\u002F`](benchmarks\u002F) for full methodology, hardware capture script, and optional ONNX Runtime \u002F Treelite \u002F lleaves comparisons.\n\n---\n\n## Runtime Comparison\n\n| | Timber | Python serving | ONNX Runtime | Treelite | lleaves |\n|---|---|---|---|---|---|\n| **Latency** | ~2 µs | 100s of µs–ms | ~100 µs | ~10–30 µs | ~50 µs |\n| **Runtime deps** | None | Python + framework | ONNX Runtime libs | Treelite runtime | Python + LightGBM |\n| **Artifact size** | ~48 KB | 50–200+ MB process | MBs | MB-scale | Python env |\n| **Formats** | 5 (trees + linear + SVM) | Each framework only | ONNX only | GBDTs | LightGBM only |\n| **C export** | Yes (C99) | No | No | Yes | No |\n| **LLVM IR export** | Yes | No | No | No | No |\n| **Edge \u002F embedded** | Yes (Cortex-M4\u002FM33, RISC-V) | No | Partial | Partial | No |\n| **MISRA-C output** | Yes | No | No | No | No |\n| **Differential privacy** | Yes | No | No | No | No |\n\n---\n\n## API Reference\n\nTimber's server exposes an **Ollama-compatible REST API** on `http:\u002F\u002Flocalhost:11434` by default.\n\n| Endpoint | Method | Body \u002F Params | Description |\n|----------|--------|---------------|-------------|\n| `\u002Fapi\u002Fpredict` | POST | `{\"model\": str, \"inputs\": [[float]]}` | Run inference |\n| `\u002Fapi\u002Fgenerate` | POST | same as `\u002Fapi\u002Fpredict` | Ollama alias |\n| `\u002Fapi\u002Fmodels` | GET | — | List all loaded models |\n| `\u002Fapi\u002Fmodel\u002F:name` | GET | — | Model metadata & schema |\n| `\u002Fapi\u002Fhealth` | GET | — | Health check |\n\n**Example — batch inference:**\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"fraud-detector\",\n    \"inputs\": [\n      [1.2, 0.4, 3.1, 0.9],\n      [0.1, 2.3, 1.0, 4.4]\n    ]\n  }'\n```\n\n---\n\n## CLI Reference\n\n```\ntimber load   \u003Cpath> --name \u003Cname>   Compile and register a model\ntimber serve  \u003Cname> [--port N]      Start the inference server\ntimber list                          List registered models\ntimber inspect \u003Cname>                Show model IR summary and schema\ntimber validate \u003Cname>               Run numerical validation against source\ntimber bench  \u003Cname>                 Benchmark latency and throughput\ntimber pull   \u003Curl>  --name \u003Cname>   Download and compile from URL\ntimber remove \u003Cname>                 Remove a model from the registry\n```\n\n---\n\n## Examples\n\nRunnable end-to-end examples live in [`examples\u002F`](examples\u002F):\n\n```bash\npython examples\u002Fquickstart_xgboost.py   # trains, compiles, and benchmarks\npython examples\u002Fquickstart_lightgbm.py\npython examples\u002Fquickstart_sklearn.py\n```\n\nEach script trains a model, saves it, runs `timber load`, and validates predictions against the source framework.\n\n---\n\n## Limitations\n\n- **ONNX** — supports `TreeEnsemble`, `LinearClassifier\u002FRegressor`, `SVMClassifier\u002FRegressor`, `Normalizer`, `Scaler`; other operators (e.g., neural network layers) are not yet supported\n- **CatBoost** — requires JSON export (`save_model(..., format='json')`); native binary format not supported\n- **scikit-learn** — major estimators and `Pipeline` wrappers are supported; uncommon custom estimators may require a custom front-end\n- **Pickle** — follow standard pickle security hygiene; only load artifacts from trusted sources\n- **XGBoost** — JSON model format is the primary path; binary booster format is not supported\n- **LLVM IR** — currently emitted as text (`.ll`); requires a local LLVM\u002FClang installation to produce native code from it\n- **MISRA-C** — the built-in compliance checker covers the rules most relevant to generated code; it is not a substitute for a certified static analysis tool\n\n---\n\n## Roadmap\n\n| Status | Item |\n|--------|------|\n| ✅ | XGBoost, LightGBM, scikit-learn, CatBoost, ONNX front-ends |\n| ✅ | Multi-pass IR optimizer (dead-leaf, quantization, branch sort, scaler fusion) |\n| ✅ | C99 emitter with WebAssembly target |\n| ✅ | Ollama-compatible HTTP inference server with multi-worker FastAPI |\n| ✅ | PyPI packaging with OIDC trusted publishing |\n| ✅ | ONNX Linear\u002FSVM\u002FNormalizer\u002FScaler operator support |\n| ✅ | ARM Cortex-M4\u002FM33 and RISC-V rv32imf\u002Frv64gc embedded deployment profiles |\n| ✅ | MISRA-C:2012 compliant output mode with built-in compliance checker |\n| ✅ | LLVM IR backend with configurable target triples |\n| ✅ | Differential privacy (Laplace + Gaussian) inference mode |\n| ✅ | Richer `bench` reports: P50\u002FP95\u002FP99\u002FP999, CV%, JSON + HTML output |\n| 🔄 | Remote model registry (`timber pull` from hosted model library) |\n| 🔲 | Neural network operator support (MLPClassifier) |\n| 🔲 | ONNX export path (Timber IR → ONNX) |\n| 🔲 | Rust backend emitter |\n\n---\n\n## Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber.git\ncd timber\npip install -e \".[dev]\"\npytest tests\u002F -v                    # 436 tests\nruff check timber\u002F                  # linting\n```\n\nThe test suite covers: parsers (sklearn, ONNX, XGBoost, LightGBM, CatBoost), IR layer (serialization, deep_copy, all stage types), optimizer passes (correctness, idempotency, pipeline fusion math), C99\u002FWASM\u002FMISRA-C\u002FLLVM IR emitters (compile + numeric accuracy), differential privacy (statistical correctness, all dtypes), and full end-to-end pipelines.\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full development guide.\n\n---\n\n## Citation\n\nIf you use Timber in research or production, please cite the accompanying technical paper:\n\n```bibtex\n@misc{royce2026timber,\n  title        = {Timber: Compiling Classical Machine Learning Models to Native Inference Binaries},\n  author       = {Kossiso Royce},\n  year         = {2026},\n  howpublished = {GitHub repository and technical paper},\n  institution  = {Electricsheep Africa},\n  url          = {https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber}\n}\n```\n\nThe full paper is available at [`paper\u002Ftimber_paper.pdf`](paper\u002Ftimber_paper.pdf).\n\n---\n\n## Community & Governance\n\n- **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- **Code of conduct:** [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)\n- **Security policy:** [`SECURITY.md`](SECURITY.md)\n- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)\n\nBugs and feature requests: [open an issue](https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Fissues). Questions: [start a discussion](https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Fdiscussions).\n\n---\n\n## Support the Project\n\nTimber is developed and maintained by [Electricsheep Africa](https:\u002F\u002Fgithub.com\u002Felectricsheepafrica). If Timber saves your team engineering time, consider supporting continued development:\n\n[![Buy Me A Coffee](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuy%20Me%20A%20Coffee-support-%23FFDD00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https:\u002F\u002Fbuymeacoffee.com\u002Felectricsheepafrica)\n\nWe're also building a hosted library of compiled models — if you have high-performance models you'd like to contribute, [get in touch](https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Fdiscussions).\n\n---\n\n## License\n\nApache-2.0 — see [`LICENSE`](LICENSE) for the full text.\n","# Timber\n\n\u003Cp align=\"center\">\n  \u003Cstrong>将经典机器学习模型编译为原生 C 语言代码，实现实时推理。\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg?branch=main\" alt=\"CI\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Ftimber-compiler.svg\" alt=\"PyPI 版本\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Ftimber-compiler.svg\" alt=\"Python 版本\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Ftimber-compiler.svg\" alt=\"月下载量\">\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-blue.svg\" alt=\"许可证：Apache-2.0\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fcodecov.io\u002Fgh\u002Fkossisoroyce\u002Ftimber\">\u003Cimg src=\"https:\u002F\u002Fcodecov.io\u002Fgh\u002Fkossisoroyce\u002Ftimber\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg\" alt=\"覆盖率\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fkossisoroyce.github.io\u002Ftimber\u002F\">文档\u003C\u002Fa> ·\n  \u003Ca href=\"CHANGELOG.md\">变更日志\u003C\u002Fa> ·\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Ftimber-compiler\u002F\">PyPI\u003C\u002Fa> ·\n  \u003Ca href=\"paper\u002Ftimber_paper.pdf\">技术论文\u003C\u002Fa> ·\n  \u003Ca href=\"skill.md\">代理技能\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\nTimber 接受经过训练的机器学习模型——XGBoost、LightGBM、scikit-learn、CatBoost、ONNX（树集成、线性模型、SVM）或 **URDF 机器人描述**——通过多遍优化编译器处理后，生成一个**自包含的 C99 推理工件**，且无运行时依赖。内置的 HTTP 服务器（兼容 Ollama API）允许您只需一条命令即可部署任何模型——无论是本地文件还是远程 URL。\n\n> **单样本推理约 2 微秒 · 比 Python XGBoost 快约 336 倍 · 工件大小约 48 KB · 无运行时依赖**\n\n---\n\n## 实际演示\n\n> **只需指向任意 URL，Timber 就会自动下载、编译并部署，无需任何配置。**\n\n```console\n$ pip install timber-compiler\n$ timber serve https:\u002F\u002Fraw.githubusercontent.com\u002Fkossisoroyce\u002Ftimber\u002Fmain\u002Fexamples\u002Fbreast_cancer_model.json\n\n  ✓ 下载              breast_cancer_model.json\n  ✓ 检测到格式         xgboost\n  ✓ 解析模型            50 棵树 · 30 个特征 · 二分类: logistic\n  ✓ 优化               应用了 3\u002F5 轮优化\n  ✓ 生成 C99           169 行\n  ✓ 编译二进制文件     47.9 KB\n\n  正在服务    breast_cancer_model\n  端点       http:\u002F\u002Flocalhost:11434\n  框架       xgboost  ·  50 棵树  ·  30 个特征\n\n  POST  http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict\n  GET   http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fmodels\n  GET   http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fhealth\n```\n\n**立即预测：**\n\n```console\n$ curl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n    -H 'Content-Type: application\u002Fjson' \\\n    -d '{\"model\": \"breast_cancer_model\", \"inputs\": [[1.799e+01, 1.038e+01, 1.228e+02, 1.001e+03, 0.1184, 0.2776, 0.3001, 0.1471, 0.2419, 0.07871, 1.095, 0.9053, 8.589, 153.4, 0.006399, 0.04904, 0.05373, 0.01587, 0.03003, 0.006193, 2.538e+01, 1.733e+01, 1.846e+02, 2.019e+03, 0.1622, 0.6656, 0.7119, 0.2654, 0.4601, 0.1189]]}'\n\n{\"model\": \"breast_cancer_model\", \"outputs\": [[0.9971]], \"n_samples\": 1}\n```\n\n**或者从本地文件加载并按名称部署：**\n\n```console\n$ timber load fraud_model.json --name fraud-detector\n$ timber serve fraud-detector\n```\n\n---\n\n## 目录\n\n- [适用人群](#who-is-this-for)\n- [工作原理](#how-it-works)\n- [快速入门](#quick-start)\n- [支持的格式](#supported-formats)\n- [性能](#performance)\n- [运行时对比](#runtime-comparison)\n- [API 参考](#api-reference)\n- [CLI 参考](#cli-reference)\n- [示例](#examples)\n- [限制](#limitations)\n- [路线图](#roadmap)\n- [开发](#development)\n- [引用](#citation)\n- [社区与治理](#community--governance)\n- [许可证](#license)\n\n---\n\n## 适用人群\n\nTimber 专为需要**快速、可预测且可移植推理**的团队打造：\n\n- **欺诈与风险团队** — 在亚毫秒级交易路径中运行经典模型，无需 Python 开销\n- **边缘与 IoT 部署** — 将约 48 KB 的 C 工件部署到网关、微控制器或 ARM Cortex-M 设备上\n- **受监管行业** — 金融、医疗和汽车行业的团队，需要确定性、可审计的推理工件\n- **平台与基础设施团队** — 完全消除关键路径中的 Python 模型推理栈\n\n---\n\n## 工作原理\n\n```\n  ┌─────────────────────────────────────────────────────────┐\n  │                     timber load                         │\n  │                                                         │\n  │  模型文件  ──►  解析器  ──►  Timber IR  ──►  优化器│\n  │  (.json\u002F.pkl\u002F                  (类型化 AST)   (去除死叶  │\n  │   .txt\u002F.onnx)                               量化、分支排序) │\n  │                                              branch-sort) │\n  │                                     │                    │\n  │                                     ▼                    │\n  │                               C99 生成器                │\n  │                                     │                    │\n  │                    ┌────────────────┼────────────────┐   │\n  │                    ▼                ▼                ▼   │\n  │               model.c         model.h        model_data.c│\n  │               (推理)     (公共 API)   (树结构数据)  │\n  │                    │                                     │\n  │                    └──► gcc \u002F clang ──► model.so         │\n  └─────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n                      timber serve \u003Cname>\n                   http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict\n```\n\n编译器流程：\n1. **解析** — 将原生模型格式读取为框架无关的 Timber IR\n2. **优化** — 去除死叶节点、阈值量化、常量特征折叠、分支排序\n3. **生成** — 生成确定性、可移植的 C99 代码，无动态内存分配且无递归调用\n4. **编译** — 使用 `gcc`\u002F`clang` 生成可通过 `ctypes` 加载的共享库\n5. **部署** — 兼容 Ollama 的 HTTP API 包装二进制文件，便于直接集成\n\n---\n\n## 快速入门\n\n```bash\npip install timber-compiler\n```\n\n**直接从 URL 提供任何模型——无需预先下载步骤：**\n\n```bash\ntimber serve https:\u002F\u002Fyourhost.com\u002Fmodels\u002Ffraud_model.json\n```\n\n**或者加载本地模型并按名称提供服务：**\n\n```bash\ntimber load fraud_model.json --name fraud-detector\ntimber serve fraud-detector\n```\n\n**预测：**\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"model\": \"fraud-detector\", \"inputs\": [[1.2, 0.4, 3.1, 0.9]]}'\n```\n\n```json\n{\"model\": \"fraud-detector\", \"outputs\": [[0.031]], \"latency_us\": 1.8}\n```\n\n**就是这样。** 无需配置模型服务器，也无需在关键路径中使用 Python 运行时。\n\n**或者从 URDF 文件提供机器人的正运动学：**\n\n```bash\ntimber serve robot.urdf\n```\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"model\": \"robot\", \"inputs\": [[0.1, 0.2, 0.3, -0.4, 0.5, -0.6, 0.7]]}'\n```\n\n```json\n{\"model\": \"robot\", \"outputs\": [[0.082, -0.982, 0.170, 0.310, 0.959, 0.031, -0.283, 0.053, 0.272, 0.187, 0.944, 1.180, 0.0, 0.0, 0.0, 1.0]], \"latency_us\": 65.0}\n```\n\n---\n\n## 支持的格式\n\n| 框架       | 文件格式     | 备注                           |\n|------------|--------------|--------------------------------|\n| XGBoost    | `.json`      | 所有目标；多分类、二分类、回归；XGBoost 3.1+ 的每类 base_score |\n| LightGBM   | `.txt`, `.model`, `.lgb` | 所有目标，包括多分类         |\n| scikit-learn | `.pkl`, `.pickle` | GradientBoostingClassifier\u002FRegressor、RandomForest、ExtraTrees、DecisionTree、Pipeline |\n| ONNX       | `.onnx`      | `TreeEnsembleClassifier\u002FRegressor`、`LinearClassifier\u002FRegressor`、`SVMClassifier\u002FRegressor`、`Normalizer`、`Scaler` |\n| CatBoost   | `.json`      | JSON 导出（`save_model(..., format='json')`） |\n| URDF       | `.urdf`      | 机器人描述 → 正运动学；输出 4×4 齐次变换；输入为关节角度 |\n\n---\n\n## 性能\n\n> 基准测试在 Apple M2 Pro · 16 GB 内存 · macOS 上运行，使用 XGBoost 二分类器，50 棵树，最大深度 4，30 个特征（sklearn `breast_cancer` 数据集），先预热 1,000 次迭代，再进行 10,000 次计时迭代。\n\n| 运行时        | 单样本延迟   | 吞吐量     | 相比 Python 的加速倍数 |\n|---------------|--------------|------------|-----------------------|\n| **Timber（原生 C）** | **~2 µs** | **~500,000 \u002F 秒** | **336×** |\n| ONNX Runtime  | ~80–150 µs   | ~10,000 \u002F 秒 | ~5×                 |\n| Treelite（编译后） | ~10–30 µs    | ~50,000 \u002F 秒 | ~20×                |\n| Python XGBoost  | ~670 µs      | ~1,500 \u002F 秒 | 1×（基准）          |\n| Python scikit-learn | ~900 µs      | ~1,100 \u002F 秒 | 0.7×                |\n\n延迟是 **进程内** 的（不是 HTTP 往返）。网络开销会根据你的堆栈增加约 50–200 µs。\n\n### 重现这些数据\n\n```bash\npython benchmarks\u002Frun_benchmarks.py --output benchmarks\u002Fresults.json\npython benchmarks\u002Frender_table.py   --input  benchmarks\u002Fresults.json\n```\n\n完整的方法论、硬件采集脚本以及可选的 ONNX Runtime \u002F Treelite \u002F lleaves 对比，请参阅 [`benchmarks\u002F`](benchmarks\u002F)。\n\n---\n\n## 运行时比较\n\n|             | Timber       | Python 服务   | ONNX Runtime | Treelite | lleaves |\n|-------------|--------------|---------------|--------------|----------|---------|\n| **延迟**    | ~2 µs        | 数百 µs–ms    | ~100 µs      | ~10–30 µs | ~50 µs  |\n| **运行时依赖** | 无           | Python + 框架 | ONNX Runtime 库 | Treelite 运行时 | Python + LightGBM |\n| **工件大小** | ~48 KB       | 50–200+ MB 进程 | MB 级别      | MB 规模  | Python 环境 |\n| **格式**    | 5 种（树模型 + 线性模型 + SVM） | 各框架专用 | 仅 ONNX    | GBDT     | 仅 LightGBM |\n| **C 导出**  | 是（C99）    | 否            | 否           | 是       | 否      |\n| **LLVM IR 导出** | 是           | 否            | 否           | 否       | 否      |\n| **边缘\u002F嵌入式** | 是（Cortex-M4\u002FM33、RISC-V） | 否           | 部分支持     | 部分支持 | 否      |\n| **MISRA-C 输出** | 是           | 否            | 否           | 否       | 否      |\n| **差分隐私** | 是           | 否            | 否           | 否       | 否      |\n\n---\n\n## API 参考\n\nTimber 的服务器默认在 `http:\u002F\u002Flocalhost:11434` 上暴露一个 **与 Ollama 兼容的 REST API**。\n\n| 端点         | 方法 | 请求体 \u002F 参数 | 描述                     |\n|--------------|------|---------------|--------------------------|\n| `\u002Fapi\u002Fpredict` | POST | `{\"model\": str, \"inputs\": [[float]]}` | 运行推理                 |\n| `\u002Fapi\u002Fgenerate` | POST | 与 `\u002Fapi\u002Fpredict` 相同 | Ollama 别名              |\n| `\u002Fapi\u002Fmodels` | GET  | —             | 列出所有已加载模型       |\n| `\u002Fapi\u002Fmodel\u002F:name` | GET  | —             | 模型元数据及架构         |\n| `\u002Fapi\u002Fhealth` | GET  | —             | 健康检查                 |\n\n**示例——批量推理：**\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"fraud-detector\",\n    \"inputs\": [\n      [1.2, 0.4, 3.1, 0.9],\n      [0.1, 2.3, 1.0, 4.4]\n    ]\n  }'\n```\n\n---\n\n## CLI 参考\n\n```\ntimber load   \u003Cpath> --name \u003Cname>   编译并注册模型\ntimber serve  \u003Cname> [--port N]      启动推理服务器\ntimber list                          列出已注册模型\ntimber inspect \u003Cname>                显示模型 IR 摘要和架构\ntimber validate \u003Cname>               对源模型进行数值验证\ntimber bench  \u003Cname>                 基准测试延迟和吞吐量\ntimber pull   \u003Curl>  --name \u003Cname>   从 URL 下载并编译\ntimber remove \u003Cname>                 从注册表中移除模型\n```\n\n---\n\n## 示例\n\n可运行的端到端示例位于 [`examples\u002F`](examples\u002F)：\n\n```bash\npython examples\u002Fquickstart_xgboost.py   # 训练、编译并进行基准测试\npython examples\u002Fquickstart_lightgbm.py\npython examples\u002Fquickstart_sklearn.py\n```\n\n每个脚本都会训练一个模型，将其保存，然后运行 `timber load`，最后将预测结果与原始框架进行验证。\n\n---\n\n## 局限性\n\n- **ONNX** — 支持 `TreeEnsemble`、`LinearClassifier\u002FRegressor`、`SVMClassifier\u002FRegressor`、`Normalizer`、`Scaler`；其他算子（如神经网络层）暂不支持。\n- **CatBoost** — 需要 JSON 导出（`save_model(..., format='json')`）；不支持原生二进制格式。\n- **scikit-learn** — 主要估计器和 `Pipeline` 包装器受支持；不常见的自定义估计器可能需要自定义前端。\n- **Pickle** — 请遵循标准的 pickle 安全规范；仅从可信来源加载工件。\n- **XGBoost** — 主要支持 JSON 模型格式；不支持二进制 booster 格式。\n- **LLVM IR** — 目前以文本形式（`.ll`）输出；需要本地安装 LLVM\u002FClang 才能从中生成原生代码。\n- **MISRA-C** — 内置合规性检查器覆盖了与生成代码最相关的规则；它不能替代经过认证的静态分析工具。\n\n---\n\n## 路线图\n\n| 状态 | 项目 |\n|--------|------|\n| ✅ | XGBoost、LightGBM、scikit-learn、CatBoost、ONNX 前端 |\n| ✅ | 多遍 IR 优化器（死节点消除、量化、分支排序、缩放器融合） |\n| ✅ | 支持 WebAssembly 目标的 C99 代码生成器 |\n| ✅ | 兼容 Ollama 的多工作线程 FastAPI HTTP 推理服务器 |\n| ✅ | 使用 OIDC 可信发布机制的 PyPI 打包 |\n| ✅ | ONNX Linear\u002FSVM\u002FNormalizer\u002FScaler 运算符支持 |\n| ✅ | ARM Cortex-M4\u002FM33 和 RISC-V rv32imf\u002Frv64gc 嵌入式部署配置文件 |\n| ✅ | 符合 MISRA-C:2012 标准的输出模式，并内置合规性检查工具 |\n| ✅ | 具有可配置目标三元组的 LLVM IR 后端 |\n| ✅ | 差分隐私（拉普拉斯 + 高斯）推理模式 |\n| ✅ | 更丰富的 `bench` 报告：P50\u002FP95\u002FP99\u002FP999、CV%、JSON + HTML 输出 |\n| 🔄 | 远程模型注册表（从托管模型库中使用 `timber pull` 下载模型） |\n| 🔲 | 神经网络运算符支持（MLPClassifier） |\n| 🔲 | ONNX 导出路径（Timber IR → ONNX） |\n| 🔲 | Rust 后端代码生成器 |\n\n---\n\n## 开发\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber.git\ncd timber\npip install -e \".[dev]\"\npytest tests\u002F -v                    # 436 个测试用例\nruff check timber\u002F                  # 代码风格检查\n```\n\n测试套件涵盖：解析器（sklearn、ONNX、XGBoost、LightGBM、CatBoost）、IR 层（序列化、深拷贝、所有阶段类型）、优化器 pass（正确性、幂等性、流水线融合数学）、C99\u002FWASM\u002FMISRA-C\u002FLLVM IR 代码生成器（编译与数值精度）、差分隐私（统计正确性、所有数据类型）以及完整的端到端流水线。\n\n完整开发指南请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。\n\n---\n\n## 引用\n\n如果您在研究或生产中使用 Timber，请引用随附的技术论文：\n\n```bibtex\n@misc{royce2026timber,\n  title        = {Timber: 将经典机器学习模型编译为原生推理二进制文件},\n  author       = {Kossiso Royce},\n  year         = {2026},\n  howpublished = {GitHub 仓库和技术论文},\n  institution  = {Electricsheep Africa},\n  url          = {https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber}\n}\n```\n\n完整论文可在 [`paper\u002Ftimber_paper.pdf`](paper\u002Ftimber_paper.pdf) 获取。\n\n---\n\n## 社区与治理\n\n- **贡献指南：** [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- **行为准则：** [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)\n- **安全策略：** [`SECURITY.md`](SECURITY.md)\n- **变更日志：** [`CHANGELOG.md`](CHANGELOG.md)\n\n如遇问题或有功能需求，请 [提交 issue](https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Fissues)。如有疑问，欢迎 [发起讨论](https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Fdiscussions)。\n\n---\n\n## 支持本项目\n\nTimber 由 [Electricsheep Africa](https:\u002F\u002Fgithub.com\u002Felectricsheepafrica) 开发并维护。如果 Timber 能为您的团队节省工程时间，请考虑支持其持续开发：\n\n[![Buy Me A Coffee](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuy%20Me%20A%20Coffee-support-%23FFDD00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https:\u002F\u002Fbuymeacoffee.com\u002Felectricsheepafrica)\n\n我们也在构建一个托管的编译模型库——如果您有高性能模型希望贡献，欢迎 [联系我们](https:\u002F\u002Fgithub.com\u002Fkossisoroyce\u002Ftimber\u002Fdiscussions)。\n\n---\n\n## 许可证\n\nApache-2.0 — 完整许可文本请参阅 [`LICENSE`](LICENSE)。","# Timber 快速上手指南\n\nTimber 是一个高性能编译器，能够将经典的机器学习模型（如 XGBoost、LightGBM、scikit-learn、CatBoost、ONNX）或 URDF 机器人描述文件编译为**原生 C99 代码**。它生成的推理工件无运行时依赖，单样本推理延迟低至 **~2 微秒**，比 Python 实现快约 336 倍。\n\n## 环境准备\n\n*   **操作系统**: Linux, macOS, Windows (需配备 GCC 或 Clang 编译器)\n*   **Python 版本**: Python 3.8+\n*   **前置依赖**:\n    *   `pip` (Python 包管理工具)\n    *   `gcc` 或 `clang` (用于编译生成的 C 代码，通常系统自带或在开发工具包中)\n*   **网络要求**: 首次运行需联网下载模型或访问 PyPI。国内用户若遇网络问题，可配置 pip 国内镜像源。\n\n## 安装步骤\n\n使用 pip 安装 Timber 编译器：\n\n```bash\npip install timber-compiler\n```\n\n> **提示**: 如果下载速度较慢，推荐使用国内镜像源加速安装：\n> ```bash\n> pip install timber-compiler -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n> ```\n\n## 基本使用\n\nTimber 的核心优势在于“一键服务”：无需手动编译配置，直接指向模型文件即可启动高性能推理服务。\n\n### 1. 直接通过 URL 启动服务\n这是最简单的使用方式。Timber 会自动下载模型、检测格式、编译优化并启动 HTTP 服务器。\n\n```bash\ntimber serve https:\u002F\u002Fraw.githubusercontent.com\u002Fkossisoroyce\u002Ftimber\u002Fmain\u002Fexamples\u002Fbreast_cancer_model.json\n```\n\n启动成功后，终端会显示类似以下信息，表明服务正在 `http:\u002F\u002Flocalhost:11434` 运行：\n```text\n✓ Downloaded              breast_cancer_model.json\n✓ Format detected         xgboost\n✓ Compiled binary         47.9 KB\nServing    breast_cancer_model\nEndpoint   http:\u002F\u002Flocalhost:11434\n```\n\n### 2. 发送预测请求\n使用 `curl` 或其他 HTTP 客户端向 API 发送 JSON 数据进行推理。Timber 兼容 Ollama API 格式。\n\n```bash\ncurl -s http:\u002F\u002Flocalhost:11434\u002Fapi\u002Fpredict \\\n    -H 'Content-Type: application\u002Fjson' \\\n    -d '{\"model\": \"breast_cancer_model\", \"inputs\": [[1.799e+01, 1.038e+01, 1.228e+02, 1.001e+03, 0.1184, 0.2776, 0.3001, 0.1471, 0.2419, 0.07871, 1.095, 0.9053, 8.589, 153.4, 0.006399, 0.04904, 0.05373, 0.01587, 0.03003, 0.006193, 2.538e+01, 1.733e+01, 1.846e+02, 2.019e+03, 0.1622, 0.6656, 0.7119, 0.2654, 0.4601, 0.1189]]}'\n```\n\n**返回示例**:\n```json\n{\"model\": \"breast_cancer_model\", \"outputs\": [[0.9971]], \"n_samples\": 1}\n```\n\n### 3. 加载本地模型文件\n如果你已有本地的模型文件（如 `.json`, `.pkl`, `.onnx` 等），可以先注册再启动：\n\n```bash\n# 加载本地模型并命名为 fraud-detector\ntimber load fraud_model.json --name fraud-detector\n\n# 通过名称启动服务\ntimber serve fraud-detector\n```\n\n### 4. 常用 CLI 命令参考\n\n| 命令 | 说明 |\n| :--- | :--- |\n| `timber serve \u003Curl_or_name>` | 启动推理服务器 |\n| `timber load \u003Cpath> --name \u003Cname>` | 编译并注册本地模型 |\n| `timber list` | 列出已注册的模型 |\n| `timber inspect \u003Cname>` | 查看模型结构和元数据 |\n| `timber bench \u003Cname>` | 对模型进行延迟和吞吐量基准测试 |","某金融科技公司的高频反欺诈团队需要在毫秒级内对每笔交易进行风险评分，当前系统基于 Python 运行 XGBoost 模型，但在流量高峰期常出现延迟抖动。\n\n### 没有 timber 时\n- **推理延迟高且不稳定**：Python 解释器开销大，单次预测耗时约 600 微秒，高并发下 GC（垃圾回收）导致延迟毛刺，影响用户体验。\n- **部署依赖复杂**：生产环境必须安装特定版本的 Python、XGBoost 库及各类底层依赖，容器镜像体积庞大，启动缓慢。\n- **资源利用率低**：为维持低延迟，不得不过度配置 CPU 资源，导致服务器成本居高不下。\n- **跨语言调用困难**：核心交易引擎由 C++ 编写，通过 subprocess 或 RPC 调用 Python 服务增加了架构复杂度和故障点。\n\n### 使用 timber 后\n- **极致性能提升**：timber 将模型编译为原生 C99 代码，单次预测仅需约 2 微秒，速度提升 336 倍，彻底消除延迟抖动。\n- **零依赖独立运行**：生成的推理产物仅为 48KB 的二进制文件，无需任何运行时环境，可直接嵌入现有 C++ 服务或作为独立微服务运行。\n- **大幅降低成本**：极高的吞吐量使得单台服务器可处理的请求量翻倍，显著减少了所需的计算节点数量。\n- **架构简化统一**：支持通过一条命令直接启动兼容 Ollama 的 HTTP 服务，或与 C++ 主程序静态链接，消除了跨语言调用的网络开销。\n\ntimber 通过将传统机器学习模型转化为原生机器码，让高频交易场景下的实时推理实现了微秒级响应与极简部署的完美平衡。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fkossisoroyce_timber_dc32ecd2.png","kossisoroyce","Kossiso Udodi","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fkossisoroyce_9a18f10b.jpg","AI infrastructure for underrepresented\r\ncompute environments.\r\nInference for edge devices, low-resource languages, data-sparse markets.","Electric Sheep Africa","Accra",null,"kossisoroyce.com","https:\u002F\u002Fgithub.com\u002Fkossisoroyce",[83,87,91,95,99],{"name":84,"color":85,"percentage":86},"Python","#3572A5",93.1,{"name":88,"color":89,"percentage":90},"TeX","#3D6117",4.5,{"name":92,"color":93,"percentage":94},"TypeScript","#3178c6",1.8,{"name":96,"color":97,"percentage":98},"CSS","#663399",0.4,{"name":100,"color":101,"percentage":102},"Dockerfile","#384d54",0.1,655,20,"2026-04-09T03:51:37","NOASSERTION",1,"未说明","不需要 GPU",{"notes":111,"python":112,"dependencies":113},"该工具将机器学习模型编译为原生 C99 代码，推理过程零运行时依赖（无需 Python 环境）。安装需要 Python 环境以运行编译器，但部署后的推理仅需生成的二进制文件。支持 XGBoost, LightGBM, scikit-learn, CatBoost, ONNX 及 URDF 格式。内置 HTTP 服务器兼容 Ollama API。","3.8+",[114],"gcc 或 clang (用于编译生成的 C99 代码)",[14,35],[117,118,119,120,121,122,123,124,125,126,127,128,129,130],"c99","catboost","compiler","decision-trees","gradient-boosting","inference","lightgbm","machine-learning","mlops","model-serving","ollama","onnx","sklearn","xgboost","2026-03-27T02:49:30.150509","2026-04-11T08:11:50.215005",[],[135,140,145],{"id":136,"version":137,"summary_zh":138,"released_at":139},198036,"v0.5.0","### 新增内容\n\n- **`IsolationForestStage` IR 节点** — 新的 `PipelineStage` 子类，用于基于扁平树结构的异常评分；叶节点值存储预计算的路径长度贡献（`depth + c(n_node_samples)`），因此 C99 推理在运行时无需调用 `log()` 函数；输出为 `−anomaly_score − offset`（正值表示内点）。\n- **`NaiveBayesStage` IR 节点** — 高斯朴素贝叶斯模型；存储每个类别的对数先验、均值（`theta`）、预计算的 `log_var_const` 和 `inv_2var`，以消除运行时的 `log()` 和除法操作；输出为 softmax 归一化结果。\n- **`GPRStage` IR 节点** — 高斯过程回归器（RBF 核）；存储训练点、`alpha` 向量以及预计算的 `inv_2ls2` 和 `amp2` 常量；通过 `y_train_mean` 和 `y_train_std` 对输出进行归一化。\n- **`KNNStage` IR 节点** — k 最近邻分类器或回归器（查表法）；支持欧几里得和曼哈顿距离度量；分类器输出获胜类别的索引，回归器输出平均标签向量。\n- **`SVMStage.is_one_class`** — 为 `SVMStage` 添加布尔标志，用于 `OneClassSVM`；更新了序列化和反序列化逻辑；决策函数为 `decision_function = sum(alpha_i × K) + intercept_`。\n- **适用于所有 5 种新基元的 sklearn 解析器**（`timber\u002Ffrontends\u002Fsklearn_parser.py`）：\n  - `_parse_isolation_forest` — 重新映射子采样的特征索引；预先计算 BFS 深度；为每棵树设置 `max_depth`，以确保正确的 C99 保护条件。\n  - `_parse_one_class_svm` — 提取 `_gamma`，处理 `scale`\u002F`auto`\u002F数值型 gamma 参数。\n  - `_parse_naive_bayes` — 根据 `GaussianNB.var_` 预计算 `log_var_const` 和 `inv_2var`。\n  - `_parse_gpr` — 遍历 `ConstantKernel * RBF` 核函数树；提取 `length_scale` 和 `amplitude`；安全地从 `_y_train_mean` 和 `_y_train_std` 中提取标量值。\n  - `_parse_knn` — 处理 `KNeighborsClassifier` 和 `KNeighborsRegressor`；映射 `minkowski`、`l1` 和 `l2` 等别名。\n- **适用于所有 5 种新基元的 C99 代码生成器**（`timber\u002Fcodegen\u002Fc99.py`）：\n  - 隔离森林：使用双精度阈值和路径长度的 `iforest_traverse()` 函数；异常分数为 `exp2(−mean_path \u002F c_max)`。\n  - 朴素贝叶斯：累积对数似然并进行数值稳定的 softmax 归一化。\n  - 高斯过程回归：使用双精度累加器进行 RBF 核矩阵与向量的乘积。\n  - k 最近邻：可配置的距离度量；利用最小堆获取前 k 个最近邻；采用多数投票或平均聚合方式。\n- **119 个核测试**（`tests\u002Ftest_primitives.py`），涵盖 IR 循环往返、sklearn 解析字段正确性、C99 代码结构、编译以及与 sklearn 参考实现相比的数值精度，适用于所有 5 种基元。\n\n- **URDF 正运动学前端**（`timber\u002Ffrontends\u002Furdf_parser.py`）— `URDFParser` 将 URDF XML 解析为 `KinematicsStage` IR；自动检测基座连杆和末端执行器；支持所有类型的关节（旋转、移动、连续、固定）。\n- **`JointSpec` IR 节点** — 新的数据类，包含关节名称、类型、轴向、原点（xyz + rpy）、父\u002F子连杆以及位置限制；支持完整的 JSON 序列化循环往返。\n- **`KinematicsStage` IR 节点** — 新的 `PipelineStage` 子类，包含 `list[JointSpec]`、`base_link`、`end_effector` 以及计算出的自由度数 `n_dof`。","2026-03-13T12:34:21",{"id":141,"version":142,"summary_zh":143,"released_at":144},198037,"v0.4.0","### 新增内容\n\n- **ONNX Linear\u002FSVM\u002FNormalizer\u002FScaler 前端** — `parse_onnx_model()` 现在除了处理 `TreeEnsemble` 外，还支持另外六种 ONNX ML opset 操作符：\n  - `LinearClassifier` — 支持二分类（sigmoid）和多分类（softmax），并能正确提取每行的权重；\n  - `LinearRegressor` — 使用恒等激活函数，输出维度可任意设置；\n  - `SVMClassifier` — 支持 RBF 和线性核，并完整提取支持向量矩阵；\n  - `SVMRegressor` — 与分类器相同，支持 RBF 和线性核；\n  - `Normalizer` — 提供 L1、L2 和最大值归一化，作为 `NormalizerStage` 预处理步骤；\n  - `Scaler` — 提供均值平移和缩放操作，作为 `ScalerStage` 预处理步骤；可通过管道融合与下游树模型合并。\n  \n- **`LinearStage` IR 节点** — 新增 `PipelineStage` 子类，用于存储权重、偏置、激活函数（`none`、`sigmoid` 或 `softmax`）、类别数 (`n_classes`) 以及是否使用多权重标志 (`multi_weights`)；支持完整的 JSON 序列化往返。\n  \n- **`SVMStage` IR 节点** — 新增 `PipelineStage` 子类，用于存储支持向量矩阵、对偶系数、截距项 (`rho`)、核参数 (`gamma`, `coef0`, `degree`) 以及核类型；支持完整的 JSON 序列化往返。\n  \n- **`NormalizerStage` IR 节点** — 新增 `PipelineStage` 子类；支持完整的 JSON 序列化往返。\n  \n- **C99 代码生成器：Linear 和 SVM 后端** — `C99Emitter.emit()` 现在会将 `LinearStage` 和 `SVMStage` 分发到专用的代码生成器：\n  - `_emit_inference_linear` — 展开点积计算，支持 sigmoid（二分类）、softmax（多分类）或恒等（回归）激活函数；\n  - `_emit_inference_svm` — 支持 RBF 核（`exp(-γ·‖x−sv‖²)`）或线性核，并在后处理中应用 `tanh` 变换；\n  - 所有输出都会被限制在 `n_outputs` 范围内，以防止缓冲区溢出。\n  \n- **嵌入式部署配置文件** — `TargetSpec.for_embedded(profile)` 为四种目标选择交叉编译工具链；由 `C99Emitter` 生成的 Makefile 会自动切换：\n  - `cortex-m4` — `arm-none-eabi-gcc -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=hard`；\n  - `cortex-m33` — `arm-none-eabi-gcc -mcpu=cortex-m33 -mfpu=fpv5-sp-d16 -mfloat-abi=hard`；\n  - `rv32imf` — `riscv32-unknown-elf-gcc -march=rv32imf -mabi=ilp32f`；\n  - `rv64gc` — `riscv64-unknown-elf-gcc -march=rv64gc -mabi=lp64d`；\n  - 在嵌入式目标上不启用 `-fPIC` 或 `-shared` 标志，而是生成 `.a` 静态库而非 `.so` 共享库。\n  \n- **LLVM IR 后端**（`timber\u002Fcodegen\u002Fllvm_ir.py`）— 新增 `LLVMIREmitter`，支持 `TreeEnsembleStage`、`LinearStage` 和 `SVMStage`；可配置目标三元组（`x86_64`、`aarch64`、`cortex-m4` 等）；生成 `model.ll` 文件，采用 SSA 形式，为每棵树生成命名的 `traverse_tree_N` 函数，并提供 `timber_infer_single` 入口函数。\n  \n- **差分隐私模块**（`timber\u002Fprivacy\u002Fdp.py`）— `apply_dp_noise(outputs, cfg)` 会在推理输出中注入经过校准的噪声；功能包括：\n  - 拉普拉斯机制：噪声尺度 = `敏感度 \u002F epsilon`；\n  - 高斯机制：σ = `√(2 ln(1.25\u002Fδ)) · 敏感度 \u002F epsilon`；\n  - `DPConfig` — 验证 `epsilon > 0`、`敏感度 > 0`、`delta ∈ (0,1)`（仅适用于高斯机制），并指定使用的机制名称；\n  - `DPReport` — 返回噪声尺度、所用机制、被加噪的输出数量以及 epsilon 的值。","2026-03-04T09:36:14",{"id":146,"version":147,"summary_zh":148,"released_at":149},198038,"v0.2.0","### 修复\n\n- **XGBoost 3.1+ 多分类 `base_score`** — XGBoost 3.1+ 将每个类别的 base score 序列化为逗号分隔的方括号字符串（例如 `'[-3.95E-2,1.97E-1,-1.57E-1]'`）。此前，Timber 只保留第一个值，并将所有类别的累加器初始化为 `0.0`，从而导致概率误差高达 7.5%。现在，完整的类别向量会被正确解析并应用。\n\n### 新增\n\n- 在 `TreeEnsembleStage` IR 中新增 `per_class_base_scores: list[float]` 字段，并支持完整的序列化\u002F反序列化\n- 在 `xgboost_parser.py` 中添加 `_parse_base_score_list()` 辅助函数，用于在不同 XGBoost 版本中稳健地解析 base score\n- 为多分类模型在 `model_data.c` 中输出 `TIMBER_CLASS_BASE_SCORES[]` 静态数组\n- 全面重构文档 — 扩展了全部四页文档，并在仓库根目录下新增 `llms.txt`\n- 添加 `mkdocs.yml` 以定义文档站点结构\n\n### 变更\n\n- 版本号从 `0.1.0` 升级至 `0.2.0`\n- 完全重写了 README：包含实时终端演示、编译器流水线图、完整的 CLI 和 API 参考表、运行时对比功能矩阵，以及带有状态指示器的路线图\n\n---","2026-03-03T13:05:36"]