selfjevai-sdk 0.4.3__py3-none-any.whl

selfjev/__init__.py

@@ -0,0 +1,45 @@
+"""selfjev: an open decisions model (selfjev-4b) with Jev's API.
+
+The SDK is importable without torch: `from selfjev import SelfJev, Noul, Choice, Score, Multi`. Serving, training and
+evaluation live in selfjev.engine, selfjev.server, selfjev.training and selfjev.evaluation (extras: serve, train).
+"""
+
+from importlib.metadata import version as _version
+
+from .client import (
+    APIConnectionError,
+    APIError,
+    AsyncSelfJev,
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    OverloadedError,
+    RateLimitError,
+    SelfJev,
+    SelfJevError,
+)
+from .types import Choice, DecisionRequest, DecisionResponse, FileObject, FineTuningJob, JobEvent, Multi, Noul, Score, TrainingRow
+
+__version__ = _version("selfjevai-sdk")  # one source: pyproject.toml
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AsyncSelfJev",
+    "AuthenticationError",
+    "Choice",
+    "DecisionRequest",
+    "DecisionResponse",
+    "FileObject",
+    "FineTuningJob",
+    "InvalidRequestError",
+    "JobEvent",
+    "Multi",
+    "NotFoundError",
+    "Noul",
+    "OverloadedError",
+    "RateLimitError",
+    "Score",
+    "SelfJev",
+    "SelfJevError",
+    "TrainingRow",
+]

selfjev/cli.py

