jev-style 0.2.0__py3-none-any.whl

jev_style/__init__.py

@@ -0,0 +1,6 @@
+"""Jev-Style: small, calibrated, local decision models with a systemone-compatible API."""
+__version__ = "0.2.0"
+
+from .client import JevStyle, JevStyleError, choice, classify, configure, decide, noul, score  # noqa: E402
+
+__all__ = ["JevStyle", "JevStyleError", "choice", "classify", "configure", "decide", "noul", "score", "__version__"]

jev_style/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

jev_style/adapter.py

@@ -0,0 +1,135 @@
+"""systemone-compatible requests on top of a Jev-Style runtime (``decide_many(state, questions)``).
+
+One request = one state and any number of questions; they go to ONE ``decide_many`` call, so the
+state is read once. Answer arithmetic (over the runtime's calibrated probabilities):
+
+* noul:   ``noul`` = P(true)
+* choice: ``choice`` = argmax option, ``probabilities`` = {option: p}, ``confidence``
+* score:  ``score`` = sum_i i * p_i over level indices 0..K-1, ``legend`` = {"0": label, ...},
+          ``probabilities`` = {"0": p_0, ...}, ``confidence``
+
+confidence = (k * p_max - 1) / (k - 1) for k options, clipped to [0, 1] (0 = uniform, 1 = all mass on
+one option). Over-budget inputs are rejected with 422 ``input_budget_exceeded``; nothing is truncated.
+"""
+from __future__ import annotations
+
+import math
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from .models import MODEL_ID
+from .schema import ApiError, ParsedRequest, QuestionSpec, parse_request
+
+DEFAULT_CATEGORY = "typed_official"      # calibration group the model card uses for free-form typed questions
+
+
+def confidence(probs: list[float]) -> float:
+    k = len(probs)
+    if k <= 1:
+        return 1.0
+    return float(min(1.0, max(0.0, (k * max(probs) - 1.0) / (k - 1.0))))
+
+
+def renormalise(probs: list[float]) -> list[float]:
+    clean = [float(p) if math.isfinite(p) and p > 0 else 0.0 for p in probs]
+    s = sum(clean)
+    if s <= 0:
+        return [1.0 / len(clean)] * len(clean)
+    return [p / s for p in clean]
+
+
+def model_thread() -> ThreadPoolExecutor:
+    """One worker thread that loads the model and runs every call. MLX keeps its GPU stream per thread,
+    so the model must be used on the thread that loaded it; one worker also means one call at a time."""
+    return ThreadPoolExecutor(max_workers=1, thread_name_prefix="jev-style-model")
+
+
+class Adapter:
+    """Thread-safe: every model call runs on ``worker`` (one at a time). ``runtime`` is a Jev-Style runtime
+    object, ``rt`` its module."""
+
+    def __init__(self, runtime: Any, rt: Any, backend: str, model_id: str = MODEL_ID,
+                 category: str | None = DEFAULT_CATEGORY, description: str | None = None,
+                 worker: ThreadPoolExecutor | None = None):
+        self.runtime, self.rt = runtime, rt
+        self.worker = worker or model_thread()
+        self.model_id = model_id
+        self.category = category
+        self._backend = backend
+        self.description = description or "Jev-Style 0.8B Decision v3: local typed decisions (noul / choice / score)"
+        self._lock = threading.Lock()
+
+    @property
+    def backend(self) -> str:
+        dev = getattr(self.runtime, "device", None)
+        return f"{self._backend}-{dev}" if dev else self._backend
+
+    @property
+    def max_len(self) -> int:
+        return int(getattr(getattr(self.runtime, "renderer", None), "max_len", 25_600))
+
+    @property
+    def head_max(self) -> int:
+        return int(getattr(getattr(self.runtime, "renderer", None), "head_max", 2_048))
+
+    def systemone(self, body: Any) -> dict:
+        t0 = time.perf_counter()
+        parsed = body if isinstance(body, ParsedRequest) else parse_request(body)
+        budget = getattr(self.rt, "InputBudgetError", ())
+        qerr = getattr(self.rt, "QuestionError", ())
+        with self._lock:
+            try:
+                results = self.worker.submit(self.runtime.decide_many, parsed.state,
+                                             [q.internal for q in parsed.questions], category=self.category).result()
+            except budget as e:
+                raise ApiError(422, "input_budget_exceeded", f"{e} (nothing truncated)") from None
+            except qerr as e:
+                raise ApiError(422, "invalid_question", str(e)) from None
+        total_ms = (time.perf_counter() - t0) * 1000
+        answers = {q.id: self._answer(q, r) for q, r in zip(parsed.questions, results)}
+        head = sum(int(r.get("head_tokens", 0)) for r in results)
+        state_tokens = int(results[0]["input_tokens"]) - int(results[0].get("head_tokens", 0)) if results else 0
+        return {"model": self.model_id, "answers": answers,
+                "usage": {"input_tokens": state_tokens + head, "state_tokens": state_tokens, "output_tokens": 0},
+                "latency_ms": round(total_ms, 1), "timing": {"total_ms": round(total_ms, 1)}, "backend": self.backend}
+
+    @staticmethod
+    def _answer(q: QuestionSpec, res: dict) -> dict:
+        probs = res["probabilities"]
+        names = q.options if q.type != "noul" else ["false", "true"]
+        p = renormalise([float(probs[n]) for n in names])
+        if q.type == "noul":
+            return {"type": "noul", "noul": p[1]}
+        i = max(range(len(p)), key=p.__getitem__)
+        if q.type == "choice":
+            return {"type": "choice", "choice": names[i], "confidence": confidence(p),
+                    "probabilities": dict(zip(names, p))}
+        return {"type": "score", "score": float(sum(k * v for k, v in enumerate(p))), "confidence": confidence(p),
+                "legend": dict(q.legend), "probabilities": dict(zip(names, p))}
+
+    def models(self) -> dict:
+        entry = {"id": self.model_id, "context_tokens": self.max_len, "head_max_tokens": self.head_max,
+                 "backend": self.backend}
+        return {"object": "list", "data": [entry],
+                # the shape the public systemone SDKs read from GET /v1/models
+                "models": [{"name": self.model_id, "release_date": "2026-09-24", "description": self.description}]}
+
+    def release_info(self) -> dict:
+        fake = self.model_id.endswith("fake")
+        return {"model_name": self.model_id, "release_kind": "fake" if fake else "release", "untrained": fake,
+                "acceptance_status": None}
+
+
+def build_adapter(backend: str = "auto", *, fake: bool = False, **load_kw: Any) -> Adapter:
+    if fake:
+        from . import fake as fk
+        return Adapter(fk.FakeRuntime(), fk, "fake", fk.FAKE_MODEL_ID,
+                       description="Fake engine: deterministic hash-based probabilities, no model")
+    from .models import load
+    worker = model_thread()
+    runtime, rt, name = worker.submit(load, backend, **load_kw).result()
+    from .fastpath import enable_prefix_sharing
+    enable_prefix_sharing(runtime, rt)          # MLX: read the state once for many questions (same scores)
+    return Adapter(runtime, rt, name, worker=worker)

