⚡ Hyperparameter Playground — Professional Portfolio Edition

Hyperparameter Playground is an interactive, premium GenAI learning laboratory and visual sandbox designed to teach AI engineers and developers how LLM generation parameters (temperature, top-p, top-k, penalties, stop sequences, max tokens, and seeds) control model outputs.

Built with Next.js (App Router), TypeScript, Tailwind CSS, shadcn-inspired custom UI components, and Recharts, this application features standard mathematical calculators, structured JSON schema validators, parallel multi-model "Tournament" dispatchers, and detailed client-side evaluation analytics.

---

🎨 Visual Preview & Gallery

![Playground Interface](./public/playground_mockup.png)
<!-- slide -->
![Softmax Lab Charts](./public/softmax_lab_mockup.png)
<!-- slide -->
![Linguistic Analytics Panel](./public/analytics_mockup.png)

---

🏗️ System Architecture & Data Flow

This diagram illustrates the comprehensive client-side data flow: from user prompt input, structured schema compilation, parallel REST proxy dispatching, through linguistic math evaluators, and local persistence.

flowchart TD
    subgraph UI ["Client Presentation Layer"]
        A[Playground Console /]
        B[Softmax Lab /softmax-lab]
        C[Sampling Lab /sampling-lab]
        D[Multi-Model Tournament /compare]
        E[Analytics Dashboard /analytics]
    end

    subgraph Config ["Structured output compiler (Phase 6)"]
        F[Prompt Injection Wrapper]
        G[JSON Schema Definitions]
    end

    subgraph Proxy ["Universal Routing Handler"]
        H[API completions Router app/api/generate]
        I[Mock Local Simulator]
        J[Google Gemini API]
        K[OpenAI API]
        L[Ollama Local API]
    end

    subgraph Logic ["Linguistic Evaluator Math (Phase 5)"]
        M[N-Gram Repetition math]
        N[Lexical Diversity TTR]
        O[Automated Readability Index]
        P[JSON Schema Validator]
    end

    subgraph Storage ["Browser storage Persistence"]
        Q[LocalStorage DB lib/storage.ts]
    end

    %% Flow connections
    A -->|1. Type Prompt| F
    G -->|2. Inject JSON Directives| F
    F -->|3. POST payload| H
    D -->|Concurrent Requests| H
    
    H -->|Route API Key| I
    H -->|Route API Key| J
    H -->|Route API Key| K
    H -->|Route API Key| L

    I -->|4. Raw Text Response| M
    J -->|4. Raw Text Response| M
    K -->|4. Raw Text Response| M
    L -->|4. Raw Text Response| M

    M -->|Repetition Score| Q
    N -->|Diversity Score| Q
    O -->|ARI Grade Level| Q
    P -->|Schema Compliance ticks| Q

    Q -->|Load History Graphs| E
    Q -->|Display Tabs| A

Loading

---

⚡ Portfolio Features (Phases 1–8 Completed)

1. Parameters Playground (Phases 1–3): Tune Temperature, Top-P (Nucleus), Frequency Penalties, Presence Penalties, Random Seeds, and Stop Sequences. Analyze outputs, token logs, latencies, and costs in real-time.
2. Linguistic Quality Evaluator (Phase 5): Client-side mathematical analysis of completed texts:
   • Lexical Diversity: Vocabulary Type-Token Ratio richness.
   • Repetition Rate: Consecutive 2-gram/3-gram looping frequency.
   • Automated Readability Index: Computes sentence length and syllable grade boundaries.
3. Structured JSON Output Validator (Phase 6): Toggles for forcing JSON format, predefined schemas (Product Review, User Profile, Entity Classifier), or custom CSV variables, providing a properties grid and compliance rate metrics.
4. Parallel Multi-Model Tournament (Phase 7): Concurrent async generation panel where a single prompt is dispatched to OpenAI, Gemini, and Mock systems at once, displaying responses in real-time side-by-side.
5. Interactive Softmax & Sampling Labs (Phases 2 & 4):
   • Softmax Lab: Adjust Temperature and watch Recharts curves dynamically uniform or narrow.
   • Sampling Lab: Stepper diagram (Logits → Softmax → Temperature → Top-K → Top-P → Sample Token) showing boundary cutoffs.
6. Analytics Console (Phase 5): High-fidelity dashboards tracking aggregate costs, model latency speeds over Recharts, and historic run logs.

---

🚀 Quick Setup & Usage

1. Clone & Install

# Install dependencies
npm install

2. Configure Environment

Copy .env.example to .env.local and add your API keys to call live models. Alternatively, leave blank to use the Mock Local Simulator free of charge!

# Add keys to .env.local
GEMINI_API_KEY="your-gemini-key"
OPENAI_API_KEY="your-openai-key"

3. Start Dev Server

npm run dev

Open http://localhost:3000 in your browser.

---

🏗️ Folder Map

• app/: Pages Router for parameter sandbox, side-by-side comparers, analytics dashboard, and lab sandboxes.
• components/: Dynamic custom modular panels (sliders, Recharts diagrams, schema configs, output metrics).
• lib/: Math helpers (Softmax T->0 Argmax bounds, Token Sampler, Linguistic Evaluator), exporters (JSON/CSV/MD triggers), and REST adapters.
• docs/: Systems documentation:
  • PRD & Requirements
  • Systems Design & ADRs
  • Interview-ready Learning Guide
  • Foundation series roadmap

---

💼 AI Engineer Interview Cheat Sheet (Novice-Friendly)

• Temperature ($T$): Divides logits before Softmax. Dividing by $T \to 0$ expands gaps (Argmax, deterministic code/facts). Dividing by $T > 1$ flattens gaps (Creativity, brainstorming).
• Top-K: Keeps strictly the top $K$ ranked tokens, blocking the rest regardless of their actual probability values.
• Top-P (Nucleus): Keeps the smallest set of sorted tokens whose cumulative sum reaches $P$, expanding/shrinking the vocabulary dynamically.
• Frequency Penalty: Penalizes words linearly with how many times they have already appeared in the completion (prevents localized loops).
• Presence Penalty: Penalizes words with a flat, static tax if they have appeared once (encourages topic exploration).

---

Created under the Solutions Architect portfolio framework.