@@ -0,0 +1,274 @@
+"""selfjev: serve | classify | eval | calibrate | compare | bench | finetune | rlcd | merge | deploy"""
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+DEFAULT_ADAPTER = "weights/selfjev_4b_vision"
+HUB_ADAPTER = "Jwuthrich/selfjev-4b-vision"  # what DEFAULT_ADAPTER holds, for a pip install with no checkout
+ADAPTER_FILES = ["adapter_model.safetensors", "adapter_config.json", "model.json"]
+# The first module a command imports from each extra, and the extra that provides it.
+EXTRAS = dict.fromkeys(("fastapi", "uvicorn", "multipart", "torch", "transformers", "peft", "safetensors", "huggingface_hub"), "serve")
+EXTRAS |= {"boto3": "deploy", "bitsandbytes": "quant", "accelerate": "quant"}
+
+
+def _adapter(path):
+    """A local adapter directory, or a Hugging Face repo id downloaded to the HF cache (DEFAULT_ADAPTER → HUB_ADAPTER)."""
+    if not path or Path(path).exists():
+        return path
+    repo = HUB_ADAPTER if path == DEFAULT_ADAPTER else path
+    if repo.count("/") != 1 or repo.startswith((".", "/", "~")):
+        raise SystemExit(f"adapter not found: {path}")
+    from huggingface_hub import snapshot_download
+
+    print(f"adapter {path} not found locally; downloading {repo} from Hugging Face", file=sys.stderr)
+    return snapshot_download(repo, allow_patterns=ADAPTER_FILES)
+
+
+def _scorer(a):
+    """The model behind every command: the shared-prefix tree (transformers, exact) or vLLM on merged weights."""
+    if a.engine == "vllm":
+        from .engine.vllm import VllmScorer
+
+        return VllmScorer(a.model_dir, max_length=a.max_length)
+    if a.engine == "ollama":
+        from .engine.ollama import OllamaScorer
+
+        try:
+            return OllamaScorer(a.ollama_model, a.ollama_host, max_length=a.max_length)
+        except RuntimeError as e:
+            raise SystemExit(f"{e}\nget the model: ollama pull hf.co/Jwuthrich/selfjev-4b-vision-GGUF:Q8_0") from None
+    from .engine.tree import TreeServer
+
+    return TreeServer(
+        a.adapter,
+        max_length=a.max_length,
+        max_batch_tokens=a.max_batch_tokens,
+        merge=not getattr(a, "fine_tuning", False),
+        quantize=a.quantize,
+        quantized_model=a.quantized_model,
+    )
+
+
+def _calibration(a, scorer):
+    if not a.calibration:
+        return None
+    from .evaluation import calibration
+
+    return calibration.load(a.calibration, scorer.meta, scorer.meta.get("prompt_sha"))
+
+
+def _model_args(p):
+    p.add_argument(
+        "--adapter", default=DEFAULT_ADAPTER, help=f"LoRA adapter dir or Hugging Face repo (default {DEFAULT_ADAPTER}, else {HUB_ADAPTER})"
+    )
+    p.add_argument(
+        "--engine",
+        default="tree",
+        choices=["tree", "vllm", "ollama"],
+        help="tree: exact, any number of questions; vllm: merged weights; ollama: a GGUF served by Ollama (no torch)",
+    )
+    p.add_argument("--model-dir", help="--engine vllm: merged checkpoint from `selfjev merge`")
+    p.add_argument("--ollama-model", default="selfjev-4b", help="--engine ollama: the model name in Ollama")
+    p.add_argument("--ollama-host", default="http://localhost:11434", help="--engine ollama: where Ollama listens")
+    p.add_argument("--max-length", type=int, default=32768, help="state + longest question, in tokens; longer input is an error")
+    p.add_argument("--max-batch-tokens", type=int, default=16384, help="packed tokens per forward pass")
+    p.add_argument("--quantize", choices=["8bit", "4bit"], help="bitsandbytes weights for an 8 GB GPU (extra: quant)")
+    p.add_argument(
+        "--quantized-model", help="a pre-quantized checkpoint (dir or Hugging Face repo, `selfjev quantize` writes one); replaces --adapter"
+    )
+    p.add_argument("--calibration", help="calibration JSON from `selfjev calibrate` (must match model/adapter/prompt)")
+
+
+def _finetune_args(p, rlcd=False):
+    p.add_argument("--data", required=True, help="training JSONL or .jsonl.gz (state, question, target per line)")
+    p.add_argument("--val", help="validation JSONL (default: 5%% of --data, at most 1,000 questions)")
+    p.add_argument("--out", required=True, help="run directory: adapter/, adapter_last/, train_meta.json")
+    p.add_argument("--init", required=rlcd, help=f"adapter to start from, e.g. {DEFAULT_ADAPTER}" + (" or a finetune run" if rlcd else ""))
+    p.add_argument("--no-options-in-question", action="store_true", help="do not list every option in the question text")
+    p.add_argument("--epochs", type=int, help="default: 1, or enough for 10 optimizer steps on small data (at most 10)")
+    p.add_argument("--lr", type=float, help="default 2e-4 (finetune from scratch), 5e-5 (from --init, rlcd)")
+    p.add_argument("--lora-r", type=int, default=64, help="LoRA rank when starting without --init")
+    p.add_argument("--max-length", type=int, default=16384, help="longer questions are dropped and counted, never truncated")
+    p.add_argument("--batch-tokens", type=int, default=16384, help="packed tree tokens per micro-batch (at least --max-length)")
+    p.add_argument("--grad-accum", type=int, default=2)
+    p.add_argument("--eval-every", type=int, default=150)
+    p.add_argument("--seed", type=int, default=13)
+    p.add_argument(
+        "--soft-weight", type=float, default=0.5, help='rows with "soft" (a teacher\'s probabilities) train on (1 - w) x label + w x soft'
+    )
+    if rlcd:
+        p.add_argument(
+            "--reward", default="log=1,brier=1,spherical=1", help="weights of log, brier, spherical (proper), accuracy, confident_miss"
+        )
+        p.add_argument("--samples", type=int, default=8, help="sampled reports per question")
+        p.add_argument("--sigma", type=float, default=0.3, help="sd of the Gaussian around the logits")
+        p.add_argument("--beta", type=float, default=0.05, help="KL penalty to the --init model")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="selfjev", description="Serve, evaluate and fine-tune selfjev-4b, an open decisions model with Jev's API."
+    )
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("serve", help="HTTP server with Jev's decisions API (POST /api/alpha/decisions) and POST /classify")
+    _model_args(p)
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8000)
+    p.add_argument("--no-options-in-question", action="store_true", help="for adapters trained without the option list")
+    p.add_argument(
+        "--fine-tuning",
+        action="store_true",
+        help="also serve /v1/files and /v1/fine_tuning/jobs (LoRA unmerged; training needs GPU memory next to serving, e.g. a 48 GB card)",
+    )
+    p.add_argument("--home", default=os.environ.get("SELFJEV_HOME", str(Path.home() / ".selfjev" / "server")), help="fine-tuning state")
+    p = sub.add_parser("classify", help="answer one request in the internal schema (a JSON file, or - for stdin)")
+    p.add_argument("request")
+    p.add_argument("--no-options-in-question", action="store_true", help="for adapters trained without the option list")
+    _model_args(p)
+    p = sub.add_parser("eval", help="evaluate JSONL examples; writes report.json and report.md")
+    p.add_argument("--data", nargs="+", required=True)
+    p.add_argument("--split", nargs="*", help="only these splits (e.g. test); default all")
+    p.add_argument("--out", required=True)
+    p.add_argument("--limit", type=int)
+    _model_args(p)
+    p = sub.add_parser("calibrate", help="fit temperatures on a calibration-split report; thresholds on a validation-split report")
+    p.add_argument("--fit", required=True, help="report.json from `selfjev eval --split calibration`")
+    p.add_argument("--thresholds", help="report.json from `selfjev eval --split validation`")
+    p.add_argument("--out", required=True)
+    p = sub.add_parser("compare", help="side-by-side markdown of two or more eval reports")
+    p.add_argument("reports", nargs="+")
+    p.add_argument("--names", nargs="*")
+    p.add_argument("--out")
+    p = sub.add_parser("bench", help="latency / throughput / memory on synthetic requests")
+    _model_args(p)
+    p.add_argument("--lengths", default="512,2048,8192")
+    p.add_argument("--questions", default="1,4,16")
+    p.add_argument("--repeats", type=int, default=20, help="max samples per row (at least 3; ~60 s budget per row)")
+    p.add_argument("--out", required=True)
+    _finetune_args(sub.add_parser("finetune", help="LoRA fine-tune selfjev's recipe (Qwen3.5 + shared-prefix tree) on your data"))
+    _finetune_args(sub.add_parser("rlcd", help="RLCD (proper-scoring-rule training) from a fine-tuned adapter"), rlcd=True)
+    p = sub.add_parser("quantize", help="write a 4-bit or 8-bit checkpoint of an adapter merged into Qwen3.5-4B (needs a CUDA GPU)")
+    p.add_argument("--adapter", default=DEFAULT_ADAPTER)
+    p.add_argument("--bits", required=True, choices=["8bit", "4bit"])
+    p.add_argument("--out", required=True)
+    p = sub.add_parser("merge", help="merge a LoRA adapter into Qwen3.5-4B for --engine vllm")
+    p.add_argument("--adapter", default=DEFAULT_ADAPTER)
+    p.add_argument("--out", required=True)
+    p = sub.add_parser("deploy", help="deploy a server: `selfjev deploy aws up|down|status|list|machines`")
+    dsub = p.add_subparsers(dest="provider", required=True)
+    aws = dsub.add_parser("aws", help="an EC2 GPU box running `selfjev serve` (pip install selfjevai-sdk[deploy])")
+    aws.add_argument("action", choices=["up", "down", "status", "list", "machines"])
+    aws.add_argument("--name", default="selfjev", help="deployment name (tags, state file)")
+    aws.add_argument("--instance", default="g6.xlarge", help="EC2 type; see `selfjev deploy aws machines`")
+    aws.add_argument("--region", default="us-east-2")
+    aws.add_argument("--allow-cidr", default="0.0.0.0/0", help="who may reach the API port (the API key still applies)")
+    aws.add_argument("--ref", default="master", help="git ref of this repository to deploy")
+    aws.add_argument("--api-key", help="default: a new random key, printed once and kept in the state file")
+    aws.add_argument("--max-hours", type=float, help="terminate the box after this many hours (a cost cap for trials)")
+    aws.add_argument("--ssh", action="store_true", help="also a key pair and port 22 from this machine, for debugging")
+    aws.add_argument("--no-wait", action="store_true", help="return once the instance runs, before the server is ready")
+    aws.add_argument("--fine-tuning", action="store_true", help="also serve the fine-tuning routes (jobs train on the box: 48 GB GPU)")
+    a = ap.parse_args(argv)
+    try:
+        for k in ("adapter", "init"):
+            own = getattr(a, "engine", "tree") in ("vllm", "ollama") or getattr(
+                a, "quantized_model", None
+            )  # these take their own model flags
+            if getattr(a, k, None) and not (k == "adapter" and own):
+                setattr(a, k, _adapter(getattr(a, k)))
+        _run(a)
+    except ModuleNotFoundError as e:
+        root = (e.name or "").split(".")[0]
+        if root == "vllm":
+            raise SystemExit("--engine vllm needs vLLM: pip install vllm") from e
+        extra = "train" if a.cmd in ("finetune", "rlcd") else EXTRAS.get(root)
+        if not extra:
+            raise
+        raise SystemExit(f"selfjev {a.cmd} needs the {extra} extra ({root} is missing): pip install 'selfjevai-sdk[{extra}]'") from e
+
+
+def _run(a):
+    if a.cmd == "serve":
+        from .server.app import serve
+
+        scorer = _scorer(a)
+        home = Path(a.home) if a.fine_tuning else None
+        serve(scorer, a.host, a.port, _calibration(a, scorer), not a.no_options_in_question, fine_tuning_home=home, init_adapter=a.adapter)
+    elif a.cmd == "classify":
+        from .core.answers import classify
+        from .core.options import with_option_lists
+
+        scorer = _scorer(a)
+        req = json.load(sys.stdin) if a.request == "-" else json.loads(Path(a.request).read_text())
+        req = req if a.no_options_in_question else with_option_lists(req)  # as selfjev-4b was trained
+        print(json.dumps(classify(scorer, req, _calibration(a, scorer)), indent=2))
+    elif a.cmd == "eval":
+        from .evaluation.evaluate import run
+
+        scorer = _scorer(a)
+        rep = run(scorer, a.data, a.split, _calibration(a, scorer), a.out, a.limit)
+        print((Path(a.out) / "report.md").read_text())
+        print(f"n={rep['meta']['n']} -> {a.out}/report.json")
+    elif a.cmd == "calibrate":
+        from .evaluation.calibration import fit
+
+        print(json.dumps(fit(a.fit, a.thresholds, a.out), indent=2))
+    elif a.cmd == "compare":
+        from .evaluation.evaluate import compare
+
+        md = compare([json.loads(Path(r).read_text()) for r in a.reports], a.names or [Path(r).parent.name for r in a.reports])
+        if a.out:
+            Path(a.out).write_text(md)
+        print(md)
+    elif a.cmd == "bench":
+        from .evaluation.benchmark import default_grid, run
+
+        t0 = time.perf_counter()
+        scorer = _scorer(a)
+        grid = default_grid(tuple(map(int, a.lengths.split(","))), tuple(map(int, a.questions.split(","))))
+        run(scorer, grid, a.repeats, out_dir=a.out, load_ms=1e3 * (time.perf_counter() - t0))
+        print((Path(a.out) / "bench.md").read_text())
+    elif a.cmd in ("finetune", "rlcd"):
+        from .training.finetune import train
+
+        extra = {}
+        if a.cmd == "rlcd":
+            extra = {"reward_weights": {k: float(v) for k, v in (x.split("=") for x in a.reward.split(","))}}
+            extra |= {"samples": a.samples, "sigma": a.sigma, "beta": a.beta}
+        train(a.cmd, a.data, a.out, val=a.val, init=a.init, options_in_question=not a.no_options_in_question, epochs=a.epochs, lr=a.lr,
+              lora_r=a.lora_r, max_length=a.max_length, batch_tokens=a.batch_tokens, grad_accum=a.grad_accum, eval_every=a.eval_every,
+              seed=a.seed, soft_weight=a.soft_weight, **extra)  # fmt: skip
+    elif a.cmd == "deploy":
+        from .deploy import aws
+
+        if a.action == "machines":
+            for k, (gpu, price, use) in aws.MACHINES.items():
+                print(f"{k:13s} {gpu:22s} ${price:.3f}/h  {use}")
+        elif a.action == "up":
+            rec = aws.up(a.name, a.instance, a.region, a.allow_cidr, a.ref, a.api_key, a.max_hours, a.ssh, not a.no_wait, a.fine_tuning)
+            print(json.dumps({k: rec[k] for k in rec if k != "security_group"}, indent=2))
+        elif a.action == "list":
+            print(json.dumps([{k: r[k] for k in ("name", "region", "instance_type", "endpoint")} for r in aws.listing()], indent=2))
+        else:
+            print(json.dumps(getattr(aws, a.action)(a.name), indent=2, default=str))
+    elif a.cmd == "quantize":
+        from .engine.qwen35 import Qwen35Scorer
+
+        sc = Qwen35Scorer(adapter=a.adapter, quantize=a.bits)
+        sc.model.save_pretrained(a.out)
+        sc.tokenizer.save_pretrained(a.out)
+        print(f"{a.bits} checkpoint -> {a.out}")
+    elif a.cmd == "merge":
+        from .engine.vllm import merge
+
+        merge(a.adapter, a.out)
+        print(f"merged -> {a.out}")
+
+
+if __name__ == "__main__":
+    main()

