reliablekit 0.1.0__py3-none-any.whl

reliable/__init__.py

@@ -0,0 +1,17 @@
+"""reliable —— 给 LLM/Agent 调用的超时 + 退避 + 熔断，重试风暴防护是一等公民。"""
+
+from .backoff import exp_backoff
+from .breaker import CircuitBreaker, State
+from .decorator import reliable
+from .exceptions import CircuitOpenError, ReliableError
+
+__all__ = [
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "ReliableError",
+    "State",
+    "exp_backoff",
+    "reliable",
+]
+
+__version__ = "0.1.0"

reliable/backoff.py

@@ -0,0 +1,31 @@
+"""指数退避 + 抖动。
+
+W1 范围：确定性指数退避，抖动在 ±jitter 区间内均匀取值。
+设计动机（来自大规模分布式系统的故障检测经验）：不带抖动的固定退避会让
+大量客户端在同一时刻同步重试，形成重试风暴。
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+
+def exp_backoff(
+    attempt: int,
+    base: float = 0.2,
+    factor: float = 2.0,
+    jitter: float = 0.1,
+    rng: Callable[[], float] = random.random,
+) -> float:
+    """计算第 attempt 次重试前的等待秒数。
+
+    attempt 从 0 开始；delay = base * factor**attempt，再乘以
+    (1 + jitter * U(-1, 1)) 的抖动因子。jitter=0 时结果确定。
+    """
+    if attempt < 0:
+        raise ValueError("attempt must be >= 0")
+    if base < 0 or factor <= 0:
+        raise ValueError("base must be >= 0 and factor must be > 0")
+    delay = base * (factor**attempt)
+    return max(0.0, delay * (1.0 + jitter * (rng() * 2.0 - 1.0)))

reliable/breaker.py

@@ -0,0 +1,147 @@
+"""滑动窗口熔断器：CLOSED -> OPEN -> HALF_OPEN -> CLOSED 三态状态机。
+
+设计取舍（来自一次生产级故障复盘，写在这里防止将来自己忘）：
+
+1. 熔断判定看"滑动窗口失败率"，不看连续失败次数。
+   连续 N 次失败才熔断的策略对"偶发抖动 + 低流量"场景过于迟钝，
+   对"突发风暴"又过于敏感；窗口失败率对两者都更稳。
+
+2. HALF_OPEN 的放行不设并发名额闸门（probe 语义 = 连续成功 N 次才闭合）。
+   名额闸门在探针调用挂死（未走到 record）时会死锁在 half_open，
+   一次生产故障复盘里"idle 看门狗假阳性"就是同类坑。v0.1 用简单语义换正确性，
+   并发闸门放路线图。
+
+3. 时钟与随机源可注入，测试不 sleep。
+"""
+
+from __future__ import annotations
+
+import random
+import threading
+import time
+from collections import deque
+from enum import Enum
+from typing import Callable
+
+from .exceptions import CircuitOpenError
+
+
+class State(Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitBreaker:
+    """滑动窗口失败率熔断器。
+
+    参数:
+        failure_rate: 窗口内失败率达到该值即熔断（0 < r <= 1）。
+        window:       滑动窗口样本数（成功+失败），deque 自动滑动。
+        cooldown:     OPEN 后等待多少秒才允许半开探测。
+        probe:        HALF_OPEN 下需要连续成功多少次才回到 CLOSED。
+        clock/rng:    可注入时钟与随机源（测试用）。
+    """
+
+    def __init__(
+        self,
+        failure_rate: float = 0.5,
+        window: int = 20,
+        cooldown: float = 30.0,
+        probe: int = 3,
+        clock: Callable[[], float] = time.monotonic,
+        rng: Callable[[], float] = random.random,
+    ) -> None:
+        if not 0 < failure_rate <= 1:
+            raise ValueError("failure_rate must be in (0, 1]")
+        if window < 1:
+            raise ValueError("window must be >= 1")
+        if cooldown < 0:
+            raise ValueError("cooldown must be >= 0")
+        if probe < 1:
+            raise ValueError("probe must be >= 1")
+        self.failure_rate = failure_rate
+        self.window = window
+        self.cooldown = cooldown
+        self.probe = probe
+        self._clock = clock
+        self._rng = rng
+        self._lock = threading.Lock()
+        self._results: deque[bool] = deque(maxlen=window)
+        self._state = State.CLOSED
+        self._opened_at: float | None = None
+        self._half_open_results: list[bool] = []
+
+    @property
+    def state(self) -> State:
+        with self._lock:
+            return self._state
+
+    def before_call(self) -> None:
+        """调用前检查；OPEN 且未到冷却时间时抛 CircuitOpenError。"""
+        with self._lock:
+            now = self._clock()
+            if self._state is State.OPEN:
+                if self._opened_at is None:
+                    self._opened_at = now
+                elapsed = now - self._opened_at
+                if elapsed >= self.cooldown:
+                    self._state = State.HALF_OPEN
+                    self._half_open_results = []
+                else:
+                    raise CircuitOpenError(
+                        f"circuit is OPEN, retry after {self.cooldown - elapsed:.1f}s",
+                        retry_after=self.cooldown - elapsed,
+                    )
+            # CLOSED / HALF_OPEN 均放行
+
+    def record_success(self) -> None:
+        with self._lock:
+            if self._state is State.HALF_OPEN:
+                self._half_open_results.append(True)
+                if len(self._half_open_results) >= self.probe:
+                    self._state = State.CLOSED
+                    self._half_open_results = []
+                    self._results.clear()
+                    self._opened_at = None
+            else:
+                self._results.append(True)
+
+    def record_failure(self) -> None:
+        with self._lock:
+            if self._state is State.HALF_OPEN:
+                self._trip()
+                return
+            self._results.append(False)
+            if len(self._results) >= self.window:
+                failures = self._results.count(False)
+                if failures / len(self._results) >= self.failure_rate:
+                    self._trip()
+
+    def _trip(self) -> None:
+        self._state = State.OPEN
+        self._opened_at = self._clock()
+        self._half_open_results = []
+
+    def stats(self) -> dict:
+        """返回当前状态与窗口统计，便于观测/接入 MCP 资源。
+
+        返回字段：state（closed/open/half_open）、failure_rate_threshold、
+        window、window_total、window_failures、window_failure_rate、
+        cooldown、probe、opened_at。
+        """
+        with self._lock:
+            results = list(self._results)
+            total = len(results)
+            failures = results.count(False) if total else 0
+            return {
+                "state": self._state.value,
+                "failure_rate_threshold": self.failure_rate,
+                "window": self.window,
+                "window_total": total,
+                "window_failures": failures,
+                "window_failure_rate": (failures / total) if total else 0.0,
+                "cooldown": self.cooldown,
+                "probe": self.probe,
+                "opened_at": self._opened_at,
+            }

reliable/decorator.py

@@ -0,0 +1,102 @@
+"""reliable 装饰器：timeout + 指数退避重试 + 熔断 + 降级回调。
+
+用法::
+
+    breaker = CircuitBreaker(failure_rate=0.5, window=20, cooldown=30.0, probe=3)
+
+    @reliable(breaker=breaker, timeout=8.0, max_attempts=5,
+              on_open=lambda *a, **k: cache_fallback())
+    def call_llm(prompt: str) -> str:
+        ...
+
+已知取舍（v0.1）：
+- timeout 语义是"放弃等待"——底层线程仍在运行，生产上请配合
+  HTTP 客户端自身的超时；asyncio 原生版本在路线图。
+"""
+
+from __future__ import annotations
+
+import functools
+import random
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, TypeVar
+
+from .backoff import exp_backoff
+from .breaker import CircuitBreaker
+from .exceptions import CircuitOpenError
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def reliable(
+    fn: F | None = None,
+    *,
+    breaker: CircuitBreaker | None = None,
+    timeout: float | None = None,
+    max_attempts: int = 5,
+    base_delay: float = 0.2,
+    factor: float = 2.0,
+    jitter: float = 0.1,
+    sleep: Callable[[float], None] = time.sleep,
+    rng: Callable[[], float] = random.random,
+    on_open: Callable[..., Any] | None = None,
+) -> Callable:
+    """把同步函数包上超时 / 重试 / 熔断 / 降级。
+
+    - 每次 attempt 前先问熔断器；OPEN 且未到冷却则抛 CircuitOpenError，
+      若提供 on_open 则调用其返回值作为降级结果。
+    - 任何异常（含超时）都记为一次失败并触发退避；成功记为成功。
+    - 支持 ``@reliable`` 与 ``@reliable(...)`` 两种写法。
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+
+    def decorator(f: F) -> F:
+        @functools.wraps(f)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            last_exc: BaseException | None = None
+            for attempt in range(max_attempts):
+                if breaker is not None:
+                    try:
+                        breaker.before_call()
+                    except CircuitOpenError:
+                        if on_open is not None:
+                            return on_open(*args, **kwargs)
+                        raise
+                try:
+                    result = _invoke(f, args, kwargs, timeout)
+                except Exception as exc:
+                    if breaker is not None:
+                        breaker.record_failure()
+                    last_exc = exc
+                    if attempt < max_attempts - 1:
+                        sleep(exp_backoff(attempt, base_delay, factor, jitter, rng))
+                else:
+                    if breaker is not None:
+                        breaker.record_success()
+                    return result
+            assert last_exc is not None
+            raise last_exc
+
+        return wrapper  # type: ignore[return-value]
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def _invoke(
+    fn: Callable[..., Any],
+    args: tuple,
+    kwargs: dict,
+    timeout: float | None,
+) -> Any:
+    if timeout is None:
+        return fn(*args, **kwargs)
+    executor = ThreadPoolExecutor(max_workers=1)
+    try:
+        future = executor.submit(fn, *args, **kwargs)
+        return future.result(timeout=timeout)
+    finally:
+        executor.shutdown(wait=False)

