Sidekick Equalizer

Sidekick Equalizer is a real-time AI negotiation coach that sits as a transparent, draggable overlay on your screen. It listens to your negotiation (via microphone) and provides instant, tactical advice to help you level the playing field.

🏗️ Architecture

┌─────────────┐     Audio      ┌─────────────┐
│   Electron  │ ──────────────▶│   FastAPI   │
│   Overlay   │    WebSocket   │   Backend   │
└─────────────┘                └──────┬──────┘
                                      │
                                      ▼
                               ┌─────────────┐
                               │ Core Engine │◀─── New!
                               │  (Logic)    │
                               └──────┬──────┘
                                      │
                                      ▼
                               ┌─────────────┐
                               │  Coach AI   │
                               │ (GPT-4o-mini)│
                               └─────────────┘

Tech Stack:

• Frontend: Electron + React (TypeScript) — Draggable floating HUD
• Backend: Python FastAPI — WebSocket server + AI pipeline
• Core Engine: Pure Python logic for tactic detection & signal gating
• Role Mapping: Strict User (Speaker 0) vs Counterparty (Speaker 1+) enforcement, with optional Test Mode override for demos
• AI: Deepgram Nova-2 (Streaming STT) + OpenAI GPT-4o-mini (Coach)

📱 App Store Mode (Mic Only)

For Mac App Store compliance, Sidekick supports a Mic Only mode that bypasses system audio capture:

Mode	Audio Source	Use Case
Standard	Mic + System Audio	Direct downloads, best quality
App Store	Mic Only	Mac App Store builds, uses speaker diarization

How Mic Only Works:

• User speaks into mic → Identified as Speaker 0 (USER)
• Counterparty voice comes through speakers → Picked up by mic as Speaker 1 (COUNTERPARTY)
• Deepgram's AI diarization separates the voices automatically

To enable App Store Mode:

# In frontend/.env
VITE_APP_STORE_MODE=true

⚠️ Note: In App Store Mode, users must use speakers (not headphones) so the counterparty's voice can be captured by the microphone.

---

🚀 Getting Started

1. Prerequisites

• Node.js: v18+
• Python: 3.10+ (recommend using conda)
• Deepgram API Key: Get one here
• OpenAI API Key: Get one here

2. Configure Environment

Create a .env file in backend/:

cd backend
cp .env.example .env

Add your keys:

OPENAI_API_KEY=sk-your-key-here
DEEPGRAM_API_KEY=your-deepgram-key-here

3. Installation

Backend:

cd backend
conda activate ai
pip install -r requirements.txt

Frontend:

cd frontend
npm install

---

▶️ How to Run

Open two terminals:

Terminal 1: Backend

cd backend && conda activate ai && python main.py

You should see: Uvicorn running on http://127.0.0.1:8000

Terminal 2: Frontend

cd frontend && npm run electron:dev

A draggable green overlay window will appear.

---

🎮 Usage Guide

Concept Definitions

Conversation Context

• General Business Conversation: Professional discussions involving leverage or persuasion.
• Vendor Pricing: Pricing discussions, concessions, terms, or service-level pushback.
• Scope & Deliverables: Preventing scope creep, timeline pressure, or unpaid expansion.
• Renewal / Upsell: Contract renewals, price increases, or expansion pressure.

Mode Preset

• Practice Mode: Solo/YouTube demo. Fast, permissive detection.
  • Use for: Self-training, testing against a video recording.
• Live Call: Two-party call. Real-time alerts with cleaner gating.
  • Use for: Real Zoom/Teams/Phone negotiations.
• Post Negotiation Analysis Only: No live prompts. Post-call summary only.
  • Use for: Recording a session silently to review later without distraction.

Standard Flow

1. Select Scenario: Vendor, Scope, Renewal, General.
2. Select Mode: Practice Mode / Live Call / Post Negotiation Analysis Only.
3. Initialize: Overlay appears in "LISTENING" state.

   CRITICAL: Ensure YOU (the User) speak the first sentence to lock in "Speaker 0" identity.

4. Negotiate:
   • In Live/Practice, watch for "⚠️ SIGNAL" alerts.
5. End Session: Click Stop -> Save Outcome (Won/Lost) -> Check "Include Expanded Debrief".
6. Report Card: Review the detailed breakdown:
   • Score: 0-100 Performance Rating.
   • Tactics Faced: List of specific tactics used against you (e.g., "ANCHORING: Seller asked for $125k").
   • Key Moments: Coaching on your "Strongest Move" and "Missed Opportunities".

Supported Tactics (Detection Engine v2)

The "Hybrid" engine combines real-time signal detection with LLM synthesis to identify:

• Anchoring: numeric_anchor, range_anchor, comparison_anchor
• Urgency: deadline, scarcity
• Authority: manager_deferral, policy_shield
• Framing: roi_reframe, monthly_breakdown, minimization
• Commitment Traps: conditional_commitment, reciprocity_gate
• Concessions: staged_concession, tradeoff_offer
• Bundling: add_on_bundle, take_it_or_leave_it_package
• Payment Deflection: monthly_focus, affordability_frame
• Loss Aversion: fear_of_missing_out, loss_warning
• Social Proof: popularity_claim, herd_reference

Session History Dashboard

• Access past negotiation reports by clicking the "History" button in Pre-Flight or Main Overlay.
• View stats at a glance: Date, Scenario, Duration, Score, and Outcome.
• Click any session to replay the detailed "Report Card" analysis.

---

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+S	Toggle pause/resume listening
Ctrl+Shift+E	End Session & Generate Report

---

✅ Verification & Testing

Live Simulation (Backend Only)

Test the analysis engine without the frontend or microphone:

cd backend
python scripts/simulate_live.py

This simulates a conversation with "User" and "Counterparty" lines to trigger tactics.

Unit Tests

Run the test suite (including new Role Mapping tests):

PYTHONPATH=/home/robert/Coding/equalizer/backend pytest backend/tests

---

📁 Project Structure

equalizer/
├── backend/
│   ├── core/                # pure logic (no web/db dependencies)
│   │   └── analysis_engine/ # tactic detection & schemas
│   ├── main.py              # FastAPI WebSocket server
│   ├── services/
│   │   ├── audio_processor.py
│   │   ├── coach.py         # Orchestrator (delegates to Core)
│   │   └── session_recorder.py
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── PreFlight.tsx    # Mode & Scenario selection
│   │   ├── Overlay.tsx      # Main HUD
│   │   └── ...
├── sessions/                # Local JSON recordings
├── agents.md                # Behavioral instructions
└── uat.md                   # User Acceptance Tests

---

🔮 Roadmap

See docs/POST_MVP_ROADMAP.md for details on:

• Phase 6: Local Inference (Llama 3)
• Phase 7: Latency Reduction

🏗️ Building for Production

To create a standalone application (AppImage for Linux, .app/.dmg for Mac):

1. Build the Backend

   cd backend
   ./build.sh
   # This creates a standalone executable in backend/dist/sidekick-backend
   # It uses a temporary, minimal virtual environment to keep the size small (~30MB)

2. Build the App

   cd frontend
   npm run build
   # This packages the React frontend + Python backend into a single app
   # Output: frontend/dist_electron/

Mac Note

To build for macOS, run the above commands on a Mac. The build scripts will automatically generate .app and .dmg files.