README.md

metadata

title: AISPY
emoji: 🕵️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

AISPY on Hugging Face Spaces (Docker)

This repository can be deployed as a Docker Space on Hugging Face.

Web app overview

The app now runs as a proper authenticated Flask web application with:

• email/password sign-up and login
• private, session-based dashboard
• saved analysis history per user
• server-rendered forensic reports
• password reset flow
• role-based admin dashboard
• report export as Markdown and JSON
• SQLite storage for users and reports

1) Create the Space

1. Go to Hugging Face → New Space.
2. Choose:
   • SDK: Docker
   • Visibility: your choice (public/private)
3. Create the Space and push this repository code.

2) Required Space Secrets

Open your Space settings → Variables and secrets and add:

• GROQ_API_KEY (required)
• TAVILY_API_KEY (required for web search)
• LANGCHAIN_API_KEY (optional, if LangSmith tracing is enabled)
• LANGCHAIN_TRACING_V2 (optional, usually true)
• LANGCHAIN_PROJECT (optional)
• SECRET_KEY (recommended for Flask sessions)
• AISPY_ADMIN_EMAILS (optional comma-separated admin emails)

If your app uses additional providers, add those keys too.

3) Build & Run Behavior

• Dockerfile installs system packages (ffmpeg, tesseract-ocr, libgl1) needed by media/CV stack.
• Python dependencies are installed from requirements-cpu.txt.
• requirements-cpu.txt points pip to the official CPU-only PyTorch wheel index.
• App runs with:
  • gunicorn app:app --bind 0.0.0.0:${PORT}
• Hugging Face provides PORT (default 7860), matching Space config.

4) Local Test (Optional)

docker build -t aispy:local .
docker run --rm -it -p 7860:7860 \
  -e GROQ_API_KEY=your_key \
  -e TAVILY_API_KEY=your_key \
  aispy:local

Then open: http://localhost:7860

5) Notes

• First build can take time due to ML dependencies.
• If you hit memory limits on free CPU Spaces, reduce model size or move to upgraded hardware.
• Keep secrets only in Space settings (not in committed .env files).

Provenance & Forensics (quick guide)

When triaging media, preserve originals and collect metadata before any transformations. The repository includes lightweight helpers in core/tools.py:

• compute_checksum(path) — returns a SHA256 hex digest for a file.
• run_ffprobe(path) — runs ffprobe and returns stream/container metadata (or an error if ffprobe is missing).
• preserve_original_copy(src, dest_dir) — copies the original file into dest_dir and writes a companion .metadata.json containing checksum and ffprobe output.
• extract_audio_with_ffmpeg(src, out.wav) — extracts audio to a WAV and returns ffmpeg stderr/stdout for debugging silent or missing tracks.

Helpful shell commands for local triage:

# Inspect container and stream info
ffprobe -v error -show_format -show_streams -print_format json input.mp4 | jq .

# Extract audio (16 kHz mono WAV)
ffmpeg -y -i input.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 out.wav

# Compute SHA256
sha256sum input.mp4

Python usage example (within the virtualenv):

python -c "from core.tools import preserve_original_copy, extract_audio_with_ffmpeg; print(preserve_original_copy('input.mp4','collected')); print(extract_audio_with_ffmpeg('input.mp4','collected/input.wav'))"

If ffmpeg / ffprobe are not installed in your environment, install them via your package manager (e.g., apt install ffmpeg) or ensure your Docker image includes the packages (the provided Dockerfile already installs them).

Collecting the original file and related metadata is essential for sensor-level forensic checks (PRNU, demosaic patterns) and increases confidence for authenticity assessments.

Local finetuned models

By default this repo will NOT eagerly load local finetuned model directories (for example under face_v2_enhanced (1) or omni_detector_v1). To enable loading local models on start set the environment variable:

export ALLOW_LOCAL_MODELS=1

Only enable this if you have installed the necessary Python packages (torch, transformers) and have sufficient CPU memory. Otherwise the app will prefer hosted inference (Hugging Face) when HUGGINGFACE_API_KEY is present.