Complete battle mode+deal negotiation added

.env.example

@@ -1,31 +0,0 @@
-# Copy to .env locally; use HF Space Secrets in deployment.
-# Frontend never reads these — backend model_router only.
-APP_ENV=development
-MAX_ROUNDS=6
-
-DEFAULT_MODEL_MODE=premium_nvidia
-
-# NVIDIA Nemotron 3 Nano Omni 30B-A3B (primary premium model — backend-only API)
-NVIDIA_API_KEY=
-NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
-NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
-
-# OpenBMB MiniCPM models
-OPENBMB_API_KEY=
-OPENBMB_BASE_URL=
-MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
-MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
-MINICPM_TEXT_BACKEND=api_or_local
-MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
-
-# Hugging Face (model download / Space)
-HF_TOKEN=
-
-# Audio transcription fallback only (not the primary judge)
-WHISPER_FALLBACK_ENABLED=true
-WHISPER_MODEL_SIZE=tiny
-
-# Feature flags
-ENABLE_DECK_CRITIQUE=true
-ENABLE_DEAL_BATTLE=true
-ENABLE_VOICE_MODE=true

.gitignore

@@ -41,3 +41,13 @@ models/
 *.gguf
 *.wav
 *.mp3
+
+# Local-only folders
+docs/
+scripts/
+tests/
+
+# Environment files
+.env
+.env.*
+.env.example

docs/BACKEND_API.md

@@ -1,393 +0,0 @@
-# PitchFight AI — Backend API Reference
-
-## 1. Important Note About Gradio Internal Endpoints
-
-When you run `python app.py` and open FastAPI/Swagger (`/docs`), you will see **many routes** that are **not** PitchFight AI product APIs, for example:
-
-- `/gradio_api/*` — config, queue, upload, streaming
-- `/queue/*` — Gradio job queue
-- `/upload` — Gradio file upload
-- `/static/*`, `/assets/*`, `/theme.css` — Gradio UI assets
-- Login, monitoring, and other framework runtime routes
-
-These are **automatically registered by Gradio** and are required for Gradio Server to work on Hugging Face Spaces. **Do not delete them.**
-
-**PitchFight AI’s real backend endpoints** are namespaced under **`/api/...`** plus **`/health`** and **`/`**.
-
-> Judge this project’s API design by `/api/*` and this document — not by the long Gradio-generated OpenAPI list.
-
----
-
-## 2. Backend Design Principles
-
-| Principle | Detail |
-|---|---|
-| **Frontend never calls model providers** | No NVIDIA/OpenBMB keys in browser JS; only `/api/*` + `/health` |
-| **Backend owns model routing** | `core/model_router.py` (Phase 2+) — default `premium_nvidia` (Nemotron Omni 30B-A3B) |
-| **Backend owns session state** | `core/session_manager.py` |
-| **Backend owns scoring** | `core/scoring_engine.py` |
-| **Frontend sends actions, renders results** | Custom HTML/CSS/JS + `fetch()` |
-| **Secrets in env only** | `.env` locally, HF Space Secrets in deployment — never in frontend or repo |
-
-> **Strategy:** High-demo sponsor-model build. Off-the-Grid is not targeted. faster-whisper is transcription fallback only; OpenBMB MiniCPM modes are secondary/fallback paths.
-
-Shared logic lives in **`core/api_handlers.py`**. Both REST routes (`/api/...`) and Gradio `@app.api` wrappers call the same handler functions.
-
----
-
-## 3. Clean Project Endpoints
-
-| Method | Path | Status | Purpose |
-|---|---|---|---|
-| `GET` | `/health` | **Implemented** | App health check |
-| `GET` | `/` | **Implemented** | Serve custom frontend |
-| `GET` | `/api/model-health` | **Implemented** (Phase 2) | Model provider config status (no keys) |
-| `POST` | `/api/load-sample` | **Implemented** | Load EventRadar AI demo startup |
-| `POST` | `/api/start-session` | **Implemented** | Start Pitch Battle session |
-| `POST` | `/api/chat-round` | **Implemented** | Send user answer, get AI pushback |
-| `POST` | `/api/end-battle` | **Implemented** | Generate scorecard |
-| `POST` | `/api/reset-session` | **Implemented** | Delete session |
-| `POST` | `/api/voice-pitch` | **Placeholder** | Voice pitch (reserved) |
-| `POST` | `/api/start-deal-session` | **Placeholder** | Deal Battle (reserved) |
-| `POST` | `/api/deck-critique` | **Placeholder** | Pitch deck critique (reserved) |
-
-### Gradio compatibility wrappers (same handlers)
-
-| Gradio `@app.api` name | Handler |
-|---|---|
-| `load_sample` | `handle_load_sample()` |
-| `start_session` | `handle_start_session()` |
-| `chat_round` | `handle_chat_round()` |
-| `end_battle` | `handle_end_battle()` |
-| `reset_session` | `handle_reset_session()` |
-
----
-
-## 4. Endpoint Details
-
-### `GET /health`
-
-**Purpose:** Verify the server is running.
-
-**Response:**
-
-```json
-{
-  "status": "ok",
-  "app": "PitchFight AI",
-  "version": "0.1.0"
-}
-```
-
----
-
-### `GET /api/model-health`
-
-**Purpose:** Return model provider configuration status. API keys are **never** included in the response.
-
-**Response:**
-
-```json
-{
-  "default_mode": "premium_nvidia",
-  "supported_modes": ["openbmb_omni", "premium_nvidia", "tiny_minicpm", "vision_deck", "whisper_fallback"],
-  "providers": {
-    "nvidia": {
-      "provider": "nvidia",
-      "configured": true,
-      "base_url": "https://integrate.api.nvidia.com/v1",
-      "model": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
-      "api_key_present": true,
-      "message": "NVIDIA client ready"
-    },
-    "minicpm": { "status": "not_configured", "provider": "openbmb", "message": "MiniCPM integration planned for Phase 9" },
-    "vision":  { "status": "not_configured", "provider": "openbmb", "message": "Vision/deck critique planned for Phase 10" },
-    "transcription": { "status": "not_configured", "provider": "local", "message": "faster-whisper fallback planned for Phase 7" }
-  }
-}
-```
-
----
-
-### `GET /`
-
-**Purpose:** Serve `frontend/index.html` (custom battle arena UI).
-
-Static assets: `/frontend/styles.css`, `/frontend/script.js`, `/frontend/assets/*`
-
----
-
-### `POST /api/load-sample`
-
-**Purpose:** Load the EventRadar AI sample startup into the form.
-
-**Request body:** none
-
-**Response:**
-
-```json
-{
-  "startup": {
-    "name": "EventRadar AI",
-    "problem": "...",
-    "target_users": "...",
-    "solution": "...",
-    "why_ai": "...",
-    "competitors": "...",
-    "traction": "...",
-    "ask": "..."
-  }
-}
-```
-
----
-
-### `POST /api/start-session`
-
-**Purpose:** Start a new Pitch Battle session.
-
-**Request body:**
-
-```json
-{
-  "mode": "pitch_battle",
-  "persona": "hackathon_judge",
-  "difficulty": "high",
-  "input_mode": "text",
-  "model_mode": "premium_nvidia",
-  "startup": {
-    "name": "EventRadar AI",
-    "problem": "...",
-    "target_users": "...",
-    "solution": "...",
-    "why_ai": "...",
-    "competitors": "...",
-    "traction": "...",
-    "ask": "..."
-  }
-}
-```
-
-**Response:**
-
-```json
-{
-  "session_id": "uuid",
-  "round": 1,
-  "pressure_level": "Medium",
-  "attack_tag": "User Pain",
-  "ai_message": "Students already lurk in WhatsApp groups..."
-}
-```
-
----
-
-### `POST /api/chat-round`
-
-**Purpose:** Submit one founder answer and receive the next AI challenge.
-
-**Request body:**
-
-```json
-{
-  "session_id": "uuid",
-  "user_message": "We use AI to rank events for students."
-}
-```
-
-**Response:**
-
-```json
-{
-  "session_id": "uuid",
-  "round": 2,
-  "pressure_level": "Medium",
-  "attack_tag": "Demo Clarity",
-  "ai_message": "If I only saw a 30-second demo..."
-}
-```
-
----
-
-### `POST /api/end-battle`
-
-**Purpose:** End the battle and return a scorecard.
-
-**Request body:**
-
-```json
-{
-  "session_id": "uuid"
-}
-```
-
-**Response:**
-
-```json
-{
-  "overall": 68,
-  "scores": {
-    "clarity": {
-      "score": 64,
-      "reason": "...",
-      "quote": "..."
-    }
-  },
-  "best_answer": "...",
-  "weakest_answer": "...",
-  "improved_answer": "...",
-  "improved_pitch": "...",
-  "top_3_questions": ["...", "...", "..."]
-}
-```
-
----
-
-### `POST /api/reset-session`
-
-**Purpose:** Delete a session.
-
-**Request body:**
-
-```json
-{
-  "session_id": "uuid"
-}
-```
-
-**Response:**
-
-```json
-{
-  "status": "reset"
-}
-```
-
----
-
-### `POST /api/voice-pitch` (placeholder)
-
-**Planned flow (Phase 7):** audio → Nemotron Omni (primary) → pitch context + opening question. Fallback: faster-whisper transcription → Nemotron or MiniCPM5-1B text path.
-
-**Response (current):**
-
-```json
-{
-  "status": "not_implemented",
-  "message": "Voice Mode endpoint is reserved. Primary path: Nemotron Omni voice; fallback: faster-whisper transcription."
-}
-```
-
----
-
-### `POST /api/start-deal-session` (placeholder)
-
-**Response:**
-
-```json
-{
-  "status": "not_implemented",
-  "message": "Deal Battle endpoint is reserved and will be connected in a later phase."
-}
-```
-
----
-
-### `POST /api/deck-critique` (placeholder)
-
-**Response:**
-
-```json
-{
-  "status": "not_implemented",
-  "message": "Deck critique endpoint is reserved and will be connected after MiniCPM-V vision integration."
-}
-```
-
----
-
-## 5. Endpoint Flow Diagrams
-
-### Pitch Battle flow
-
-```mermaid
-flowchart TD
-    A[Frontend UI] --> B[/api/start-session]
-    B --> C[Session Manager]
-    C --> D[Persona Builder]
-    D --> E[Attack Tag Selector]
-    E --> F[Model Router]
-    F --> G[AI Response]
-    G --> A
-```
-
-### Scorecard flow
-
-```mermaid
-flowchart TD
-    A[Frontend UI] --> B[/api/end-battle]
-    B --> C[Session Manager]
-    C --> D[Scoring Engine]
-    D --> E[Model Router]
-    E --> F[JSON Parser]
-    F --> G[Scorecard Response]
-    G --> A
-```
-
----
-
-## 6. Why Swagger Shows Many Routes
-
-Gradio Server is built on FastAPI. When the app launches, Gradio **automatically registers** internal endpoints for:
-
-- App configuration (`/gradio_api/config`, `/gradio_api/info`)
-- Request queueing (`/queue/join`, `/queue/data`)
-- File uploads (`/upload`)
-- Static assets and themes
-- Streaming, login checks, and monitoring
-
-These are **framework runtime routes**, not hand-written PitchFight product APIs. They exist so Gradio can host the app on Hugging Face Spaces with queuing, MCP, and ZeroGPU support.
-
-**You do not call or maintain those routes manually.** The custom frontend uses only `/api/*` and `/health`.
-
----
-
-## 7. Final API Contract — Quick Examples
-
-### Load sample
-
-```bash
-curl -X POST http://127.0.0.1:7860/api/load-sample
-```
-
-### Start session
-
-```bash
-curl -X POST http://127.0.0.1:7860/api/start-session \
-  -H "Content-Type: application/json" \
-  -d '{"mode":"pitch_battle","persona":"hackathon_judge","difficulty":"high","input_mode":"text","model_mode":"premium_nvidia","startup":{"name":"Test","problem":"p","target_users":"u","solution":"s","why_ai":"a","competitors":"c","traction":"t","ask":"a"}}'
-```
-
-### Chat round
-
-```bash
-curl -X POST http://127.0.0.1:7860/api/chat-round \
-  -H "Content-Type: application/json" \
-  -d '{"session_id":"<uuid>","user_message":"We use AI for ranking."}'
-```
-
-### End battle
-
-```bash
-curl -X POST http://127.0.0.1:7860/api/end-battle \
-  -H "Content-Type: application/json" \
-  -d '{"session_id":"<uuid>"}'
-```
-
-### Reset session
-
-```bash
-curl -X POST http://127.0.0.1:7860/api/reset-session \
-  -H "Content-Type: application/json" \
-  -d '{"session_id":"<uuid>"}'
-```

docs/CLAUDE_PROJECT_CONTEXT.md

@@ -1,299 +0,0 @@
-# PitchFight AI — Claude Project Context
-
-> **Read this file before starting any implementation phase.**
-> Generated after full repository inspection on 2026-06-08.
-
----
-
-## 1. Project Summary
-
-PitchFight AI is a voice-and-text AI sparring arena for student founders built for the Hugging Face **Build Small Hackathon** (Backyard AI track). The core use case: let founders get grilled by a realistic AI judge before they face real judges, mentors, investors, or sponsors. The AI does not give advice — it applies pressure, remembers prior answers, attacks vague claims, and scores the conversation.
-
-The project runs on **Gradio Server** (not default Gradio UI), hosts a **custom HTML/CSS/JS frontend**, and exposes a clean **`/api/*` REST layer**. All AI model calls are strictly backend-only. The frontend never touches any model provider API.
-
----
-
-## 2. Current Strategy
-
-| Decision | Value |
-|---|---|
-| Hackathon track | Backyard AI |
-| Off-the-Grid | **Not targeted** — intentional |
-| Model cap | ≤32B parameters (all models comply) |
-| Default model mode | `premium_nvidia` |
-| Primary judge model | NVIDIA Nemotron 3 Nano Omni 30B-A3B |
-| Frontend model calls | **Never** — frontend calls `/api/*` only |
-| API keys | Backend `.env` locally; HF Space Secrets in deployment |
-| Target prizes | Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, Field Notes, Tiny Titan |
-| Current build status | Phase 1 complete (mock APIs running) |
-
----
-
-## 3. Current Model Stack
-
-| Role | Model | Mode Key | Status |
-|---|---|---|---|
-| Primary judge (text, voice, scoring, rewrites) | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | `premium_nvidia` | **Live (Phase 2)** — client tested |
-| OpenBMB omni mode | `openbmb/MiniCPM-o-4_5` | `openbmb_omni` | Stub — Phase 9 |
-| Tiny fallback / Tiny Mode | `openbmb/MiniCPM5-1B` | `tiny_minicpm` | Stub — Phase 9 |
-| Pitch deck critique | `openbmb/MiniCPM-V-4.6` | `vision_deck` | Stub — Phase 10 |
-| Audio transcription fallback | `faster-whisper` (tiny or base) | `whisper_fallback` | Stub — Phase 7 |
-
-> **Reasoning model note:** `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` uses tokens for an internal chain-of-thought before writing `message.content`. Confirmed token defaults: opponent=500, scorecard=2000, rewrite=800.
-
-NVIDIA endpoint base URL: `https://integrate.api.nvidia.com/v1`
-
-All model calls must go through `core/model_router.py` → individual client files. No model provider URL or key must ever appear in frontend code.
-
----
-
-## 4. Backend Architecture
-
-```
-app.py                        ← Gradio Server entrypoint
-  /health                     ← health check
-  /                           ← serves frontend/index.html
-  /api/load-sample            ← REST endpoint
-  /api/start-session          ← REST endpoint
-  /api/chat-round             ← REST endpoint
-  /api/end-battle             ← REST endpoint
-  /api/reset-session          ← REST endpoint
-  /api/voice-pitch            ← placeholder (Phase 7)
-  /api/start-deal-session     ← placeholder (Phase 8)
-  /api/deck-critique          ← placeholder (Phase 10)
-  @app.api wrappers           ← same handlers, Gradio client compat
-
-core/api_handlers.py          ← shared handler logic (REST + Gradio route)
-core/session_manager.py       ← in-memory session store (SESSIONS dict)
-core/persona_builder.py       ← builds system prompt per persona + startup
-core/attack_tags.py           ← attack tag taxonomy, round-based selection
-core/scoring_engine.py        ← mock scorecard (Phase 1); real model call planned Phase 5
-core/feedback_generator.py    ← mock rewrite logic (Phase 1); model call planned Phase 5
-core/json_utils.py            ← JSON extraction + safe_json_parse + fallback_scorecard()
-core/local_text_model.py      ← stub placeholder (Phase 1 only)
-core/voice_transcriber.py     ← stub placeholder (Phase 7)
-core/samples.py               ← get_sample_startup() (EventRadar AI)
-
-config/personas.json          ← persona metadata (ids, names, focus areas)
-config/attack_tags.json       ← attack tag reference (not yet used in code — code uses attack_tags.py)
-config/pitch_rubric.json      ← 6 dimensions + weights
-config/sample_startups.json   ← sample startup data
-
-ADDED in Phase 2:
-  model_router.py             ← routes tasks; premium_nvidia live; others stub
-  nvidia_client.py            ← NVIDIA Nemotron client; live, tested
-  minicpm_client.py           ← health_check stub (Phase 9)
-  vision_client.py            ← health_check stub (Phase 10)
-  transcription_client.py     ← health_check stub (Phase 7)
-```
-
----
-
-## 5. Frontend Architecture
-
-File: `frontend/script.js`
-
-The frontend uses **`fetch()`** calls exclusively to `/api/*` backend routes. No model provider URLs or API keys exist in any frontend file. This is verified and correct.
-
-Key functions:
-- `apiPost(path, body)` — all API calls go through this helper
-- `loadSample()` → `POST /api/load-sample`
-- `startSession()` → `POST /api/start-session` (sends `model_mode: "premium_nvidia"`)
-- `sendMessage()` → `POST /api/chat-round`
-- `endBattle()` → `POST /api/end-battle`
-- `resetBattle()` → `POST /api/reset-session`
-- `renderScorecard(data)` — renders overall score, bars, rewrites, questions
-
-The `boot()` function calls `GET /health` on page load for backend availability check.
-
-Static assets served at `/frontend/*` via Gradio StaticFiles mount.
-
----
-
-## 6. Real Product API Endpoints
-
-These are the only endpoints that matter for PitchFight as a product. Ignore Gradio-internal Swagger routes.
-
-| Method | Path | Status | Phase |
-|---|---|---|---|
-| GET | `/health` | Live (mock-free) | Phase 1 |
-| GET | `/` | Live | Phase 1 |
-| POST | `/api/load-sample` | Live (real config data) | Phase 1 |
-| POST | `/api/start-session` | Live (mock AI response) | Phase 1 |
-| POST | `/api/chat-round` | Live (mock AI response) | Phase 1 |
-| POST | `/api/end-battle` | Live (mock scorecard) | Phase 1 |
-| POST | `/api/reset-session` | Live | Phase 1 |
-| POST | `/api/voice-pitch` | Placeholder 501 | Phase 7 |
-| POST | `/api/start-deal-session` | Placeholder 501 | Phase 8 |
-| POST | `/api/deck-critique` | Placeholder 501 | Phase 10 |
-
-Gradio internal routes (`/gradio_api/*`, `/queue/*`, `/upload`, `/static/*`) are framework runtime routes registered automatically. **Do not call or maintain them as product APIs.**
-
----
-
-## 7. Existing File Structure
-
-```
-Pitchfight/
-├── app.py                         ← Gradio Server + REST endpoints
-├── .env.example                   ← env template (complete, correct)
-├── .gitignore                     ← must include .env
-├── README.md                      ← HF Spaces metadata + project overview
-├── core/
-│   ├── __init__.py
-│   ├── api_handlers.py            ← shared handler logic
-│   ├── attack_tags.py             ← tag taxonomy + selector
-│   ├── feedback_generator.py      ← mock rewrite (Phase 1)
-│   ├── json_utils.py              ← JSON parse + fallback
-│   ├── local_text_model.py        ← stub (Phase 1)
-│   ├── persona_builder.py         ← system prompt builder
-│   ├── samples.py                 ← EventRadar AI sample
-│   ├── scoring_engine.py          ← mock scorecard (Phase 1)
-│   ├── session_manager.py         ← in-memory sessions
-│   └── voice_transcriber.py       ← stub (Phase 1)
-├── config/
-│   ├── attack_tags.json           ← reference (code uses attack_tags.py)
-│   ├── personas.json              ← persona metadata
-│   ├── pitch_rubric.json          ← 6-dimension rubric weights
-│   └── sample_startups.json       ← sample startup data
-├── frontend/
-│   ├── index.html
-│   ├── script.js                  ← fetch-only, /api/* calls
-│   ├── styles.css
-│   └── assets/
-└── docs/
-    ├── BACKEND_API.md             ← endpoint reference
-    ├── CLAUDE_PROJECT_CONTEXT.md  ← this file
-    ├── DEMO_NOTES.md              ← demo flow + prize talking points
-    ├── DOCUMENTATION.md           ← full project documentation
-    ├── FIELD_NOTES.md             ← build log
-    ├── MODELS_FINAL.md            ← model strategy
-    ├── PHASE_WISE_PLAN.md         ← 14-phase build plan
-    ├── PROMPTS.md                 ← prompt templates
-    └── TASK_TRACKER.md            ← phase + task status
-```
-
-**Missing from `core/` (needed Phase 2+):**
-- `model_router.py`
-- `nvidia_client.py`
-- `minicpm_client.py`
-- `vision_client.py`
-- `transcription_client.py`
-
----
-
-## 8. Current Implementation Status
-
-### Working (Phase 1)
-- Gradio Server app starts and serves custom frontend
-- GET `/health` returns version + status
-- GET `/` serves `frontend/index.html`
-- POST `/api/load-sample` returns EventRadar AI startup dict from `samples.py`
-- POST `/api/start-session` creates in-memory session, returns mock opening question keyed by persona
-- POST `/api/chat-round` increments round, rotates attack tags, returns hardcoded mock follow-up per persona
-- POST `/api/end-battle` returns mock scorecard with static scores, real user quotes from session history
-- POST `/api/reset-session` deletes session from SESSIONS dict
-- Frontend flow: landing → setup (load sample or enter custom) → battle arena → scorecard
-- Error banners and loading overlay functional in frontend
-- Health check on boot functional
-
-### Mock / Placeholder
-- All AI opponent messages in `api_handlers.py` — hardcoded string lists per persona
-- All scorecard scores — hardcoded integers (overall: 68, clarity: 64, etc.)
-- `feedback_generator.py` — template string rewrites, no model call
-- `local_text_model.py` — stub, returns placeholder string
-- `voice_transcriber.py` — stub, returns not_loaded status
-- `/api/voice-pitch` — returns `{"status": "not_implemented"}`
-- `/api/start-deal-session` — returns `{"status": "not_implemented"}`
-- `/api/deck-critique` — returns `{"status": "not_implemented"}`
-
-### Missing (Phase 2+)
-- `core/model_router.py` — central routing logic
-- `core/nvidia_client.py` — NVIDIA Nemotron API calls
-- `core/minicpm_client.py` — MiniCPM-o and MiniCPM5-1B API/local calls
-- `core/vision_client.py` — MiniCPM-V 4.6 image/vision calls
-- `core/transcription_client.py` — faster-whisper audio fallback
-- Real AI response in `handle_chat_round` (replace hardcoded followups)
-- Real scoring in `handle_end_battle` (replace `mock_scorecard`)
-- Real rewrite in `feedback_generator` (replace template strings)
-- Voice audio handling in `/api/voice-pitch`
-- Deal battle logic in `/api/start-deal-session`
-- Image upload and critique in `/api/deck-critique`
-
----
-
-## 9. Mock vs Real Components
-
-| Component | Mock or Real | Notes |
-|---|---|---|
-| Session management | **Real** | In-memory, uuid-based, correct |
-| Persona system prompt builder | **Real** | `persona_builder.py` builds full system prompt |
-| Attack tag rotator | **Real** | `attack_tags.py` rotates by round index |
-| Sample startup data | **Real** | EventRadar AI data loaded from `samples.py` |
-| Config JSON files | **Real** | personas, rubric, tags all present |
-| JSON utils | **Real** | Extraction + safe parse + fallback all coded |
-| `json_utils.fallback_scorecard()` | **Real** | Safe fallback ready |
-| Opening AI question | **Mock** | Hardcoded per persona in `api_handlers.py` |
-| Follow-up AI questions | **Mock** | Hardcoded list per persona, index by round |
-| Scorecard scores | **Mock** | All integers hardcoded in `scoring_engine.mock_scorecard()` |
-| Answer rewrite | **Mock** | Template string in `feedback_generator.py` |
-| Pitch rewrite | **Mock** | Template string in `feedback_generator.py` |
-| NVIDIA API client | **Real** | `core/nvidia_client.py` — live, tested Phase 2 |
-| Model router | **Real** | `core/model_router.py` — premium_nvidia live; others stub |
-| MiniCPM clients | **Stub** | `core/minicpm_client.py` — health_check only, Phase 9 |
-| Vision client | **Stub** | `core/vision_client.py` — health_check only, Phase 10 |
-| Whisper transcription | **Stub** | `core/transcription_client.py` — health_check only, Phase 7 |
-
----
-
-## 10. Next Recommended Phase
-
-**Phase 3: Wire model_router into battle flow**
-
-Phase 2 is complete. NVIDIA Nemotron is live and tested. Next step is connecting `model_router.generate_opponent_response()` to the actual battle endpoints.
-
-Goals:
-1. In `core/api_handlers.py`: import `model_router` and `persona_builder`
-2. In `handle_start_session`: build system prompt, call `model_router.generate_opponent_response()`, fall back to mock if `ok=False`
-3. In `handle_chat_round`: build full message history, call `model_router.generate_opponent_response()`, fall back to mock if `ok=False`
-4. End-to-end test: full battle with live Nemotron responses
-5. Update docs
-
-Do **not** connect voice, deal battle, scoring, or deck critique in Phase 3.
-
----
-
-## 11. Rules for Future Claude Code Work
-
-1. **Always read docs before implementing a phase.** Read `PHASE_WISE_PLAN.md`, this file, and `BACKEND_API.md` before touching code.
-2. **Never expose API keys in frontend.** No env reads, no hardcoded keys, no fetch calls to model provider URLs from frontend JS.
-3. **Never commit `.env`.** `.gitignore` must include `.env`. Only `.env.example` (empty values) goes to repo.
-4. **Keep frontend calls limited to `/api/*`.** The only external call from frontend is to `/health`. All AI calls go through backend `/api/*` routes.
-5. **Keep model calls backend-only.** All `openai.Client`, `requests.post`, or SDK calls to NVIDIA/OpenBMB must be in `core/` files only.
-6. **After each phase, update `docs/PHASE_WISE_PLAN.md`** with a status line marking the phase complete.
-7. **After each phase, update `docs/FIELD_NOTES.md`** with what changed, what worked, and what was learned.
-8. **After each phase, update `docs/BACKEND_API.md`** if any endpoint changed signature, status, or behavior.
-9. **After each phase, update `docs/MODELS_FINAL.md`** if the model strategy or routing changed.
-10. **Do not silently change architecture.** Any change to the API contract, session model, or model routing must be documented before implementation.
-11. **Preserve the working mock flow while replacing parts incrementally.** Never delete a working mock endpoint before its replacement is tested. The mock is the safety net.
-12. **Use `os.getenv()` only** for API key reads. Never use hardcoded fallback values for secrets. If the key is missing, log a warning and return a clear error — do not silently continue.
-13. **Do not add features outside the current phase scope.** One phase at a time. Phase 2 is model router only. Phase 3 is NVIDIA text only. Do not reach forward.
-14. **Test each model client independently** before wiring it into the session/handler flow.
-15. **`core/json_utils.py` already has `safe_json_parse` and `fallback_scorecard`.** Use them — do not rewrite JSON parsing logic elsewhere.
-
----
-
-## 12. Documentation Update Rules
-
-After every phase:
-
-| Doc | What to update |
-|---|---|
-| `docs/PHASE_WISE_PLAN.md` | Mark phase status as Complete. Add date. |
-| `docs/FIELD_NOTES.md` | Add a build log entry: what changed, what worked, what surprised you. |
-| `docs/BACKEND_API.md` | Update endpoint status column if a placeholder became real. |
-| `docs/MODELS_FINAL.md` | Update model-to-file mapping if new client files were created or routes changed. |
-| `docs/TASK_TRACKER.md` | Move completed tasks to done; update current phase and next tasks. |
-| `docs/CLAUDE_PROJECT_CONTEXT.md` | Update "Current Implementation Status" and "Mock vs Real Components" sections. |
-
-Do **not** update docs prophylactically for future phases. Only document what is actually implemented.

