Skip to content

Latest commit

Β 

History

History
309 lines (211 loc) Β· 17.5 KB

PROJECT_DETAILS.md

File metadata and controls

309 lines (211 loc) Β· 17.5 KB

πŸš€ TokenSlash: Project Specification & Architectural Blueprint

---

πŸ“Œ 1. Project Title & Metadata

  • Official Project Title: TokenSlash: Multimodal Edge-AI Gateway & Autonomous Token-Optimization Engine
  • Short Tagline: Cut AI token costs by up to 60%, eliminate prompt fluff with multimodal phone sensors, and autonomously route to the most cost-effective AI model with real-time execution.
  • Category / Track: Developer Tools (Secondary: Open Innovation / Productivity)
  • Target Platforms: iQOO Flagship Mobile Devices (Android), Desktop Workstations (Windows/macOS/Linux), Web Browsers, Cursor IDE, Claude Desktop, and MCP-compatible AI Clients.
  • Target Audience: Software Developers, AI Engineers, Enterprise Dev Teams, Startups, and Prompt Engineers looking to optimize LLM cost, latency, and context-window efficiency.

---

πŸ›‘ 2. Problem Statement

As generative AI becomes deeply embedded into software engineering, customer support, and autonomous agents, organizations face three severe bottlenecks:

  1. Massive Token Inflation & Conversational Fluff:

    • Prompts entered via natural conversation, voice dictation, or raw error logs contain 40% to 60% redundant tokens (e.g., pleasantries, filler words, repetitive context, boilerplate logs, and UI noise).
    • In multimodal inputs (e.g., screenshots of code, whiteboard diagrams, terminal dumps), passing raw base64 images to vision models consumes 1,500 to 3,000+ tokens per query, resulting in exponential API billing for information that could be represented in 150 structured tokens.
  2. Sub-Optimal Model Over-Provisioning:

    • Developers frequently send low-complexity tasks (regex generation, JSON parsing, basic syntax conversion, unit test scaffolds) to expensive flagship frontier models (e.g., Claude 3.5 Sonnet, GPT-4o) costing $15–$30 per million tokens.
    • Without real-time automated complexity analysis, teams lack dynamic routing to use lightweight models (Gemini 1.5 Flash, GPT-4o mini) or local edge models ($0.00 cost) for simpler tasks.
  3. Friction Between Mobile Capture and Desktop Development:

    • Real-world development issues frequently originate outside the desktop editorβ€”on physical whiteboards, external test screens, or through verbal team brainstorming.
    • Developers must manually type out or re-format errors on their desktop machines, breaking flow state and introducing transcription overhead.

---

πŸ’‘ 3. Proposed Solution

TokenSlash is a phone-first, multimodal AI middleware and Model Context Protocol (MCP) gateway that intercepts, analyzes, cleans, compresses, and routes developer queries to the optimal AI model before execution.

TokenSlash transforms raw multimodal inputs (camera snapshots and voice dictation on the iQOO phone) into zero-fluff, high-density structured prompts, evaluates complexity using a 77-feature syntactic classifier, predicts performance trade-offs across AI models using a 4-model Machine Learning ensemble (PromptIQ), and autonomously executes the request across connected AI providers (OpenAI, Anthropic, Google Gemini, DeepSeek, Perplexity, or Local SLMs).

The final response and optimized code artifacts are streamed live to the iQOO mobile interface and instantly synchronized to desktop developer environments (Cursor / VS Code) via the iQOO Office Kit Cross-Device Bridge.

---

⭐ 4. Key Features & Unique Selling Points (USP)

1. πŸ“Έ "Snap-to-Slash" (Multimodal Visual Bug & Whiteboard Tokenizer)

  • What it does: Uses the iQOO Camera to capture terminal stack traces, monitor bugs, and whiteboard architecture diagrams.
  • The USP: Rather than transmitting heavy raw images to expensive cloud vision models (costing thousands of tokens), an on-device OCR and AST filtering parser extracts only the actionable error traces and code structures, compressing the input into a 120-token structured prompt (up to 90% token reduction).

