@ebowwa/ai 0.1.0

package/dist/prompts.d.ts

@@ -0,0 +1,222 @@
+/**
+ * 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 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 declare class SystemInstruction implements PromptPart {
+    role: string;
+    guidelines?: string[] | undefined;
+    constructor(role: string, guidelines?: string[] | undefined);
+    toPrompt(): string;
+}
+/**
+ * Context - provides data/background information
+ */
+export declare class Context implements PromptPart {
+    data: Record<string, unknown>;
+    constructor(data: Record<string, unknown>);
+    toPrompt(): string;
+}
+/**
+ * Examples - few-shot learning samples
+ */
+export declare class Examples implements PromptPart {
+    examples: Array<{
+        input: string;
+        output: string;
+    }>;
+    constructor(examples: Array<{
+        input: string;
+        output: string;
+    }>);
+    toPrompt(): string;
+}
+/**
+ * Output format specification
+ */
+export declare class OutputFormat implements PromptPart {
+    type: "json" | "text" | "code" | "markdown";
+    schema?: Record<string, unknown> | undefined;
+    constructor(type: "json" | "text" | "code" | "markdown", schema?: Record<string, unknown> | undefined);
+    toPrompt(): string;
+}
+/**
+ * Constraints - rules and limitations
+ */
+export declare class Constraints implements PromptPart {
+    rules: string[];
+    constructor(rules: string[]);
+    toPrompt(): string;
+}
+/**
+ * Task - the main instruction/question
+ */
+export declare class Task implements PromptPart {
+    instruction: string;
+    constructor(instruction: string);
+    toPrompt(): string;
+}
+/**
+ * Fluent builder for composable prompts
+ */
+export declare class PromptBuilder {
+    private parts;
+    private systemPart?;
+    /**
+     * Set system role and guidelines
+     */
+    system(role: string, guidelines?: string[]): this;
+    /**
+     * Add context data
+     */
+    context(data: Record<string, unknown>): this;
+    /**
+     * Add few-shot examples
+     */
+    examples(examples: Array<{
+        input: string;
+        output: string;
+    }>): this;
+    /**
+     * Specify output format
+     */
+    output(type: "json" | "text" | "code" | "markdown", schema?: Record<string, unknown>): this;
+    /**
+     * Add constraints/rules
+     */
+    constraints(...rules: string[]): this;
+    /**
+     * Add the main task/instruction
+     */
+    task(instruction: string): this;
+    /**
+     * Add custom prompt part
+     */
+    custom(part: PromptPart): this;
+    /**
+     * Build final prompt string (for simple generate)
+     */
+    build(): string;
+    /**
+     * Build for chat completion (returns messages array)
+     */
+    buildChat(): ChatMessage[];
+    /**
+     * Build as system + user prompt pair
+     */
+    buildPair(): {
+        system: string;
+        user: string;
+    };
+}
+/**
+ * Reusable prompt template with variable interpolation
+ */
+export declare class PromptTemplate {
+    private template;
+    constructor(template: string);
+    /**
+     * Render template with variables
+     * Supports {{variable}} syntax
+     */
+    render(vars: Record<string, unknown>): string;
+    /**
+     * Create template from string
+     */
+    static from(template: string): PromptTemplate;
+    /**
+     * Create typed template with compile-time safety
+     */
+    static typed<T extends Record<string, unknown>>(template: string): TypedPromptTemplate<T>;
+}
+/**
+ * Type-safe prompt template
+ */
+export declare class TypedPromptTemplate<T extends Record<string, unknown>> {
+    private template;
+    constructor(template: string);
+    render(vars: T): string;
+}
+/**
+ * Prompt strategies for different reasoning approaches
+ */
+export declare class PromptStrategy {
+    /**
+     * Zero-shot: direct instruction without examples
+     */
+    static zeroShot(instruction: string): string;
+    /**
+     * Few-shot: instruction with examples
+     */
+    static fewShot(instruction: string, examples: Array<{
+        input: string;
+        output: string;
+    }>): string;
+    /**
+     * Chain-of-thought: step-by-step reasoning
+     */
+    static chainOfThought(question: string): string;
+    /**
+     * ReAct: Reasoning + Acting (for tool use)
+     */
+    static reAct(task: string): string;
+}
+/**
+ * Chain prompts where output feeds into next input
+ */
+export declare class PromptChain {
+    private steps;
+    /**
+     * Add a step to the chain
+     */
+    add(step: (input: string, client: any) => Promise<string>): this;
+    /**
+     * Execute the entire chain
+     */
+    execute(initialInput: string, client: any): Promise<string[]>;
+}
+/**
+ * Pre-built prompt templates for common AI tasks
+ */
+export declare const PROMPTS: {
+    /**
+     * Generate a server name based on project context
+     */
+    readonly generateServerName: (project?: string, description?: string) => string;
+    /**
+     * Suggest optimal server type based on workload
+     */
+    readonly suggestServerType: (workload: string) => string;
+    /**
+     * Analyze resource usage and provide recommendations
+     */
+    readonly analyzeResources: (cpu: number, memory: number, disk: number, activePorts?: string[]) => string;
+    /**
+     * Generate SSH troubleshooting tips
+     */
+    readonly sshTroubleshoot: (error: string) => string;
+    /**
+     * Suggest server actions based on state
+     */
+    readonly suggestActions: (status: string, age?: string) => string;
+    /**
+     * Generate a witty server status message
+     */
+    readonly statusMessage: (status: string, name: string) => string;
+};

