clarity-helper/README.md

<div align="center">
  <img width="1200" height="475" alt="Cognitive Clarity Banner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
  <h1>🧠 Cognitive Clarity</h1>
  <p><strong>An Adaptive Clinical Training & Multimodal Roleplay Environment for Cognitive Behavioral Therapy (CBT)</strong></p>
  <p>
    <a href="#key-features">Key Features</a> •
    <a href="#system-architecture">Architecture</a> •
    <a href="#getting-started">Getting Started</a> •
    <a href="#cbt-framework--scenarios">CBT Scenarios</a> •
    <a href="#serverless-backend-api">Serverless Backend</a> •
    <a href="#developer-tools--scripts">Developer Tools</a> •
    <a href="#agents--skills">Agents & Skills</a>
  </p>
</div>

---

## 🌟 Key Features

- **🎙️ Real-Time Voice & Text Roleplay**: Natural interactive voice roleplay and streaming text chat powered exclusively by OpenRouter (`google/gemini-3.8-flash`, `google/gemini-3.7-flash`, `anthropic/claude-3.5-haiku`, `meta-llama/llama-3.3-70b-instruct`) with WebAudio speech synthesis and FFT frequency visualization.
- **👁️ Out-of-Band Clinical Supervisor**: Real-time turn-by-turn clinical supervision evaluating cognitive distortions (Mind Reading, Catastrophizing, Should Statements, etc.) and effective restructuring techniques without breaking character during roleplay.
- **📊 Comprehensive Session Diagnostic Reports**: End-of-session case conceptualization reports with psychometric scoring (1-5), evidence quotes, cognitive restructuring trajectories, and one-click Markdown & JSON exports.
- **🛠️ AI Custom Scenario Architect**: Dynamic clinical scenario generator creating calibrated roleplays across `Social Anxiety`, `Workplace`, `Relationships`, and `Self-Talk` at `Beginner`, `Intermediate`, and `Advanced` difficulty levels.
- **📖 Evidence-Based CBT Reference Guide**: Searchable clinical glossary covering 12 cognitive distortions, 5 therapeutic techniques (Cognitive Reframing, Behavioral Activation, Radical Acceptance, etc.), and concepts (Spotlight Effect, Gray Rock Method).
- **⚡ Progressive Web App (PWA)**: Built with `vite-plugin-pwa` and Workbox custom service worker (`sw.ts`) for offline caching, asset precaching, and mobile standalone installation.
- **☁️ Serverless C# API Layer**: Optional headless backend implemented in Azure Functions v4 (.NET 8 Isolated Worker) powered by OpenRouter.

---

## 🏛️ System Architecture

```mermaid
graph TD
    User([User Voice / Text]) <--> Frontend[React 19 + Vite + Tailwind + Radix UI]
    
    subgraph "Frontend Real-Time Multimodal Layer"
        Frontend <--> WebAudio[WebAudio DSP Engine: Live FFT Analysis & Speech Synthesis]
        Frontend <--> OpenRouterClient[OpenRouter API: Streaming Roleplay & Structured Analysis]
        OpenRouterClient --> Transcripts[Real-Time Transcription Pipeline]
        Transcripts --> Supervisor[Parallel Turn Supervisor: OpenRouter google/gemini-3.8-flash]
        Supervisor --> LiveInsights[LiveInsightPanel & SessionReport]
    end

    subgraph "Backend Serverless Layer (api/)"
        Frontend -.->|Headless / Batch Evaluation| AzFunc[Azure Functions v4 .NET 8 Isolated Worker]
        AzFunc --> ChatFunc["/api/chat (ChatProgression)"]
        AzFunc --> AnalysisFunc["/api/analysis (ClinicalAnalysis)"]
        AzFunc --> ScenarioFunc["/api/scenario/generate (GenerateScenario)"]
        AzFunc <--> OpenRouterAPI[OpenRouter API /chat/completions]
    end

    subgraph "Local Persistence & Offline"
        Frontend <--> LocalStorage[LocalStorage: Custom Scenarios, Settings & Session History]
        Frontend <--> ServiceWorker[Vite PWA / Workbox Service Worker: sw.ts]
    end
```

