docs: add README and deployment guide for audio service

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

bitcheck-audio-service/README.md

@@ -2,32 +2,255 @@
 
 AI-powered audio verification microservice that detects AI-generated / deepfake speech using a Random Forest classifier trained on 26 spectral and MFCC audio features.
 
-## Quick Start
+## Overview
+
+BitCheck Audio Verification accepts uploaded audio files, extracts 26 handcrafted audio features, and runs them through a saved Random Forest model to estimate whether the speech is likely human-recorded or AI-generated. The service produces a risk-based verification report — not an absolute judgment.
+
+## Architecture
+
+```
+upload → validate → metadata → preprocess → quality → features → model → trust → report
+```
+
+### Pipeline Steps
+
+| Step | Module | Description |
+|------|--------|-------------|
+| 1 | `file_validator` | Extension, size, SHA256, safe save |
+| 2 | `audio_metadata_analyzer` | ffprobe/librosa metadata, AI tool markers |
+| 3 | `audio_preprocessor` | Normalize to mono 22.05kHz WAV |
+| 4 | `audio_quality_analyzer` | Silence, clipping, SNR proxy |
+| 5 | `audio_feature_extractor` | Extract exact 26 features |
+| 6 | `audio_model_loader` | Load Random Forest from joblib |
+| 7 | `audio_analyzer` | Run inference, map classes to fake/real |
+| 8 | `trust_scorer` | Weighted risk synthesis |
+| 9 | `report_builder` | Assemble final JSON report |
+
+## API Endpoints
+
+### `GET /`
+
+Service info and status.
+
+### `GET /health`
+
+Health check with model/ffmpeg availability.
+
+```json
+{
+  "status": "ok",
+  "service": "BitCheck Audio Verification API",
+  "version": "1.0.0",
+  "audio_model_found": true,
+  "ffmpeg_available": true,
+  "max_audio_duration_seconds": 30,
+  "target_sample_rate": 22050
+}
+```
+
+### `POST /verify/audio`
+
+Upload and verify an audio file.
+
+**Request:** `multipart/form-data`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `file` | file | required | Audio file to verify |
+| `max_duration_seconds` | int | 30 | Max duration to analyze |
+| `strict_duration_limit` | bool | false | Reject if longer than max |
+| `return_features` | bool | false | Include raw feature values |
+| `run_quality_analysis` | bool | true | Run quality signal analysis |
+
+**Response:** Full verification report (see example below).
+
+**Error responses:**
+- `400` — `unsupported_file_type`, `invalid_upload`, `audio_too_long`
+- `413` — `file_too_large`
+- `422` — `preprocessing_failed`
+
+### `GET /outputs/{filename}`
+
+Serve generated output files (normalized WAVs).
+
+## Supported Audio Formats
+
+- `.wav`, `.mp3`, `.m4a`, `.aac`, `.flac`, `.ogg`, `.webm`
+- Video: `.mp4`, `.mov` (audio extracted for analysis)
+
+## Model File Placement
+
+Place your trained Random Forest model in the `models/` directory:
+
+```
+models/BitcheckDeepfake.joblib
+```
+
+Fallback paths are checked in order:
+1. `models/BitcheckDeepfake.joblib` (preferred)
+2. `models/BitcheckDeepFake`
+3. `models/BitcheckDeepFake.joblib`
+4. `models/BitcheckDeepfake`
+
+The service starts and runs without the model — it returns `completed_with_warnings` with `model_found: false`.
+
+## Audio Feature Pipeline
+
+### Exact 26 Features
+
+Features are computed as the mean over time using librosa at 22050 Hz mono:
+
+1. `chroma_stft` — Mean chromagram (12 pitch classes)
+2. `rms` — Root mean square energy
+3. `spectral_centroid` — Center of mass of spectrum
+4. `spectral_bandwidth` — Spread of spectrum
+5. `rolloff` — Frequency below which 85% of energy lies
+6. `zero_crossing_rate` — Rate of sign changes
+7–26. `mfcc1`–`mfcc20` — 20 Mel-frequency cepstral coefficients
+
+### Class Mapping
+
+The Random Forest model from the training notebook maps:
+
+| Model Class | Meaning |
+|-------------|---------|
+| `0` | **FAKE** / AI-generated / deepfake |
+| `1` | **REAL** / human |
+
+For string-labeled models, known keywords are matched (`FAKE`, `REAL`, `ai_generated`, `human`, etc.). Unknown labels return raw probabilities with a warning.
+
+## Local Setup
 
 ```bash
+# Install dependencies
 pip install -r requirements.txt
+
+# Copy environment config
+cp .env.example .env
+
+# Place your model
+cp /path/to/BitcheckDeepfake.joblib models/
+
+# Run the server
 uvicorn main:app --host 0.0.0.0 --port 7860
 ```
 