docs/DEMO_NOTES.md

@@ -1,48 +0,0 @@
-# PitchFight AI — Demo Notes
-
-## Strategic Demo Positioning
-
-PitchFight AI is a **high-demo sponsor-model build** — not Off-the-Grid. Lead with voice, pressure, and scorecard quality. Mention NVIDIA Nemotron Omni and OpenBMB MiniCPM modes as sponsor-aligned small models under 32B.
-
-## Full Demo Flow (Target Build)
-
-1. Open the app — custom battle arena UI (not default Gradio).
-2. Show **model mode badge** (Premium Nemotron / OpenBMB Omni / Tiny MiniCPM).
-3. **Text path:** Load EventRadar AI → Hackathon Judge → Enter Arena → get grilled → End Battle → scorecard.
-4. **Voice path:** Record spoken pitch → Nemotron interprets → first hard question → continue battle.
-5. **Deal Battle:** Sponsorship or salary negotiation scenario → deal-specific scorecard.
-6. **Deck critique (if built):** Upload slide screenshot → 3 judge questions.
-7. **Retry:** Retry weakest question → show improvement.
-
-## Phase 1 Demo Flow (Current)
-
-1. Open the app.
-2. Click **Load Demo Startup** (EventRadar AI).
-3. Select **Hackathon Judge**.
-4. Click **Enter the Arena**.
-5. Answer weakly (e.g., "We use AI to rank events better").
-6. Watch mock AI push back with attack tag + pressure level.
-7. Click **End Battle** after 2–3 rounds.
-8. Show scorecard: overall, bars, rewrites, top prep questions.
-
-## Talking Points
-
-- Custom Gradio Server frontend + `@app.api` backend.
-- All model calls backend-only; keys in HF Space Secrets.
-- ≤32B models: Nemotron Omni, MiniCPM-o, MiniCPM5-1B, MiniCPM-V.
-- Voice + multimodal judging as differentiator.
-- Rubric-based scorecard with quotes and rewrites.
-- Off-the-Grid **not** claimed — demo quality is the goal.
-
-## Prize Alignment Talking Points
-
-| Prize | Hook |
-|---|---|
-| Backyard AI | Student founders, real pressure practice |
-| Best Demo | Voice pitch → grill → scorecard in one flow |
-| Best Agent | Persona + memory + attack tags + scoring loop |
-| Off-Brand | Custom HTML/CSS/JS arena UI |
-| NVIDIA Nemotron Quest | Premium voice/multimodal judge |
-| OpenBMB Awards | MiniCPM-o / 5-1B / V modes |
-| Sharing is Caring | Public prompts, rubrics, attack tags |
-| Field Notes | Build story post-deployment |

docs/DOCUMENTATION.md