---

## 🚀 Getting Started

### Prerequisites

- **Node.js**: v20+ or v22+
- **npm**: v10+
- **.NET 8.0 SDK** (optional, for backend Azure Functions)
- **OpenRouter API Key**: [Get an API Key from OpenRouter](https://openrouter.ai/keys)

### 1. Installation

```bash
git clone https://github.com/jpremill/clarity-helper.git
cd clarity-helper
npm install
```

### 2. Configure Environment Variables

Create `.env.local` in the project root (or set your key directly in the in-app Settings modal):

```env
VITE_OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_API_KEY=your_openrouter_api_key_here
```

### 3. Run Development Server

```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) in your browser.

---

## 🧠 CBT Framework & Scenarios

Cognitive Clarity includes 14 pre-calibrated clinical scenarios across 4 core domains:

| Category | Beginner | Intermediate | Advanced |
|:---|:---|:---|:---|
| **Relationships** | *The Silent Friend* (s1) | *The Friend's Criticism* (s13) | *Intrusive Relative* (s11), *The Unpaid Debt* (s7) |
| **Workplace** | — | *Critical Feedback* (s2), *The Deadline Slip* (s9) | *The Salary Discussion* (s8), *The Job Interview* (s12) |
| **Social Anxiety** | *Booking an Appointment* (s5) | *The Defective Return* (s6), *The Social 'No'* (s10) | *The Social Spotlight* (s3) |
| **Self-Talk** | *Inner Critic Echo* (s4) | — | *The Unexpected Health Symptom* (s14) |

---

## ☁️ Serverless Backend API (`api/`)

The repository includes a .NET 8 Azure Functions isolated worker backend:

```bash
# Build the .NET Functions project
dotnet build api/api.csproj
```

### Endpoints

| Route | Method | Description |
|:---|:---|:---|
| `/api/chat` | `POST` | Advances the character roleplay dialogue with strict anti-meta guardrails. |
| `/api/analysis` | `POST` | Analyzes a dialogue turn for cognitive distortions and returns structured feedback. |
| `/api/scenario/generate` | `POST` | Generates a complete, validated scenario specification using JSON schema constraints. |

---

## 🛠️ Developer Tools & Scripts

| Script | Command | Purpose |
|:---|:---|:---|
| **Run Unit Tests** | `npm test` | Executes native Node.js / `tsx` unit test suites. |
| **Typecheck** | `npm run lint` | Runs `tsc --noEmit` to verify type safety. |
| **Build SPA & PWA** | `npm run build:nobump` | Compiles Vite production bundle + Service Worker into `dist/`. |
| **Validate Scenarios** | `npm run validate:scenarios` | Validates all 14 built-in scenarios against schema and distortion rules. |
| **Simulate Session** | `npm run simulate:session` | Headless multi-turn roleplay & clinical scoring simulator harness. |

---

## 🤖 Agents & Skills

Specialized agent configurations and workflow blueprints are organized in `.agents/skills/`:

- [`.agents/skills/cbt-scenario-design/SKILL.md`](.agents/skills/cbt-scenario-design/SKILL.md): Scenario creation, difficulty calibration, and psychological persona guidelines.
- [`.agents/skills/webaudio-gemini-live/SKILL.md`](.agents/skills/webaudio-gemini-live/SKILL.md): Real-time duplex WebAudio streaming, PCM conversions, and visualizer math.
- [`.agents/skills/cbt-clinical-evaluation/SKILL.md`](.agents/skills/cbt-clinical-evaluation/SKILL.md): Clinical supervisor scoring, distortion taxonomy, and diagnostic report structures.
- [`.agents/skills/azure-functions-genai/SKILL.md`](.agents/skills/azure-functions-genai/SKILL.md): C# isolated worker API design with `Google.GenAI` 1.20+ SDK.

---

## 📄 License

MIT License. Designed with evidence-based Cognitive Behavioral Therapy principles.