Metadata-Version: 2.4
Name: pixjury
Version: 0.4.0
Summary: Extensible image quality evaluation engine with pluggable reviewers
Project-URL: Homepage, https://github.com/Sunhill666/PixJury
Project-URL: Documentation, https://github.com/Sunhill666/PixJury/tree/main/docs/en
Project-URL: Repository, https://github.com/Sunhill666/PixJury
Project-URL: Issues, https://github.com/Sunhill666/PixJury/issues
Author: Baihao You
License-Expression: MIT
License-File: LICENSE
Keywords: computer-vision,image-quality,image-quality-assessment,reviewer,visual-evaluation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: accelerate>=1.14.0
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: qwen-vl-utils[decord]>=0.0.14
Requires-Dist: torch>=2.12.0
Requires-Dist: torchvision>=0.27.0
Requires-Dist: transformers>=5.12.1
Description-Content-Type: text/markdown

# PixJury

[中文文档](README.zh-CN.md)

PixJury is a Python SDK and CLI reviewer engine for visual quality evaluation.

![PixJury banner](docs/assets/banner.png)

<p align="center">
  <img alt="Python 3.12+" src="https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white">
  <img alt="Version 0.4.0" src="https://img.shields.io/badge/version-0.4.0-6C5CE7">
  <img alt="SDK" src="https://img.shields.io/badge/SDK-Python-2D3436">
  <img alt="CLI" src="https://img.shields.io/badge/CLI-JSON-00B894">
  <img alt="Reviewer Engine" src="https://img.shields.io/badge/Reviewer-Engine-E17055">
  <img alt="Project status: design phase" src="https://img.shields.io/badge/status-design%20phase-FDCB6E">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-A3BE8C"></a>
</p>

## ⚖️ What is PixJury

PixJury runs one or more reviewers against local images and returns each reviewer's original structured result. It supports deterministic metrics, model-backed reviewers, resource reuse, and reviewer extensions without combining reviewer output into a `final_score`.

Platform-level orchestration should be implemented outside PixJury.

## ✨ Core Features

- Python SDK and JSON-oriented CLI
- `score`, `compare`, and `perceive` operations
- Built-in Mock, PSNR, SSIM, and Q-Insight reviewers
- Reviewer-owned prompts with version and SHA-256 provenance
- Explicit model resource preload, pin, unload, and status APIs
- `none`, `keep`, and OOM-aware `lru` resource cache policies
- Pydantic request and result schemas

## 📦 Installation

PixJury requires Python 3.12 or later.

```bash
pip install pixjury
```

For source installation or local development, use `uv sync` from the repository root.

Q-Insight uses FlashAttention 2 and requires `flash-attn` on a supported CUDA system. Install it separately by following the official [FlashAttention instructions](https://github.com/dao-ailab/flash-attention#installation-and-features).

## 🐍 QuickStart: Python SDK

```python
from pixjury import PixJury

with PixJury(default_reviewers=["mock"]) as jury:
    result = jury.score(
        {
            "request_id": "quickstart",
            "image": {"path": "/path/to/image.png"},
        }
    )

print(result.model_dump_json(indent=2))
```

Request image paths must point to readable local image files.

## ⌨️ QuickStart: CLI

Create a request:

```json
{
  "request_id": "quickstart",
  "image": {"path": "/path/to/image.png"},
  "reviewers": ["mock"]
}
```

Then run it from a file or standard input:

```bash
uv run pixjury score --request request.json
uv run pixjury score --request - < request.json
```

See [`examples/`](examples/) for request JSON templates.

## 🧑‍⚖️ Built-in Reviewers

| Reviewer | Operations | Reference requirement |
| --- | --- | --- |
| `mock` | `score`, `compare`, `perceive` | None |
| `psnr` | `score` | Required |
| `ssim` | `score` | Required |
| `q_insight` | `score`, `compare`, `perceive` | Required for `compare` |

Q-Insight model files are downloaded by Transformers when first needed unless a local or offline configuration is provided.

## 🧩 Basic Concepts

- A **Reviewer** implements one or more visual evaluation operations.
- An **Operation** is `score`, `compare`, or `perceive`.
- A **Resource** is a reviewer-owned model or other loaded dependency.
- A **JuryResult** contains one original `ReviewerResult` per selected reviewer.

PixJury does not fuse reviewer outputs or generate a final score.

## 📚 Documentation

- [Core concepts](docs/en/concepts.md)
- [Lifecycle and resource caching](docs/en/lifecycle.md)
- [Resource status model](docs/en/resource-status.md)
- [Prompt management](docs/en/prompt-management.md)
- [Developing reviewers](docs/en/reviewers.md)
- [Q-Insight](docs/en/q-insight.md)
- [CLI guide](docs/en/cli.md)
- [Python SDK guide](docs/en/sdk.md)
- [Examples](docs/en/examples.md)

## 🛠️ Development

```bash
uv run ruff check .
uv run pytest
uv build
```

## 📄 License

PixJury is released under the [MIT License](LICENSE).