reliable/exceptions.py

@@ -0,0 +1,18 @@
+"""reliable 的异常定义。"""
+
+from __future__ import annotations
+
+
+class ReliableError(Exception):
+    """reliable 库的异常基类。"""
+
+
+class CircuitOpenError(ReliableError):
+    """熔断器处于 OPEN（或半开名额已拒绝）时发起调用。
+
+    携带剩余冷却秒数，调用方可据此决定等待或直接降级。
+    """
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after

reliable/mcp.py

@@ -0,0 +1,222 @@
+"""reliable 的 MCP server 骨架。
+
+把库里的容错原语暴露成 LLM Agent 可直接调用的工具：
+- 给每个下游依赖（如某个 LLM provider）建一个命名熔断器；
+- 通过熔断器发起带超时/退避/降级的 HTTP 调用；
+- 查询熔断状态、预览退避节奏。
+
+运行（stdio，供 Claude / mcp.so / Smithery 接入）::
+
+    pip install -e ".[mcp]"
+    python -m reliable.mcp
+    # 或 reliable-mcp（安装后由 console script 提供）
+
+设计取舍：server 内用进程内字典保存命名熔断器（单实例、线程安全由
+CircuitBreaker 自身保证）。多副本场景需要共享状态时，把 _BREAKERS 换成
+Redis/etcd 后端即可——这点与"可插拔存储后端"的设计原则同构。
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from . import CircuitBreaker, CircuitOpenError, exp_backoff, reliable
+
+mcp = MCPServer("reliable")
+
+# 进程内命名熔断器注册表：name -> CircuitBreaker
+_BREAKERS: dict[str, CircuitBreaker] = {}
+
+
+def _get_breaker(name: str) -> CircuitBreaker | None:
+    return _BREAKERS.get(name)
+
+
+def _parse_headers(headers: str | None) -> dict[str, str]:
+    if not headers:
+        return {}
+    return json.loads(headers)
+
+
+def _encode(body: str | None) -> bytes | None:
+    return body.encode("utf-8") if body is not None else None
+
+
+def _http(method: str, url: str, headers: dict, payload: bytes | None, timeout: float) -> str:
+    req = urllib.request.Request(
+        url, data=payload, method=method.upper(), headers=headers
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read().decode("utf-8", "replace")
+
+
+@mcp.tool()
+def create_breaker(
+    name: str,
+    failure_rate: float = 0.5,
+    window: int = 20,
+    cooldown: float = 30.0,
+    probe: int = 3,
+) -> dict:
+    """Register or replace a named circuit breaker.
+
+    Use one breaker per downstream dependency (e.g. one per LLM provider).
+    The breaker lives in the server process for its lifetime.
+
+    Args:
+        name: unique breaker id, e.g. "openai", "local-llm".
+        failure_rate: trip when the sliding-window failure rate >= this (0..1).
+        window: number of recent calls in the sliding window.
+        cooldown: seconds the breaker stays OPEN before probing.
+        probe: consecutive HALF_OPEN successes required to close.
+    """
+    _BREAKERS[name] = CircuitBreaker(
+        failure_rate=failure_rate, window=window, cooldown=cooldown, probe=probe
+    )
+    return {"name": name, "created": True, **_BREAKERS[name].stats()}
+
+
+@mcp.tool()
+def get_breaker_state(name: str) -> dict:
+    """Return the current state and stats of a named breaker.
+
+    Args:
+        name: breaker id previously created with create_breaker.
+
+    Returns state (closed/open/half_open), failure-rate threshold, window
+    stats, cooldown and probe config.
+    """
+    b = _get_breaker(name)
+    if b is None:
+        return {"error": f"unknown breaker: {name}"}
+    return {"name": name, **b.stats()}
+
+
+@mcp.tool()
+def compute_backoff(
+    attempt: int,
+    base_delay: float = 0.2,
+    factor: float = 2.0,
+    jitter: float = 0.1,
+) -> dict:
+    """Compute the exponential backoff delay for a retry attempt (pure).
+
+    No side effects — handy to preview retry pacing before committing config.
+
+    Args:
+        attempt: 1-based retry index.
+        base_delay: initial delay in seconds.
+        factor: growth multiplier per attempt.
+        jitter: +/- fraction of randomness (0 disables it).
+    """
+    delay = exp_backoff(attempt, base_delay, factor, jitter)
+    return {"attempt": attempt, "delay": delay}
+
+
+@mcp.tool()
+def reliable_http_call(
+    breaker: str,
+    url: str,
+    method: str = "POST",
+    headers: str | None = None,
+    body: str | None = None,
+    timeout: float = 8.0,
+    max_attempts: int = 5,
+    base_delay: float = 0.2,
+    factor: float = 2.0,
+    jitter: float = 0.1,
+    fallback: str | None = None,
+) -> dict:
+    """Call an HTTP endpoint through a named circuit breaker.
+
+    The breaker is auto-created with default config if the name is new.
+    On breaker OPEN the call short-circuits and returns `fallback` (or an
+    error) instead of hammering the downstream — that is the retry-storm
+    guard this library exists for.
+
+    Args:
+        breaker: breaker id (auto-created if absent).
+        url: target URL.
+        method: HTTP method (default POST).
+        headers: JSON string of request headers.
+        body: request body as string/JSON.
+        timeout: per-attempt timeout in seconds.
+        max_attempts: total tries including the first.
+        base_delay / factor / jitter: retry backoff config.
+        fallback: JSON string returned when the call cannot succeed.
+    """
+    b = _get_breaker(breaker) or _BREAKERS.setdefault(breaker, CircuitBreaker())
+
+    try:
+        result = reliable(
+            breaker=b,
+            timeout=timeout,
+            max_attempts=max_attempts,
+            base_delay=base_delay,
+            factor=factor,
+            jitter=jitter,
+        )(_http)(method, url, _parse_headers(headers), _encode(body), timeout)
+        return {"ok": True, "breaker": breaker, "state": b.state.value, "body": result}
+    except CircuitOpenError as e:
+        return {
+            "ok": False,
+            "breaker": breaker,
+            "open": True,
+            "retry_after": e.retry_after,
+            "fallback": fallback,
+        }
+    except urllib.error.HTTPError as e:  # non-2xx
+        return {
+            "ok": False,
+            "breaker": breaker,
+            "state": b.state.value,
+            "http_status": e.code,
+            "error": e.reason,
+        }
+    except Exception as e:  # noqa: BLE001 - surface everything else as error
+        return {"ok": False, "breaker": breaker, "state": b.state.value, "error": str(e)}
+
+
+@mcp.resource("reliable://breaker/{name}")
+def breaker_resource(name: str) -> dict:
+    """Expose a breaker's live stats as an MCP resource."""
+    b = _get_breaker(name)
+    if b is None:
+        return {"error": f"unknown breaker: {name}"}
+    return b.stats()
+
+
+@mcp.prompt()
+def diagnose_breaker(name: str) -> str:
+    """Build a diagnostic prompt for a named breaker's current health."""
+    b = _get_breaker(name)
+    if b is None:
+        return (
+            f"Breaker '{name}' does not exist yet. "
+            "Create it first with the create_breaker tool."
+        )
+    s = b.stats()
+    rate = s["window_failure_rate"]
+    thr = s["failure_rate_threshold"]
+    return (
+        f"Analyze the circuit breaker '{name}'.\n"
+        f"Current state: {s['state']}.\n"
+        f"Window failure rate: {rate:.0%} (trip threshold {thr:.0%}), "
+        f"window size {s['window_total']}/{s['window']}.\n"
+        f"Cooldown {s['cooldown']}s, probe {s['probe']}.\n"
+        "Is the downstream dependency healthy? Should we tighten or loosen "
+        "the threshold, and what action do you recommend next?"
+    )
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

