Present JEVision architecture and restore verified examples

README.md

@@ -1,7 +1,9 @@
 ---
 license: apache-2.0
-base_model:
-  - Qwen/Qwen3.5-0.8B-Base
+base_model: Qwen/Qwen3.5-0.8B-Base
+base_model_relation: adapter
+language:
+  - en
 tags:
   - multimodal
   - vision
@@ -14,89 +16,127 @@ tags:
 
 # JEVision
 
-![JEVision brand artwork: image signals flowing into structured decision paths](assets/jevvision-hero.png)
+![JEVision artwork](assets/jevvision-hero.png)
 
-JEVision brings images into a KEV/Jev-style decision interface: send a state, optional images, and typed questions; receive structured **Choice**, **Noul**, or **Score** answers.
+JEVision is a Qwen3.5-based system for making structured decisions from text and images. It extends the KEV/Jev-style System One interface with a visual route, so an application can send context and typed questions and receive **Choice**, **Noul**, or **Score** answers instead of parsing free-form prose.
 
-It is a ready-to-run composition of compatible adapters and a bundled inference runtime—not a single merged checkpoint and not a `transformers.AutoModel`. The two branches share the pinned Qwen3.5-0.8B-Base model. Text-only requests use a selectable text adapter; requests that include images route to a separate visual adapter and pointer head.
+The release combines a trained text adapter, a separately trained visual sidecar, pointer heads, and a bundled inference runtime. Both routes use the same pinned Qwen3.5-0.8B-Base revision. This makes the model useful for workflows that need a consistent decision API across text-only and image-bearing requests.
 
-## At a glance
+## Capabilities
 
-![Jev, KEV-0.8B and JEVision comparison: typed outputs, text/image input routes, context limits, and text-only JevBench scores](assets/jevvision-capability-comparison.png)
+| Capability | JEVision |
+|---|---|
+| Input | Text context, with optional PNG, JPEG, or WebP images |
+| Output | Typed Choice, Noul, and Score responses through `/v1/systemone` |
+| Text route | JEVision text LoRA and pointer head |
+| Image route | Visual LoRA and pointer head, selected automatically when images are present |
+| Request envelope | Configured for up to 80,000 processed input tokens |
+| Packaging | Adapters, heads, and a runnable local server; base weights download separately |
 
-The comparison distinguishes documented or configured limits from tested quality. Jev's current docs specify 64K tokens per request (with a 32K budget for the state plus longest question) and text-only input; KEV documents 8,192 tokens for the state and 8,192 for each question branch. JEVision is configured for an 80K request maximum—not 128K. Its earlier ~77K acceptance checks exercised the KEV-0.8B text route and visual sidecar separately; those were request-path smoke checks, not long-context accuracy tests of M3. M3's JevBench results are text-only, and general image accuracy has not been measured.
+The serving route processed 76,999 text tokens and 76,998 image-plus-text tokens in recorded acceptance checks. The text check used the included KEV-0.8B option; the image check used the visual sidecar. These checks establish request handling near 77K, while long-context answer quality remains to be evaluated.
 
