jev: give any coding agent (Claude Code, Codex, OpenCode) a calibrated gut check. A zero-dependency CLI + a global skill that wraps TypeSafe's Jev decision model, so an agent can classify, filter,…

A developer released jev, a zero-dependency Python CLI and library that wraps TypeSafe's Jev decision model so coding agents like Claude Code, Codex, and OpenCode can classify, filter, rank, or verify hundreds of items in a single ~250 ms call without loading them into context. The tool returns calibrated probabilities for yes/no, choice, and rubric-score questions at $0.042 per million input tokens, and ships with usage and cost tracking, a one-line installer, and documentation of a measured pitfall the vendor docs omit.

| | /usr/bin/env python3 | | | """jev: calibrated, typed decisions from TypeSafe's Jev model, for agents. | | | | | | Jev is a "System One" model. It does not generate text. You hand it a STATE | | | text or JSON and typed QUESTIONS, and it returns typed answers with | | | calibrated probabilities in ~250 ms for $0.042 per million input tokens. | | | | | | noul yes/no - probability that the answer is yes 0..1 | | | choice pick one - chosen option + probability per option + confidence | | | score rate on rubric- position on your ordered levels + confidence | | | | | | Progressive disclosure: | | | jev short help this | | | jev guide the agent playbook: when to use it, how to ask, how to read | | | jev guide <topic depth on one topic jev guide --list | | | jev examples copy-paste examples for the common jobs | | | jev docs live index of the vendor docs | | | | | | Zero dependencies. Importable as a library: | | | sys.path.insert 0, "/path/to/dir/containing/jev.py" | | | from jev import JevClient, noul, choice, score | | | | | | Auth: --api-key, else $TYPESAFE API KEY, else ~/.config/typesafe/api key 0600 . | | | """ | | | | | | from future import annotations | | | | | | import argparse | | | import concurrent.futures as cf | | | import json | | | import os | | | import random | | | import sys | | | import time | | | import urllib.error | | | import urllib.request | | | from datetime import datetime, timedelta | | | from pathlib import Path | | | | | | VERSION = "1.0.0" | | | API BASE = os.environ.get "TYPESAFE BASE URL", "https://api.typesafe.ai" .rstrip "/" | | | DEFAULT MODEL = os.environ.get "TYPESAFE DEFAULT MODEL", "jev-latest" | | | CONFIG DIR = Path.home / ".config" / "typesafe" | | | KEY FILE = CONFIG DIR / "api key" | | | USAGE FILE = CONFIG DIR / "usage.jsonl" | | | CONFIG FILE = CONFIG DIR / "config.json" | | | PRICE PER MTOK IN = 0.042 USD per million input tokens jev-1.13 list price ; output tokens are free | | | RATE LIMIT RPM = 1200 vendor-published, adjusts without notice | | | RATE LIMIT TPS = 250 000 | | | DOCS = "https://docs.typesafe.ai" | | | MAX CHOICE OPTIONS = 255 | | | MAX SCORE LEVELS = 10 | | | STATE CHAR BUDGET = 120 000 ~30k tokens; the state+longest-question budget is 32k tokens | | | | | | --------------------------------------------------------------------------- errors | | | | | | | | | class JevError Exception : | | | exit code = 4 API error after retries | | | | | | | | | class UsageError JevError : | | | exit code = 2 | | | | | | | | | class AuthError JevError : | | | exit code = 3 | | | | | | | | | class NetworkError JevError : | | | exit code = 5 | | | | | | | | | --------------------------------------------------------------------------- auth | | | | | | | | | def resolve key explicit: str \| None = None - tuple str, str : | | | """Return key, source . Order: explicit, $TYPESAFE API KEY, key file.""" | | | if explicit: | | | return explicit.strip , "--api-key" | | | env = os.environ.get "TYPESAFE API KEY", "" .strip | | | if env: | | | return env, "$TYPESAFE API KEY" | | | if KEY FILE.exists : | | | key = KEY FILE.read text .strip | | | if key: | | | return key, str KEY FILE | | | raise AuthError | | | "no API key. Run jev auth set <key stored 0600 in " | | | f"{KEY FILE} or export TYPESAFE API KEY. Keys: https://console.typesafe.ai/keys" | | | | | | | | | | | | def mask key: str - str: | | | return key :10 + "…" + key -4: if len key 16 else "…" | | | | | | | | | --------------------------------------------------------------------------- question builders | | | | | | | | | def noul instructions, true=None, false=None - dict: | | | """Yes/no question. Returns P yes . Optional criteria say what yes and no mean.""" | | | q = {"type": "noul", "instructions": instructions} | | | if true is not None or false is not None: | | | crit = {} | | | if true is not None: | | | crit "true" = true | | | if false is not None: | | | crit "false" = false | | | q "criteria" = crit | | | return q | | | | | | | | | def choice instructions, options - dict: | | | """Pick one option. options is a dict {name: description\|None} or a list of names.""" | | | if isinstance options, list, tuple : | | | options = {str o : None for o in options} | | | return {"type": "choice", "instructions": instructions, "criteria": dict options } | | | | | | | | | def score instructions, levels - dict: | | | """Rate on an ordered rubric. levels is an ordered list, low to high, 2..10 entries.""" | | | return {"type": "score", "instructions": instructions, "criteria": list levels } | | | | | | | | | def validate questions questions: dict - None: | | | if not isinstance questions, dict or not questions: | | | raise UsageError "questions must be a non-empty map of id - question" | | | for qid, q in questions.items : | | | if not isinstance q, dict or "type" not in q: | | | raise UsageError f"question {qid r}: must be an object with a type " | | | t = q "type" | | | if t not in "noul", "choice", "score" : | | | raise UsageError f"question {qid r}: type must be noul, choice or score, not {t r}" | | | if "instructions" not in q: | | | raise UsageError f"question {qid r}: missing instructions " | | | crit = q.get "criteria" | | | if t == "choice": | | | if not isinstance crit, dict or len crit < 2: | | | raise UsageError f"choice {qid r}: criteria must map at least 2 options to descriptions null allowed " | | | if len crit MAX CHOICE OPTIONS: | | | raise UsageError f"choice {qid r}: at most {MAX CHOICE OPTIONS} options" | | | elif t == "score": | | | if not isinstance crit, list or not 2 <= len crit <= MAX SCORE LEVELS: | | | raise UsageError f"score {qid r}: criteria must be an ordered list of 2..{MAX SCORE LEVELS} level descriptions" | | | elif t == "noul" and crit is not None: | | | if not isinstance crit, dict or not set crit <= {"true", "false"}: | | | raise UsageError f"noul {qid r}: criteria may only have true and false keys" | | | | | | | | | --------------------------------------------------------------------------- client | | | | | | | | | class JevClient: | | | """Thin HTTP client with retries. ask returns the raw API response dict.""" | | | | | | def init self, api key=None, model=None, timeout=30.0, retries=5, base url=None, record=True, label="lib" : | | | self.api key, self.key source = resolve key api key | | | self.model = model or DEFAULT MODEL | | | self.timeout = timeout | | | self.retries = retries | | | self.base url = base url or API BASE .rstrip "/" | | | self.record = record | | | self.label = label | | | self.last ms = 0.0 | | | self.last request id = "" | | | self.last attempts = 0 | | | | | | def request self, method: str, path: str, body=None - dict: | | | data = json.dumps body .encode if body is not None else None | | | headers = { | | | "Authorization": f"Bearer {self.api key}", | | | "Content-Type": "application/json", | | | "User-Agent": f"jev-cli/{VERSION}", | | | } | | | attempt = 0 | | | while True: | | | attempt += 1 | | | req = urllib.request.Request self.base url + path, data=data, method=method, headers=headers | | | t0 = time.time | | | try: | | | with urllib.request.urlopen req, timeout=self.timeout as r: | | | self.last ms = time.time - t0 1000 | | | self.last request id = r.headers.get "x-typesafe-request-id", "" | | | self.last attempts = attempt | | | return json.loads r.read .decode | | | except urllib.error.HTTPError as e: | | | self.last ms = time.time - t0 1000 | | | text = e.read .decode errors="replace" | | | if e.code in 401, 403 : | | | raise AuthError f"HTTP {e.code}: API key rejected {self.key source} . {text :300 }" | | | if e.code in 429, 529 or e.code = 500: | | | if attempt <= self.retries: | | | ra = e.headers.get "retry-after" | | | delay = float ra if ra and ra.replace ".", "", 1 .isdigit else min 8.0, 0.5 2 attempt - 1 | | | time.sleep delay + random.uniform 0, 0.25 | | | continue | | | raise JevError f"HTTP {e.code} after {attempt} attempts: {text :300 }" | | | raise JevError f"HTTP {e.code}: {text :600 }" | | | except urllib.error.URLError, TimeoutError, OSError as e: | | | if attempt <= self.retries: | | | time.sleep min 8.0, 0.5 2 attempt - 1 | | | continue | | | raise NetworkError f"network error after {attempt} attempts: {e}" | | | | | | def models self - dict: | | | return self. request "GET", "/v1/models" | | | | | | def ask self, state, questions: dict, model: str \| None = None - dict: | | | """POST /v1/systemone. state is str\|dict\|list. Returns the raw response.""" | | | if state is None or state == "" or state == {} or state == : | | | raise UsageError "state is empty" | | | validate questions questions | | | body = {"state": state, "model": model or self.model, "questions": questions} | | | try: | | | resp = self. request "POST", "/v1/systemone", body | | | except JevError as e: | | | if self.record: | | | record usage None, self, len questions , err=e | | | raise | | | if self.record: | | | record usage resp, self, len questions | | | return resp | | | | | | | | | def load config - dict: | | | try: | | | return json.loads CONFIG FILE.read text if CONFIG FILE.exists else {} | | | except OSError, json.JSONDecodeError : | | | return {} | | | | | | | | | def save config cfg: dict - None: | | | CONFIG DIR.mkdir parents=True, exist ok=True | | | CONFIG FILE.write text json.dumps cfg, indent=2 + "\n" | | | | | | | | | def price per mtok - float: | | | v = load config .get "price per mtok in" | | | return float v if v else PRICE PER MTOK IN | | | | | | | | | def record usage resp: dict \| None, client: "JevClient", n questions: int, err: Exception \| None = None - None: | | | """Append one row per request success or failure to the local ledger.""" | | | try: | | | CONFIG DIR.mkdir parents=True, exist ok=True | | | row = { | | | "ts": datetime.now .isoformat timespec="seconds" , | | | "cmd": client.label, | | | "agent": os.environ.get "JEV AGENT" or os.environ.get "AGENT ID" or "", | | | "q": n questions, | | | "ms": round client.last ms , | | | } | | | if resp is not None: | | | u = resp.get "usage" or {} | | | row.update {"model": resp.get "model" , "in": u.get "input tokens", 0 , "out": u.get "output tokens", 0 } | | | if client.last request id: | | | row "rid" = client.last request id | | | if client.last attempts 1: | | | row "attempts" = client.last attempts | | | else: | | | msg = str err | | | code = msg.split ":", 1 0 .replace "HTTP ", "" .strip if msg.startswith "HTTP" else type err . name | | | row.update {"in": 0, "out": 0, "err": code} | | | with USAGE FILE.open "a" as f: | | | f.write json.dumps row + "\n" | | | except OSError: | | | pass | | | | | | | | | def cost usd input tokens: int - float: | | | return input tokens / 1 000 000 price per mtok | | | | | | | | | --------------------------------------------------------------------------- input parsing | | | | | | | | | def parse value v: str : | | | """ @path reads a file .json parsed . JSON-looking text is parsed. Else string.""" | | | if v.startswith "@" : | | | p = Path v 1: .expanduser | | | if not p.exists : | | | raise UsageError f"file not found: {p}" | | | txt = p.read text | | | if p.suffix.lower in ".json", ".jsonl" : | | | try: | | | return json.loads txt if p.suffix.lower == ".json" else json.loads line for line in txt.splitlines if line.strip | | | except json.JSONDecodeError as e: | | | raise UsageError f"{p}: invalid JSON: {e}" | | | return txt | | | s = v.strip | | | if s and s 0 in "{ " or s in "true", "false", "null" : | | | try: | | | return json.loads s | | | except json.JSONDecodeError: | | | pass | | | return v | | | | | | | | | def build state args - object: | | | srcs = n for n in "state", "state file", "state json" if getattr args, n, None | | | if len srcs 1: | | | raise UsageError "give the state one way: --state, --state-file, or --state-json --field may be added to any of them, and becomes text " | | | state = None | | | if getattr args, "state", None : | | | state = sys.stdin.read if args.state == "-" else parse value args.state if args.state.startswith "@" else args.state | | | elif getattr args, "state file", None : | | | state = parse value "@" + args.state file | | | elif getattr args, "state json", None : | | | try: | | | state = json.loads args.state json | | | except json.JSONDecodeError as e: | | | raise UsageError f"--state-json: invalid JSON: {e}" | | | if getattr args, "field", None : | | | obj = {} | | | if state is not None: | | | obj "text" = state | | | for kv in args.field: | | | if "=" not in kv: | | | raise UsageError f"--field expects key=value, got {kv r}" | | | k, v = kv.split "=", 1 | | | obj k.strip = parse value v | | | state = obj | | | if state is None: | | | state = implicit stdin | | | if not state: | | | raise UsageError "no state. Use --state TEXT, --state-file PATH, --state-json JSON, --field k=v, or pipe text on stdin" | | | n = len state if isinstance state, str else len json.dumps state | | | if n STATE CHAR BUDGET: | | | eprint f"jev: warning: state is {n:,} chars ~{n // 4:,} tokens ; the per-request budget is ~32k tokens for state + longest question. Filter first, or use jev batch / jev rank which chunk." | | | return state | | | | | | | | | def implicit stdin timeout: float = 1.5 - str \| None: | | | """Read stdin only when it is not a terminal AND has data ready. A harness that leaves | | | stdin open with no writer would otherwise block forever; --state - forces a blocking read.""" | | | if sys.stdin is None or sys.stdin.isatty : | | | return None | | | try: | | | import select | | | ready, , = select.select sys.stdin , , , timeout | | | if not ready: | | | return None | | | except OSError, ValueError : | | | pass | | | return sys.stdin.read | | | | | | | | | def parse kv options items: list str - dict: | | | """ 'billing=Payments', 'sales' - {'billing': 'Payments', 'sales': None}""" | | | out = {} | | | for it in items: | | | if "=" in it: | | | k, v = it.split "=", 1 | | | out k.strip = parse value v if v = "" else None | | | else: | | | out it.strip = None | | | return out | | | | | | | | | class QAction argparse.Action : | | | """Collects --noul/--choice/--score in declaration order.""" | | | | | | def call self, parser, ns, values, option string=None : | | | lst = getattr ns, "qlist", None or | | | lst.append self.dest, list values | | | ns.qlist = lst | | | | | | | | | def questions from args args - dict: | | | qs: dict = {} | | | if getattr args, "questions file", None : | | | v = parse value "@" + args.questions file | | | if not isinstance v, dict : | | | raise UsageError "--questions-file must contain a JSON object of id - question" | | | qs.update v | | | if getattr args, "questions json", None : | | | try: | | | qs.update json.loads args.questions json | | | except json.JSONDecodeError as e: | | | raise UsageError f"--questions-json: invalid JSON: {e}" | | | for kind, vals in getattr args, "qlist", None or : | | | if len vals < 2: | | | raise UsageError f"--{kind} needs ID INSTRUCTIONS ... " | | | qid, instr, rest = vals 0 , parse value vals 1 , vals 2: | | | if kind == "noul": | | | kv = parse kv options rest | | | extra = set kv - {"true", "false"} | | | if extra: | | | raise UsageError f"--noul {qid}: after the instructions only true=... and false=... are allowed, got {sorted extra }" | | | qs qid = noul instr, kv.get "true" , kv.get "false" | | | elif kind == "choice": | | | if len rest < 2: | | | raise UsageError f"--choice {qid}: give at least 2 options as NAME or NAME=description" | | | qs qid = choice instr, parse kv options rest | | | elif kind == "score": | | | if len rest < 2: | | | raise UsageError f"--score {qid}: give 2..{MAX SCORE LEVELS} level descriptions, low to high" | | | qs qid = score instr, parse value r for r in rest | | | if not qs: | | | raise UsageError "no questions. Use --noul/--choice/--score, --questions-file, or --questions-json see jev ask --help " | | | return qs | | | | | | | | | --------------------------------------------------------------------------- rendering | | | | | | | | | def eprint a, k : | | | print a, file=sys.stderr, k | | | | | | | | | def describe level desc - str: | | | if isinstance desc, dict : | | | for k in "what", "level", "description", "name" : | | | if k in desc: | | | return str desc k | | | return json.dumps desc :80 | | | return str desc | | | | | | | | | def render answer qid: str, a: dict - str: | | | t = a.get "type" | | | if t == "noul": | | | p = a "noul" | | | return f"{qid:<24} noul {p:.2f} {'yes' if p = 0.5 else 'no'}" | | | if t == "choice": | | | probs = a.get "probabilities", {} | | | best = a "choice" | | | others = ", ".join f"{k} {v:.2f}" for k, v in sorted probs.items , key=lambda kv: -kv 1 if k = best | | | return f"{qid:<24} choice {best} p={probs.get best, 0 :.2f} conf={a.get 'confidence', 0 :.2f} {others} " | | | if t == "score": | | | legend = a.get "legend", {} | | | top = max len legend - 1, 1 | | | s = a "score" | | | nearest = describe level legend.get str int round s , "" | | | return f"{qid:<24} score {s:.2f}/{top} conf={a.get 'confidence', 0 :.2f} ≈ {nearest}" | | | return f"{qid:<24} {t} {json.dumps a }" | | | | | | | | | def render response resp: dict, ms: float, verbose: bool - str: | | | lines = render answer qid, a for qid, a in resp.get "answers", {} .items | | | u = resp.get "usage", {} | | | lines.append f"· {resp.get 'model' } · {u.get 'input tokens', 0 } in / {u.get 'output tokens', 0 } out tokens · {ms:.0f} ms · ${cost usd u.get 'input tokens', 0 :.6f}" | | | return "\n".join lines | | | | | | | | | def emit args, resp: dict, ms: float, extra: dict \| None = None - None: | | | if args.json: | | | out = dict resp | | | if extra: | | | out.update extra | | | print json.dumps out, indent=None if args.compact else 2 | | | else: | | | print render response resp, ms, args.verbose | | | | | | | | | --------------------------------------------------------------------------- commands | | | | | | | | | def cmd ask args - int: | | | state = build state args | | | qs = questions from args args | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="ask" | | | resp = c.ask state, qs | | | emit args, resp, c.last ms | | | return 0 | | | | | | | | | def cmd yes args - int: | | | state = build state args | | | q = noul parse value args.instructions , args.true, args.false | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="yes" | | | resp = c.ask state, {"q": q} | | | p = resp "answers" "q" "noul" | | | lo, hi = args.band if args.band else args.threshold, args.threshold | | | if p = hi: | | | verdict, code = "yes", 0 | | | elif p < lo: | | | verdict, code = "no", 1 | | | else: | | | verdict, code = "uncertain", 1 | | | if args.json: | | | print json.dumps {"noul": p, "verdict": verdict, "threshold": args.threshold, "band": args.band, "model": resp "model" , "usage": resp "usage" } | | | else: | | | print f"{p:.3f} {verdict}" | | | return code | | | | | | | | | def cmd pick args - int: | | | state = build state args | | | opts = parse kv options args.options | | | if len opts < 2: | | | raise UsageError "pick needs at least 2 options NAME or NAME=description " | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="pick" | | | resp = c.ask state, {"q": choice parse value args.instructions , opts } | | | a = resp "answers" "q" | | | conf = a.get "confidence", 0.0 | | | ok = conf = args.min confidence | | | if args.json: | | | print json.dumps {"choice": a "choice" , "confidence": conf, "probabilities": a "probabilities" , "verdict": "ok" if ok else "uncertain", "min confidence": args.min confidence, "model": resp "model" , "usage": resp "usage" } | | | else: | | | ranked = ", ".join f"{k} {v:.2f}" for k, v in sorted a "probabilities" .items , key=lambda kv: -kv 1 | | | if ok: | | | print f"{a 'choice' } conf={conf:.2f} {ranked} " | | | else: | | | print f"uncertain best={a 'choice' } conf={conf:.2f} < {args.min confidence} {ranked} " | | | return 0 if ok else 1 | | | | | | | | | def cmd rate args - int: | | | state = build state args | | | levels = parse value lv for lv in args.levels | | | if not 2 <= len levels <= MAX SCORE LEVELS: | | | raise UsageError f"rate needs 2..{MAX SCORE LEVELS} level descriptions, low to high" | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="rate" | | | resp = c.ask state, {"q": score parse value args.instructions , levels } | | | a = resp "answers" "q" | | | conf = a.get "confidence", 0.0 | | | top = len levels - 1 | | | ok = conf = args.min confidence | | | nearest = int round a "score" | | | if args.json: | | | print json.dumps {"score": a "score" , "top": top, "normalized": a "score" / top, "nearest level": nearest, "nearest": describe level levels nearest , "confidence": conf, "probabilities": a "probabilities" , "verdict": "ok" if ok else "uncertain", "model": resp "model" , "usage": resp "usage" } | | | else: | | | flag = "" if ok else f" uncertain conf < {args.min confidence} " | | | print f"{a 'score' :.2f}/{top} conf={conf:.2f} ≈ {describe level levels nearest }{flag}" | | | return 0 if ok else 1 | | | | | | | | | def read candidates args - list: | | | if args.candidates file: | | | v = parse value "@" + args.candidates file | | | if isinstance v, list : | | | return v | | | return line for line in str v .splitlines if line.strip | | | if args.candidates: | | | return list args.candidates | | | txt = implicit stdin | | | if txt: | | | return line.rstrip "\n" for line in txt.splitlines if line.strip | | | raise UsageError "no candidates: give them as arguments, --candidates-file lines, or a JSON array , or on stdin" | | | | | | | | | def chunk candidates cands: list, max chars: int, max n: int - list list tuple int, object : | | | chunks, cur, size = , , 0 | | | for i, c in enumerate cands : | | | n = len c if isinstance c, str else len json.dumps c | | | if cur and size + n max chars or len cur = max n : | | | chunks.append cur | | | cur, size = , 0 | | | cur.append i, c | | | size += n | | | if cur: | | | chunks.append cur | | | return chunks | | | | | | | | | def cmd rank args - int: | | | cands = read candidates args | | | if not cands: | | | raise UsageError "no candidates" | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="rank" | | | levels = parse value lv for lv in args.levels if args.levels else None | | | question text = args.instructions or "How well does candidate match query ?" if levels else "Is candidate relevant to query ?" | | | if "{i}" in question text or "candidates " in question text: | | | eprint "jev: warning: refer to the item as candidate ; each question carries its own item. Positional candidates i references mis-locate past ~20 items measured 27% wrong at 150 ." | | | results: list dict = | | | usage in = usage out = 0 | | | t0 = time.time | | | chunks = chunk candidates cands, args.chunk chars, args.chunk size | | | | | | def run chunk : | | | The item lives INSIDE its question, not at an index in the state: Jev mis-locates | | | candidates i in long arrays measured 2026-09-18: 86/320 wrong at 150 per request, | | | 29/320 at 25 while an embedded or keyed item scored 0/320 wrong at 320 per request. | | | state = {"query": parse value args.query } | | | if args.context: | | | state "context" = parse value args.context | | | qs = {} | | | for j, i, cand in enumerate chunk : | | | instr = {"question": question text, "candidate": cand} | | | qs f"c{j}" = score instr, levels if levels else noul instr | | | resp = c.ask state, qs | | | out = | | | for j, i, cand in enumerate chunk : | | | a = resp "answers" f"c{j}" | | | if levels: | | | top = len levels - 1 | | | out.append {"i": i, "p": a "score" / top, "score": a "score" , "confidence": a.get "confidence" , "candidate": cand} | | | else: | | | out.append {"i": i, "p": a "noul" , "candidate": cand} | | | return out, resp.get "usage", {} | | | | | | with cf.ThreadPoolExecutor max workers=args.concurrency as ex: | | | for out, u in ex.map run, chunks : | | | results.extend out | | | usage in += u.get "input tokens", 0 | | | usage out += u.get "output tokens", 0 | | | results.sort key=lambda r: -r "p" | | | if args.min is not None: | | | results = r for r in results if r "p" = args.min | | | if args.top: | | | results = results : args.top | | | ms = time.time - t0 1000 | | | if args.json: | | | print json.dumps {"results": results, "n": len cands , "requests": len chunks , "usage": {"input tokens": usage in, "output tokens": usage out}, "ms": round ms }, indent=None if args.compact else 2 | | | else: | | | for r in results: | | | cand = r "candidate" if isinstance r "candidate" , str else json.dumps r "candidate" | | | cand = cand.replace "\n", " " | | | if len cand args.width: | | | cand = cand : args.width - 1 + "…" | | | print f"{r 'p' :.3f} {r 'i' :<4} {cand}" | | | eprint f"· {len cands } candidates · {len chunks } request s · {usage in} in tokens · {ms:.0f} ms · ${cost usd usage in :.5f}" | | | return 0 | | | | | | | | | def cmd batch args - int: | | | qs = questions from args args | | | if args.input == "-": | | | raw = sys.stdin.read | | | else: | | | p = Path args.input .expanduser | | | if not p.exists : | | | raise UsageError f"input not found: {p}" | | | raw = p.read text | | | items = | | | for n, line in enumerate raw.splitlines : | | | if not line.strip : | | | continue | | | if args.text lines: | | | items.append n, None, line | | | continue | | | try: | | | obj = json.loads line | | | except json.JSONDecodeError: | | | items.append n, None, line | | | continue | | | if isinstance obj, dict and args.state key: | | | if args.state key not in obj: | | | raise UsageError f"line {n}: no key {args.state key r}" | | | items.append n, obj.get args.id key , obj args.state key | | | else: | | | items.append n, obj.get args.id key if isinstance obj, dict else None, obj | | | if not items: | | | raise UsageError "no input rows" | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="batch" | | | out f = open args.out, "w" if args.out else sys.stdout | | | usage in = 0 | | | t0 = time.time | | | errors = 0 | | | | | | def run item : | | | n, ident, state = item | | | try: | | | resp = c.ask state, qs | | | row = {"line": n, "answers": resp "answers" , "usage": resp "usage" } | | | except JevError as e: | | | row = {"line": n, "error": str e } | | | if ident is not None: | | | row "id" = ident | | | if args.echo: | | | row "state" = state | | | return row | | | | | | try: | | | with cf.ThreadPoolExecutor max workers=args.concurrency as ex: | | | for row in ex.map run, items : | | | if "error" in row: | | | errors += 1 | | | else: | | | usage in += row "usage" .get "input tokens", 0 | | | out f.write json.dumps row + "\n" | | | out f.flush | | | finally: | | | if args.out: | | | out f.close | | | ms = time.time - t0 1000 | | | eprint f"· {len items } rows · {errors} errors · {usage in} in tokens · {ms:.0f} ms · ${cost usd usage in :.5f}" + f" · wrote {args.out}" if args.out else "" | | | return 0 if errors == 0 else 4 | | | | | | | | | def cmd models args - int: | | | c = JevClient args.api key, args.model, timeout=args.timeout, record=False | | | resp = c.models | | | if args.json: | | | print json.dumps resp, indent=2 | | | else: | | | for m in resp.get "models", : | | | print f"{m.get 'name' :<14} {str m.get 'release date', '' :10 } {m.get 'description', '' }" | | | return 0 | | | | | | | | | def cmd auth args - int: | | | if args.action == "set": | | | key = args.key or sys.stdin.readline .strip if not sys.stdin.isatty else "" | | | if not key: | | | raise UsageError "jev auth set <key or pipe the key on stdin " | | | CONFIG DIR.mkdir parents=True, exist ok=True | | | old = os.umask 0o077 | | | try: | | | KEY FILE.write text key.strip + "\n" | | | finally: | | | os.umask old | | | os.chmod KEY FILE, 0o600 | | | print f"stored {mask key } in {KEY FILE} 0600 " | | | return 0 | | | if args.action == "clear": | | | if KEY FILE.exists : | | | KEY FILE.unlink | | | print f"removed {KEY FILE}" | | | else: | | | print "no key file" | | | return 0 | | | try: | | | key, src = resolve key args.api key | | | except AuthError as e: | | | print f"no key: {e}" | | | return 3 | | | print f"key {mask key } from {src}" | | | if src == str KEY FILE : | | | mode = oct KEY FILE.stat .st mode & 0o777 | | | print f"file mode {mode}" + "" if mode == "0o600" else " <- should be 0600" | | | return 0 | | | | | | | | | def cmd doctor args - int: | | | ok = True | | | | | | def step name, fn : | | | nonlocal ok | | | try: | | | msg = fn | | | print f"ok {name}: {msg}" | | | except Exception as e: noqa: BLE001 | | | ok = False | | | print f"FAIL {name}: {e}" | | | | | | step "python", lambda: sys.version.split 0 | | | def key : | | | k, src = resolve key args.api key | | | return f"{mask k } from {src}" | | | | | | step "key", key | | | c = None | | | | | | def models : | | | nonlocal c | | | c = JevClient args.api key, args.model, timeout=args.timeout, record=False | | | r = c.models | | | return f"{ m 'name' for m in r.get 'models', } in {c.last ms:.0f} ms" | | | | | | step "GET /v1/models", models | | | | | | def roundtrip : | | | r = c.ask "The export button crashes the settings page in Safari but works in Chrome.", | | | {"is bug": noul "Does this describe a software bug?" , | | | "severity": score "How severe?", "Cosmetic", "Degraded, workaround exists", "Blocking" } | | | a = r "answers" | | | return f"model={r 'model' } is bug={a 'is bug' 'noul' :.2f} severity={a 'severity' 'score' :.2f} in {c.last ms:.0f} ms, {r 'usage' 'input tokens' } tokens" | | | | | | if c is not None: | | | step "POST /v1/systemone", roundtrip | | | step "usage ledger", lambda: f"{USAGE FILE} {USAGE FILE.stat .st size if USAGE FILE.exists else 0} bytes " | | | step "skill", lambda: ", ".join str p for p in Path.home / ".claude/skills/jev", Path.home / ".codex/skills/jev", Path.home / ".config/opencode/skills/jev" if p.exists or "not linked see jev guide install " | | | print "healthy" if ok else "problems found" | | | return 0 if ok else 4 | | | | | | | | | def load ledger - list dict : | | | if not USAGE FILE.exists : | | | return | | | rows = | | | for line in USAGE FILE.read text .splitlines : | | | try: | | | r = json.loads line | | | r " t" = datetime.fromisoformat r "ts" | | | rows.append r | | | except json.JSONDecodeError, KeyError, ValueError : | | | continue | | | return rows | | | | | | | | | def agent names ids: set str - dict str, str : | | | """Agents are attributed by $JEV AGENT or $AGENT ID . Names are whatever you export.""" | | | return {i: i if i else " no agent " for i in ids} | | | | | | | | | def agg sel: list dict - dict: | | | ok = r for r in sel if "err" not in r | | | tin = sum r.get "in", 0 for r in ok | | | ms = sorted r "ms" for r in ok if r.get "ms" | | | pct = lambda p: ms min len ms - 1, int len ms p if ms else 0 noqa: E731 | | | return { | | | "requests": len sel , "errors": len sel - len ok , "questions": sum r.get "q", 0 for r in ok , | | | "input tokens": tin, "output tokens": sum r.get "out", 0 for r in ok , "usd": round cost usd tin , 6 , | | | "avg ms": round sum ms / len ms if ms else 0, "p50 ms": pct 0.5 , "p95 ms": pct 0.95 , "max ms": ms -1 if ms else 0, | | | } | | | | | | | | | def peaks sel: list dict - dict: | | | per min: dict str, int = {} | | | per sec: dict str, int = {} | | | for r in sel: | | | per min r "ts" :16 = per min.get r "ts" :16 , 0 + 1 | | | per sec r "ts" = per sec.get r "ts" , 0 + r.get "in", 0 | | | rpm = max per min.values if per min else 0 | | | tps = max per sec.values if per sec else 0 | | | return {"peak rpm": rpm, "peak rpm at": max per min, key=per min.get if per min else None, "rpm limit": RATE LIMIT RPM, | | | "peak tps": tps, "peak tps at": max per sec, key=per sec.get if per sec else None, "tps limit": RATE LIMIT TPS} | | | | | | | | | def cmd usage args - int: | | | rows = load ledger | | | if args.label: | | | rows = r for r in rows if r.get "cmd" == args.label | | | if args.agent: | | | rows = r for r in rows if args.agent in r.get "agent" or "" | | | if args.since: | | | try: | | | since = datetime.fromisoformat args.since | | | except ValueError: | | | raise UsageError "--since expects YYYY-MM-DD or an ISO timestamp" | | | rows = r for r in rows if r " t" = since | | | if not rows: | | | print "no usage recorded" + " for that filter" if args.label or args.agent or args.since else " yet" | | | return 0 | | | now = datetime.now | | | day0 = now.replace hour=0, minute=0, second=0, microsecond=0 | | | cfg = load config | | | | | | if args.tail: | | | sel = rows -args.tail: | | | if args.json: | | | print json.dumps {k: v for k, v in r.items if k = " t"} for r in sel , indent=2 | | | return 0 | | | names = agent names {r.get "agent", "" for r in sel} | | | print f"{'ts':<19} {'cmd':<12} {'agent':<22} {'q': 4} {'in': 7} {'ms': 5} rid/err" | | | for r in sel: | | | tail = r.get "err" and f"ERR {r 'err' }" or r.get "rid", "" | | | print f"{r 'ts' :<19} {r.get 'cmd', '?' :12 :<12} {names r.get 'agent', '' :22 :<22} {r.get 'q', 0 : 4} {r.get 'in', 0 : 7} {r.get 'ms', 0 : 5} {tail}" | | | return 0 | | | | | | if args.by: | | | key = args.by | | | if key == "day": | | | groups = {} | | | for r in rows: | | | if r " t" = day0 - timedelta days=args.days - 1 : | | | groups.setdefault r "ts" :10 , .append r | | | elif key == "hour": | | | groups = {} | | | for r in rows: | | | if r " t" = now - timedelta hours=24 : | | | groups.setdefault r "ts" :13 + ":00", .append r | | | elif key in "cmd", "model" : | | | groups = {} | | | for r in rows: | | | groups.setdefault str r.get key or "?" , .append r | | | elif key == "agent": | | | names = agent names {r.get "agent", "" for r in rows} | | | groups = {} | | | for r in rows: | | | groups.setdefault names r.get "agent", "" , .append r | | | else: | | | raise UsageError "--by expects day, hour, cmd, agent or model" | | | table = {k: agg v for k, v in groups.items } | | | order = sorted table if key in "day", "hour" else sorted table, key=lambda k: -table k "input tokens" | | | if args.json: | | | print json.dumps {k: table k for k in order}, indent=2 | | | return 0 | | | print f"{key:<24} {'requests': 8} {'errors': 6} {'questions': 9} {'in tokens': 10} {'usd': 9} {'avg ms': 6}" | | | for k in order: | | | a = table k | | | print f"{k :24 :<24} {a 'requests' : 8} {a 'errors' : 6} {a 'questions' : 9} {a 'input tokens' : 10,} {a 'usd' : 9.4f} {a 'avg ms' : 6}" | | | return 0 | | | | | | windows = { | | | "today": day0, "yesterday": day0 - timedelta days=1 , day0 , "7d": now - timedelta days=7 , | | | "30d": now - timedelta days=30 , "month": day0.replace day=1 , "all": datetime.min, | | | } | | | summary = {} | | | for name, w in windows.items : | | | lo, hi = w if isinstance w, tuple else w, None | | | sel = r for r in rows if r " t" = lo and hi is None or r " t" < hi | | | summary name = agg sel | | | last7 = r for r in rows if r " t" = now - timedelta days=7 | | | last30 = r for r in rows if r " t" = now - timedelta days=30 | | | first ts = rows 0 " t" | | | days observed = max 1e-9, now - first ts .total seconds / 86400 | | | rate7 = summary "7d" "usd" / min 7, days observed | | | rate30 = summary "30d" "usd" / min 30, days observed | | | forecast = {"usd per day 7d": round rate7, 6 , "usd per day 30d": round rate30, 6 , | | | "usd per month at 7d rate": round rate7 30, 4 , "usd per month at 30d rate": round rate30 30, 4 , | | | "days observed": round days observed, 2 } | | | credits = None | | | if cfg.get "credits usd" is not None: | | | as of = datetime.fromisoformat cfg.get "credits as of" or first ts.isoformat | | | spent = cost usd sum r.get "in", 0 for r in rows if r " t" = as of | | | remaining = float cfg "credits usd" - spent | | | credits = {"credits usd": float cfg "credits usd" , "as of": as of.isoformat timespec="seconds" , "spent since": round spent, 6 , | | | "remaining usd": round remaining, 6 , "remaining mtok": round remaining / price per mtok , 3 if remaining 0 else 0.0, | | | "days left at 7d rate": round remaining / rate7, 1 if rate7 0 and remaining 0 else None} | | | budget = None | | | if cfg.get "budget usd month" : | | | b = float cfg "budget usd month" | | | mtd = summary "month" "usd" | | | dim = day0.replace day=28 + timedelta days=4 .replace day=1 - timedelta days=1 .day | | | budget = {"budget usd month": b, "mtd usd": mtd, "pct used": round 100 mtd / b, 1 if b else None, | | | "projected month end usd": round mtd + rate7 dim - now.day , 4 , "days left in month": dim - now.day} | | | errors = {} | | | for r in last7: | | | if "err" in r: | | | errors r "err" = errors.get r "err" , 0 + 1 | | | by cmd = {} | | | for r in rows: | | | by cmd.setdefault r.get "cmd" or "?", .append r | | | names = agent names {r.get "agent", "" for r in rows} | | | by agent = {} | | | for r in rows: | | | by agent.setdefault names r.get "agent", "" , .append r | | | by model = {} | | | for r in rows: | | | if r.get "model" : | | | by model.setdefault r "model" , .append r | | | peaks = peaks last30 | | | out = { | | | "price per mtok in": price per mtok , "ledger": str USAGE FILE , "rows": len rows , "first": rows 0 "ts" , "last": rows -1 "ts" , | | | "windows": summary, "by cmd": {k: agg v for k, v in by cmd.items }, "by agent": {k: agg v for k, v in by agent.items }, | | | "by model": {k: agg v for k, v in by model.items }, "errors 7d": errors, "throughput 30d": peaks, | | | "forecast": forecast, "credits": credits, "budget": budget, | | | } | | | if args.json: | | | print json.dumps out, indent=2 | | | return 0 | | | | | | print f"jev usage · ${price per mtok }/Mtok in, output free · {len rows } requests since {rows 0 'ts' :16 } · {USAGE FILE}" | | | print f"\n{'window':<10} {'requests': 8} {'errors': 6} {'questions': 9} {'in tokens': 10} {'out': 7} {'usd': 9} {'avg ms': 6}" | | | for name, a in summary.items : | | | print f"{name:<10} {a 'requests' : 8} {a 'errors' : 6} {a 'questions' : 9} {a 'input tokens' : 10,} {a 'output tokens' : 7,} {a 'usd' : 9.4f} {a 'avg ms' : 6}" | | | a7 = summary "7d" | | | print f"\nlatency 7d p50 {a7 'p50 ms' } ms · p95 {a7 'p95 ms' } ms · max {a7 'max ms' } ms · avg questions/request {a7 'questions' / max 1, a7 'requests' - a7 'errors' :.1f} · avg tokens/request {a7 'input tokens' / max 1, a7 'requests' - a7 'errors' :,.0f}" | | | print f"throughput peak {peaks 'peak rpm' } req/min {100 peaks 'peak rpm' / RATE LIMIT RPM:.1f}% of {RATE LIMIT RPM} at {peaks 'peak rpm at' } · peak {peaks 'peak tps' :,} tok/s {100 peaks 'peak tps' / RATE LIMIT TPS:.2f}% of {RATE LIMIT TPS:,} · 30d window" | | | print "errors 7d " + ", ".join f"{k} x{v}" for k, v in sorted errors.items , key=lambda kv: -kv 1 if errors else "none" | | | print f"forecast ${forecast 'usd per day 7d' :.4f}/day at the 7d rate - ${forecast 'usd per month at 7d rate' :.2f}/month · ${forecast 'usd per month at 30d rate' :.2f}/month at the 30d rate" | | | if credits: | | | dl = f" · ~{credits 'days left at 7d rate' } days left at the 7d rate" if credits "days left at 7d rate" else "" | | | print f"credits ${credits 'remaining usd' :.4f} remaining of ${credits 'credits usd' :.2f} set {credits 'as of' :16 } {credits 'remaining mtok' :.1f} Mtok {dl}" | | | else: | | | print "credits not configured. The API exposes no balance; read it at https://console.typesafe.ai and run jev config set credits <usd " | | | if budget: | | | print f"budget ${budget 'mtd usd' :.4f} of ${budget 'budget usd month' :.2f} this month {budget 'pct used' }% · projected month end ${budget 'projected month end usd' :.2f}" | | | print f"\n{'by command':<24} {'requests': 8} {'questions': 9} {'in tokens': 10} {'usd': 9}" | | | for k, v in sorted by cmd.items , key=lambda kv: -sum r.get 'in', 0 for r in kv 1 :12 : | | | a = agg v | | | print f"{k :24 :<24} {a 'requests' : 8} {a 'questions' : 9} {a 'input tokens' : 10,} {a 'usd' : 9.4f}" | | | print f"\n{'by agent':<24} {'requests': 8} {'questions': 9} {'in tokens': 10} {'usd': 9}" | | | for k, v in sorted by agent.items , key=lambda kv: -sum r.get 'in', 0 for r in kv 1 :12 : | | | a = agg v | | | print f"{k :24 :<24} {a 'requests' : 8} {a 'questions' : 9} {a 'input tokens' : 10,} {a 'usd' : 9.4f}" | | | if len by model 1: | | | print "\nby model: " + ", ".join f"{k} {len v }" for k, v in by model.items | | | print "\nmore: --by day\|hour\|cmd\|agent\|model · --tail N · --since DATE · --label X · --agent X · --json · jev config · jev cost" | | | return 0 | | | | | | | | | CONFIG KEYS = { | | | "credits": "credits usd", float, "prepaid balance in USD, read off https://console.typesafe.ai; jev usage counts down from it" , | | | "credits as of": "credits as of", str, "ISO timestamp the balance was read default: when you set it " , | | | "budget": "budget usd month", float, "monthly spend budget in USD; jev usage shows % used and a month-end projection" , | | | "price": "price per mtok in", float, f"USD per million input tokens if the vendor changes it default {PRICE PER MTOK IN} " , | | | } | | | | | | | | | def cmd config args - int: | | | cfg = load config | | | if args.action == "show" or not args.action: | | | if args.json: | | | print json.dumps cfg, indent=2 | | | return 0 | | | print f"{CONFIG FILE}" + "" if CONFIG FILE.exists else " not created yet " | | | for k, real, , desc in CONFIG KEYS.items : | | | print f" {k:<14} {str cfg.get real, '-' :<24} {desc}" | | | return 0 | | | if args.action == "unset": | | | if not args.key or args.key not in CONFIG KEYS: | | | raise UsageError f"jev config unset <{'\|'.join CONFIG KEYS } " | | | cfg.pop CONFIG KEYS args.key 0 , None | | | if args.key == "credits": | | | cfg.pop "credits as of", None | | | save config cfg | | | print f"unset {args.key}" | | | return 0 | | | if args.action == "set": | | | if not args.key or args.key not in CONFIG KEYS or args.value is None: | | | raise UsageError f"jev config set <{'\|'.join CONFIG KEYS } <value " | | | real, typ, = CONFIG KEYS args.key | | | try: | | | val = typ args.value | | | except ValueError: | | | raise UsageError f"{args.key} expects a {typ. name }" | | | if args.key == "credits as of": | | | try: | | | datetime.fromisoformat val | | | except ValueError: | | | raise UsageError "credits as of expects an ISO timestamp, e.g. 2026-09-19T14:00" | | | cfg real = val | | | if args.key == "credits": | | | cfg "credits as of" = args.as of or datetime.now .isoformat timespec="seconds" | | | save config cfg | | | print f"set {args.key} = {val}" + f" as of {cfg 'credits as of' } " if args.key == "credits" else "" | | | return 0 | | | raise UsageError "jev config show\|set\|unset " | | | | | | | | | CHARS PER TOKEN = 4.0 rough English heuristic; --exact measures the real count with one tiny call | | | | | | | | | def cmd cost args - int: | | | """Estimate tokens and cost for a prospective job before running it.""" | | | state = build state args | | | text = state if isinstance state, str else json.dumps state | | | est state = int len text / CHARS PER TOKEN | | | q tokens = int args.question chars / CHARS PER TOKEN | | | exact = None | | | if args.exact: | | | c = JevClient args.api key, args.model, timeout=args.timeout, label="cost" | | | r = c.ask state, {"probe": noul "Is this text written in English?" } | | | exact = r "usage" "input tokens" | | | est state = max 0, exact - q tokens - 40 subtract the probe question and request overhead | | | per request = est state + args.questions q tokens | | | fits = per request <= 64 000 and est state + q tokens <= 32 000 | | | n items = args.items or 1 | | | if args.items: | | | rank/batch shape: each item is its own request if --per-item, else items are packed with the state repeated per request | | | if args.per item: | | | total = per request n items | | | requests = n items | | | else: | | | per req items = max 1, min 250, 64 000 - est state // max 1, q tokens | | | requests = - -n items // per req items | | | total = requests est state + n items q tokens | | | else: | | | total, requests = per request, 1 | | | out = {"state tokens": est state, "exact": exact is not None, "question tokens each": q tokens, "questions": args.questions, | | | "tokens per request": per request, "fits request budget": fits, "items": n items, "requests": requests, | | | "total input tokens": total, "usd": round cost usd total , 6 , "price per mtok in": price per mtok } | | | if args.json: | | | print json.dumps out, indent=2 | | | return 0 | | | how = "measured" if exact is not None else f"estimated at {CHARS PER TOKEN:g} chars/token add --exact to measure " | | | print f"state {est state:,} tokens {how} " | | | print f"per request {per request:,} tokens = state + {args.questions} question s x ~{q tokens} · {'fits' if fits else 'EXCEEDS'} the 64k/32k request budget" | | | if args.items: | | | print f"job {n items:,} items - {requests:,} request s , {total:,} input tokens" | | | print f"cost ${cost usd total :.6f} at ${price per mtok }/Mtok" + f" ${cost usd total / n items:.7f} per item " if args.items else "" | | | return 0 | | | | | | | | | def cmd schema args - int: | | | print json.dumps { | | | "state": "string \| object \| array the content to judge; use an object with named fields; reference them in instructions with backticks like ticket.message ", | | | "model": "jev-latest", | | | "questions": { | | | "is urgent": {"type": "noul", "instructions": "Does ticket.message convey urgency?", "criteria": {"true": "optional: what yes means", "false": "optional: what no means"}}, | | | "department": {"type": "choice", "instructions": "Which team should handle ticket.message ?", "criteria": {"billing": "Charges, invoices, refunds", "technical": "Bugs, outages, integrations", "other": None}}, | | | "frustration": {"type": "score", "instructions": "How frustrated does the customer appear in ticket.message ?", "criteria": "Calm and matter-of-fact", "Frustrated but civil", "Very angry or threatening to leave" }, | | | }, | | | }, indent=2 | | | print "\nAnswers come back under the same ids: noul - {noul}; choice - {choice, probabilities, confidence}; score - {score, legend, probabilities, confidence}.\ninstructions and every criteria entry may be a string OR a JSON object/array see jev guide structure ." | | | return 0 | | | | | | | | | def cmd docs args - int: | | | url = f"{DOCS}/llms.txt" | | | try: | | | with urllib.request.urlopen urllib.request.Request url, headers={"User-Agent": f"jev-cli/{VERSION}"} , timeout=20 as r: | | | txt = r.read .decode | | | except Exception as e: noqa: BLE001 | | | raise NetworkError f"could not fetch {url}: {e}" | | | if args.grep: | | | needle = args.grep.lower | | | txt = "\n".join line for line in txt.splitlines if needle in line.lower | | | print txt | | | return 0 | | | | | | | | | def cmd guide args - int: | | | if args.list: | | | for k, title, , live in GUIDE.items : | | | print f"{k:<12} {title}" + f" live: {live if live.startswith 'http' else DOCS + live + '.md'} " if live else "" | | | return 0 | | | topic = args.topic or "when" | | | if topic not in GUIDE: | | | raise UsageError f"unknown topic {topic r}. Topics: {', '.join GUIDE }" | | | title, body, live = GUIDE topic | | | if args.live or topic == "vendor": | | | if not live: | | | raise UsageError f"topic {topic r} has no live page" | | | url = live if live.startswith "http" else f"{DOCS}{live}.md" | | | try: | | | with urllib.request.urlopen urllib.request.Request url, headers={"User-Agent": f"jev-cli/{VERSION}"} , timeout=20 as r: | | | print r.read .decode | | | except Exception as e: noqa: BLE001 | | | raise NetworkError f"could not fetch {url}: {e}" | | | return 0 | | | print f" {title}\n\n{body.strip }\n" | | | if live: | | | print f"Live source: {live if live.startswith 'http' else DOCS + live + '.md'} jev guide {topic} --live " | | | return 0 | | | | | | | | | def cmd examples args - int: | | | if not args.name: | | | print "Copy-paste examples. jev examples <name prints one; jev examples all prints everything.\n" | | | for k, title, in EXAMPLES.items : | | | print f" {k:<10} {title}" | | | return 0 | | | keys = list EXAMPLES if args.name == "all" else args.name | | | for k in keys: | | | if k not in EXAMPLES: | | | raise UsageError f"unknown example {k r}. Names: {', '.join EXAMPLES }" | | | title, body = EXAMPLES k | | | print f" {title}\n{body.strip }\n" | | | return 0 | | | | | | | | | --------------------------------------------------------------------------- embedded docs | | | | | | GUIDE: dict str, tuple str, str, str \| None = {} | | | | | | GUIDE "when" = "Jev playbook for agents: when to reach for it, how to ask, how to read", r""" | | | Jev is TypeSafe's System One model. It does not write text. It makes ONE narrow judgment | | | per question against a state you hand it, and returns a calibrated probability. ~250 ms. | | | $0.042 per million input tokens a 1k-token item costs $0.00004 . Output tokens are free. | | | Same input - same answer, run to run. It is a semantic if-statement, not a chatbot. | | | | | | Reach for Jev when | | | 1. The decision REPEATS over many items and you should not read them all into context: | | | classify / filter / rank / dedupe hundreds of notes, emails, transcript segments, log | | | lines, RSS items, PRs, findings. jev rank and jev batch do this in a few requests. | | | 2. You want a CALIBRATED PROBABILITY, not your own vibe. Your confidence is not calibrated; | | | Jev's is trained to be RLCD . Use it to decide act / confirm / escalate. | | | 3. A SCRIPT or CUE needs a judgment that runs unattended, a million times, with no agent | | | loop: "is this Ring event a delivery?", "is this email a receipt?", "is this item relevant?" | | | 4. You need an INDEPENDENT CHECK of your own output: does the source support this claim, | | | does this draft break a stated rule, does this text contain an instruction aimed at an | | | agent prompt injection , is this tool call risky. | | | 5. You need SPEED: real-time gates inside a request path or a UI. | | | | | | Do NOT use Jev for | | | - Generation, rewriting, summarizing, explaining. It cannot. Use yourself. | | | - Math, counting, date arithmetic, numeric comparison. Keep those in code; Jev extracts | | | the parts a Choice over months/days , code does the arithmetic. | | | - Multi-hop reasoning, double negatives, "a property of a property". | | | - One small item you can judge in a glance. The call costs more than the decision. | | | - Hostile input without care: state is data, and injected text can move an answer. Write | | | precise criteria and test edge cases. | | | | | | The three primitives pick by the SHAPE of the answer your code needs | | | \| need \| type \| answer fields \| | | | \| is this true? \| noul \| noul = P yes 0..1 no separate confidence \| | | | \| which one of these? \| choice \| choice, probabilities{opt: p}, confidence \| | | | \| where on this rubric? \| score \| score 0..N-1, may fall between , legend, \| | | | \| \| \| probabilities{level: p}, confidence \| | | | | | | Fast path one question | | | jev yes "Does this message ask for a refund?" --state "I was charged twice, fix it" | | | jev pick "Which team handles this?" billing="Charges, refunds" tech="Bugs" other -s "…" | | | jev rate "How severe is the bug?" "Cosmetic" "Degraded, workaround exists" "Blocking" -s @report.txt | | | yes exits 0/1 on --threshold default 0.5 . pick / rate exit 1 below --min-confidence. | | | Pipe text on stdin instead of --state: cat email.txt \| jev yes "Is this a receipt?" | | | | | | Real path many questions, one call: SPECULATIVE FAN-OUT | | | Ask EVERY question you might need in ONE request. They run in parallel and independently; | | | adding questions barely changes latency and costs only the question tokens. Let code ignore | | | the answers it does not need. | | | jev ask --field message=@ticket.txt --field policy=@refund policy.md \ | | | --noul refund 'Does message request a refund?' \ | | | --noul covered 'Does policy cover the refund requested in message ?' \ | | | --choice team 'Which team should handle message ?' billing=Charges tech=Bugs other \ | | | --score anger 'How angry is message ?' "Calm" "Frustrated but civil" "Hostile" --json | | | Shell rule: SINGLE-QUOTE any instruction containing backticks, or zsh runs them as commands. | | | | | | Writing a question that works Jev reads LITERALLY | | | - One judgment per question. "Analyze this and decide what to do" is not a question; split | | | it. "Does message ask for money back?" is. | | | - Say the exact condition. If you find yourself explaining what you "really meant", that | | | explanation belongs in the instructions or criteria. | | | - Point at the field with a backticked path: ticket.messages 0 .text . Question IDs are | | | NOT sent to the model; the instructions must carry the whole meaning. | | | - NEVER index into a long array items 137 . Measured 2026-09-18: 27% wrong at 150 | | | items per request, still 9% at 25. Key the object instead items.k137 or put the | | | item inside the question itself; both scored 0 wrong out of 320. jev rank does the | | | latter for you. | | | - Choice: describe each option so the boundary with its neighbour is clear; add other / | | | none when the list may not cover the input. Up to 255 options. | | | - Score: levels describe SITUATIONS, low to high, 2..10 of them. "Broken but a workaround | | | exists" works; "moderately bad" and bare numbers do not. One dimension per score. | | | - Noul: phrase it so high = yes. Optional true=/false= criteria pin a subtle boundary. | | | - Send only the state the questions need. Irrelevant context lowers accuracy context rot . | | | Filter in code first. Budget: ~32k tokens for state + longest question. | | | | | | Reading the answer | | | - noul: p = 0.5 is yes, but pick the threshold by stakes. Do not read 0.5 as "medium". | | | - choice: choice is the argmax; confidence says how peaked the distribution is. A second | | | option with real mass is signal, not noise. | | | - score: a position between levels 0.7 1 + 0.3 2 = 1.3 . Round for one outcome; compare or | | | sort for ranking; divide by N-1 to normalize before weighting several scores together. | | | - THREE BANDS: high confidence - act; medium - confirm or gather more; low - do not act, | | | escalate or ask. Thresholds scale with risk: read-only at 0.6, destructive at 0.9. | | | - Do not carry a threshold tuned on a noul over to a choice, and do not expect P x and | | | 1 - P not x from two questions to agree. Ask the question you want, one way. | | | - Combine independent answers in CODE with weights you own composite scoring . A weight | | | change is a code change, not a prompt rewrite, and needs no re-inference. | | | | | | Build it into a tool, not just a chat turn | | | sys.path.insert 0, "/path/to/dir/containing/jev.py" | | | from jev import JevClient, noul, choice, score | | | r = JevClient label="my tool" .ask state, {"ok": noul "Is text a receipt?" } | | | p = r "answers" "ok" "noul" | | | Keep the QUESTIONS and THRESHOLDS in one constant block at the top of the tool so a human | | | can review them. That is the part that needs eyes; the rest is plumbing. | | | | | | Go deeper | | | jev guide --list topics: questions choice score noul state confidence patterns | | | design pitfalls structure cookbooks api library usage | | | exit-codes install vendor | | | jev guide design BUILDING a tool or cron job on Jev, not just calling it once | | | jev guide vendor TypeSafe's own agent skill, fetched live | | | jev guide <topic --live the vendor's page for that topic, current | | | jev examples copy-paste recipes: triage rank filter guardrail verify batch python | | | jev docs live index of every vendor page and cookbook | | | """, "/concepts/how-to-build-with-system-one" | | | | | | GUIDE "questions" = "Writing instructions and criteria", r""" | | | A question is: an ID you choose not sent to the model , a type , instructions , and | | | criteria options for choice, ordered levels for score, optional true/false for noul . | | | | | | Rules that come from measured failure modes jev-1.13 | | | 1. LITERAL READING. Jev answers the words, not the intent. Scoping words, negations and | | | implied conditions are taken at face value. Write the exact condition. Put boundary | | | cases in the criteria. Split any interpretation into two literal questions. | | | 2. ATOMIC. Broad questions hide several judgments behind one number. "Is this spam?" | | | becomes: requests a credential? sender identity conflicts with domain? announces an | | | unexpected reward? Then weight them in code. | | | 3. NAME THE FIELD. With an object state, reference path.to 0 .field in backticks. | | | Structured state + named references removes ambiguity about what to judge. But do | | | not rely on POSITIONAL indexes in long arrays: items 137 mis-locates 27% wrong | | | at 150 items, 9% at 25, measured 2026-09-18 . Use keyed objects items.k137 or | | | embed the item in the question; both 0% wrong at 320. | | | 4. ALIGN INSTRUCTIONS AND CRITERIA. A noul where true means "no" confuses it. The | | | criteria are an extension of the instruction, in the same direction. | | | 5. CONTRASTIVE OPTIONS. For a choice, say what each option covers, what belongs to the | | | neighbour instead, and 1-3 examples. Same field names on every option. | | | 6. SITUATIONS, NOT DEGREES. Score levels are matched one by one against the state; the | | | model does not see the level numbers or neighbours. "Cosmetic; no impact" beats "1". | | | 7. COVER THE SPACE. Add other / none of the above to a choice when inputs may not fit. | | | For selection-from-candidates, the model cannot pick a value you did not offer. | | | 8. KEEP MATH OUT. Counting, dates, magnitudes, hex colours, assembly: convert or compute in | | | code, hand Jev the semantic part "does this colour read as a warning?" . | | | 9. LESS STATE. Send only what the question needs. Retrieve and filter first. | | | | | | Shapes | | | noul {"type":"noul","instructions":"Does msg request a refund?", | | | "criteria":{"true":"asks for money back or a credit","false":"complains without asking for a remedy"}} | | | choice {"type":"choice","instructions":"Which team should handle msg ?", | | | "criteria":{"billing":"charges, invoices, refunds","orders":"status, delivery, returns","other":null}} | | | score {"type":"score","instructions":"How severe is the bug in report ?", | | | "criteria": "Cosmetic; no functional impact","Broken, workaround exists","Blocking; no workaround" } | | | | | | instructions and every criteria entry may be a JSON object or array instead of a string | | | jev guide structure . Start with strings; add structure when two options keep getting | | | confused or a level needs examples. | | | """, "/primitives" | | | | | | GUIDE "choice" = "Choice: pick one option from a defined set", r""" | | | Use when the answer is one of a known set with NO order between them: routing, category, | | | language, entity type, which candidate span is the value. Up to 255 options; adding an | | | option costs a few tokens, so give the FULL list rather than a shortlist. | | | | | | Answer: choice argmax , probabilities every option, sums to 1 , confidence | | | how peaked . Read the runner-up: 0.60 vs 0.38 means two teams want this ticket. | | | | | | jev pick "Which team should handle this?" \ | | | returns="Exchanges, refunds, wrong or damaged items" \ | | | shipping="Delivery status, delays, lost packages" \ | | | billing="Charges, invoices, payment problems" other \ | | | -s "My shoes came in the wrong size and I was charged twice" --min-confidence 0.4 | | | | | | - Confusable neighbours: give each option an object {what, not for, examples}. | | | - Deep taxonomy: one choice per level, options = children, value = the subtree; walk in | | | code, keep several branches alive when probabilities are close beam search . | | | - Relative vs absolute: a choice says WHICH option is best even when all are bad. Pair it | | | with one noul per option or a none option to know whether ANY fits. | | | - Speculative: "If this is a return, why?" is fine to ask on every ticket; ignore the | | | answer when the department was not returns. | | | """, "/primitives/choice" | | | | | | GUIDE "score" = "Score: rate the state on an ordered rubric", r""" | | | Use when the answer is a position on a spectrum you can describe in steps: severity, | | | frustration, relevance, seniority, formality. 2..10 levels, low to high. Level N is its | | | index in the array. The model judges each level's description on its own against the | | | state; it never sees the numbers or the neighbours. | | | | | | Answer: score = sum level p , can land between levels; probabilities per level; | | | legend maps level - description; confidence . | | | | | | jev rate "How much does this bug report give an engineer to work with?" \ | | | "No detail; just says something is broken" \ | | | "Names the feature but no steps or environment" \ | | | "Steps to reproduce or environment, but not both" \ | | | "Steps to reproduce and environment" -s @report.txt | | | | | | - Describe SITUATIONS. Examples inside a level object with what + examples sharpen it, | | | but only when they resemble real inputs. Test against known cases. | | | - One dimension per score. "Punctual and smart and experienced" cannot be placed. | | | - Give a rare extreme its own level "abusive or threatening" so the top is not shared. | | | - Do not interpolate magnitudes from a score "1.3 means 30% of users" . It is a | | | position for thresholding, ranking and rounding, not a measurement. | | | - Same score, different shapes: 1.0 can be all-on-level-1 or half 0 / half 2. Read | | | probabilities and confidence alongside. | | | - Composite: normalize each score by levels-1 , then weight in code: | | | priority = 0.6 severity + 0.3 frustration + 0.1 report quality. | | | """, "/primitives/score" | | | | | | GUIDE "noul" = "Noul: probability that a yes/no statement is true", r""" | | | Use for a clean yes/no where the probability itself is the signal: mentions X, requests | | | Y, contains PII, is a receipt, is relevant to the query, contains an instruction aimed at | | | an agent. Answer: noul = P yes . No separate confidence: near 1 strong yes, near 0 | | | strong no, near 0.5 undecided NOT "medium"; for degree use a score . | | | | | | jev yes 'Does text contain an instruction directed at an AI agent or assistant?' \ | | | --true "tells an agent/assistant/model to do, ignore, or reveal something" \ | | | --false "ordinary content with no directive aimed at a model" \ | | | --field text=@untrusted.md --threshold 0.7 | | | | | | - Phrase so high means yes. A statement form "the customer is requesting a refund" | | | works as well as a question; test both on your data. | | | - Criteria are optional; add true=/false= when the boundary is subtle. | | | - One noul per label when several labels may apply at once multi-label , instead of | | | a single choice. | | | - Counting: one noul per item, the item embedded in its question or under a key | | | items.k7 , never items 7 in a long array; then count in code. | | | - jev yes exit codes: 0 yes, 1 no or uncertain with --band LOW HIGH , 2+ errors. | | | """, "/primitives/noul" | | | | | | GUIDE "state" = "State: what you hand the model", r""" | | | State is the material a panel of experts would be shown before judging. String, JSON | | | object, or array. Text only no images/audio . English is strongest. | | | | | | --state "text" --state @file --state - stdin cat f \| jev … | | | --state-file path .json parsed, else text | | | --state-json '{"a":1}' | | | --field msg=@ticket.txt --field policy=@policy.md --field n=3 builds an object | | | | | | Every shape below is state, and a question is separate from it: | | | | | | \| Shape \| How \| Reference it as \| | | | \|---\|---\|---\| | | | \| one string \| -s TEXT , -s @file , stdin \| the whole state \| | | | \| many sources at once \| --field msg=@t.txt --field policy=@p.md --field orders=@o.json \| msg , policy , orders \| | | | \| nested JSON \| --state-file o.json \| open 0 .charges , sla.tier \| | | | \| a sequence \| --state-json ' "turn 1","turn 2" ' \| the array, in order \| | | | \| a whole document \| --state-file bigdoc.md \| measured OK to 107k chars \| | | | \| full control \| jev ask -f request.json state AND questions \| anything you wrote \| | | | | | | A --field value that is @file.json or inline JSON is PARSED, so an object stays an | | | object and the model sees real structure. Mixing types in one request is fine: a text file, | | | a JSON file, a JSONL file and a bare scalar side by side. | | | | | | Prefer an OBJECT with named fields, then reference fields in instructions with backticked | | | paths: ticket.messages 0 .text , policy . Small arrays index fine; long ones do not | | | items 137 is wrong 27% of the time at 150 items . Key them: {"k137": ...} . | | | | | | - One request = one state, any number of questions, all independent, all parallel. | | | - Budget, MEASURED 2026-09-20 by binary search rather than taken from the docs: the largest | | | state accepted was 107,500 chars = 32,388 input tokens 765 ms ; ~110k chars returns | | | HTTP 400 max tokens exceeded . English measured at 3.32 chars/token , not 4, so the | | | real ceiling is nearer 107k chars than the 150k a 4-char rule of thumb implies. jev | | | warns above 120k chars; rank and batch chunk under it. | | | - Irrelevant material costs accuracy. Filter in code. If you cannot, ask a noul for | | | relevance first and drop what fails. | | | - State is data, not instructions, but adversarial text inside it can still steer an | | | answer. Be explicit in criteria; test edge cases before trusting a guardrail. | | | - When a later question depends on an earlier ANSWER you need it to fetch data or pick | | | the next options , make a second request. Otherwise ask everything at once. | | | """, "/concepts/state" | | | | | | GUIDE "confidence" = "Probabilities vs confidence, and how to act on them", r""" | | | Every choice/score answer carries probabilities the distribution and confidence | | | one number, 0..1, derived from how peaked that distribution is . Nouls carry only P yes . | | | | | | Calibration: across many predictions, outcomes given 0.8 happen ~80% of the time. It | | | describes groups, not any single answer; confidence 1.0 is not a guarantee. | | | | | | Three bands draw the lines by stakes, then test on your data | | | high act automatically | | | medium act with a confirmation, or gather more, or flag | | | low do not act: escalate to a person or a reasoning model, or ask | | | | | | Thresholds scale with risk | | | if a.confidence < 0.5: escalate genuinely unsure | | | elif a.choice == "read only": do it cheap to be wrong | | | elif a.choice == "destroy": | | | if a.confidence 0.9: confirm then do | | | else: ask user | | | | | | - Low choice confidence: no clear winner, OR several acceptable answers harmless . | | | - Low score confidence: levels overlap, question measures 1 thing, or the state does | | | not say enough. | | | - If all you need is the best option, take the argmax; thresholds are for deciding | | | whether to ACT. If you have a statistical procedure in mind, use probabilities, not | | | the confidence summary. | | | - Aliases move jev-latest - new version . Thresholds tuned on one version: pin the | | | versioned id jev-1.13.0 with --model and migrate on your schedule. | | | """, "/confidence" | | | | | | GUIDE "patterns" = "Patterns that compose Jev into systems", r""" | | | 1. SPECULATIVE FAN-OUT. Put every question the workflow might need in one request, | | | including ones that matter only on some branches. Parallel, independent, near-zero | | | latency cost. 13 questions in one call measured 12x cheaper and 10x faster than 13 | | | calls, with identical answers. Code decides which answers count. | | | 2. CONFIDENCE-GATED ROUTING. The answer says WHAT; confidence says WHETHER to act. Gate | | | each action at its own threshold by consequence. jev guide confidence | | | 3. COMPOSITE SCORING. Break a judgment into atomic scores, normalize by levels-1 , | | | weight in code. Weights are reviewable and tunable without re-inference. | | | 4. INTENT ROUTING. Cheap classifier in front of expensive handlers: deterministic code | | | for one intent, a specialist LLM for another, a human for the low-confidence rest. | | | 5. SELECT, DO NOT GENERATE. Find candidate spans/values with regex or a generative model, | | | then let Jev CHOOSE the right one. Extraction becomes a choice over enumerated options | | | with an explicit "not stated". | | | 6. RERANK / FILTER. Cheap retrieval BM25, embeddings, grep makes a shortlist; one Jev | | | question per query-candidate pair grades it. jev rank does this in one request per | | | chunk. Measured on a legal corpus: top-1 5% - 18%, top-10 38% - 62%. | | | 7. VERIFY AND ESCALATE. Check a claim against its source supports / contradicts / says | | | nothing , an extraction against the document, a tool-call trace against its intent. | | | Low confidence goes to a human or a reasoning model. Cascade: small model extracts, | | | Jev verifies, big model only on the uncertain slice. | | | 8. GUARDRAIL. One request per message, in and out of an LLM: a battery of nouls jailbreak? | | | harm? self-harm? instruction aimed at the model? plus a severity score. Threshold in | | | code: pass / review / block / route. | | | 9. MAP-REDUCE. Thousands of items x same questions - jev batch , then aggregate in code. | | | Probabilities become features for a classical model when you have labels. | | | 10. TWO-STAGE SELECTION. Rank everything cheaply, then re-judge the top K with fuller | | | evidence and let the second stage reject all of them. skill suggestion cookbook: | | | wrong loads down by more than half. | | | """, "/patterns" | | | | | | GUIDE "design" = "Designing a NEW integration tool, cron job, pipeline ", r""" | | | Runtime use is jev yes\|pick\|rate\|ask\|rank\|batch . This topic is for the other job: you | | | are about to BUILD something that calls Jev on every run. Much of it is distilled from | | | TypeSafe's own agent skill github.com/typesafe-ai/skills, MIT , which is a docs-oriented | | | skill for exactly this job; jev guide vendor fetches it live. | | | | | | Start from the behaviour, work back to the judgments | | | What will the tool show, select, change, or hand off? List the judgments that decision | | | needs. Keep known rules, calculations, exact lookups and execution in code. Preserve the | | | stack and scope already in place; add Jev only where semantic understanding helps. | | | | | | Shapes beyond "classify" | | | - Route AND fill arguments: one request selects the handler and its closed-set params. | | | - Select instead of generate: code finds candidate spans/values, Jev picks the intended | | | one. Check candidate COVERAGE: the model cannot choose a value you did not offer. | | | - Find and judge evidence: cheap retrieval, then per-candidate relevance, then select. | | | - Judgments as reusable data: score dimensions once; weights, thresholds, rankings and | | | views change in code with no re-inference while the evidence and questions stand. | | | - Verify and escalate: check a claim/field/tool-call against its evidence; send the | | | uncertain slice to a person or a reasoning model. | | | - Respond to changing state: keep INFERRED state distinct from OBSERVED facts, and check | | | freshness before applying an old answer to a changed situation. | | | | | | Atomic is not "one fact per question" | | | A bounded action selection or a contextual interpretation is a valid single judgment. | | | Split independently useful dimensions; do not split a relationship you need judged whole. | | | | | | Policy stays explicit in code | | | Weighted sums suit compensating preferences. An "any serious violation blocks" rule needs | | | separate conditions, not a weight. Ignore uncertainty on branches you do not take. Several | | | acceptable alternatives can spread probability; low confidence on a harmless preference | | | choice is not a reason to stop. Typed output guarantees the INTERFACE, not truth: | | | validate on your own data before trusting it unattended. | | | | | | Ship checklist | | | 1. Questions + thresholds in ONE constant block at the top of the file. Agents write | | | mediocre questions; expect a human to edit them, so make them easy to find. | | | 2. --model jev-1.13.0 pinned once thresholds are tuned. jev-latest moves. | | | 3. A handful of known cases run before the first unattended run; when one fails, separate | | | missing evidence / model error / code error / service failure before changing anything. | | | 4. label= set on the client so jev usage attributes the spend. | | | 5. Long lists: never items i ; key the object or embed the item see pitfalls row 10 . | | | 6. Never embed the key in a web page or a repo; the CLI reads ~/.config/typesafe/api key. | | | """, "/concepts/how-to-build-with-system-one" | | | | | | GUIDE "vendor" = "TypeSafe's own agent skill fetched live from GitHub ", r""" | | | TypeSafe publishes a docs-oriented skill for agents BUILDING integrations: | | | https://github.com/typesafe-ai/skills skills/typesafe-ai/SKILL.md, MIT, ~2.5k tokens | | | It has no executable and no runtime commands; jev is the runtime. Its value is the | | | design guidance and the map of which vendor page to read for which task, and it is | | | updated by the vendor when the API changes. jev guide vendor --live prints the current | | | copy. jev guide design is our distillation, kept short. | | | """, "https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md" | | | | | | GUIDE "pitfalls" = "Jagged edges of jev-1.13 vendor-acknowledged ", r""" | | | \| \| failure \| do this instead \| | | | \| 1 \| literal reading \| write the exact condition; boundary cases in criteria \| | | | \| 2 \| math, counting, magnitudes \| compute in code; one noul per item then sum \| | | | \| 3 \| date/time comparison \| extract parts as choices; compare in code \| | | | \| 4 \| indirection, double negatives \| direct wording; name the field \| | | | \| 5 \| large state with irrelevant detail \| filter first; relevance noul if you cannot \| | | | \| 6 \| adversarial content in state \| precise criteria; test edge cases \| | | | \| 7 \| contradictory instructions/criteria \| align them; true must mean yes \| | | | \| 8 \| expected structural invariants \| P x and 1-P not x need not agree; noul vs choice thresholds differ; ask one way \| | | | \| 9 \| generation \| it cannot; select from candidates instead \| | | | \| 10\| positional index into a long array \| ours, measured 2026-09-18 items 137 27% wrong at 150, 9% at 25; keyed object or item-in-question 0% at 320 \| | | | | | | Numeric representations hex colours, RGB, assembly underperform names and high-level | | | code. Non-English works but is weaker; watch confidence. Reviewed by the vendor | | | 2026-09-17. Live: jev guide pitfalls --live | | | """, "/model-jaggedness/jev-1.13" | | | | | | GUIDE "structure" = "Structured instructions and criteria JSON instead of strings ", r""" | | | instructions , every choice option description, every score level, and noul true/false | | | may be a string, an object, an array, or null. The model is trained on structure; keys | | | are labels it reads, so use short descriptive names none are reserved . | | | | | | "instructions": {"question": "Does the claimed sender conflict with the domain?", | | | "compare": " ticket.sender.display name ", " ticket.sender.email " , | | | "focus": "Compare the named organization with the email domain."} | | | | | | "criteria": {"return policy": {"what": "rules for returns in general", | | | "not for": "the status of a specific return", | | | "examples": "Can I return sale items?" }, | | | "return status": {"what": "where a specific return is", | | | "not for": "general policy questions", | | | "examples": "Where is my refund for order A-104?" }} | | | | | | score level: {"what": "Broken or degraded, workaround exists", | | | "examples": "export fails in one browser but works in another" } | | | | | | When: a question has several parts; two options keep getting confused; a level needs | | | examples; the supporting data is already JSON schema, taxonomy, record . Use the same | | | field names across options so the model compares like with like. Examples only help when | | | they resemble real inputs; the wrong example changes little, the right one concentrates | | | probability measured 0.54 - 0.90 confidence on the same ticket . | | | | | | Taxonomy walk: option value = the child subtree, so the model sees what lives under a | | | branch before committing. Trim large subtrees to direct children plus sample leaves. | | | """, "/primitives/advanced" | | | | | | GUIDE "cookbooks" = "Vendor cookbooks worked, measured examples ", r""" | | | Each is a page under https://docs.typesafe.ai/cookbooks/<slug .md | | | parallel questions 13 questions, one call: 12.2x cheaper, 10x faster, same answers | | | skill suggestion rank 182 agent skills, re-judge top 3, may reject all; wrong loads halved | | | rerank typesafe BM25 shortlist - one question per pair; top-1 5% - 18% | | | semantic find score 218 line ids vs a query in ONE choice; noul: is there an answer at all | | | classifying rag passages per passage: relevant? usable? contradicts premise? instructs the model? | | | citation check supports / contradicts / says nothing; confidence flags for review | | | llm guardrails noul battery + severity score on every LLM input and output | | | function calling NL request - function name + closed-set args, confidence-aware | | | pre parsed value extraction regex finds candidates, Jev selects the intended span | | | date extraction cookbook month/day/year as choices with "not stated"; code assembles and compares | | | autoformat recover Markdown structure: line-join nouls, then block-type choices | | | hierarchical classification beam search over choice probabilities through deep taxonomies | | | entity alignment one 3-level score decides merge / leave / send to curator | | | sde cascade mini extracts - Jev verifies - reasoning model only where needed | | | consistency noul cookbook 14 nouls x 15 runs: std dev 0.0102, below every LLM; route 0.3-0.7 to review | | | consistency choice cookbook add an explicit uncertain outcome to moderation decisions | | | classification using confidence 75 industry groups; low confidence - report the parent division | | | autoresearch feature discovery propose questions, turn text into features, train CatBoost on them | | | Read one with: jev docs --grep <slug then fetch the .md URL. | | | """, "/cookbooks/parallel questions" | | | | | | GUIDE "api" = "HTTP API, limits, pricing", r""" | | | POST https://api.typesafe.ai/v1/systemone Authorization: Bearer <key | | | body {"state": str\|obj\|arr, "model": "jev-latest", "questions": {id: Question}} | | | answer {"model": "jev-1.13.0", "answers": {id: Answer}, "usage": {"input tokens", "output tokens"}} | | | GET /v1/models lists aliases jev-latest, jev-preview ; versioned ids like jev-1.13.0 also accepted | | | | | | Errors: 401 bad key · 422 malformed request body names the field · 429 rate limit · | | | 529 overloaded. jev retries 429/529/5xx with backoff and honours retry-after. | | | Limits jev-1.13, adjust without notice : 250k tokens/s, 1200 req/min; 64k tokens per | | | request, 32k for state + longest question. MEASURED 2026-09-20: 107,500 chars of English | | | state = 32,388 tokens went through; ~110k chars returned 400 max tokens exceeded , an error | | | code the docs do not list. English runs 3.32 chars/token, so budget on tokens, not on the | | | 4-chars-per-token rule of thumb. Text only. | | | Price: $42 per billion input tokens $0.042/Mtok . Output free. jev usage shows spend, | | | jev cost estimates a job, jev config set credits tracks a balance no balance endpoint | | | exists; see jev guide usage . | | | Model is not fine-tuned per customer; you shape it through state, instructions, criteria. | | | Not trained on customer traffic. jev schema prints a request skeleton. | | | Full JSON path: jev ask -f request.json or jev ask with the JSON body on stdin | | | """, "/api" | | | | | | GUIDE "library" = "Using jev from Python tools, Cues, pipelines ", r""" | | | import sys; sys.path.insert 0, "/path/to/dir/containing/jev.py" | | | from jev import JevClient, noul, choice, score, JevError | | | | | | QUESTIONS = { keep questions + thresholds together, reviewable | | | "is receipt": noul "Is email.body a purchase receipt or order confirmation?" , | | | "vendor": choice "Which vendor sent email ?", {"amazon": None, "apple": None, "other": None} , | | | "urgency": score "How urgent is email.body ?", "None", "This week", "Today" , | | | } | | | THRESHOLDS = {"is receipt": 0.7, "vendor conf": 0.6} | | | | | | client = JevClient label="mail triage" label shows up in jev usage | | | r = client.ask {"email": {"subject": s, "body": b}}, QUESTIONS | | | a = r "answers" | | | if a "is receipt" "noul" = THRESHOLDS "is receipt" : ... | | | if a "vendor" "confidence" < THRESHOLDS "vendor conf" : escalate | | | | | | - ask raises JevError exit code attr: 2 usage, 3 auth, 4 api, 5 network . | | | - Many items: a ThreadPoolExecutor over client.ask 8 workers is safe , or shell out | | | to jev batch . Every call appends one line to ~/.config/typesafe/usage.jsonl. | | | - Official SDKs exist pip install typesafe-sdk , npm i @typesafe-ai/sdk with typed | | | answers and retries; this module is the zero-dependency path that works from any agent. | | | - Pin --model jev-1.13.0 in a pipeline whose thresholds you tuned. | | | """, "/sdk/python" | | | | | | GUIDE "usage" = "Usage, cost, credits and rate limits", r""" | | | Every request appends one row to ~/.config/typesafe/usage.jsonl: ts, cmd the label , agent | | | $JEV AGENT , q questions , in/out tokens, ms, model, rid x-typesafe-request-id , | | | attempts when retried, or err on failure. Nothing secret is in it. record=False on | | | JevClient skips it. | | | | | | jev usage windows today/yesterday/7d/30d/month/all , latency p50/p95, | | | peak req/min and tok/s vs the published limits, errors, forecast, | | | credits countdown, budget, by command, by agent names resolved | | | jev usage --by day also hour, cmd, agent, model --days N | | | jev usage --tail 20 recent requests with request ids quote a rid to the vendor | | | jev usage --since 2026-09-01 --label rank --agent 8ba5 --json | | | jev cost --state-file f --questions 12 --exact tokens + usd before you run it | | | jev cost -s "…" --items 5000 a rank-shaped job over 5,000 items | | | jev config set credits 50 balance read off the console; usage counts down from it | | | jev config set budget 5 monthly USD budget; usage shows % used and a projection | | | jev config set price 0.042 only if the vendor changes list price | | | | | | What the API does NOT give you measured 2026-09-19 | | | No balance, usage, or quota endpoint exists /v1/usage, /v1/balance, /v1/account ... all | | | 404 and responses carry no rate-limit headers, only x-typesafe-request-id. "Tokens | | | remaining" therefore means one of three things here: | | | 1. credits remaining: a balance YOU snapshot from https://console.typesafe.ai via | | | jev config set credits , minus spend recorded since. Drift = calls made from | | | another machine or key. Re-snapshot when you look at the console. | | | 2. request budget: 64k tokens per request, 32k for state + longest question. jev cost | | | says whether a state fits and how many items pack per request. | | | 3. rate headroom: 1,200 req/min and 250k tok/s adjust without notice . jev usage | | | shows your measured peaks as a percentage of both. | | | Price: $42 per billion input tokens $0.042/Mtok . Output is free. A 1k-token item costs | | | $0.00004; a thousand of them cost four cents. | | | """, "/models" | | | | | | GUIDE "exit-codes" = "Exit codes", r""" | | | 0 success / yes / confident | | | 1 yes : no or uncertain · pick / rate : confidence below --min-confidence | | | 2 usage error bad flags, empty state, malformed question | | | 3 auth error no key, key rejected | | | 4 API error after retries 429/529/5xx exhausted, 422 · batch : some rows failed | | | 5 network error after retries | | | Errors print one line to stderr prefixed jev: ; with --json the line is JSON. | | | """, None | | | | | | GUIDE "install" = "Where jev lives and how it is maintained", r""" | | | Single file jev.py, anywhere on disk; symlink it onto PATH: ln -s $PWD/jev.py ~/.local/bin/jev | | | Requires Python 3.10+, standard library only | | | Key jev auth set <key - ~/.config/typesafe/api key 0600 , or export TYPESAFE API KEY | | | Keys: https://console.typesafe.ai/keys | | | Usage ledger ~/.config/typesafe/usage.jsonl jev usage | | | Config ~/.config/typesafe/config.json jev config: credits, budget, price; no secrets | | | Skill copy the jev/ skill folder SKILL.md into your agent's skills dir: | | | Claude Code ~/.claude/skills/jev/ | | | Codex ~/.agents/skills/jev/ documented user path; ~/.codex/skills/ also read | | | OpenCode ~/.config/opencode/skills/jev/ | | | One canonical copy, symlinked into each, is easiest to keep current. | | | Attribution export JEV AGENT=<name so jev usage --by agent can tell your agents apart | | | Health jev doctor | | | Vendor docs https://docs.typesafe.ai Markdown at any page path + .md; index at /llms.txt | | | Vendor skill github.com/typesafe-ai/skills is a docs-orientation skill for BUILDING integrations, | | | with no executable. jev guide vendor fetches it live. Installing both puts two skills | | | on the same triggers; pick one. | | | """, None | | | | | | EXAMPLES: dict str, tuple str, str = {} | | | | | | EXAMPLES "gutcheck" = "One calibrated yes/no, usable in an if ", r""" | | | if jev yes 'Does text describe a package delivery?' --field text="$DESC" --threshold 0.7; then | | | echo delivery | | | fi | | | cat draft.md \| jev yes "Does the text contain an em dash character or the phrase 'you're absolutely right'?" | | | that one is a lint, and grep does it better; use jev for judgments grep cannot make | | | cat draft.md \| jev yes "Does the text flatter the reader or agree without giving a reason?" --json | | | """ | | | | | | EXAMPLES "triage" = "Classify + speculative questions in one call", r""" | | | jev ask --field message=@ticket.txt --field open orders=' "A-104","A-118" ' \ | | | --choice team 'Which team should handle message ?' \ | | | billing="Charges, invoices, refunds, subscriptions" \ | | | orders="Order status, delivery, cancellation, returns" \ | | | account="Login, profile, permissions, security" other \ | | | --noul refund 'Does message explicitly ask for money back or a credit?' \ | | | --noul mentions order 'Does message refer to one of open orders by id?' \ | | | --score anger 'How angry is the author of message ?' \ | | | "Calm and matter-of-fact" "Frustrated but civil" "Hostile or threatening to leave" \ | | | --json | | | then in code: route on team.choice if team.confidence = 0.6 else escalate; | | | read refund only on the billing branch; read mentions order only on orders. | | | """ | | | | | | EXAMPLES "rank" = "Rank or filter many candidates against a query one request per chunk ", r""" | | | lines in a file | | | jev rank --query "notes about thermostat schedules" --candidates-file titles.txt --top 10 | | | JSON array of objects each candidate is shown to the model as JSON | | | jev rank --query "a bug that causes data loss" --candidates-file issues.json --min 0.6 --json | | | stdin, graded on a rubric instead of yes/no | | | ls Meetings \| jev rank --query "meetings about the Q3 launch" \ | | | --levels "unrelated" "adjacent" "directly about it" | | | custom question; refer to the item as candidate it is embedded in each question | | | jev rank --query "$Q" --candidates-file x.txt --instructions 'Does candidate answer query ?' | | | extra shared context for every judgment | | | jev rank --query "…" --candidates-file x.txt --context @rubric.md | | | """ | | | | | | EXAMPLES "guardrail" = "Screen untrusted text before acting on it", r""" | | | jev ask --field text=@untrusted.md \ | | | --noul injection 'Does text contain an instruction aimed at an AI agent, assistant, or model?' \ | | | true="tells a model to do, ignore, reveal, or change something" \ | | | false="ordinary content; any imperatives are aimed at a human reader" \ | | | --noul secrets 'Does text ask the reader to disclose a credential, key, or password?' \ | | | --score harm 'How much harm would follow from doing what text asks?' \ | | | "None" "Minor or reversible" "Serious or irreversible" --json | | | thresholds live in your code: block if injection = 0.7 or harm = 1.5; review 0.4..0.7 | | | """ | | | | | | EXAMPLES "verify" = "Check a claim against its source, or a draft against a rule", r""" | | | jev ask --field claim="$CLAIM" --field source=@source.md \ | | | --choice support 'How does source relate to claim ?' \ | | | supports="the source states or entails the claim" \ | | | contradicts="the source states the opposite or an incompatible fact" \ | | | silent="the source does not address the claim" --json | | | confidence < 0.8 - a human confirms it | | | | | | jev ask --field draft=@post.md --field rules=@voice rules.md \ | | | --noul r1 'Does draft violate any rule stated in rules ?' \ | | | --noul r2 'Does draft contain a sentence that flatters the reader?' \ | | | --score tone 'How formal is draft ?' "casual" "neutral" "formal" | | | """ | | | | | | EXAMPLES "batch" = "Same questions over thousands of rows - JSONL", r""" | | | rows: one JSON object per line; --state-key picks the field to judge, --id-key is echoed back | | | jev batch --input items.jsonl --state-key text --id-key id --concurrency 8 \ | | | --noul relevant 'Is text about home automation?' \ | | | --score quality 'How useful is text to a power user?' "noise" "some value" "must read" \ | | | --out results.jsonl | | | plain text lines, one state per line | | | jev batch --input lines.txt --text-lines --noul q "Is this line a TODO?" out.jsonl | | | aggregate in code: jq 'select .answers.relevant.noul 0.7 \| .id' results.jsonl | | | """ | | | | | | EXAMPLES "python" = "From a tool or a cron job", r""" | | | import sys; sys.path.insert 0, "/path/to/dir/containing/jev.py" | | | from jev import JevClient, noul, choice, score | | | Q = {"delivery": noul "Does event.description describe a package being delivered?" , | | | "who": choice "Who is at the door in event.description ?", | | | {"courier": None, "family": None, "stranger": None, "nobody": None} } | | | r = JevClient label="ring watch" .ask {"event": ev}, Q | | | if r "answers" "delivery" "noul" 0.8: notify | | | """ | | | | | | --------------------------------------------------------------------------- argparse | | | | | | SHORT HELP = """jev: calibrated, typed decisions from TypeSafe's Jev model ~250 ms, $0.042/Mtok | | | | | | jev yes "question?" -s TEXT P yes ; exit 0 yes / 1 no | | | jev pick "which?" a=desc b=desc other -s TEXT one option + probabilities + confidence | | | jev rate "how much?" "low" "mid" "high" -s TEXT position on your rubric + confidence | | | jev ask --noul/--choice/--score … -s TEXT many questions, one call fan-out , --json | | | jev rank --query Q --candidates-file F rank/filter many items, chunked | | | jev batch --input rows.jsonl --noul … same questions over many rows - JSONL | | | | | | jev guide the playbook read once per session jev guide --list | | | jev examples copy-paste recipes jev docs live vendor index | | | jev usage spend, tokens, latency, throughput, credits, budget --by, --tail, --json | | | jev cost estimate a job before running it jev config credits / budget / price | | | jev doctor · models · schema · auth set\|status\|clear · version | | | | | | State: -s/--state TEXT \| --state-file F \| --state-json J \| --field k=v v=@file \| stdin. | | | Questions reference fields with backticks; SINGLE-QUOTE them in a shell: 'Does message ask for a refund?' | | | """ | | | | | | | | | def add state args p : | | | g = p.add argument group "state" | | | g.add argument "-s", "--state", help="text to judge; @path reads a file; '-' reads stdin" | | | g.add argument "--state-file", help="file to judge .json is parsed, else text " | | | g.add argument "--state-json", help="inline JSON state" | | | g.add argument "--field", action="append", metavar="KEY=VALUE", help="build an object state; VALUE may be @file or JSON; repeatable; combines with --state as text " | | | | | | | | | def add question args p : | | | g = p.add argument group "questions repeatable, any mix " | | | g.add argument "--noul", dest="noul", action=QAction, nargs="+", metavar="ARG", help="ID INSTRUCTIONS true=… false=… " | | | g.add argument "--choice", dest="choice", action=QAction, nargs="+", metavar="ARG", help="ID INSTRUCTIONS OPTION =desc OPTION =desc …" | | | g.add argument "--score", dest="score", action=QAction, nargs="+", metavar="ARG", help="ID INSTRUCTIONS LEVEL LEVEL … low to high, 2..10 " | | | g.add argument "--questions-file", "-q", help="JSON file: {id: question}" | | | g.add argument "--questions-json", help="inline JSON: {id: question}" | | | | | | | | | def add common p : | | | p.add argument "--model", default=None, help=f"model id or alias default {DEFAULT MODEL}; pin e.g. jev-1.13.0 " | | | p.add argument "--api-key", default=None, help="override key resolution" | | | p.add argument "--timeout", type=float, default=30.0 | | | p.add argument "--json", action="store true", help="machine output raw API response where applicable " | | | p.add argument "--compact", action="store true", help="single-line JSON" | | | p.add argument "-v", "--verbose", action="store true" | | | | | | | | | def build parser - argparse.ArgumentParser: | | | p = argparse.ArgumentParser prog="jev", description=SHORT HELP, formatter class=argparse.RawDescriptionHelpFormatter, add help=True | | | p.add argument "--version", action="version", version=f"jev {VERSION}" | | | sub = p.add subparsers dest="cmd" | | | | | | a = sub.add parser "ask", help="many questions, one call", description="Ask any mix of noul/choice/score questions about one state in ONE request speculative fan-out . Also: jev ask -f request.json or a full JSON body on stdin.", formatter class=argparse.RawDescriptionHelpFormatter, epilog=EXAMPLES "triage" 1 | | | add state args a | | | add question args a | | | a.add argument "-f", "--request", help="full request JSON file state+questions ; '-' for stdin" | | | add common a | | | a.set defaults fn=cmd ask entry | | | | | | y = sub.add parser "yes", help="one yes/no - P yes ; exit 0/1", description="One noul question. Prints <p yes\|no\|uncertain . Exit 0 when p = --threshold or = HIGH of --band , else 1." | | | y.add argument "instructions", help="the yes/no question; phrase so that high = yes" | | | y.add argument "--true", help="what a yes means optional criteria " | | | y.add argument "--false", help="what a no means optional criteria " | | | y.add argument "--threshold", type=float, default=0.5 | | | y.add argument "--band", type=float, nargs=2, metavar= "LOW", "HIGH" , help="p < LOW no · LOW..HIGH uncertain · = HIGH yes" | | | add state args y | | | add common y | | | y.set defaults fn=cmd yes | | | | | | k = sub.add parser "pick", help="one choice - option + confidence", description="One choice question. Options as NAME or NAME=description null description is fine when the name is clear . Exit 1 when confidence < --min-confidence." | | | k.add argument "instructions" | | | k.add argument "options", nargs="+", metavar="OPTION =desc " | | | k.add argument "--min-confidence", type=float, default=0.0 | | | add state args k | | | add common k | | | k.set defaults fn=cmd pick | | | | | | r = sub.add parser "rate", help="one score - position on rubric", description="One score question. Levels low to high, 2..10, each describing a situation. Exit 1 when confidence < --min-confidence." | | | r.add argument "instructions" | | | r.add argument "levels", nargs="+", metavar="LEVEL" | | | r.add argument "--min-confidence", type=float, default=0.0 | | | add state args r | | | add common r | | | r.set defaults fn=cmd rate | | | | | | rk = sub.add parser "rank", help="rank/filter many candidates vs a query", description="Grades every candidate against --query with one question per candidate the item embedded in its question , packed into as few requests as the token budget allows. Default: noul relevance. With --levels: a score rubric normalized to 0..1 as p .", formatter class=argparse.RawDescriptionHelpFormatter, epilog=EXAMPLES "rank" 1 | | | rk.add argument "--query", required=True, help="what you are looking for text, JSON, or @file " | | | rk.add argument "--candidates-file", help="one candidate per line, or a .json array" | | | rk.add argument "candidates", nargs=" ", help="candidates as arguments or stdin " | | | rk.add argument "--instructions", help="the question, referring to candidate and query , e.g. 'Does candidate answer query ?' the item is embedded in each question " | | | rk.add argument "--levels", nargs="+", metavar="LEVEL", help="use a score rubric instead of yes/no" | | | rk.add argument "--context", help="extra shared state text, JSON, or @file available as context " | | | rk.add argument "--top", type=int, help="keep the best N" | | | rk.add argument "--min", type=float, help="keep p = MIN" | | | rk.add argument "--chunk-size", type=int, default=250, help="max candidates per request default 250; 320 measured at 0.4 s " | | | rk.add argument "--chunk-chars", type=int, default=90 000, help="max candidate chars per request default 90k " | | | rk.add argument "--concurrency", type=int, default=6 | | | rk.add argument "--width", type=int, default=110, help="truncate candidate display" | | | add common rk | | | rk.set defaults fn=cmd rank | | | | | | b = sub.add parser "batch", help="same questions over many rows - JSONL", description="One request per input row, in parallel. Rows: JSONL object = state, or --state-key picks a field , or plain text lines --text-lines . Output: JSONL with answers per row.", formatter class=argparse.RawDescriptionHelpFormatter, epilog=EXAMPLES "batch" 1 | | | b.add argument "--input", "-i", required=True, help="JSONL or text file; '-' for stdin" | | | b.add argument "--state-key", help="field of each JSON row to use as the state" | | | b.add argument "--id-key", default="id", help="field echoed back as id default id " | | | b.add argument "--text-lines", action="store true", help="treat every line as a plain-text state" | | | b.add argument "--echo", action="store true", help="include the state in each output row" | | | b.add argument "--out", "-o", help="write JSONL here instead of stdout" | | | b.add argument "--concurrency", type=int, default=8 | | | add question args b | | | add common b | | | b.set defaults fn=cmd batch | | | | | | m = sub.add parser "models", help="list models/aliases" | | | add common m | | | m.set defaults fn=cmd models | | | | | | au = sub.add parser "auth", help="set \| status \| clear the API key" | | | au.add argument "action", choices= "set", "status", "clear" , nargs="?", default="status" | | | au.add argument "key", nargs="?" | | | add common au | | | au.set defaults fn=cmd auth | | | | | | d = sub.add parser "doctor", help="check key, connectivity, one round trip" | | | add common d | | | d.set defaults fn=cmd doctor | | | | | | u = sub.add parser "usage", help="spend, tokens, latency, throughput, credits and budget from the local ledger", description="Every request appends a row to ~/.config/typesafe/usage.jsonl. Default prints the summary; --by breaks it down; --tail lists recent requests. Credits and budget come from jev config because the API exposes no balance." | | | u.add argument "--by", choices= "day", "hour", "cmd", "agent", "model" , help="breakdown table" | | | u.add argument "--days", type=int, default=14, help="days for --by day default 14 " | | | u.add argument "--tail", type=int, metavar="N", help="last N requests with request ids" | | | u.add argument "--since", help="only rows at or after YYYY-MM-DD / ISO timestamp" | | | u.add argument "--label", help="only rows with this cmd/label" | | | u.add argument "--agent", help="only rows whose agent id contains this" | | | add common u | | | u.set defaults fn=cmd usage | | | | | | cf = sub.add parser "config", help="show \| set \| unset credits, budget, price", description="Values live in ~/.config/typesafe/config.json no secrets . jev config set credits 50 after reading the balance off the console; jev usage then counts down." | | | cf.add argument "action", nargs="?", choices= "show", "set", "unset" , default="show" | | | cf.add argument "key", nargs="?", help="credits \| credits as of \| budget \| price" | | | cf.add argument "value", nargs="?" | | | cf.add argument "--as-of", help="ISO timestamp the credits balance was read with set credits " | | | add common cf | | | cf.set defaults fn=cmd config | | | | | | co = sub.add parser "cost", help="estimate tokens and cost for a job before running it", description="Estimates from characters 4 per token or measures with one tiny real call --exact . --items N and --per-item model a rank/batch job." | | | co.add argument "--questions", type=int, default=1, help="questions per request default 1 " | | | co.add argument "--question-chars", type=int, default=120, help="average characters per question incl. criteria default 120 " | | | co.add argument "--items", type=int, help="number of items for a rank/batch-shaped job" | | | co.add argument "--per-item", action="store true", help="each item is its own request with the full state batch shape rather than packed rank shape " | | | co.add argument "--exact", action="store true", help="measure the state's real token count with one tiny call costs a fraction of a cent " | | | add state args co | | | add common co | | | co.set defaults fn=cmd cost | | | | | | s = sub.add parser "schema", help="print a request skeleton" | | | s.set defaults fn=cmd schema | | | | | | g = sub.add parser "guide", help="the agent playbook; guide <topic ; guide --list " | | | g.add argument "topic", nargs="?" | | | g.add argument "--list", action="store true" | | | g.add argument "--live", action="store true", help="fetch the vendor's current page for this topic" | | | g.set defaults fn=cmd guide | | | | | | e = sub.add parser "examples", help="copy-paste recipes; examples <name or examples all " | | | e.add argument "name", nargs="?" | | | e.set defaults fn=cmd examples | | | | | | dc = sub.add parser "docs", help="live vendor doc index llms.txt ; --grep to filter" | | | dc.add argument "--grep" | | | dc.set defaults fn=cmd docs | | | | | | ver = sub.add parser "version" | | | ver.set defaults fn=lambda a: print f"jev {VERSION}" or 0 | | | return p | | | | | | | | | def cmd ask entry args - int: | | | if args.request: | | | raw = sys.stdin.read if args.request == "-" else Path args.request .expanduser .read text | | | try: | | | body = json.loads raw | | | except json.JSONDecodeError as e: | | | raise UsageError f"request JSON invalid: {e}" | | | if not isinstance body, dict or "state" not in body or "questions" not in body: | | | raise UsageError "request JSON must have state and questions " | | | c = JevClient args.api key, args.model or body.get "model" , timeout=args.timeout, label="ask" | | | resp = c.ask body "state" , body "questions" | | | emit args, resp, c.last ms | | | return 0 | | | a full JSON body on stdin no flags is also accepted | | | if not args.state or args.state file or args.state json or args.field and not getattr args, "qlist", None and not args.questions file and not args.questions json and not sys.stdin.isatty : | | | raw = implicit stdin or "" | | | try: | | | body = json.loads raw | | | if isinstance body, dict and "state" in body and "questions" in body: | | | c = JevClient args.api key, args.model or body.get "model" , timeout=args.timeout, label="ask" | | | resp = c.ask body "state" , body "questions" | | | emit args, resp, c.last ms | | | return 0 | | | except json.JSONDecodeError: | | | pass | | | raise UsageError "stdin was not a request JSON; pass questions with --noul/--choice/--score and the state with --state or stdin" | | | return cmd ask args | | | | | | | | | def main argv=None - int: | | | parser = build parser | | | args = parser.parse args argv | | | if not args.cmd: | | | print SHORT HELP.rstrip | | | return 0 | | | if not hasattr args, "json" : | | | args.json = False | | | if not hasattr args, "compact" : | | | args.compact = False | | | if not hasattr args, "verbose" : | | | args.verbose = False | | | try: | | | return int args.fn args or 0 | | | except JevError as e: | | | if getattr args, "json", False : | | | eprint json.dumps {"error": str e , "exit code": e.exit code} | | | else: | | | eprint f"jev: {e}" | | | return e.exit code | | | except KeyboardInterrupt: | | | return 130 | | | | | | | | | if name == " main ": | | | sys.exit main |