ai-cto 0.1.0

package/docs/STACK.md

@@ -0,0 +1,204 @@
+# ⚡ AI CTO — Technical Architecture & Stack Document
+
+> **Goal:** Validate if choosing AI models is fun. Optimized for shipping in a single weekend with zero backend, pure deterministic logic, and rapid iteration via JSON configuration.
+
+---
+
+## 🎯 Guiding Principles
+
+- 🎲 **100% Deterministic:** Seeded RNG ensures every player faces identical daily challenges.
+- 📊 **Data-Driven Design:** Game rules, models, and requests are fully configurable via JSON schemas.
+- ⚡ **Zero Backend Architecture:** No authentication, no databases, no APIs, no network dependency.
+- 🧪 **Test-Driven Engine:** Pure TypeScript core logic decoupled completely from the UI layer.
+
+---
+
+## 🛠️ Technology Stack Overview
+
+| Domain | Technology | Rationale |
+| :--- | :--- | :--- |
+| **Framework** | React 19 + Vite + TypeScript | Blazing fast dev loop, minimal bundle size, ideal for static deployment |
+| **Styling** | Tailwind CSS + shadcn/ui | Accelerated component building with zero custom CSS except animations |
+| **State** | Zustand | Ultra-lightweight, single centralized state store |
+| **Persistence** | LocalStorage | Simple client-side persistence for game state and settings |
+| **Routing** | React Router v7 | Seamless single-page navigation |
+| **Animations** | Framer Motion | Fluid card transitions, score incrementing, and cash feedback |
+| **Icons** | Lucide React | Clean modern SVG icons |
+| **Audio** | Howler.js / HTML5 Audio | Snappy sound effects (clicks, cash register, failures) |
+| **Testing** | Vitest | Fast headless CLI unit testing for engine logic |
+| **Deployment** | Vercel / Cloudflare Pages | Instant static deployment with edge distribution |
+
+---
+
+## 🗂️ Project Directory Structure
+
+```
+aicto/
+├── src/
+│   ├── assets/           # Sound FX, custom graphics, and icons
+│   │   ├── icons/
+│   │   └── sounds/
+│   ├── components/       # Reusable UI components (shadcn/ui based)
+│   │   ├── EndScreen.tsx
+│   │   ├── Header.tsx
+│   │   ├── ModelCard.tsx
+│   │   ├── RequestCard.tsx
+│   │   └── ScoreBar.tsx
+│   ├── data/             # Static game JSON data
+│   │   ├── encyclopedia.json
+│   │   ├── models.json
+│   │   └── requests.json
+│   ├── engine/           # Pure TypeScript game simulation engine
+│   │   ├── economy.ts
+│   │   ├── evaluate.ts
+│   │   ├── rng.ts
+│   │   ├── scoring.ts
+│   │   └── seed.ts
+│   ├── hooks/            # Custom React hooks
+│   ├── pages/            # Page-level routes
+│   │   ├── Encyclopedia.tsx
+│   │   ├── Game.tsx
+│   │   ├── Home.tsx
+│   │   ├── Results.tsx
+│   │   └── Settings.tsx
+│   ├── store/            # State management
+│   │   └── game.ts
+│   ├── types/            # TypeScript interfaces & types
+│   └── utils/            # Helper functions
+└── tests/                # Engine unit tests (Vitest)
+```
+
+---
+
+## 📐 Data Contracts & JSON Schemas
+
+### 1. Request Schema (`requests.json`)
+
+```json
+{
+  "id": 12,
+  "title": "Generate SQL query for analytics dashboard",
+  "category": "coding",
+  "difficulty": "medium",
+  "latencyRequirement": 2.0,
+  "qualityRequirement": 3,
+  "reward": 18.00,
+  "penalty": -30.00
+}
+```
+
+### 2. Model Schema (`models.json`)
+
+```json
+{
+  "id": "nano",
+  "name": "Nano",
+  "cost": 0.03,
+  "latency": 0.4,
+  "quality": 2,
+  "coding": 2,
+  "reasoning": 1,
+  "vision": 0,
+  "context": 1
+}
+```
+
+---
+
+## 🧠 Game Engine Logic & Evaluation Pipeline
+
+The game engine is pure TypeScript with zero React dependencies, allowing direct CLI execution and unit testing via Vitest.
+
+```mermaid
+flowchart TD
+    Data[📄 JSON Data] --> Engine[⚡ Game Engine]
+    Req[📥 Request Requirements] --> Eval[🧪 evaluate request, model ]
+    Mod[🤖 Model Capabilities] --> Eval
+    Eval --> Outcome{Success Check}
+    Outcome -- Success --> Profit[💰 Calculate Profit & Bonus]
+    Outcome -- Failure --> Refund[📉 Deduct Penalty & Trust]
+    Profit --> Store[📦 Zustand Game Store]
+    Refund --> Store
+    Store --> UI[💻 React UI & LocalStorage]
+```
+
+### Scoring & Failure Probability Formula
+
+Success is probabilistic when model capabilities fall below required thresholds:
+
+| Quality Match Standard | Success Probability | Impact |
+| :--- | :--- | :--- |
+| **Perfect Match** (`Model >= Requirement`) | `100%` | Full Reward Granted |
+| **Close Match** (`Difference = -1`) | `80%` | Minor failure risk |
+| **Below Standard** (`Difference = -2`) | `35%` | High failure risk |
+| **Far Below** (`Difference <= -3`) | `5%` | Almost guaranteed failure penalty |
+
+---
+
+## 📐 Vector-Based Capability Architecture
+
+To support generic capability scoring without per-request hardcoding, requests and models are represented as multidimensional capability vectors:
+
+### Vector Definition
+
+```typescript
+export interface CapabilityVector {
+  quality: number;
+  reasoning: number;
+  coding: number;
+  vision: number;
+  context: number;
+  latency: number;
+}
+
+export interface Model {
+  id: string;
+  cost: number;
+  capabilities: CapabilityVector;
+}
+
+export interface RequestRequirements {
+  requirements: CapabilityVector;
+  maxLatency: number;
+  reward: number;
+  penalty: number;
+}
+```
+
+> [!TIP]
+> **Extensibility:** Using vector scoring allows introducing new capabilities (e.g. `multilingual`, `audio`, `functionCalling`) by updating vectors in `models.json` and `requests.json` without modifying core engine evaluation code.
+
+---
+
+## 🎲 Randomness & Seeded RNG
+
+To enable fair daily competitive scoring without a server:
+- `seedrandom` provides pseudo-random outcomes based on the current date string (e.g., `2026-08-01`).
+- All players face identical request orders, failure rolls, and scoring conditions on any given day.
+
+---
+
+## 📈 Minimal Client Analytics
+
+Client-side event tracking captures essential gameplay metrics without requiring a custom backend:
+
+- 🚪 **Drop-off Points:** Identify requests where players exit early.
+- ⚠️ **Bottleneck Identification:** Track requests with highest failure rates.
+- 🔄 **Replay Frequency:** Monitor immediate replay button clicks.
+- ⏱️ **Completion Time:** Average duration to complete 20 requests.
+- 📊 **Model Bias:** Distribution of Nano vs Mini vs Large selections.
+
+---
+
+## 📦 Required Libraries Summary
+
+| Category | Package | Purpose |
+| :--- | :--- | :--- |
+| **State** | `zustand` | Store global game state |
+| **Animation** | `framer-motion` | Micro-animations and page transitions |
+| **Sound** | `howler` | Fast web audio playback |
+| **RNG** | `seedrandom` | Deterministic daily random seeds |
+| **Class Helpers** | `clsx` + `tailwind-merge` | Conditional utility class merging |
+| **Icons** | `lucide-react` | Dashboard and card icons |
+| **Validation** | `zod` | JSON runtime schema validation |
+| **Testing** | `vitest` | Headless unit testing for game engine |

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "ai-cto",
+  "version": "0.1.0",
+  "description": "Run an AI startup for 5 minutes (Terminal CLI Edition)",
+  "type": "module",
+  "bin": {
+    "ai-cto": "./bin/cli.js"
+  },
+  "scripts": {
+    "play": "node ./bin/cli.js",
+    "test": "node ./scripts/playtest.js"
+  },
+  "keywords": [
+    "cli",
+    "game",
+    "ai",
+    "simulation"
+  ],
+  "license": "MIT"
+}