@@ -1,1447 +0,0 @@
-# ⚔️ PitchFight AI — Final Hackathon-Aligned Documentation
-
-## A Voice-and-Text AI Sparring Arena for Student Founders (≤32B Models)
-
-> **Your first tough pitch should not be in front of a real judge.**  
-> **Normal AI assistants give advice. PitchFight AI creates pressure.**
-
-### Strategy Update (Current Build)
-
-This documentation reflects the **high-demo sponsor-model strategy**. PitchFight AI prioritizes demo strength, model quality, and sponsor alignment (NVIDIA Nemotron Omni, OpenBMB MiniCPM) while staying under the **≤32B** Build Small Hackathon rule.
-
-> **Off-the-Grid is not targeted.** Premium default model mode is **NVIDIA Nemotron Omni** (backend-only). API keys live in `.env` locally / HF Space Secrets in deployment — never in the frontend.
-
-See also: [`PHASE_WISE_PLAN.md`](PHASE_WISE_PLAN.md) · [`MODELS_FINAL.md`](MODELS_FINAL.md) · [`BACKEND_API.md`](BACKEND_API.md)
-
-PitchFight AI exposes **clean custom project APIs under `/api/...`**. Gradio internal routes may appear in OpenAPI/Swagger, but they are **framework runtime routes**, not product endpoints.
-
----
-
-## 1. Project Overview
-
-**PitchFight AI** is a Hugging Face Spaces + Gradio Server application that helps student founders practice high-pressure startup pitching before facing real judges, mentors, investors, sponsors, recruiters, or clients.
-
-The project is built for the **Backyard AI** track of the Build Small Hackathon. The target user is intentionally narrow:
-
-> **Student founders and hackathon builders who know their project, but freeze when someone asks hard questions.**
-
-PitchFight AI turns pitch practice into a realistic AI sparring arena. The AI does not behave like a generic assistant. It behaves like a skeptical counterpart, asks tough follow-up questions, remembers previous answers, detects weak claims, scores the conversation, and rewrites the weakest answer into a stronger response.
-
----
-
-## 2. Hackathon Rule Alignment
-
-This section is intentionally explicit so the project does not violate the hackathon constraints.
-
-### Required Rules
-
-| Rule | How PitchFight AI Complies |
-|---|---|
-| **Small Models Only** | All models stay under the 32B parameter cap: Nemotron 3 Nano Omni (~30B), MiniCPM-o, MiniCPM5-1B, MiniCPM-V 4.6. |
-| **Built on Gradio** | Gradio Server app hosted as a Hugging Face Space with custom HTML/CSS/JS frontend. |
-| **Show, Don’t Tell** | Demo-first: pitch battle, voice mode, deal battle, scorecard — runnable in the Space. |
-| **No Frontend Model Calls** | Browser calls only `/api/...` endpoints via `fetch()`; model APIs are backend-only. |
-
-### Sponsor-Model / High-Demo Strategy
-
-The **default submitted build** prioritizes the strongest demonstrative experience:
-
-- **NVIDIA Nemotron Omni** — primary premium judge (text, voice, multimodal, scoring).
-- **OpenBMB MiniCPM** — MiniCPM-o (omni), MiniCPM5-1B (tiny/fallback), MiniCPM-V 4.6 (deck critique).
-- **faster-whisper** — backup local transcription when Omni voice path is unavailable.
-- **No browser-side model API calls** — all keys in HF Space Secrets / backend `.env`.
-- **No OpenAI or unrelated cloud APIs** in the default flow.
-
-### Off-the-Grid Position
-
-> **Off-the-Grid is intentionally not targeted.** Sponsor/model APIs are used for demo quality. The project instead targets Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, and Field Notes.
-
-### Final Compliance Position
-
-> **PitchFight AI follows hackathon core rules: ≤32B models, Gradio/HF Spaces, demo-first execution, backend-only inference with secrets managed server-side.**
-
----
-
-## 3. Core Problem
-
-Most student founders prepare their pitch by:
-
-- Reading pitch tips online
-- Practicing alone
-- Showing their idea to friends who say “sounds good”
-- Making slides but not preparing for hard Q&A
-
-The first real pressure often happens during judging, mentoring, investor review, or sponsorship calls. That is exactly when many students freeze.
-
-### Gap
-
-There is no easy, low-cost, always-available sparring partner that can simulate:
-
-- A skeptical hackathon judge
-- A technical evaluator
-- A hard investor
-- A sponsor asking for ROI
-- A recruiter or client pushing back
-
-### PitchFight AI’s Solution
-
-PitchFight AI creates a **pressure simulation loop**:
-
-1. User enters startup/project context.
-2. User chooses an AI opponent.
-3. AI opponent asks one sharp question at a time.
-4. User responds under pressure.
-5. AI follows up on weak or vague answers.
-6. App generates a scorecard and improved answer.
-
----
-
-## 4. Final Product Scope
-
-### Primary Mode: Pitch Battle
-
-The user defends their startup or hackathon project against a persona-locked AI opponent.
-
-#### Personas
-
-| Persona | Role | What They Attack |
-|---|---|---|
-| **Skeptical VC** | Investor-style evaluator | Market, moat, revenue, defensibility, retention |
-| **Technical Judge** | Engineering evaluator | AI necessity, architecture, scalability, feasibility |
-| **Hackathon Judge** | Competition evaluator | Novelty, demo clarity, MVP strength, real-world usefulness |
-
-### Secondary Mode: Deal Battle
-
-The user practices negotiation scenarios useful for student founders and early-career builders.
-
-#### Scenarios
-
-| Scenario | Counterpart |
-|---|---|
-| Startup Sponsorship Ask | Tough sponsor |
-| Internship Salary Negotiation | Strict HR recruiter |
-| Freelance Client Pricing | Budget-conscious client |
-| Equity Negotiation | Investor negotiating hard |
-
-### Voice Mode
-
-Voice Mode allows the user to speak their pitch instead of typing it.
-
-For the MVP, Voice Mode is intentionally simple and reliable:
-
-```text
-User records pitch audio
-        ↓
-Backend /api/voice-pitch (frontend never calls model APIs)
-        ↓
-Primary: NVIDIA Nemotron Omni interprets audio + asks first hard question
-        ↓
-Fallback: faster-whisper transcribes → Nemotron or MiniCPM5-1B text path
-        ↓
-User continues by text or voice
-        ↓
-Scorecard includes voice-derived structure and conciseness signals
-```
-
-Founders normally pitch out loud; the premium voice path uses Nemotron Omni backend-only, with faster-whisper as transcription fallback only.
-
----
-
-## 5. What Makes This a Strong Hackathon Project
-
-PitchFight AI is designed around the hackathon’s judging taste: runnable, specific, useful, delightful, and more than a chatbot wrapper.
-
-### Runnable Gradio Space
-
-The final app is deployed as a Hugging Face Space using Gradio.
-
-### Clear Purpose
-
-The app has one clear mission:
-
-> Help student founders survive tough pitch and negotiation conversations before the real moment.
-
-### Useful + Delightful
-
-Useful: improves pitch readiness.  
-Delightful: feels like entering a battle arena instead of filling a boring form.
-
-### More Than a Chatbot Wrapper
-
-PitchFight AI includes:
-
-- Startup context intake
-- Persona selection
-- Round-based battle flow
-- Pressure level
-- Attack tags
-- Conversation memory
-- Voice pitch mode
-- Rubric-based scoring
-- Weakest answer detection
-- Improved answer rewrite
-- Final pitch rewrite
-- Scorecard screen
-
-### Small Model Showcase
-
-The project uses compact models strategically rather than relying on one huge model. The intelligence comes from:
-
-- Strong persona prompts
-- Memory
-- Role consistency
-- Attack-tag routing
-- Rubric scoring
-- faster-whisper transcription fallback (when Omni voice path is unavailable)
-- Feedback generation
-
----
-
-## 6. Final System Architecture
-
-```mermaid
-flowchart TD
-    A[Student Founder] --> B[Custom Web UI — fetch to /api/* only]
-
-    B --> C{Input Mode}
-    C -->|Text Pitch| D[Startup Context Form]
-    C -->|Voice Pitch| E[Browser Audio Recorder]
-
-    D --> H[Session Manager]
-    E --> VP[/api/voice-pitch]
-    VP --> F[NVIDIA Nemotron Omni — primary voice path]
-    VP --> W[faster-whisper — transcription fallback only]
-    F --> H
-    W --> H
-
-    H --> I[Persona Prompt Builder]
-    I --> J[Attack Tag Selector]
-    J --> K[Battle Engine]
-
-    K --> MR[Model Router]
-    MR --> L1[NVIDIA Nemotron Omni — default premium judge]
-    MR --> L2[MiniCPM-o 4.5 — OpenBMB omni mode]
-    MR --> L3[MiniCPM5-1B — tiny / API-failure fallback]
-    MR --> L4[MiniCPM-V 4.6 — deck critique]
-    L1 --> M[AI Opponent Response]
-    L2 --> M
-    L3 --> M
-    M --> B
-
-    H --> N[Scoring Engine]
-    N --> MR
-    MR --> O[Structured Scorecard JSON]
-    O --> P[JSON Parser + Fallback Handler]
-    P --> Q[Feedback Generator]
-    Q --> R[Scorecard + Improved Answer]
-    R --> B
-```
-
-### Simple Explanation
-
-- The **custom frontend** handles the arena UI and calls only **`/api/...`** endpoints — never model provider APIs.
-- **Gradio Server** exposes backend APIs and serves the custom frontend.
-- The **Session Manager** stores startup details, chosen persona, round count, attack tags, and conversation history.
-- The **Persona Prompt Builder** creates the opponent behavior.
-- The **Attack Tag Selector** decides what kind of pressure the AI should apply next.
-- The **Model Router** routes inference to **NVIDIA Nemotron Omni** by default, with OpenBMB MiniCPM modes and MiniCPM5-1B fallback.
-- **faster-whisper** is backup transcription only when the Omni voice path is unavailable.
-- API keys live in **HF Space Secrets** / backend `.env` only — never in frontend code.
-- The **Scorecard UI** shows what went well, what failed, and how to improve.
-
----
-
-## 7. User Workflow Diagram
-
-```mermaid
-flowchart LR
-    A[Open PitchFight AI] --> B[Choose Mode]
-    B --> C[Pitch Battle]
-    B --> D[Deal Battle]
-
-    C --> E[Enter Startup Context]
-    D --> F[Enter Negotiation Context]
-
-    E --> G[Choose Opponent]
-    F --> G
-
-    G --> H[Choose Text or Voice Input]
-    H --> I[AI Opens With Hard Question]
-    I --> J[User Responds]
-    J --> K[AI Selects Attack Tag]
-    K --> L[AI Pushes Back]
-    L --> J
-
-    J --> M[End Battle]
-    M --> N[Scorecard]
-    N --> O[Weakest Answer]
-    O --> P[Improved Version]
-    P --> Q[Retry or Start New Battle]
-```
-
----
-
-## 8. Final Model Strategy
-
-The core model table is kept intentionally small. Every model listed here has a real job in the submitted app.
-
-| Model | Type | Where Used | Why Used |
-|---|---|---|---|
-| **NVIDIA Nemotron 3 Nano Omni** | Premium multimodal LLM (≤30B) | Primary judge: pitch battle, voice, deal battle, scoring, rewrites | Best demo quality; NVIDIA Nemotron Quest alignment |
-| **MiniCPM-o 4.5** | OpenBMB omni model | OpenBMB sponsor mode, multimodal fallback | OpenBMB Awards alignment |
-| **MiniCPM5-1B** | Tiny text LLM | Tiny Mode, API failure fallback | Speed + Tiny Titan eligibility |
-| **MiniCPM-V 4.6** | Vision model | Pitch deck / slide critique | Image-based judge questions |
-| **faster-whisper (tiny/base)** | Local STT | Voice fallback transcription | Reliable backup when Omni voice path fails |
-
-### Fallback Model Note
-
-`core/model_router.py` routes to **Tiny MiniCPM5-1B** or **whisper_fallback** when premium APIs timeout, fail, or keys are missing. UI shows active mode badge (Premium Nemotron / OpenBMB Omni / Tiny MiniCPM).
-
----
-
-## 9. Exact Use of Each Model
-
-### 9.1 NVIDIA Nemotron Omni — Primary Premium Model
-
-Used for:
-
-- AI opponent responses and follow-ups
-- Voice pitch interpretation and first hard question
-- Deal battle counterpart dialogue
-- Scorecard generation (structured JSON)
-- Weakest answer rewrite and 60-second pitch rewrite
-- Optional multimodal deck + spoken pitch critique
-
-#### Backend Client
-
-`core/nvidia_client.py` — secure calls via `NVIDIA_API_KEY` and `NVIDIA_BASE_URL`. Never exposed to frontend.
-
-### 9.1b MiniCPM Models — OpenBMB + Fallback
-
-**MiniCPM-o 4.5** — OpenBMB omni mode. **MiniCPM5-1B** — tiny/fallback text. **MiniCPM-V 4.6** — slide critique.
-
-#### Runtime Options
-
-| Runtime | Use Case |
-|---|---|
-| OpenBMB API / HF inference | Primary OpenBMB sponsor path |
-| Local `transformers` / quantized | Tiny Mode on Space hardware if needed |
-
-#### Suggested Settings
-
-| Task | Temperature | Max Tokens |
-|---|---:|---:|
-| Opponent response | 0.7–0.8 | 180–260 |
-| Scorecard | 0.1–0.3 | 900–1400 |
-| Rewrite weak answer | 0.4–0.5 | 400–600 |
-| Final pitch rewrite | 0.5–0.6 | 400–700 |
-
----
-
-### 9.2 Whisper Tiny/Base — Local Voice Input
-
-Used for:
-
-- Spoken pitch transcription
-- Spoken answer transcription
-- Generating a transcript for the text battle engine
-- Voice add-on metrics based on transcript structure
-
-#### Voice Flow (Primary)
-
-```text
-Browser records audio
-  → /voice_pitch API
-  → NVIDIA Nemotron Omni (audio + prompt)
-  → structured pitch context + first hard question
-  → Pitch Battle continues (voice or text)
-```
-
-#### Voice Flow (Fallback)
-
-```text
-Browser records audio
-  → faster-whisper local transcription
-  → transcript → selected text model (Nemotron or MiniCPM5-1B)
-  → normal Pitch Battle flow
-```
-
----
-
-### 9.3 Pitch Deck Critique — MiniCPM-V / Nemotron Vision
-
-Used for:
-
-- Slide screenshot upload via `/deck_critique`
-- Claim extraction and clarity critique
-- Three judge prep questions per slide
-
-Primary: **MiniCPM-V 4.6**. Alternate: Nemotron Omni vision path.
-
----
-
-## 10. Tools and Their Exact Usage
-
-| Tool / Platform | Use in PitchFight AI |
-|---|---|
-| **Hugging Face Spaces** | Final deployment platform |
-| **Gradio Server** | Gradio backend server with custom route support |
-| **FastAPI `/api/*` routes** | Product endpoints: `/api/start-session`, `/api/chat-round`, `/api/end-battle`, etc. |
-| **Gradio `@app.api` wrappers** | Compatibility aliases calling the same `core/api_handlers.py` functions |
-| **Custom HTML/CSS/JS** | Makes the UI look like a battle arena instead of default Gradio |
-| **Browser `fetch()`** | Frontend calls `/api/*` endpoints only — never model provider APIs |
-| **faster-whisper** | Audio transcription fallback when Nemotron Omni voice path is unavailable |
-| **Hugging Face Hub** | Model download and project sharing |
-| **HF Space Secrets** | NVIDIA, OpenBMB, and HF tokens for backend-only inference (never exposed to frontend) |
-| **GitHub / HF repo** | Version control and project sharing |
-| **Mermaid diagrams** | Architecture and workflow documentation |
-| **Cursor Agent** | Frontend implementation and UI polish |
-| **Claude Code** | File generation, backend modules, refactoring |
-| **ChatGPT** | Planning, architecture, prompt design, debugging strategy, documentation |
-
----
-
-## 11. Backend API Design
-
-The frontend should never call model runtime code directly. All model calls go through the Python backend.
-
-### Correct Flow
-
-```text
-Browser UI → /api/* (fetch) → api_handlers → model_router → NVIDIA / OpenBMB / whisper clients
-```
-
-### Wrong Flow
-
-```text
-Browser UI → External model API directly
-```
-
-This would expose API keys. All model calls must stay on the backend.
-
----
-
-### 11.1 `/start_session`
-
-Starts a new battle session.
-
-#### Input
-
-```json
-{
-  "mode": "pitch_battle",
-  "persona": "hackathon_judge",
-  "difficulty": "high",
-  "input_mode": "text",
-  "startup": {
-    "name": "EventRadar AI",
-    "problem": "Students miss hackathons and tech events because discovery is scattered.",
-    "target_users": "College students and early-stage builders",
-    "solution": "AI-powered event matching based on goals, skills, location, and urgency",
-    "why_ai": "The model ranks and explains relevance instead of just listing events",
-    "competitors": "Luma, LinkedIn Events, WhatsApp groups",
-    "traction": "Prototype with scraped event data and ranking logic",
-    "ask": "Hackathon prize and mentor feedback"
-  }
-}
-```
-
-#### Output
-
-```json
-{
-  "session_id": "abc123",
-  "round": 1,
-  "pressure_level": "High",
-  "attack_tag": "AI Justification",
-  "ai_message": "Why does this need AI? A sorted event list with filters seems enough. What is the intelligence here?"
-}
-```
-
----
-
-### 11.2 `/chat_round`
-
-Processes one user answer and returns the next AI pushback.
-
-#### Input
-
-```json
-{
-  "session_id": "abc123",
-  "user_message": "The AI ranks events based on the student's profile and explains why each event matters."
-}
-```
-
-#### Output
-
-```json
-{
-  "round": 2,
-  "pressure_level": "High",
-  "attack_tag": "Retention",
-  "ai_message": "That explains matching, not retention. Why would a student return every week instead of checking once before placement season?"
-}
-```
-
----
-
-### 11.3 `/voice_pitch`
-
-Accepts an audio file. Primary path: Nemotron Omni voice interpretation. Fallback: faster-whisper transcription.
-
-#### Input
-
-```json
-{
-  "audio_file": "pitch.wav",
-  "persona": "skeptical_vc"
-}
-```
-
-#### Output
-
-```json
-{
-  "transcript": "We are building EventRadar AI...",
-  "detected_startup_context": {
-    "name": "EventRadar AI",
-    "problem": "students miss events",
-    "solution": "AI event matching"
-  },
-  "opening_question": "You are describing discovery, but where is the urgency? Why is this painful enough for students to change behavior?"
-}
-```
-
-Implementation detail:
-
-- **Primary:** audio sent to NVIDIA Nemotron Omni via backend; model extracts pitch context and opening question.
-- **Fallback:** faster-whisper transcribes locally; transcript routed to Nemotron or MiniCPM5-1B text path.
-- If context extraction is uncertain, the UI asks the user to quickly edit the detected fields before the battle starts.
-
----
-
-### 11.4 `/end_battle`
-
-Scores the conversation.
-
-#### Input
-
-```json
-{
-  "session_id": "abc123"
-}
-```
-
-#### Output
-
-```json
-{
-  "overall": 68,
-  "scores": {
-    "clarity": {
-      "score": 76,
-      "reason": "The user explained the workflow clearly but took too long to state the core value.",
-      "quote": "It ranks events based on a student's profile."
-    },
-    "problem_understanding": {
-      "score": 70,
-      "reason": "The user described the problem but did not provide evidence of frequency or severity.",
-      "quote": "Students miss hackathons because discovery is scattered."
-    }
-  },
-  "best_answer": {
-    "quote": "The app explains why each event is relevant instead of only listing it.",
-    "why": "This differentiated the product from a basic directory."
-  },
-  "weakest_answer": {
-    "quote": "Students will use it because it is helpful.",
-    "why": "This answer was vague and did not address retention or urgency."
-  },
-  "improved_answer": "Students return because the system continuously tracks deadlines, skill fit, team requirements, and local event updates. It becomes a weekly opportunity radar, not a one-time event list.",
-  "improved_pitch": "EventRadar AI helps students discover the right hackathons and tech events by matching opportunities to their skills, goals, location, and urgency. Unlike static event lists, it explains why each event matters and helps students act before deadlines.",
-  "top_3_questions": [
-    "Why does this need AI instead of filters?",
-    "What makes users return weekly?",
-    "How will you get your first 100 active users?"
-  ]
-}
-```
-
----
-
-## 12. Attack Tag Taxonomy
-
-Attack tags make PitchFight AI feel structured instead of random. The AI should rotate through known pressure points based on the selected persona and the user’s previous answer.
-
-### 12.1 Skeptical VC Attack Tags
-
-| Attack Tag | What It Tests | Example Question |
-|---|---|---|
-| Market Size | Whether the opportunity is big enough | “How many people have this problem badly enough to pay or change behavior?” |
-| Moat | Whether the idea is defensible | “What stops a larger platform from copying this in a week?” |
-| Retention | Whether users come back | “Why would someone open this again after the first use?” |
-| Revenue Logic | Whether there is a path to money/value | “Who pays, how much, and why would they keep paying?” |
-| First 100 Users | Whether acquisition is realistic | “How exactly do you get the first 100 active users without paid ads?” |
-| Why Now | Whether timing is convincing | “Why is this urgent now instead of two years ago or two years later?” |
-| Competition | Whether existing alternatives are understood | “Why does your user choose this over what they already do today?” |
-
-### 12.2 Technical Judge Attack Tags
-
-| Attack Tag | What It Tests | Example Question |
-|---|---|---|
-| AI Justification | Whether AI is actually needed | “What does the model do that filters or rules cannot?” |
-| Architecture | Whether the system design is clear | “Where exactly does inference happen, and what data flows through it?” |
-| Scalability | Whether the system can grow | “What breaks first when 100 users become 10,000?” |
-| Latency | Whether the UX is practical | “How long does one response take, and what happens when it is slow?” |
-| Data Quality | Whether input data is reliable | “Where does your data come from, and how do you handle missing or wrong data?” |
-| Failure Mode | Whether the team knows what can go wrong | “What is the worst wrong output your system can produce?” |
-| Simpler Alternative | Whether the build is overengineered | “Could this be done with a form and rules? Why is your system better?” |
-
-### 12.3 Hackathon Judge Attack Tags
-
-| Attack Tag | What It Tests | Example Question |
-|---|---|---|
-| Novelty | Whether the project is memorable | “I have seen similar ideas. What is the one thing I will remember?” |
-| Demo Clarity | Whether the demo lands quickly | “Can you show the value in 30 seconds?” |
-| MVP Strength | Whether the prototype actually works | “What part is fully working right now, not just planned?” |
-| User Pain | Whether the problem is real | “Who exactly has this problem, and how do you know?” |
-| AI Load-Bearing | Whether AI is central | “If I remove the model, does the product collapse or still work?” |
-| Backyard Fit | Whether it helps a real person | “Who used this, and what got better for them?” |
-| Practical Impact | Whether it matters beyond the demo | “What changes for the user after using this?” |
-
-### 12.4 Deal Battle Attack Tags
-
-| Attack Tag | What It Tests | Example Question |
-|---|---|---|
-| Anchoring | Whether the user sets a clear position | “What number are you asking for, and why that number?” |
-| Evidence | Whether claims are backed by proof | “What proof do you have that you are worth that ask?” |
-| Concession | Whether the user gives up too early | “If I say no, what do you offer without lowering the value?” |
-| Mutual Value | Whether both sides benefit | “Why is this good for me, not just for you?” |
-| Closing | Whether the user moves toward action | “What exact next step are you asking me to agree to?” |
-
----
-
-## 13. Core Prompt Design
-
-### 13.1 Opponent System Prompt
-
-```text
-You are {persona_name}, a realistic evaluator speaking to a student founder.
-
-Your job is not to encourage. Your job is to pressure-test the founder's thinking.
-
-Startup context:
-- Name: {name}
-- Problem: {problem}
-- Target users: {target_users}
-- Solution: {solution}
-- Why AI: {why_ai}
-- Competitors: {competitors}
-- Traction: {traction}
-- Ask: {ask}
-
-Current attack tag: {attack_tag}
-
-Rules:
-1. Ask one sharp question at a time.
-2. Keep responses under 4 sentences.
-3. Reference the founder's previous answer.
-4. Do not give advice during the battle.
-5. Do not say "great answer", "interesting", or "that makes sense".
-6. If the answer is vague, attack the vague part.
-7. If the answer is strong, raise the difficulty.
-8. Stay in character.
-9. Be firm, realistic, and useful — not abusive.
-10. Your response must match the current attack tag.
-```
-
----
-
-### 13.2 Scoring Prompt
-
-```text
-You watched a pitch battle between a student founder and an AI evaluator.
-
-Score the founder on:
-1. Clarity
-2. Problem Understanding
-3. Market Awareness
-4. Differentiation
-5. Business Model
-6. Objection Handling
-
-For each dimension:
-- Give a score from 0 to 100
-- Mention the exact quote that influenced the score
-- Give one specific reason
-
-Then identify:
-- Best answer
-- Weakest answer
-- Why the weak answer failed
-- Improved version of the weak answer
-- Improved 60-second pitch
-- Top 3 questions to prepare next
-
-Return valid JSON only.
-```
-
----
-
-## 14. Scoring Rubric
-
-### Pitch Battle
-
-| Dimension | Weight | What It Measures |
-|---|---:|---|
-| Clarity | 15% | Can a judge understand the idea quickly? |
-| Problem Understanding | 20% | Did the founder prove the pain is real? |
-| Market Awareness | 15% | Do they know who the first users are? |
-| Differentiation | 20% | Why does this beat existing options? |
-| Business Model | 15% | Is there a path to value or revenue? |
-| Objection Handling | 15% | Did they answer directly or dodge? |
-
-### Deal Battle
-
-| Dimension | Weight | What It Measures |
-|---|---:|---|
-| Anchoring | 20% | Did the user set a clear position? |
-| Evidence Usage | 20% | Did they support the ask with proof? |
-| Confidence | 15% | Did they hold ground under pressure? |
-| Empathy | 15% | Did they understand the other side’s constraints? |
-| Concession Handling | 15% | Did they avoid giving up too fast? |
-| Closing | 15% | Did they move toward a clear next step? |
-
-### Voice Mode Add-On Metrics
-
-| Dimension | What It Measures |
-|---|---|
-| Structure | Did the spoken pitch have a clear beginning, middle, and ask? |
-| Conciseness | Did the user avoid rambling? |
-| Confidence Signals | Did the transcript show hesitation or unclear phrasing? |
-| Directness | Did the user answer the question directly? |
-
----
-
-## 15. JSON Parsing and Fallback Strategy
-
-Small models can return malformed JSON. The scoring engine must handle this gracefully.
-
-### Fallback Pipeline
-
-```text
-1. Try direct JSON parse.
-        ↓
-2. If parse fails, extract substring from first `{` to last `}` and parse again.
-        ↓
-3. If still broken, send a model retry prompt via model router:
-   “Convert the following response into valid JSON only.”
-        ↓
-4. If retry fails, use regex to extract numeric scores and key sections.
-        ↓
-5. If all parsing fails, show a graceful fallback scorecard:
-   “Scorecard could not be fully structured, but here is the raw feedback.”
-```
-
-### Implementation Notes
-
-- Never expose raw Python errors in the UI.
-- Always show something useful to the user.
-- Log parse failures in the backend console for debugging.
-- Keep a default scorecard schema so the frontend never breaks.
-
----
-
-## 16. Frontend UI Design
-
-### Design Goal
-
-The app should not look like a basic Gradio demo. It should feel like a polished AI practice arena.
-
-### Screens
-
-1. Landing screen
-2. Mode selection
-3. Startup / negotiation context form
-4. Persona selection
-5. Text or voice input selection
-6. Battle arena
-7. Scorecard screen
-8. Retry / new battle screen
-
-### Visual Direction
-
-```text
-Theme: Dark Battle Arena
-Background: near-black / navy
-Primary accent: red
-Secondary accent: gold
-Cards: dark glassmorphism
-Typography: bold headings, clean mono-style chat
-Animations: subtle glow, score reveal, pressure meter pulse
-```
-
-### UI Elements
-
-- Round counter
-- Pressure meter
-- Attack tag
-- Opponent card
-- Founder card
-- Voice recording button
-- Chat transcript
-- End battle button
-- Score bars
-- Weakest answer highlight
-- Improved answer card
-
----
-
-## 17. Hugging Face Spaces Deployment Plan
-
-### Space Type
-
-```yaml
----
-title: PitchFight AI
-emoji: ⚔️
-colorFrom: red
-colorTo: yellow
-sdk: gradio
-app_file: app.py
-pinned: false
----
-```
-
-### Core Environment Variables
-
-Set in HF Space Secrets and local `.env` (never commit real keys):
-
-```text
-APP_ENV=production
-MAX_ROUNDS=6
-
-NVIDIA_API_KEY=<hf-space-secret>
-NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
-NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
-
-OPENBMB_API_KEY=<hf-space-secret>
-OPENBMB_BASE_URL=
-MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
-MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
-MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
-
-HF_TOKEN=<hf-space-secret>
-WHISPER_FALLBACK_ENABLED=true
-WHISPER_MODEL_SIZE=tiny
-```
-
-Do **not** expose keys in frontend code, README, or public repos.
-
-### Required `packages.txt`
-
-```text
-ffmpeg
-```
-
-### Important Security Rules
-
-- Never commit real API keys.
-- Never put keys in frontend JavaScript.
-- Use `.env` locally only for configuration.
-- Add `.env` to `.gitignore`.
-- Sponsor model API keys (NVIDIA, OpenBMB) are required for the premium demo path; they stay backend-only.
-
----
-
-## 18. Final Deployment File Structure
-
-```text
-pitchfight-ai/
-│
-├── app.py
-├── requirements.txt
-├── packages.txt
-├── README.md
-├── .env.example
-├── .gitignore
-│
-├── core/
-│   ├── __init__.py
-│   ├── api_handlers.py
-│   ├── session_manager.py
-│   ├── persona_builder.py
-│   ├── attack_tags.py
-│   ├── model_router.py
-│   ├── nvidia_client.py
-│   ├── minicpm_client.py
-│   ├── vision_client.py
-│   ├── transcription_client.py
-│   ├── scoring_engine.py
-│   ├── feedback_generator.py
-│   ├── json_utils.py
-│   └── samples.py
-│
-├── config/
-│   ├── personas.json
-│   ├── attack_tags.json
-│   ├── pitch_rubric.json
-│   ├── deal_rubric.json
-│   └── sample_startups.json
-│
-├── frontend/
-│   ├── index.html
-│   ├── styles.css
-│   ├── script.js
-│   └── assets/
-│       ├── logo.svg
-│       └── icons/
-│
-├── docs/
-│   ├── DOCUMENTATION.md
-│   ├── PROMPTS.md
-│   ├── DEMO_NOTES.md
-│   └── FIELD_NOTES.md
-│
-└── tests/
-    ├── test_prompts.py
-    ├── test_attack_tags.py
-    └── test_json_parser.py
-```
-
----
-
-## 19. File Responsibilities
-
-### `app.py`
-
-Main Gradio Server entry point.
-
-Responsibilities:
-
-- Create `gradio.Server`
-- Serve custom `frontend/index.html`
-- Serve static CSS/JS/assets
-- Expose backend APIs
-- Launch app
-
-### `core/session_manager.py`
-
-Stores active battle sessions.
-
-Responsibilities:
-
-- Create sessions
-- Store conversation history
-- Track rounds
-- Track persona and mode
-- Track attack tags
-- Return full conversation for scoring
-
-### `core/persona_builder.py`
-
-Builds persona prompts.
-
-Responsibilities:
-
-- Load persona config
-- Inject startup or negotiation context
-- Add difficulty rules
-- Add current attack tag
-- Return system prompt
-
-### `core/attack_tags.py`
-
-Controls structured pressure flow.
-
-Responsibilities:
-
-- Store attack tag taxonomy
-- Select next attack tag per persona
-- Avoid repeating the same attack tag too often
-- Increase pressure as rounds progress
-
-### `core/model_router.py`
-
-Backend-only model routing (Phase 2+).
-
-Responsibilities:
-
-- Text battle → NVIDIA Nemotron Omni by default; MiniCPM5-1B on failure
-- Voice input → Nemotron Omni primary; faster-whisper transcription fallback
-- OpenBMB omni mode → MiniCPM-o 4.5
-- Deck critique → MiniCPM-V 4.6 or Nemotron vision path
-- Expose active mode badge to frontend (`premium_nvidia`, `openbmb_omni`, `tiny_minicpm`, etc.)
-
-### `core/nvidia_client.py`
-
-Secure NVIDIA Nemotron Omni client (Phase 2+).
-
-Responsibilities:
-
-- Backend-only API calls via `NVIDIA_API_KEY`
-- Text, voice, multimodal judge responses
-- Scorecard and rewrite generation
-- Timeout / retry handling
-
-### `core/minicpm_client.py`
-
-OpenBMB MiniCPM backend client (Phase 2+).
-
-Responsibilities:
-
-- MiniCPM-o omni mode
-- MiniCPM5-1B tiny / fallback text generation
-
-### `core/transcription_client.py`
-
-Voice transcription fallback.
-
-Responsibilities:
-
-- Accept audio file
-- Run faster-whisper locally when Omni voice path fails
-- Return transcript for model router
-
-### `core/vision_client.py`
-
-Deck critique vision client (Phase 2+).
-
-Responsibilities:
-
-- Route slide images to MiniCPM-V 4.6 or Nemotron vision path
-
-### `core/scoring_engine.py`
-
-Generates scorecard.
-
-Responsibilities:
-
-- Build scoring prompt
-- Call model router (Nemotron default, MiniCPM5 fallback)
-- Parse JSON
-- Use fallback strategy if JSON breaks
-
-### `core/feedback_generator.py`
-
-Generates improved answers.
-
-Responsibilities:
-
-- Rewrite weakest answer
-- Generate improved pitch
-- Generate top 3 prep questions
-
-### `core/json_utils.py`
-
-Keeps frontend stable.
-
-Responsibilities:
-
-- Parse scorecard JSON
-- Repair malformed JSON
-- Extract fallback sections
-- Return default schema if needed
-
-### `frontend/index.html`
-
-Custom UI shell.
-
-Responsibilities:
-
-- Landing page
-- Mode selector
-- Form screens
-- Battle arena
-- Scorecard layout
-
-### `frontend/script.js`
-
-Frontend logic.
-
-Responsibilities:
-
-- Call `/api/*` endpoints via `fetch()` only — never model provider APIs
-- Manage UI state
-- Render messages and scorecards
-- Handle audio recording
-
-### `frontend/styles.css`
-
-Visual polish.
-
-Responsibilities:
-
-- Dark battle theme
-- Cards
-- Animations
-- Responsive layout
-- Score bars
-- Pressure meter
-
----
-
-## 20. Development Phases
-
-> **Authoritative roadmap:** [`PHASE_WISE_PLAN.md`](PHASE_WISE_PLAN.md) (14 phases, sponsor-model strategy). The summary below aligns with that plan.
-
-This section describes the build order at a high level. The project can be built fast, but the documentation should not contradict itself by calling a full build a “one-day plan.”
-
-### Phase 1 — Project Skeleton
-
-Goal: create working HF Spaces-compatible Gradio Server app.
-
-Deliverables:
-
-- `app.py`
-- custom homepage
-- `requirements.txt`
-- `packages.txt`
-- README metadata
-
-Success check:
-
-```text
-python app.py
-```
-
-opens the custom UI.
-
----
-
-### Phase 2 — Model Router + Secrets (see PHASE_WISE_PLAN.md)
-
-Goal: backend-only model routing with `DEFAULT_MODEL_MODE=premium_nvidia`.
-
----
-
-### Phase 3 — Text Battle Engine
-
-Goal: get core pitch battle working.
-
-Deliverables:
-
-- session manager
-- persona builder
-- attack tag selector
-- `/start_session`
-- `/chat_round`
-
-Success check:
-
-```text
-User can start a pitch battle and get hard follow-up questions.
-```
-
----
-
-### Phase 4 — Scorecard Engine
-
-Goal: turn chat into useful feedback.
-
-Deliverables:
-
-- scoring prompt
-- JSON parser
-- fallback parser
-- `/end_battle`
-- scorecard UI
-
-Success check:
-
-```text
-User ends battle and sees 6 scores, weakest answer, improved answer, and improved pitch.
-```
-
----
-
-### Phase 5 — Custom UI Polish
-
-Goal: make it look like a product.
-
-Deliverables:
-
-- battle arena layout
-- round counter
-- pressure meter
-- persona cards
-- attack tag display
-- score animation
-- loading states
-
-Success check:
-
-```text
-The app visually feels different from default Gradio.
-```
-
----
-
-### Phase 6 — Voice Pitch Mode
-
-Goal: Nemotron Omni primary voice path; faster-whisper transcription fallback only.
-
-Deliverables:
-
-- browser audio recorder
-- `/api/voice-pitch`
-- `transcription_client.py` (faster-whisper fallback)
-- transcript panel
-- text battle continuation from voice input
-
-Success check:
-
-```text
-User records a pitch and receives a hard first question via Nemotron (or whisper → text fallback).
-```
-
----
-
-### Phase 7 — NVIDIA Nemotron Integration (primary)
-
-Goal: Nemotron Omni 30B-A3B as default premium judge (backend-only API).
-
-Deliverables:
-
-- `nvidia_client.py`
-- model router default `premium_nvidia`
-- MiniCPM5-1B fallback on failure
-
-Success check:
-
-```text
-Backend returns sharp judge questions and scorecards via Nemotron; app degrades to MiniCPM5 on failure.
-```
-
----
-
-### Phase 8 — Deployment
-
-Goal: deploy to Hugging Face Spaces.
-
-Deliverables:
-
-- push repo
-- set non-secret config if needed
-- verify app runs publicly
-- test full flow
-
-Success check:
-
-```text
-HF Space link opens and completes one full battle.
-```
-
----
-
-## 21. Minimum Viable Winning Version
-
-If time gets tight, ship this:
-
-- Pitch Battle only
-- Text input only
-- 3 personas
-- Attack tags
-- 6-round chat
-- NVIDIA Nemotron Omni via backend (MiniCPM5-1B fallback)
-- Scorecard
-- Improved answer
-- Custom UI
-- HF Spaces deployment
-
-Then add Voice Mode after deployment.
-
----
-
-## 22. Full Winning Version
-
-Best final version:
-
-- Pitch Battle
-- Deal Battle
-- Local Voice Mode
-- 3 pitch personas
-- 2 negotiation personas
-- Attack tags
-- Scorecard
-- Improved answer
-- Retry weak question
-- Custom Gradio Server UI
-- HF Spaces deployment
-- Documentation
-- Field Notes
-- Public prompts and rubrics
-- NVIDIA Nemotron + OpenBMB MiniCPM sponsor-model stack
-
----
-
-## 23. Badge / Prize Strategy
-
-| Target | How PitchFight AI Qualifies |
-|---|---|
-| Backyard AI | Built for student founders with a real high-pressure problem |
-| Best Demo | Voice + text pitch battle → scorecard in one polished flow |
-| Best Agent | Persona + memory + attack-tag planning + evaluation loop |
-| Off-Brand | Custom frontend using Gradio Server instead of default Gradio UI |
-| NVIDIA Nemotron Quest | Nemotron Omni as premium voice/multimodal judge |
-| OpenBMB Awards | MiniCPM-o, MiniCPM5-1B, MiniCPM-V integration |
-| Tiny Titan | MiniCPM5-1B Tiny Mode fallback |
-| Sharing is Caring | Publish prompts, rubrics, attack tags, sample scenarios |
-| Field Notes | Write short build post after deployment |
-| ~~Off the Grid~~ | **Not targeted** — sponsor APIs used intentionally for demo quality |
-
----
-
-## 24. Environment and Safety
-
-Use this `.env.example`:
-
-```text
-APP_ENV=development
-MAX_ROUNDS=6
-
-NVIDIA_API_KEY=
-NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
-NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
-
-OPENBMB_API_KEY=
-OPENBMB_BASE_URL=
-MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
-MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
-MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
-
-HF_TOKEN=
-WHISPER_FALLBACK_ENABLED=true
-WHISPER_MODEL_SIZE=tiny
-```
-
-Use this `.gitignore`:
-
-```text
-.env
-__pycache__/
-*.pyc
-.DS_Store
-node_modules/
-.gradio/
-models/
-*.gguf
-```
-
-Security rules:
-
-- Do not commit API keys.
-- Do not call model APIs from frontend JS — frontend uses `/api/*` only.
-- Store keys in `.env` locally and HF Space Secrets in deployment.
-- NVIDIA and OpenBMB sponsor APIs are the intended default inference path (backend-only).
-
----
-
-## 25. Sample Demo Startup
-
-```json
-{
-  "name": "EventRadar AI",
-  "problem": "Students miss hackathons, tech events, and startup opportunities because discovery is scattered across WhatsApp groups, LinkedIn, Luma, college clubs, and random websites.",
-  "target_users": "College students, student founders, and early-stage builders.",
-  "solution": "AI-powered event discovery that ranks opportunities based on skills, goals, location, and deadline urgency.",
-  "why_ai": "The app does not just list events. It matches events to a student's profile and explains why each event is worth attending.",
-  "competitors": "Luma, LinkedIn Events, WhatsApp groups, college club pages.",
-  "traction": "Prototype built with scraped event data and ranking logic.",
-  "ask": "Hackathon prize and mentor feedback."
-}
-```
-
----
-
-## 26. Demo Flow
-
-1. Open app.
-2. Click “Load Demo Startup”.
-3. Select “Hackathon Judge”.
-4. Choose “Text Battle” or “Voice Pitch”.
-5. AI asks:  
-   “Why does this need AI? A sorted event list with filters seems enough.”
-6. User gives a weak answer.
-7. AI selects an attack tag such as “Retention” and pushes back harder.
-8. End battle.
-9. Scorecard shows:
-   - Overall score
-   - 6 rubric scores
-   - Weakest answer
-   - Improved answer
-   - Improved 60-second pitch
-   - Top 3 prep questions
-
-Final spoken line:
-
-> **That is PitchFight AI — your first tough pitch should not be in front of a real judge.**
-
----
-
-## 27. Final Implementation Checklist
-
-### Core
-
-- [ ] Custom Gradio Server app runs
-- [ ] Frontend loads from `frontend/index.html`
-- [ ] Frontend calls `/api/*` only (no direct model API calls)
-- [ ] Model router + Nemotron client wired (Phase 2+)
-- [ ] Session creation works
-- [ ] Persona prompt works
-- [ ] Attack tag selector works
-- [ ] Chat round works
-- [ ] Scorecard works
-- [ ] JSON parsing fallback works
-- [ ] Sample startup loads
-
-### Voice
-
-- [ ] Browser recorder works
-- [ ] Audio file reaches backend
-- [ ] faster-whisper transcribes locally
-- [ ] Transcript becomes usable context
-- [ ] AI asks voice-based first question
-
-### NVIDIA Nemotron (primary)
-
-- [ ] Backend-only Nemotron client uses HF Space Secrets / `.env`
-- [ ] MiniCPM5-1B fallback when Nemotron fails or keys missing
-- [ ] Model mode badge visible in UI
-
-### Deployment
-
-- [ ] HF Space created
-- [ ] README metadata added
-- [ ] `packages.txt` includes ffmpeg
-- [ ] App builds
-- [ ] Full flow tested publicly
-- [ ] No API keys exposed in frontend or public repo
-- [ ] Model router fallbacks tested when sponsor APIs fail
-
----
-
-## 28. Final One-Line Description
-
-**PitchFight AI is a voice-and-text AI sparring arena where student founders practice tough startup pitches, get grilled by realistic AI judges under 32B parameters, and receive a scorecard that shows exactly how to answer better.**
-
----
-
-## 29. Final Project Promise
-
-PitchFight AI is not trying to replace mentors or investors.
-
-It prepares student founders for them.
-
-> **The goal is simple: make the first hard question happen inside the app — not on stage.**
-
----
-
-## 30. Reference Notes
-
-- Off-the-Grid is **not** targeted; sponsor-model APIs (NVIDIA, OpenBMB) power the default high-quality demo.
-- All models ≤32B; Gradio Server + custom HTML/CSS/JS frontend.
-- `core/model_router.py` selects premium_nvidia, openbmb_omni, tiny_minicpm, vision_deck, whisper_fallback.
-- API keys only in HF Space Secrets / backend `os.getenv`.
-- See `PHASE_WISE_PLAN.md` for the 14-phase implementation roadmap.

