@ebowwa/ai 0.1.0 → 0.1.1

package/prompts.ts

@@ -0,0 +1,551 @@
+/**
+ * Composable prompt architecture for scalable AI interactions
+ *
+ * Core concepts:
+ * - PromptPart: Composable building blocks
+ * - PromptBuilder: Fluent API for assembling prompts
+ * - PromptTemplate: Reusable templates with interpolation
+ * - PromptChain: Multi-step workflows
+ * - PromptStrategy: Different reasoning approaches
+ */
+
+// Import and re-export ChatMessage for type compatibility
+import type { ChatMessage } from "./types.js";
+
+export type { ChatMessage };
+
+/**
+ * Base interface for all composable prompt parts
+ */
+export interface PromptPart {
+  toPrompt(): string;
+}
+
+/**
+ * System instruction - sets AI role and behavior
+ */
+export class SystemInstruction implements PromptPart {
+  constructor(
+    public role: string,
+    public guidelines?: string[],
+  ) {}
+
+  toPrompt(): string {
+    const base = `You are a ${this.role}.`;
+    if (this.guidelines?.length) {
+      return `${base}\n\nGuidelines:\n${this.guidelines.map((g) => `- ${g}`).join("\n")}`;
+    }
+    return base;
+  }
+}
+
+/**
+ * Context - provides data/background information
+ */
+export class Context implements PromptPart {
+  constructor(public data: Record<string, unknown>) {}
+
+  toPrompt(): string {
+    const entries = Object.entries(this.data)
+      .filter(([_, v]) => v !== undefined && v !== null && v !== "")
+      .map(
+        ([k, v]) => `- ${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`,
+      )
+      .join("\n");
+    return entries ? `Context:\n${entries}` : "";
+  }
+}
+
+/**
+ * Examples - few-shot learning samples
+ */
+export class Examples implements PromptPart {
+  constructor(public examples: Array<{ input: string; output: string }>) {}
+
+  toPrompt(): string {
+    if (this.examples.length === 0) return "";
+    return this.examples
+      .map(
+        (ex, i) =>
+          `Example ${i + 1}:\nInput: ${ex.input}\nOutput: ${ex.output}`,
+      )
+      .join("\n\n");
+  }
+}
+
+/**
+ * Output format specification
+ */
+export class OutputFormat implements PromptPart {
+  constructor(
+    public type: "json" | "text" | "code" | "markdown",
+    public schema?: Record<string, unknown>,
+  ) {}
+
+  toPrompt(): string {
+    if (this.type === "json" && this.schema) {
+      return `Respond in JSON format with this schema:\n${JSON.stringify(this.schema, null, 2)}`;
+    }
+    return `Respond in ${this.type} format.`;
+  }
+}
+
+/**
+ * Constraints - rules and limitations
+ */
+export class Constraints implements PromptPart {
+  constructor(public rules: string[]) {}
+
+  toPrompt(): string {
+    if (this.rules.length === 0) return "";
+    return `Constraints:\n${this.rules.map((r) => `- ${r}`).join("\n")}`;
+  }
+}
+
+/**
+ * Task - the main instruction/question
+ */
+export class Task implements PromptPart {
+  constructor(public instruction: string) {}
+
+  toPrompt(): string {
+    return `Task:\n${this.instruction}`;
+  }
+}
+
+/**
+ * Fluent builder for composable prompts
+ */
+export class PromptBuilder {
+  private parts: PromptPart[] = [];
+  private systemPart?: SystemInstruction;
+
+  /**
+   * Set system role and guidelines
+   */
+  system(role: string, guidelines?: string[]): this {
+    this.systemPart = new SystemInstruction(role, guidelines);
+    return this;
+  }
+
+  /**
+   * Add context data
+   */
+  context(data: Record<string, unknown>): this {
+    this.parts.push(new Context(data));
+    return this;
+  }
+
+  /**
+   * Add few-shot examples
+   */
+  examples(examples: Array<{ input: string; output: string }>): this {
+    this.parts.push(new Examples(examples));
+    return this;
+  }
+
+  /**
+   * Specify output format
+   */
+  output(
+    type: "json" | "text" | "code" | "markdown",
+    schema?: Record<string, unknown>,
+  ): this {
+    this.parts.push(new OutputFormat(type, schema));
+    return this;
+  }
+
+  /**
+   * Add constraints/rules
+   */
+  constraints(...rules: string[]): this {
+    this.parts.push(new Constraints(rules));
+    return this;
+  }
+
+  /**
+   * Add the main task/instruction
+   */
+  task(instruction: string): this {
+    this.parts.push(new Task(instruction));
+    return this;
+  }
+
+  /**
+   * Add custom prompt part
+   */
+  custom(part: PromptPart): this {
+    this.parts.push(part);
+    return this;
+  }
+
+  /**
+   * Build final prompt string (for simple generate)
+   */
+  build(): string {
+    const allParts = [
+      ...(this.systemPart ? [this.systemPart] : []),
+      ...this.parts,
+    ];
+    return allParts
+      .map((p) => p.toPrompt())
+      .filter(Boolean)
+      .join("\n\n");
+  }
+
+  /**
+   * Build for chat completion (returns messages array)
+   */
+  buildChat(): ChatMessage[] {
+    const messages: ChatMessage[] = [];
+
+    if (this.systemPart) {
+      messages.push({ role: "system", content: this.systemPart.toPrompt() });
+    }
+
+    const userContent = this.parts
+      .map((p) => p.toPrompt())
+      .filter(Boolean)
+      .join("\n\n");
+    if (userContent) {
+      messages.push({ role: "user", content: userContent });
+    }
+
+    return messages;
+  }
+
+  /**
+   * Build as system + user prompt pair
+   */
+  buildPair(): { system: string; user: string } {
+    return {
+      system: this.systemPart?.toPrompt() || "",
+      user: this.parts
+        .map((p) => p.toPrompt())
+        .filter(Boolean)
+        .join("\n\n"),
+    };
+  }
+}
+
+/**
+ * Reusable prompt template with variable interpolation
+ */
+export class PromptTemplate {
+  constructor(private template: string) {}
+
+  /**
+   * Render template with variables
+   * Supports {{variable}} syntax
+   */
+  render(vars: Record<string, unknown>): string {
+    let result = this.template;
+    for (const [key, value] of Object.entries(vars)) {
+      const placeholder = `{{${key}}}`;
+      result = result.replaceAll(placeholder, String(value ?? ""));
+    }
+    return result;
+  }
+
+  /**
+   * Create template from string
+   */
+  static from(template: string): PromptTemplate {
+    return new PromptTemplate(template);
+  }
+
+  /**
+   * Create typed template with compile-time safety
+   */
+  static typed<T extends Record<string, unknown>>(
+    template: string,
+  ): TypedPromptTemplate<T> {
+    return new TypedPromptTemplate(template);
+  }
+}
+
+/**
+ * Type-safe prompt template
+ */
+export class TypedPromptTemplate<T extends Record<string, unknown>> {
+  constructor(private template: string) {}
+
+  render(vars: T): string {
+    return new PromptTemplate(this.template).render(vars);
+  }
+}
+
+/**
+ * Prompt strategies for different reasoning approaches
+ */
+export class PromptStrategy {
+  /**
+   * Zero-shot: direct instruction without examples
+   */
+  static zeroShot(instruction: string): string {
+    return instruction;
+  }
+
+  /**
+   * Few-shot: instruction with examples
+   */
+  static fewShot(
+    instruction: string,
+    examples: Array<{ input: string; output: string }>,
+  ): string {
+    return new PromptBuilder().examples(examples).task(instruction).build();
+  }
+
+  /**
+   * Chain-of-thought: step-by-step reasoning
+   */
+  static chainOfThought(question: string): string {
+    return `${question}\n\nThink step by step. Show your work and reasoning process.`;
+  }
+
+  /**
+   * ReAct: Reasoning + Acting (for tool use)
+   */
+  static reAct(task: string): string {
+    return `Task: ${task}
+
+Think: [your reasoning about the current state]
+Act: [action to take]
+Observation: [result of action]
+
+Repeat Think/Act/Observation until the task is complete.`;
+  }
+}
+
+/**
+ * Chain prompts where output feeds into next input
+ */
+export class PromptChain {
+  private steps: Array<(input: string, client: any) => Promise<string>> = [];
+
+  /**
+   * Add a step to the chain
+   */
+  add(step: (input: string, client: any) => Promise<string>): this {
+    this.steps.push(step);
+    return this;
+  }
+
+  /**
+   * Execute the entire chain
+   */
+  async execute(initialInput: string, client: any): Promise<string[]> {
+    const results: string[] = [];
+    let current = initialInput;
+
+    for (const step of this.steps) {
+      current = await step(current, client);
+      results.push(current);
+    }
+
+    return results;
+  }
+}
+
+// ============================================================================
+// PRE-BUILT PROMPTS (Refactored using composable architecture)
+// ============================================================================
+
+/**
+ * Pre-built prompt templates for common AI tasks
+ */
+export const PROMPTS = {
+  /**
+   * Generate a server name based on project context
+   */
+  generateServerName: (project?: string, description?: string) => {
+    return new PromptBuilder()
+      .system("server naming specialist", [
+        "Create memorable, technical names",
+        "Use lowercase letters and hyphens only",
+      ])
+      .context({ project, description })
+      .constraints(
+        "8-15 characters maximum",
+        "lowercase letters only",
+        "hyphens allowed but no consecutive hyphens",
+        "Return ONLY the name, no explanation",
+      )
+      .task("Generate a short, memorable server name.")
+      .build();
+  },
+
+  /**
+   * Suggest optimal server type based on workload
+   */
+  suggestServerType: (workload: string) => {
+    return new PromptBuilder()
+      .system("Hetzner cloud infrastructure expert", [
+        "Know all Hetzner server types and their capabilities",
+        "Consider cost-effectiveness",
+      ])
+      .context({ workload })
+      .examples([
+        {
+          input: "High-traffic web server with moderate CPU needs",
+          output:
+            "cpx21 - Good balance of performance and cost for web workloads",
+        },
+        {
+          input: "Development/testing server",
+          output: "cpx11 - Lowest cost option, sufficient for development",
+        },
+      ])
+      .constraints(
+        "Respond with just the server type name",
+        "Follow with one brief sentence explaining why",
+        "Suggest any appropriate Hetzner server type based on the workload needs",
+      )
+      .task("Suggest the best Hetzner server type for this workload.")
+      .build();
+  },
+
+  /**
+   * Analyze resource usage and provide recommendations
+   */
+  analyzeResources: (
+    cpu: number,
+    memory: number,
+    disk: number,
+    activePorts?: string[],
+  ) => {
+    const contextData: Record<string, unknown> = {
+      cpu: `${cpu}%`,
+      memory: `${memory}%`,
+      disk: `${disk}%`,
+    };
+
+    if (activePorts && activePorts.length > 0) {
+      contextData.activePorts =
+        activePorts.slice(0, 10).join(", ") +
+        (activePorts.length > 10 ? ` (+${activePorts.length - 10} more)` : "");
+    }
+
+    return new PromptBuilder()
+      .system("DevOps monitoring specialist", [
+        "Assess server health holistically",
+        "Prioritize actionable advice",
+      ])
+      .context(contextData)
+      .examples([
+        {
+          input: "CPU: 95%, Memory: 90%, Disk: 50%",
+          output:
+            "CRITICAL: Immediate scale-up required. CPU and memory are at dangerous levels.",
+        },
+        {
+          input: "CPU: 15%, Memory: 25%, Disk: 30%",
+          output: "HEALTHY: All metrics within normal range. No action needed.",
+        },
+        {
+          input: "CPU: 45%, Memory: 85%, Disk: 20%",
+          output:
+            "WARNING: Memory usage high. Consider optimizing applications or upgrading memory.",
+        },
+      ])
+      .constraints(
+        "Assessment must be one of: HEALTHY, WARNING, CRITICAL",
+        "Provide exactly one sentence for assessment",
+        "Provide exactly one actionable recommendation if not HEALTHY",
+        "Keep total response under 100 words",
+      )
+      .task("Analyze the server resource usage and provide health assessment.")
+      .build();
+  },
+
+  /**
+   * Generate SSH troubleshooting tips
+   */
+  sshTroubleshoot: (error: string) => {
+    return new PromptBuilder()
+      .system("SSH troubleshooting expert", [
+        "Know common SSH issues and solutions",
+        "Provide practical, step-by-step solutions",
+      ])
+      .context({ error })
+      .examples([
+        {
+          input: "Connection refused",
+          output:
+            "1. Verify SSH service is running: systemctl status sshd\n2. Check firewall rules\n3. Confirm correct port (usually 22)",
+        },
+        {
+          input: "Permission denied (publickey)",
+          output:
+            "1. Verify public key is added to server's ~/.ssh/authorized_keys\n2. Check file permissions: chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys\n3. Ensure you're using the correct private key",
+        },
+      ])
+      .constraints(
+        "Provide 2-3 specific troubleshooting steps",
+        "Each step should be actionable",
+        "Keep responses concise",
+      )
+      .task("Provide SSH troubleshooting steps for this error.")
+      .build();
+  },
+
+  /**
+   * Suggest server actions based on state
+   */
+  suggestActions: (status: string, age?: string) => {
+    return new PromptBuilder()
+      .system("Server operations specialist", [
+        "Understand server lifecycle management",
+        "Consider cost implications",
+      ])
+      .context({ status, age })
+      .examples([
+        {
+          input: "Status: stopped, Age: 2 hours",
+          output:
+            "Actions: start (to resume service), delete (if no longer needed)",
+        },
+        {
+          input: "Status: running, Age: 30 days",
+          output:
+            "Actions: reboot (for maintenance), resize (if performance issues)",
+        },
+      ])
+      .constraints(
+        "Suggest 1-2 appropriate actions",
+        "Include very brief explanation for each",
+        "Consider actions: start, stop, restart, delete, resize",
+      )
+      .task("Suggest appropriate server management actions.")
+      .build();
+  },
+
+  /**
+   * Generate a witty server status message
+   */
+  statusMessage: (status: string, name: string) => {
+    return new PromptBuilder()
+      .system("Playful status message generator", [
+        "Be lighthearted but professional",
+        "Use puns and wordplay when appropriate",
+      ])
+      .context({ status, name })
+      .examples([
+        {
+          input: "Status: running, Name: prod-db-01",
+          output: "🟢 prod-db-01 is alive and kicking!",
+        },
+        {
+          input: "Status: stopped, Name: dev-server",
+          output: "💤 dev-server is taking a nap",
+        },
+      ])
+      .constraints(
+        "Keep under 50 characters",
+        "Use appropriate emoji for status",
+        "Be creative and memorable",
+      )
+      .task("Generate a brief, witty status message.")
+      .build();
+  },
+} as const;