2. πŸŽ™οΈ "Voice-to-DSL" (Zero-Fluff Speech Compactor)

  • What it does: Captures spontaneous developer thoughts and voice dictation via the iQOO microphone.
  • The USP: Uses the Web Speech API / audio streaming combined with syntactic filtering algorithms to strip conversational stutter, hesitation, and filler words, structuring the spoken request into high-compliance XML tags (<context>, <instructions>, <output\_format>).

3. 🧠 PromptIQ 4-Model ML Routing Ensemble

  • What it does: A machine learning intelligence core that evaluates prompt complexity against a unified dataset of model capabilities and live pricing.

  • The Ensemble:

    • Model 1 (Satisfaction Predictor): Predicts user satisfaction per candidate model.
    • Model 2 (Retry Risk Estimator): Estimates the probability that a model fails or requires a follow-up retry.
    • Model 3 (Latency Forecaster): Predicts end-to-end token generation time.
    • Model 4 (Pareto Utility Optimizer): Solves the cost-vs-quality trade-off curve to select the optimal model.

4. πŸ¦™ "Tier-0 Edge-SLM Bypass" (Local / On-Device AI Execution)

  • What it does: For tasks with a Complexity Score < 25/100 (e.g., regex, SQL formatting, git commands, JSON fixes), TokenSlash routes execution to a Local/Edge Small Language Model (e.g., Llama-3.2, Gemma-2B, or local Ollama).
  • The USP: Delivers 0ms network latency, 100% offline privacy, and β‚Ή0 / $0 token cost.

5. πŸ€– Multi-Provider Autonomous Execution Gateway

  • What it does: Not only recommends the best model, but directly dispatches the prompt to the winning provider (OpenAI GPT-4o / 4o-mini, Anthropic Claude 3.5 Sonnet, Google Gemini 1.5 Flash/Pro, DeepSeek V3, Perplexity Sonar) and streams the live answer directly on the phone.

6. ⚑ iQOO Office Kit Cross-Device Dev-Warp

  • What it does: Seamlessly connects the mobile experience with the desktop editor.
  • The USP: Prompts optimized on the iQOO phone during mobile brainstorming or "Red Light" phases are beamed via Office Kit Shared Clipboard and File Sync directly into the desktop IDE (Cursor, VS Code, Terminal) with a single tap.

7. πŸ“Š Green-AI & Real-Time Token-Burn HUD

  • What it does: Live analytics displaying token reduction rates (40–60%), monetary savings (β‚Ή / $), latency SLA improvements, and estimated carbon emissions (COβ‚‚ grams) saved per session.

---

πŸ› οΈ 5. Technology Stack & Tools Used

A. Existing Project Architecture & Core Engine

Component Technologies & Libraries Purpose
Backend Framework Node.js, TypeScript, Express Core API server & pipeline orchestration
Protocol Engine NitroStack SDK (@nitrostack/mcp-core), Model Context Protocol (MCP) JSON-RPC 2.0 & SSE MCP tool interfaces
Token Estimation js-tiktoken (cl100k\_base BPE tokenizer) Sub-millisecond exact BPE token calculation
Machine Learning Core Python 3.11+, Scikit-learn, Pandas, NumPy, Parquet PromptIQ 4-Model Ensemble training & inference
Datasets & Benchmarks Unified TokenSlash Dataset, LMSYS Chatbot Arena, HuggingFace data Training satisfaction, latency, and retry models
Frontend Dashboard React 18, Vite, Tailwind CSS, Lucide Icons Responsive web UI, live diff viewer, analytics
Testing & Quality Vitest, TypeScript compiler, custom PowerShell e2e test suites Automated unit testing & regression suites

B. Additions for the Updated Phone-First Project

