akebonin/rhetoriq

# Rhetoriq: The Narrative Forensics Engine

**Rhetoriq** is an adversarial AI system designed to reverse-engineer video content. It deconstructs the **audio**, **visual**, and **linguistic** signals creators use to engineer urgency, while simultaneously exposing **logical fallacies** and hidden assumptions used to mask weak arguments.

Powered by **Google Gemini 3 (Experimental)**, Rhetoriq acts as a "Cognitive Defense" layer, visualizing both the emotional pressure and the logical integrity of modern media.

---

## ⚡ Key Features

### 1. Multimodal Signal Analysis
Rhetoriq interrogates 3 distinct signal tracks simultaneously:
* **Audio:** Music swells, BPM changes, SFX, and prosody (voice stress).
* **Visual:** Framing (close-ups vs wide), color grading, and rapid-cut frequency.
* **Linguistic:** Rhetorical devices, urgency framing, and keyword loading.

### 2. Logic Forensics (New)
Beyond simple sentiment, the engine now detects "Reasoning Leaks":
* **Reasoning Integrity Score:** A reliability metric (0.0 - 1.0) assessing the logical soundness of the argument.
* **Fallacy Detection:** Automatically flags Ad Hominem, False Causality, Strawman arguments, and Unfounded Assumptions.
* **Visual Dissonance:** Detects when the visuals contradict or misleadingly support the audio track.

### 3. The Coercion Index
A calculated "Threat Level" identifying whether content is **Informational**, **Persuasive**, or **Propagandistic**.

### 4. Forensic Player
* **Interactive Timeline:** Click any spike on the Pressure Curve or any Logic Leak tag to instantly jump the video player to that exact frame.
* **Audio Suppression:** Toggle "Disable Audio Influence" to recompute the pressure curve without the manipulative music/SFX track.

### 5. Mobile-First Architecture
* **Universal Chunking Protocol:** Supports large video uploads on mobile networks (4G/5G) by slicing files into 5MB chunks to bypass carrier limits.
* **Responsive UI:** Fully optimized charts and tooltips for vertical mobile screens.

---

## 🛠️ Prerequisites

* **Docker Desktop** (Running and updated)
* **Google Gemini API Key** (Get one [here](https://aistudio.google.com/))

---

## 🚀 Quick Start

### 1. Setup Environment

Create a file named `.env` in the root directory and add your API key:

```env
GOOGLE_API_KEY=your_actual_api_key_here

2. Build the Engine

Open your terminal in the project folder and run:

# The --no-cache flag ensures you get the latest code updates
docker build --no-cache -t rhetoriq-unified .

3. Run the Forensic Console

Start the server on port 8000:

docker run -p 8000:8000 --env-file .env rhetoriq-unified

4. Analyze

Open your browser (Desktop or Mobile) to:

http://localhost:8000

Select a File (up to 150MB) or paste a YouTube URL.
Click Analyze Signal.
Upload Phase: The system chunks and uploads your video securely.
Neural Stream: Watch the "Brain Logs" as the AI extracts signals in real-time.
Review: Analyze the Pressure Curve and Logic Leaks.

🏗️ Architecture

Rhetoriq is built as a unified, containerized application optimized for unstable networks:

Backend: Python FastAPI with Threaded Generators.
Universal API: Supports both legacy POST requests and new Chunked Uploads.
Anti-Buffering: Uses whitespace padding to force logs through mobile carrier proxies.
AI Core: Gemini 3 Flash Preview (Multimodal Reasoning).
Frontend: Vanilla JS + Chart.js (Visualization).
Async Handshake: Decouples Uploads (POST) from Streaming (GET) to prevent timeouts.
Processing: FFmpeg (Audio Extraction & Frame Sampling).

Project Structure

/rhetoriq
├── Dockerfile            # Unified build instructions
├── backend/
│   ├── api.py            # FastAPI (Chunking, Streaming, State Management)
│   ├── pipeline.py       # The Agentic Generator (Signal + Logic Analysis)
│   └── media_processor.py # FFmpeg & OpenCV wrappers
├── frontend/
│   ├── index.html        # Forensic Dashboard (Responsive)
│   ├── pressure.js       # Chunked Uploader & Charting Logic
│   └── logo.png          # Assets
└── requirements.txt      # Python dependencies

⚠️ Disclaimer

Rhetoriq is a prototype.
Analysis is probabilistic and powered by experimental AI models. It should be used for educational forensics and media literacy, not as absolute objective truth.

Troubleshooting

"Upload Failed / Entity Too Large":
Ensure you are using the latest pressure.js (Hard refresh: Ctrl+F5). The new version supports chunking to bypass size limits.
"Chart is broken/squashed":
If on Desktop, ensure your browser window isn't extremely narrow. The container is responsive but requires some height.
"Analysis Failed: 504 Timeout":
This usually means the video is too long for the Cloud Run instance. Try trimming the video to under 5 minutes.