feat: add gradio ai-image detector demo and clean repo ignores

.gitignore

@@ -0,0 +1,5 @@
+.agents/
+.codex/
+__pycache__/
+*.pyc
+.DS_Store

README.md

@@ -10,3 +10,30 @@ pinned: false
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Demo Description
+
+This Space provides a simple AI-image detection demo:
+
+1. Upload one image in the Gradio UI.
+2. The app calls an external vision-capable LLM API (OpenAI-compatible).
+3. It returns:
+   - `classification`: `REAL` / `AI_GENERATED` / `UNSURE`
+   - `confidence`: `0-100`
+   - `signals`: key visual clues
+   - `summary`: short explanation
+
+## Environment Variables (Space Secrets)
+
+Set the following in your Space settings:
+
+- `OPENAI_API_KEY` (required)
+- `OPENAI_MODEL` (optional, default: `gpt-4.1-mini`)
+- `OPENAI_BASE_URL` (optional, for OpenAI-compatible third-party services)
+
+## Local Run
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,185 @@
+import base64
+import io
+import json
+import os
+from typing import Any
+
+import gradio as gr
+from openai import OpenAI
+from PIL import Image
+
+
+SYSTEM_PROMPT = """
+You are an expert in image forensics.
+Your task is to assess whether an image is likely a real photo or AI-generated.
+
+Return strict JSON only:
+{
+  "classification": "REAL|AI_GENERATED|UNSURE",
+  "confidence": 0-100,
+  "signals": ["short signal 1", "short signal 2"],
+  "summary": "one concise paragraph"
+}
+
+Rules:
+- Base your judgment on visible artifacts and coherence.
+- Do not claim certainty unless confidence is high.
+- If evidence is mixed, use UNSURE.
+""".strip()
+
+
+def _build_client() -> OpenAI:
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        raise ValueError("Missing OPENAI_API_KEY. Please configure it in Space Secrets.")
+
+    base_url = os.getenv("OPENAI_BASE_URL", "").strip()
+    if base_url:
+        return OpenAI(api_key=api_key, base_url=base_url)
+    return OpenAI(api_key=api_key)
+
+
+def _image_to_data_url(image: Image.Image) -> str:
+    buffer = io.BytesIO()
+    image.convert("RGB").save(buffer, format="JPEG", quality=95)
+    b64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
+    return f"data:image/jpeg;base64,{b64}"
+
+
+def _extract_output_text(response: Any) -> str:
+    output_text = getattr(response, "output_text", None)
+    if isinstance(output_text, str) and output_text.strip():
+        return output_text.strip()
+
+    chunks: list[str] = []
+    for item in getattr(response, "output", []) or []:
+        for content in getattr(item, "content", []) or []:
+            text = getattr(content, "text", None)
+            if isinstance(text, str) and text.strip():
+                chunks.append(text.strip())
+    return "\n".join(chunks).strip()
+
+
+def _safe_parse_json(text: str) -> dict[str, Any] | None:
+    if not text:
+        return None
+
+    try:
+        data = json.loads(text)
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError:
+        pass
+
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        try:
+            data = json.loads(text[start : end + 1])
+            if isinstance(data, dict):
+                return data
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+def _format_result(data: dict[str, Any]) -> str:
+    classification = str(data.get("classification", "UNSURE")).upper()
+    confidence = data.get("confidence", "N/A")
+    signals = data.get("signals", [])
+    summary = str(data.get("summary", "")).strip()
+
+    if not isinstance(signals, list):
+        signals = [str(signals)]
+
+    signal_lines = "\n".join(f"- {str(s)}" for s in signals[:8]) if signals else "- (none)"
+
+    return (
+        f"### Analysis Result\n"
+        f"- **Classification**: `{classification}`\n"
+        f"- **Confidence**: `{confidence}`\n"
+        f"- **Key Signals**:\n{signal_lines}\n\n"
+        f"### Summary\n{summary or '(empty)'}\n\n"
+        f"> Note: This output is for demo and decision-support purposes only, not a professional forensic conclusion."
+    )
+
+
+def analyze_image(image: Image.Image | None, extra_instruction: str) -> tuple[str, str]:
+    if image is None:
+        return "Please upload an image first.", ""
+
+    try:
+        client = _build_client()
+        model = os.getenv("OPENAI_MODEL", "gpt-4.1-mini")
+
+        data_url = _image_to_data_url(image)
+        user_prompt = (
+            "Analyze this image and decide whether it is REAL, AI_GENERATED, or UNSURE. "
+            "Return strict JSON only."
+        )
+        if extra_instruction and extra_instruction.strip():
+            user_prompt += f"\nAdditional user instruction: {extra_instruction.strip()}"
+
+        response = client.responses.create(
+            model=model,
+            input=[
+                {"role": "system", "content": [{"type": "input_text", "text": SYSTEM_PROMPT}]},
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "input_text", "text": user_prompt},
+                        {"type": "input_image", "image_url": data_url},
+                    ],
+                },
+            ],
+        )
+
+        raw_text = _extract_output_text(response)
+        parsed = _safe_parse_json(raw_text)
+
+        if parsed is None:
+            return (
+                "The model returned non-JSON content. Please inspect the raw output and adjust the prompt or model.",
+                raw_text or "(empty response)",
+            )
+        return _format_result(parsed), json.dumps(parsed, ensure_ascii=False, indent=2)
+    except Exception as exc:
+        return f"Request failed: `{type(exc).__name__}: {exc}`", ""
+
+
+with gr.Blocks(title="AI Image Detector Demo") as demo:
+    gr.Markdown(
+        """
+# AI Image Detector (Gradio + GPT API)
+
+Upload an image and call an external vision-capable LLM API to judge whether
+the image is likely a real photo or AI-generated.
+
+Before running, configure these Hugging Face Space Secrets:
+- `OPENAI_API_KEY` (required)
+- `OPENAI_MODEL` (optional, default: `gpt-4.1-mini`)
+- `OPENAI_BASE_URL` (optional, for compatible third-party endpoints)
+"""
+    )
+
+    with gr.Row():
+        image_input = gr.Image(type="pil", label="Upload Image")
+        prompt_input = gr.Textbox(
+            label="Additional Instruction (Optional)",
+            placeholder="Example: Focus on skin texture, finger structure, and text regions.",
+            lines=6,
+        )
+
+    run_btn = gr.Button("Start Analysis", variant="primary")
+    result_md = gr.Markdown(label="Structured Result")
+    raw_json = gr.Code(label="Raw Model JSON", language="json")
+
+    run_btn.click(
+        fn=analyze_image,
+        inputs=[image_input, prompt_input],
+        outputs=[result_md, raw_json],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,3 @@
+gradio>=6.9.0
+openai>=1.40.0
+Pillow>=10.0.0