selfjev/client.py

@@ -0,0 +1,335 @@
+"""The selfjev SDK: a client for the decisions API, in Jev's shape (docs/api.md). Works against a selfjev server and
+against Jev itself (TypeSafe's /v1/systemone, or OpenRouter with path="/api/alpha/decisions").
+
+    from selfjev import SelfJev, Choice, Noul
+
+    client = SelfJev(base_url="http://localhost:8000")           # or SELFJEV_BASE_URL / SELFJEV_API_KEY
+    res = client.system_one(
+        state="Ticket 4411: the invoice was charged twice.",
+        questions={"refund": Noul("Does the customer ask for a refund?"),
+                   "team": Choice("Which team?", {"billing": "billing and refunds", "tech": "outages and bugs"})},
+    )
+    res.choices["team"].choice, res.nouls["refund"].noul
+
+Images (the default tree engine): `state=[Path("cat.jpg")]`, or a PIL image or image bytes, alone or next to text parts.
+
+Fine-tuning (a selfjev server started with --fine-tuning; docs/api.md "Fine-tuning"):
+
+    f = client.upload_file("train.jsonl")                         # one decisions request + its answers per line
+    f = client.upload_file([{"state": [Path("a.jpg")], "questions": {...}, "answers": {...}}, ...])  # or rows: images inline
+    job = client.create_fine_tuning_job(f.id, method="rlcd", suffix="acme")
+    job = client.wait_fine_tuning_job(job.id)                     # polls until it ends; then system_one(..., model=job.fine_tuned_model)
+
+Needs only httpx and pydantic. Retries 429, 529, 5xx and connection errors with exponential backoff (Retry-After wins).
+"""
+
+import asyncio
+import base64
+import io
+import json
+import os
+import random
+import time
+from pathlib import Path
+from typing import Any, Literal
+
+import httpx
+from pydantic import TypeAdapter
+
+from .types import (
+    DecisionRequest,
+    DecisionResponse,
+    ErrorResponse,
+    FileObject,
+    FineTuningJob,
+    FineTuningJobRequest,
+    JobEvent,
+    Question,
+    TrainingRow,
+)
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+DEFAULT_PATH = "/v1/systemone"
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504, 529})
+_QUESTIONS = TypeAdapter(dict[str, Question])
+_JOBS, _EVENTS = TypeAdapter(list[FineTuningJob]), TypeAdapter(list[JobEvent])
+JOBS = "/v1/fine_tuning/jobs"
+DONE = frozenset({"succeeded", "failed", "cancelled"})
+
+
+class SelfJevError(Exception):
+    """Base class of every SDK error."""
+
+
+class APIConnectionError(SelfJevError):
+    """The server could not be reached (after retries)."""
+
+
+class APIError(SelfJevError):
+    """The server answered with an error status. `type` and `message` come from its JSON error body."""
+
+    def __init__(self, status: int, message: str, type: str = "api_error", param: str | None = None, request_id: str | None = None):
+        super().__init__(f"{status} {type}: {message}")
+        self.status, self.message, self.type, self.param, self.request_id = status, message, type, param, request_id
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class InvalidRequestError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class OverloadedError(APIError):
+    pass
+
+
+_BY_STATUS = {401: AuthenticationError, 403: AuthenticationError, 404: NotFoundError, 400: InvalidRequestError,
+              422: InvalidRequestError, 429: RateLimitError, 529: OverloadedError}  # fmt: skip
+
+
+def _error(r: httpx.Response) -> APIError:
+    try:
+        e = ErrorResponse.model_validate(r.json()).error
+        message, kind, param = e.message, e.type, e.param
+    except Exception:  # not our JSON error body: keep the raw text
+        message, kind, param = r.text[:500] or r.reason_phrase, "api_error", None
+    return _BY_STATUS.get(r.status_code, APIError)(r.status_code, message, kind, param, r.headers.get("x-request-id"))
+
+
+def _delay(attempt: int, r: httpx.Response | None) -> float:
+    after = r.headers.get("retry-after") if r is not None else None
+    if after:
+        try:
+            return min(float(after), 60.0)
+        except ValueError:
+            pass
+    return min(8.0, 0.5 * 2**attempt) * (0.5 + random.random() / 2)
+
+
+_MAGIC = {b"\x89PNG": "png", b"\xff\xd8\xff": "jpeg", b"GIF8": "gif", b"RIFF": "webp"}
+
+
+def _part(p):
+    """An image in `state` (a PIL image, image file bytes, or a Path to an image file) -> a base64 data URL."""
+    if isinstance(p, Path):
+        p = p.read_bytes()
+    if hasattr(p, "save"):  # PIL.Image
+        buf = io.BytesIO()
+        p.save(buf, format="PNG")
+        p = buf.getvalue()
+    if not isinstance(p, bytes):
+        return p
+    kind = next((k for m, k in _MAGIC.items() if p.startswith(m)), None)
+    if kind is None:
+        raise ValueError("state: bytes must be a PNG, JPEG, GIF or WebP image")
+    return f"data:image/{kind};base64," + base64.b64encode(p).decode()
+
+
+def _state(state):
+    """Images in `state` (alone or among the parts of a list) -> data URLs; text and JSON stay as they are."""
+    return [_part(p) for p in state] if isinstance(state, list | tuple) else _part(state)
+
+
+class _Base:
+    def __init__(self, api_key=None, base_url=None, model=None, timeout=60.0, max_retries=2, path=DEFAULT_PATH):
+        self.api_key = api_key if api_key is not None else os.environ.get("SELFJEV_API_KEY")
+        self.base_url = (base_url or os.environ.get("SELFJEV_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.model = model or os.environ.get("SELFJEV_DEFAULT_MODEL") or "selfjev-4b"
+        self.timeout, self.max_retries, self.path = timeout, max_retries, path
+
+    def _headers(self) -> dict[str, str]:
+        h = {"User-Agent": "selfjev-python"}  # httpx sets Content-Type: JSON bodies and multipart uploads differ
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def _body(self, state, questions, model, extra_body) -> dict:
+        req = DecisionRequest(model=model or self.model, state=_state(state), questions=_QUESTIONS.validate_python(questions))
+        return req.model_dump(mode="json", exclude_none=True) | (extra_body or {})
+
+    @staticmethod
+    def _upload(file, purpose) -> dict:  # bytes, not a file handle, so a retry resends the whole file
+        if isinstance(file, str | Path):
+            name, content = Path(file).name, Path(file).read_bytes()
+        else:  # rows, each checked here (a bad one fails before the upload); images as in system_one's state
+            rows = (r.model_dump(exclude_none=True) if isinstance(r, TrainingRow) else r for r in file)
+            rows = [TrainingRow.model_validate(r | {"state": _state(r["state"])}).model_dump(mode="json", exclude_none=True) for r in rows]
+            name, content = "rows.jsonl", "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in rows).encode()
+        return {"files": {"file": (name, content)}, "data": {"purpose": purpose}}
+
+    @staticmethod
+    def _job(training_file, method, hyperparameters, validation_file, suffix, model) -> dict:
+        req = FineTuningJobRequest.model_validate(
+            {"training_file": training_file, "validation_file": validation_file, "suffix": suffix,
+             "method": {"type": method, "hyperparameters": hyperparameters or {}}} | ({"model": model} if model else {})
+        )  # fmt: skip
+        return {"json": req.model_dump(mode="json", exclude_none=True)}
+
+
+class SelfJev(_Base):
+    """Synchronous client. Reuse one instance: it keeps a connection pool."""
+
+    def __init__(self, api_key=None, base_url=None, model=None, timeout=60.0, max_retries=2, path=DEFAULT_PATH, http_client=None):
+        super().__init__(api_key, base_url, model, timeout, max_retries, path)
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    def system_one(self, state, questions: dict[str, Any], model: str | None = None, extra_body: dict | None = None) -> DecisionResponse:
+        """Answer every question about `state`. Questions: Noul / Choice / Score / Multi objects or plain dicts."""
+        return DecisionResponse.model_validate(self._post(self.path, self._body(state, questions, model, extra_body)))
+
+    def models(self) -> list[dict]:
+        return self._request("GET", "/v1/models").json()["data"]
+
+    def upload_file(self, file: str | Path | list, purpose: str = "fine-tune") -> FileObject:
+        """Upload fine-tuning data: a JSONL file (one {"state", "questions", "answers"} object per line) or a list of such
+        rows (dicts or TrainingRow), whose images may be Paths, image bytes or PIL images as in system_one."""
+        return FileObject.model_validate(self._request("POST", "/v1/files", **self._upload(file, purpose)).json())
+
+    def create_fine_tuning_job(
+        self,
+        training_file: str,
+        method: Literal["supervised", "rlcd"] = "supervised",
+        hyperparameters: dict | None = None,
+        validation_file: str | None = None,
+        suffix: str | None = None,
+        model: str | None = None,
+    ) -> FineTuningJob:
+        """Queue a fine-tune (supervised) or RLCD job; its model is served under job.fine_tuned_model once it succeeds."""
+        body = self._job(training_file, method, hyperparameters, validation_file, suffix, model)
+        return FineTuningJob.model_validate(self._request("POST", JOBS, **body).json())
+
+    def fine_tuning_job(self, job_id: str) -> FineTuningJob:
+        return FineTuningJob.model_validate(self._request("GET", f"{JOBS}/{job_id}").json())
+
+    def fine_tuning_jobs(self) -> list[FineTuningJob]:
+        return _JOBS.validate_python(self._request("GET", JOBS).json()["data"])
+
+    def fine_tuning_events(self, job_id: str) -> list[JobEvent]:
+        return _EVENTS.validate_python(self._request("GET", f"{JOBS}/{job_id}/events").json()["data"])
+
+    def cancel_fine_tuning_job(self, job_id: str) -> FineTuningJob:
+        return FineTuningJob.model_validate(self._request("POST", f"{JOBS}/{job_id}/cancel").json())
+
+    def wait_fine_tuning_job(self, job_id: str, poll: float = 10.0, timeout: float | None = None) -> FineTuningJob:
+        """Poll until the job succeeds, fails or is cancelled (check job.status); TimeoutError after `timeout` seconds."""
+        t0 = time.monotonic()
+        while (job := self.fine_tuning_job(job_id)).status not in DONE:
+            if timeout is not None and time.monotonic() - t0 > timeout:
+                raise TimeoutError(f"{job_id} still {job.status} after {timeout:.0f} s")
+            time.sleep(poll)
+        return job
+
+    def _post(self, path: str, body: dict) -> dict:
+        return self._request("POST", path, json=body).json()
+
+    def _request(self, method: str, path: str, **kw) -> httpx.Response:
+        for attempt in range(self.max_retries + 1):
+            try:
+                r = self._http.request(method, self.base_url + path, headers=self._headers(), **kw)
+            except httpx.TransportError as e:
+                if attempt == self.max_retries:
+                    raise APIConnectionError(f"{method} {self.base_url + path}: {e}") from e
+                time.sleep(_delay(attempt, None))
+                continue
+            if r.status_code < 400:
+                return r
+            if r.status_code not in RETRY_STATUSES or attempt == self.max_retries:
+                raise _error(r)
+            time.sleep(_delay(attempt, r))
+        raise AssertionError("unreachable")
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class AsyncSelfJev(_Base):
+    """Asynchronous client: `await client.system_one(...)`."""
+
+    def __init__(self, api_key=None, base_url=None, model=None, timeout=60.0, max_retries=2, path=DEFAULT_PATH, http_client=None):
+        super().__init__(api_key, base_url, model, timeout, max_retries, path)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def system_one(
+        self, state, questions: dict[str, Any], model: str | None = None, extra_body: dict | None = None
+    ) -> DecisionResponse:
+        body = self._body(state, questions, model, extra_body)
+        return DecisionResponse.model_validate((await self._request("POST", self.path, json=body)).json())
+
+    async def models(self) -> list[dict]:
+        return (await self._request("GET", "/v1/models")).json()["data"]
+
+    async def upload_file(self, file: str | Path | list, purpose: str = "fine-tune") -> FileObject:
+        return FileObject.model_validate((await self._request("POST", "/v1/files", **self._upload(file, purpose))).json())
+
+    async def create_fine_tuning_job(
+        self,
+        training_file: str,
+        method: Literal["supervised", "rlcd"] = "supervised",
+        hyperparameters: dict | None = None,
+        validation_file: str | None = None,
+        suffix: str | None = None,
+        model: str | None = None,
+    ) -> FineTuningJob:
+        body = self._job(training_file, method, hyperparameters, validation_file, suffix, model)
+        return FineTuningJob.model_validate((await self._request("POST", JOBS, **body)).json())
+
+    async def fine_tuning_job(self, job_id: str) -> FineTuningJob:
+        return FineTuningJob.model_validate((await self._request("GET", f"{JOBS}/{job_id}")).json())
+
+    async def fine_tuning_jobs(self) -> list[FineTuningJob]:
+        return _JOBS.validate_python((await self._request("GET", JOBS)).json()["data"])
+
+    async def fine_tuning_events(self, job_id: str) -> list[JobEvent]:
+        return _EVENTS.validate_python((await self._request("GET", f"{JOBS}/{job_id}/events")).json()["data"])
+
+    async def cancel_fine_tuning_job(self, job_id: str) -> FineTuningJob:
+        return FineTuningJob.model_validate((await self._request("POST", f"{JOBS}/{job_id}/cancel")).json())
+
+    async def wait_fine_tuning_job(self, job_id: str, poll: float = 10.0, timeout: float | None = None) -> FineTuningJob:
+        t0 = time.monotonic()
+        while (job := await self.fine_tuning_job(job_id)).status not in DONE:
+            if timeout is not None and time.monotonic() - t0 > timeout:
+                raise TimeoutError(f"{job_id} still {job.status} after {timeout:.0f} s")
+            await asyncio.sleep(poll)
+        return job
+
+    async def _request(self, method: str, path: str, **kw) -> httpx.Response:
+        for attempt in range(self.max_retries + 1):
+            try:
+                r = await self._http.request(method, self.base_url + path, headers=self._headers(), **kw)
+            except httpx.TransportError as e:
+                if attempt == self.max_retries:
+                    raise APIConnectionError(f"{method} {self.base_url + path}: {e}") from e
+                await asyncio.sleep(_delay(attempt, None))
+                continue
+            if r.status_code < 400:
+                return r
+            if r.status_code not in RETRY_STATUSES or attempt == self.max_retries:
+                raise _error(r)
+            await asyncio.sleep(_delay(attempt, r))
+        raise AssertionError("unreachable")
+
+    async def aclose(self):
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.aclose()

selfjev/core/__init__.py

@@ -0,0 +1 @@
+"""Model-agnostic pieces: the internal request schema, the option-list transform, scores -> typed answers."""