CoolFace
Apppublic

saiK90/image-forensics-env

sourceHugging Faceupdated 6mo agoView on Hugging Face
0likes
App README

🔬 ImageForensicsEnv

An OpenEnv environment for training RL agents to detect AI-generated images.

Built for the Meta × PyTorch OpenEnv Hackathon by Scaler School of Technology.

Overview

ImageForensicsEnv is a real-world reinforcement learning environment where an AI agent learns to distinguish AI-generated images from authentic photographs by analyzing forensic visual signals.

The agent receives a set of extracted forensic features (noise patterns, edge coherence, lighting consistency, texture realism, frequency domain analysis, structural symmetry) and must submit a verdict:

VerdictMeaning
AI_GENERATEDThe image was created by an AI model
AUTHENTICThe image is a real photograph
UNCERTAINSignals are ambiguous

Environment Design

Action Space

python
ForensicsAction(
    verdict: Literal["AI_GENERATED", "AUTHENTIC", "UNCERTAIN"],
    confidence: float,      # 0.0 – 1.0
    reasoning: str,         # optional chain-of-thought
    task_id: str,           # which task difficulty
)

Observation Space

python
ForensicsObservation(
    image_id: str,
    task_id: str,
    signals: List[SignalFeature],   # 6 forensic signals
    image_b64: str,                 # base64 JPEG for multimodal agents
    ground_truth: str | None,       # revealed after step()
    reward: float,
    done: bool,
    success: bool | None,
    feedback: str,
    step_count: int,
)

Reward Function

OutcomeReward
Correct + confidence ≥ 0.7+1.0 (+ difficulty bonus)
Correct + confidence < 0.7+0.7 (+ difficulty bonus)
UNCERTAIN (honest)+0.3
Wrong verdict0.0
Wrong + overconfident-0.1

Difficulty bonuses: Medium +0.1, Hard +0.2

Tasks

Easy — Obvious AI Images

Detect clearly AI-generated images with obvious artifacts: perfect symmetry, dreamlike backgrounds, merged fingers, halo edges.

  • —Score range: 0.0 – 1.0

Medium — Subtle AI Composites

Detect AI images that mimic photographic quality. Requires analyzing subtle texture anomalies and lighting inconsistencies.

  • —Score range: 0.0 – 1.1

Hard — Adversarial AI Images

Detect post-processed AI images designed to evade detectors. Requires frequency domain and deep pattern analysis.

  • —Score range: 0.0 – 1.2

Setup & Running

Prerequisites

  • —Python 3.10+
  • —Docker
  • —Hugging Face CLI

Local Setup

bash
git clone https://github.com/your-org/image-forensics-env
cd image-forensics-env
pip install -r server/requirements.txt

# Start the environment server
uvicorn server.app:app --host 0.0.0.0 --port 8000

Run Baseline Inference

bash
export API_BASE_URL="https://api.openai.com/v1"
export MODEL_NAME="gpt-4o-mini"
export HF_TOKEN="your_hf_token"
export ENV_BASE_URL="http://localhost:8000"

python inference.py

Run Graders

bash
python graders.py

Docker

bash
docker build -t image-forensics-env .
docker run -p 8000:8000 image-forensics-env

API Reference

EndpointMethodDescription
/GETEnvironment info
/healthGETHealth check
/resetPOSTStart new episode
/stepPOSTSubmit action
/stateGETEpisode metadata
/tasksGETList all tasks

Example Usage

python
from client import ImageForensicsEnv
from models import ForensicsAction

with ImageForensicsEnv(base_url="https://your-space.hf.space") as env:
    # Start episode
    obs = env.reset()
    print(f"Task: {obs.task_id}")
    for signal in obs.signals:
        print(f"  {signal.name}: {signal.score:.3f} — {signal.description}")

    # Submit verdict
    result = env.step(ForensicsAction(
        verdict="AI_GENERATED",
        confidence=0.87,
        task_id=obs.task_id,
        reasoning="High symmetry score and anomalous frequency peaks",
    ))
    print(f"Reward: {result.reward} | Ground truth: {result.ground_truth}")

Project Structure

image_forensics_env/
├── models.py              # Typed Action + Observation models
├── client.py              # Python client for connecting to env
├── inference.py           # Baseline LLM agent (hackathon required)
├── graders.py             # Automated task graders
├── openenv.yaml           # OpenEnv spec config
├── Dockerfile             # Container for HF Spaces
├── README.md              # This file
└── server/
    ├── app.py             # FastAPI server
    ├── environment.py     # Core environment logic
    └── requirements.txt   # Dependencies

Environment Variables

VariableDescriptionRequired
API_BASE_URLLLM API endpoint (OpenAI-compatible)Yes
MODEL_NAMEModel identifierYes
HF_TOKENHugging Face API tokenYes
ENV_BASE_URLRunning environment URLNo (default: localhost:8000)

Hackathon Submission

  • —Event: Meta × PyTorch OpenEnv Hackathon — Scaler School of Technology
  • —Deadline: April 8, 2026, 11:59 PM IST
  • —Track: Real-world OpenEnv Environment
  • —Framework: OpenEnv + FastAPI + Pydantic