package/dist/prompts.js

@@ -0,0 +1,462 @@
+/**
+ * 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
+ */
+/**
+ * System instruction - sets AI role and behavior
+ */
+export class SystemInstruction {
+    role;
+    guidelines;
+    constructor(role, guidelines) {
+        this.role = role;
+        this.guidelines = guidelines;
+    }
+    toPrompt() {
+        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 {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    toPrompt() {
+        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 {
+    examples;
+    constructor(examples) {
+        this.examples = examples;
+    }
+    toPrompt() {
+        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 {
+    type;
+    schema;
+    constructor(type, schema) {
+        this.type = type;
+        this.schema = schema;
+    }
+    toPrompt() {
+        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 {
+    rules;
+    constructor(rules) {
+        this.rules = rules;
+    }
+    toPrompt() {
+        if (this.rules.length === 0)
+            return "";
+        return `Constraints:\n${this.rules.map((r) => `- ${r}`).join("\n")}`;
+    }
+}
+/**
+ * Task - the main instruction/question
+ */
+export class Task {
+    instruction;
+    constructor(instruction) {
+        this.instruction = instruction;
+    }
+    toPrompt() {
+        return `Task:\n${this.instruction}`;
+    }
+}
+/**
+ * Fluent builder for composable prompts
+ */
+export class PromptBuilder {
+    parts = [];
+    systemPart;
+    /**
+     * Set system role and guidelines
+     */
+    system(role, guidelines) {
+        this.systemPart = new SystemInstruction(role, guidelines);
+        return this;
+    }
+    /**
+     * Add context data
+     */
+    context(data) {
+        this.parts.push(new Context(data));
+        return this;
+    }
+    /**
+     * Add few-shot examples
+     */
+    examples(examples) {
+        this.parts.push(new Examples(examples));
+        return this;
+    }
+    /**
+     * Specify output format
+     */
+    output(type, schema) {
+        this.parts.push(new OutputFormat(type, schema));
+        return this;
+    }
+    /**
+     * Add constraints/rules
+     */
+    constraints(...rules) {
+        this.parts.push(new Constraints(rules));
+        return this;
+    }
+    /**
+     * Add the main task/instruction
+     */
+    task(instruction) {
+        this.parts.push(new Task(instruction));
+        return this;
+    }
+    /**
+     * Add custom prompt part
+     */
+    custom(part) {
+        this.parts.push(part);
+        return this;
+    }
+    /**
+     * Build final prompt string (for simple generate)
+     */
+    build() {
+        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() {
+        const messages = [];
+        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() {
+        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 {
+    template;
+    constructor(template) {
+        this.template = template;
+    }
+    /**
+     * Render template with variables
+     * Supports {{variable}} syntax
+     */
+    render(vars) {
+        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) {
+        return new PromptTemplate(template);
+    }
+    /**
+     * Create typed template with compile-time safety
+     */
+    static typed(template) {
+        return new TypedPromptTemplate(template);
+    }
+}
+/**
+ * Type-safe prompt template
+ */
+export class TypedPromptTemplate {
+    template;
+    constructor(template) {
+        this.template = template;
+    }
+    render(vars) {
+        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) {
+        return instruction;
+    }
+    /**
+     * Few-shot: instruction with examples
+     */
+    static fewShot(instruction, examples) {
+        return new PromptBuilder().examples(examples).task(instruction).build();
+    }
+    /**
+     * Chain-of-thought: step-by-step reasoning
+     */
+    static chainOfThought(question) {
+        return `${question}\n\nThink step by step. Show your work and reasoning process.`;
+    }
+    /**
+     * ReAct: Reasoning + Acting (for tool use)
+     */
+    static reAct(task) {
+        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 {
+    steps = [];
+    /**
+     * Add a step to the chain
+     */
+    add(step) {
+        this.steps.push(step);
+        return this;
+    }
+    /**
+     * Execute the entire chain
+     */
+    async execute(initialInput, client) {
+        const results = [];
+        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, description) => {
+        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) => {
+        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, memory, disk, activePorts) => {
+        const contextData = {
+            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) => {
+        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, age) => {
+        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, name) => {
+        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();
+    },
+};