qev 0.2.0__py3-none-any.whl

qev/__init__.py

@@ -0,0 +1,28 @@
+"""QEV public interface to the evaluated multimodal decision runtime."""
+
+__version__ = "0.2.0"
+__all__ = ["DecisionRequest", "QEV", "load", "__version__"]
+
+
+def load(checkpoint=None, *, device="auto", cache_dir=None, offline=False):
+    """Load QEV, downloading its pinned weights on the first use.
+
+    Later calls reuse the local model cache. ``offline=True`` requires all weights
+    to be available already. ``QEV.load`` remains the original low-level loader.
+    """
+    from qev.runtime import load_model
+
+    return load_model(checkpoint, device=device, cache_dir=cache_dir, offline=offline)
+
+
+def __getattr__(name):
+    # CLI help and packaging metadata do not need to initialize PyTorch.
+    if name == "QEV":
+        from veyra.option_model import OptionModel
+
+        return OptionModel
+    if name == "DecisionRequest":
+        from veyra.schema import DecisionRequest
+
+        return DecisionRequest
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

qev/__main__.py

@@ -0,0 +1,5 @@
+"""Support python -m qev as well as the installed qev command."""
+
+from qev.cli import main
+
+main()

qev/cli.py

@@ -0,0 +1,130 @@
+"""SDK, local playground and first-use model downloads in one installed command."""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from qev import __version__
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="qev")
+    parser.add_argument("--version", action="version", version=f"qev {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    download = commands.add_parser("download", help="Download the pinned model for later use")
+    download.add_argument("--cache-dir")
+    download.add_argument("--output", "--checkpoint", type=Path)
+    download.add_argument("--checkpoint-only", action="store_true")
+    download.add_argument("--base-only", action="store_true")
+    download.add_argument(
+        "--offline", action="store_true", default=os.environ.get("QEV_OFFLINE") == "1"
+    )
+    for name in ("predict", "serve", "playground"):
+        command = commands.add_parser(name)
+        command.add_argument(
+            "--checkpoint", type=Path, help="Checkpoint folder; default: QEV cache"
+        )
+        command.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto")
+        command.add_argument("--cache-dir", help="Hugging Face cache; also accepts QEV_CACHE_DIR")
+        command.add_argument(
+            "--offline", action="store_true", default=os.environ.get("QEV_OFFLINE") == "1"
+        )
+        if name == "predict":
+            command.add_argument("--request", type=Path, required=True)
+        else:
+            command.add_argument("--host", default="127.0.0.1")
+            command.add_argument("--port", type=int, default=7860 if name == "playground" else 8000)
+            if name == "serve":
+                command.add_argument("--image-root", type=Path, default=Path.cwd())
+            else:
+                command.add_argument(
+                    "--open", action="store_true", help="Open the playground in a browser"
+                )
+    for name in ("star", "support"):
+        command = commands.add_parser(name, help=f"Show the QEV {name} page")
+        command.add_argument("--open", action="store_true", help="Open the page in your browser")
+    args = parser.parse_args(argv)
+    if args.command == "download" and args.base_only and args.checkpoint_only:
+        parser.error("--base-only and --checkpoint-only cannot be combined")
+    if hasattr(args, "port") and not 1 <= args.port <= 65535:
+        parser.error("--port must be between 1 and 65535")
+    try:
+        run(args)
+    except (ValueError, RuntimeError, OSError) as error:
+        parser.exit(1, f"qev: {error}\n")
+
+
+def run(args):
+    if args.command in {"star", "support"}:
+        from qev.community import REPOSITORY_URL, SUPPORT_URL
+
+        url = REPOSITORY_URL if args.command == "star" else SUPPORT_URL
+        print(url)
+        if args.open:
+            import webbrowser
+
+            webbrowser.open(url)
+        return
+    from qev.runtime import cache_home, load_model, prepare_checkpoint, resolve_cache
+
+    def progress(message):
+        print(message, file=sys.stderr, flush=True)
+
+    if args.command == "download":
+        from qev.download import CHECKPOINT_REVISION, download_backbone, download_checkpoint
+
+        folder = args.output or cache_home() / "checkpoints" / CHECKPOINT_REVISION
+        cache = resolve_cache(args.cache_dir)
+        if args.checkpoint_only:
+            result = {
+                "checkpoint": str(download_checkpoint(folder, cache, local_files_only=args.offline))
+            }
+        elif args.base_only:
+            result = {"backbone_cache": download_backbone(cache, local_files_only=args.offline)}
+        else:
+            folder, cache = prepare_checkpoint(
+                folder, cache_dir=cache, offline=args.offline, progress=progress
+            )
+            result = {"checkpoint": str(folder), "backbone_cache": cache}
+        print(json.dumps(result, indent=2))
+        return
+    if args.command == "playground":
+        from qev.playground.app import launch
+
+        launch(
+            checkpoint=args.checkpoint,
+            device=args.device,
+            cache_dir=args.cache_dir,
+            offline=args.offline,
+            host=args.host,
+            port=args.port,
+            inbrowser=args.open,
+        )
+        return
+    import torch
+
+    from qev import DecisionRequest
+
+    torch.set_num_threads(4)
+    request = None
+    if args.command == "predict":
+        request = DecisionRequest.from_json(args.request.read_text(encoding="utf-8"))
+    elif not args.image_root.is_dir():
+        raise ValueError("--image-root must be an existing directory")
+    model = load_model(
+        args.checkpoint,
+        device=args.device,
+        cache_dir=args.cache_dir,
+        offline=args.offline,
+        progress=progress,
+    )
+    if request is not None:
+        print(json.dumps(model.predict(request, args.request.parent.resolve()), indent=2))
+    else:
+        import uvicorn
+
+        from veyra.server import create_app
+
+        uvicorn.run(create_app(model, args.image_root), host=args.host, port=args.port)

qev/community.py

@@ -0,0 +1,10 @@
+"""Public community links; opening a page always requires a user action."""
+
+REPOSITORY_URL = "https://github.com/ken-jo/qev"
+SUPPORT_URL = "https://github.com/sponsors/ken-jo"
+
+
+def community_markdown():
+    return (
+        "[Star QEV on GitHub](" + REPOSITORY_URL + ") · [GitHub Sponsors](" + SUPPORT_URL + ")"
+    )

qev/download.py

@@ -0,0 +1,118 @@
+"""Download the immutable QEV decision checkpoint and its upstream backbone."""
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+CHECKPOINT_ID = "ken-jo/qev"
+# The repository rename preserves this original checkpoint revision.
+CHECKPOINT_REVISION = "0d2d13ffb3c392071ea00b6bdb903c4b84dff48d"
+CHECKPOINT_HASHES = {
+    "head.safetensors": "84b57aeeb987f73416ac0f796150957d1c5beb1ed373733053e46438f77a8fee",
+    "manifest.json": "d83f9910196c6e801658ca3816c3d2bd4a849ba3da6ff059a0edf7c6028e898d",
+}
+
+
+def download_checkpoint(output: Path, cache_dir: str, *, local_files_only=False) -> Path:
+    """Copy verified checkpoint files into an explicit local directory."""
+    from filelock import FileLock
+    from huggingface_hub import hf_hub_download
+
+    output = output.resolve()
+    existing = []
+    for name, expected in CHECKPOINT_HASHES.items():
+        target = output / name
+        if target.exists():
+            if hashlib.sha256(target.read_bytes()).hexdigest() != expected:
+                raise ValueError(f"Refusing to replace a different checkpoint file: {target}")
+            existing.append(name)
+    if len(existing) == len(CHECKPOINT_HASHES):
+        return output
+    output.mkdir(parents=True, exist_ok=True)
+    locks = Path(cache_dir) / ".qev-locks"
+    locks.mkdir(parents=True, exist_ok=True)
+    lock_name = hashlib.sha256(os.path.normcase(str(output)).encode()).hexdigest() + ".lock"
+    with FileLock(str(locks / lock_name)):
+        for name, expected in CHECKPOINT_HASHES.items():
+            destination = output / name
+            if destination.exists():
+                if hashlib.sha256(destination.read_bytes()).hexdigest() != expected:
+                    raise ValueError(
+                        f"Refusing to replace a different checkpoint file: {destination}"
+                    )
+                continue
+            source = Path(
+                hf_hub_download(
+                    CHECKPOINT_ID,
+                    name,
+                    revision=CHECKPOINT_REVISION,
+                    cache_dir=cache_dir,
+                    local_files_only=local_files_only,
+                    token=False,
+                )
+            )
+            raw = source.read_bytes()
+            if hashlib.sha256(raw).hexdigest() != expected:
+                raise ValueError(f"Checkpoint integrity check failed: {name}")
+            temporary = None
+            try:
+                with tempfile.NamedTemporaryFile(
+                    dir=output, suffix=".partial", delete=False
+                ) as stream:
+                    temporary = Path(stream.name)
+                    stream.write(raw)
+                os.replace(temporary, destination)
+            finally:
+                if temporary is not None:
+                    temporary.unlink(missing_ok=True)
+    return output
+
+
+def download_backbone(cache_dir: str, *, local_files_only=False) -> str:
+    """Download the exact upstream weights and preprocessing files."""
+    from huggingface_hub import snapshot_download
+
+    from veyra.constants import MODEL_ID, MODEL_REVISION
+
+    folder = Path(
+        snapshot_download(
+            MODEL_ID,
+            revision=MODEL_REVISION,
+            cache_dir=cache_dir,
+            local_files_only=local_files_only,
+            allow_patterns=["*.json", "*.safetensors", "*.jinja", "*.txt"],
+            token=False,
+        )
+    )
+    required = {
+        "config.json",
+        "preprocessor_config.json",
+        "tokenizer.json",
+        "tokenizer_config.json",
+        "chat_template.jinja",
+        "merges.txt",
+        "vocab.json",
+        "video_preprocessor_config.json",
+        "model.safetensors.index.json",
+    }
+    index = folder / "model.safetensors.index.json"
+    if index.is_file():
+        required.update(json.loads(index.read_text("utf-8"))["weight_map"].values())
+    missing = []
+    for name in required:
+        # Hub snapshots may symlink weights into the adjacent blob cache.
+        path = folder / name
+        if (
+            Path(name).is_absolute()
+            or ".." in Path(name).parts
+            or not path.is_file()
+            or path.stat().st_size == 0
+        ):
+            missing.append(name)
+    if missing:
+        from huggingface_hub.errors import LocalEntryNotFoundError
+
+        raise LocalEntryNotFoundError("Incomplete Qwen snapshot: " + ", ".join(sorted(missing)))
+    return str(folder)

qev/playground/__init__.py

@@ -0,0 +1 @@
+"""English playground and licensed sample photographs included with the QEV SDK."""

qev/playground/app.py

@@ -0,0 +1,243 @@
+"""English local playground shipped inside the QEV Python distribution."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+os.environ.setdefault("GRADIO_ANALYTICS_ENABLED", "False")
+import gradio as gr  # noqa: E402
+
+from qev.community import community_markdown  # noqa: E402
+from qev.playground.engine import DemoEngine  # noqa: E402
+
+ROOT = Path(__file__).resolve().parent
+PRESETS = json.loads((ROOT / "presets.json").read_text("utf-8"))
+LABELS = {
+    "support": "Text / Route a support request",
+    "policy": "Text / Apply an order policy",
+    "uncertain": "Text / Check insufficient evidence",
+    "photo": "Image / Choose the material",
+    "photo_score": "Image / Score visibility",
+    "photo_truth": "Image / Judge a proposition",
+    "photo_policy": "Image + text / Apply a sorting policy",
+}
+SAMPLES = [
+    ("sample-01.jpg", "Glass bottle"),
+    ("sample-02.jpg", "Newspaper"),
+    ("sample-03.jpg", "Cardboard"),
+    ("sample-04.jpg", "Plastic bottle"),
+    ("sample-05.jpg", "Metal can"),
+    ("sample-06.jpg", "Packaging pouch"),
+]
+CSS = """
+.gradio-container { max-width: 1200px !important; }
+#intro { padding: 12px 0 20px; }
+#intro h1 { letter-spacing: -.04em; font-size: 34px; line-height: 1.12; }
+#intro p { max-width: 760px; }
+#run-button { min-height: 48px; }
+footer { display: none !important; }
+"""
+
+
+def preset_values(key):
+    preset = PRESETS[key]
+    question = preset["questions"][0]
+    options = question["options"]
+    criteria = "\n".join(
+        item["text"] if question["type"] == "score" else f"{item['key']} | {item['text']}"
+        for item in options
+    )
+    image = str(ROOT / "samples" / (preset["sampleId"] + ".jpg")) if "sampleId" in preset else None
+    return preset["text"], image, question["instructions"], question["type"], criteria
+
+
+def default_criteria(kind):
+    if kind == "noul":
+        return "false | The proposition is false.\ntrue | The proposition is true."
+    if kind == "score":
+        return (
+            "Low: the criterion is not met.\nMedium: the criterion is partly met.\n"
+            "High: the criterion is fully met."
+        )
+    return "yes | The evidence meets the criterion.\nno | The evidence does not meet the criterion."
+
+
+def runtime_notice(device, shared_gpu=False):
+    if shared_gpu:
+        return (
+            "**Shared GPU demo.** GPU acceleration is enabled. Response time depends on "
+            "GPU availability, input size and the queue. Daily usage limits apply."
+        )
+    if device == "cuda":
+        return (
+            "**GPU demo.** GPU acceleration is enabled. "
+            "Response time depends on input size and the queue."
+        )
+    return (
+        "**CPU demo.** Responses may take several seconds. GPU hosting can make model "
+        "processing faster; input size and queue time also affect how long you wait."
+    )
+
+
+def build_demo(engine):
+    def predict(*args):
+        try:
+            return engine.predict(*args)
+        except (ValueError, TypeError) as error:
+            raise gr.Error(str(error)) from error
+        except Exception as error:
+            logging.exception("Demo inference failed")
+            raise gr.Error(
+                "The model could not process this request. Please try a shorter example."
+            ) from error
+
+    initial = preset_values("support")
+    with gr.Blocks(title="QEV", delete_cache=(300, 600)) as demo:
+        gr.Markdown(
+            "# QEV\n"
+            "Provide the evidence. Define your candidates. Inspect the probabilities.\n\n"
+            "Dynamic text and image decisions with **Qwen3.5-2B**. "
+            "[Model](https://huggingface.co/ken-jo/qev) · "
+            "[Data](https://huggingface.co/datasets/ken-jo/qev-data) · "
+            "[Source](https://github.com/ken-jo/qev)",
+            elem_id="intro",
+        )
+        gr.Markdown(runtime_notice(engine.device))
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=6):
+                example = gr.Dropdown(
+                    choices=[(value, key) for key, value in LABELS.items()],
+                    value="support",
+                    label="Start with an example",
+                )
+                evidence = gr.Textbox(
+                    value=initial[0], label="Evidence and context", lines=4, max_lines=8
+                )
+                image = gr.Image(
+                    type="pil",
+                    image_mode="RGB",
+                    sources=["upload", "clipboard"],
+                    label="Image (optional)",
+                    height=250,
+                )
+                gr.Examples(
+                    examples=[[str(ROOT / "samples" / name)] for name, _ in SAMPLES],
+                    inputs=[image],
+                    label="Sample photographs",
+                    cache_examples=False,
+                )
+                gr.Markdown(
+                    "Photos: TrashNet, Gary Thung & Mindy Yang (MIT). These examples overlap "
+                    "development data; they are not a benchmark."
+                )
+                kind = gr.Radio(
+                    ["choice", "score", "noul"], value=initial[3], label="Decision type"
+                )
+                question = gr.Textbox(value=initial[2], label="Question and decision rule", lines=2)
+                criteria = gr.Textbox(
+                    value=initial[4], label="Candidate descriptions / score levels", lines=5
+                )
+                gr.Markdown(
+                    "**choice:** `label | description`, one per line. "
+                    "**score:** one description per line, from level 0 upward. "
+                    "**noul:** use `false | ...` and `true | ...`."
+                )
+                resolution = gr.Dropdown(
+                    ["Original", "64", "128", "192", "256", "384", "512", "768", "1024"],
+                    value="Original",
+                    label="Image long edge (pixels)",
+                    info=(
+                        "Resize without cropping or upscaling. "
+                        "The model then applies its trained pixel budget."
+                    ),
+                )
+                run = gr.Button("Run decision", variant="primary", elem_id="run-button")
+            with gr.Column(scale=5):
+                summary = gr.Textbox(label="Decision", lines=6, interactive=False)
+                distribution = gr.Label(label="Candidate probabilities", num_top_classes=16)
+                gr.Markdown(
+                    "Probabilities are model estimates, not verified accuracy. "
+                    "An abstained prediction needs review. "
+                    "Score is an expected level, not a confidence percentage."
+                )
+                with gr.Accordion("Request and response JSON", open=False):
+                    request = gr.Code(label="Request", language="json", interactive=False)
+                    response = gr.JSON(label="Response")
+                with gr.Accordion("Scope and limitations", open=False):
+                    gr.Markdown(
+                        "One image, one question and 2–16 candidates per demo request. "
+                        "The full API supports up to four questions. OCR and spatial reasoning "
+                        "are weak; 2048 experiments produced no wins. English is the main "
+                        "evaluated language. Inputs are processed on the machine running QEV. "
+                        "Per-request image files are removed after inference; cached uploads "
+                        "expire after approximately 10 minutes."
+                    )
+
+        def clear_results():
+            return "Inputs changed. Run a decision to see the new result.", None, None, None
+
+        result_outputs = [summary, distribution, request, response]
+        example.change(
+            preset_values,
+            [example],
+            [evidence, image, question, kind, criteria],
+            queue=False,
+            api_name=False,
+        ).then(clear_results, [], result_outputs, queue=False, api_name=False)
+        kind.input(default_criteria, [kind], [criteria], queue=False, api_name=False)
+        for control in (evidence, image, question, kind, criteria, resolution):
+            control.input(clear_results, [], result_outputs, queue=False, api_name=False)
+        run.click(
+            predict,
+            [evidence, image, question, kind, criteria, resolution],
+            [summary, distribution, request, response],
+            api_name="predict",
+            concurrency_limit=1,
+            concurrency_id="model",
+        )
+        gr.Markdown(community_markdown())
+    return demo
+
+
+def launch(
+    *,
+    checkpoint=None,
+    device="auto",
+    cache_dir=None,
+    offline=False,
+    host="127.0.0.1",
+    port=7860,
+    inbrowser=False,
+):
+    logging.basicConfig(level=logging.INFO)
+
+    def progress(message):
+        print(message, file=sys.stderr, flush=True)
+
+    print("QEV local playground. Optional: star or support QEV at https://github.com/ken-jo/qev")
+    engine = DemoEngine(
+        device=device,
+        checkpoint=checkpoint,
+        cache_dir=cache_dir,
+        offline=offline,
+    ).load(progress=progress)
+    demo = build_demo(engine)
+    demo.queue(max_size=8, default_concurrency_limit=1)
+    demo.launch(
+        server_name=host,
+        server_port=port,
+        inbrowser=inbrowser,
+        share=False,
+        show_error=False,
+        max_file_size="10mb",
+        css=CSS,
+        theme=gr.themes.Base(primary_hue="blue"),
+    )
+
+
+if __name__ == "__main__":
+    launch()

qev/playground/engine.py

@@ -0,0 +1,121 @@
+"""Public demo adapter around the released, unchanged decision runtime."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+import torch
+from PIL import Image, ImageOps
+
+from qev import DecisionRequest
+from qev.runtime import load_model, resolve_cache, resolve_device
+
+MAX_IMAGE_PIXELS = 16_000_000
+RESOLUTIONS = (64, 128, 192, 256, 384, 512, 768, 1024)
+
+
+def build_request(text, question, kind, criteria, has_image):
+    if len(text) > 6000 or len(question) > 1000 or len(criteria) > 6000:
+        raise ValueError("Please shorten the evidence, question or candidate descriptions.")
+    lines = [line.strip() for line in criteria.splitlines() if line.strip()]
+    if kind == "score":
+        choices = lines
+    elif kind in {"choice", "noul"}:
+        choices = {}
+        for line in lines:
+            if "|" not in line:
+                raise ValueError("Use one candidate per line: label | description.")
+            label, description = (part.strip() for part in line.split("|", 1))
+            if label in choices:
+                raise ValueError("Candidate labels must be unique.")
+            choices[label] = description
+        if kind == "noul" and set(choices) != {"false", "true"}:
+            raise ValueError("A noul question needs exactly the labels false and true.")
+    else:
+        raise ValueError("Choose choice, score or noul.")
+    return DecisionRequest.model_validate(
+        {
+            "state": {"text": text, "images": [{"path": "image.png"}] if has_image else []},
+            "questions": {
+                "decision": {"type": kind, "instructions": question, "criteria": choices}
+            },
+        }
+    )
+
+
+def prepare_image(image, resolution):
+    if image is None:
+        return None, "No image"
+    if image.width * image.height > MAX_IMAGE_PIXELS:
+        raise ValueError("Use an image of at most 16 megapixels.")
+    if resolution != "Original" and int(resolution) not in RESOLUTIONS:
+        raise ValueError("Choose one of the available image resolutions.")
+    prepared = ImageOps.exif_transpose(image).convert("RGB")
+    source_size = prepared.size
+    if resolution != "Original":
+        edge = int(resolution)
+        prepared.thumbnail((edge, edge), Image.Resampling.LANCZOS)
+    return prepared, f"{source_size[0]} x {source_size[1]} -> {prepared.width} x {prepared.height}"
+
+
+class DemoEngine:
+    def __init__(self, device="auto", checkpoint=None, cache_dir=None, offline=False):
+        self.device = resolve_device(device)
+        self.checkpoint = checkpoint
+        self.cache_dir = resolve_cache(cache_dir)
+        self.offline = offline or os.environ.get("QEV_OFFLINE") == "1"
+        self.model = None
+
+    def load(self, progress=None):
+        torch.set_num_threads(4)
+        self.model = load_model(
+            self.checkpoint,
+            device=self.device,
+            cache_dir=self.cache_dir,
+            offline=self.offline,
+            progress=progress,
+        )
+        return self
+
+    def predict(self, text, image, question, kind, criteria, resolution="Original"):
+        if self.model is None:
+            raise RuntimeError("The model is not ready yet. Please try again shortly.")
+        request = build_request(text, question, kind, criteria, image is not None)
+        prepared, geometry = prepare_image(image, resolution)
+        try:
+            with tempfile.TemporaryDirectory(prefix="qev-") as temporary:
+                if prepared is not None:
+                    prepared.save(Path(temporary) / "image.png")
+                if self.device == "cuda":
+                    torch.cuda.synchronize()
+                start = time.perf_counter()
+                result = self.model.predict(request, image_root=Path(temporary))
+                if self.device == "cuda":
+                    torch.cuda.synchronize()
+                elapsed = (time.perf_counter() - start) * 1000
+        finally:
+            if prepared is not None:
+                prepared.close()
+        answer = result["answers"]["decision"]
+        probabilities = answer["probabilities"]
+        top = max(probabilities, key=probabilities.get)
+        if kind == "score":
+            expected = sum(float(key) * value for key, value in probabilities.items())
+            decision = f"Expected score: {expected:.3f} (levels start at 0)"
+        elif kind == "noul":
+            decision = f"Probability true: {probabilities['true']:.1%}"
+        else:
+            decision = f"Top candidate: {top} ({probabilities[top]:.1%})"
+        status = "ABSTAINED - review the evidence" if answer["abstained"] else "Answer accepted"
+        summary = (
+            f"{status}\n{decision}\n"
+            f"Model computation: {elapsed:.0f} ms on {self.device.upper()}\n"
+            f"Image: {geometry}\nQueue, upload and network time are excluded."
+        )
+        result["demo"] = {"device": self.device, "model_ms": round(elapsed, 2), "image": geometry}
+        # Keep schema paths as JSON text: Gradio clients otherwise interpret them as files.
+        return summary, probabilities, json.dumps(request.model_dump(), indent=2), result