package/scripts/playtest.js

@@ -0,0 +1,147 @@
+import { evaluateChoice, MODELS, REQUESTS } from '../bin/cli.js'; // or import game evaluator logic
+
+// ---------------------------------------------------------
+// Playtest Simulator Engine
+// ---------------------------------------------------------
+
+function runSimulatedGame(strategyName, strategyFn) {
+  let capital = 100.00;
+  let trust = 85;
+  let totalRevenue = 0;
+  let totalCost = 0;
+  let successes = 0;
+  let failures = 0;
+  const turnLogs = [];
+
+  for (let i = 0; i < REQUESTS.length; i++) {
+    const req = REQUESTS[i];
+    const selectedModel = strategyFn(req, i);
+
+    const res = evaluateChoice(selectedModel, req);
+    capital += res.profit;
+    trust = Math.min(100, Math.max(0, trust + res.trustDelta));
+    totalCost += selectedModel.cost;
+
+    if (res.success) {
+      successes++;
+      totalRevenue += req.reward;
+    } else {
+      failures++;
+      totalRevenue += req.penalty;
+    }
+
+    turnLogs.push({
+      turn: i + 1,
+      reqId: req.id,
+      title: req.title,
+      difficulty: req.diff,
+      modelChosen: selectedModel.name,
+      success: res.success,
+      profit: res.profit,
+      trustDelta: res.trustDelta,
+      headline: res.headline
+    });
+  }
+
+  let rank = 'C Tier (Break-even)';
+  if (capital > 250 && trust >= 90) rank = 'S Tier (Unicorn Founder)';
+  else if (capital > 150) rank = 'A Tier (Profitable Startup)';
+  else if (capital > 50) rank = 'B Tier (Sustainable Ops)';
+  else if (capital < 0) rank = 'Bankrupt Founder';
+
+  return {
+    strategyName,
+    capital,
+    trust,
+    totalRevenue,
+    totalCost,
+    successes,
+    failures,
+    rank,
+    turnLogs
+  };
+}
+
+// ---------------------------------------------------------
+// Strategies
+// ---------------------------------------------------------
+
+// 1. Optimal Strategy (Nano for Low, Mini for Med, Large for High)
+const optimalStrategy = (req) => {
+  if (req.diff === 'Low') return MODELS[0];   // Nano
+  if (req.diff === 'Medium') return MODELS[1]; // Mini
+  return MODELS[2];                            // Large
+};
+
+// 2. Nano Spam Strategy (Nano for everything)
+const nanoSpamStrategy = () => MODELS[0];
+
+// 3. Large Safe Strategy (Large for everything)
+const largeSafeStrategy = () => MODELS[2];
+
+// 4. Random Strategy
+const randomStrategy = () => MODELS[Math.floor(Math.random() * MODELS.length)];
+
+// ---------------------------------------------------------
+// Run 10 Runs per Strategy & Record Anomalies
+// ---------------------------------------------------------
+console.log('================================================================');
+console.log('🧪 AI CTO — AUTOMATED SIMULATION & ANOMALY DETECTION SUITE');
+console.log('================================================================\n');
+
+const RUNS = 10;
+const strategies = [
+  { name: 'Optimal Strategy', fn: optimalStrategy },
+  { name: 'Nano Spam Strategy', fn: nanoSpamStrategy },
+  { name: 'Large Safe Strategy', fn: largeSafeStrategy },
+  { name: 'Random Choice Strategy', fn: randomStrategy }
+];
+
+const allResults = [];
+const requestFailureTracker = {};
+
+REQUESTS.forEach(r => { requestFailureTracker[r.id] = { title: r.title, diff: r.diff, failures: 0, total: 0 }; });
+
+strategies.forEach(strat => {
+  console.log(`\n--- Running 10 Playthroughs: ${strat.name} ---`);
+  const stratRuns = [];
+
+  for (let run = 1; run <= RUNS; run++) {
+    const result = runSimulatedGame(strat.name, strat.fn);
+    stratRuns.push(result);
+
+    result.turnLogs.forEach(log => {
+      requestFailureTracker[log.reqId].total++;
+      if (!log.success) requestFailureTracker[log.reqId].failures++;
+    });
+
+    console.log(` Run #${run.toString().padStart(2)}: Capital = $${result.capital.toFixed(2).padStart(7)} | Trust = ${result.trust.toString().padStart(3)}% | Score = ${result.successes}/20 Successes | Rank = ${result.rank}`);
+  }
+
+  const avgCapital = stratRuns.reduce((acc, r) => acc + r.capital, 0) / RUNS;
+  const avgTrust = stratRuns.reduce((acc, r) => acc + r.trust, 0) / RUNS;
+  const avgSuccess = stratRuns.reduce((acc, r) => acc + r.successes, 0) / RUNS;
+
+  console.log(` 📊 SUMMARY (${strat.name}): Avg Profit = $${avgCapital.toFixed(2)} | Avg Trust = ${avgTrust.toFixed(1)}% | Avg Wins = ${avgSuccess.toFixed(1)}/20`);
+  allResults.push({ strat: strat.name, avgCapital, avgTrust, avgSuccess, stratRuns });
+});
+
+// ---------------------------------------------------------
+// Anomaly Analysis
+// ---------------------------------------------------------
+console.log('\n================================================================');
+console.log('🔍 ANOMALY DETECTION REPORT');
+console.log('================================================================\n');
+
+console.log('1. High Failure Rate Bottlenecks (> 50% Failure across all runs):');
+Object.values(requestFailureTracker).forEach(item => {
+  const failRate = (item.failures / item.total) * 100;
+  if (failRate > 40) {
+    console.log(` ⚠️ [Req #${item.title}] Difficulty: ${item.diff} | Failure Rate: ${failRate.toFixed(1)}% (${item.failures}/${item.total} runs failed)`);
+  }
+});
+
+console.log('\n2. Strategy ROI & Dominance Check:');
+allResults.forEach(res => {
+  console.log(` - ${res.strat.padEnd(25)}: Avg Final Capital = $${res.avgCapital.toFixed(2)} (${res.avgCapital > 0 ? 'PROFITABLE' : 'UNPROFITABLE'})`);
+});