@geenius/ai 0.1.0

package/packages/shared/src/content.ts

@@ -0,0 +1,249 @@
+// @geenius-ai/shared — src/content.ts
+
+/**
+ * Content management types and helpers.
+ * Supports AI-powered content generation, rewriting, translation, and templating.
+ */
+
+import type { AIProviderType } from './types'
+
+// ============================================================================
+// Content Types
+// ============================================================================
+
+export type ContentType =
+    | 'text'
+    | 'email'
+    | 'social-post'
+    | 'product-description'
+    | 'blog-post'
+    | 'landing-page'
+    | 'notification'
+    | 'seo-meta'
+    | 'ad-copy'
+    | 'custom'
+
+export type ContentAction =
+    | 'generate'
+    | 'rewrite'
+    | 'translate'
+    | 'summarize'
+    | 'expand'
+    | 'shorten'
+    | 'change-tone'
+    | 'extract'
+    | 'proofread'
+    | 'variations'
+
+export type ContentTone =
+    | 'professional'
+    | 'casual'
+    | 'friendly'
+    | 'formal'
+    | 'persuasive'
+    | 'technical'
+    | 'humorous'
+    | 'empathetic'
+
+export interface ContentTemplate {
+    id: string
+    name: string
+    type: ContentType
+    description?: string
+    systemPrompt: string
+    userPromptTemplate: string
+    /** Expected output fields */
+    outputFields?: ContentOutputField[]
+    /** Default tone */
+    tone?: ContentTone
+    /** Max tokens for generation */
+    maxTokens?: number
+    /** Tags for filtering */
+    tags?: string[]
+}
+
+export interface ContentOutputField {
+    name: string
+    type: 'string' | 'string[]' | 'number'
+    description?: string
+    required?: boolean
+}
+
+export interface ContentItem {
+    id: string
+    type: ContentType
+    action: ContentAction
+    input: string
+    output: string
+    templateId?: string
+    model?: string
+    provider?: AIProviderType
+    tone?: ContentTone
+    language?: string
+    metadata?: Record<string, unknown>
+    tokens?: number
+    costUsd?: number
+    createdAt: number
+}
+
+export interface ContentSchema {
+    /** Zod/Yup schema for the content fields */
+    fields: ContentFieldMeta[]
+    /** Context for AI generation */
+    context?: string
+}
+
+export interface ContentFieldMeta {
+    name: string
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object'
+    label?: string
+    /** AI hint for content generation */
+    hint?: string
+    /** Max length */
+    maxLength?: number
+    /** Allowed values */
+    enum?: string[]
+    required?: boolean
+}
+
+// ============================================================================
+// Content Generation Options
+// ============================================================================
+
+export interface ContentGenerateOptions {
+    action: ContentAction
+    /** Input text to transform, or prompt for generation */
+    input: string
+    type?: ContentType
+    tone?: ContentTone
+    /** Target language for translation */
+    language?: string
+    /** Number of variations to generate */
+    variations?: number
+    /** Template to use */
+    templateId?: string
+    /** Custom instructions */
+    instructions?: string
+    /** Max output length */
+    maxLength?: number
+    /** Model override */
+    model?: string
+    /** Schema context for structured generation */
+    schema?: ContentSchema
+}
+
+export interface ContentResult {
+    content: string
+    /** For multi-variation generation */
+    alternatives?: string[]
+    action: ContentAction
+    type: ContentType
+    model: string
+    tokens?: number
+    costUsd?: number
+    durationMs: number
+}
+
+// ============================================================================
+// Built-in Templates
+// ============================================================================
+
+export const BUILT_IN_TEMPLATES: Record<string, ContentTemplate> = {
+    'product-description': {
+        id: 'product-description',
+        name: 'Product Description',
+        type: 'product-description',
+        description: 'Generate a compelling product description',
+        systemPrompt: 'You are a skilled copywriter specializing in product descriptions. Write clear, persuasive descriptions that highlight key features and benefits.',
+        userPromptTemplate: 'Write a product description for: {{input}}\n\n{{#instructions}}Additional instructions: {{instructions}}{{/instructions}}',
+        outputFields: [
+            { name: 'headline', type: 'string', required: true },
+            { name: 'description', type: 'string', required: true },
+            { name: 'bulletPoints', type: 'string[]' },
+        ],
+        tone: 'persuasive',
+        maxTokens: 500,
+        tags: ['ecommerce', 'marketing'],
+    },
+    'email-subject': {
+        id: 'email-subject',
+        name: 'Email Subject Line',
+        type: 'email',
+        description: 'Generate email subject lines',
+        systemPrompt: 'You are an email marketing expert. Generate compelling subject lines that drive opens.',
+        userPromptTemplate: 'Generate 5 email subject lines for: {{input}}',
+        outputFields: [
+            { name: 'subjects', type: 'string[]', required: true },
+        ],
+        tone: 'persuasive',
+        maxTokens: 200,
+        tags: ['email', 'marketing'],
+    },
+    'social-post': {
+        id: 'social-post',
+        name: 'Social Media Post',
+        type: 'social-post',
+        description: 'Generate a social media post',
+        systemPrompt: 'You are a social media manager. Write engaging posts that drive engagement.',
+        userPromptTemplate: 'Write a social media post about: {{input}}\n\nPlatform: {{platform}}\nTone: {{tone}}',
+        tone: 'casual',
+        maxTokens: 300,
+        tags: ['social', 'marketing'],
+    },
+    'seo-meta': {
+        id: 'seo-meta',
+        name: 'SEO Meta Tags',
+        type: 'seo-meta',
+        description: 'Generate SEO meta title and description',
+        systemPrompt: 'You are an SEO expert. Generate optimized meta tags.',
+        userPromptTemplate: 'Generate SEO meta title (60 chars max) and meta description (155 chars max) for: {{input}}',
+        outputFields: [
+            { name: 'title', type: 'string', required: true },
+            { name: 'description', type: 'string', required: true },
+        ],
+        tone: 'professional',
+        maxTokens: 200,
+        tags: ['seo'],
+    },
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Build a prompt from a content template and variables.
+ */
+export function buildContentPrompt(
+    template: ContentTemplate,
+    vars: Record<string, string>,
+): { systemPrompt: string; userPrompt: string } {
+    let userPrompt = template.userPromptTemplate
+    for (const [key, value] of Object.entries(vars)) {
+        // Handle simple {{var}} replacement
+        userPrompt = userPrompt.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value)
+    }
+    // Remove unmatched conditionals {{#...}}...{{/...}}
+    userPrompt = userPrompt.replace(/\{\{#\w+\}\}.*?\{\{\/\w+\}\}/gs, '')
+    return { systemPrompt: template.systemPrompt, userPrompt: userPrompt.trim() }
+}
+
+/**
+ * Build a system prompt for a content action.
+ */
+export function buildActionSystemPrompt(action: ContentAction, tone?: ContentTone): string {
+    const toneStr = tone ? ` Use a ${tone} tone.` : ''
+    const prompts: Record<ContentAction, string> = {
+        generate: `You are a skilled content writer. Generate high-quality content as requested.${toneStr}`,
+        rewrite: `You are an expert editor. Rewrite the provided content to improve clarity, flow, and impact.${toneStr}`,
+        translate: `You are a professional translator. Translate the content accurately while preserving tone and meaning.`,
+        summarize: `You are an expert at summarization. Provide a clear, concise summary of the given content.`,
+        expand: `You are a content writer. Expand the given content with more detail, examples, and depth.${toneStr}`,
+        shorten: `You are an editor. Shorten the content while preserving the key message and important details.`,
+        'change-tone': `You are a skilled writer. Rewrite the content in the specified tone while preserving the meaning.${toneStr}`,
+        extract: `You are a data extraction expert. Extract the requested information from the provided content.`,
+        proofread: `You are a proofreader. Fix grammar, spelling, punctuation, and style issues. Return the corrected text.`,
+        variations: `You are a creative writer. Generate multiple distinct variations of the given content.${toneStr}`,
+    }
+    return prompts[action]
+}

package/packages/shared/src/convex/helpers.ts

@@ -0,0 +1,163 @@
+// @geenius-ai/shared — src/convex/helpers.ts
+
+/**
+ * Convex backend helper functions for AI operations.
+ * Apps use these inside their own Convex actions/mutations.
+ *
+ * @example
+ * ```ts
+ * // convex/ai.ts
+ * import { action, internalMutation, query } from './_generated/server'
+ * import { generateTextArgs, saveLogArgs, listLogsArgs } from '@geenius-ai/shared/convex'
+ * import { performAICall, createLogEntry } from '@geenius-ai/shared/convex'
+ *
+ * export const generateText = action({
+ *     args: generateTextArgs,
+ *     handler: async (ctx, args) => {
+ *         return await performAICall(ctx, args)
+ *     },
+ * })
+ * ```
+ */
+
+import type {
+    AIConfig,
+    AIGenerateTextOptions,
+    AIGenerationResult,
+    AILogEntry,
+    AIRequestStatus,
+    AIGenerationType,
+} from '../types'
+import { defineAIConfig } from '../config'
+import { resolveProviderForModel, generateTextWithRetries } from '../providers/registry'
+import { extractPromptText } from '../providers/base'
+
+/**
+ * Perform an AI text generation call with logging.
+ * This is the high-level function apps call from Convex actions.
+ */
+export async function performAICall(
+    ctx: { runMutation?: (fn: any, args: any) => Promise<any>; runQuery?: (fn: any, args: any) => Promise<any> },
+    args: AIGenerateTextOptions,
+    options: {
+        config?: AIConfig
+        saveLogFn?: any // Reference to the internal mutation for saving logs
+        getModelCostFn?: any // Reference to the internal query for model costs
+        getApiKey?: (envVar: string) => string | undefined
+    } = {},
+): Promise<AIGenerationResult> {
+    const config = options.config ?? defineAIConfig()
+    const getApiKey = options.getApiKey ?? ((envVar: string) =>
+        (globalThis as any).process?.env?.[envVar]
+    )
+
+    const { model, messages, caller = 'unknown' } = args
+    const provider = resolveProviderForModel(config, model, getApiKey)
+    const promptInfo = extractPromptText(messages)
+    const requestId = `req-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`
+    const timestamp = Date.now()
+
+    let result: AIGenerationResult | undefined
+    let status: AIRequestStatus = 'success'
+    let errorMessage: string | undefined
+    let httpStatus = 200
+
+    try {
+        result = await generateTextWithRetries(provider, args, config.retries)
+        return result
+    } catch (err) {
+        status = 'error'
+        errorMessage = err instanceof Error ? err.message : 'Unknown error'
+        // Try to extract HTTP status from error message
+        const statusMatch = errorMessage.match(/\((\d{3})\)/)
+        if (statusMatch) httpStatus = parseInt(statusMatch[1]!, 10)
+        throw err
+    } finally {
+        const durationMs = Date.now() - timestamp
+
+        // Calculate costs
+        let inputCostUsd: number | undefined
+        let outputCostUsd: number | undefined
+        let totalCostUsd: number | undefined
+
+        const modelConfig = config.models.find(m => m.id === model)
+        if (modelConfig && result?.tokens) {
+            inputCostUsd = (result.tokens.prompt / 1000) * modelConfig.inputCostPer1k
+            outputCostUsd = (result.tokens.completion / 1000) * modelConfig.outputCostPer1k
+            totalCostUsd = inputCostUsd + outputCostUsd
+        }
+
+        // Save log if mutation reference provided
+        if (options.saveLogFn && ctx.runMutation) {
+            try {
+                await ctx.runMutation(options.saveLogFn, {
+                    requestId,
+                    model,
+                    provider: provider.type,
+                    caller,
+                    type: 'text' as string,
+                    timestamp,
+                    durationMs,
+                    systemPrompt: promptInfo.systemPrompt.substring(0, config.logging.maxPromptLength),
+                    userPrompt: promptInfo.userPromptText.substring(0, config.logging.maxPromptLength),
+                    hasImage: promptInfo.hasImage,
+                    imageSizeBytes: promptInfo.imageSizeBytes || undefined,
+                    temperature: args.temperature,
+                    maxTokens: args.maxTokens,
+                    requestBodySize: JSON.stringify(args).length,
+                    status,
+                    httpStatus,
+                    responseContent: (result?.content ?? '').substring(0, config.logging.maxResponseLength),
+                    responseSize: result?.content?.length ?? 0,
+                    finishReason: result?.finishReason,
+                    promptTokens: result?.tokens?.prompt,
+                    completionTokens: result?.tokens?.completion,
+                    totalTokens: result?.tokens?.total,
+                    errorMessage,
+                    inputCostUsd,
+                    outputCostUsd,
+                    totalCostUsd,
+                })
+            } catch (logErr) {
+                console.error('[geenius-ai] Failed to save log:', logErr)
+            }
+        }
+    }
+}
+
+/**
+ * Build an AI log entry object (without saving).
+ * Useful for custom logging flows.
+ */
+export function createLogEntry(
+    args: Partial<AILogEntry> & { requestId: string; model: string; timestamp: number },
+): AILogEntry {
+    return {
+        requestId: args.requestId,
+        model: args.model,
+        provider: args.provider ?? 'openai',
+        caller: args.caller ?? 'unknown',
+        type: args.type ?? 'text',
+        timestamp: args.timestamp,
+        durationMs: args.durationMs ?? 0,
+        systemPrompt: args.systemPrompt ?? '',
+        userPrompt: args.userPrompt ?? '',
+        hasImage: args.hasImage ?? false,
+        imageSizeBytes: args.imageSizeBytes,
+        temperature: args.temperature,
+        maxTokens: args.maxTokens,
+        requestBodySize: args.requestBodySize ?? 0,
+        status: args.status ?? 'success',
+        httpStatus: args.httpStatus ?? 200,
+        responseContent: args.responseContent ?? '',
+        responseSize: args.responseSize ?? 0,
+        finishReason: args.finishReason,
+        promptTokens: args.promptTokens,
+        completionTokens: args.completionTokens,
+        totalTokens: args.totalTokens,
+        errorMessage: args.errorMessage,
+        inputCostUsd: args.inputCostUsd,
+        outputCostUsd: args.outputCostUsd,
+        totalCostUsd: args.totalCostUsd,
+    }
+}

package/packages/shared/src/convex/index.ts

@@ -0,0 +1,16 @@
+// @geenius-ai/shared — src/convex/index.ts
+
+// Schemas
+export { aiTables, aiLogsTable, aiModelCostsTable, aiProvidersTable, aiConversationsTable, aiMessagesTable } from './schemas'
+
+// Validators
+export {
+    generateTextArgs, generateImageArgs, generateAudioArgs,
+    transcribeAudioArgs, generateVideoArgs, testModelArgs,
+    saveLogArgs, listLogsArgs,
+    upsertModelArgs,
+    createConversationArgs, updateConversationArgs, sendMessageArgs,
+} from './validators'
+
+// Helpers
+export { performAICall, createLogEntry } from './helpers'

package/packages/shared/src/convex/schemas.ts

@@ -0,0 +1,146 @@
+// @geenius-ai/shared — src/convex/schemas.ts
+
+/**
+ * Convex table schemas for the AI component.
+ * Apps merge these into their schema.
+ *
+ * @example
+ * ```ts
+ * // convex/schema.ts
+ * import { defineSchema } from 'convex/server'
+ * import { aiTables } from '@geenius-ai/shared/convex'
+ *
+ * export default defineSchema({
+ *   ...aiTables,
+ *   // your other tables
+ * })
+ * ```
+ */
+
+import { defineTable } from 'convex/server'
+import { v } from 'convex/values'
+
+// ============================================================================
+// AI Log Entry — every API call is recorded
+// ============================================================================
+
+export const aiLogsTable = defineTable({
+    requestId: v.string(),
+    model: v.string(),
+    provider: v.string(),
+    caller: v.string(),
+    type: v.string(), // text, image, audio, video, transcription
+    timestamp: v.number(),
+    durationMs: v.number(),
+    systemPrompt: v.string(),
+    userPrompt: v.string(),
+    hasImage: v.boolean(),
+    imageSizeBytes: v.optional(v.number()),
+    temperature: v.optional(v.number()),
+    maxTokens: v.optional(v.number()),
+    requestBodySize: v.number(),
+    status: v.union(v.literal('success'), v.literal('error')),
+    httpStatus: v.number(),
+    responseContent: v.string(),
+    responseSize: v.number(),
+    finishReason: v.optional(v.string()),
+    promptTokens: v.optional(v.number()),
+    completionTokens: v.optional(v.number()),
+    totalTokens: v.optional(v.number()),
+    errorMessage: v.optional(v.string()),
+    inputCostUsd: v.optional(v.number()),
+    outputCostUsd: v.optional(v.number()),
+    totalCostUsd: v.optional(v.number()),
+})
+    .index('by_timestamp', ['timestamp'])
+    .index('by_model', ['model', 'timestamp'])
+    .index('by_provider', ['provider', 'timestamp'])
+    .index('by_caller', ['caller', 'timestamp'])
+    .index('by_status', ['status', 'timestamp'])
+
+// ============================================================================
+// Model Cost Registry
+// ============================================================================
+
+export const aiModelCostsTable = defineTable({
+    model: v.string(),
+    provider: v.string(),
+    displayName: v.optional(v.string()),
+    inputCostPer1k: v.number(),
+    outputCostPer1k: v.number(),
+    capabilities: v.optional(v.array(v.string())),
+    contextWindow: v.optional(v.number()),
+    isActive: v.boolean(),
+    updatedAt: v.number(),
+})
+    .index('by_model', ['model'])
+    .index('by_provider', ['provider'])
+
+// ============================================================================
+// Provider Configuration
+// ============================================================================
+
+export const aiProvidersTable = defineTable({
+    name: v.string(),
+    type: v.string(),
+    baseUrl: v.string(),
+    apiKeyEnvVar: v.string(),
+    isActive: v.boolean(),
+    models: v.array(v.string()),
+    defaultModel: v.optional(v.string()),
+    updatedAt: v.number(),
+})
+    .index('by_type', ['type'])
+    .index('by_name', ['name'])
+
+// ============================================================================
+// Chat Conversations
+// ============================================================================
+
+export const aiConversationsTable = defineTable({
+    userId: v.string(),
+    title: v.string(),
+    model: v.string(),
+    systemPrompt: v.optional(v.string()),
+    status: v.union(v.literal('active'), v.literal('archived')),
+    favorite: v.boolean(),
+    tags: v.array(v.string()),
+    folderId: v.optional(v.string()),
+    messageCount: v.number(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+})
+    .index('by_userId', ['userId'])
+    .index('by_userId_model', ['userId', 'model'])
+    .index('by_userId_status', ['userId', 'status'])
+    .index('by_userId_favorite', ['userId', 'favorite'])
+
+// ============================================================================
+// Chat Messages
+// ============================================================================
+
+export const aiMessagesTable = defineTable({
+    conversationId: v.id('aiConversations'),
+    userId: v.string(),
+    role: v.union(v.literal('system'), v.literal('user'), v.literal('assistant'), v.literal('tool')),
+    content: v.string(),
+    model: v.optional(v.string()),
+    tokens: v.optional(v.number()),
+    durationMs: v.optional(v.number()),
+    createdAt: v.number(),
+})
+    .index('by_conversationId', ['conversationId'])
+    .index('by_conversationId_createdAt', ['conversationId', 'createdAt'])
+    .index('by_userId', ['userId'])
+
+// ============================================================================
+// Combined table export
+// ============================================================================
+
+export const aiTables = {
+    aiLogs: aiLogsTable,
+    aiModelCosts: aiModelCostsTable,
+    aiProviders: aiProvidersTable,
+    aiConversations: aiConversationsTable,
+    aiMessages: aiMessagesTable,
+}