reliablekit-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: reliablekit
+Version: 0.1.0
+Summary: Reliable LLM/Agent calls: timeout + exponential backoff + sliding-window circuit breaker, with retry-storm protection as a first-class citizen.
+Author: Hou Congcong
+License-Expression: MIT
+Keywords: llm,retry,circuit-breaker,resilience,agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Dynamic: license-file
+
+# reliable
+
+> Python resilience for LLM/Agent calls — timeout + jitter backoff + sliding-window circuit breaker + fallback. Built to stop retry storms.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
+[![Status](https://img.shields.io/badge/status-v0.1--alpha-orange.svg)](https://github.com/GravityWell8/reliable)
+<!-- mcp-name: io.github.gravitywell8/reliable -->
+
+**给谁**：调 LLM/Agent API 的 Python 开发者。
+**解决什么**：超时、限流、偶发 5xx 把 Agent 搞挂；naive retry 引发重试风暴；下游已经瘫了还在持续被打。
+**怎么用**：一个装饰器，把任意同步函数包上超时 + 指数退避 + 滑动窗口熔断 + 降级回调。
+
+## 安装
+
+```bash
+# 从 PyPI 安装（发布名 reliablekit，import 名仍为 reliable）
+pip install reliablekit
+python3 -m reliable.demo   # 需先 pip install -e . 或本地运行 examples/demo.py
+
+# 本地开发：可编辑安装（推荐）
+pip install -e .
+python3 examples/demo.py
+python3 -m unittest discover -s tests
+
+# 不安装，直接用 PYTHONPATH 指向 src（从仓库根目录运行）
+PYTHONPATH=src python3 examples/demo.py
+```
+
+> 发布名是 `reliablekit`（PyPI 不允许 `reliable`，因与已存在的 `reliability` 太像被防 typosquat 规则拦截）；导入时仍用 `import reliable`。
+
+## 快速开始
+
+```python
+from reliable import CircuitBreaker, reliable
+
+breaker = CircuitBreaker(
+    failure_rate=0.5,   # 滑动窗口失败率 >= 50% 即熔断
+    window=20,          # 窗口 20 次调用
+    cooldown=30.0,      # 熔断后冷却 30 秒
+    probe=3,            # 半开后连续成功 3 次才闭合
+)
+
+@reliable(
+    breaker=breaker,
+    timeout=8.0,        # 单次调用超时
+    max_attempts=5,     # 含首次共 5 次尝试
+    base_delay=0.2,     # 退避基数，factor=2 指数增长
+    jitter=0.1,         # ±10% 抖动，防重试同步化
+    on_open=lambda *a, **k: cache_fallback(),  # 熔断期间的降级
+)
+def call_llm(prompt: str) -> str:
+    ...
+```
+
+跑 demo（完整状态机流转，约 4 秒）：
+
+```bash
+python3 examples/demo.py          # 已 pip install -e . 时
+# 或 PYTHONPATH=src python3 examples/demo.py
+```
+
+跑测试（19 个用例，时钟/sleep 全注入，零真实等待）：
+
+```bash
+python3 -m unittest discover -s tests
+# 或 PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+## 状态机
+
+```
+            失败率 >= 阈值
+   CLOSED ────────────────► OPEN
+      ▲                       │
+      │ probe 次连续成功      │ 冷却到期
+      │                       ▼
+      └────────────────── HALF_OPEN
+                 任一失败 ──► 回到 OPEN
+```
+
+- **CLOSED**：正常放行；滑动窗口失败率达到 `failure_rate` → OPEN。
+- **OPEN**：直接拒绝（`CircuitOpenError`）或走 `on_open` 降级，不打下游；冷却到期 → HALF_OPEN。
+- **HALF_OPEN**：放行探针调用；任一失败 → 回 OPEN（重新计时）；`probe` 次连续成功 → CLOSED 并清空窗口。
+
+## API
+
+| 名称 | 说明 |
+|---|---|
+| `reliable(fn=None, *, breaker, timeout, max_attempts, base_delay, factor, jitter, sleep, rng, on_open)` | 装饰器 / 包装函数，支持 `@reliable` 与 `@reliable(...)` |
+| `CircuitBreaker(failure_rate, window, cooldown, probe, clock, rng)` | 滑动窗口熔断器，线程安全，时钟/随机源可注入 |
+| `exp_backoff(attempt, base, factor, jitter, rng)` | 指数退避 + 抖动计算 |
+| `CircuitOpenError(retry_after=...)` | 熔断期调用抛出，携带剩余冷却秒数 |
+
+## 设计取舍（为什么和别的 retry 库不一样）
+
+1. **熔断判定看滑动窗口失败率，不看连续失败次数。** 连续 N 次失败的策略对"偶发抖动 + 低流量"过于迟钝、对"突发风暴"过于敏感；窗口失败率对两者都稳。
+2. **重试带 ±jitter 抖动。** 无抖动的固定退避会让大量客户端同步重试——重试风暴是这套库防御的第一目标，所以抖动默认开启。
+3. **熔断期间走降级回调而不是干等。** `on_open` 让你在下游瘫痪时仍有产出（缓存/简化模型/默认值），错误被转化为降级结果。
+4. **HALF_OPEN 不设并发名额闸门。** 名额在探针调用挂死时会死锁在 half_open——这类"idle 探测假阳性/状态卡死"的坑来自真实故障复盘（下游静默卡死、探针挂死），v0.1 用"连续成功 N 次闭合"的简单语义换正确性。
+
+## 已知限制（v0.1）
+
+- `timeout` 语义是"放弃等待"：底层线程仍在运行，生产上请配合 HTTP 客户端自身超时。
+- 仅支持同步函数；asyncio 原生版在路线图。
+
+## 路线图
+
+- [x] MCP server（已发布，见下）
+- [ ] asyncio 原生版（真取消，不放弃等待）
+- [ ] TypeScript 版（同 API 语义）
+- [ ] 指标导出：每次调用的耗时 / 尝试次数 / 熔断状态变化（可观测性对接）
+- [ ] 预算熔断（token / 成本上限，共享同一熔断内核）
+
+## MCP Server
+
+把库里的容错原语暴露成 LLM Agent 可直接调用的 MCP 工具，适合"Agent 要调很多 LLM/HTTP 下游、又不想自己重写熔断"的场景。
+
+**提供的 surface：**
+- 工具 `create_breaker`：给每个下游依赖（如某 LLM provider）建一个命名熔断器。
+- 工具 `reliable_http_call`：通过命名熔断器发起带超时 / 退避 / 降级的 HTTP 调用；熔断 OPEN 时直接短路返回 `fallback`，不再打下游（重试风暴防护）。
+- 工具 `get_breaker_state` / `compute_backoff`：查状态、预览退避节奏。
+- 资源 `reliable://breaker/{name}`：熔断器的实时 stats。
+- 提示 `diagnose_breaker`：根据状态生成健康诊断 prompt。
+
+**运行（stdio，供 Claude Desktop / Cursor 等 MCP 客户端接入）：**
+
+```bash
+pip install -e ".[mcp]"
+python -m reliable.mcp          # 或安装后直接用 reliable-mcp
+```
+
+**Manifest 文件（仓库根，供注册表提交 / 自托管）：** `mcp.json`、`.mcp.json`，以及可复用的 `smithery.yaml` + `Dockerfile`（供需要容器构建的注册表）。
+
+> 状态保存在 server 进程内的 `_BREAKERS` 字典（单实例、线程安全由 `CircuitBreaker` 保证）。多副本需要共享状态时，把 `_BREAKERS` 换成 Redis/etcd 后端即可——这点与"可插拔存储后端"的设计原则同构。
+
+## License
+
+MIT

reliablekit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+reliable/__init__.py,sha256=w-5b_Mhlew0jyonuALQckEG0wVz07bFVnYL9Tw-Tzo4,427
+reliable/backoff.py,sha256=E3fI6cJZKurn_9uVpiH12Wq-mKxqQlbyWjl5UjbcxhQ,1015
+reliable/breaker.py,sha256=C3nl96epq6pLmLdJ6683xIiJvggXrWYDSDv-b_h3r0Y,5411
+reliable/decorator.py,sha256=UAhgh83pYj9BXnePM-t4ekTFPlW7uwzGnKTyUCkUh-w,3332
+reliable/exceptions.py,sha256=vmhZp8rV-7hskXOd_YD3FvxDqVcLXPRghgHrA-I_aYQ,505
+reliable/mcp.py,sha256=fpSMo738Mucp5mRGxdcwXa8pLIz8DW2To7P5GIDUlYM,7137
+reliablekit-0.1.0.dist-info/licenses/LICENSE,sha256=9UT9WrKfOxvEtEx5dH-QvSQQIoi6JE1qGp7y2p1NqDw,1078
+reliablekit-0.1.0.dist-info/METADATA,sha256=Scl1FlSnyb6kq77Min9Zckwey414tMn47HHLvq3H-Ek,7013
+reliablekit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+reliablekit-0.1.0.dist-info/entry_points.txt,sha256=q0BAyQznb6Vl1tJ1BTPtxcHdt4hGoHml7XQZhL1-v_A,51
+reliablekit-0.1.0.dist-info/top_level.txt,sha256=wzruBZKWPHfo8MId3YiH7KcGcFviVQ0Ea9FiubWoiMI,9
+reliablekit-0.1.0.dist-info/RECORD,,

reliablekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reliablekit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reliable-mcp = reliable.mcp:main

reliablekit-0.1.0.dist-info/licenses/LICENSE

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

reliablekit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+reliable