docs/FIELD_NOTES.md

@@ -1,92 +0,0 @@
-# PitchFight AI — Field Notes
-
-## Why This Exists
-
-Student founders often practice pitches alone or with friendly feedback. The first real pressure hits during judging, mentoring, investor calls, or sponsorship negotiations. PitchFight AI creates a safe but intense sparring arena before that moment.
-
-## Strategic Pivot (Phase 0)
-
-We moved from an **Off-the-Grid / local-first** strategy to a **high-demo sponsor-model** strategy:
-
-- **Not targeting** Off-the-Grid badge.
-- **Targeting** Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, Field Notes.
-- Still compliant: ≤32B models, Gradio, HF Spaces, no frontend API keys.
-
-## What Was Built
-
-### Phase 1 (Complete)
-
-- Hugging Face Spaces-ready Gradio Server skeleton
-- Custom battle arena frontend (HTML/CSS/JS)
-- In-memory session manager
-- Persona + attack-tag routing
-- Mock scoring and feedback (placeholder for real models)
-- Config files for personas, rubric, samples
-
-### Planned (Phases 2–14)
-
-- Model router + NVIDIA / OpenBMB clients
-- Real Pitch Battle + Deal Battle engines
-- Voice pitch mode (Nemotron primary, whisper fallback)
-- Pitch deck critique (MiniCPM-V)
-- Retry weakest question + downloadable report
-- UI polish + public HF Space deployment
-
-## What the Models Will Do
-
-| Model | Job |
-|---|---|
-| Nemotron Omni | Premium judge, voice, scoring, rewrites |
-| MiniCPM-o | OpenBMB multimodal mode |
-| MiniCPM5-1B | Tiny/fallback text |
-| MiniCPM-V 4.6 | Slide critique |
-| faster-whisper | Backup transcription |
-
-## What Worked
-
-- Clean separation: frontend → Gradio API → model router → clients
-- Attack-tag driven pressure design
-- Runnable Phase 1 skeleton for fast iteration
-- Clear phase-wise plan for hackathon execution
-
-## What Will Be Improved
-
-- Replace mock APIs with Nemotron + MiniCPM routing (Phase 2–5)
-- Voice mode as headline demo feature (Phase 7)
-- Deal Battle + deck critique (Phases 8–10)
-- Product polish and public deployment (Phases 12–14)
-
-## Build Log
-
-### Phase 2 — Model Router + Secrets Setup (2026-06-08)
-
-**What shipped:**
-- `core/nvidia_client.py` — backend-only NVIDIA Nemotron client using OpenAI-compatible SDK
-- `core/model_router.py` — central routing layer (premium_nvidia live; other modes return clean stubs)
-- `core/minicpm_client.py` — health_check stub (Phase 9 placeholder)
-- `core/vision_client.py` — health_check stub (Phase 10 placeholder)
-- `core/transcription_client.py` — health_check stub (Phase 7 placeholder)
-- `scripts/test_nvidia_client.py` — isolated connectivity test (exits 0/1, no key exposure)
-- `GET /api/model-health` — config status endpoint, keys never exposed
-- `requirements.txt` updated: added `openai>=1.0.0`, `httpx`, `requests`
-
-**What worked:**
-- NVIDIA API key read from `NVIDIA_API_KEY` env var only — no hardcoding, no key leak
-- `health_check()` correctly reports configured/not-configured without printing key
-- `generate_nemotron_response()` returns clean judge question on first real test
-- `get_model_health()` returns correct provider status for all four providers
-- Error handling catches timeout, connection, and status errors cleanly
-
-**What surprised us:**
-- `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` is a **reasoning model**: it writes an internal chain-of-thought before the final answer. When `max_tokens` is too small (< ~400 for opponent mode), all tokens are consumed by the reasoning trace and `message.content` is `None`.
-- The fix: increase `max_tokens` defaults (opponent: 500, scorecard: 2000, rewrite: 800) and add a `reasoning_content` fallback for edge cases.
-- The final answer in `message.content` is sharp, in-character, and correctly short — the reasoning trace stays internal.
-
-**What the model returned (live test):**
-> "How does your AI differentiate between similar events and avoid false positives in ranking?"
-
-**What we'd do differently:**
-- Test with the actual model before setting token defaults — reasoning models have different budget dynamics than completion models.
-
-**What's next:**
-- Phase 3: Wire `model_router.generate_opponent_response()` into `handle_start_session` and `handle_chat_round` in `core/api_handlers.py` — replacing hardcoded mock followups with live Nemotron responses.

docs/MODELS_FINAL.md

@@ -1,434 +0,0 @@
-# PitchFight AI — Final Model Strategy
-
-## High-Demo Sponsor-Model Stack Under 32B Parameters
-
----
-
-## 1. Final Model Philosophy
-
-PitchFight AI prioritizes:
-
-- **Best demonstrative experience** — the app must feel like a real sparring arena, not a chatbot wrapper.
-- **Voice-first pitch practice** — founders pitch out loud; the judge responds with pressure, not generic advice.
-- **High-quality AI judge behavior** — persona-locked opponents, attack tags, memory, and sharp follow-ups.
-- **Sponsor-model alignment** — NVIDIA Nemotron Omni and OpenBMB MiniCPM models used intentionally and visibly.
-- **Strong fallback reliability** — if a premium endpoint fails, the app degrades gracefully instead of breaking the demo.
-- **Models under 32B parameters** — every reasoning model in the stack complies with the Build Small Hackathon cap.
-
-The project is **not** targeting the **Off-the-Grid** badge. This is intentional — Off-the-Grid is not part of this build.
-
-The app **does** follow the required hackathon rules:
-
-- **≤32B models** for all core reasoning
-- **Gradio** + **Hugging Face Spaces** hosting
-- **Demo-first** execution with a custom non-default UI
-
-**Target badges/prizes:** Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, and Field Notes.
-
-Cloud/sponsor model APIs are **allowed and expected** for this build when called **backend-only** with keys in HF Space Secrets. They are not forbidden — they are the default path to demo quality.
-
----
-
-## 2. Final Default Model Stack
-
-| Layer | Final Model | Default? | Purpose |
-|---|---|---:|---|
-| Premium reasoning + voice/multimodal judge | NVIDIA Nemotron 3 Nano Omni 30B-A3B | Yes | Main voice/text judge, pitch battle, deal battle, scorecard, voice critique |
-| OpenBMB omni mode | MiniCPM-o 4.5 | Secondary | OpenBMB-aligned omni mode for voice/text/multimodal pitch interaction |
-| Tiny fallback | MiniCPM5-1B | Fallback | Fast text battle, scorecard fallback, Tiny Mode |
-| Vision/deck critique | MiniCPM-V 4.6 | Feature mode | Pitch deck screenshot critique and visual pitch feedback |
-| Audio fallback | faster-whisper / Whisper Tiny or Base | Fallback | Audio transcription if direct audio handling is unstable |
-| Optional multilingual | Cohere Aya or suitable small multilingual model | Optional | Hindi/Kannada/regional pitch practice if added |
-| Optional visuals | FLUX / Black Forest Labs model | Optional assets only | Persona art or visual assets, not core reasoning |
-
----
-
-## 3. Primary Model — NVIDIA Nemotron 3 Nano Omni 30B-A3B
-
-> **Deep dive:** How Omni processes raw audio, paralinguistic signals, hesitation detection, and PitchFight voice paths A/B — see [`NEMOTRON_OMNI_AUDIO.md`](NEMOTRON_OMNI_AUDIO.md).
-
-### Role
-
-Primary premium model for the strongest demo.
-
-### Use cases
-
-- Voice pitch understanding
-- AI opponent responses
-- Pitch Battle
-- Deal Battle
-- Multimodal pitch judging
-- Scorecard generation
-- Weakest answer rewrite
-- Improved pitch generation
-- Voice-specific feedback
-- Optional pitch deck + spoken pitch critique
-
-### Why
-
-- Strong sponsor alignment (NVIDIA Nemotron Quest)
-- Multimodal / omni capability
-- Under 32B total parameter rule
-- Best fit for high-quality voice demo
-- Targets NVIDIA Nemotron Quest
-
-### Implementation
-
-- Backend-only API call.
-- API key stored in HF Space Secrets.
-- Frontend never calls NVIDIA directly.
-- Model call goes through `core/nvidia_client.py` and `core/model_router.py`.
-
-### Environment variables
-
-```text
-NVIDIA_API_KEY=
-NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
-NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
-```
-
-### Suggested settings
-
-| Task | Temperature | Max Tokens |
-|---|---:|---:|
-| Opponent response | 0.7 | 250 |
-| Scorecard | 0.2 | 1200 |
-| Rewrite | 0.45 | 500 |
-
----
-
-## 4. OpenBMB Mode — MiniCPM-o 4.5
-
-### Role
-
-OpenBMB-aligned advanced omni model.
-
-### Use cases
-
-- Alternative voice judge mode
-- Speech/text pitch interaction
-- OpenBMB sponsor route
-- Model comparison mode
-- Optional multimodal interaction
-
-### Why
-
-- 9B model, under 32B
-- Strong OpenBMB alignment
-- Supports omnimodal interaction
-- Useful for OpenBMB Awards
-- Smaller than Nemotron
-
-### Implementation
-
-- Backend-only API call or supported official endpoint.
-- Keep separate from NVIDIA path.
-- Can be exposed in UI as **“OpenBMB Omni Mode”**.
-
-### Environment variables
-
-```text
-OPENBMB_API_KEY=
-OPENBMB_BASE_URL=
-MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
-```
-
----
-
-## 5. Tiny / Fallback Mode — MiniCPM5-1B
-
-### Role
-
-Reliable small fallback model.
-
-### Use cases
-
-- Text Pitch Battle fallback
-- Deal Battle fallback
-- Scorecard fallback
-- Tiny Mode
-- Low-latency text mode
-- Tiny Titan angle if shipped well
-
-### Why
-
-- Very small
-- OpenBMB-aligned
-- Good backup if premium endpoints are slow
-- Keeps app usable during API failures
-
-### Implementation
-
-- Use through backend model router.
-- Can be local or hosted depending on final deployment.
-- If using API, clearly do not claim Off-the-Grid.
-- If local, can be mentioned as optional local fallback.
-
-### Environment variables
-
-```text
-MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
-MINICPM_TEXT_BACKEND=api_or_local
-```
-
----
-
-## 6. Vision Mode — MiniCPM-V 4.6
-
-### Role
-
-Pitch deck screenshot critique.
-
-### Use cases
-
-- Upload slide screenshot
-- Extract visible claims
-- Critique clarity
-- Critique problem/solution/market/ask
-- Generate judge questions from slide
-
-### Why
-
-- OpenBMB-aligned
-- Small visual model
-- Strong demo feature
-- Adds multimodal value beyond chat
-
-### Implementation
-
-- Add `/deck_critique` endpoint.
-- Frontend image upload.
-- Backend routes image to MiniCPM-V or NVIDIA Omni.
-- Show slide critique card.
-
-### Environment variables
-
-```text
-MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
-```
-
----
-
-## 7. Audio Fallback — faster-whisper
-
-### Role
-
-Backup transcription.
-
-### Use cases
-
-- Convert audio to transcript if direct omni audio fails
-- Debug voice input
-- Allow browser-recorded audio to become text reliably
-
-### Why
-
-- Reliable
-- Simple
-- Helps prevent voice demo failure
-
-### Implementation
-
-- **Not** the main judge.
-- Only audio-to-text fallback.
-- Transcript then goes into selected reasoning model.
-
-### Environment variables
-
-```text
-WHISPER_FALLBACK_ENABLED=true
-WHISPER_MODEL_SIZE=tiny
-```
-
----
-
-## 8. Model Router
-
-Routing logic for `core/model_router.py`:
-
-### Text Pitch Battle
-
-```text
-startup context + persona + attack tag
-  → NVIDIA Nemotron by default
-  → MiniCPM5-1B fallback if NVIDIA fails
-```
-
-### Voice Pitch
-
-```text
-audio
-  → NVIDIA Nemotron Omni primary
-  → if fails: faster-whisper transcription
-  → MiniCPM5-1B or Nemotron text path
-```
-
-### Deal Battle
-
-```text
-negotiation context
-  → NVIDIA Nemotron by default
-  → MiniCPM5-1B fallback
-```
-
-### Scorecard
-
-```text
-conversation history
-  → NVIDIA Nemotron by default
-  → MiniCPM5-1B fallback
-  → json_utils parser + fallback_scorecard()
-```
-
-### Deck Critique
-
-```text
-image
-  → MiniCPM-V 4.6 or NVIDIA Omni
-  → slide critique + judge questions
-```
-
-### OpenBMB Mode
-
-```text
-user-selected
-  → MiniCPM-o 4.5
-```
-
-### Tiny Mode
-
-```text
-user-selected or automatic fallback
-  → MiniCPM5-1B
-```
-
----
-
-## 9. Model-to-File Mapping
-
-| File | Responsibility | Phase 2 Status |
-|---|---|---|
-| `core/model_router.py` | Routes tasks to NVIDIA, MiniCPM-o, MiniCPM5, MiniCPM-V, or Whisper fallback | **Created** — premium_nvidia live; other modes stub |
-| `core/nvidia_client.py` | Calls NVIDIA Nemotron Omni backend-only | **Created** — live, tested |
-| `core/minicpm_client.py` | Calls MiniCPM-o and MiniCPM5 paths | **Stub** — health_check only (Phase 9) |
-| `core/vision_client.py` | Handles MiniCPM-V / deck critique model calls | **Stub** — health_check only (Phase 10) |
-| `core/transcription_client.py` | Handles faster-whisper fallback transcription | **Stub** — health_check only (Phase 7) |
-| `core/session_manager.py` | Stores selected model mode and conversation history | Existing — unchanged |
-| `core/persona_builder.py` | Builds prompt before model call | Existing — unchanged |
-| `core/attack_tags.py` | Selects pressure direction before model call | Existing — unchanged |
-| `core/scoring_engine.py` | Builds scorecard prompt and calls model_router | Existing — still mock (Phase 5) |
-
-> **Reasoning model token note:** `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` writes an internal chain-of-thought before producing `message.content`. Confirmed defaults: opponent=500, scorecard=2000, rewrite=800 tokens.
-| `core/json_utils.py` | Repairs/parses model-generated scorecards |
-
----
-
-## 10. Environment Variables
-
-Final environment block:
-
-```text
-APP_ENV=development
-MAX_ROUNDS=6
-
-DEFAULT_MODEL_MODE=premium_nvidia
-
-NVIDIA_API_KEY=
-NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
-NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
-
-OPENBMB_API_KEY=
-OPENBMB_BASE_URL=
-MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
-MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
-MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
-
-HF_TOKEN=
-
-WHISPER_FALLBACK_ENABLED=true
-WHISPER_MODEL_SIZE=tiny
-
-ENABLE_DECK_CRITIQUE=true
-ENABLE_DEAL_BATTLE=true
-ENABLE_VOICE_MODE=true
-```
-
-**Security rules:**
-
-- API keys must be **backend-only**.
-- Use **HF Space Secrets** in production.
-- Never expose keys in frontend JS.
-- Do not commit `.env`.
-
----
-
-## 11. Requirements Strategy
-
-### Skeleton (always)
-
-```text
-gradio
-fastapi
-uvicorn
-pydantic
-python-dotenv
-numpy
-```
-
-### API/model clients
-
-```text
-openai
-requests
-httpx
-```
-
-### Voice fallback
-
-```text
-faster-whisper
-```
-
-### Audio/system
-
-```text
-packages.txt includes ffmpeg
-```
-
-### Optional image handling
-
-```text
-pillow
-```
-
-**Note:** Do not add heavy local inference dependencies unless needed. This build prioritizes **API-backed sponsor models** for demo quality. Local inference (e.g. llama-cpp-python) is optional for Tiny Mode fallback only — not the default path.
-
----
-
-## 12. Model Architecture Diagram
-
-```mermaid
-flowchart TD
-    A[User Text Pitch] --> B[Custom Gradio UI]
-    C[User Voice Pitch] --> B
-    D[Pitch Deck Screenshot] --> B
-
-    B --> E[Gradio Server Backend]
-    E --> F[Model Router]
-
-    F --> G[NVIDIA Nemotron Omni\nPremium Judge Mode]
-    F --> H[MiniCPM-o 4.5\nOpenBMB Omni Mode]
-    F --> I[MiniCPM5-1B\nTiny/Fallback Mode]
-    F --> J[MiniCPM-V 4.6\nDeck Critique Mode]
-    F --> K[faster-whisper\nAudio Fallback]
-
-    G --> L[Opponent Response + Scorecard]
-    H --> L
-    I --> L
-    J --> M[Slide Critique + Judge Questions]
-    K --> N[Transcript]
-    N --> F
-
-    L --> O[Battle Arena UI]
-    M --> O
-```

docs/NEMOTRON_OMNI_AUDIO.md

@@ -1,294 +0,0 @@
-# NVIDIA Nemotron 3 Nano Omni — Audio & Voice Architecture
-
-Technical reference for how **NVIDIA Nemotron 3 Nano Omni 30B-A3B** processes pitch audio in PitchFight AI, what it can infer about hesitation and confidence, and how the app should wire voice mode.
-
-> **PitchFight context:** Nemotron Omni is the **primary premium judge** (backend-only API). Raw audio goes to the model on the primary path. **faster-whisper** is transcription fallback only — not the main judge. Frontend never calls NVIDIA directly; audio flows through `/api/voice-pitch`.
-
-See also: [`MODELS_FINAL.md`](MODELS_FINAL.md) · [`BACKEND_API.md`](BACKEND_API.md) · [`PHASE_WISE_PLAN.md`](PHASE_WISE_PLAN.md)
-
----
-
-## 1. Model Identity
-
-| Field | Value |
-|---|---|
-| **Model** | NVIDIA Nemotron 3 Nano Omni 30B-A3B |
-| **Env var** | `NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` |
-| **Parameter cap** | ~30B — complies with Build Small ≤32B rule |
-| **Access** | Backend-only via `NVIDIA_API_KEY` + `NVIDIA_BASE_URL` |
-| **Role in PitchFight** | Primary voice/text/multimodal judge, scorecard, rewrites |
-
----
-
-## 2. How the Model Works With Audio
-
-### Unified encoder–projector–decoder design
-
-NeMoTron Nano Omni uses a **unified multimodal architecture**:
-
-- **Language backbone:** Nemotron 3 Nano 30B-A3B (reasoning)
-- **Vision encoder:** C-RADIOv4-H
-- **Audio encoder:** Parakeet-TDT-0.6B-v2
-
-Modality-specific encoders connect into the LLM backbone through **lightweight projectors**. Audio and text share the same reasoning loop inside the backbone.
-
-### Exact pipeline when an audio file hits the model
-
-```text
-Your WAV / audio file (raw bytes)
-        ↓
-Parakeet-TDT-0.6B-v2 (dedicated audio encoder)
-        ↓ converts audio into audio tokens
-Lightweight projector (aligns audio tokens to LLM embedding space)
-        ↓
-Nemotron 30B-A3B backbone (reasoning happens here)
-        ↓
-Structured text output (transcript, observations, judge question, etc.)
-```
-
-### What this is *not*
-
-This is **fundamentally different** from Whisper → LLM:
-
-| Approach | Flow |
-|---|---|
-| **Whisper → LLM** | Audio → text transcript → text-only reasoning |
-| **Nemotron Omni (primary path)** | Audio → audio tokens → projected embeddings → unified reasoning |
-
-On the Nemotron primary path, the model does **not** need to transcribe to plain text first before reasoning. Audio signals are preserved as tokens that flow into the backbone.
-
-### Paralinguistic coverage
-
-Parakeet provides strong ASR. NVIDIA extends the audio surface with **Granary** and **Music Flamingo** extensions, broadening coverage beyond bare transcription to include:
-
-- Paralinguistic signals (tone, pace, stress, hesitation sounds)
-- Music and ambient sound understanding
-
-**Paralinguistic** = signals beyond literal words — how something is said, not only what is said. This is what makes the model competitive on voice benchmarks and useful for media understanding, not just dictation.
-
----
-
-## 3. Quick Answers (FAQ)
-
-| Question | Answer |
-|---|---|
-| Does the raw audio file go to Nemotron? | **Yes** — Parakeet processes native audio input. |
-| Does it get transcribed to text first? | **No** on the primary Omni path — audio tokens flow directly into reasoning. |
-| Does it use embeddings? | **Yes** — audio tokens are projected into the LLM embedding space. |
-| Can it detect hesitation? | **Yes** — linguistic hesitation and filler words reliably. |
-| Can it detect confidence from voice tone? | **Partially** — paralinguistic inference, not clinical prosody analysis. |
-| Is this strong enough for a pitch trainer? | **Yes** — linguistic hesitation is the most actionable signal for founders. |
-| How do you make it accurate? | **Prompt explicitly** for delivery observations alongside content. |
-
----
-
-## 4. Hesitation & Confidence Detection
-
-### Partially yes — with important caveats
-
-#### What it can detect reliably
-
-The Parakeet encoder (with Granary / Music Flamingo extensions) processes **paralinguistic features**. When preserved as audio tokens in the backbone, the LLM can reason about:
-
-| Signal | Example |
-|---|---|
-| Filler words | "um", "uh", "like", "you know" |
-| Long pauses | Mid-sentence gaps before a key claim |
-| Trailing off | Weak endings on important statements |
-| Rushed speech | Compressed delivery on uncertain phrases |
-| Repetition / self-correction | Restarts, hedging, reformulations |
-
-For pitch training, **linguistic hesitation is often the most useful signal**:
-
-> *"Um… I think… maybe the market is… around 10 million?"*  
-> vs  
-> *"The addressable market is $10M based on X."*
-
-The model can flag the first pattern when prompted correctly.
-
-#### What it cannot detect reliably
-
-Pure acoustic / physiological confidence signals require dedicated prosody tools (e.g. Praat, specialized emotion models), not a general-purpose multimodal LLM:
-
-- Heart rate change
-- Micro-tremors in voice
-- Subtle pitch drops indicating clinical-level uncertainty
-
-**Do not claim** heart-rate or micro-tremor detection in PitchFight UI or demo script.
-
-#### Honest positioning
-
-NeMoTron can detect **linguistic hesitation** (words and sounds of hesitation) and make **reasonable inferences** about apparent confidence from speech patterns. It cannot do **clinical-grade prosody analysis**. For a student pitch trainer, that is the right tradeoff.
-
----
-
-## 5. Voice Scorecard Metrics (Grounded in Architecture)
-
-Only score dimensions the model can plausibly observe:
-
-| Metric | How Nemotron detects it | Reliability |
-|---|---|---|
-| Filler word count | Direct from audio tokens + transcript | **High** |
-| Pause before key claims | Temporal gap in audio | **Medium–High** |
-| Self-corrections | Restarts in transcript / audio pattern | **High** |
-| Trailing off on weak claims | Audio token patterns | **Medium** |
-| Speaking pace (rushed vs calm) | Token density over time | **Medium** |
-| Confidence on specific claims | Inference from above signals | **Medium** |
-
-When on **Whisper fallback**, mark voice-derived metrics as unavailable or transcript-only.
-
----
-
-## 6. PitchFight AI Voice Architecture
-
-### Path A — Nemotron direct (primary, when API available)
-
-```text
-Browser records audio
-        ↓
-POST /api/voice-pitch (backend only)
-        ↓
-NVIDIA Nemotron Omni
-        ↓
-Parakeet encoder processes raw audio
-        ↓
-Paralinguistic + linguistic signals preserved in backbone
-        ↓
-Single API response includes:
-  - transcript
-  - delivery_observations (hesitation / pace / fillers)
-  - detected_startup_context
-  - opening judge question
-        ↓
-Pitch Battle continues (voice or text)
-```
-
-**UI badge:** `⚡ Voice Analysis Active` (or similar) when Path A is active.
-
-### Path B — Whisper fallback (when Nemotron audio path fails)
-
-```text
-Browser records audio
-        ↓
-POST /api/voice-pitch
-        ↓
-faster-whisper local transcription
-        ↓
-Clean transcript text only (no paralinguistic tokens)
-        ↓
-Nemotron or MiniCPM5-1B text reasoning
-        ↓
-Judge question (no delivery observations)
-        ↓
-Scorecard notes: "Voice delivery metrics unavailable in fallback mode"
-```
-
-**UI badge:** `📝 Text Mode` (transcript-only fallback).
-
-Path A is the **demo differentiator**. Path B keeps the app working when audio API fails, keys are missing, or latency/errors trigger fallback.
-
-### Security
-
-- Audio upload hits **backend only** — never send `NVIDIA_API_KEY` to the browser.
-- Keys live in `.env` locally and **HF Space Secrets** in deployment.
-
----
-
-## 7. Recommended Voice Prompt (Hesitation / Delivery)
-
-When sending audio to Nemotron for `/api/voice-pitch`, include instructions like:
-
-```text
-Listen to this pitch audio carefully.
-
-Beyond the words spoken, note:
-- Any filler words (um, uh, like, you know, sort of)
-- Any long pauses before answering a key claim
-- Any statements that trail off or sound uncertain
-- Any rushing through parts they seem unsure about
-- Any self-corrections or restarts
-
-After understanding the pitch, include a section called
-DELIVERY OBSERVATIONS with specific timestamps or quotes
-where hesitation or low confidence was audible.
-
-Extract startup context fields if possible.
-Then ask your first hard judge question in character.
-Return structured JSON when requested.
-```
-
-Anchoring the model to **delivery observations** makes paralinguistic reporting explicit instead of hoping it infers them silently.
-
-### Suggested structured response fields (Phase 7+)
-
-```json
-{
-  "transcript": "...",
-  "delivery_observations": [
-    {
-      "type": "filler_words",
-      "quote_or_timestamp": "0:12 — 'um, I think maybe...'",
-      "note": "Hedging before market size claim"
-    }
-  ],
-  "detected_startup_context": { },
-  "opening_question": "..."
-}
-```
-
-Exact schema should match `core/api_handlers.py` when voice mode is implemented.
-
----
-
-## 8. Comparison: Nemotron Omni vs faster-whisper
-
-| | Nemotron Omni (Path A) | faster-whisper (Path B) |
-|---|---|---|
-| **Input** | Raw audio | Raw audio |
-| **Output** | Transcript + reasoning + delivery signals | Transcript text only |
-| **Hesitation / pace** | Paralinguistic tokens in backbone | Not available |
-| **Judge question** | Same call or follow-up text call | Requires separate text model call |
-| **Role in PitchFight** | Primary voice judge | Transcription fallback only |
-| **Runs** | NVIDIA API (backend) | Local on Space / dev machine |
-
----
-
-## 9. Implementation Notes (Future Phases)
-
-Planned wiring (no app logic in this doc — reference only):
-
-| Module | Responsibility |
-|---|---|
-| `core/nvidia_client.py` | Send audio + prompt to Nemotron API; parse structured response |
-| `core/model_router.py` | Choose `premium_nvidia` vs `whisper_fallback` |
-| `core/transcription_client.py` | faster-whisper when Omni audio fails |
-| `core/api_handlers.py` | `handle_voice_pitch()` orchestration |
-| `frontend/script.js` | Upload audio to `/api/voice-pitch` only |
-
-### Fallback triggers (suggested)
-
-- NVIDIA API timeout or 5xx
-- Missing `NVIDIA_API_KEY`
-- Audio format unsupported by API
-- Explicit `WHISPER_FALLBACK_ENABLED=true` override for debugging
-
-### Demo talking points
-
-1. **Raw audio goes to Nemotron** — not transcribe-then-reason on the premium path.
-2. **Delivery observations** — fillers, pauses, trailing off — are first-class signals.
-3. **Honest limits** — we score linguistic hesitation, not biometrics.
-4. **Graceful fallback** — whisper keeps voice mode alive without breaking the demo.
-
----
-
-## 10. References
-
-- NVIDIA Nemotron 3 Nano Omni model card and integrate API docs (NVIDIA NIM / integrate.api.nvidia.com)
-- Build Small Hackathon: ≤32B models, Gradio/HF Spaces, demo-first
-- PitchFight model stack: [`MODELS_FINAL.md`](MODELS_FINAL.md)
-
----
-
-## 11. Bottom Line
-
-Nemotron Omni is the right primary voice model for PitchFight because it processes **raw audio through a dedicated encoder into a shared reasoning backbone**, preserving paralinguistic cues that matter for pitch coaching. Pair it with an explicit **delivery observations** prompt, honest scorecard metrics, and a **whisper fallback** that degrades visibly — not silently — when the premium audio path is unavailable.