Component Technologies & Integration Purpose
Mobile Hardware Ingestion HTML5 MediaDevices / Camera API, Web Speech API (webkitSpeechRecognition) On-device camera and microphone capture
Cross-Device Bridge iQOO Office Kit (Shared Clipboard Protocol, File Sync, Screen Mirroring) Seamless Phone-to-Desktop data transfer
Multi-Provider AI Gateway OpenAI API SDK, Anthropic SDK, Google GenAI SDK, OpenRouter / DeepSeek API Direct multi-model prompt dispatch & streaming
Edge / Local AI Ollama, Llama-3.2-1B, Gemma-2B / ONNX Runtime Web Tier-0 local prompt execution ($0 cost / 0ms)

---

πŸ”Œ 6. Why We Used MCP (Model Context Protocol)

The Model Context Protocol (MCP) is an open industry standard that connects AI assistants to external tools, data sources, and services.

Why TokenSlash uses MCP:

  1. Zero-Code Client Integration: Any MCP-compatible tool (Cursor IDE, Claude Desktop, NitroChat, or custom LLM agents) can natively discover and call TokenSlash tools without needing custom API integration.

  2. Standardized Tool Exposure: Exposes 7 modular tools:

    • analyze\_prompt: Complete end-to-end token, complexity, and model analysis.
    • rewrite\_prompt: Algorithmic fluff removal and XML structure refactoring.
    • recommend\_model: ML ensemble inference for optimal model selection.
    • estimate\_tokens: Exact BPE token metrics.
    • classify\_complexity: 77-feature syntactic complexity scoring.
    • synthesize\_report: Executive-level ROI and monthly volume cost projections.
    • analyze\_history: Multi-session developer profiling for domain customization.
  3. Multi-Transport Flexibility: Supports both Server-Sent Events (/sse) for real-time streaming and Streamable HTTP (/mcp) for high-throughput cloud requests.

---

πŸ€– 7. How TokenSlash Connects to External AIs & Delivers Direct Output

User Input (Voice/Camera/Text) 
   ──▢ TokenSlash Ingestion \& Fluff Stripper
   ──▢ 77-Feature Complexity Evaluation
   ──▢ PromptIQ ML Decision (Optimal Model Selected)
   ──▢ Dynamic Multi-Provider Dispatch Layer
          β”œβ”€β”€ Option 1: Local SLM (Ollama / ONNX) \[Complexity < 25]
          β”œβ”€β”€ Option 2: Google Gemini API (gemini-1.5-flash)
          β”œβ”€β”€ Option 3: Anthropic API (claude-3-5-sonnet)
          β”œβ”€β”€ Option 4: OpenAI API (gpt-4o / gpt-4o-mini)
          β”œβ”€β”€ Option 5: DeepSeek API (deepseek-chat)
          └── Option 6: Perplexity API (sonar-pro)
   ──▢ Live Stream Response to iQOO Phone
   ──▢ Auto-Beam via Office Kit to Laptop Cursor / VS Code
  1. User Authentication & Permission: The user enables "Auto-Execute Best Model" and provides provider API keys (or uses an integrated unified gateway like OpenRouter / NitroCloud proxy).
  2. Autonomous Model Selection: The PromptIQ ML ensemble evaluates the prompt's structural needs. If the query requires deep multi-step coding, it chooses Claude 3.5 Sonnet or DeepSeek V3; if it is a general knowledge question, it selects Gemini 1.5 Flash; if it is a simple syntax fix, it routes to Local SLM.
  3. Execution & Streaming: The backend dispatches the optimized XML prompt directly to the selected provider's API over SSE.
  4. Output Rendering: The token-slashed response is rendered in real time on the iQOO phone and instantly synced to the laptop clipboard via Office Kit.

---

πŸ›οΈ 8. Complete System Architecture