-## Endpoints
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `APP_NAME` | BitCheck Audio Verification API | App name |
+| `VERSION` | 1.0.0 | App version |
+| `UPLOAD_DIR` | uploads | Upload storage |
+| `OUTPUT_DIR` | outputs | Normalized audio output |
+| `MODEL_DIR` | models | Model directory |
+| `AUDIO_MODEL_PATH` | models/BitcheckDeepfake.joblib | Primary model path |
+| `MAX_AUDIO_DURATION_SECONDS` | 30 | Max duration to analyze |
+| `MAX_AUDIO_SIZE_MB` | 25 | Max upload size |
+| `TARGET_SAMPLE_RATE` | 22050 | Target sample rate |
+| `STRICT_DURATION_LIMIT` | false | Reject over-limit audio |
+| `LOG_LEVEL` | INFO | Logging level |
+
+## Example curl Requests
+
+```bash
+# Verify an audio file
+curl -X POST http://localhost:7860/verify/audio \
+  -F "file=@voice_note.mp3" \
+  -F "max_duration_seconds=30" \
+  -F "return_features=false"
+
+# With raw features
+curl -X POST http://localhost:7860/verify/audio \
+  -F "file=@recording.wav" \
+  -F "return_features=true"
+
+# Strict duration limit
+curl -X POST http://localhost:7860/verify/audio \
+  -F "file=@long_audio.mp3" \
+  -F "strict_duration_limit=true"
+```
+
+## Example Response
+
+```json
+{
+  "verification_id": "a1b2c3d4-...",
+  "service": "BitCheck",
+  "file_type": "audio",
+  "status": "completed_with_warnings",
+  "processing_time_ms": 1234,
+  "input": {
+    "filename": "voice_note.mp3",
+    "sha256": "abc123...",
+    "extension": ".mp3",
+    "mime_type": "audio/mpeg",
+    "file_size_bytes": 123456
+  },
+  "file_validation": {"valid": true, "warnings": []},
+  "audio_metadata": {
+    "duration_seconds": 5.2,
+    "sample_rate": 44100,
+    "channels": 2,
+    "codec": "mp3",
+    "bitrate": 128000,
+    "format": "mp3",
+    "metadata_risk_score": 0.05
+  },
+  "trust": {
+    "trust_score": 78,
+    "risk_score": 0.22,
+    "risk_level": "Low Risk",
+    "decision": "approve",
+    "summary": "Overall risk signals are low."
+  },
+  "limitations": ["BitCheck audio verification is probabilistic..."],
+  "recommended_actions": ["Request original uncompressed audio..."]
+}
+```
 
-| Method | Path              | Description                |
-|--------|-------------------|----------------------------|
-| GET    | /                 | Service info               |
-| GET    | /health           | Health check               |
-| POST   | /verify/audio     | Upload and verify audio    |
+## Hugging Face Spaces Deployment
 
-## Environment
+1. Create a new Space at [huggingface.co/new-space](https://huggingface.co/new-space)
+2. Choose the **Docker** SDK
+3. Clone the Space repo and copy all files from this project
+4. Place `BitcheckDeepfake.joblib` in the `models/` directory
+5. Push to the Space — Hugging Face will build and deploy automatically
 
-Copy `.env.example` to `.env` and adjust as needed.
+The Dockerfile is pre-configured:
+- Python 3.11-slim
+- ffmpeg, libsndfile1, libgl1 pre-installed
+- Exposes port 7860
+- Runs `uvicorn main:app --host 0.0.0.0 --port 7860`
 
-## Docker
+## Testing
 
 ```bash
-docker build -t bitcheck-audio .
-docker run -p 7860:7860 bitcheck-audio
+# Run all tests
+python -m pytest tests/ -q
+
+# Run specific test file
+python -m pytest tests/test_audio_analyzer.py -q
 ```
 
-## Model
+## Limitations
+
+- BitCheck audio verification is probabilistic, not absolute proof
+- The Random Forest model depends on matching the exact 26-feature extraction pipeline used during training
+- Noisy, compressed, very short, or silent audio can reduce reliability
+- The model was trained on a specific dataset and may not generalize to all AI voice generators
+- Audio from social media apps may be compressed and harder to analyze
+- High-stakes decisions should involve human review
+
+## Future Improvements
 
-Place `BitcheckDeepfake.joblib` in the `models/` directory.
+- Stronger deep learning model (spectrogram CNN or audio transformer)
+- Audio foundation model (Wav2Vec2, HuBERT, Whisper-based)
+- SHAP-based explanation for individual feature contributions
+- Speaker consistency and voice similarity analysis
+- Robustness testing against common compression/codec pipelines
+- Multilingual and accent-robust evaluation
+- Nigerian / West African voice dataset fine-tuning
+- Integration with BitCheck image and video verification services
+- Real-time streaming audio verification
+- Dashboard and visualization UI