---
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)

```bash
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:

```bash
# 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):

```bash
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:

```bash
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.