docs/PHASE_WISE_PLAN.md

@@ -1,478 +0,0 @@
-# PitchFight AI — Phase-Wise Implementation Plan
-
-## Full Sponsor-Model Build Plan for Voice, Text, Deal Battle, Scorecards, and Demo Polish
-
-PitchFight AI is a voice-and-text AI sparring arena for student founders. The project prioritizes the strongest possible demo experience using small models under 32B, including NVIDIA Nemotron Omni for premium voice/multimodal judge behavior, OpenBMB MiniCPM models for sponsor-aligned modes, a custom Gradio Server frontend, persona-based pitch battles, deal negotiation battles, and rubric-based scorecards.
-
-> **Strategy note:** This version does **not** claim the Off-the-Grid badge because the default high-quality build may use sponsor/model APIs. This is intentional. The project instead targets **Backyard AI**, **Best Demo**, **Best Agent**, **Off-Brand**, **NVIDIA Nemotron Quest**, **OpenBMB Awards**, **Sharing is Caring**, and **Field Notes**.
-
----
-
-## 1. Final Build Goal
-
-The complete final app includes:
-
-- Custom Gradio Server app
-- Custom HTML/CSS/JS frontend
-- Pitch Battle mode
-- Deal Battle mode
-- Voice Pitch mode
-- Text Pitch mode
-- AI opponent personas
-- Attack-tag routing
-- Session memory
-- NVIDIA Nemotron Omni integration
-- MiniCPM-o / MiniCPM fallback modes
-- MiniCPM-V pitch deck critique mode
-- Scorecard engine
-- Weakest answer rewrite
-- Improved 60-second pitch
-- Retry weakest question
-- HF Spaces deployment
-- Documentation and demo notes
-
-**Focus:** demo strength, model quality, and sponsor-model alignment — **not** Off-the-Grid.
-
-All models stay **≤32B parameters**. The app is built on **Gradio**, hosted as a **Hugging Face Space**, uses a **custom non-default UI**, and keeps **all API keys in backend/HF Space Secrets** only (never in the frontend).
-
----
-
-## 2. Master Build Order
-
-| Phase | Name |
-|---|---|
-| **Phase 0** | Strategy Reset + Documentation Alignment |
-| **Phase 1** | Project Skeleton Verification |
-| **Phase 2** | Model Router + Secrets Setup |
-| **Phase 3** | NVIDIA Nemotron Omni Integration |
-| **Phase 4** | Pitch Battle Engine |
-| **Phase 5** | Scorecard + Feedback Engine |
-| **Phase 6** | Custom Frontend Integration |
-| **Phase 7** | Voice Pitch Mode |
-| **Phase 8** | Deal Battle Mode |
-| **Phase 9** | MiniCPM / OpenBMB Modes |
-| **Phase 10** | Pitch Deck Critique Mode |
-| **Phase 11** | Retry + Report Enhancements |
-| **Phase 12** | UI Polish + Demo Flow |
-| **Phase 13** | Hugging Face Spaces Deployment |
-| **Phase 14** | Final Testing + Submission Readiness |
-
----
-
-## 3. Phase 0 — Strategy Reset + Documentation Alignment
-
-**Goal:** Ensure all repository docs reflect the high-demo sponsor-model strategy (historical local-first/off-grid wording removed).
-
-**Tasks:**
-
-- Remove wording that says the default build is Off-the-Grid.
-- Keep a note that Off-the-Grid is **not** targeted.
-- Update model strategy to include **NVIDIA Nemotron Omni** as the primary premium model.
-- Add **MiniCPM-o** as OpenBMB advanced mode.
-- Add **MiniCPM5-1B** as Tiny/Fallback mode.
-- Add **MiniCPM-V 4.6** as pitch deck critique mode.
-- Keep **faster-whisper** as backup transcription fallback.
-- Update `README.md`, `docs/DOCUMENTATION.md`, `docs/PROMPTS.md`, `docs/DEMO_NOTES.md`, `docs/FIELD_NOTES.md`, and `docs/MODELS_FINAL.md` accordingly.
-
-**Success check:** All docs agree that the project is under 32B, Gradio/HF Spaces based, and high-demo sponsor-model focused.
-
----
-
-## 4. Phase 1 — Project Skeleton Verification
-
-**Goal:** Verify that the existing Gradio Server + custom frontend skeleton works.
-
-**Tasks:**
-
-- Check `app.py` exists.
-- Check `frontend/index.html`, `styles.css`, `script.js` exist.
-- Check `core/` modules exist.
-- Check `config/` files exist.
-- Run `python app.py`.
-- Confirm custom UI opens.
-- Confirm mock battle works.
-- Confirm mock scorecard appears.
-
-**Files:**
-
-- `app.py`
-- `frontend/*`
-- `core/*`
-- `config/*`
-- `docs/*`
-
-**Success check:** Custom PitchFight AI UI opens and mock demo flow runs.
-
-**Current status:** ✅ Complete (Phase 1 skeleton in place with mock APIs).
-
-**API layer:** Clean product endpoints live under `/api/...` (see [`BACKEND_API.md`](BACKEND_API.md)). Gradio internal routes in Swagger are framework runtime routes, not PitchFight product APIs.
-
----
-
-## 5. Phase 2 — Model Router + Secrets Setup
-
-**Goal:** Create a clean backend-only model routing layer.
-
-**Tasks:**
-
-- Create or update `core/model_router.py`.
-- Create or update `core/nvidia_client.py`.
-- Create or update `core/minicpm_client.py`.
-- Create or update `core/vision_client.py`.
-- Create or update `core/transcription_client.py`.
-- Ensure frontend never calls model APIs.
-- Add env variables to `.env.example`.
-- Read keys only from `os.getenv` (`.env` locally, HF Space Secrets in deployment).
-- Frontend calls `/api/*` only — never model provider APIs.
-- Add graceful fallback if a model call fails.
-
-**Environment variables:**
-
-```text
-NVIDIA_API_KEY=
-NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
-NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
-
-OPENBMB_API_KEY=
-OPENBMB_BASE_URL=
-MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
-MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
-MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
-
-HF_TOKEN=
-WHISPER_FALLBACK_ENABLED=true
-MAX_ROUNDS=6
-APP_ENV=development
-```
-
-**Success check:** Backend can select a model path:
-
-- `premium_nvidia`
-- `openbmb_omni`
-- `tiny_minicpm`
-- `vision_deck`
-- `whisper_fallback`
-
-**Current status:** ✅ Complete (2026-06-08). `core/nvidia_client.py` and `core/model_router.py` created. NVIDIA connectivity tested — live response confirmed. Stub clients created for MiniCPM, vision, and transcription. `GET /api/model-health` added.
-
-**Key discovery:** `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` is a reasoning model. It uses tokens for an internal chain-of-thought before writing `message.content`. Token defaults: opponent=500, scorecard=2000, rewrite=800. A `reasoning_content` fallback is in place for edge cases.
-
----
-
-## 6. Phase 3 — NVIDIA Nemotron Omni Integration
-
-**Goal:** Make NVIDIA Nemotron Omni the primary premium reasoning and voice/multimodal judge model.
-
-**Tasks:**
-
-- Implement secure backend call using `NVIDIA_API_KEY`.
-- Add function `generate_nemotron_response(messages, mode)`.
-- Add timeout handling.
-- Add retry handling.
-- Add fallback to MiniCPM mode if NVIDIA fails.
-- Test text-only judge prompt first.
-- Test scoring prompt second.
-- Test voice/multimodal input after text works.
-
-**Use cases:**
-
-- AI opponent response
-- Voice pitch critique
-- Deal battle counterpart
-- Scorecard generation
-- Weakest answer rewrite
-- Optional pitch deck + spoken explanation critique
-
-**Success check:** Backend receives a startup context and Nemotron returns a sharp judge question.
-
----
-
-## 7. Phase 4 — Pitch Battle Engine
-
-**Goal:** Make Pitch Battle real.
-
-**Tasks:**
-
-- Connect `/start_session` to `model_router`.
-- Connect `/chat_round` to `model_router`.
-- Use `persona_builder.py`.
-- Use `attack_tags.py`.
-- Store history in `session_manager.py`.
-- Rotate attack tags.
-- Return `attack_tag`, `pressure_level`, `round`, `ai_message`.
-- Support 3 personas:
-  - Skeptical VC
-  - Technical Judge
-  - Hackathon Judge
-
-**Success check:** User enters EventRadar AI, selects Hackathon Judge, and receives a sharp AI challenge.
-
----
-
-## 8. Phase 5 — Scorecard + Feedback Engine
-
-**Goal:** Generate real scorecards.
-
-**Tasks:**
-
-- Build scoring prompt from conversation history.
-- Use NVIDIA Nemotron as default scorer.
-- Use MiniCPM fallback if needed.
-- Parse scorecard JSON safely.
-- Implement JSON fallback pipeline.
-- Generate:
-  - overall score
-  - 6 pitch dimensions
-  - best answer
-  - weakest answer
-  - improved answer
-  - improved pitch
-  - top 3 prep questions
-
-**Files:**
-
-- `core/scoring_engine.py`
-- `core/feedback_generator.py`
-- `core/json_utils.py`
-- `app.py`
-- `frontend/script.js`
-
-**Success check:** End Battle produces structured scorecard with user quotes and useful rewrites.
-
----
-
-## 9. Phase 6 — Custom Frontend Integration
-
-**Goal:** Connect UI fully to backend APIs.
-
-**Tasks:**
-
-- Connect Gradio JS Client.
-- Load demo startup.
-- Start session.
-- Render AI question.
-- Render user messages.
-- Render AI follow-ups.
-- Render attack tag.
-- Render pressure meter.
-- Render scorecard.
-- Show model mode badge:
-  - Premium Nemotron
-  - OpenBMB Omni
-  - Tiny MiniCPM
-- Handle errors and loading states.
-
-**Success check:** User can complete full Pitch Battle from UI.
-
----
-
-## 10. Phase 7 — Voice Pitch Mode
-
-**Goal:** Make voice mode a major demo feature.
-
-**Primary path:**
-
-```text
-Browser records audio
-  → backend sends audio/transcript to NVIDIA Nemotron Omni
-  → AI extracts pitch understanding
-  → AI asks first hard question
-  → user continues by voice or text
-```
-
-**Fallback path:**
-
-```text
-Browser records audio
-  → faster-whisper transcribes locally
-  → transcript goes to selected text model
-  → battle starts
-```
-
-**Tasks:**
-
-- Add browser audio recorder.
-- Add `/voice_pitch` endpoint.
-- Add audio upload handling.
-- Add transcript/interpretation panel.
-- Add user editable transcript.
-- Add voice-specific metrics:
-  - Structure
-  - Conciseness
-  - Confidence Signals
-  - Directness
-- Continue battle from voice input.
-
-**Success check:** User records a pitch and receives a hard first question.
-
----
-
-## 11. Phase 8 — Deal Battle Mode
-
-**Goal:** Add negotiation practice.
-
-**Scenarios:**
-
-- Startup Sponsorship Ask
-- Internship Salary Negotiation
-- Freelance Client Pricing
-- Equity Negotiation
-
-**Personas:**
-
-- Tough Sponsor
-- Strict HR Recruiter
-- Budget-Conscious Client
-- Hard-Negotiating Investor
-
-**Tasks:**
-
-- Add Deal Battle mode to UI.
-- Add negotiation context form.
-- Add deal personas.
-- Add deal attack tags.
-- Add deal rubric.
-- Route deal battle to `model_router`.
-- Generate negotiation-specific scorecard.
-
-**Success check:** User can negotiate and receive a deal-specific scorecard.
-
----
-
-## 12. Phase 9 — MiniCPM / OpenBMB Modes
-
-**Goal:** Add OpenBMB sponsor-aligned models and fallback modes.
-
-**Models:**
-
-- **MiniCPM-o 4.5** — OpenBMB Omni Mode
-- **MiniCPM5-1B** — Tiny Mode / fallback
-- **MiniCPM-V 4.6** — vision mode
-
-**Tasks:**
-
-- Add model selector or backend mode switch.
-- Add OpenBMB Omni mode.
-- Add Tiny MiniCPM mode.
-- Add fallback if NVIDIA errors.
-- Add docs explaining model use cases.
-
-**Success check:** App can run at least one OpenBMB mode and one fallback mode.
-
----
-
-## 13. Phase 10 — Pitch Deck Critique Mode
-
-**Goal:** Add image/slide critique.
-
-**Primary model:** MiniCPM-V 4.6 or NVIDIA Omni.
-
-**Tasks:**
-
-- Add image upload.
-- Add `/deck_critique` endpoint.
-- Extract slide claims.
-- Critique clarity, problem, solution, market, ask.
-- Generate 3 judge questions based on the slide.
-
-**Success check:** User uploads a pitch slide screenshot and receives useful critique.
-
----
-
-## 14. Phase 11 — Retry + Report Enhancements
-
-**Goal:** Make it feel product-ready.
-
-**Tasks:**
-
-- Add Retry Weakest Question.
-- Store weakest AI question.
-- Compare original vs retried answer.
-- Generate downloadable markdown report.
-- Add full session summary.
-- Add “Start New Battle”.
-
-**Success check:** User can retry the weakest objection and get improvement guidance.
-
----
-
-## 15. Phase 12 — UI Polish + Demo Flow
-
-**Goal:** Make it visually memorable.
-
-**Tasks:**
-
-- Improve landing hero.
-- Add model mode badges.
-- Add premium voice mode card.
-- Add deck critique card.
-- Add battle arena split layout.
-- Add score animations.
-- Add voice recording animation.
-- Add mobile responsiveness.
-- Add error banners.
-- Add loading states.
-
-**Design:** Dark battle arena, red pressure accents, gold score accents, glass cards, custom typography.
-
-**Success check:** The app looks like a custom product, not default Gradio.
-
----
-
-## 16. Phase 13 — Hugging Face Spaces Deployment
-
-**Goal:** Deploy publicly.
-
-**Tasks:**
-
-- Add README metadata.
-- Add required secrets in HF Space Settings.
-- Confirm app builds.
-- Confirm no keys are exposed.
-- Test all modes publicly.
-- Add screenshots to README.
-- Add final Space link.
-
-**Success check:** Public HF Space completes:
-
-- Text Pitch Battle
-- Voice Pitch Battle
-- Deal Battle
-- Scorecard
-- Deck critique (if built)
-
----
-
-## 17. Phase 14 — Final Testing + Submission Readiness
-
-**Tasks:**
-
-- Test every endpoint.
-- Test every UI button.
-- Test failure fallback.
-- Test missing API keys.
-- Test slow responses.
-- Test mobile layout.
-- Update README.
-- Update docs.
-- Prepare demo flow.
-- Prepare field notes.
-- Prepare social post separately.
-
-**Badges/prizes to mention:**
-
-- Backyard AI
-- Best Demo
-- Best Agent
-- Off-Brand
-- NVIDIA Nemotron Quest
-- OpenBMB Awards
-- Sharing is Caring
-- Field Notes
-- Tiny Titan (if Tiny Mode works)
-
----
-
-## Final One-Line Pitch
-
-**PitchFight AI is a voice-and-text AI sparring arena where student founders practice tough startup pitches, get grilled by realistic AI judges under 32B parameters, and receive a scorecard that shows exactly how to answer better.**

docs/PROMPTS.md

@@ -1,155 +0,0 @@
-# PitchFight AI — Prompt Templates
-
-## Model Routing (Backend Only)
-
-All prompts are sent through `core/model_router.py`. Default scorer and opponent: **NVIDIA Nemotron Omni**. Fallback: **MiniCPM5-1B**. Voice primary path: Nemotron Omni audio; fallback: **faster-whisper** → text model.
-
-> API keys never appear in prompts or frontend code. Keys are read from `os.getenv` on the backend only.
-
----
-
-## Opponent System Prompt Template
-
-Used by Nemotron Omni (primary) and MiniCPM fallback.
-
-```text
-You are {persona_label}, a tough pitch opponent in PitchFight AI.
-Difficulty: {difficulty}
-Current attack tag: {attack_tag}
-Round: {round_number} of {max_rounds}
-
-Startup: {startup_name}
-Problem: {problem}
-Solution: {solution}
-Why AI: {why_ai}
-Target users: {target_users}
-Competitors: {competitors}
-Traction: {traction}
-
-Conversation so far:
-{history}
-
-{persona_focus}
-
-Behavior rules:
-- Ask one sharp question at a time.
-- Keep responses under 4 sentences.
-- Reference the founder's previous answer when pushing back.
-- Do not give advice during the battle.
-- Do not compliment the founder.
-- Attack vague, generic, or unsubstantiated claims.
-- Raise difficulty after strong answers.
-- Stay in character at all times.
-- Be firm but not abusive.
-- Frame your question around the current attack tag: {attack_tag}.
-
-Return only your next question as plain text (no JSON).
-```
-
----
-
-## Scoring Prompt Template
-
-Default model: **NVIDIA Nemotron Omni**. Fallback: MiniCPM5-1B + `json_utils.safe_json_parse`.
-
-```text
-You are a pitch battle evaluator. Score the founder's performance using the rubric below.
-Return valid JSON only — no markdown fences, no commentary.
-
-Rubric weights:
-- clarity: 15
-- problem_understanding: 20
-- market_awareness: 15
-- differentiation: 20
-- business_model: 15
-- objection_handling: 15
-
-Startup context:
-{startup_json}
-
-Conversation:
-{history_json}
-
-Return exactly this JSON shape:
-{
-  "overall": <0-100>,
-  "scores": {
-    "clarity": {"score": <0-100>, "reason": "...", "quote": "..."},
-    "problem_understanding": {"score": <0-100>, "reason": "...", "quote": "..."},
-    "market_awareness": {"score": <0-100>, "reason": "...", "quote": "..."},
-    "differentiation": {"score": <0-100>, "reason": "...", "quote": "..."},
-    "business_model": {"score": <0-100>, "reason": "...", "quote": "..."},
-    "objection_handling": {"score": <0-100>, "reason": "...", "quote": "..."}
-  },
-  "best_answer": "...",
-  "weakest_answer": "...",
-  "improved_answer": "...",
-  "improved_pitch": "...",
-  "top_3_questions": ["...", "...", "..."]
-}
-```
-
----
-
-## Voice Pitch Extraction Prompt (Nemotron Omni)
-
-```text
-You heard a student founder's spoken pitch. Extract structured startup context and identify the weakest claim.
-
-Return JSON:
-{
-  "name": "...",
-  "problem": "...",
-  "target_users": "...",
-  "solution": "...",
-  "why_ai": "...",
-  "competitors": "...",
-  "traction": "...",
-  "ask": "...",
-  "voice_metrics": {
-    "structure": <0-100>,
-    "conciseness": <0-100>,
-    "confidence_signals": <0-100>,
-    "directness": <0-100>
-  },
-  "first_hard_question": "..."
-}
-```
-
----
-
-## Pitch Deck Critique Prompt (MiniCPM-V / Nemotron Vision)
-
-```text
-You are a hackathon judge reviewing one pitch slide image.
-
-Critique: clarity, problem, solution, market, ask.
-Return JSON:
-{
-  "slide_summary": "...",
-  "strengths": ["..."],
-  "weaknesses": ["..."],
-  "judge_questions": ["...", "...", "..."]
-}
-```
-
----
-
-## Persona Behavior Rules
-
-| Persona | Focus |
-|---|---|
-| Skeptical VC | Market size, moat, retention, revenue, defensibility |
-| Technical Judge | AI justification, architecture, scalability, data quality |
-| Hackathon Judge | Novelty, demo clarity, MVP strength, backyard fit |
-
-## Attack Tag Lists
-
-### Skeptical VC
-Market Size, Moat, Retention, Revenue Logic, First 100 Users, Why Now, Competition, Defensibility
-
-### Technical Judge
-AI Justification, Architecture, Scalability, Latency, Data Quality, Failure Mode, Simpler Alternative, Technical Feasibility
-
-### Hackathon Judge
-Novelty, Demo Clarity, MVP Strength, User Pain, AI Load-Bearing, Backyard Fit, Practical Impact, Judging Memorability