flowchart TD
    %% LAYER 1: CLIENT \& INGESTION
    subgraph L1\["πŸ“± LAYER 1: HARDWARE \& CLIENT INGESTION (iQOO Phone)"]
        A1\["πŸ“Έ Snap-to-Slash (Camera / OCR)\\nTerminal Errors \& Whiteboards"]
        A2\["πŸŽ™οΈ Voice-to-DSL (Microphone)\\nSpoken Speech-to-Text Input"]
        A3\["πŸ’» Web \& Mobile Dashboard (React / Vite)\\nInteractive Input \& Telemetry HUD"]
        A4\["πŸ”Œ External MCP Clients\\nCursor IDE / Claude Desktop / NitroChat"]
    end

    %% LAYER 2: OFFICE KIT BRIDGE
    subgraph L2\["⚑ LAYER 2: iQOO OFFICE KIT CROSS-DEVICE BRIDGE"]
        B1\["πŸ“‹ Shared Clipboard Sync"]
        B2\["πŸ“ File \& AST Transfer"]
        B3\["πŸ–₯️ Screen Mirroring \& Dev-Warp\\n(Phone ↔ Laptop IDE / Terminal)"]
    end

    %% LAYER 3: OPTIMIZATION PIPELINE
    subgraph L3\["βš™οΈ LAYER 3: PRE-PROCESSING \& OPTIMIZATION PIPELINE"]
        C1\["πŸ“ BPE Token Estimator\\n(js-tiktoken cl100k\_base)"]
        C2\["πŸ” 77-Feature Syntactic Classifier\\n(AST depth, vocabulary, code markers)"]
        C3\["🧹 Zero-Fluff Stripper\\n(Removes pleasantries, stutter, noise)"]
        C4\["🏷️ XML Prompt Reformulator\\n(<context>, <instructions>, <output\_format>)"]
    end

    %% LAYER 4: PROMPTIQ ML ENSEMBLE
    subgraph L4\["🧠 LAYER 4: PROMPTIQ ML ROUTING ENSEMBLE"]
        D1\["Model 1: Satisfaction Predictor (pkl)"]
        D2\["Model 2: Retry Risk Estimator (pkl)"]
        D3\["Model 3: Latency Forecaster (pkl)"]
        D4\["Model 4: Cost \& Pareto Utility Optimizer"]
    end

    %% LAYER 5: EXECUTION GATEWAY
    subgraph L5\["πŸ€– LAYER 5: MULTI-PROVIDER EXECUTION GATEWAY"]
        E1\["πŸ¦™ Tier 0: Local / Edge SLM (Llama-3.2 / Gemma / ONNX)\\n\[Score < 25 | $0.00 Cost | 0ms Network]"]
        E2\["⚑ Tier 1: Fast \& Cost-Efficient\\n(Google Gemini 1.5 Flash / GPT-4o mini)"]
        E3\["🧠 Tier 2: Deep Reasoning \& Coding\\n(Anthropic Claude 3.5 Sonnet / DeepSeek V3)"]
        E4\["🌐 Tier 3: Search-Augmented\\n(Perplexity / Sonar)"]
    end

    %% LAYER 6: TELEMETRY \& MCP PROTOCOL
    subgraph L6\["πŸ“Š LAYER 6: TELEMETRY, AUDIT \& MCP PROTOCOL"]
        F1\["πŸ”Œ MCP Server (JSON-RPC 2.0 / SSE / Streamable HTTP)"]
        F2\["πŸ“ˆ Green-AI \& Carbon/Cost Telemetry HUD"]
        F3\["πŸ“ Audit Trace \& Session Profiler"]
    end

    %% Flow Connections
    A1 \& A2 \& A3 --> L3
    A4 --> F1
    F1 --> L3
    
    L3 --> L4
    L4 --> L5

    L5 --> F2 \& F3
    F2 \& F3 --> A3
    L5 -->|Live Response \& Snippets| L2
    L2 -->|Auto-Paste / Insert| A4
Loading

---