jev_style/cli.py

@@ -0,0 +1,163 @@
+"""``jev-style`` command line.
+
+    jev-style serve                      start the local server (API + Playground) on :8765
+    jev-style decide "text" --noul "Is this about billing?"
+    jev-style download [--backend mlx]   fetch the weights ahead of time
+    jev-style guard [--check CMD]        Claude Code PreToolUse hook
+    jev-style guard-replay               score the guard on labelled tool calls
+    jev-style mcp                        MCP server (stdio) for Claude Code, Cursor, Codex ...
+    jev-style eval data.jsonl            accuracy, calibration and automation rate on your labels
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from typing import Any
+
+from . import __version__
+from .models import BACKENDS
+
+DEFAULT_PORT = 8765
+
+
+def _model_args(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--backend", default=os.environ.get("JEV_STYLE_BACKEND", "auto"), choices=BACKENDS,
+                    help="auto = mlx on Apple silicon when installed, else torch ($JEV_STYLE_BACKEND)")
+    ap.add_argument("--model-dir", default=os.environ.get("JEV_STYLE_MODEL_DIR"),
+                    help="use a local copy of the model repository instead of downloading ($JEV_STYLE_MODEL_DIR)")
+    ap.add_argument("--device", choices=("cuda", "mps", "cpu"),
+                    help="torch device (default: $JEV_STYLE_DEVICE, else the best available)")
+    ap.add_argument("--dtype", default="float32", choices=("float32", "bfloat16", "float16"), help="torch dtype")
+    ap.add_argument("--precision", default="bf16", choices=("bf16", "8bit"), help="mlx weights")
+    ap.add_argument("--quant", default="Q8_0", choices=("F16", "Q8_0", "Q4_K_M"), help="gguf file")
+    ap.add_argument("--scorer", help="path to the jev-score binary (gguf backend)")
+    ap.add_argument("--fake", action="store_true", help="deterministic fake engine, no model (tests / UI work)")
+
+
+def _load_kw(args: argparse.Namespace) -> dict[str, Any]:
+    return {"model_dir": args.model_dir, "device": args.device, "dtype": args.dtype, "precision": args.precision,
+            "quant": args.quant, "scorer": args.scorer}
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    api_key = None
+    if args.api_key_env:
+        api_key = os.environ.get(args.api_key_env, "").strip()
+        if not api_key:
+            print(f"error: environment variable {args.api_key_env} is empty or unset", file=sys.stderr)
+            return 2
+    from .server import build_app
+    print("loading the model (the first run downloads it) ..." if not args.fake else "fake engine", flush=True)
+    app = build_app(args.backend, fake=args.fake, api_key=api_key, **({} if args.fake else _load_kw(args)))
+    a = app.state.adapter
+    print(f"Jev-Style server: model={a.model_id} backend={a.backend} context={a.max_len} "
+          f"auth={'on' if api_key else 'off'} -> http://{args.host}:{args.port}/", flush=True)
+    for e in app.state.ext_errors:
+        print(f"warning: extension {e['slug']} not loaded: {e['error']}", file=sys.stderr)
+    import uvicorn
+    uvicorn.run(app, host=args.host, port=args.port, log_level="warning")
+    return 0
+
+
+def cmd_download(args: argparse.Namespace) -> int:
+    from .models import download
+    print(download(args.backend, precision=args.precision, quant=args.quant))
+    return 0
+
+
+def cmd_decide(args: argparse.Namespace) -> int:
+    from .client import JevStyle, JevStyleError, choice, noul, score
+    state: Any = sys.stdin.read() if args.state == "-" else args.state
+    if args.json_state:
+        state = json.loads(state)
+    qs: dict[str, dict] = {}
+    for i, text in enumerate(args.noul or []):
+        qs[f"noul_{i + 1}"] = noul(text)
+    for i, spec in enumerate(args.choice or []):
+        text, _, opts = spec.partition("::")
+        qs[f"choice_{i + 1}"] = choice(text, [o.strip() for o in opts.split(",") if o.strip()])
+    for i, spec in enumerate(args.score or []):
+        text, _, levels = spec.partition("::")
+        qs[f"score_{i + 1}"] = score(text, [x.strip() for x in levels.split(",") if x.strip()])
+    if not qs:
+        print("error: give at least one --noul, --choice or --score", file=sys.stderr)
+        return 2
+    url = args.url or os.environ.get("JEV_STYLE_URL")
+    js = JevStyle(base_url=url) if url else JevStyle(backend=args.backend, fake=args.fake,
+                                                     **({} if args.fake else _load_kw(args)))
+    try:
+        out = js.decide(state, qs)
+    except JevStyleError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_guard(argv: list[str]) -> int:
+    from . import guard
+    try:
+        return guard.main(argv)
+    except SystemExit:
+        raise
+    except Exception as exc:  # last resort: ask, never block or allow by accident
+        sys.stdout.write(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse", "permissionDecision": "ask",
+            "permissionDecisionReason": f"Jev-Style guard failed ({exc.__class__.__name__}); asking instead."}}) + "\n")
+        return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # subcommands with their own parsers
+    if argv and argv[0] == "guard":
+        return cmd_guard(argv[1:])
+    if argv and argv[0] == "guard-replay":
+        from .guard_replay import main as replay
+        return replay(argv[1:])
+    if argv and argv[0] == "eval":
+        from .evaluate import main as ev
+        return ev(argv[1:])
+    if argv and argv[0] == "mcp":
+        from .mcp_server import main as mcp
+        return mcp(argv[1:])
+
+    ap = argparse.ArgumentParser(prog="jev-style", description="Small, calibrated, local decision models.",
+                                 epilog="also: jev-style eval | guard | guard-replay | mcp  (each has its own --help)")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("serve", help="start the local server (API + Playground)")
+    _model_args(s)
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=int(os.environ.get("JEV_STYLE_PORT", DEFAULT_PORT)),
+                   help=f"default $JEV_STYLE_PORT or {DEFAULT_PORT}")
+    s.add_argument("--api-key-env", metavar="NAME", help="require 'Authorization: Bearer <key>', key from env NAME")
+    s.set_defaults(func=cmd_serve)
+
+    d = sub.add_parser("download", help="download the weights for a backend")
+    d.add_argument("--backend", default=os.environ.get("JEV_STYLE_BACKEND", "auto"), choices=BACKENDS)
+    d.add_argument("--precision", default="bf16", choices=("bf16", "8bit"))
+    d.add_argument("--quant", default="Q8_0", choices=("F16", "Q8_0", "Q4_K_M"))
+    d.set_defaults(func=cmd_download)
+
+    q = sub.add_parser("decide", help="answer questions about a text from the command line")
+    q.add_argument("state", help="the text to judge ('-' reads stdin)")
+    q.add_argument("--json-state", action="store_true", help="parse the state as JSON")
+    q.add_argument("--noul", action="append", metavar="STATEMENT", help="yes/no question (repeatable)")
+    q.add_argument("--choice", action="append", metavar="Q::a,b,c", help="multiple choice (repeatable)")
+    q.add_argument("--score", action="append", metavar="Q::low,mid,high", help="ordered scale, lowest first")
+    q.add_argument("--url", help="use a running server instead of loading the model ($JEV_STYLE_URL)")
+    _model_args(q)
+    q.set_defaults(func=cmd_decide)
+
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jev_style/client.py

@@ -0,0 +1,167 @@
+"""Python client for Jev-Style: in-process, or against any systemone-compatible server.
+
+    from jev_style import JevStyle, noul, choice, score
+    js = JevStyle(fake=True)                             # in-process fake engine (no model)
+    js = JevStyle(backend="auto")                        # in-process real model (downloads it once)
+    js = JevStyle.from_pretrained("chaoliangUNSW/Jev-Style-0.8B-Decision-v3-GGUF")   # pick the build by repo id
+    js = JevStyle(base_url="http://127.0.0.1:8765")      # over HTTP: jev-style serve, or another server
+                                                         # that implements POST /v1/systemone
+    out = js.decide("I was charged twice.", {
+        "billing": noul("Is this about billing?"),
+        "team": choice("Which team?", {"billing": None, "tech": "bugs, outages"}),
+        "urgency": score("How urgent?", ["low", "medium", "high"]),
+    })
+    out["answers"]["team"]["choice"]
+
+``decide`` returns exactly the HTTP response body of ``POST /v1/systemone`` and raises
+``JevStyleError`` (status, code, message, question) for the contract's error bodies.
+
+For scripts there are module-level shortcuts that share one lazily created client
+(``$JEV_STYLE_URL`` if set, else the local model with ``$JEV_STYLE_BACKEND`` or ``auto``)::
+
+    import jev_style
+    jev_style.classify("Where is my parcel?", ["billing", "shipping", "tech"])["label"]   # 'shipping'
+    jev_style.decide("I was charged twice.", {"billing": noul("This is about billing.")})
+    jev_style.configure(base_url="http://127.0.0.1:8765")     # optional: choose the engine yourself
+"""
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any, Iterable, Mapping
+
+
+class JevStyleError(Exception):
+    def __init__(self, status: int, code: str, message: str, question: str | None = None, body: dict | None = None):
+        super().__init__(f"{status} {code}: {message}" + (f" (question {question!r})" if question else ""))
+        self.status, self.code, self.message, self.question, self.body = status, code, message, question, body or {}
+
+
+def noul(instructions: Any, criteria: Mapping[str, Any] | None = None) -> dict:
+    q = {"type": "noul", "instructions": instructions}
+    if criteria is not None:
+        q["criteria"] = dict(criteria)
+    return q
+
+
+def choice(instructions: Any, options: Mapping[str, Any] | Iterable[str]) -> dict:
+    crit = dict(options) if isinstance(options, Mapping) else {str(o): None for o in options}
+    return {"type": "choice", "instructions": instructions, "criteria": crit}
+
+
+def score(instructions: Any, levels: Iterable[Any]) -> dict:
+    return {"type": "score", "instructions": instructions, "criteria": list(levels)}
+
+
+class JevStyle:
+    def __init__(self, base_url: str | None = None, backend: str = "auto", fake: bool = False,
+                 api_key: str | None = None, timeout: float = 120.0, http_client: Any = None, **load_kw: Any):
+        self.base_url = base_url.rstrip("/") if base_url else None
+        self.api_key = api_key if api_key is not None else os.environ.get("JEV_STYLE_API_KEY")
+        self.timeout = timeout
+        self._http = http_client
+        self._adapter = None
+        if self.base_url is None and http_client is None:
+            from .adapter import build_adapter
+            self._adapter = build_adapter(backend, fake=fake, **load_kw)
+
+    @classmethod
+    def from_pretrained(cls, repo_id: str, *, trust_remote_code: bool = False, **load_kw: Any) -> "JevStyle":
+        """Load a Jev-Style release in-process by its Hub repo id; the repo decides the backend (a ``-GGUF`` repo
+        runs on llama.cpp, ``-MLX`` on MLX, the main repo on PyTorch). Keyword arguments go to the loader
+        (``precision="8bit"``, ``quant="Q4_K_M"``, ``device="cpu"``, ``model_dir=...``)."""
+        return cls(repo=repo_id, trust_remote_code=trust_remote_code, **load_kw)
+
+    # -- transport ---------------------------------------------------------------------------
+    def _client(self):
+        if self._http is None:
+            import httpx
+            self._http = httpx.Client(base_url=self.base_url, timeout=self.timeout)
+        return self._http
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+
+    @staticmethod
+    def _raise(resp) -> None:
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+        err = body.get("error") if isinstance(body, dict) else None
+        err = err if isinstance(err, dict) else {}
+        raise JevStyleError(resp.status_code, err.get("code", "http_error"), err.get("message", resp.text[:500]),
+                          err.get("question"), body)
+
+    # -- API ---------------------------------------------------------------------------------
+    def decide(self, state: Any, questions: Mapping[str, dict], model: str | None = None) -> dict:
+        body: dict = {"state": state, "questions": dict(questions)}
+        if model:
+            body["model"] = model
+        if self._adapter is not None:
+            from .schema import ApiError
+            try:
+                return self._adapter.systemone(body)
+            except ApiError as e:
+                raise JevStyleError(e.status, e.code, e.message, e.question, e.body()) from None
+        resp = self._client().post("/v1/systemone", json=body, headers=self._headers())
+        if resp.status_code != 200:
+            self._raise(resp)
+        return resp.json()
+
+    def models(self) -> dict:
+        if self._adapter is not None:
+            return self._adapter.models()
+        resp = self._client().get("/v1/models", headers=self._headers())
+        if resp.status_code != 200:
+            self._raise(resp)
+        return resp.json()
+
+    def close(self) -> None:
+        if self._http is not None and hasattr(self._http, "close"):
+            self._http.close()
+
+    def __enter__(self) -> "JevStyle":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+# -- module-level shortcuts ------------------------------------------------------------------------
+_default: JevStyle | None = None
+_default_lock = threading.Lock()
+
+
+def configure(**kw: Any) -> JevStyle:
+    """Set the client the shortcuts use (same arguments as ``JevStyle``). Returns it."""
+    global _default
+    client = JevStyle(**kw)
+    with _default_lock:
+        old, _default = _default, client
+    if old is not None:
+        old.close()
+    return client
+
+
+def default_client() -> JevStyle:
+    global _default
+    with _default_lock:
+        if _default is None:
+            url = os.environ.get("JEV_STYLE_URL")
+            backend = os.environ.get("JEV_STYLE_BACKEND", "auto")
+            _default = JevStyle(base_url=url) if url else JevStyle(backend=backend)
+        return _default
+
+
+def decide(state: Any, questions: Mapping[str, dict], model: str | None = None) -> dict:
+    """``JevStyle.decide`` on the shared client."""
+    return default_client().decide(state, questions, model=model)
+
+
+def classify(state: Any, labels: Mapping[str, Any] | Iterable[str],
+             instructions: Any = "Which label fits best?") -> dict:
+    """Pick one label. ``labels`` is a list of names or {name: description}.
+    Returns {"label", "confidence", "probabilities"}."""
+    ans = decide(state, {"label": choice(instructions, labels)})["answers"]["label"]
+    return {"label": ans["choice"], "confidence": ans["confidence"], "probabilities": ans["probabilities"]}