docs/TASK_TRACKER.md

@@ -1,105 +0,0 @@
-# PitchFight AI — Task Tracker
-
-## Current Phase
-
-Phase 2 complete: Model Router + Secrets Setup (2026-06-08)
-
-## Next Phase
-
-Phase 3: Wire model_router into battle flow (handle_start_session + handle_chat_round)
-
----
-
-## Phase Status Table
-
-| Phase | Name | Status | Notes |
-|---|---|---|---|
-| 0 | Strategy Reset + Documentation Alignment | Complete | Off-the-Grid removed; sponsor-model strategy locked |
-| 1 | Project Skeleton Verification | Complete | Mock app runs; custom frontend live; all /api/* endpoints return responses |
-| 2 | Model Router + Secrets Setup | **Complete** (2026-06-08) | nvidia_client, model_router, stub clients created; NVIDIA tested live |
-| 3 | NVIDIA Nemotron Omni Integration | Pending | Depends on Phase 2 |
-| 4 | Pitch Battle Engine | Pending | Replace mock followups with real Nemotron responses |
-| 5 | Scorecard + Feedback Engine | Pending | Real scoring via Nemotron; json_utils already ready |
-| 6 | Custom Frontend Integration | Pending | Model mode badge; error/loading polish |
-| 7 | Voice Pitch Mode | Pending | Browser audio → Nemotron Omni; fallback to whisper |
-| 8 | Deal Battle Mode | Pending | Negotiation scenarios + deal personas |
-| 9 | MiniCPM / OpenBMB Modes | Pending | MiniCPM-o, MiniCPM5-1B, fallback routing |
-| 10 | Pitch Deck Critique Mode | Pending | MiniCPM-V 4.6 image upload + slide critique |
-| 11 | Retry + Report Enhancements | Pending | Retry weakest question; downloadable markdown report |
-| 12 | UI Polish + Demo Flow | Pending | Animations, model badges, mobile, dark arena look |
-| 13 | Hugging Face Spaces Deployment | Pending | HF Space Secrets, public test, screenshots |
-| 14 | Final Testing + Submission Readiness | Pending | All endpoints, all modes, all failure paths |
-
----
-
-## Immediate Next Tasks (Phase 3)
-
-1. In `core/api_handlers.py`: import `model_router` and `persona_builder`
-2. In `handle_start_session`: build system prompt via `persona_builder.build_persona_prompt()`, call `model_router.generate_opponent_response()`, use mock opening as fallback if `ok=False`
-3. In `handle_chat_round`: build message list from session history, call `model_router.generate_opponent_response()`, use mock followup as fallback if `ok=False`
-4. Run full battle flow end-to-end: load sample → start session → 2 chat rounds → end battle
-5. Confirm Nemotron response is sharp, persona-locked, and references attack tag
-6. Update docs after confirming end-to-end works
-
-**Do not touch scoring, voice, deal battle, or deck critique in Phase 3.**
-
----
-
-## Phase 2 Completed Tasks
-
-- [x] `.env.example` verified — all variables present and correct
-- [x] `core/nvidia_client.py` created
-  - [x] Reads keys from `os.getenv` only — no hardcoded values
-  - [x] `generate_nemotron_response(messages, mode, temperature, max_tokens, timeout)` implemented
-  - [x] Timeout handling (30s default)
-  - [x] Returns string on success; raises `RuntimeError` with clean message on failure
-  - [x] `reasoning_content` fallback for reasoning model edge cases
-  - [x] No API key or URL hardcoded anywhere
-- [x] `core/model_router.py` created
-  - [x] Routes `premium_nvidia` → nvidia_client (live)
-  - [x] Stub/placeholder routes for `openbmb_omni`, `tiny_minicpm`, `vision_deck`, `whisper_fallback`
-  - [x] Graceful fallback if NVIDIA fails (`ok=False`, fallback message returned, no crash)
-  - [x] `get_model_health()` — all providers, no key exposure
-- [x] `core/minicpm_client.py` stub created (health_check only)
-- [x] `core/vision_client.py` stub created (health_check only)
-- [x] `core/transcription_client.py` stub created (health_check only)
-- [x] `scripts/test_nvidia_client.py` — isolated test, exits 0 on success / 1 on failure
-- [x] Isolated NVIDIA test: **PASSED** — live Nemotron response confirmed
-- [x] `GET /api/model-health` added to `app.py`
-- [x] `requirements.txt` updated: `openai>=1.0.0`, `httpx`, `requests` added
-- [x] Mock followup lists remain in `api_handlers.py` — not removed
-- [x] `docs/PHASE_WISE_PLAN.md` Phase 2 marked Complete
-- [x] `docs/FIELD_NOTES.md` updated with Phase 2 build log
-- [x] `docs/BACKEND_API.md` `/api/model-health` added
-- [x] `docs/MODELS_FINAL.md` model-to-file mapping updated with Phase 2 status
-
----
-
-## Phase 1 Completed Tasks (for reference)
-
-- [x] `app.py` — Gradio Server with `/api/*` REST routes and `@app.api` wrappers
-- [x] `frontend/index.html`, `styles.css`, `script.js` — custom battle arena UI
-- [x] `core/session_manager.py` — in-memory session store
-- [x] `core/persona_builder.py` — system prompt builder per persona
-- [x] `core/attack_tags.py` — tag taxonomy + round-based selector
-- [x] `core/scoring_engine.py` — mock scorecard with real session quotes
-- [x] `core/feedback_generator.py` — mock rewrite templates
-- [x] `core/json_utils.py` — JSON extraction, safe parse, fallback scorecard
-- [x] `core/samples.py` — EventRadar AI sample startup
-- [x] `core/local_text_model.py` — Phase 1 stub
-- [x] `core/voice_transcriber.py` — Phase 1 stub
-- [x] `config/personas.json`, `attack_tags.json`, `pitch_rubric.json`, `sample_startups.json`
-- [x] `docs/BACKEND_API.md`, `DOCUMENTATION.md`, `FIELD_NOTES.md`, `DEMO_NOTES.md`, `MODELS_FINAL.md`, `PHASE_WISE_PLAN.md`, `PROMPTS.md`
-- [x] `.env.example` — all required variables present
-
----
-
-## Risks Before Phase 2
-
-| Risk | Mitigation |
-|---|---|
-| NVIDIA API key not yet provisioned | Get key from NVIDIA developer portal; add to `.env` before Phase 2 testing |
-| Nemotron endpoint may need special headers or model format | Test isolated before wiring into session flow |
-| `openai` Python SDK compatibility with NVIDIA base URL | NVIDIA uses OpenAI-compatible API; use `openai.OpenAI(base_url=..., api_key=...)` |
-| Session manager is in-memory; process restart loses sessions | Acceptable for hackathon; note as known limitation |
-| Mock fallback strings (MOCK_FOLLOWUPS) must stay in api_handlers.py | Do not delete until real model routing is confirmed stable |

scripts/test_claim_based_scoring.py

@@ -1,336 +0,0 @@
-"""Phase 5D: Local unit tests for claim extractor, local scoring, and session-aware fallback.
-
-No server required. Tests run purely locally.
-
-Usage:
-  python scripts/test_claim_based_scoring.py
-"""
-
-from __future__ import annotations
-
-import sys
-import os
-
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
-
-from core.claim_extractor import extract_concrete_signals
-from core.scoring_engine import (
-    build_session_aware_fallback_scorecard,
-    _compute_local_scores,
-    _score_label,
-)
-from core.json_utils import _score_label as json_score_label
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    marker = "PASS" if condition else "FAIL"
-    suffix = f" — {detail}" if detail else ""
-    print(f"  {marker}  {label}{suffix}")
-    if not condition:
-        sys.exit(1)
-
-
-def make_session(answers: list[str], startup: dict | None = None) -> dict:
-    startup = startup or {
-        "name": "TestStartup",
-        "problem": "Test problem",
-        "solution": "Test solution",
-        "why_ai": "AI helps",
-        "stage": "Prototype",
-        "team": "2 founders",
-        "traction": "10 beta users",
-    }
-    history = []
-    for i, ans in enumerate(answers):
-        if i % 2 == 0:
-            history.append({"role": "assistant", "content": f"Judge question {i}", "attack_tag": "Market Size"})
-        history.append({"role": "user", "content": ans})
-    return {"startup": startup, "persona": "hackathon_judge", "difficulty": "high", "history": history}
-
-
-# ---------------------------------------------------------------------------
-# Extraction tests (existing)
-# ---------------------------------------------------------------------------
-
-def test_strong_evidence_answer() -> None:
-    print("\nTest 1: Strong evidence — numbers, validation, campus")
-    session = make_session(["80 users, 60% interview rate, 3 colleges have onboarded already."])
-    sigs = extract_concrete_signals(session)
-    check("numbers extracted", len(sigs["numbers"]) > 0, f"got {sigs['numbers']}")
-    check("percentages extracted", len(sigs["percentages"]) > 0, f"got {sigs['percentages']}")
-    check("college_mentions extracted", len(sigs["college_mentions"]) > 0, f"got {sigs['college_mentions']}")
-    check("signal_count > 0", sigs["signal_count"] > 0, f"got {sigs['signal_count']}")
-    check("non_answers empty", len(sigs["non_answers"]) == 0)
-    check("best_user_quotes non-empty", len(sigs["best_user_quotes"]) > 0)
-
-
-def test_vague_answer() -> None:
-    print("\nTest 2: Vague answer — big market, useful")
-    session = make_session(["It is useful and big market will love it."])
-    sigs = extract_concrete_signals(session)
-    check("vague_claims detected", len(sigs["vague_claims"]) > 0, f"got {sigs['vague_claims']}")
-    check("no numbers", len(sigs["numbers"]) == 0, f"got {sigs['numbers']}")
-
-
-def test_non_answer() -> None:
-    print("\nTest 3: Non-answer — 'I don't know'")
-    session = make_session(["I don't know"])
-    sigs = extract_concrete_signals(session)
-    check("non_answers detected", len(sigs["non_answers"]) > 0, f"got {sigs['non_answers']}")
-    check("best_user_quotes empty", len(sigs["best_user_quotes"]) == 0)
-    check("signal_count is 0", sigs["signal_count"] == 0, f"got {sigs['signal_count']}")
-
-
-def test_pricing_and_revenue() -> None:
-    print("\nTest 4: Pricing and revenue — ₹399 per student and CAC ~₹50")
-    session = make_session(["We charge ₹399 per student and our CAC is around ₹50."])
-    sigs = extract_concrete_signals(session)
-    check("pricing detected", len(sigs["pricing"]) > 0, f"got {sigs['pricing']}")
-    check("revenue_signals detected", len(sigs["revenue_signals"]) > 0, f"got {sigs['revenue_signals']}")
-    check("signal_count > 0", sigs["signal_count"] > 0)
-
-
-def test_competitors_and_tech() -> None:
-    print("\nTest 5: Competitors and technical mechanism")
-    session = make_session([
-        "Luma and LinkedIn are competitors but we use profile-based ranking with embedding models."
-    ])
-    sigs = extract_concrete_signals(session)
-    check("competitors detected", len(sigs["competitors"]) > 0, f"got {sigs['competitors']}")
-    check("technical_mechanisms detected", len(sigs["technical_mechanisms"]) > 0, f"got {sigs['technical_mechanisms']}")
-
-
-def test_mixed_session() -> None:
-    print("\nTest 6: Mixed session — strong + non-answer + vague")
-    session = make_session([
-        "We validated this with 50 beta users, 3 campus ambassadors, and weekly event-miss reports.",
-        "I don't know",
-        "It is a big market.",
-        "We use embeddings and a ranking model trained on student behavior.",
-    ])
-    sigs = extract_concrete_signals(session)
-    check("numbers detected", len(sigs["numbers"]) > 0, f"got {sigs['numbers']}")
-    check("validation detected", len(sigs["validation"]) > 0, f"got {sigs['validation']}")
-    check("non_answers detected", len(sigs["non_answers"]) > 0)
-    check("vague_claims detected", len(sigs["vague_claims"]) > 0)
-    check("technical_mechanisms detected", len(sigs["technical_mechanisms"]) > 0)
-    check("best_user_quotes >= 2", len(sigs["best_user_quotes"]) >= 2, f"got {len(sigs['best_user_quotes'])}")
-    check("signal_count > 3", sigs["signal_count"] > 3, f"got {sigs['signal_count']}")
-
-
-# ---------------------------------------------------------------------------
-# Local scoring tests (Phase 5D)
-# ---------------------------------------------------------------------------
-
-def test_local_scoring_strong_evidence() -> None:
-    print("\nTest 7: Local scoring — '80 users, 60% interview rate, 3 colleges' should get real credit")
-    session = make_session([
-        "80 users, 60% interview rate, 3 colleges have onboarded already.",
-        "We charge ₹399 per student and our CAC is around ₹50.",
-        "Luma and LinkedIn are competitors but we use profile-based ranking with embedding models.",
-    ])
-    sigs = extract_concrete_signals(session)
-    startup = session.get("startup", {})
-    scores, best_answer, weakest_answer, why_weak = _compute_local_scores(sigs, startup)
-
-    # All 6 dims must be present
-    required = {"clarity", "problem_understanding", "market_awareness",
-                "differentiation", "business_model", "objection_handling"}
-    check("all 6 dims present", required <= set(scores.keys()))
-
-    # With concrete evidence, most dims should be Developing (31+) or above
-    for dim in required:
-        s = scores[dim]["score"]
-        check(f"{dim}.score >= 30", s >= 30, f"got {s} — evidence was strong")
-
-    # Dims with direct evidence should be Solid (51+) or Strong
-    # market_awareness should get credit for numbers + competitors
-    market_s = scores["market_awareness"]["score"]
-    check("market_awareness >= 50 (has numbers + competitors)", market_s >= 50, f"got {market_s}")
-
-    # differentiation should get credit for competitors + tech
-    diff_s = scores["differentiation"]["score"]
-    check("differentiation >= 50 (has competitors + tech)", diff_s >= 50, f"got {diff_s}")
-
-    # business_model should get credit for ₹399 + CAC
-    biz_s = scores["business_model"]["score"]
-    check("business_model >= 45 (has pricing + revenue)", biz_s >= 45, f"got {biz_s}")
-
-    # best_answer should be non-empty
-    check("best_answer non-empty", bool(best_answer))
-    check("why_weak non-empty", bool(why_weak))
-
-
-def test_local_scoring_vague_floor() -> None:
-    print("\nTest 8: Local scoring — vague on-topic answer should not go below 30 (global floor)")
-    session = make_session([
-        "It is a big market because students attend events often.",
-        "We have a better AI solution than others.",
-    ])
-    sigs = extract_concrete_signals(session)
-    startup = session.get("startup", {})
-    scores, _, _, _ = _compute_local_scores(sigs, startup)
-
-    # On-topic engagement = engagement > 0, so floor is 33
-    for dim, data in scores.items():
-        s = data["score"]
-        # Some dims may dip below 33 (business_model has 28 floor), but most should be >= 30
-        if dim != "business_model":
-            check(f"{dim}.score >= 30 (vague but on-topic)", s >= 30, f"got {s}")
-
-
-def test_local_scoring_non_answer_can_be_below_30() -> None:
-    print("\nTest 9: Local scoring — all non-answers can score below 30")
-    session = make_session(["ok", "I don't know", "yeah", "not sure"])
-    sigs = extract_concrete_signals(session)
-    startup = session.get("startup", {})
-    scores, _, _, _ = _compute_local_scores(sigs, startup)
-
-    # With all non-answers, engagement=0, so dims should be low
-    low_count = sum(1 for d in scores.values() if d["score"] <= 20)
-    check("majority of dims <= 20 when all non-answers", low_count >= 4,
-          f"got {low_count} dims <= 20, scores={[(k, v['score']) for k, v in scores.items()]}")
-
-
-def test_local_scoring_pricing_revenue() -> None:
-    print("\nTest 10: Local scoring — ₹399 and CAC ₹50 → business_model Developing or better")
-    session = make_session(["We charge ₹399 per student and our CAC is around ₹50."])
-    sigs = extract_concrete_signals(session)
-    startup = session.get("startup", {})
-    scores, _, _, _ = _compute_local_scores(sigs, startup)
-
-    biz_s = scores["business_model"]["score"]
-    biz_lbl = scores["business_model"]["label"]
-    check(
-        "business_model >= 31 (Developing or better) with ₹399 + CAC",
-        biz_s >= 31,
-        f"got {biz_s} ({biz_lbl})",
-    )
-
-
-# ---------------------------------------------------------------------------
-# Session-aware fallback test
-# ---------------------------------------------------------------------------
-
-def test_session_aware_fallback_not_static() -> None:
-    print("\nTest 11: Session-aware fallback does not return EventRadar static content")
-    session = make_session(
-        [
-            "We have 80 users at IIT Delhi and IIT Bombay paying ₹499/month.",
-            "Competitors are LinkedIn and Glassdoor but we do skill-gap analysis.",
-        ],
-        startup={
-            "name": "SkillBridge",
-            "problem": "Students get rejected because their resume skills don't match job requirements.",
-            "solution": "AI that maps resume skills to actual job description gaps.",
-            "why_ai": "Personalized skill-gap analysis requires LLM understanding.",
-            "stage": "Beta",
-            "team": "2 founders",
-            "traction": "80 paying users",
-        },
-    )
-    sigs = extract_concrete_signals(session)
-    fb = build_session_aware_fallback_scorecard(session, sigs, "test error")
-
-    check("scorecard_source=session_fallback", fb.get("scorecard_source") == "session_fallback")
-    check("model_ok=False", fb.get("model_ok") is False)
-    check("provider=local", fb.get("provider") == "local")
-    check("model_error present", bool(fb.get("model_error")))
-    check("overall is int 0-100",
-          isinstance(fb.get("overall"), int) and 0 <= fb.get("overall", -1) <= 100)
-    check("overall_label valid",
-          fb.get("overall_label") in {"Not addressed", "Developing", "Solid", "Strong", "Excellent"})
-    check("all 6 dims present",
-          {"clarity", "problem_understanding", "market_awareness",
-           "differentiation", "business_model", "objection_handling"}
-          <= set(fb.get("scores", {}).keys()))
-    check("concrete_signals_summary present", isinstance(fb.get("concrete_signals_summary"), dict))
-    check("top_3_questions has 3", len(fb.get("top_3_questions", [])) == 3)
-
-    full_text = str(fb)
-    for phrase in ["WhatsApp groups", "EventRadar"]:
-        check(
-            f"no static phrase '{phrase}' in session fallback",
-            phrase not in full_text or "SkillBridge" in full_text,
-        )
-
-    best = fb.get("best_answer", "")
-    check(
-        "best_answer contains actual answer text",
-        any(word in best for word in ["80 users", "IIT", "499", "SkillBridge", "LinkedIn", "skill"]),
-        f"got: {best[:120]}",
-    )
-
-
-# ---------------------------------------------------------------------------
-# Score label band tests
-# ---------------------------------------------------------------------------
-
-def test_score_label_bands() -> None:
-    print("\nTest 12: Score label bands (Phase 5C/5D)")
-    cases = [
-        (0,   "Not addressed"),
-        (15,  "Not addressed"),
-        (30,  "Not addressed"),
-        (31,  "Developing"),
-        (50,  "Developing"),
-        (51,  "Solid"),
-        (70,  "Solid"),
-        (71,  "Strong"),
-        (85,  "Strong"),
-        (86,  "Excellent"),
-        (100, "Excellent"),
-    ]
-    for score, expected in cases:
-        got = _score_label(score)
-        check(f"_score_label({score}) == '{expected}'", got == expected, f"got '{got}'")
-    # Also verify json_utils._score_label matches
-    for score, expected in cases:
-        got = json_score_label(score)
-        check(f"json_utils._score_label({score}) == '{expected}'", got == expected, f"got '{got}'")
-
-
-def test_all_non_answer_session() -> None:
-    print("\nTest 13: All non-answer session — fallback should still work")
-    session = make_session(["ok", "I don't know", "yeah", "not sure"])
-    sigs = extract_concrete_signals(session)
-    check("all are non_answers", len(sigs["non_answers"]) >= 3)
-    check("signal_count=0", sigs["signal_count"] == 0)
-    fb = build_session_aware_fallback_scorecard(session, sigs)
-    check("fallback returns valid dict", isinstance(fb, dict))
-    check("overall >= 0", fb.get("overall", -1) >= 0)
-    check("scorecard_source=session_fallback", fb.get("scorecard_source") == "session_fallback")
-
-
-# ---------------------------------------------------------------------------
-# Runner
-# ---------------------------------------------------------------------------
-
-def main() -> None:
-    print("\nPhase 5D — Claim Extractor + Local Scoring + Session-Aware Fallback Tests")
-    print("(No server required)\n")
-
-    test_strong_evidence_answer()
-    test_vague_answer()
-    test_non_answer()
-    test_pricing_and_revenue()
-    test_competitors_and_tech()
-    test_mixed_session()
-    test_local_scoring_strong_evidence()
-    test_local_scoring_vague_floor()
-    test_local_scoring_non_answer_can_be_below_30()
-    test_local_scoring_pricing_revenue()
-    test_session_aware_fallback_not_static()
-    test_score_label_bands()
-    test_all_non_answer_session()
-
-    print("\nAll Phase 5D claim-based scoring tests passed.\n")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

scripts/test_nvidia_client.py

@@ -1,90 +0,0 @@
-"""Isolated NVIDIA Nemotron connectivity test.
-
-Run from the project root:
-    python scripts/test_nvidia_client.py
-
-Exits 0 on success, 1 on failure.
-Does not expose the API key in output.
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-# Allow imports from project root regardless of working directory
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from dotenv import load_dotenv
-
-load_dotenv()
-
-from core.nvidia_client import health_check, generate_nemotron_response  # noqa: E402
-
-
-def main() -> int:
-    print("=" * 60)
-    print("PitchFight AI — NVIDIA Nemotron connectivity test")
-    print("=" * 60)
-
-    # 1. Health check (no key in output)
-    print("\n[1] Health check")
-    status = health_check()
-    print(f"  provider    : {status['provider']}")
-    print(f"  configured  : {status['configured']}")
-    print(f"  base_url    : {status['base_url']}")
-    print(f"  model       : {status['model']}")
-    print(f"  key present : {status['api_key_present']}")
-    print(f"  message     : {status['message']}")
-
-    if not status["configured"]:
-        print("\n[FAIL] NVIDIA_API_KEY is not set.")
-        print("  Add it to your .env file and re-run this script.")
-        return 1
-
-    # 2. Test prompt
-    print("\n[2] Sending test prompt to Nemotron...")
-    messages = [
-        {
-            "role": "system",
-            "content": (
-                "You are a skeptical hackathon judge. "
-                "Ask exactly one sharp question. Do not give advice."
-            ),
-        },
-        {
-            "role": "user",
-            "content": (
-                "Startup: EventRadar AI.\n"
-                "Problem: Students miss hackathons and tech events because "
-                "discovery is scattered.\n"
-                "Solution: AI-powered event discovery that ranks opportunities "
-                "by skills, goals, location, and deadline urgency.\n\n"
-                "Return exactly one question under 40 words."
-            ),
-        },
-    ]
-
-    try:
-        response = generate_nemotron_response(
-            messages,
-            mode="opponent",
-            temperature=0.7,
-            timeout=30,
-        )
-        print("\n[3] Model response:")
-        print("-" * 40)
-        print(response)
-        print("-" * 40)
-        print("\n[PASS] NVIDIA Nemotron responded successfully.")
-        print("Phase 2 model connectivity: OK")
-        return 0
-
-    except RuntimeError as exc:
-        print(f"\n[FAIL] {exc}")
-        print("Check your NVIDIA_API_KEY and NVIDIA_BASE_URL in .env")
-        return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/test_phase3_pitch_battle.py

@@ -1,123 +0,0 @@
-"""Phase 3 end-to-end test: live pitch battle via the running server.
-
-Usage:
-  python scripts/test_phase3_pitch_battle.py
-
-Requires the server to already be running. Set PITCHFIGHT_BASE_URL to override
-the default base URL (http://127.0.0.1:7861).
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-
-import requests
-
-BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
-
-SAMPLE_STARTUP = {
-    "name": "EventRadar AI",
-    "problem": "Students miss relevant hackathons, workshops, and networking events.",
-    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
-    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
-    "stage": "Prototype",
-    "team": "2 founders",
-    "traction": "50 beta signups, no revenue yet",
-}
-
-USER_ANSWER = (
-    "It is a pretty big market because students attend events often."
-)
-
-
-def post(path: str, body: dict) -> dict:
-    url = f"{BASE_URL}{path}"
-    resp = requests.post(url, json=body, timeout=60)
-    resp.raise_for_status()
-    return resp.json()
-
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    if condition:
-        print(f"  PASS  {label}")
-    else:
-        print(f"  FAIL  {label}" + (f" — {detail}" if detail else ""))
-        sys.exit(1)
-
-
-def main() -> None:
-    print(f"\nPhase 3 Pitch Battle Test\nBase URL: {BASE_URL}\n")
-
-    # --- Step 1: start-session ---
-    print("Step 1: POST /api/start-session")
-    try:
-        data = post("/api/start-session", {
-            "mode": "pitch_battle",
-            "startup": SAMPLE_STARTUP,
-            "persona": "hackathon_judge",
-            "difficulty": "high",
-            "input_mode": "text",
-            "model_mode": "premium_nvidia",
-        })
-    except Exception as exc:
-        print(f"  FAIL  Request failed: {exc}")
-        sys.exit(1)
-
-    print(f"  session_id : {data.get('session_id', '—')}")
-    print(f"  model_ok   : {data.get('model_ok')}")
-    print(f"  provider   : {data.get('provider')}")
-    print(f"  model_mode : {data.get('model_mode')}")
-    print(f"  attack_tag : {data.get('attack_tag')}")
-    print(f"  round      : {data.get('round')}")
-    print(f"  ai_message :\n    {data.get('ai_message', '')}\n")
-
-    session_id = data.get("session_id")
-    check("session_id present", bool(session_id), "got empty session_id")
-    check("ai_message non-empty", bool(data.get("ai_message")), "ai_message is empty")
-    check("round is 1", data.get("round") == 1, f"got {data.get('round')}")
-    check("attack_tag present", bool(data.get("attack_tag")))
-
-    if data.get("model_ok"):
-        check("provider is nvidia", data.get("provider") == "nvidia")
-    else:
-        print("  NOTE  Model returned mock fallback (NVIDIA may be down or key missing)")
-        if data.get("model_error"):
-            print(f"  model_error: {data['model_error']}")
-
-    # --- Step 2: chat-round ---
-    print("\nStep 2: POST /api/chat-round")
-    try:
-        data2 = post("/api/chat-round", {
-            "session_id": session_id,
-            "user_message": USER_ANSWER,
-        })
-    except Exception as exc:
-        print(f"  FAIL  Request failed: {exc}")
-        sys.exit(1)
-
-    print(f"  model_ok   : {data2.get('model_ok')}")
-    print(f"  provider   : {data2.get('provider')}")
-    print(f"  model_mode : {data2.get('model_mode')}")
-    print(f"  attack_tag : {data2.get('attack_tag')}")
-    print(f"  round      : {data2.get('round')}")
-    print(f"  ai_message :\n    {data2.get('ai_message', '')}\n")
-
-    check("session_id echoed", data2.get("session_id") == session_id)
-    check("ai_message non-empty", bool(data2.get("ai_message")), "ai_message is empty")
-    check("round is 2", data2.get("round") == 2, f"got {data2.get('round')}")
-
-    if data2.get("model_ok"):
-        check("provider is nvidia", data2.get("provider") == "nvidia")
-    else:
-        print("  NOTE  chat-round returned mock fallback")
-        if data2.get("model_error"):
-            print(f"  model_error: {data2['model_error']}")
-
-    print("\nAll checks passed. Phase 3 integration is working.\n")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

scripts/test_phase3b_battle_flow.py

@@ -1,217 +0,0 @@
-"""Phase 3B end-to-end test: Socratic judge flow via the running server.
-
-Validates:
-  - answer_quality classification appears in chat-round responses
-  - judge_action drives tag switching / follow-up decisions
-  - Same attack tag not repeated more than MAX_ATTEMPTS_PER_ATTACK_TAG times
-  - ai_message is always non-empty (model or mock fallback)
-  - All required response fields are present
-
-Usage:
-  python scripts/test_phase3b_battle_flow.py
-
-Server must already be running. Set PITCHFIGHT_BASE_URL to override default.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from collections import defaultdict
-
-import requests
-
-BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
-
-SAMPLE_STARTUP = {
-    "name": "EventRadar AI",
-    "problem": "Students miss relevant hackathons, workshops, and networking events.",
-    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
-    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
-    "stage": "Prototype",
-    "team": "2 founders",
-    "traction": "50 beta signups, no revenue yet",
-}
-
-STRONG_ANSWER = (
-    "We validated this with 50 beta users, 3 campus ambassadors, "
-    "and weekly event-miss reports from two colleges."
-)
-
-ANSWERS = [
-    "It is a pretty big market because students attend events often.",  # weak
-    "I don't know",                                                      # non_answer
-    "ok",                                                                # non_answer → triggers move_after_limit
-    STRONG_ANSWER,                                                       # strong → move_next_tag
-    "The AI personalizes event ranking based on student goals.",         # partial
-]
-
-MAX_ATTEMPTS_ALLOWED = 2  # must match battle_flow.MAX_ATTEMPTS_PER_ATTACK_TAG
-
-
-def post(path: str, body: dict) -> dict:
-    url = f"{BASE_URL}{path}"
-    resp = requests.post(url, json=body, timeout=60)
-    resp.raise_for_status()
-    return resp.json()
-
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    marker = "PASS" if condition else "FAIL"
-    suffix = f" — {detail}" if detail else ""
-    print(f"  {marker}  {label}{suffix}")
-    if not condition:
-        sys.exit(1)
-
-
-def main() -> None:
-    print(f"\nPhase 3B Battle Flow Test\nBase URL: {BASE_URL}\n")
-
-    # --- start-session ---
-    print("Step 0: POST /api/start-session")
-    try:
-        start = post("/api/start-session", {
-            "mode": "pitch_battle",
-            "startup": SAMPLE_STARTUP,
-            "persona": "hackathon_judge",
-            "difficulty": "high",
-            "input_mode": "text",
-            "model_mode": "premium_nvidia",
-        })
-    except Exception as exc:
-        print(f"  FAIL  Request failed: {exc}")
-        sys.exit(1)
-
-    session_id = start.get("session_id")
-    check("session_id present", bool(session_id))
-    check("ai_message non-empty", bool(start.get("ai_message")))
-    check("judge_action = opening_question", start.get("judge_action") == "opening_question",
-          f"got {start.get('judge_action')!r}")
-    check("answer_quality is None", start.get("answer_quality") is None,
-          f"got {start.get('answer_quality')!r}")
-    check("tag_attempt = 1", start.get("tag_attempt") == 1, f"got {start.get('tag_attempt')!r}")
-
-    opening_tag = start.get("attack_tag")
-    print(f"  opening attack_tag : {opening_tag}")
-    print(f"  ai_message         : {start['ai_message'][:120]}...\n")
-
-    # Track tag attempt counts locally to verify the invariant
-    tag_attempts: dict[str, int] = defaultdict(int)
-    tag_attempts[opening_tag] += 1
-
-    rounds: list[dict] = []
-
-    # --- chat rounds ---
-    for i, answer in enumerate(ANSWERS, start=1):
-        round_num = i + 1  # round 1 was the opening
-        print(f"Step {i}: POST /api/chat-round  (sending: {answer!r})")
-
-        try:
-            data = post("/api/chat-round", {
-                "session_id": session_id,
-                "user_message": answer,
-            })
-        except Exception as exc:
-            print(f"  FAIL  Request failed: {exc}")
-            sys.exit(1)
-
-        atag = data.get("attack_tag", "")
-        aq = data.get("answer_quality", "")
-        ja = data.get("judge_action", "")
-        attempt = data.get("tag_attempt", 0)
-        satisfied = data.get("topic_satisfied")
-        prev_tag = data.get("previous_attack_tag", "")
-
-        # Update local tracking
-        tag_attempts[atag] += 1
-
-        print(f"  round              : {data.get('round')}")
-        print(f"  attack_tag         : {atag}")
-        print(f"  previous_tag       : {prev_tag}")
-        print(f"  answer_quality     : {aq}")
-        print(f"  judge_action       : {ja}")
-        print(f"  tag_attempt        : {attempt}")
-        print(f"  topic_satisfied    : {satisfied}")
-        print(f"  model_ok           : {data.get('model_ok')}")
-        print(f"  provider           : {data.get('provider')}")
-        print(f"  ai_message         : {data.get('ai_message', '')[:120]}...\n")
-
-        # Required field checks
-        check("session_id echoed", data.get("session_id") == session_id)
-        check("ai_message non-empty", bool(data.get("ai_message")), "ai_message is empty")
-        check("attack_tag present", bool(atag))
-        check("answer_quality present", aq in ("strong", "partial", "weak", "non_answer"),
-              f"got {aq!r}")
-        check("judge_action present", ja in ("follow_up_same_tag", "move_next_tag", "move_after_limit"),
-              f"got {ja!r}")
-        check("tag_attempt present", isinstance(attempt, int) and attempt >= 1,
-              f"got {attempt!r}")
-        check("provider present", bool(data.get("provider")))
-
-        rounds.append(data)
-
-    # --- Invariant: no tag exceeded MAX_ATTEMPTS_ALLOWED across all rounds ---
-    print("Invariant check: no attack_tag exceeded MAX_ATTEMPTS_PER_ATTACK_TAG")
-    for tag, count in tag_attempts.items():
-        if tag in ("Round Limit", "Session Error"):
-            continue
-        check(
-            f"  tag '{tag}' attempts <= {MAX_ATTEMPTS_ALLOWED}",
-            count <= MAX_ATTEMPTS_ALLOWED,
-            f"got {count} attempts",
-        )
-
-    # --- Verify first weak answer triggered follow_up_same_tag (not a random jump) ---
-    first = rounds[0]
-    first_ja = first.get("judge_action", "")
-    check(
-        "First weak answer → follow_up or move (not random jump)",
-        first_ja in ("follow_up_same_tag", "move_after_limit", "move_next_tag"),
-        f"got {first_ja!r}",
-    )
-
-    # --- Verify third answer ("ok") did not keep drilling the same tag forever ---
-    if len(rounds) >= 3:
-        third_ja = rounds[2].get("judge_action", "")
-        check(
-            "After 2nd non-answer on same tag, judge moved or pressed (no infinite loop)",
-            third_ja in ("move_after_limit", "move_next_tag", "follow_up_same_tag"),
-            f"got {third_ja!r}",
-        )
-
-    # --- Strong-answer checks (rounds[3] = STRONG_ANSWER) ---
-    if len(rounds) >= 4:
-        strong_round = rounds[3]
-        strong_ja = strong_round.get("judge_action", "")
-        strong_tag = strong_round.get("attack_tag", "")
-        strong_prev = strong_round.get("previous_attack_tag", "")
-        strong_satisfied = strong_round.get("topic_satisfied")
-
-        print("\nStrong-answer invariant checks:")
-        check(
-            "Strong answer → judge_action is move_next_tag",
-            strong_ja == "move_next_tag",
-            f"got {strong_ja!r}",
-        )
-        check(
-            "Strong answer → attack_tag changed from previous_attack_tag",
-            strong_tag != strong_prev,
-            f"both are {strong_tag!r} — judge did not advance",
-        )
-        check(
-            "Strong answer → topic_satisfied is True",
-            strong_satisfied is True,
-            f"got {strong_satisfied!r}",
-        )
-        check(
-            "Strong answer → answer_quality is 'strong'",
-            strong_round.get("answer_quality") == "strong",
-            f"got {strong_round.get('answer_quality')!r}",
-        )
-
-    print("\nAll Phase 3B checks passed. Socratic battle flow is working.\n")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

scripts/test_phase4_battle_stability.py

@@ -1,261 +0,0 @@
-"""Phase 4 stability test: full battle lifecycle via the running server.
-
-Validates:
-  - Battle runs cleanly from start to and beyond MAX_ROUNDS
-  - Strong answer causes move_next_tag with different attack_tag
-  - No attack_tag exceeds 2 attempts
-  - At round >= MAX_ROUNDS: soft_round_limit_reached=True, battle_complete=False, can_continue=True
-  - Chat continues working after MAX_ROUNDS (no hard block)
-  - /api/end-battle returns a scorecard dict (even if mock)
-  - Every ai_message is non-empty throughout
-  - No ai_message contains instruction leakage patterns
-
-Usage:
-  python scripts/test_phase4_battle_stability.py
-  PITCHFIGHT_BASE_URL=http://localhost:7861 python scripts/test_phase4_battle_stability.py
-"""
-
-from __future__ import annotations
-
-import os
-import re
-import sys
-from collections import defaultdict
-
-import requests
-
-BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
-MAX_ROUNDS = int(os.getenv("MAX_ROUNDS", "6"))
-
-SAMPLE_STARTUP = {
-    "name": "EventRadar AI",
-    "problem": "Students miss relevant hackathons, workshops, and networking events.",
-    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
-    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
-    "stage": "Prototype",
-    "team": "2 founders",
-    "traction": "50 beta signups, no revenue yet",
-}
-
-STRONG_ANSWER = (
-    "We validated this with 50 beta users, 3 campus ambassadors, "
-    "and weekly event-miss reports from two colleges."
-)
-
-# Sequence designed to exercise all branches: weak → non_answer → strong → partial → weak → strong
-ANSWER_SEQUENCE = [
-    "It is a pretty big market because students attend events often.",   # weak
-    "I don't know",                                                       # non_answer
-    STRONG_ANSWER,                                                        # strong → move_next_tag
-    "The AI ranks events based on student interest profiles.",            # partial
-    "okay fine",                                                          # non_answer
-    "We use embeddings and a ranking model trained on student behavior.", # strong (technical)
-    "It is useful and helpful for everyone.",                             # weak — beyond MAX_ROUNDS
-]
-
-_LEAKAGE_PATTERNS = re.compile(
-    r"we need to\b|the prompt says\b|as instructed\b|my instructions\b"
-    r"|i am supposed to\b|i should follow\b|the rules say\b|per the instructions?\b",
-    re.IGNORECASE,
-)
-
-
-def post(path: str, body: dict, timeout: int = 90) -> dict:
-    resp = requests.post(f"{BASE_URL}{path}", json=body, timeout=timeout)
-    resp.raise_for_status()
-    return resp.json()
-
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    marker = "PASS" if condition else "FAIL"
-    suffix = f" — {detail}" if detail else ""
-    print(f"  {marker}  {label}{suffix}")
-    if not condition:
-        sys.exit(1)
-
-
-def main() -> None:
-    print(f"\nPhase 4 Battle Stability Test (Soft Round Limit)")
-    print(f"Base URL  : {BASE_URL}")
-    print(f"MAX_ROUNDS: {MAX_ROUNDS}\n")
-
-    # -------------------------------------------------------------------------
-    # Step 0: Start session
-    # -------------------------------------------------------------------------
-    print("Step 0: POST /api/start-session")
-    try:
-        start = post("/api/start-session", {
-            "mode": "pitch_battle",
-            "startup": SAMPLE_STARTUP,
-            "persona": "hackathon_judge",
-            "difficulty": "high",
-            "input_mode": "text",
-            "model_mode": "premium_nvidia",
-        })
-    except Exception as exc:
-        print(f"  FAIL  Request failed: {exc}")
-        sys.exit(1)
-
-    session_id = start.get("session_id")
-    check("session_id present", bool(session_id))
-    check("ai_message non-empty", bool(start.get("ai_message")))
-    check("round == 1", start.get("round") == 1, f"got {start.get('round')}")
-    check("judge_action == opening_question", start.get("judge_action") == "opening_question")
-    check("battle_complete=False at start", start.get("battle_complete") is False)
-    check("can_continue=True at start", start.get("can_continue") is True)
-
-    opening_tag = start.get("attack_tag")
-    print(f"  opening_tag  : {opening_tag}")
-    print(f"  battle_phase : {start.get('battle_phase')}")
-    print(f"  ai_message   : {start['ai_message'][:100]}...\n")
-
-    check(
-        "start ai_message has no leakage",
-        not _LEAKAGE_PATTERNS.search(start.get("ai_message", "")),
-        "instruction leakage detected in opening message",
-    )
-
-    # -------------------------------------------------------------------------
-    # Steps 1..MAX_ROUNDS+1: chat rounds (one beyond soft limit)
-    # -------------------------------------------------------------------------
-    tag_attempt_counts: dict[str, int] = defaultdict(int)
-    tag_attempt_counts[opening_tag] += 1
-
-    rounds: list[dict] = []
-    strong_round_idx: int | None = None
-
-    answers_to_send = ANSWER_SEQUENCE[: MAX_ROUNDS + 1]  # include one beyond soft limit
-
-    for i, answer in enumerate(answers_to_send):
-        print(f"Step {i + 1}: POST /api/chat-round  answer={answer[:60]!r}")
-        try:
-            data = post("/api/chat-round", {
-                "session_id": session_id,
-                "user_message": answer,
-            })
-        except Exception as exc:
-            print(f"  FAIL  Request failed: {exc}")
-            sys.exit(1)
-
-        atag     = data.get("attack_tag", "")
-        aq       = data.get("answer_quality", "")
-        ja       = data.get("judge_action", "")
-        prev_tag = data.get("previous_attack_tag", "")
-        rnd      = data.get("round", 0)
-        bc       = data.get("battle_complete", True)
-        cc       = data.get("can_continue", False)
-        na       = data.get("next_action", "")
-        sl       = data.get("soft_round_limit_reached", False)
-        phase    = data.get("battle_phase", "")
-
-        if atag not in ("Round Limit", "Session Error", ""):
-            tag_attempt_counts[atag] += 1
-
-        print(f"  round                   : {rnd}")
-        print(f"  battle_phase            : {phase}")
-        print(f"  attack_tag              : {atag}")
-        print(f"  prev_tag                : {prev_tag}")
-        print(f"  answer_quality          : {aq}")
-        print(f"  judge_action            : {ja}")
-        print(f"  battle_complete         : {bc}  can_continue: {cc}  next_action: {na}")
-        print(f"  soft_round_limit_reached: {sl}")
-        print(f"  model_ok                : {data.get('model_ok')}  provider: {data.get('provider')}")
-        print(f"  ai_message              : {data.get('ai_message', '')[:100]}...\n")
-
-        # Required fields
-        check("session_id echoed", data.get("session_id") == session_id)
-        check("ai_message non-empty", bool(data.get("ai_message")), "empty ai_message")
-        check("attack_tag present", bool(atag))
-        check("provider present", bool(data.get("provider")))
-        check("model_mode present", bool(data.get("model_mode")))
-
-        # battle_complete must always be False (soft limit only)
-        check("battle_complete always False", bc is False, f"got {bc!r}")
-        check("can_continue always True", cc is True, f"got {cc!r}")
-        check("next_action always continue", na == "continue", f"got {na!r}")
-
-        # Soft limit flag
-        if rnd >= MAX_ROUNDS:
-            check("soft_round_limit_reached=True at/after MAX_ROUNDS", sl is True, f"got {sl!r}")
-            check(
-                "recommended_action=end_battle when soft limit",
-                data.get("recommended_action") == "end_battle",
-                f"got {data.get('recommended_action')!r}",
-            )
-        else:
-            check("soft_round_limit_reached=False before MAX_ROUNDS", sl is False, f"got {sl!r}")
-
-        # Valid answer quality and judge action on normal rounds
-        if atag not in ("Round Limit",):
-            check(
-                "answer_quality valid",
-                aq in ("strong", "partial", "weak", "non_answer"),
-                f"got {aq!r}",
-            )
-            check(
-                "judge_action valid",
-                ja in ("follow_up_same_tag", "move_next_tag", "move_after_limit"),
-                f"got {ja!r}",
-            )
-
-        # No leakage
-        ai_msg = data.get("ai_message", "")
-        check(
-            "ai_message has no instruction leakage",
-            not _LEAKAGE_PATTERNS.search(ai_msg),
-            "instruction leakage detected",
-        )
-
-        # battle_phase progression
-        if rnd <= 3:
-            check("battle_phase=explore in rounds 1-3", phase == "explore", f"got {phase!r}")
-        elif rnd <= 6:
-            check("battle_phase=pressure in rounds 4-6", phase == "pressure", f"got {phase!r}")
-        else:
-            check("battle_phase=close in rounds 7+", phase == "close", f"got {phase!r}")
-
-        # Strong answer invariant
-        if aq == "strong" and strong_round_idx is None:
-            strong_round_idx = i
-            check("Strong answer → judge_action is move_next_tag", ja == "move_next_tag", f"got {ja!r}")
-            check("Strong answer → attack_tag changed", atag != prev_tag, f"both are {atag!r}")
-            check("Strong answer → topic_satisfied is True", data.get("topic_satisfied") is True)
-
-        rounds.append(data)
-
-    # -------------------------------------------------------------------------
-    # Invariant: no attack_tag exceeded 2 attempts
-    # -------------------------------------------------------------------------
-    print("Invariant: no attack_tag exceeded MAX_ATTEMPTS_PER_ATTACK_TAG (2)")
-    for tag, count in tag_attempt_counts.items():
-        if tag in ("Round Limit", "Session Error", ""):
-            continue
-        check(f"  tag '{tag}' attempts <= 2", count <= 2, f"got {count}")
-
-    # -------------------------------------------------------------------------
-    # /api/end-battle — must return a scorecard dict (mock is fine)
-    # -------------------------------------------------------------------------
-    print("\nStep final: POST /api/end-battle")
-    try:
-        scorecard = post("/api/end-battle", {"session_id": session_id})
-    except Exception as exc:
-        print(f"  FAIL  end-battle request failed: {exc}")
-        sys.exit(1)
-
-    print(f"  overall         : {scorecard.get('overall')}")
-    print(f"  overall_label   : {scorecard.get('overall_label')}")
-    print(f"  scorecard_source: {scorecard.get('scorecard_source')}")
-    print(f"  keys            : {list(scorecard.keys())}")
-
-    check("end-battle returns dict", isinstance(scorecard, dict))
-    check("no error in end-battle", "error" not in scorecard, f"error={scorecard.get('error')}")
-    check("overall score present", "overall" in scorecard, f"keys={list(scorecard.keys())}")
-    check("overall_label present", "overall_label" in scorecard)
-    check("scorecard_source present", "scorecard_source" in scorecard)
-
-    print("\nAll Phase 4 stability checks passed.\n")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

scripts/test_phase5_scorecard.py

@@ -1,329 +0,0 @@
-"""Phase 5D scorecard test: hybrid claim-based scoring via the running server.
-
-Validates:
-  - /api/end-battle returns all required fields
-  - All 6 score dimensions present with integer scores 0-100
-  - Score labels use 5-band scheme (Not addressed / Developing / Solid / Strong / Excellent)
-  - top_3_questions has exactly 3 items
-  - model_ok, provider, scorecard_source present
-  - concrete_signals_summary present with required sub-keys
-  - scorecard_source in ("hybrid_claims_nemotron", "hybrid_claims_local")
-  - provider in ("local+nvidia", "local")
-  - Set STRICT_NEMOTRON_COACHING=true to fail if not hybrid_claims_nemotron
-  - Conversation includes "50 beta users" and "3 campus ambassadors" →
-    expect these signals to appear in concrete_signals_summary or scores
-  - No old static mock content
-
-Usage:
-  python scripts/test_phase5_scorecard.py
-  PITCHFIGHT_BASE_URL=http://localhost:7861 python scripts/test_phase5_scorecard.py
-  STRICT_NEMOTRON_COACHING=true python scripts/test_phase5_scorecard.py
-
-Server must already be running (python app.py).
-"""
-
-from __future__ import annotations
-
-import os
-import re
-import sys
-
-import requests
-
-BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
-STRICT_COACHING = os.getenv("STRICT_NEMOTRON_COACHING", "false").strip().lower() == "true"
-# Legacy flag kept for compatibility
-ALLOW_FALLBACK = os.getenv("ALLOW_SCORECARD_FALLBACK", "false").strip().lower() == "true"
-
-SAMPLE_STARTUP = {
-    "name": "EventRadar AI",
-    "problem": "Students miss relevant hackathons, workshops, and networking events.",
-    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
-    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
-    "stage": "Prototype",
-    "team": "2 founders",
-    "traction": "50 beta signups, no revenue yet",
-}
-
-STRONG_ANSWER = (
-    "We validated this with 50 beta users, 3 campus ambassadors, "
-    "and weekly event-miss reports from two colleges."
-)
-
-ANSWERS = [
-    "It is a big market because students attend events often.",    # weak
-    "I don't know",                                               # non_answer
-    STRONG_ANSWER,                                                # strong → evidence
-    "The AI personalizes event ranking based on student goals.",  # partial
-]
-
-REQUIRED_DIMS = {
-    "clarity",
-    "problem_understanding",
-    "market_awareness",
-    "differentiation",
-    "business_model",
-    "objection_handling",
-}
-
-_VALID_LABELS = {"Not addressed", "Developing", "Solid", "Strong", "Excellent"}
-_VALID_SOURCES = {"hybrid_claims_nemotron", "hybrid_claims_local"}
-_VALID_PROVIDERS = {"local+nvidia", "local"}
-
-_LEAKAGE = re.compile(
-    r"we need to\b|the prompt says\b|as instructed\b|my instructions\b"
-    r"|i am supposed to\b|the rules say\b",
-    re.IGNORECASE,
-)
-
-
-def post(path: str, body: dict, timeout: int = 120) -> dict:
-    resp = requests.post(f"{BASE_URL}{path}", json=body, timeout=timeout)
-    resp.raise_for_status()
-    return resp.json()
-
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    marker = "PASS" if condition else "FAIL"
-    suffix = f" — {detail}" if detail else ""
-    print(f"  {marker}  {label}{suffix}")
-    if not condition:
-        sys.exit(1)
-
-
-def main() -> None:
-    print(f"\nPhase 5D Scorecard Test (Hybrid Claim-Based)")
-    print(f"Base URL             : {BASE_URL}")
-    print(f"Strict Nemotron      : {STRICT_COACHING}")
-    print()
-
-    # -------------------------------------------------------------------------
-    # Step 0: Start session
-    # -------------------------------------------------------------------------
-    print("Step 0: POST /api/start-session")
-    try:
-        start = post("/api/start-session", {
-            "mode": "pitch_battle",
-            "startup": SAMPLE_STARTUP,
-            "persona": "hackathon_judge",
-            "difficulty": "high",
-            "input_mode": "text",
-            "model_mode": "premium_nvidia",
-        })
-    except Exception as exc:
-        print(f"  FAIL  Could not start session: {exc}")
-        sys.exit(1)
-
-    session_id = start.get("session_id")
-    check("session_id present", bool(session_id))
-    check("ai_message non-empty", bool(start.get("ai_message")))
-    print(f"  session_id  : {session_id}")
-    print(f"  attack_tag  : {start.get('attack_tag')}")
-    print(f"  ai_message  : {start.get('ai_message', '')[:100]}...\n")
-
-    # -------------------------------------------------------------------------
-    # Steps 1-N: Send answers
-    # -------------------------------------------------------------------------
-    for i, answer in enumerate(ANSWERS):
-        print(f"Step {i + 1}: POST /api/chat-round  answer={answer[:60]!r}")
-        try:
-            data = post("/api/chat-round", {
-                "session_id": session_id,
-                "user_message": answer,
-            })
-        except Exception as exc:
-            print(f"  FAIL  chat-round failed: {exc}")
-            sys.exit(1)
-
-        check("session_id echoed", data.get("session_id") == session_id)
-        check("ai_message non-empty", bool(data.get("ai_message")))
-        print(
-            f"  round={data.get('round')}  "
-            f"quality={data.get('answer_quality')}  "
-            f"action={data.get('judge_action')}  "
-            f"tag={data.get('attack_tag')}\n"
-        )
-
-    # -------------------------------------------------------------------------
-    # Final: POST /api/end-battle
-    # -------------------------------------------------------------------------
-    print("Final step: POST /api/end-battle  (local scoring is fast; Nemotron coaching may take ~60s)")
-    try:
-        sc = post("/api/end-battle", {"session_id": session_id}, timeout=180)
-    except Exception as exc:
-        print(f"  FAIL  end-battle request failed: {exc}")
-        sys.exit(1)
-
-    # --- Top-level required fields ---
-    check("overall present", "overall" in sc, f"keys={list(sc.keys())}")
-    check("overall_label present", "overall_label" in sc)
-    check("scores present", "scores" in sc)
-    check("best_answer present", "best_answer" in sc)
-    check("weakest_answer present", "weakest_answer" in sc)
-    check("improved_answer present", "improved_answer" in sc)
-    check("improved_pitch present", "improved_pitch" in sc)
-    check("top_3_questions present", "top_3_questions" in sc)
-    check("model_ok present", "model_ok" in sc)
-    check("provider present", "provider" in sc)
-    check("scorecard_source present", "scorecard_source" in sc)
-    check("no error key", "error" not in sc, f"error={sc.get('error')}")
-
-    overall = sc.get("overall", -1)
-    check("overall is int 0-100", isinstance(overall, int) and 0 <= overall <= 100, f"got {overall!r}")
-    check(
-        "overall_label valid",
-        sc.get("overall_label") in _VALID_LABELS,
-        f"got {sc.get('overall_label')!r}",
-    )
-
-    # --- concrete_signals_summary ---
-    css = sc.get("concrete_signals_summary")
-    check("concrete_signals_summary present", isinstance(css, dict), f"got {type(css).__name__}")
-    if isinstance(css, dict):
-        for key in ("numbers", "validation", "competitors", "revenue_signals", "technical_mechanisms"):
-            check(
-                f"concrete_signals_summary.{key} is list",
-                isinstance(css.get(key), list),
-                f"got {type(css.get(key)).__name__}",
-            )
-
-    # --- Dimension checks ---
-    scores = sc.get("scores", {})
-    check("all 6 dimensions present", REQUIRED_DIMS <= set(scores.keys()),
-          f"missing={REQUIRED_DIMS - set(scores.keys())}")
-
-    for dim in REQUIRED_DIMS:
-        dim_data = scores.get(dim, {})
-        dim_score = dim_data.get("score", -1)
-        check(
-            f"{dim}.score is int 0-100",
-            isinstance(dim_score, int) and 0 <= dim_score <= 100,
-            f"got {dim_score!r}",
-        )
-        check(f"{dim}.reason non-empty", bool(dim_data.get("reason")))
-        check(
-            f"{dim}.label is valid",
-            dim_data.get("label") in _VALID_LABELS,
-            f"got {dim_data.get('label')!r}",
-        )
-        check(
-            f"{dim}.signals_used is list",
-            isinstance(dim_data.get("signals_used", []), list),
-        )
-
-    # --- top_3_questions ---
-    top3 = sc.get("top_3_questions", [])
-    check("top_3_questions is list", isinstance(top3, list))
-    check("top_3_questions has exactly 3", len(top3) == 3, f"got {len(top3)}")
-    for q in top3:
-        check("question is non-empty string", isinstance(q, str) and bool(q.strip()))
-
-    # --- Source and provider checks (Phase 5D: hybrid architecture) ---
-    source = sc.get("scorecard_source", "")
-    model_ok = sc.get("model_ok")
-    provider = sc.get("provider", "")
-
-    check(
-        "scorecard_source is hybrid",
-        source in _VALID_SOURCES,
-        f"got {source!r} — expected one of {_VALID_SOURCES}",
-    )
-    check(
-        "provider is local or local+nvidia",
-        provider in _VALID_PROVIDERS,
-        f"got {provider!r}",
-    )
-    check("model_ok is bool", isinstance(model_ok, bool), f"got {type(model_ok).__name__}")
-
-    if STRICT_COACHING and source != "hybrid_claims_nemotron":
-        print(
-            f"\n  FAIL  STRICT_NEMOTRON_COACHING=true but source={source!r}\n"
-            f"  model_error: {sc.get('model_error', 'none')}\n"
-            "  Nemotron coaching did not produce valid JSON."
-        )
-        sys.exit(1)
-    elif source == "hybrid_claims_local":
-        print(f"  NOTE: hybrid_claims_local — Nemotron coaching unavailable, local fallback used.")
-        print(f"  model_error: {sc.get('model_error', 'none')}")
-    else:
-        print(f"  NOTE: hybrid_claims_nemotron — Nemotron coaching succeeded.")
-
-    # --- Evidence detection: "50 beta users" should appear in signals/scores ---
-    evidence_terms = ["50 beta", "campus ambassador", "event-miss report", "validated", "beta users"]
-    evidence_fields = [
-        str(sc.get("best_answer", "")),
-        str(sc.get("improved_answer", "")),
-        str(sc.get("improved_pitch", "")),
-    ]
-    for dim in REQUIRED_DIMS:
-        evidence_fields.append(str(scores.get(dim, {}).get("reason", "")))
-        for sig in scores.get(dim, {}).get("signals_used", []):
-            evidence_fields.append(str(sig))
-    if isinstance(css, dict):
-        for key in ("numbers", "validation"):
-            evidence_fields.extend(str(x) for x in css.get(key, []))
-    combined = " ".join(evidence_fields).lower()
-    evidence_found = any(t.lower() in combined for t in evidence_terms)
-    if evidence_found:
-        print("  PASS  Scorecard acknowledges concrete validation evidence from STRONG_ANSWER")
-    else:
-        print("  NOTE  Scorecard did not explicitly reference validation evidence (not a hard fail in 5D)")
-
-    # --- No static EventRadar mock content ---
-    all_text = " ".join([
-        str(sc.get("best_answer", "")),
-        str(sc.get("weakest_answer", "")),
-        str(sc.get("improved_answer", "")),
-        str(sc.get("improved_pitch", "")),
-    ])
-    check(
-        "no static WhatsApp groups mock content",
-        "WhatsApp groups" not in all_text or "EventRadar" in SAMPLE_STARTUP.get("name", ""),
-    )
-
-    # --- Leakage check ---
-    scorecard_text = " ".join([
-        str(sc.get("best_answer", "")),
-        str(sc.get("weakest_answer", "")),
-        str(sc.get("improved_answer", "")),
-        str(sc.get("improved_pitch", "")),
-        str(sc.get("why_weak", "")),
-    ])
-    check("no leakage in scorecard text", not _LEAKAGE.search(scorecard_text), "instruction leakage detected")
-
-    # -------------------------------------------------------------------------
-    # Summary
-    # -------------------------------------------------------------------------
-    print("\n--- Scorecard Summary ---")
-    print(f"  scorecard_source : {sc.get('scorecard_source')}")
-    print(f"  model_ok         : {sc.get('model_ok')}  provider: {sc.get('provider')}")
-    print(f"  overall          : {overall}  ({sc.get('overall_label')})")
-    print()
-    for dim in REQUIRED_DIMS:
-        d = scores.get(dim, {})
-        sigs = d.get("signals_used", [])
-        print(
-            f"  {dim:<25}  score={d.get('score', '?'):>3}  [{d.get('label', '?')}]"
-            + (f"  sigs={sigs[:2]}" if sigs else "")
-        )
-    print()
-    print(f"  weakest_answer   : {sc.get('weakest_answer', '')[:120]}")
-    print(f"  improved_answer  : {sc.get('improved_answer', '')[:120]}")
-    print(f"  top_3_questions  :")
-    for q in top3:
-        print(f"    - {q}")
-    if isinstance(css, dict):
-        print(f"\n  concrete_signals_summary:")
-        for k, v in css.items():
-            if v:
-                print(f"    {k}: {v[:3]}")
-
-    if sc.get("model_error"):
-        print(f"\n  model_error : {sc.get('model_error')}")
-
-    print("\nAll Phase 5D scorecard checks passed.\n")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

scripts/test_phase5b_refinement.py

@@ -1,240 +0,0 @@
-"""Phase 5B/5D refinement test: 8+ rounds, soft limit, battle_phase, labels, no leakage.
-
-Validates:
-  - User can continue chatting past MAX_ROUNDS (no hard block)
-  - soft_round_limit_reached appears at round >= MAX_ROUNDS
-  - battle_phase progresses: explore (1-3), pressure (4-6), close (7+)
-  - No instruction leakage in any ai_message
-  - /api/end-battle returns hybrid claim-based scorecard with score labels
-  - overall_label and per-dimension labels present
-  - scorecard_source in ("hybrid_claims_nemotron", "hybrid_claims_local")
-
-Usage:
-  python scripts/test_phase5b_refinement.py
-  ALLOW_SCORECARD_FALLBACK=true python scripts/test_phase5b_refinement.py
-"""
-
-from __future__ import annotations
-
-import os
-import re
-import sys
-
-import requests
-
-BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
-ALLOW_FALLBACK = os.getenv("ALLOW_SCORECARD_FALLBACK", "false").strip().lower() == "true"
-MAX_ROUNDS = int(os.getenv("MAX_ROUNDS", "6"))
-
-SAMPLE_STARTUP = {
-    "name": "EventRadar AI",
-    "problem": "Students miss relevant hackathons, workshops, and networking events.",
-    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
-    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
-    "stage": "Prototype",
-    "team": "2 founders",
-    "traction": "50 beta signups, no revenue yet",
-}
-
-STRONG_ANSWER = (
-    "We validated this with 50 beta users, 3 campus ambassadors, "
-    "and weekly event-miss reports from two colleges."
-)
-
-# 9 answers to go well past MAX_ROUNDS=6
-ANSWERS = [
-    "It is a pretty big market because students attend events often.",         # weak
-    "I don't know",                                                             # non_answer
-    STRONG_ANSWER,                                                              # strong
-    "The AI ranks events based on student interest profiles.",                  # partial
-    "We use embeddings and a ranking model trained on student behavior data.",  # strong
-    "okay",                                                                     # non_answer
-    "Our differentiation is the personalization layer no event aggregator has.",# partial
-    "We plan to charge colleges $500/month for analytics and promotions.",      # partial (revenue)
-    "We have 3 campus ambassadors onboarding 20 students each right now.",      # strong
-]
-
-REQUIRED_DIMS = {
-    "clarity", "problem_understanding", "market_awareness",
-    "differentiation", "business_model", "objection_handling",
-}
-_VALID_LABELS = {"Not addressed", "Developing", "Solid", "Strong", "Excellent"}
-
-_LEAKAGE = re.compile(
-    r"we need to\b|the prompt says\b|as instructed\b|my instructions\b"
-    r"|i am supposed to\b|i should follow\b|the rules say\b|per the instructions?\b",
-    re.IGNORECASE,
-)
-
-
-def post(path: str, body: dict, timeout: int = 180) -> dict:
-    resp = requests.post(f"{BASE_URL}{path}", json=body, timeout=timeout)
-    resp.raise_for_status()
-    return resp.json()
-
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    marker = "PASS" if condition else "FAIL"
-    suffix = f" — {detail}" if detail else ""
-    print(f"  {marker}  {label}{suffix}")
-    if not condition:
-        sys.exit(1)
-
-
-def main() -> None:
-    print(f"\nPhase 5B Refinement Test")
-    print(f"Base URL       : {BASE_URL}")
-    print(f"MAX_ROUNDS     : {MAX_ROUNDS}")
-    print(f"Allow fallback : {ALLOW_FALLBACK}")
-    print(f"Total answers  : {len(ANSWERS)} (well past MAX_ROUNDS)\n")
-
-    # -------------------------------------------------------------------------
-    # Step 0: Start session
-    # -------------------------------------------------------------------------
-    print("Step 0: POST /api/start-session")
-    try:
-        start = post("/api/start-session", {
-            "mode": "pitch_battle",
-            "startup": SAMPLE_STARTUP,
-            "persona": "hackathon_judge",
-            "difficulty": "high",
-            "input_mode": "text",
-            "model_mode": "premium_nvidia",
-        })
-    except Exception as exc:
-        print(f"  FAIL  Could not start session: {exc}")
-        sys.exit(1)
-
-    session_id = start.get("session_id")
-    check("session_id present", bool(session_id))
-    check("ai_message non-empty", bool(start.get("ai_message")))
-    check("battle_complete=False at start", start.get("battle_complete") is False)
-    check("can_continue=True at start", start.get("can_continue") is True)
-    check("battle_phase present", bool(start.get("battle_phase")))
-    check("start battle_phase=explore", start.get("battle_phase") == "explore",
-          f"got {start.get('battle_phase')!r}")
-    check("no leakage in opening", not _LEAKAGE.search(start.get("ai_message", "")))
-
-    print(f"  session_id   : {session_id}")
-    print(f"  attack_tag   : {start.get('attack_tag')}")
-    print(f"  battle_phase : {start.get('battle_phase')}")
-    print(f"  ai_message   : {start.get('ai_message', '')[:100]}...\n")
-
-    # -------------------------------------------------------------------------
-    # Steps 1..len(ANSWERS): send all answers, including past MAX_ROUNDS
-    # -------------------------------------------------------------------------
-    soft_limit_seen = False
-
-    for i, answer in enumerate(ANSWERS):
-        print(f"Step {i + 1}: POST /api/chat-round  answer={answer[:60]!r}")
-        try:
-            data = post("/api/chat-round", {"session_id": session_id, "user_message": answer})
-        except Exception as exc:
-            print(f"  FAIL  chat-round failed: {exc}")
-            sys.exit(1)
-
-        rnd   = data.get("round", 0)
-        phase = data.get("battle_phase", "")
-        sl    = data.get("soft_round_limit_reached", False)
-        bc    = data.get("battle_complete", True)
-        cc    = data.get("can_continue", False)
-        na    = data.get("next_action", "")
-        ai    = data.get("ai_message", "")
-
-        print(f"  round={rnd}  phase={phase}  soft_limit={sl}  "
-              f"battle_complete={bc}  can_continue={cc}")
-        print(f"  ai_message: {ai[:100]}...\n")
-
-        # Always must continue
-        check("battle_complete=False (never hard-stopped)", bc is False, f"round={rnd}")
-        check("can_continue=True (always)", cc is True, f"round={rnd}")
-        check("next_action=continue (always)", na == "continue", f"got {na!r}")
-        check("ai_message non-empty", bool(ai))
-        check("no leakage in ai_message", not _LEAKAGE.search(ai),
-              f"leakage at round {rnd}")
-
-        # Soft limit
-        if rnd >= MAX_ROUNDS:
-            check("soft_round_limit_reached=True", sl is True, f"round={rnd}")
-            if sl:
-                soft_limit_seen = True
-        else:
-            check("soft_round_limit_reached=False", sl is False, f"round={rnd}")
-
-        # Battle phase progression
-        if 1 <= rnd <= 3:
-            check(f"phase=explore at round {rnd}", phase == "explore", f"got {phase!r}")
-        elif 4 <= rnd <= 6:
-            check(f"phase=pressure at round {rnd}", phase == "pressure", f"got {phase!r}")
-        elif rnd >= 7:
-            check(f"phase=close at round {rnd}", phase == "close", f"got {phase!r}")
-
-    check("soft_round_limit_reached appeared at least once", soft_limit_seen)
-
-    # -------------------------------------------------------------------------
-    # Final: POST /api/end-battle
-    # -------------------------------------------------------------------------
-    print(f"\nFinal: POST /api/end-battle (may take up to 3 minutes)")
-    try:
-        sc = post("/api/end-battle", {"session_id": session_id}, timeout=240)
-    except Exception as exc:
-        print(f"  FAIL  end-battle failed: {exc}")
-        sys.exit(1)
-
-    # Top-level fields
-    check("overall present", "overall" in sc)
-    check("overall_label present", "overall_label" in sc)
-    check("scores present", "scores" in sc)
-    check("scorecard_source present", "scorecard_source" in sc)
-    check("model_ok present", "model_ok" in sc)
-
-    overall = sc.get("overall", -1)
-    check("overall 0-100", isinstance(overall, int) and 0 <= overall <= 100, f"got {overall!r}")
-    check(
-        "overall_label valid",
-        sc.get("overall_label") in _VALID_LABELS,
-        f"got {sc.get('overall_label')!r}",
-    )
-
-    # Dimension labels
-    scores = sc.get("scores", {})
-    check("all 6 dims present", REQUIRED_DIMS <= set(scores.keys()))
-    for dim in REQUIRED_DIMS:
-        d = scores.get(dim, {})
-        check(f"{dim}.label valid", d.get("label") in _VALID_LABELS, f"got {d.get('label')!r}")
-        dim_score = d.get("score", -1)
-        check(f"{dim}.score 0-100", isinstance(dim_score, int) and 0 <= dim_score <= 100)
-
-    # Scorecard source check (Phase 5D: hybrid architecture)
-    source = sc.get("scorecard_source", "")
-    _hybrid_sources = {"hybrid_claims_nemotron", "hybrid_claims_local"}
-    check(
-        "scorecard_source is hybrid",
-        source in _hybrid_sources,
-        f"got {source!r} — expected one of {_hybrid_sources}",
-    )
-    check(
-        "provider is local or local+nvidia",
-        sc.get("provider") in {"local+nvidia", "local"},
-        f"got {sc.get('provider')!r}",
-    )
-    if source == "hybrid_claims_local":
-        print(f"  NOTE: hybrid_claims_local — Nemotron coaching unavailable, local fallback used.")
-        if sc.get("model_error"):
-            print(f"  model_error: {sc.get('model_error')}")
-    else:
-        print("  NOTE: hybrid_claims_nemotron — Nemotron coaching succeeded.")
-
-    print(f"\n--- Refinement Summary ---")
-    print(f"  scorecard_source : {sc.get('scorecard_source')}")
-    print(f"  overall          : {overall}  ({sc.get('overall_label')})")
-    for dim in REQUIRED_DIMS:
-        d = scores.get(dim, {})
-        print(f"  {dim:<25}  {d.get('score', '?'):>3}  [{d.get('label', '?')}]")
-
-    print("\nAll Phase 5B refinement checks passed.\n")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

tests/test_api_handlers.py

@@ -1,52 +0,0 @@
-"""Tests for shared API handlers."""
-
-import unittest
-
-from core.api_handlers import (
-    handle_chat_round,
-    handle_end_battle,
-    handle_load_sample,
-    handle_reset_session,
-    handle_start_session,
-    handle_voice_pitch_placeholder,
-)
-
-
-class TestApiHandlers(unittest.TestCase):
-    def test_load_sample(self):
-        result = handle_load_sample()
-        self.assertIn("startup", result)
-        self.assertEqual(result["startup"]["name"], "EventRadar AI")
-
-    def test_full_battle_flow(self):
-        start = handle_start_session(
-            {
-                "persona": "hackathon_judge",
-                "difficulty": "high",
-                "input_mode": "text",
-                "startup": handle_load_sample()["startup"],
-            }
-        )
-        session_id = start["session_id"]
-        self.assertEqual(start["round"], 1)
-
-        chat = handle_chat_round(
-            {"session_id": session_id, "user_message": "We rank events with AI."}
-        )
-        self.assertEqual(chat["session_id"], session_id)
-        self.assertEqual(chat["round"], 2)
-
-        scorecard = handle_end_battle({"session_id": session_id})
-        self.assertIn("overall", scorecard)
-        self.assertIn("scores", scorecard)
-
-        reset = handle_reset_session({"session_id": session_id})
-        self.assertEqual(reset["status"], "reset")
-
-    def test_voice_placeholder(self):
-        result = handle_voice_pitch_placeholder()
-        self.assertEqual(result["status"], "not_implemented")
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_json_parser.py

@@ -1,38 +0,0 @@
-"""Tests for JSON parsing utilities."""
-
-import json
-import unittest
-
-from core.json_utils import extract_json_block, fallback_scorecard, safe_json_parse
-
-
-class TestJsonParser(unittest.TestCase):
-    def test_safe_json_parse_raw_object(self):
-        payload = {"overall": 70, "scores": {}}
-        result = safe_json_parse(json.dumps(payload))
-        self.assertEqual(result["overall"], 70)
-
-    def test_safe_json_parse_fenced_block(self):
-        text = 'Here is the score:\n```json\n{"overall": 55}\n```'
-        result = safe_json_parse(text)
-        self.assertEqual(result["overall"], 55)
-
-    def test_safe_json_parse_invalid_returns_default(self):
-        result = safe_json_parse("not json at all", default={"ok": False})
-        self.assertEqual(result, {"ok": False})
-
-    def test_extract_json_block_from_text(self):
-        text = 'Analysis complete {"round": 2, "tag": "Moat"} thanks.'
-        block = extract_json_block(text)
-        self.assertIsNotNone(block)
-        self.assertEqual(json.loads(block)["tag"], "Moat")
-
-    def test_fallback_scorecard_shape(self):
-        card = fallback_scorecard()
-        self.assertIn("overall", card)
-        self.assertIn("scores", card)
-        self.assertIn("top_3_questions", card)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_prompts.py

@@ -1,28 +0,0 @@
-"""Tests for persona prompt builder."""
-
-import unittest
-
-from core.persona_builder import build_persona_prompt
-from core.samples import get_sample_startup
-
-
-class TestPrompts(unittest.TestCase):
-    def test_persona_prompt_not_empty(self):
-        startup = get_sample_startup()
-        prompt = build_persona_prompt("hackathon_judge", startup, difficulty="high")
-        self.assertTrue(prompt.strip())
-
-    def test_persona_prompt_includes_startup_name(self):
-        startup = get_sample_startup()
-        prompt = build_persona_prompt("technical_judge", startup)
-        self.assertIn("EventRadar AI", prompt)
-
-    def test_all_personas_build(self):
-        startup = get_sample_startup()
-        for persona in ("skeptical_vc", "technical_judge", "hackathon_judge"):
-            prompt = build_persona_prompt(persona, startup)
-            self.assertIn("Ask one sharp question", prompt)
-
-
-if __name__ == "__main__":
-    unittest.main()