package/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * OpenAI protocol related types for the application
+ *
+ * This file now re-exports types from schema.ts for backward compatibility.
+ * New code should import directly from schema.ts.
+ *
+ * Schema provides:
+ * - Runtime validation with Zod
+ * - Type inference for TypeScript
+ * - Helper functions for validation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.categorizeError = exports.convertUsage = exports.validateRawResponse = exports.validateChatCompletionOptions = exports.validateChatMessages = exports.validateChatMessage = void 0;
+// Re-export validation helpers for convenience
+var ai_1 = require("@ebowwa/codespaces-types/runtime/ai");
+Object.defineProperty(exports, "validateChatMessage", { enumerable: true, get: function () { return ai_1.validateChatMessage; } });
+Object.defineProperty(exports, "validateChatMessages", { enumerable: true, get: function () { return ai_1.validateChatMessages; } });
+Object.defineProperty(exports, "validateChatCompletionOptions", { enumerable: true, get: function () { return ai_1.validateChatCompletionOptions; } });
+Object.defineProperty(exports, "validateRawResponse", { enumerable: true, get: function () { return ai_1.validateRawResponse; } });
+Object.defineProperty(exports, "convertUsage", { enumerable: true, get: function () { return ai_1.convertUsage; } });
+Object.defineProperty(exports, "categorizeError", { enumerable: true, get: function () { return ai_1.categorizeError; } });

package/{dist/types.js → types.ts}

@@ -9,5 +9,16 @@
  * - Type inference for TypeScript
  * - Helper functions for validation
  */
+
+// Re-export all types from schema
+export type * from "@ebowwa/codespaces-types/runtime/ai";
+
 // Re-export validation helpers for convenience
-export { validateChatMessage, validateChatMessages, validateChatCompletionOptions, validateRawResponse, convertUsage, categorizeError, } from "./schemas/ai.js";
+export {
+  validateChatMessage,
+  validateChatMessages,
+  validateChatCompletionOptions,
+  validateRawResponse,
+  convertUsage,
+  categorizeError,
+} from "@ebowwa/codespaces-types/runtime/ai";

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Ebowwa Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.