Metadata-Version: 2.4
Name: pixjury
Version: 0.3.1
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
Provides-Extra: q-insight-flash
Requires-Dist: flash-attn>=2.8.3.post1; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'q-insight-flash'
Requires-Dist: ninja>=1.13.0; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'q-insight-flash'
Requires-Dist: packaging>=26.2; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'q-insight-flash'
Requires-Dist: psutil>=7.2.2; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'q-insight-flash'
Requires-Dist: setuptools>=81.0.0; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'q-insight-flash'
Requires-Dist: wheel>=0.47.0; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'q-insight-flash'
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.3.1" src="https://img.shields.io/badge/version-0.3.1-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
uv sync
```

To enable Q-Insight with FlashAttention 2 on a supported CUDA system:

```bash
uv sync --extra q-insight-flash
```

## 🐍 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).
