jevkit 0.1.0__py3-none-any.whl

jevkit/__init__.py

@@ -0,0 +1,5 @@
+"""jevkit package — Jev decision model client."""
+from .client import Client, Answer, gate
+
+__all__ = ['Client', 'Answer', 'gate']
+__version__ = '0.1.0'

jevkit/cli.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""jevkit CLI — 命令行入口。
+
+用法:
+    jevkit noul "worth outreach?" --state "lead: ..."
+    jevkit gate 0.63
+    jevkit decide questions.json --state "..."
+"""
+import argparse
+import json
+import sys
+
+from .client import Client, gate
+
+
+def main():
+    ap = argparse.ArgumentParser(prog='jevkit',
+                                 description='Jev decision model CLI (calibrated probabilities, not chat)')
+    sub = ap.add_subparsers(dest='cmd')
+
+    # noul
+    p_noul = sub.add_parser('noul', help='yes/no calibrated probability')
+    p_noul.add_argument('question', help='是/否问题')
+    p_noul.add_argument('--state', default='', help='上下文')
+    p_noul.add_argument('--name', default='q', help='question name')
+    p_noul.add_argument('--true-desc', default='The condition described holds.', help='true criteria')
+    p_noul.add_argument('--false-desc', default='The condition described does not hold.', help='false criteria')
+
+    # gate
+    p_gate = sub.add_parser('gate', help='act/confirm/escalate decision gate')
+    p_gate.add_argument('p', type=float, help='probability 0.0-1.0')
+    p_gate.add_argument('--act', type=float, default=0.7)
+    p_gate.add_argument('--confirm', type=float, default=0.5)
+
+    # decide
+    p_dec = sub.add_parser('decide', help='full decisions call (questions record JSON)')
+    p_dec.add_argument('questions', help='questions record JSON 文件路径')
+    p_dec.add_argument('--state', default='', help='上下文')
+
+    args = ap.parse_args()
+
+    if args.cmd == 'noul':
+        client = Client()
+        criteria = {'true': args.true_desc, 'false': args.false_desc}
+        p = client.noul(args.name, args.question, criteria, state=args.state)
+        action = gate(p)
+        print(f'{p:.2f} → {action}')
+    elif args.cmd == 'gate':
+        print(gate(args.p, act=args.act, confirm=args.confirm))
+    elif args.cmd == 'decide':
+        client = Client()
+        questions = json.loads(open(args.questions).read())
+        r = client.decide(questions, state=args.state)
+        print(json.dumps(r.get('answers', r), ensure_ascii=False, indent=2))
+    else:
+        ap.print_help()
+
+
+if __name__ == '__main__':
+    main()

jevkit/client.py

@@ -0,0 +1,88 @@
+"""jevkit — Python client for the Jev decision model (OpenRouter Decisions API)."""
+import json
+import os
+import urllib.request
+import urllib.error
+from dataclasses import dataclass
+
+API = "https://openrouter.ai/api/alpha/decisions"
+DEFAULT_MODEL = "typesafe/jev-1.13"
+
+
+@dataclass
+class Answer:
+    """单个问题的回答（校准结果）。"""
+    name: str
+    type: str                    # noul / choice / score
+    noul: float = None           # noul 概率
+    choice: str = None           # choice 选中项
+    confidence: float = None     # choice/score 置信
+    probabilities: dict = None   # choice 分布
+
+
+class Client:
+    """Jev Decisions API client。
+
+    不是聊天模型：state + typed questions → 校准概率，零文本生成。
+    """
+
+    def __init__(self, api_key: str = None, model: str = DEFAULT_MODEL):
+        self.api_key = api_key or os.environ.get("OPENROUTER_API_KEY") or os.environ.get("JEV_API_KEY")
+        self.model = model
+
+    def decide(self, questions: dict, state: str = "", timeout: int = 30) -> dict:
+        """单次 decisions 调用。questions 是 record: {name: {type, instructions, ...}}。"""
+        if not self.api_key:
+            raise RuntimeError("OPENROUTER_API_KEY not set.")
+        payload = {"model": self.model, "state": state, "questions": questions}
+        req = urllib.request.Request(
+            API,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return json.loads(r.read())
+        except urllib.error.HTTPError as e:
+            err = e.read().decode("utf-8", errors="ignore")
+            # RuntimeError — except Exception 能接住（fallback 友好）
+            raise RuntimeError(f"Jev HTTP {e.code}: {err[:300]}")
+
+    def noul(self, name: str, instructions: str, criteria: dict,
+             state: str = "", timeout: int = 30) -> float:
+        """是/否校准概率。criteria: {"true": str, "false": str}（描述，不是 options）。"""
+        r = self.decide(
+            {name: {"type": "noul", "instructions": instructions, "criteria": criteria}},
+            state=state, timeout=timeout,
+        )
+        a = r.get("answers", {}).get(name, {})
+        if "noul" in a:
+            return float(a["noul"])
+        raise RuntimeError(f"Jev 响应无 noul: {json.dumps(r)[:200]}")
+
+    def choice(self, name: str, instructions: str, options: list,
+               state: str = "", timeout: int = 30) -> Answer:
+        """挑一。"""
+        r = self.decide(
+            {name: {"type": "choice", "instructions": instructions, "options": options}},
+            state=state, timeout=timeout,
+        )
+        a = r.get("answers", {}).get(name, {})
+        return Answer(name=name, type="choice", choice=a.get("choice"),
+                      confidence=a.get("confidence"), probabilities=a.get("probabilities"))
+
+
+def gate(p: float, act: float = 0.7, confirm: float = 0.5) -> str:
+    """confidence-gated act/confirm/escalate。
+
+    act(>=0.7) → 直接执行；confirm(0.5-0.7) → 待审（borderline 会翻转，不自动执行）；
+    escalate(<0.5) → 升级/跳过。
+    """
+    if p >= act:
+        return "act"
+    if p >= confirm:
+        return "confirm"
+    return "escalate"

jevkit/test_jevkit.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""test_jevkit.py — jevkit 测试（需要 OPENROUTER_API_KEY 才跑真调用）。
+
+用法:
+    python3 -m jevkit.test_jevkit          # 真调用测试
+"""
+import os
+import unittest
+
+
+class TestGate(unittest.TestCase):
+    """gate 决策门（不需要 key）。"""
+
+    def test_act(self):
+        from jevkit import gate
+        self.assertEqual(gate(0.8), 'act')
+        self.assertEqual(gate(0.7), 'act')
+
+    def test_confirm(self):
+        from jevkit import gate
+        self.assertEqual(gate(0.6), 'confirm')
+        self.assertEqual(gate(0.5), 'confirm')
+
+    def test_escalate(self):
+        from jevkit import gate
+        self.assertEqual(gate(0.4), 'escalate')
+        self.assertEqual(gate(0.0), 'escalate')
+
+    def test_borderline_flips(self):
+        """borderline 会翻转 — confirm 档不自动执行（坑 2）。"""
+        from jevkit import gate
+        # 0.5-0.7 区间永远 confirm，不会 act
+        for p in (0.5, 0.55, 0.6, 0.65, 0.69):
+            self.assertEqual(gate(p), 'confirm', f'{p} 应该是 confirm（不自动执行）')
+
+
+class TestClient(unittest.TestCase):
+    """Client（需要 key — 真调用）。"""
+
+    def setUp(self):
+        if not os.environ.get('OPENROUTER_API_KEY'):
+            self.skipTest('OPENROUTER_API_KEY not set')
+
+    def test_noul_real(self):
+        from jevkit import Client
+        client = Client()
+        p = client.noul(
+            'worth_outreach',
+            'Is this lead worth cold outreach?',
+            {'true': 'Explicit budget + concrete need.',
+             'false': 'No budget or self-promotion.'},
+            state='HN post: [Hiring] N8n automation expert, $2k budget, urgent',
+        )
+        self.assertIsInstance(p, float)
+        self.assertGreaterEqual(p, 0.0)
+        self.assertLessEqual(p, 1.0)
+
+    def test_no_key_error(self):
+        """无 key 时 RuntimeError（fallback 友好 — except Exception 能接住）。"""
+        from jevkit import Client
+        saved = os.environ.pop('OPENROUTER_API_KEY', None)
+        try:
+            client = Client(api_key='')
+            with self.assertRaises(RuntimeError):
+                client.noul('q', 'i', {'true': 't', 'false': 'f'}, state='s')
+        finally:
+            if saved:
+                os.environ['OPENROUTER_API_KEY'] = saved
+
+
+if __name__ == '__main__':
+    unittest.main(verbosity=2)

jevkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: jevkit
+Version: 0.1.0
+Summary: First open-source third-party Python client for OpenRouter's Decisions API (Jev, by TypeSafe) - calibrated-probability decision model, not a chat model.
+Author: jevkit contributors
+License: MIT
+Project-URL: Homepage, https://github.com/block/buzz
+Keywords: jev,openrouter,decisions,calibration,agent,noul,gating
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# jevkit — Python client for the Jev decision model
+
+> ⚠️ **Disclaimer**: This is a third-party, unofficial wrapper around OpenRouter's
+> Decisions API — not affiliated with, endorsed by, or maintained by OpenRouter or
+> TypeSafe. The API is in alpha and may change without notice.
+
+The first open-source third-party client for OpenRouter's **Decisions API**
+(Jev, by TypeSafe) — a calibrated-probability decision model, not a chat model.
+
+> Jev answers typed questions with calibrated probabilities — zero text generation.
+> Three primitives: **noul** (yes/no calibrated probability), **choice** (pick one),
+> **score** (scale rating). 70-500ms latency, output tokens free.
+
+## Why
+
+Chat models guess; Jev **calibrates**. If you need routing, classification, or
+gating decisions ("is this worth doing?"), a chat model wrapped in JSON is
+slower, uncalibrated, and costs more. Jev is the ultimate classifier:
+
+- **Calibrated probabilities** — real confidence, not vibes
+- **70-500ms** — System-1 speed for gating decisions
+- **$0.042/M input, output free** — 14 questions ≈ $0.00004
+- **Typed questions** — noul / choice / score, with explicit criteria
+
+## Install
+
+```bash
+pip install jevkit   # (after publish — for now: copy the jevkit/ directory)
+export OPENROUTER_API_KEY=<your key>   # free from openrouter.ai
+```
+
+## Quickstart
+
+```python
+from jevkit import Client, gate
+
+client = Client()  # reads OPENROUTER_API_KEY
+
+# noul — yes/no calibrated probability
+p = client.noul(
+    name="worth_outreach",
+    instructions="Is this lead worth cold outreach?",
+    criteria={
+        "false": "No budget, or the poster is promoting themselves.",
+        "true": "Explicit budget + concrete need, reachable for a pitch.",
+    },
+    state="HN post: [Hiring] N8n automation expert, $2k budget, urgent",
+)
+# → 0.63
+
+# gate — confidence-gated decision (act / confirm / escalate)
+action = gate(p)   # confirm (borderline — flips, don't auto-send)
+
+# choice — pick one from options
+r = client.decide({
+    "category": {
+        "type": "choice",
+        "instructions": "What does the customer need?",
+        "options": ["coding", "design", "content", "infra"],
+    }
+}, state="I need someone to build a checkout flow")
+# → {"choice": "coding", "confidence": 0.8, ...}
+```
+
+
+# score — scale rating
+r = client.decide({
+    "urgency": {
+        "type": "score",
+        "instructions": "How urgent is this?",
+        "legend": {
+            "0": "Can wait",
+            "1": "This week",
+            "2": "Blocking revenue now",
+        },
+    }
+}, state="Payments are failing for customers right now")
+# → {"confidence": 0.99, "legend": {...}, ...}
+
+## CLI
+
+```bash
+jevkit noul "worth outreach?" --state "lead: ..."      # → 0.61
+jevkit gate 0.63                                        # → confirm
+jevkit decide questions.json --state "..."              # → full answers
+```
+
+## Gotchas (learned the hard way)
+
+1. `questions` expects a **record** (`{name: {...}}`), not an array
+2. noul's `criteria` is `{"true": str, "false": str}` — descriptions, not options
+3. The response is `answers.{name}.noul` — not a top-level probability
+4. **Borderline probabilities flip** — never auto-act on 0.5-0.7, gate them
+5. noul(false) + noul(true) don't have to sum to 1
+
+## The gate pattern
+
+```python
+from jevkit import gate
+
+p = client.noul(...)          # System 1: calibrated fast decision
+action = gate(p)              # act(>=0.7) / confirm(0.5-0.7) / escalate(<0.5)
+if action == "act":           # only auto-act on high confidence
+    do_the_thing()
+elif action == "confirm":
+    queue_for_review()        # borderline → human or System 2 (LLM review)
+```
+
+
+Default thresholds: `act >= 0.7`, `confirm >= 0.5` — tuned for the "borderline
+flips" property (never auto-act in 0.5-0.7). Override per use case:
+
+```python
+gate(p, act=0.8, confirm=0.6)   # stricter gate
+```
+
+System 1 (Jev) decides **who/what to act on**; System 2 (a chat model) handles
+**the acting itself** (writing, reasoning). This division keeps costs low and
+decisions calibrated.
+
+## Status
+
+- ✅ Client + CLI + gate pattern (validated with real API calls, R3 read-back)
+- ✅ Error handling: RuntimeError on HTTP errors (fallback-friendly)
+- 🚧 Tests + CI (in progress)
+
+## License
+
+MIT

jevkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+jevkit/__init__.py,sha256=qhxw9OWrOFyZpWseih-F1LGh0nv23LDTZLSgIzrB8ck,155
+jevkit/cli.py,sha256=kg98Z10OaKWA_2CbKEOlKvG4Ek3Z6ESaB4ASgoiYrjg,2208
+jevkit/client.py,sha256=L9FWSTFvA3U1-AzuuRKA8Q0e4PgB1B4PnsGYz1qo4wk,3462
+jevkit/test_jevkit.py,sha256=ZW5OROBPfHOPDrN3aXIAgwYcGooLnLKeevR8Kq32cXU,2387
+jevkit-0.1.0.dist-info/licenses/LICENSE,sha256=Ms15jB19awSNoEyysGVctrN5YhdkvEtcIzjUWCWeHwA,1063
+jevkit-0.1.0.dist-info/METADATA,sha256=zZYnO4zN0aADfhOChf3mVe-cu6h0laGLDn8X_Yk4FxI,5044
+jevkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jevkit-0.1.0.dist-info/entry_points.txt,sha256=GpGtafz5YoqJvVrAMpFvETj1eN7Bw-b6v3ACjymKym4,43
+jevkit-0.1.0.dist-info/top_level.txt,sha256=UvX7-zD0FFAn_vm4mP_8SuXiU_KWPGFgLeJ-ll16_Ac,7
+jevkit-0.1.0.dist-info/RECORD,,

jevkit-0.1.0.dist-info/WHEEL

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

jevkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jevkit = jevkit.cli:main

jevkit-0.1.0.dist-info/licenses/LICENSE

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

jevkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jevkit