@geenius/ai 0.1.0

package/packages/shared/src/skills.ts

@@ -0,0 +1,273 @@
+// @geenius-ai/shared — src/skills.ts
+
+/**
+ * Skill registry — reusable, composable AI capabilities.
+ * Skills are named operations with typed inputs/outputs that can be
+ * chained, configured, and discovered at runtime.
+ */
+
+// ============================================================================
+// Skill Types
+// ============================================================================
+
+export type SkillCategory =
+    | 'text'
+    | 'data'
+    | 'media'
+    | 'analysis'
+    | 'communication'
+    | 'code'
+    | 'custom'
+
+export type SkillParameterType = 'string' | 'number' | 'boolean' | 'string[]' | 'object'
+
+export interface SkillParameter {
+    name: string
+    type: SkillParameterType
+    description?: string
+    required?: boolean
+    default?: unknown
+    enum?: string[]
+}
+
+export interface SkillDefinition {
+    id: string
+    name: string
+    description: string
+    category: SkillCategory
+    /** Input parameters the skill accepts */
+    parameters: SkillParameter[]
+    /** System prompt for the AI */
+    systemPrompt: string
+    /** User prompt template (use {{paramName}} for interpolation) */
+    promptTemplate: string
+    /** Required model capabilities */
+    requiredCapabilities?: string[]
+    /** Default model to use */
+    defaultModel?: string
+    /** Max tokens for output */
+    maxTokens?: number
+    /** Tags for discovery */
+    tags?: string[]
+}
+
+export interface SkillContext {
+    /** The skill being executed */
+    skillId: string
+    /** Input parameters */
+    params: Record<string, unknown>
+    /** User ID for personalization */
+    userId?: string
+    /** Additional context (e.g., page data, form schema) */
+    context?: Record<string, unknown>
+    /** Model override */
+    model?: string
+}
+
+export interface SkillResult {
+    skillId: string
+    output: string
+    /** Structured output if applicable */
+    structured?: Record<string, unknown>
+    model: string
+    tokens?: number
+    costUsd?: number
+    durationMs: number
+}
+
+// ============================================================================
+// Skill Registry
+// ============================================================================
+
+export interface SkillRegistry {
+    /** Register a custom skill */
+    register(skill: SkillDefinition): void
+    /** Get a skill by ID */
+    get(id: string): SkillDefinition | undefined
+    /** List all registered skills */
+    list(category?: SkillCategory): SkillDefinition[]
+    /** Search skills by query */
+    search(query: string): SkillDefinition[]
+    /** Execute a skill */
+    execute(context: SkillContext): Promise<SkillResult>
+}
+
+/**
+ * Create an in-memory skill registry.
+ */
+export function createSkillRegistry(): SkillRegistry {
+    const skills = new Map<string, SkillDefinition>()
+
+    // Register built-in skills
+    for (const skill of Object.values(BUILT_IN_SKILLS)) {
+        skills.set(skill.id, skill)
+    }
+
+    return {
+        register(skill) {
+            skills.set(skill.id, skill)
+        },
+        get(id) {
+            return skills.get(id)
+        },
+        list(category?) {
+            const all = Array.from(skills.values())
+            if (!category) return all
+            return all.filter(s => s.category === category)
+        },
+        search(query) {
+            const q = query.toLowerCase()
+            return Array.from(skills.values()).filter(s =>
+                s.name.toLowerCase().includes(q) ||
+                s.description.toLowerCase().includes(q) ||
+                s.tags?.some(t => t.toLowerCase().includes(q))
+            )
+        },
+        async execute(_context) {
+            // This is a stub — actual execution happens in the framework-specific layer
+            // (React hook / SolidJS primitive) which has access to the AI provider
+            throw new Error('Skill execution requires a framework adapter. Use useSkills() or createSkills().')
+        },
+    }
+}
+
+// ============================================================================
+// Built-in Skill Definitions
+// ============================================================================
+
+export const BUILT_IN_SKILLS: Record<string, SkillDefinition> = {
+    summarize: {
+        id: 'summarize',
+        name: 'Summarize',
+        description: 'Summarize text content into a concise overview',
+        category: 'text',
+        parameters: [
+            { name: 'text', type: 'string', description: 'Text to summarize', required: true },
+            { name: 'length', type: 'string', description: 'Summary length', default: 'medium', enum: ['short', 'medium', 'long'] },
+            { name: 'format', type: 'string', description: 'Output format', default: 'paragraph', enum: ['paragraph', 'bullets', 'tldr'] },
+        ],
+        systemPrompt: 'You are an expert summarizer. Provide clear, accurate summaries that capture the key points.',
+        promptTemplate: 'Summarize the following text ({{length}}, {{format}} format):\n\n{{text}}',
+        tags: ['text', 'summary', 'core'],
+    },
+    translate: {
+        id: 'translate',
+        name: 'Translate',
+        description: 'Translate text between languages',
+        category: 'text',
+        parameters: [
+            { name: 'text', type: 'string', description: 'Text to translate', required: true },
+            { name: 'targetLanguage', type: 'string', description: 'Target language', required: true },
+            { name: 'sourceLanguage', type: 'string', description: 'Source language (auto-detect if omitted)' },
+            { name: 'preserveTone', type: 'boolean', description: 'Preserve the original tone', default: true },
+        ],
+        systemPrompt: 'You are a professional translator. Translate accurately while preserving tone, meaning, and cultural nuance.',
+        promptTemplate: 'Translate the following to {{targetLanguage}}{{#sourceLanguage}} (from {{sourceLanguage}}){{/sourceLanguage}}:\n\n{{text}}',
+        tags: ['text', 'translation', 'i18n', 'core'],
+    },
+    rewrite: {
+        id: 'rewrite',
+        name: 'Rewrite',
+        description: 'Rewrite text with improved clarity, tone, or style',
+        category: 'text',
+        parameters: [
+            { name: 'text', type: 'string', description: 'Text to rewrite', required: true },
+            { name: 'tone', type: 'string', description: 'Target tone', enum: ['professional', 'casual', 'friendly', 'formal', 'persuasive'] },
+            { name: 'instructions', type: 'string', description: 'Specific rewrite instructions' },
+        ],
+        systemPrompt: 'You are an expert editor. Rewrite content to improve its quality while preserving the core message.',
+        promptTemplate: 'Rewrite the following text{{#tone}} in a {{tone}} tone{{/tone}}{{#instructions}}. Instructions: {{instructions}}{{/instructions}}:\n\n{{text}}',
+        tags: ['text', 'editing', 'core'],
+    },
+    extract: {
+        id: 'extract',
+        name: 'Extract Data',
+        description: 'Extract structured data or specific information from text',
+        category: 'data',
+        parameters: [
+            { name: 'text', type: 'string', description: 'Text to extract from', required: true },
+            { name: 'fields', type: 'string[]', description: 'Fields to extract', required: true },
+            { name: 'format', type: 'string', description: 'Output format', default: 'json', enum: ['json', 'csv', 'table'] },
+        ],
+        systemPrompt: 'You are a data extraction expert. Extract the requested information accurately and return it in the specified format.',
+        promptTemplate: 'Extract the following fields from the text: {{fields}}\n\nOutput format: {{format}}\n\nText:\n{{text}}',
+        tags: ['data', 'extraction', 'structured'],
+    },
+    classify: {
+        id: 'classify',
+        name: 'Classify',
+        description: 'Classify text into categories',
+        category: 'analysis',
+        parameters: [
+            { name: 'text', type: 'string', description: 'Text to classify', required: true },
+            { name: 'categories', type: 'string[]', description: 'Available categories', required: true },
+            { name: 'multiLabel', type: 'boolean', description: 'Allow multiple categories', default: false },
+        ],
+        systemPrompt: 'You are a text classification expert. Classify content accurately into the given categories.',
+        promptTemplate: 'Classify the following text into {{#multiLabel}}one or more of{{/multiLabel}}{{^multiLabel}}exactly one of{{/multiLabel}} these categories: {{categories}}\n\nText:\n{{text}}',
+        tags: ['analysis', 'classification', 'core'],
+    },
+    'sentiment-analysis': {
+        id: 'sentiment-analysis',
+        name: 'Sentiment Analysis',
+        description: 'Analyze the sentiment and emotion of text',
+        category: 'analysis',
+        parameters: [
+            { name: 'text', type: 'string', description: 'Text to analyze', required: true },
+            { name: 'granularity', type: 'string', description: 'Analysis depth', default: 'basic', enum: ['basic', 'detailed'] },
+        ],
+        systemPrompt: 'You are a sentiment analysis expert. Analyze text for sentiment, emotion, and tone.',
+        promptTemplate: 'Analyze the sentiment of the following text ({{granularity}} analysis):\n\n{{text}}\n\nReturn: sentiment (positive/negative/neutral/mixed), confidence (0-1), and key emotions detected.',
+        tags: ['analysis', 'sentiment', 'nlp'],
+    },
+    'generate-code': {
+        id: 'generate-code',
+        name: 'Generate Code',
+        description: 'Generate code from natural language description',
+        category: 'code',
+        parameters: [
+            { name: 'description', type: 'string', description: 'What the code should do', required: true },
+            { name: 'language', type: 'string', description: 'Programming language', required: true },
+            { name: 'framework', type: 'string', description: 'Framework to use (optional)' },
+        ],
+        systemPrompt: 'You are an expert programmer. Generate clean, well-documented code.',
+        promptTemplate: 'Generate {{language}} code{{#framework}} using {{framework}}{{/framework}} for the following:\n\n{{description}}',
+        tags: ['code', 'generation'],
+    },
+    'compose-email': {
+        id: 'compose-email',
+        name: 'Compose Email',
+        description: 'Draft a professional email',
+        category: 'communication',
+        parameters: [
+            { name: 'purpose', type: 'string', description: 'Purpose of the email', required: true },
+            { name: 'recipient', type: 'string', description: 'Who the email is to' },
+            { name: 'tone', type: 'string', description: 'Email tone', default: 'professional', enum: ['professional', 'casual', 'friendly', 'formal'] },
+            { name: 'context', type: 'string', description: 'Additional context' },
+        ],
+        systemPrompt: 'You are a professional email writer. Draft clear, effective emails.',
+        promptTemplate: 'Draft an email{{#recipient}} to {{recipient}}{{/recipient}} with a {{tone}} tone.\n\nPurpose: {{purpose}}{{#context}}\n\nContext: {{context}}{{/context}}',
+        tags: ['communication', 'email'],
+    },
+}
+
+/**
+ * Build a prompt from a skill definition and parameters.
+ */
+export function buildSkillPrompt(
+    skill: SkillDefinition,
+    params: Record<string, unknown>,
+): { systemPrompt: string; userPrompt: string } {
+    let userPrompt = skill.promptTemplate
+
+    for (const [key, value] of Object.entries(params)) {
+        const strValue = Array.isArray(value) ? value.join(', ') : String(value ?? '')
+        userPrompt = userPrompt.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), strValue)
+    }
+
+    // Remove unmatched template conditionals
+    userPrompt = userPrompt.replace(/\{\{#\w+\}\}.*?\{\{\/\w+\}\}/gs, '')
+    userPrompt = userPrompt.replace(/\{\{\^\w+\}\}.*?\{\{\/\w+\}\}/gs, '')
+
+    return { systemPrompt: skill.systemPrompt, userPrompt: userPrompt.trim() }
+}