Initial EviScene release

.gitattributes

@@ -0,0 +1,41 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/architecture.webp filter=lfs diff=lfs merge=lfs -text
+paper/EviScene.pdf filter=lfs diff=lfs merge=lfs -text
+models/sft/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+models/psd/tokenizer.json filter=lfs diff=lfs merge=lfs -text
+datasets/EviLens/train/images/** filter=lfs diff=lfs merge=lfs -text
+datasets/EviLens/test/images/** filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: Code checks
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.11', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]" -e ./training
+      - run: ruff check .
+      - run: python scripts/check_release.py
+      - run: python -m build
+      - run: python -m build training
+      - run: python scripts/check_release.py --distributions
+      - name: Verify installed wheels outside checkout
+        shell: bash
+        run: |
+          python -m venv wheel-check
+          if [ "${{ runner.os }}" = "Windows" ]; then
+            py="$PWD/wheel-check/Scripts/python.exe"
+          else
+            py="$PWD/wheel-check/bin/python"
+          fi
+          "$py" -m pip install dist/*.whl training/dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$py" -c "import eviscene, eviscene_training; from eviscene.orchestrator.stage_runner import StageRunner, StageStep"
+          "$py" -m eviscene --help
+          "$py" -m eviscene_training.cli --help

.gitignore

@@ -0,0 +1,86 @@
+# Generated Python/package files
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+.venv/
+wheel-check/
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+*.bak
+*.tmp
+*.orig
+*.rej
+tests/
+outputs/
+.cache/
+cache/
+*.log
+*.whl
+
+# Credentials and local configuration
+.env
+.env.*
+!.env.example
+*runtime.env
+*.pem
+*.key
+
+# Training, evaluation, and model artifacts
+data/
+datasets/
+evaluation/
+runs/
+logs/
+checkpoints/
+exports/
+models/
+weights/
+traces/
+artifacts/
+*.safetensors
+*.pt
+*.pth
+*.ckpt
+*.jsonl
+*.jsonl.gz
+*.parquet
+*.arrow
+*.csv
+*.tsv
+*.png
+*.jpg
+*.jpeg
+*.webp
+*.gif
+*.tar
+*.tar.gz
+*.zip
+
+# The README method figure is a publication asset, not a dataset payload.
+!/assets/architecture.webp
+
+# Selected release checkpoints in this Hugging Face repository only.
+!/models/
+!/models/sft/
+!/models/psd/
+!/models/sft/model-00001-of-00004.safetensors
+!/models/sft/model-00002-of-00004.safetensors
+!/models/sft/model-00003-of-00004.safetensors
+!/models/sft/model-00004-of-00004.safetensors
+!/models/psd/model-00001-of-00004.safetensors
+!/models/psd/model-00002-of-00004.safetensors
+!/models/psd/model-00003-of-00004.safetensors
+!/models/psd/model-00004-of-00004.safetensors
+
+!/datasets/EviLens/train/metadata.jsonl
+!/datasets/EviLens/train/images/**
+
+!/datasets/EviLens/test/metadata.jsonl
+!/datasets/EviLens/test/images/**

CITATION.cff

@@ -0,0 +1,68 @@
+cff-version: 1.2.0
+message: "If you use EviScene, please cite the paper below."
+type: software
+title: 'EviScene: Beyond “Is It AI?” for Agentic Image Factuality Assessment'
+version: 0.1.0
+license: Apache-2.0
+repository-code: 'https://github.com/wangzian828/EVISCENE'
+url: 'https://wangzian828.github.io/EVISCENE/'
+authors:
+  - family-names: Wang
+    given-names: ZiAn
+  - family-names: Liu
+    given-names: Ruiqi
+  - family-names: Zhang
+    given-names: Zhengbo
+  - family-names: Han
+    given-names: Yi
+  - family-names: Shen
+    given-names: Jialiang
+  - family-names: Chen
+    given-names: Ruoxin
+  - family-names: Cui
+    given-names: Manni
+  - family-names: Zhu
+    given-names: Ximo
+  - family-names: Jiang
+    given-names: Jin
+  - family-names: Liu
+    given-names: Mingzhe
+  - family-names: Wang
+    given-names: Linhao
+  - family-names: Wang
+    given-names: Wenhao
+  - family-names: Wu
+    given-names: Shu
+preferred-citation:
+  type: article
+  title: 'EviScene: Beyond "Is It AI?" for Agentic Image Factuality Assessment'
+  authors:
+    - family-names: Wang
+      given-names: ZiAn
+    - family-names: Liu
+      given-names: Ruiqi
+    - family-names: Zhang
+      given-names: Zhengbo
+    - family-names: Han
+      given-names: Yi
+    - family-names: Shen
+      given-names: Jialiang
+    - family-names: Chen
+      given-names: Ruoxin
+    - family-names: Cui
+      given-names: Manni
+    - family-names: Zhu
+      given-names: Ximo
+    - family-names: Jiang
+      given-names: Jin
+    - family-names: Liu
+      given-names: Mingzhe
+    - family-names: Wang
+      given-names: Linhao
+    - family-names: Wang
+      given-names: Wenhao
+    - family-names: Wu
+      given-names: Shu
+  year: 2026
+  journal: arXiv
+  url: 'https://arxiv.org/abs/2610.14609'

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Keep changes focused and validate behavior changes locally.
+Do not commit credentials, images, datasets, model weights, private annotations,
+or experiment logs. Do not change frozen prompts, schemas, or metric definitions
+as part of a formatting/refactoring change.
+
+```bash
+python -m pip install -e '.[dev]' -e ./training
+ruff check .
+python scripts/check_release.py
+python -m build
+python -m build training
+```
+
+CI checks code and packaging, not GPU training, external providers, or paper
+scores. Report those validations separately if performed. Test fixtures and
+internal validation suites are not included in this repository.
+Contributions are made under Apache-2.0.

LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

MANIFEST.in

@@ -0,0 +1,12 @@
+prune tests
+prune operations
+prune outputs
+prune .cache
+prune cache
+prune logs
+prune runs
+prune datasets
+prune models
+prune weights
+prune private
+global-exclude *.py[cod] *.log .env .env.* *.pem *.key

NOTICE

@@ -0,0 +1,12 @@
+EviScene
+Copyright 2026 EviScene contributors
+
+The code in this repository is licensed under Apache-2.0.
+Model weights, datasets, and the manuscript are separate artifacts; this
+license does not grant rights to them or to third-party services.
+
+The PSD implementation references Privileged Self-Distillation:
+https://www.canvas.inc/research/privileged-self-distillation
+https://github.com/essamsleiman/psd
+The reference implementation is not bundled. Python dependencies retain
+their respective licenses.

README.md

@@ -0,0 +1,385 @@
+---
+language:
+  - en
+  - zh
+tags:
+  - eviscene
+  - multimodal
+  - image-factuality
+  - agent
+  - sft
+  - distillation
+  - arxiv:2610.14609
+---
+
+<div align="center">
+
+<h1>EviScene</h1>
+
+<strong>Beyond “Is It AI?” for Agentic Image Factuality Assessment</strong>
+
+<p>Inspect the image. Find the evidence. Verify the facts.</p>
+
+<p>
+  <a href="https://wangzian828.github.io/EVISCENE/"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-website.svg" alt="Project website" height="36"></a>
+  <a href="https://arxiv.org/abs/2610.14609"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-arxiv.svg" alt="Read the paper on arXiv" height="36"></a>
+  <a href="https://huggingface.co/papers/2610.14609"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-hf-paper.svg" alt="Paper page on Hugging Face" height="36"></a>
+  <a href="https://huggingface.co/ZiAnwang/EviScene"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-models-data.svg" alt="Models and data on Hugging Face" height="36"></a>
+</p>
+
+[English](https://huggingface.co/ZiAnwang/EviScene) · [简体中文](./README_zh-CN.md)
+
+[Overview](#overview) · [Quick Start](#quick-start) · [Models & Data](#models-and-data) · [Results](#results) · [Training](#training) · [Evaluation](#evaluation) · [Citation](#citation)
+
+</div>
+
+EviScene investigates whether the facts depicted in an image are supported by
+evidence—not simply whether the image was AI-generated. Given an image, the
+agent inspects visual details, searches for external evidence, and produces a
+verdict with an evidence-grounded report. No user-written claim is required
+at inference time.
+
+This repository provides the agent runtime, tool integrations, SFT and PSD
+training utilities, and evaluation code.
+
+<a id="overview"></a>
+
+## 🔎 Overview
+
+![EviScene: an image-only agent that iteratively inspects visual details, retrieves evidence, and writes a grounded report.](assets/architecture.webp)
+
+- **Evidence-seeking investigation.** A single ReAct policy chooses visual
+  inspection, web search, image retrieval, or evidence inspection according
+  to what remains unresolved.
+- **A compact, trained policy.** Supervised fine-tuning (SFT) learns from
+  reviewed teacher trajectories. Privileged on-policy self-distillation (PSD)
+  refines selected decisions using training-time hints; the deployed student
+  does not receive those hints.
+- **Evaluation beyond the verdict.** EviLens evaluates image factuality, while
+  the evaluation code measures both classification performance and whether
+  the final report has sufficient factual grounds.
+
+<details>
+<summary><strong>Repository layout and command-line entry points</strong></summary>
+
+| Directory | Purpose |
+| --- | --- |
+| `eviscene/` | Agent runtime, tools, and evaluation |
+| `training/eviscene_training/` | SFT and PSD data preparation and training adapters |
+| `scripts/` | Dataset preparation and evaluation entry points |
+
+The installed commands are `eviscene` for inference and `eviscene-train` for
+training preparation. Python modules use the same `eviscene` and
+`eviscene_training` namespaces.
+
+</details>
+
+<a id="quick-start"></a>
+
+## 🚀 Quick Start
+
+### 1. Install
+
+Use **Python 3.11 or 3.12** in a fresh environment. The commands below assume
+Bash; on Windows, activate the environment with `.venv\Scripts\Activate.ps1`
+in PowerShell instead of `source`.
+
+```bash
+git clone https://github.com/wangzian828/EVISCENE.git
+cd EVISCENE
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[all]' -e ./training
+```
+
+For a lightweight runtime installation, use `python -m pip install -e .`; `image-retrieval` adds
+OSS image-upload support. OCR uses the Baidu API only. Installing the
+Python packages does **not** download an EviScene checkpoint or start a model
+server. GPU training dependencies are separate; see [Training](#training).
+
+### 2. Configure the model and tools
+
+Start a compatible multimodal model server with your EviScene checkpoint. It
+must expose an OpenAI-compatible chat-completions endpoint with image support.
+Set the URL and served model name to match that server; the values below are
+examples, not a hosted EviScene API.
+
+<details>
+<summary><strong>Required configuration: .env settings</strong></summary>
+
+Create a local `.env` file at the repository root:
+
+```dotenv
+# Agent policy and visual tools: your local multimodal server.
+QWEN35_LOCAL_BASE_URL=http://127.0.0.1:8000/v1
+QWEN35_LOCAL_MODEL=eviscene
+QWEN_LOCAL_API_KEY=none
+
+# Text search, image search, and reverse-image search.
+SERPER_API_KEY=YOUR_SERPER_API_KEY
+VISUAL_SEARCH_PROVIDER=serper_lens
+
+# Fetch readable webpage content through Jina Reader.
+BROWSE_FETCH_PROVIDER=jina
+JINA_API_KEY=YOUR_JINA_API_KEY
+
+# Upload images to obtain URLs usable by reverse-image search.
+IMAGE_UPLOAD_PROVIDER=oss
+OSS_ACCESS_KEY_ID=YOUR_OSS_ACCESS_KEY_ID
+OSS_ACCESS_KEY_SECRET=YOUR_OSS_ACCESS_KEY_SECRET
+OSS_ENDPOINT=YOUR_OSS_ENDPOINT
+OSS_BUCKET_NAME=YOUR_OSS_BUCKET_NAME
+
+# Baidu OCR API and fresh tool observations.
+OCR_BACKEND=baidu
+BAIDU_OCR_API_KEY=YOUR_BAIDU_OCR_API_KEY
+BAIDU_OCR_SECRET_KEY=YOUR_BAIDU_OCR_SECRET_KEY
+TOOL_CACHE_ENABLED=0
+PERCEPTION_CACHE_ENABLED=0
+```
+
+Replace the credential placeholders and use your server's API key if required.
+The `.env` file is Git-ignored. OCR sends image content to Baidu; it does not
+use a local OCR model or fall back to another provider.
+
+</details>
+
+**Model inference can be local; external search is not offline.** Search,
+webpage reading, and image hosting require network access and may incur
+provider charges. Reverse-image search sends the input image to the configured
+hosting/search services; use only images you are authorized to share.
+
+<details>
+<summary><strong>Advanced configuration: local model routing and overrides</strong></summary>
+
+Project settings use the `EVISCENE_*` prefix, for example `EVISCENE_DATA_ROOT`
+for artifact storage and `EVISCENE_ENV_FILE` for a custom environment file.
+Existing `IFV_*` settings are accepted; an explicitly set `EVISCENE_*` value
+takes precedence. Provider settings such as `QWEN35_LOCAL_MODEL` keep their names.
+
+The CLI and Python API default to `student-qwen3.5-local`; cloud model providers
+must be explicitly selected. The profile routes the policy and visual tools to the
+local model. **Webpage evidence extraction defaults to the same local policy
+model and endpoint**, with no extra extraction settings required. The
+`BROWSE_EXTRACT_PROVIDER`, `BROWSE_EXTRACT_MODEL`, `BROWSE_EXTRACT_BASE_URL`,
+`BROWSE_EXTRACT_WIRE_API`, and `BROWSE_EXTRACT_API_KEY` settings allow an explicit
+override. Existing environment or `.env` overrides still take precedence;
+remove a legacy `BROWSE_EXTRACT_PROVIDER=gemini` setting to use the local default.
+Extraction does not fall back to Gemini if local inference fails. Gemini-based
+evaluation is a separate, optional step—not part of this inference example.
+
+</details>
+
+### 3. Investigate an image
+
+Run from the repository root, replacing the image path with your own file:
+
+```bash
+eviscene path/to/image.jpg --profile student-qwen3.5-local --output-dir runs/example
+```
+
+The CLI prints the verdict, confidence, assessment, and tool-call statistics.
+It also saves the canonical trace as `runs/example/image.jpg.json` for this
+filename. To inspect the reasoning, tool observations, and final report:
+
+```bash
+python -m eviscene.render_trace_html runs/example/image.jpg.json
+```
+
+Open the generated `runs/example/image.jpg.html` in a browser. The runtime's
+`real` / `fake` verdict labels correspond to supported / refuted factuality;
+they are not AI-generation provenance labels. Model outputs are not guaranteed
+to be correct; inspect the cited evidence before relying on a conclusion.
+
+<a id="models-and-data"></a>
+
+## 📦 Models and Data
+
+> **Resources:** Code, checkpoints, dataset files, and the paper are publicly
+> available. The [Hugging Face EviScene repository](https://huggingface.co/ZiAnwang/EviScene)
+> contains code, SFT and PSD checkpoints, the EviLens
+> train/test images and metadata, and the paper PDF.
+
+| Artifact | Contents | Availability |
+| --- | --- | --- |
+| [EviScene-SFT](./models/sft) | Qwen3.5-9B policy after supervised fine-tuning | Available |
+| [EviScene-PSD](./models/psd) | Qwen3.5-9B policy after SFT and PSD | Available |
+| [EviLens train](./datasets/EviLens/train) | 8,647 images with paired metadata | Available |
+| [EviLens test](./datasets/EviLens/test) | 1,527 images with paired metadata | Available |
+
+Code is at the Hugging Face repository root. The two checkpoints belong under
+`models/sft/` and `models/psd/`; the manuscript is `paper/EviScene.pdf`.
+The dataset is in `datasets/EviLens/`, with separate `train/` and `test/` folders.
+Each model directory contains merged safetensors weights and the corresponding
+configuration, tokenizer, and processor files. The code license does not grant
+rights to model weights or third-party images; consult the model and dataset cards.
+EviLens image/metadata splits are distinct from
+the teacher trajectories and distillation targets used by the training
+pipeline. Keep the test split out of training and model selection.
+
+<a id="results"></a>
+
+## 📊 Results
+
+Selected results from the current paper snapshot on EviLens. All values are
+percentages; higher is better. These are reported paper results, not scores
+recomputed from this code snapshot.
+
+| Qwen3.5-9B setting | BAcc | Macro F1 | Supported recall | Refuted recall | SESR |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Direct prediction | 65.70 | 57.26 | 79.05 | 52.35 | 1.70 |
+| Base agent | 72.34 | 74.57 | 51.19 | 93.48 | 42.89 |
+| After SFT | 78.81 | 75.69 | 76.39 | 81.22 | 50.49 |
+| **EviScene: SFT + PSD** | **79.05** | 74.67 | 80.11 | 78.00 | **52.26** |
+
+SFT + PSD improves BAcc by **6.71 percentage points** and SESR by **9.37
+percentage points** over the same-backbone base agent. Macro F1 and class-wise
+recall are included to show the trade-offs rather than implying every metric
+improves.
+
+- **BAcc:** the mean of supported and refuted recall.
+- **Macro F1:** the mean of the two class-wise F1 scores.
+- **SESR:** Strict Evidence Sufficiency Rate—the percentage of cases with a
+  correct verdict and sufficient grounds for the decisive image-grounded fact.
+
+<a id="training"></a>
+
+## 🛠️ Training
+
+The training pipeline has two stages:
+
+1. **SFT:** audit teacher investigations, export accepted trajectories, and
+   convert them to the policy training format.
+2. **PSD:** collect on-policy training rollouts, locate failed decisions,
+   construct procedural hints, verify repairs, and train on selected
+   teacher-distribution targets alongside preservation targets.
+
+| Step | Implementation |
+| --- | --- |
+| Build reviewed SFT examples | [`build_sft_training_package.py`](scripts/trajectory/build_sft_training_package.py) |
+| Convert policy examples | [`eviscene-train convert-policy`](training/eviscene_training/policy.py) |
+| Collect on-policy rollouts | [`collect_psd_rollouts.py`](scripts/collect_psd_rollouts.py) |
+| Localize and verify training failures | [`run_psd_judge.py`](scripts/run_psd_judge.py) |
+| Construct hints and search for repairs | [`run_psd_repair_driver.py`](scripts/run_psd_repair_driver.py) |
+| Build sparse teacher targets | [`build-psd-datums`](training/eviscene_training/psd_datums.py) |
+| Apply the PSD training loss | [`psd_ms_swift.py`](training/eviscene_training/psd_ms_swift.py) |
+
+Inspect the available preparation commands with:
+
+```bash
+eviscene-train --help
+python -m scripts.trajectory.build_sft_training_package --help
+eviscene-train build-psd-datums --help
+python -m scripts.run_psd_repair_driver --help
+```
+
+The lightweight package does not install a GPU training stack or download weights.
+See the short [training settings](training/README.md) and [data interface](docs/data.md).
+The settings are paper-reported, not an independently verified reproduction run.
+
+<a id="evaluation"></a>
+
+## 🔬 Evaluation
+
+Agent inference and evidence judging are separate. The agent receives the
+image, not the reference labels or evaluator-only material. The judge reads
+the saved investigation afterward.
+
+### Run the agent
+
+With a prepared runtime case package and the model/tool configuration above:
+
+```bash
+python -m eviscene.eval.run_cases \
+  --benchmark path/to/runtime_input/cases.jsonl \
+  --profile student-qwen3.5-local \
+  --output-dir runs/eval-full \
+  --concurrency 4 \
+  --base-sampling-seed 1729
+```
+
+This saves `run_manifest.json`, `run_results.jsonl`, `summary.json`, and per-case
+traces. Runtime inputs must follow the [data interface](docs/data.md);
+an arbitrary image/label JSONL is not a drop-in replacement. The concurrency
+above is a starting point for your server, not a claim about paper hardware.
+The [recoverable rollout wrapper](scripts/run_agent_test_rollout.py) additionally
+supports bounded engineering retries for compatible test releases.
+
+### Judge saved investigations
+
+The [post-hoc judge](scripts/audit_agent_private_gold.py) requires separately
+supplied reference annotations and `GEMINI_API_KEY` or `GOOGLE_API_KEY`:
+
+```bash
+python -m scripts.audit_agent_private_gold \
+  --run-dir runs/eval-full \
+  --manifest path/to/test-manifest.jsonl \
+  --private-gold-sidecar path/to/test-private-gold.jsonl \
+  --output-dir runs/eval-full-judge \
+  --judge-model gemini-3.7-flash \
+  --thinking-level low \
+  --max-output-tokens 32768 \
+  --concurrency 4
+```
+
+This is a paid external evaluation step. The annotation paths are placeholders;
+evaluator reference material is not included in this code repository. Public
+image-level labels alone are insufficient to reproduce the evidence-quality
+audit. Preserve the dataset version, case set, model configuration, and metric
+denominator when comparing results; failed or unjudged cases are not successes.
+
+For larger runs, the [streaming judge](scripts/server/stream_agent_judges.py)
+can judge completed cases while inference continues. The
+[summary script](scripts/summarize_agent_test_evaluation.py) aggregates post-hoc
+audit records; the [metric definitions](eviscene/eval/private_gold_metrics.py) are
+included in the repository.
+
+### Tool ablations
+
+Add one flag to `eviscene.eval.run_cases` and use a separate output directory:
+
+| Variant | Flag | Removed tools |
+| --- | --- | --- |
+| No web search | `--disable-web-search` | `text_search` |
+| No image retrieval | `--disable-image-retrieval` | `text_image_search`, `reverse_image_search` |
+| No evidence inspection | `--disable-evidence-inspection` | `visit`, `compare_with_reference` |
+
+Direct visual operations and final reporting remain available in all three
+ablations. Keep the model, case set, seeds, and action budgets fixed. The exact
+tool-family mapping is defined in [`tool_ablation.py`](eviscene/orchestrator/tool_ablation.py).
+
+<a id="citation"></a>
+
+## 📝 Citation
+
+**EviScene: Beyond “Is It AI?” for Agentic Image Factuality Assessment.**
+Read the [paper on arXiv](https://arxiv.org/abs/2610.14609)
+or [download BibTeX](https://wangzian828.github.io/EVISCENE/assets/eviscene.bib).
+If you use EviScene, please cite:
+
+```bibtex
+@misc{wang2026evisceneisaiagentic,
+  title={EviScene: Beyond "Is It AI?" for Agentic Image Factuality Assessment},
+  author={ZiAn Wang and Ruiqi Liu and Zhengbo Zhang and Yi Han and
+          Jialiang Shen and Ruoxin Chen and Manni Cui and Ximo Zhu and
+          Jin Jiang and Mingzhe Liu and Linhao Wang and Wenhao Wang and Shu Wu},
+  year={2026},
+  eprint={2610.14609},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2610.14609},
+}
+```
+
+Machine-readable citation metadata is in [`CITATION.cff`](CITATION.cff).
+
+## 🤝 Contributing
+
+See [Contributing](CONTRIBUTING.md) for code and package checks, and
+[Security](SECURITY.md) for handling credentials and external tool access.
+
+## ⚖️ License
+
+Code is licensed under [Apache-2.0](LICENSE); see [NOTICE](NOTICE).
+Weights, datasets, and the manuscript have separate terms. The code license
+does not replace upstream model, image, or service licenses.

README_zh-CN.md

@@ -0,0 +1,343 @@
+<div align="center">
+
+<h1>EviScene</h1>
+
+<strong>Beyond “Is It AI?” for Agentic Image Factuality Assessment</strong>
+
+<p>观察图像，寻找证据，核实事实。</p>
+
+<p>
+  <a href="https://wangzian828.github.io/EVISCENE/"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-website.svg" alt="项目网站" height="36"></a>
+  <a href="https://arxiv.org/abs/2610.14609"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-arxiv.svg" alt="阅读 arXiv 论文" height="36"></a>
+  <a href="https://huggingface.co/papers/2610.14609"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-hf-paper.svg" alt="Hugging Face 论文页" height="36"></a>
+  <a href="https://huggingface.co/ZiAnwang/EviScene"><img src="https://huggingface.co/ZiAnwang/EviScene/resolve/main/assets/badge-models-data.svg" alt="Hugging Face 模型与数据" height="36"></a>
+</p>
+
+[English](https://huggingface.co/ZiAnwang/EviScene) · [简体中文](./README_zh-CN.md)
+
+[概览](#overview) · [快速开始](#quick-start) · [模型与数据](#models-and-data) · [实验结果](#results) · [训练](#training) · [评测](#evaluation) · [引用](#citation)
+
+</div>
+
+EviScene 关注图像所描绘的事实是否有证据支持，而不只是判断图像是否由 AI 生成。
+给定一张图像，Agent 会检查视觉细节、检索外部证据，并输出判断与基于证据的报告。
+推理时不需要用户额外提供文字断言。
+
+本仓库提供 Agent 运行时、工具集成、SFT 与 PSD 训练工具，以及评测代码。
+
+<a id="overview"></a>
+
+## 🔎 项目概览
+
+![EviScene：仅输入图像，迭代检查视觉细节、检索证据并生成有依据的报告。](assets/architecture.webp)
+
+- **主动寻找证据。** 单一 ReAct 策略根据尚未解决的问题，选择视觉检查、网页搜索、
+  图像检索或证据检查。
+- **经过训练的紧凑策略模型。** 监督微调（SFT）学习经过审核的教师轨迹；
+  特权信息辅助的在线自蒸馏（PSD）利用训练阶段的提示改进选定决策。
+  部署后的学生模型不接收这些训练提示。
+- **评测不止看最终判断。** EviLens 用于评估图像事实性，评测代码同时衡量分类表现
+  和最终报告的事实依据是否充分。
+
+<details>
+<summary><strong>代码结构与命令行入口</strong></summary>
+
+| 目录 | 用途 |
+| --- | --- |
+| `eviscene/` | Agent 运行时、工具与评测 |
+| `training/eviscene_training/` | SFT 与 PSD 数据准备及训练适配器 |
+| `scripts/` | 数据集准备和评测入口脚本 |
+
+安装后通过 `eviscene` 运行推理，通过 `eviscene-train` 进行训练数据准备。
+Python 模块对应使用 `eviscene` 与 `eviscene_training` 命名空间。
+
+</details>
+
+<a id="quick-start"></a>
+
+## 🚀 快速开始
+
+### 1. 安装
+
+请使用 **Python 3.11 或 3.12** 并创建独立环境。以下命令以 Bash 为例；
+Windows 用户可在 PowerShell 中通过 `.venv\Scripts\Activate.ps1` 激活环境，
+替代 `source` 命令。
+
+```bash
+git clone https://github.com/wangzian828/EVISCENE.git
+cd EVISCENE
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[all]' -e ./training
+```
+
+轻量运行时可用
+`python -m pip install -e .` 安装；OCR 仅调用百度 API，
+`image-retrieval` 可选依赖提供 OSS 图像上传支持。
+安装 Python 包**不会**自动下载 EviScene 权重，也不会启动模型服务。
+GPU 训练所需依赖另行配置，见[训练](#training)。
+
+### 2. 配置模型和工具
+
+使用 EviScene 权重启动兼容的多模态模型服务。服务需提供支持图像输入的
+OpenAI 兼容 chat-completions 接口。URL 和模型名称应与实际服务一致；
+下列配置仅为示例，不是可直接调用的在线 EviScene API。
+
+<details>
+<summary><strong>必需配置：.env 参数</strong></summary>
+
+在仓库根目录创建本地 `.env` 文件：
+
+```dotenv
+# Agent policy and visual tools: your local multimodal server.
+QWEN35_LOCAL_BASE_URL=http://127.0.0.1:8000/v1
+QWEN35_LOCAL_MODEL=eviscene
+QWEN_LOCAL_API_KEY=none
+
+# Text search, image search, and reverse-image search.
+SERPER_API_KEY=YOUR_SERPER_API_KEY
+VISUAL_SEARCH_PROVIDER=serper_lens
+
+# Fetch readable webpage content through Jina Reader.
+BROWSE_FETCH_PROVIDER=jina
+JINA_API_KEY=YOUR_JINA_API_KEY
+
+# Upload images to obtain URLs usable by reverse-image search.
+IMAGE_UPLOAD_PROVIDER=oss
+OSS_ACCESS_KEY_ID=YOUR_OSS_ACCESS_KEY_ID
+OSS_ACCESS_KEY_SECRET=YOUR_OSS_ACCESS_KEY_SECRET
+OSS_ENDPOINT=YOUR_OSS_ENDPOINT
+OSS_BUCKET_NAME=YOUR_OSS_BUCKET_NAME
+
+# 百度 OCR API；工具观察不使用本地缓存。
+OCR_BACKEND=baidu
+BAIDU_OCR_API_KEY=YOUR_BAIDU_OCR_API_KEY
+BAIDU_OCR_SECRET_KEY=YOUR_BAIDU_OCR_SECRET_KEY
+TOOL_CACHE_ENABLED=0
+PERCEPTION_CACHE_ENABLED=0
+```
+
+请替换凭据占位符；模型服务需要鉴权时，也应配置对应 API key。
+`.env` 已被 Git 忽略。OCR 会将图像内容发送到百度；不使用本地 OCR 模型，也不回退其他服务。
+
+</details>
+
+**模型推理可以在本地进行，但外部检索并不是离线功能。** 网页搜索、网页读取和图像
+托管需要网络访问，可能产生服务费用。反向图像搜索会将输入图像发送到配置的托管与
+搜索服务，请仅使用你有权向这些服务提供的图像。
+
+<details>
+<summary><strong>进阶配置：本地模型路由与参数覆盖</strong></summary>
+
+项目配置统一使用 `EVISCENE_*` 前缀，例如 `EVISCENE_DATA_ROOT` 指定产物存储目录，
+`EVISCENE_ENV_FILE` 指定环境配置文件。已有的 `IFV_*` 配置仍可读取；
+显式设置的 `EVISCENE_*` 值优先。`QWEN35_LOCAL_MODEL` 等服务提供方配置名保持不变。
+
+命令行和 Python 接口默认采用 `student-qwen3.5-local`，将策略模型和视觉工具路由到本地模型；云端模型须显式选择。
+**网页证据抽取默认使用同一个本地策略模型及服务地址**，无需额外设置抽取器。
+如需显式覆盖，可配置 `BROWSE_EXTRACT_PROVIDER`、`BROWSE_EXTRACT_MODEL`、
+`BROWSE_EXTRACT_BASE_URL`、`BROWSE_EXTRACT_WIRE_API` 和
+`BROWSE_EXTRACT_API_KEY`。已有环境变量或 `.env` 配置仍具有优先级；
+如之前设置过 `BROWSE_EXTRACT_PROVIDER=gemini`，需移除该设置才能使用本地默认值。
+本地抽取失败时不会自动回退到 Gemini。Gemini 评测是独立的可选步骤，
+不属于此推理示例的一部分。
+
+</details>
+
+### 3. 核查一张图像
+
+在仓库根目录运行，并将图像路径替换为你自己的文件：
+
+```bash
+eviscene path/to/image.jpg --profile student-qwen3.5-local --output-dir runs/example
+```
+
+命令行会输出判断、置信度、评估结果和工具调用统计。对于上述文件名，标准轨迹保存为
+`runs/example/image.jpg.json`。可通过以下命令查看推理、工具观察和最终报告：
+
+```bash
+python -m eviscene.render_trace_html runs/example/image.jpg.json
+```
+
+在浏览器中打开生成的 `runs/example/image.jpg.html`。
+运行时的 `real` / `fake` 分别对应事实性标签 supported / refuted，
+并不表示图像是否由 AI 生成。模型输出不保证正确，使用结论前请检查引用证据。
+
+<a id="models-and-data"></a>
+
+## 📦 模型与数据
+
+> **项目资源：** 代码、权重、数据文件和论文均已公开。
+> [Hugging Face 的 EviScene 项目仓库](https://huggingface.co/ZiAnwang/EviScene)统一存放代码、SFT 与 PSD
+> 权重、EviLens 训练集和测试集的图片与元数据，以及论文 PDF。
+
+| 项目 | 内容 | 发布状态 |
+| --- | --- | --- |
+| [EviScene-SFT](./models/sft) | 经过监督微调的 Qwen3.5-9B 策略模型 | 已发布 |
+| [EviScene-PSD](./models/psd) | 经过 SFT 和 PSD 的 Qwen3.5-9B 策略模型 | 已发布 |
+| [EviLens train](./datasets/EviLens/train) | 8,647 张图像及配套元数据 | 已发布 |
+| [EviLens test](./datasets/EviLens/test) | 1,527 张图像及配套元数据 | 已发布 |
+
+Hugging Face 仓库根目录为代码；两个权重分别放在 `models/sft/` 和 `models/psd/`，
+论文位于 `paper/EviScene.pdf`。两个模型目录均包含合并后的 safetensors 权重
+以及对应的模型配置、tokenizer 和 processor 文件。
+数据集位于同一仓库的 `datasets/EviLens/`，下设 `train/` 和 `test/`。
+代码许可证不授予模型权重或第三方图片的使用权；请参阅模型卡和数据集说明。
+EviLens 图像与元数据划分不同于训练流程所使用的教师轨迹和蒸馏目标。
+请勿将测试集用于训练或模型选择。
+
+<a id="results"></a>
+
+## 📊 实验结果
+
+以下为当前论文快照中选取的 EviLens 结果。所有数值均为百分比，越高越好。
+这些是论文报告的结果，并非使用本代码快照重新计算的分数。
+
+| Qwen3.5-9B 设置 | BAcc | Macro F1 | Supported 召回率 | Refuted 召回率 | SESR |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 直接预测 | 65.70 | 57.26 | 79.05 | 52.35 | 1.70 |
+| 基础 Agent | 72.34 | 74.57 | 51.19 | 93.48 | 42.89 |
+| SFT 后 | 78.81 | 75.69 | 76.39 | 81.22 | 50.49 |
+| **EviScene：SFT + PSD** | **79.05** | 74.67 | 80.11 | 78.00 | **52.26** |
+
+与同一骨干的基础 Agent 相比，SFT + PSD 的 BAcc 提升 **6.71 个百分点**，
+SESR 提升 **9.37 个百分点**。同时列出 Macro F1 和分类别召回率，
+以展示不同指标之间的取舍，而不是暗示所有指标都获得了提升。
+
+- **BAcc：** supported 和 refuted 两类召回率的平均值。
+- **Macro F1：** 两个类别 F1 分数的平均值。
+- **SESR：** 严格证据充分率（Strict Evidence Sufficiency Rate），即判断正确且
+  对决定性、图像关联的事实提供充分依据的 case 所占比例。
+
+<a id="training"></a>
+
+## 🛠️ 训练
+
+训练流程分为两个阶段：
+
+1. **SFT：** 审核教师核查轨迹，导出通过审核的样本，并转换为策略训练格式。
+2. **PSD：** 收集当前策���的在线训练轨迹，定位失败决策，构造程序性提示，验证修复，
+   并使用选定的教师分布目标和保留目标进行训练。
+
+| 步骤 | 实现 |
+| --- | --- |
+| 构建审核后的 SFT 样本 | [`build_sft_training_package.py`](scripts/trajectory/build_sft_training_package.py) |
+| 转换策略样本 | [`eviscene-train convert-policy`](training/eviscene_training/policy.py) |
+| 收集在线轨迹 | [`collect_psd_rollouts.py`](scripts/collect_psd_rollouts.py) |
+| 定位并验证训练失败 | [`run_psd_judge.py`](scripts/run_psd_judge.py) |
+| 构造提示并搜索修复 | [`run_psd_repair_driver.py`](scripts/run_psd_repair_driver.py) |
+| 构建稀疏教师目标 | [`build-psd-datums`](training/eviscene_training/psd_datums.py) |
+| 应用 PSD 训练损失 | [`psd_ms_swift.py`](training/eviscene_training/psd_ms_swift.py) |
+
+可用以下命令查看数据准备工具的参数：
+
+```bash
+eviscene-train --help
+python -m scripts.trajectory.build_sft_training_package --help
+eviscene-train build-psd-datums --help
+python -m scripts.run_psd_repair_driver --help
+```
+
+轻量包不安装 GPU 训练环境，也不下载权重。
+必要参数见[训练配置](training/README.md)，输入字段见[数据接口](docs/data.md)。
+配置来自论文，不代表已经独立复现了训练结果。
+
+<a id="evaluation"></a>
+
+## 🔬 评测
+
+Agent 推理与证据判定相互独立。Agent 接收图像，不接收参考标签或评测器专用材料。
+Judge 在核查轨迹保存后进行判定。
+
+### 运行 Agent
+
+准备运行时 case 包，以及上述模型与工具配置后：
+
+```bash
+python -m eviscene.eval.run_cases \
+  --benchmark path/to/runtime_input/cases.jsonl \
+  --profile student-qwen3.5-local \
+  --output-dir runs/eval-full \
+  --concurrency 4 \
+  --base-sampling-seed 1729
+```
+
+输出包括 `run_manifest.json`、`run_results.jsonl`、`summary.json` 和逐 case 轨迹。
+运行时输入须遵循[数据接口](docs/data.md)；任意图像/标签 JSONL
+不能直接替代运行时输入。上面的并发度仅是配置服务器的起点，并非论文硬件设置。
+[可恢复的 rollout 包装器](scripts/run_agent_test_rollout.py)也支持对兼容的测试发布包
+进行有界工程重试。
+
+### 判定保存的核查轨迹
+
+[事后 Judge](scripts/audit_agent_private_gold.py)需要单独提供参考标注，并配置
+`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`：
+
+```bash
+python -m scripts.audit_agent_private_gold \
+  --run-dir runs/eval-full \
+  --manifest path/to/test-manifest.jsonl \
+  --private-gold-sidecar path/to/test-private-gold.jsonl \
+  --output-dir runs/eval-full-judge \
+  --judge-model gemini-3.7-flash \
+  --thinking-level low \
+  --max-output-tokens 32768 \
+  --concurrency 4
+```
+
+这是一个需要付费调用外部服务的评测步骤。标注路径为占位符，代码仓库不包含
+评测器参考材料。仅有公开的图像级标签，不足以复现证据质量审核。
+比较结果时应保持数据集版本、case 集合、模型配置和指标分母一致；
+失败或未判定的 case 不能作为成功计算。
+
+较大规模运行可使用[流式 Judge](scripts/server/stream_agent_judges.py)，
+在推理进行的同时判定已完成的 case。
+[汇总脚本](scripts/summarize_agent_test_evaluation.py)用于聚合事后审核记录；
+仓库也包含[指标定义](eviscene/eval/private_gold_metrics.py)。
+
+### 工具消融
+
+为 `eviscene.eval.run_cases` 添加一个消融参数，并使用独立输出目录：
+
+| 变体 | 参数 | 移除的工具 |
+| --- | --- | --- |
+| 去掉网页搜索 | `--disable-web-search` | `text_search` |
+| 去掉图像检索 | `--disable-image-retrieval` | `text_image_search`、`reverse_image_search` |
+| 去掉证据检查 | `--disable-evidence-inspection` | `visit`、`compare_with_reference` |
+
+三种消融均保留直接视觉操作与最终报告能力。
+请固定模型、case 集合、种子和动作预算。
+精确的工具族划分见 [`tool_ablation.py`](eviscene/orchestrator/tool_ablation.py)。
+
+<a id="citation"></a>
+
+## 📝 引用
+
+**EviScene: Beyond “Is It AI?” for Agentic Image Factuality Assessment.**
+
+阅读 [arXiv 论文](https://arxiv.org/abs/2610.14609)，
+或[下载 BibTeX](https://wangzian828.github.io/EVISCENE/assets/eviscene.bib)。
+如使用 EviScene，请引用：
+
+```bibtex
+@misc{wang2026evisceneisaiagentic,
+  title={EviScene: Beyond "Is It AI?" for Agentic Image Factuality Assessment},
+  author={ZiAn Wang and Ruiqi Liu and Zhengbo Zhang and Yi Han and
+          Jialiang Shen and Ruoxin Chen and Manni Cui and Ximo Zhu and
+          Jin Jiang and Mingzhe Liu and Linhao Wang and Wenhao Wang and Shu Wu},
+  year={2026},
+  eprint={2610.14609},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2610.14609},
+}
+```
+
+## ⚖️ 许可证
+
+代码采用 [Apache-2.0](LICENSE)，另见 [NOTICE](NOTICE)。
+权重、数据和论文分别授权；代码许可证不替代上游模型、图像或服务���条款。
+
+开发检查见 [Contributing](CONTRIBUTING.md)，安全注意事项见 [Security](SECURITY.md)。
+仓库 CI 仅做代码与打包检查；测试和测试数据不随仓库发布。
+软件引用信息见 [CITATION.cff](CITATION.cff)。

SECURITY.md

@@ -0,0 +1,14 @@
+# Security
+
+Do not post credentials or private traces in issues. Use GitHub's private
+vulnerability-reporting channel when available; otherwise request a private
+contact without disclosing the vulnerability.
+
+This is a research runtime, not a sandbox. Treat retrieved pages and model
+outputs as untrusted. Use a restricted service account and only images you are
+authorized to send to configured search/hosting providers and the Baidu OCR API. Local model inference
+does not make external tools offline. Judge requests require explicit credentials
+and may incur charges.
+
+Rotate exposed keys at their provider. Deleting a file or rewriting Git history
+does not revoke a key. Never attach a complete environment dump to a bug report.

datasets/EviLens/.gitattributes

@@ -0,0 +1,60 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.avro filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.lz4 filter=lfs diff=lfs merge=lfs -text
+*.mds filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Audio files - uncompressed
+*.pcm filter=lfs diff=lfs merge=lfs -text
+*.sam filter=lfs diff=lfs merge=lfs -text
+*.raw filter=lfs diff=lfs merge=lfs -text
+# Audio files - compressed
+*.aac filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+# Image files - uncompressed
+*.bmp filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text
+# Image files - compressed
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+# Video files - compressed
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text

datasets/EviLens/README.md

@@ -0,0 +1,48 @@
+---
+task_categories:
+  - image-classification
+tags:
+  - eviscene
+  - image-factuality
+  - multimodal
+---
+
+# EviLens
+
+EviLens pairs images with factuality labels and metadata for image factuality
+assessment. Both splits are available in this repository.
+This is an image/metadata dataset, not SFT teacher trajectories or PSD training targets.
+
+| Split | Images / metadata records | Files |
+| --- | ---: | --- |
+| Train | 8,647 / 8,647 | `train/images/`, `train/metadata.jsonl` |
+| Test | 1,527 / 1,527 | `test/images/`, `test/metadata.jsonl` |
+
+Each metadata record provides an opaque `id`, relative `image` path, `claim`,
+supported/refuted `label`, `split`, and provenance/category fields. Resolve
+the image path relative to its split directory. Labels describe factuality,
+not whether an image was AI-generated. Keep test data out of training and model selection.
+
+Only images and paired metadata are included. Internal ID mappings, private
+evaluator gold, judge receipts, investigation traces, and credentials are excluded.
+
+## Related artifacts
+
+- [EviScene: code, models, and paper](https://huggingface.co/ZiAnwang/EviScene)
+- [SFT model](https://huggingface.co/ZiAnwang/EviScene/tree/main/models/sft)
+- [Original PSD model](https://huggingface.co/ZiAnwang/EviScene/tree/main/models/psd)
+
+## 中文说明
+
+训练集 8,647 张图片、测试集 1,527 张图片及各自逐图配套元数据均已公开。
+图片路径相对于对应的 `train/` 或 `test/` 目录；supported/refuted 表示事实性，
+不是 AI 生成来源标签。仅包含图片和元数据，不含教师轨迹、PSD 训练目标、
+私有评测材料或内部 ID 映射。测试集不可用于训练或模型选择。
+
+代码、SFT 与原版 PSD 权重、论文统一位于
+[EviScene 仓库](https://huggingface.co/ZiAnwang/EviScene)。
+
+Images remain subject to their respective source-specific rights and terms.
+Public download does not confer unrestricted reuse or redistribution rights.
+No blanket image license is assigned by this card. / 图片仍受各自来源的权利与条款约束；
+公开下载不代表可不受限制地使用或再分发，本说明不授予统一的图片许可。