πŸ”„ 9. End-to-End Workflow: The Life of a Query

  1. Capture & Ingestion:

    • The developer snaps an error screenshot using Snap-to-Slash on the iQOO phone or speaks a feature requirement using Voice-to-DSL.
  2. Syntactic De-noising & Fluff Removal:

    • TokenSlash strips conversational fluff, pleasantries, terminal timestamps, and UI boilerplate.
  3. Token Estimation & Complexity Classification:

    • js-tiktoken computes original vs. projected BPE token count.
    • The 77-feature syntactic analyzer calculates a complexity score (0–100).
  4. Prompt Restructuring:

    • Input is refactored into structured XML tags (<context>, <instructions>, <output\_format>).
  5. PromptIQ ML Ensemble Inference:

    • The ML ensemble predicts satisfaction score, retry risk, and latency across available models.
    • The Pareto optimizer selects the winning model based on required accuracy vs. minimal cost.
  6. Execution & Direct Output:

    • If complexity < 25: Executed on Local Edge SLM ($0 cost).
    • If complexity β‰₯ 25: Executed via selected Cloud API (Gemini / Claude / GPT / DeepSeek).
  7. Telemetry & Cross-Device Sync:

    • Live response streams to the phone HUD showing tokens saved, cost reduced, and carbon prevented.
    • Office Kit beams the response/code snippet straight to the desktop IDE.

---

πŸ“ˆ 10. Real-World Impacts & Benefits

1. πŸ’° Financial & Economic ROI

  • 40% to 60% Token Reduction: Saves thousands of dollars per month for startups and enterprises running automated AI agent workflows.
  • Over-Provisioning Elimination: Replaces unnecessary $20/M token frontier model calls with $0.15/M token flash models or $0.00 local models for routine queries.

2. ⚑ Performance & Latency Acceleration

  • Up to 2.5x Faster Turnaround: Lighter models and compressed prompts significantly reduce Time-to-First-Token (TTFT) and total generation time.
  • Preserved Context Windows: Keeps prompt payloads lean, allowing more history and context to fit inside multi-turn agent conversations without hitting context limits.

3. 🌱 Green-AI & Environmental Impact

  • Decreasing unnecessary compute cycles across massive cloud data centers directly cuts electrical kilowatt-hours and reduces the carbon footprint per prompt.

4. πŸš€ Cross-Device Developer Flow

  • Seamlessly bridges real-world visual/audio brainstorming on the iQOO phone with active coding on the desktop workstation using Office Kit.

---

πŸ‘₯ 11. Team Execution & 30-Hour Hackathon Roles

  • πŸ‘¨β€πŸ’» Member 1 (AI & ML Pipeline):

    • PromptIQ ML ensemble inference, complexity classifier feature extractor, Local SLM / Ollama routing, and provider API connectors.
  • πŸ‘¨β€πŸ’» Member 2 (Frontend & Mobile Experience):

    • React mobile dashboard, HTML5 Camera "Snap-to-Slash" OCR integration, Web Speech API "Voice-to-DSL", and Green-AI telemetry widgets.
  • πŸ‘¨β€πŸ’» Member 3 (Architecture, Office Kit & Demo Pitch):

    • Office Kit cross-device clipboard/file synchronization, MCP server integration into Cursor IDE, live demo script, and 3-minute jury presentation.

---

🏁 12. 3-Minute Live Pitch Script Structure for the Jury

  • 0:00 – 0:30 (The Hook & Problem):

*"Every day, developers waste 50% of their AI token budgets on conversational fluff, bloated code screenshots, and sending simple tasks to expensive models. We built TokenSlash to fix this."*

  • 0:30 – 1:30 (Live Hardware Demo on iQOO Phone):

*"Watch this live: I snap a photo of a broken stack trace on my iQOO phone with Snap-to-Slash. TokenSlash strips 85% of the visual log noise, calculates BPE tokens, and classifies complexity."*

  • 1:30 – 2:15 (ML Routing & Live Output):

*"Our PromptIQ ML Ensemble selects the fastest, cheapest model, executes the request autonomously, and streams the live code fix right here."*

  • 2:15 – 2:45 (Office Kit Magic):

*"With 1 tap via Office Kit, the fix is beamed straight into my desktop Cursor editor without touching the keyboard."*

  • 2:45 – 3:00 (Impact & Closing):

*"45% fewer tokens, 60% lower cost, β‚Ή0 local fallback, and cross-device speed. TokenSlash is the intelligent gateway for the next generation of AI development."*