https://github.com/w2jmoe/wisepick
Decision Infrastructure for the AI Era. 🧠✨️🤺
https://github.com/w2jmoe/wisepick
adapter-pattern agent-infrastructure agent-orchestration agent-runtime capability-routing decision-routing deterministic-orchestration deterministic-routing execution-routing llm-ops low-latency mcp multi-agent routing-middleware runtime-intelligence
Last synced: about 6 hours ago
JSON representation
Decision Infrastructure for the AI Era. 🧠✨️🤺
- Host: GitHub
- URL: https://github.com/w2jmoe/wisepick
- Owner: w2jmoe
- License: apache-2.0
- Created: 2026-05-05T10:19:16.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-05-30T08:31:26.000Z (1 day ago)
- Last Synced: 2026-05-30T10:12:35.751Z (1 day ago)
- Topics: adapter-pattern, agent-infrastructure, agent-orchestration, agent-runtime, capability-routing, decision-routing, deterministic-orchestration, deterministic-routing, execution-routing, llm-ops, low-latency, mcp, multi-agent, routing-middleware, runtime-intelligence
- Language: Python
- Homepage:
- Size: 313 KB
- Stars: 14
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# WisePick | 智选
> **Docs:** [Overview](./README.md) | [Integration & SDK](./README_API.md) | [Agent Protocol](./AGENTS.md)
**The deterministic layer that helps agent runtimes make better execution decisions.**
**帮助 Agent Runtime 做出更优执行决策的确定性层。**
[](https://github.com/w2jmoe/WisePick/stargazers)
[](./LICENSE)
[](https://twitter.com/w2jmoe)
---
## 🚀 WisePick Decision API (WPDA)
* Deterministic capability selection for AI agents.
* 为 AI Agent 提供确定性能力选择。
### What it is | 智选是什么
WisePick is a small decision layer for agent runtimes. It takes an intent, picks the best capability, and improves from execution feedback.
智选是一个面向 Agent Runtime 的轻量决策层：输入意图，选择最合适的能力，并从执行反馈中持续优化。
### Who is it for | 适用于谁
* Agent Operators
* Agent Runtime Builders
* Internal Agent Teams
* Agent SaaS Platforms
* Agent Hosting Providers
For teams running real agent workflows.
面向运行真实 Agent Workflow 的团队。
### Why it matters | 为什么重要
WisePick cuts tool searching, retry loops, latency, and cost by reusing execution feedback.
智选通过复用执行反馈，减少工具搜索、重试循环、延迟和成本。
## 🌐 Ecosystem Alignment | 生态兼容
[](https://github.com/yantrikos/yantrikdb-server)
[](https://github.com/avivsinai/langfuse-mcp)
[](https://github.com/dgenio/ChainWeaver)
[](https://github.com/Colin4k1024/Aetheris)
[](https://github.com/azender1/SafeAgent)
[](https://github.com/gryszzz/open-thymos)
---
## 📘 Contents | 目录
| Core Sections | 核心章节 |
| :--------------------------------------------------------------------------- | :-------- |
| [🚀 Quick Start](#-quick-start--快速启动) | 快速启动 |
| [⚡ Why Integrate WisePick](#-why-integrate-wisepick--为什么接入智选) | 为什么接入智选 |
| [📜 Performance Benchmarks](#-performance--cost-benchmarks--性能与成本报告) | 性能与成本报告 |
| [🔌 Integration Specification](#-integration--router-specification--集成与路由规范) | 集成与路由规范 |
| [🧠 How It Works](#-how-it-works--工作原理) | 工作原理 |
| [🏗️ Architectural Paradigm](#%EF%B8%8F-architectural-paradigm--架构范式演进) | 架构范式演进 |
| [🧪 Agent Workflow](#-agent-workflow--agent-工作流) | Agent 工作流 |
| [🗺️ Roadmap](#%EF%B8%8F-roadmap--路线图) | 路线图 |
---
## 🚀 Quick Start | 快速启动
> WisePick Decision API (WPDA) is routing infrastructure for agent runtimes.
> Deploy it as an independent API service; integrate it through the SDK.
>
> 智选 Decision API（WPDA）是面向 Agent Runtime 的路由基础设施。
> 请将其作为独立 API 服务部署，并通过 SDK 接入。
### 1. Start Server | 启动服务
```bash
git clone https://github.com/w2jmoe/WisePick.git
cd WisePick
cp .env.example .env
# Configure DATABASE_URL
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
### 2. Integrate SDK | 接入 SDK
See the [15-Minute Integration Guide](./README_API.md%2315-minute-integration-checklist).
查看 [15分钟接入指南](./README_API.md%2315-minute-integration-checklist)。
**Help us refine:** If you find the docs confusing, please [open an issue](https://github.com/w2jmoe/WisePick/issues) — we are aggressively refining our integration flow.
**反馈建议：** 若您在接入中遇到任何困惑，请 [提交 Issue](https://github.com/w2jmoe/WisePick/issues)，我们正在全力优化文档与接入体验。
---
## ⚡ Why Integrate WisePick | 为什么接入智选
* Lower cost and latency by cutting trial-and-error.
更低成本与延迟：减少无效试错与 Token 浪费。
* One best capability per decision.
每次决策只选一个最合适的能力。
* Feedback makes the next decision better.
执行反馈让下一次选择更好。
---
## 📜 Performance & Cost Benchmarks | 性能与成本报告
Production-oriented deterministic routing vs. native LLM tool-calling. Tested inside a Hermes-style agent runtime.
面向生产的确定性路由与原生 LLM 工具调用的对比测试。已在 Hermes 类 Agent 运行时中完成验证。
### Runtime Efficiency | 运行时效率提升
| Metrics | Native LLM | WisePick | Optimization |
| --------------------- | ---------- | ---------------- | -------------------------------- |
| **🚀 Path Speed** | Baseline | **~31% Faster** | Shrunk from 6.33 to 4.33 steps |
| **⏱️ Time Saved** | Baseline | **~62% Saved** | Benchmark cut from 12m to 4m30s |
| **💵 Cost Cut** | High | **~33% Reduced** | $0.15 → $0.10 per session |
| **🎯 First-Hit Rate** | Exp. | **100% Locked** | Zero hallucinated tool-selection |
### Key Capabilities | 核心优势
* **Zero-Latency Gatekeeping**: Sub-millisecond average latency under isolated routing-core stress testing.
（隔离路由核心压测下平均亚毫秒级延迟）
* **Anti-Loop Depth**: Stabilizes execution across 20+ mixed-tool tasks without infinite loops.
（在 20+ 混合工具任务下稳定运行，彻底消除无限循环路径）
Benchmark scripts & instrumentation: [BENCHMARK](./benchmark/) | [STRESS_TEST_RESULTS.md](./docs/STRESS_TEST_RESULTS.md)
---
## 🔌 Integration & Router Specification | 集成与路由规范
WisePick is stateless. You own execution; we provide routing.
智选是无状态决策层：由你负责执行，我们负责路由。
* **For Human Builders / 面向人类开发者 ([README_API.md](./README_API.md)):** SDK integration, programmatic turn interception, multi-turn lock release, and execution hook feedback closure.
SDK 代码集成、首轮意图拦截、多轮强制解锁以及执行钩子反馈闭环。
* **For AI Agents & Automation / 面向智能体与自动配置 ([AGENTS.md](./AGENTS.md)):** Machine-readable `wisepick.agent.v1` manifest contract, protocol state machine mapping, and runtime environment declaration.
机器可读的声明式配置清单契约、协议状态机映射以及运行时环境依赖声明。
---
## 🧠 How It Works | 工作原理
### Capability Matching | 能力匹配
Task text → capability labels derived from bootstrap rules.
任务文本 → 由引导规则得到能力标签。
### Capability Scoring | 能力评分
```text
score =
capability_match * 0.40 (语义匹配度 - 核心逻辑)
execution_success_rate * 0.20 (历史可靠性)
efficiency_factor * 0.20 (执行效率 - 基于 avg_latency_ms)
economy_factor * 0.10 (成本性价比 - 基于 avg_token_cost)
bootstrap_weight * 0.10 (初始冷启动权重)
```
### Feedback Loop | 反馈闭环
```text
decision → execution → feedback → capability_stats → next decision
Routing updates from real execution outcomes.
路由统计随真实执行结果更新。
```
### Components | 核心组件
```text
Routing Core (decision_engine)
Converts incoming tasks into ECU scores and selects the best capability.
将输入任务转换为 ECU（执行单元）评分并进行路由决策。
Capability Registry (api_tool_specs)
Maintains available providers, capability labels, and bootstrap weights.
管理可用 Provider、能力标签及冷启动权重分配。
Execution Memory (tool_stats, feedback)
Stores execution feedback reported by your runtime and continuously improves routing quality.
存储由运行时上报的执行反馈，并持续优化路由质量。
```
---
## 🏗️ Architectural Paradigm | 架构范式演进
WisePick unifies both hard-coded and dynamic tool discovery under a deterministic routing layer.
智选将硬编码与动态发现路线统一于确定性路由层。
| Paradigm | Discovery | Runtime Pain | WisePick Value |
| ----------- | -------------- | ---------------------------------------------------------- | --------------------------------------------------- |
| **Static** | Manual config | Brittle scaling, zero runtime flexibility | Centralized ECU registry, cleaner code |
| **Dynamic** | Auto-discovery | **Tool Anxiety:** Context explosion, loops, hallucinations | **Deterministic Filter:** Cuts 95% noise, 100% lock |
## 🔬 ECU Response (with ROI Metrics) | 带有 ROI 指标的 ECU 响应
> **ECU (Executable Capability Unit)**
>
> A standardized executable capability an agent can route, invoke, and learn from.
>
> 可执行能力单元：可被路由、调用并通过反馈学习的标准化能力抽象。
```json
{
"metadata": {
"schema_version": "mcp.route_decision.v1",
"decision_id": "dec_abc123def4567890",
"trace_id": "trace_9876543210abcdef",
"router_name": "wisepick",
"capability_id": "audio_transcription",
"provider": "feishu_minutes",
"execution_type": "api",
"callable": true,
"confidence": 0.87,
"latency_ms": 450,
"candidate_count": 1,
"top_candidates": [
{
"rank": 1,
"capability_id": "audio_transcription",
"score": 0.87,
"selected": true
}
],
"reason_codes": ["capability_match"]
}
}
```
WisePick predicts performance before execution to ensure the best ROI.
WisePick 在执行前预测性能，以确保最佳投资回报率 (ROI)。
---
## 🧪 Agent Workflow | Agent 工作流
```mermaid
graph LR
A[Ask Routing] --> B(Receive ECU)
B --> C{Map to Local Implementation}
C --> D[Execute]
D --> E[Send Feedback]
E -.->|Updates ROI Models| A
```
WisePick provides decision intelligence and feedback loops—not task execution.
智选提供决策智能与反馈闭环；**不替代**任务执行本身。
---
## 🔮 Vision | 愿景
**Long-term: Execution Experience Network — collective decision memory across agent runtimes.**
**长期愿景：执行经验网络（Execution Experience Network）— 跨运行时的集体决策记忆。**
**Today:** [WisePick Decision API (WPDA)](#-wisepick-decision-api-wpda) delivers deterministic capability routing and execution feedback via SDK integration; your runtime owns invoke, policy, and retries.
**当前：** [WisePick Decision API（WPDA）](#-wisepick-decision-api-wpda) 通过 SDK 提供确定性能力路由与执行反馈；工具调用、策略与重试由您的运行时负责。
WisePick turns execution outcomes into reusable routing experience — the foundation for shared ECU feedback and feedback-driven execution optimization on the path to that network.
智选将执行结果沉淀为可复用的路由经验，为 ECU 反馈共享与反馈驱动的执行优化奠定基础，并沿路线图演进至上述网络愿景。
---
## 🗺️ Roadmap | 路线图
* **✅ v0.1**: Core Infrastructure · 核心路由与反馈闭环
* Deterministic ECU routing & feedback loop.
* Multi-dimensional ROI metrics aggregation (Latency / Cost / Quality).
* **🔄 v0.2**: Runtime-Aware Optimization · Runtime 感知执行优化
* Task-level capability routing for multi-agent runtimes.
* Adaptive execution-path optimization based on latency / cost / quality feedback.
* Lightweight integration adapters for orchestration frameworks.
* **🔄 v0.3**: Collective Decision Memory · 集体决策记忆
* Cross-agent experience sharing (Execution Experience Network direction).
* Global capability indexing & optimization.
---
## 🤗 Feedback & Integration | 反馈与集成
* **Issues:** [GitHub Issues](https://github.com/w2jmoe/WisePick/issues)
* **Email:** w2jmoe@gmail.com
**Every routing decision feeds execution feedback today — and collective decision memory as the platform evolves toward the Execution Experience Network vision.**
**每一次路由决策都会形成执行反馈；随平台演进，亦将沉淀为集体决策记忆，迈向执行经验网络愿景。˗ˋˏ( ´͈ ᗜ `͈ )ˎˊ˗**
---
## 🌸 License | 许可协议
Apache License 2.0 — see [LICENSE](./LICENSE).
