clarity-helper/README.md

🧠 Cognitive Clarity

An Adaptive Clinical Training & Multimodal Roleplay Environment for Cognitive Behavioral Therapy (CBT)

Key Features • Architecture • Getting Started • CBT Scenarios • Serverless Backend • Developer Tools • Agents & Skills

---

🌟 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

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

1. Installation

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):

VITE_OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_API_KEY=your_openrouter_api_key_here

3. Run Development Server

npm run dev

Open 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:

# 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: Scenario creation, difficulty calibration, and psychological persona guidelines.
• .agents/skills/webaudio-gemini-live/SKILL.md: Real-time duplex WebAudio streaming, PCM conversions, and visualizer math.
• .agents/skills/cbt-clinical-evaluation/SKILL.md: Clinical supervisor scoring, distortion taxonomy, and diagnostic report structures.
• .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.