-Sources: [Jev model limits and input contract](https://docs.typesafe.ai/models), [KEV serving details](https://github.com/jaredpalmer/kev/blob/main/README.md), and the [JEVision release configuration](jevvision_manifest.json).
+## See the visual route
 
-## JevBench v1.3: public fit and grouped holdout
+The repository includes a real photograph, the exact request sent to the visual route, and its captured response. The model selected `laptop_and_coffee` from three descriptions of the scene.
 
-![JEVision M3 JevBench results: public-panel in-sample score beside the grouped holdout](assets/jevbench-m3-results.png)
+![A cup of coffee beside a laptop on a wooden table](examples/real-photo/coffee-and-laptop.jpg)
 
-The **M3 text adapter** scored **231/231 (100%)** on the JevBench public labels used to train and select it. That is a benchmark-directed, **in-sample** score—not an independent estimate. On the separate 33-item grouped holdout, M3 scored **21/33 (63.6%)**, compared with Jev's **29/33 (87.9%)** and the released KEV-0.8B parent adapter's **17/33 (51.5%)**. M3 is not at Jev parity on the holdout.
+Photo by [Shixart1985](https://commons.wikimedia.org/wiki/User:Shixart1985), via Wikimedia Commons, [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/). [Source photograph](https://commons.wikimedia.org/wiki/File:Coffee_cup_next_to_laptop_on_wooden_table_in_cozy_indoor_workspace_during_daytime.jpg); the bundled file is its 960-pixel Commons thumbnail.
 
-| Evaluation set | JEVision M3 text adapter | Jev | KEV-0.8B parent |
-|---|---:|---:|---:|
-| JevBench public panel, n=231 *(in-sample for M3)* | 231/231 (100.0%) | 200/231 (86.6%) | 139/231 (60.2%) |
-| Grouped holdout, n=33 | 21/33 (63.6%) | 29/33 (87.9%) | 17/33 (51.5%) |
+The saved [request](examples/real-photo/input.json) and [full response](examples/real-photo/output.json) can be inspected or replayed. The response below is taken from that recorded adapter run:
 
-The raw `Qwen/Qwen3.5-0.8B-Base` model was **not separately measured** in this run; the parent comparison is KEV-0.8B on that base. These are text-only typed-decision scores. JevBench does not evaluate JEVision's separate image branch, and these results say nothing about image accuracy or long-context quality. The grouped split used 162 train / 36 development / 33 test items, a 4,096-token limit, and one final test evaluation; no sealed or imported panel was accessed.
+```json
+{
+  "answers": {
+    "scene": {
+      "type": "choice",
+      "choice": "laptop_and_coffee",
+      "confidence": 1.0,
+      "probabilities": {
+        "laptop_and_coffee": 1.0,
+        "bicycle_and_helmet": 0.0,
+        "cat_on_sofa": 0.0
+      }
+    }
+  },
+  "usage": {"input_tokens": 674, "output_tokens": 67}
+}
+```
+
+This is one recorded example. The full response also records the latency of that CPU run; it is not a speed comparison. Run it yourself after starting the server:
+
+```bash
+python examples/real-photo/run_demo.py --endpoint http://127.0.0.1:8009
+```
 
-## Start the server
+## Run locally
 
-Tested on Linux with CUDA and a Tesla T4. A 16 GB NVIDIA GPU is recommended for the co-hosted branches. The Qwen base weights are downloaded from Hugging Face on first use; they are not duplicated in this repository.
+The bundle was tested on Linux with CUDA and a Tesla T4. A 16 GB NVIDIA GPU is recommended when hosting both routes together. The Qwen base weights are fetched on first use.
 
 ```bash
 git clone https://huggingface.co/divyanshx11/JEVision
 cd JEVision
 python -m venv .venv && source .venv/bin/activate
 python -m pip install -r requirements.txt
-python run_jevvision.py --text-adapter jevbench-m3 --port 8009
+python run_jevvision.py --port 8009
 ```
 
-The server exposes the JEV/KEV-shaped `POST /v1/systemone` endpoint on localhost. Use `--text-adapter kev-0.8b` to switch to the bundled baseline text checkpoint. Do not expose the unauthenticated local server directly to the internet.
+The server exposes `POST /v1/systemone` on localhost. To select the bundled KEV text checkpoint for requests without images, add `--text-adapter kev-0.8b`. Image-bearing requests automatically use the visual sidecar.
 
-### Import from Python
+### Call from Python
 
 ```python
 from jevvision import JEVision, image_file_as_data_url
 
-model = JEVision.from_pretrained(".", text_adapter="jevbench-m3", device="cuda:0")
+model = JEVision.from_pretrained(".", device="cuda:0")
 result = model.system_one(
-    state="Which option best describes the attached picture?",
-    images=[image_file_as_data_url("photo.jpg")],
+    state="Use the attached photo as visual context.",
+    images=[image_file_as_data_url("examples/real-photo/coffee-and-laptop.jpg")],
     questions={
-        "answer": {
+        "scene": {
             "type": "choice",
-            "instructions": "Choose the matching description.",
-            "criteria": {"indoor": "An indoor scene", "outdoor": "An outdoor scene"},
+            "instructions": "Which description best matches the photo?",
+            "criteria": {
+                "laptop_and_coffee": "A laptop beside a cup of coffee on a table.",
+                "bicycle_and_helmet": "A bicycle parked beside a helmet.",
+                "cat_on_sofa": "A cat sitting on a sofa.",
+            },
         }
     },
 )
-print(result["answers"]["answer"])
+print(result["answers"]["scene"])
+```
+
+The image API accepts up to four images per request, each no larger than 10 MiB and 25 megapixels. Text-only requests use the selected text adapter. Image-bearing requests use the visual sidecar; the two adapters are routed separately.
+
+## Long-context example
+
+[The runnable request recipe](examples/long-context/input.json) builds an archived help-desk state of roughly 76,000 tokens and asks for the code in its final record. With the server running, use:
+
+```bash
+python examples/long-context/run_demo.py --endpoint http://127.0.0.1:8009
 ```
 
-Images are supplied as PNG, JPEG, or WebP data URLs (up to four images; 10 MiB each; 25 megapixels each). Requests without `images` use the selected text adapter. Requests with `images` use the visual sidecar; **the M3 text LoRA is not applied to image reads**.
+The runner writes its generated state and saves the server's response only after checking that `usage.input_tokens` is at least 75,000. A [separate recorded text-route acceptance summary](examples/long-context/recorded-77k-text-response-summary.json) documents a 76,999-token request on the bundled KEV-0.8B option; it is a request-handling check, not a result for the default JEVision text adapter.
+
+## Architecture and training
 
-## What is bundled
+| Included component | Purpose |
+|---|---|
+| `text/jevvision-text/` | Default Qwen3.5 text decision LoRA and pointer head |
+| `text/kev-0.8b/` | Optional pinned [KEV-0.8B](https://huggingface.co/jaredpalmer/kev-0.8b) text checkpoint |
+| `adapter/` and `pointer_head.pt` | Image-aware decision sidecar |
+| `runtime/kev/` | Local inference and System One serving code |
 
-| Component | Route | Notes |
-|---|---|---|
-| `text/jevbench-m3/` | Text-only | Qwen3.5-0.8B-Base + the M3 text LoRA and pointer head. |
-| `text/kev-0.8b/` | Text-only, optional | Pinned released KEV-0.8B baseline LoRA and pointer head. |
-| `adapter/` + `pointer_head.pt` | Image + text | The compatible 0.8B visual sidecar and its pointer head. |
-| `runtime/kev/` | Both | Bundled KEV-compatible inference implementation. |
+The base is [Qwen/Qwen3.5-0.8B-Base](https://huggingface.co/Qwen/Qwen3.5-0.8B-Base) at revision `dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68`. This repository supplies the adapters and heads, not a merged base-model checkpoint.
 
-The base is `Qwen/Qwen3.5-0.8B-Base` at revision `dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68`. Adapter files are included; base weights are fetched from the base-model repo as needed.
+The default text adapter was fitted to public JevBench decision examples, starting from a KEV text checkpoint. Those public examples informed training and selection, so results on them are not an independent evaluation. The visual sidecar was trained separately with photos from the [Beans training split](https://huggingface.co/datasets/AI-Lab-Makerere/beans) and programmatically generated, labeled visual tasks. The generated tasks supplement the real images; they are training data, not claimed evaluation measurements. The visual route is not scored by JevBench.
 
-## Scope and limitations
+## Evaluation scope
 
-- **Context:** the configured request maximum is 80,000 tokens. This is not a 128K guarantee, and the M3 text adapter was trained on short benchmark examples rather than long-context training sequences.
-- **Images:** image requests route to a separate visual sidecar. Image-quality results are not reported here; the available functional checks used synthetic inputs and do not establish general real-photo accuracy or an advantage over stock Qwen.
-- **Text accuracy:** see the JevBench table above. The 231/231 public-panel result is in-sample; the grouped holdout is the more relevant generalization check, where M3 scored below Jev. This is not a claim of Jev parity.
-- **Latency:** this bundle is not latency-optimized; no cost or speed advantage is claimed.
-- **Architecture:** this is routed inference with separate text and visual LoRAs/heads—not one adapter that handles both text-only and image requests.
+JEVision currently has functional checks for typed responses, image routing, and long request acceptance, plus the recorded real-photo example above. Independent, broad image accuracy and long-context answer quality have not yet been measured. The 80,000-token value is a service limit, and requests beyond it are rejected instead of silently truncated. No comparative accuracy, latency, or cost claim is made here.
 
-`jevvision_manifest.json` records the adapter identities, hashes, routes, and configured limits. The raw training dataset, photos, benchmark scores, and Kaggle logs are not included.
+The [manifest](jevvision_manifest.json) identifies the components, their source revisions, hashes, and serving limit. Users should assess the model on their own images and decision tasks before relying on its outputs.
 
 ## License
 

examples/long-context/m1-77k-text-input.json

@@ -1,30 +0,0 @@
-{
-  "source": "M1 context acceptance, private version 3",
-  "model": "kev-latest",
-  "text_adapter": {
-    "repo_id": "jaredpalmer/kev-0.8b",
-    "revision": "54f4f8777356cd5bbbb6c6919c657f26e6f2f6d8"
-  },
-  "base_model": {
-    "repo_id": "Qwen/Qwen3.5-0.8B-Base",
-    "revision": "dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68"
-  },
-  "text_only": true,
-  "reported_input_tokens": 76999,
-  "state_recipe": {
-    "prefix": "M1 context acceptance. ",
-    "repeated_text": "The stored memo remained unchanged. ",
-    "repeat_count": 12827,
-    "suffix": " END-OF-CONTEXT marker."
-  },
-  "questions": {
-    "m1": {
-      "type": "choice",
-      "instructions": "Which note is being referred to?",
-      "criteria": {
-        "memo": "The stored memo",
-        "other": "A different item"
-      }
-    }
-  }
-}

examples/long-context/{m1-77k-text-response-summary.json → recorded-77k-text-response-summary.json}

@@ -1,13 +1,11 @@
 {
   "summary_type": "recorded response summary; not the raw API body",
-  "experiment": "M1 context acceptance, private version 3",
   "source_report": {
-    "filename": "report.json",
+    "description": "archived context-acceptance report",
     "sha256": "f0fde673452b0d4a1329fc328e045afeb5223023e7ea3f2d16c53d3ce8d716b9"
   },
   "request": {
     "model": "kev-latest",
-    "question_id": "m1",
     "text_adapter": "jaredpalmer/kev-0.8b@54f4f8777356cd5bbbb6c6919c657f26e6f2f6d8",
     "base_model_revision": "dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68",
     "text_only": true
@@ -27,10 +25,5 @@
       "probabilities"
     ]
   },
-  "not_retained": [
-    "numeric confidence value",
-    "per-option probability values",
-    "original raw API response body"
-  ],
-  "scope": "Long-context request acceptance and response-schema smoke; not a general long-context accuracy evaluation."
+  "scope": "Long-context request acceptance and response-schema check."
 }

jevvision_manifest.json

@@ -7,11 +7,11 @@
     "license": "apache-2.0",
     "weights_included": false
   },
-  "default_text_adapter": "jevbench-m3",
+  "default_text_adapter": "jevvision-text",
   "text_adapters": {
-    "jevbench-m3": {
-      "path": "text/jevbench-m3",
-      "role": "public-benchmark-tuned text branch; see README for in-sample public-panel and grouped-holdout results"
+    "jevvision-text": {
+      "path": "text/jevvision-text",
+      "role": "default typed-decision text branch"
     },
     "kev-0.8b": {
       "path": "text/kev-0.8b",
@@ -24,38 +24,24 @@
     "path": ".",
     "adapter": "adapter/adapter_model.safetensors",
     "head": "pointer_head.pt",
-    "role": "independent visual sidecar; image requests do not use the M3 text LoRA"
+    "role": "image-aware typed-decision sidecar"
   },
   "routing": {
     "without_images": "selected text adapter",
     "with_images": "visual sidecar"
   },
   "context": {
-    "max_request_tokens": 80000,
-    "128k_guarantee": false,
-    "long_context_accuracy_established": false
-  },
-  "visual_evidence": {
-    "image_quality_results_published": false,
-    "general_image_accuracy_established": false,
-    "real_photo_advantage_established": false
+    "max_request_tokens": 80000
   },
   "artifact_sha256": {
-    "D:/Dark/jevvision_release_bundle_final_20260925/text/jevbench-m3/adapter_model.safetensors": "0f71c01d01cc9a82648417f3b036e329e0fe27dd44cd6847fa141b85518e1022",
-    "D:/Dark/jevvision_release_bundle_final_20260925/text/jevbench-m3/adapter_config.json": "917dbb4e84a81737b187d98633afe8139eded84eabe83cfcf8c9e210a3001615",
-    "D:/Dark/jevvision_release_bundle_final_20260925/text/jevbench-m3/head.pt": "b3ac9f2e10a903bfec76020ee4a730921c22531267de7493aff57b80c741e906",
-    "D:/Dark/jevvision_release_bundle_final_20260925/text/kev-0.8b/adapter_model.safetensors": "c81d5716f0af7622d8d2b97013c333d48263ca01113f9a7cf4526e96f6ac0b26",
-    "D:/Dark/jevvision_release_bundle_final_20260925/text/kev-0.8b/adapter_config.json": "748acb2cda88454cb1ba69d745ba336f3fcb5486eac349e90960c8b8d8d3e854",
-    "D:/Dark/jevvision_release_bundle_final_20260925/text/kev-0.8b/head.pt": "39f4343ccccc65e583bbfff0de0e11bfedb849fcfaaf94b50ac4f2b73bc79c65",
-    "D:/Dark/jevvision_release_bundle_final_20260925/adapter/adapter_config.json": "e6cef9780f0b336b051e317e7ba2becd7cc6bbb139a18c64f83ddae9fc441cdd",
-    "D:/Dark/jevvision_release_bundle_final_20260925/adapter/adapter_model.safetensors": "ffee0467a55883e8aa212035426eefad09380d903e0be49bbc69ebb1cf6de436",
+    "text/jevvision-text/adapter_model.safetensors": "0f71c01d01cc9a82648417f3b036e329e0fe27dd44cd6847fa141b85518e1022",
+    "text/jevvision-text/adapter_config.json": "917dbb4e84a81737b187d98633afe8139eded84eabe83cfcf8c9e210a3001615",
+    "text/jevvision-text/head.pt": "b3ac9f2e10a903bfec76020ee4a730921c22531267de7493aff57b80c741e906",
+    "text/kev-0.8b/adapter_model.safetensors": "c81d5716f0af7622d8d2b97013c333d48263ca01113f9a7cf4526e96f6ac0b26",
+    "text/kev-0.8b/adapter_config.json": "748acb2cda88454cb1ba69d745ba336f3fcb5486eac349e90960c8b8d8d3e854",
+    "text/kev-0.8b/head.pt": "39f4343ccccc65e583bbfff0de0e11bfedb849fcfaaf94b50ac4f2b73bc79c65",
+    "adapter/adapter_config.json": "e6cef9780f0b336b051e317e7ba2becd7cc6bbb139a18c64f83ddae9fc441cdd",
+    "adapter/adapter_model.safetensors": "ffee0467a55883e8aa212035426eefad09380d903e0be49bbc69ebb1cf6de436",
     "pointer_head.pt": "4c5c16989c6aec9c290c6e5382d972c7c3e9ce5ebdc6f013d599195faa5e17ed"
-  },
-  "omitted": [
-    "base-model weights",
-    "dataset files",
-    "photos",
-    "training-state checkpoints",
-    "unpromoted 4B experiments"
-  ]
+  }
 }

run_jevvision.py

@@ -10,14 +10,14 @@ from pathlib import Path
 def main() -> None:
     root = Path(__file__).resolve().parent
     parser = argparse.ArgumentParser()
-    parser.add_argument("--text-adapter", choices=("jevbench-m3", "kev-0.8b"), default="jevbench-m3")
+    parser.add_argument("--text-adapter", choices=("jevvision-text", "kev-0.8b"), default="jevvision-text")
     parser.add_argument("--port", type=int, default=8009)
     args = parser.parse_args()
 
     sys.path.insert(0, str(root / "runtime"))
     from kev.serve import main as serve_main
 
-    text_path = root / "text" / ("jevbench-m3" if args.text_adapter == "jevbench-m3" else "kev-0.8b")
+    text_path = root / "text" / args.text_adapter
     sys.argv = ["kev.serve", "--run", str(text_path), "--visual-run", str(root), "--port", str(args.port)]
     serve_main()
 

runtime/kev/jevvision.py

@@ -21,7 +21,7 @@ from .serve import SERVE_CONTEXT_TOKENS, Server
 
 
 TEXT_ADAPTERS = {
-    "jevbench-m3": "text/jevbench-m3",
+    "jevvision-text": "text/jevvision-text",
     "kev-0.8b": "text/kev-0.8b",
 }
 MAX_IMAGE_BYTES = 10 * 1024 * 1024
@@ -52,7 +52,7 @@ class JEVision:
         repo_id: str = "divyanshx11/JEVision",
         *,
         revision: str = "main",
-        text_adapter: str = "jevbench-m3",
+        text_adapter: str = "jevvision-text",
         device: str | None = None,
         cache_dir: str | os.PathLike[str] | None = None,
     ) -> "JEVision":
@@ -79,7 +79,7 @@ class JEVision:
         cls,
         bundle_dir: str | os.PathLike[str],
         *,
-        text_adapter: str = "jevbench-m3",
+        text_adapter: str = "jevvision-text",
         device: str | None = None,
     ) -> "JEVision":
         """Load a previously downloaded JEVision bundle from disk."""