jev-bisect：用 Jev 的 higher/lower/exactly 二分搜索找数值答案

通过重复的higher、lower或exactly决策，与 Jev 一起寻找数值答案。提供一个问题和边界；该库使用官方 TypeSafe Python SDK 计算猜测值。

安装并运行

需要 Python 3.10 或更高版本。从 PyPI 安装：

pip install jev-bisect
export TYPESAFE_API_KEY="your-typesafe-api-key"

from jev_bisect import bisect

result = bisect(
    "How many slices in a pizza?",
    min=0,
    max=100,
)
print(result.answer)
print(result.turns)

min 和 max 是必需的关键字参数，必须是有限数字，且满足 min < max。省略 last_guess 或传入 None 以从中点开始。要选择第一个猜测值，请提供覆盖值，例如 bisect(question, min=0, max=100, last_guess=25)。

只有在 Jev 选择 exactly 后才会返回结果。结果包含 answer、turns、最终的 state 以及 history。每条历史记录都记录了状态、选择、置信度、概率和模型版本。

配置

from jev_bisect import SearchConfig, bisect

result = bisect(
    "What is pi?",
    min=3,
    max=4,
    config=SearchConfig(precision=0.01, max_turns=10),
)
print(result.answer)  # 3.14 if Jev makes the correct comparisons

省略 config 或传入 None 将使用这些默认值。两项设置都属于 SearchConfig。每次评估的猜测都计为一轮，包括初始中点。这些调用禁用了 SDK 重试。

精度与边界行为

候选值是相对于零的 precision 的倍数：1 搜索整数，0.01 搜索百分位，2.5 搜索诸如 0、2.5 和 5 的值。Jev 被指示在比较前将答案四舍五入到最接近的倍数，中间值向远离零的方向舍入。精度指定的是搜索分辨率，而不是有效数字或误差容限。

在 higher 或 lower 之后，当前猜测值被排除，下一个猜测值是剩余候选值的向下取整中点。对于默认精度下的 min=0, max=100，选择 higher、lower、exactly 会评估 50、75 和 62。向下取整也适用于负数：min=-5, max=0 的第一个猜测值是 -3。

边界会向内对齐到候选网格。使用 min=0.001, max=0.019 和精度 0.01 时，唯一的候选值是 0.01。使用 min=0.1, max=5.9 和精度 1 时，候选值是整数 1 到 5。任何显式的 last_guess 都必须在边界内，并且是 precision 的倍数。

网格上的端点是可以到达的。有效的搜索可能在内部缩小到一个候选值，这仍然需要一个 exactly 决策。选择包含四舍五入后答案的边界；搜索不会扩展它们。大范围或高精度可能需要比配置限制更多的猜测次数，并且 Jev 可能会做出错误的比较。

猜测值在内部使用精确有理数运算和整数候选索引。整数增量（包括 1.0）返回整数；小数增量返回浮点数。不保留末尾零。

异常

模型循环期间的失败包括最后评估的 state 和已完成的 history；MaxTurnsExceededError 还包括 max_turns。在任何评估之前耗尽时，state=None 和空历史。SDK 错误会传播。

from jev_bisect import MaxTurnsExceededError, SearchExhaustedError, bisect

try:
    result = bisect("How many minutes are in three hours?", min=0, max=300)
except (MaxTurnsExceededError, SearchExhaustedError) as error:
    print(error)
    print(error.state, error.history)
else:
    print(result.answer)

自行应用选择

advance 在不调用 API 的情况下执行一步，并返回一个 SearchState。当省略 last_guess 时，选择应用于边界的中点。为下一步提供返回的边界和猜测值，使用相同的配置。如果返回的边界相等，传入 last_guess 以评估剩余的候选值：exactly 返回该状态，而 higher 或 lower 会引发 SearchExhaustedError。没有 last_guess 时，advance 需要 min < max。

from jev_bisect import advance

state = advance("higher", min=0, max=100)
assert state.to_dict() == {"max": 100, "min": 51, "last_guess": 75}

state = advance("lower", min=state.min, max=state.max, last_guess=state.last_guess)
assert state.last_guess == 62

复用客户端或固定模型

from typesafe_sdk import TypeSafeClient
from jev_bisect import bisect

with TypeSafeClient() as client:
    result = bisect(
        "How many centimeters are in three quarters of a meter?",
        min=0,
        max=100,
        client=client,
        model="jev-1.13.0",
    )

默认模型是 jev-latest。提供的客户端保持打开；否则，bisect 会在成功或出错时创建并关闭自己的客户端。

开发

pip install -e '.[dev]'
pytest
ruff check .
python -m build

测试使用确定性响应和模拟 HTTP 传输，无需 API 密钥或网络请求。

准备发布

每次新发布时更新 pyproject.toml 中的 version，然后构建并检查 wheel 和源码分发包：

pip install -e '.[dev,release]'
pytest
ruff check .
python -m build
python -m twine check --strict dist/*

这些命令在本地准备文件。准备好发布时，将 TWINE_USERNAME=__token__ 和 TWINE_PASSWORD 设置为 PyPI API 令牌，然后仅上传该发布版本的文件：

python -m twine upload dist/jev_bisect-0.1.0-py3-none-any.whl dist/jev_bisect-0.1.0.tar.gz

许可证

MIT；参见 LICENSE。