Update .ipynb_checkpoints/simpletool-game.skill-checkpoint.md

.ipynb_checkpoints/simpletool-game.skill-checkpoint.md

@@ -0,0 +1,318 @@
+# SimpleTool Skill — Real-Time AI Application Development
+
+> **This is a skill file.** Feed it to any AI coding assistant (Claude, Gemini, GPT, Cursor, etc.) as context, then describe the app you want. The AI will generate a working SimpleTool-powered application.
+>
+> Example prompt: *"Read the attached SimpleTool skill, then build me a Pong game where AI controls one paddle in real-time."*
+
+---
+
+## 1. What is SimpleTool?
+
+SimpleTool is a **multi-head parallel decoding** server for real-time LLM function calling. It runs on vLLM and decodes function name + arguments simultaneously instead of sequentially.
+
+```
+Traditional:  function → arg1 → arg2 → ...  (sequential, ~200-500ms)
+SimpleTool:   [function, arg1, arg2, ...]    (parallel,   ~25-60ms)
+```
+
+**Application domains**: game AI, robotic arm control, digital human animation, IoT automation — anything that needs < 100ms LLM decision-making.
+
+## 2. Server API
+
+Server default: `http://localhost:8899`
+
+### Endpoints
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check, returns `{status, version, model}` |
+| POST | `/v1/function_call` | Multi-head parallel function call |
+
+### Request Format (v2)
+```javascript
+{
+  messages: [{role: 'user', content: 'your query'}],
+  tools: [...],                // OpenAI-format tool definitions
+  system: "domain prompt",     // Domain-specific system prompt (v2)
+  environment: [...],          // Current state info (string array, optional)
+  history: [...],              // Action history (string array, max 6)
+  include_content_head: false  // Whether to generate <content> head
+}
+```
+
+The `system` field lets you inject a domain-specific system prompt (e.g., "You are a robotic arm controller"). If omitted, the server uses a generic default. The `environment` field is optional context folded into the user message.
+
+### Response Format
+```javascript
+{
+  success: true,
+  function: "move",
+  args: {direction: "up", speed: "fast"},   // Named args (param names from tool def)
+  heads: {                                   // Raw per-head output
+    function: "move",
+    arg1: "up",
+    arg2: "fast",
+    arg3: "<|null|>"
+  },
+  content: null,       // Only if include_content_head was true
+  latency_ms: 35.2
+}
+```
+
+## 3. Dynamic Head Count (Critical for Latency!)
+
+**The server automatically prunes unused heads.** If your tools have at most 2 parameters, only 3 heads are spawned (`<function>`, `<arg1>`, `<arg2>`), not 8. This saves ~40% latency.
+
+```
+Active heads = [<function>] + [<arg1>...<argN>]
+where N = max parameter count across all tool definitions
+```
+
+**Design tip**: Keep your tools to 1–3 parameters when possible. Fewer params = fewer heads = lower latency.
+
+## 4. Tool Definition
+
+### Constraints
+- Maximum **6 arguments** per function (arg1–arg6)
+- Arguments map to `arg1, arg2, ...` in the order defined in `properties`
+- Server auto-converts types: numeric strings → int/float, otherwise lowercase string
+- Use `enum` to constrain options — this dramatically improves accuracy
+
+### Template
+```javascript
+const TOOLS = [{
+  type: "function",
+  function: {
+    name: "action_name",
+    description: "Clear, concise — what this action does and when to use it",
+    parameters: {
+      type: "object",
+      properties: {
+        param1: {
+          type: "string",
+          enum: ["opt_a", "opt_b", "opt_c"],  // Constrain! Improves accuracy
+          description: "What this param controls"
+        },
+        param2: {
+          type: "number",
+          description: "Numeric value with unit, e.g. 'Force in Newtons'"
+        }
+      },
+      required: ["param1"]
+    }
+  }
+}];
+```
+
+### Multi-Tool Example (Game)
+```javascript
+const TOOLS = [
+  {type:"function", function:{name:"move",    description:"Move unit to position", parameters:{type:"object", properties:{unit:{type:"string"}, target:{type:"string", enum:["north","south","east","west"]}}}}},
+  {type:"function", function:{name:"attack",  description:"Attack enemy",          parameters:{type:"object", properties:{unit:{type:"string"}, target:{type:"string"}}}}},
+  {type:"function", function:{name:"retreat",  description:"Pull back unit",        parameters:{type:"object", properties:{unit:{type:"string"}}}}},
+  {type:"function", function:{name:"pass",     description:"Do nothing this turn",  parameters:{type:"object", properties:{}}}}
+];
+// Max params = 2 → only 3 heads spawned
+```
+
+## 5. Query Design
+
+### Principles
+1. **Be imperative** — tell the model what to decide, not just describe state
+2. **Include decision context** — "Ball is BELOW paddle, intercept it" not "Ball y=250"
+3. **List valid options** — "Choose: up/down/stay"
+4. **Keep it short** — shorter query = faster prefill
+
+### Good vs Bad
+```
+✅ "Ball 50px BELOW paddle, approaching fast. Move DOWN to intercept. Choose: up/down/stay"
+❌ "Ball position: 250, Paddle position: 200. What should I do?"
+
+✅ "Red gear at (300,150,50). Move arm there slowly for pickup."
+❌ "There is a gear somewhere on the table. The arm needs to go to it."
+
+✅ "Stream starting, viewers saying hello. Greet them warmly."
+❌ "Viewers are in the chat. Do something appropriate."
+```
+
+### Environment & History
+```javascript
+// Environment: current state as key=value strings
+const env = [
+  `ball_y=${ballY}`,
+  `paddle_y=${paddleY}`,
+  `gap=${gap}`,
+  `approaching=true`
+];
+
+// History: recent actions (max 6, server trims automatically)
+const history = [
+  "move(up)", "move(up)", "stay()"
+];
+```
+
+### Domain System Prompts (v2)
+For v2 server, set a domain-specific system prompt:
+```javascript
+// Game AI
+const SYSTEM = "You are the AI controller for a Pong game. Move the paddle to intercept the ball. React quickly.";
+
+// Robotic arm
+const SYSTEM = "You are the voice controller for a 6-axis robotic arm. Convert commands to precise function calls. Coordinates in mm.";
+
+// Digital human
+const SYSTEM = "You are the animation controller for a virtual streamer. Convert director instructions to expression and speech calls.";
+```
+
+## 6. Frontend Code Standards
+
+### Required: Type-Safe Value Extraction
+```javascript
+// Values in args may be int, not string — always coerce
+function safeStr(v) {
+  if (v === null || v === undefined) return '';
+  return String(v).trim().toLowerCase();
+}
+
+// Extract with args (named) first, heads (positional) as fallback
+let direction = safeStr(d.args?.direction) || safeStr(d.heads?.arg1);
+```
+
+### Required: Validate Return Values
+```javascript
+const VALID = ['up', 'down', 'stay'];
+if (!VALID.includes(direction)) {
+  console.warn(`Invalid: "${direction}", fallback to stay`);
+  direction = 'stay';
+}
+```
+
+### Required: Error Handling with Fallback
+```javascript
+async function callAI() {
+  try {
+    const r = await fetch(SERVER_URL + '/v1/function_call', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify(request)
+    });
+    const data = await r.json();
+    if (!data.success) throw new Error(data.error);
+    applyAction(data);
+  } catch (e) {
+    console.error('[AI] Failed:', e);
+    applyFallbackAI();  // MUST have fallback — never freeze the app
+  }
+}
+```
+
+### Required: Logging
+```javascript
+console.log(`[Game] Query: ${query}`);
+console.log(`[Game] → ${data.function}(${JSON.stringify(data.args)}) ${data.latency_ms.toFixed(0)}ms`);
+```
+
+### Recommended: Debug UI Overlay
+Show in a corner of your app: current query, raw response, latency (current + rolling average).
+
+## 7. Game Loop Pattern
+
+**Decouple AI from rendering.** The AI loop runs at 10–16 Hz; the render loop runs at 60 fps.
+
+```javascript
+const AI_INTERVAL = 100;  // 100ms = 10 Hz
+let aiPending = false;
+
+// Render loop (60fps) — never blocks on AI
+function gameLoop() {
+  update();
+  render();
+  requestAnimationFrame(gameLoop);
+}
+
+// AI loop (async, non-blocking)
+async function aiLoop() {
+  if (aiPending) return;
+  aiPending = true;
+  await callAI();
+  aiPending = false;
+}
+
+setInterval(aiLoop, AI_INTERVAL);
+gameLoop();
+```
+
+## 8. FCClient Template
+
+Drop-in client class for any HTML/JS application:
+
+```javascript
+class FCClient {
+  constructor(url = 'http://localhost:8899') {
+    this.url = url.replace(/\/$/, '');
+  }
+
+  async health() {
+    try {
+      const r = await fetch(`${this.url}/health`, {signal: AbortSignal.timeout(3000)});
+      const d = await r.json();
+      return {ok: d.loaded === true || d.status === 'ok', version: d.version};
+    } catch (e) {
+      return {ok: false};
+    }
+  }
+
+  async call({query, tools, system, env, history, includeContent = false}) {
+    const t0 = performance.now();
+    try {
+      const r = await fetch(`${this.url}/v1/function_call`, {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({
+          messages: [{role: 'user', content: query}],
+          tools,
+          system,                              // v2: domain system prompt
+          environment: env,
+          history,
+          include_content_head: includeContent
+        })
+      });
+      const d = await r.json();
+      return {...d, wall_ms: performance.now() - t0};
+    } catch (e) {
+      return {success: false, error: e.message, wall_ms: performance.now() - t0};
+    }
+  }
+}
+```
+
+Usage:
+```javascript
+const ai = new FCClient('http://localhost:8899');
+
+const result = await ai.call({
+  query: "Ball is BELOW. Move down. Choose: up/down/stay",
+  tools: TOOLS,
+  system: "You are a Pong AI. Move paddle to intercept ball.",
+  env: ["ball_y=300", "paddle_y=200", "gap=100"],
+  history: ["move(down)", "move(down)"]
+});
+
+if (result.success) {
+  console.log(`${result.function}(${JSON.stringify(result.args)}) in ${result.latency_ms}ms`);
+}
+```
+
+## 9. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| AI stuck / no movement | Query too vague | Add decision hints: "Move DOWN to intercept" |
+| `.trim is not a function` | `args` values may be int | Use `String(v)` before `.trim()` |
+| High latency (>100ms) | Too many heads / long query | Reduce tool params, shorten query/env |
+| Wrong function called | Ambiguous tool descriptions | Add `enum`, improve `description` fields |
+| `<|null|>` in all args | Model confused | Check tool param order matches expectations |
+
+---
+
+**Skill Version**: 2.0 — Supports v1/v2 server, multi-domain (game, robotics, avatar)  
+**Last Updated**: 2026-03