@geenius/ai 0.1.0

package/packages/react/src/hooks/useMemory.ts

@@ -0,0 +1,161 @@
+// @geenius-ai/react — src/hooks/useMemory.ts
+
+import { useState, useCallback, useRef } from 'react'
+import type {
+    MemoryEntry,
+    MemoryQuery,
+    MemoryNamespace,
+    MemoryImportance,
+    MemoryType,
+} from '@geenius-ai/shared'
+
+export interface UseMemoryOptions {
+    /** Convex mutation to store a memory */
+    storeFn: (entry: Omit<MemoryEntry, 'id' | 'accessCount' | 'lastAccessedAt' | 'createdAt' | 'updatedAt'>) => Promise<MemoryEntry>
+    /** Convex query to search memories */
+    searchFn: (query: MemoryQuery) => Promise<MemoryEntry[]>
+    /** Convex mutation to delete a memory */
+    deleteFn: (id: string) => Promise<void>
+    /** Convex mutation to clear memories */
+    clearFn: (namespace: MemoryNamespace, scopeId: string) => Promise<void>
+    /** Default namespace */
+    defaultNamespace?: MemoryNamespace
+    /** Default scope ID (e.g., current user ID) */
+    defaultScopeId?: string
+}
+
+export interface UseMemoryReturn {
+    /** Store a memory */
+    store: (key: string, value: string, options?: {
+        namespace?: MemoryNamespace
+        type?: MemoryType
+        importance?: MemoryImportance
+        metadata?: Record<string, unknown>
+        scopeId?: string
+    }) => Promise<MemoryEntry>
+    /** Recall a specific memory by key */
+    recall: (key: string, namespace?: MemoryNamespace) => Promise<MemoryEntry | null>
+    /** Search memories */
+    search: (query: MemoryQuery) => Promise<MemoryEntry[]>
+    /** Delete a memory */
+    remove: (id: string) => Promise<void>
+    /** Clear all memories in a namespace/scope */
+    clear: (namespace?: MemoryNamespace) => Promise<void>
+    /** Currently loaded memories */
+    memories: MemoryEntry[]
+    /** Loading state */
+    isLoading: boolean
+    /** Error state */
+    error: Error | null
+}
+
+export function useMemory(options: UseMemoryOptions): UseMemoryReturn {
+    const {
+        storeFn, searchFn, deleteFn, clearFn,
+        defaultNamespace = 'user',
+        defaultScopeId = '',
+    } = options
+
+    const [memories, setMemories] = useState<MemoryEntry[]>([])
+    const [isLoading, setIsLoading] = useState(false)
+    const [error, setError] = useState<Error | null>(null)
+
+    const store = useCallback(async (
+        key: string,
+        value: string,
+        opts?: {
+            namespace?: MemoryNamespace
+            type?: MemoryType
+            importance?: MemoryImportance
+            metadata?: Record<string, unknown>
+            scopeId?: string
+        },
+    ) => {
+        setIsLoading(true)
+        setError(null)
+        try {
+            const entry = await storeFn({
+                namespace: opts?.namespace ?? defaultNamespace,
+                type: opts?.type ?? 'fact',
+                importance: opts?.importance ?? 'medium',
+                key,
+                value,
+                metadata: opts?.metadata,
+                scopeId: opts?.scopeId ?? defaultScopeId,
+            })
+            setMemories(prev => [...prev, entry])
+            return entry
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e)
+            throw e
+        } finally {
+            setIsLoading(false)
+        }
+    }, [storeFn, defaultNamespace, defaultScopeId])
+
+    const recall = useCallback(async (key: string, namespace?: MemoryNamespace) => {
+        setIsLoading(true)
+        setError(null)
+        try {
+            const results = await searchFn({
+                namespace: namespace ?? defaultNamespace,
+                key,
+                scopeId: defaultScopeId,
+                limit: 1,
+            })
+            return results.length > 0 ? results[0] : null
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e)
+            throw e
+        } finally {
+            setIsLoading(false)
+        }
+    }, [searchFn, defaultNamespace, defaultScopeId])
+
+    const search = useCallback(async (query: MemoryQuery) => {
+        setIsLoading(true)
+        setError(null)
+        try {
+            const results = await searchFn({
+                scopeId: defaultScopeId,
+                ...query,
+            })
+            setMemories(results)
+            return results
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e)
+            throw e
+        } finally {
+            setIsLoading(false)
+        }
+    }, [searchFn, defaultScopeId])
+
+    const remove = useCallback(async (id: string) => {
+        setError(null)
+        try {
+            await deleteFn(id)
+            setMemories(prev => prev.filter(m => m.id !== id))
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e)
+            throw e
+        }
+    }, [deleteFn])
+
+    const clear = useCallback(async (namespace?: MemoryNamespace) => {
+        setError(null)
+        try {
+            await clearFn(namespace ?? defaultNamespace, defaultScopeId)
+            setMemories([])
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e)
+            throw e
+        }
+    }, [clearFn, defaultNamespace, defaultScopeId])
+
+    return { store, recall, search, remove, clear, memories, isLoading, error }
+}

package/packages/react/src/hooks/useModelTest.ts

@@ -0,0 +1,126 @@
+// @geenius-ai/react — src/hooks/useModelTest.ts
+
+/**
+ * Hook for testing AI models with prompts.
+ */
+
+import { useState, useCallback } from 'react'
+import { useAction } from 'convex/react'
+import type { AIGenerationType } from '@geenius-ai/shared'
+
+// Stable no-op for optional Convex action references (React Rules of Hooks)
+const _noop = (() => Promise.resolve(null)) as any
+
+export interface UseModelTestOptions {
+    /** Action reference for text: api.ai.generateText */
+    generateTextAction?: any
+    /** Action reference for image: api.ai.generateImage */
+    generateImageAction?: any
+    /** Action reference for audio: api.ai.generateAudio */
+    generateAudioAction?: any
+    /** Action reference for transcription: api.ai.transcribeAudio */
+    transcribeAudioAction?: any
+    /** Action reference for video: api.ai.generateVideo */
+    generateVideoAction?: any
+}
+
+export interface ModelTestResult {
+    model: string
+    type: AIGenerationType
+    result: string
+    durationMs: number
+    timestamp: number
+    error?: string
+}
+
+export interface UseModelTestReturn {
+    runTest: (model: string, prompt: string, type?: AIGenerationType) => Promise<ModelTestResult>
+    runBatchTest: (models: string[], prompt: string) => Promise<ModelTestResult[]>
+    results: ModelTestResult[]
+    isRunning: boolean
+    clearResults: () => void
+}
+
+export function useModelTest(options: UseModelTestOptions = {}): UseModelTestReturn {
+    const [results, setResults] = useState<ModelTestResult[]>([])
+    const [isRunning, setIsRunning] = useState(false)
+
+    // Always call hooks unconditionally; gate invocations on options presence
+    const textAction = useAction(options.generateTextAction ?? _noop)
+    const imageAction = useAction(options.generateImageAction ?? _noop)
+    const audioAction = useAction(options.generateAudioAction ?? _noop)
+    const transcribeAction = useAction(options.transcribeAudioAction ?? _noop)
+    const videoAction = useAction(options.generateVideoAction ?? _noop)
+
+    const runTest = useCallback(async (
+        model: string,
+        prompt: string,
+        type: AIGenerationType = 'text',
+    ): Promise<ModelTestResult> => {
+        setIsRunning(true)
+        const start = Date.now()
+
+        try {
+            let result = ''
+            switch (type) {
+                case 'text':
+                    if (!options.generateTextAction) throw new Error('generateTextAction not provided')
+                    result = await textAction({
+                        model,
+                        messages: [{ role: 'user', content: prompt }],
+                        caller: 'model-test',
+                    })
+                    break
+                case 'image':
+                    if (!options.generateImageAction) throw new Error('generateImageAction not provided')
+                    result = await imageAction({ prompt, model })
+                    break
+                case 'audio':
+                    if (!options.generateAudioAction) throw new Error('generateAudioAction not provided')
+                    result = await audioAction({ prompt })
+                    break
+                case 'video':
+                    if (!options.generateVideoAction) throw new Error('generateVideoAction not provided')
+                    result = await videoAction({ prompt })
+                    break
+                default:
+                    throw new Error(`Unsupported test type: ${type}`)
+            }
+
+            const testResult: ModelTestResult = {
+                model, type, result, durationMs: Date.now() - start, timestamp: Date.now(),
+            }
+            setResults(prev => [...prev, testResult])
+            return testResult
+        } catch (err) {
+            const testResult: ModelTestResult = {
+                model, type, result: '',
+                durationMs: Date.now() - start,
+                timestamp: Date.now(),
+                error: err instanceof Error ? err.message : 'Test failed',
+            }
+            setResults(prev => [...prev, testResult])
+            return testResult
+        } finally {
+            setIsRunning(false)
+        }
+    }, [textAction, imageAction, audioAction, videoAction])
+
+    const runBatchTest = useCallback(async (
+        models: string[],
+        prompt: string,
+    ): Promise<ModelTestResult[]> => {
+        setIsRunning(true)
+        const batchResults: ModelTestResult[] = []
+        for (const model of models) {
+            const result = await runTest(model, prompt)
+            batchResults.push(result)
+        }
+        setIsRunning(false)
+        return batchResults
+    }, [runTest])
+
+    const clearResults = useCallback(() => setResults([]), [])
+
+    return { runTest, runBatchTest, results, isRunning, clearResults }
+}

package/packages/react/src/hooks/useRealtimeAudio.ts

@@ -0,0 +1,203 @@
+// @geenius-ai/react — src/hooks/useRealtimeAudio.ts
+
+/**
+ * Realtime audio conversation hook — OpenAI Realtime API.
+ * Uses WebSocket for bidirectional audio streaming.
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react'
+import type { AIRealtimeConfig, AIRealtimeEvent } from '@geenius-ai/shared'
+
+export interface UseRealtimeAudioOptions extends AIRealtimeConfig {
+    /** WebSocket URL for the realtime API session */
+    wsUrl?: string
+    /** Gets a session token/URL from your backend */
+    getSessionAction?: any
+    /** Called when AI responds with text */
+    onResponse?: (text: string) => void
+    /** Called when user's speech is transcribed */
+    onTranscript?: (text: string) => void
+    /** Called on any realtime event */
+    onEvent?: (event: AIRealtimeEvent) => void
+}
+
+export interface UseRealtimeAudioReturn {
+    connect: () => Promise<void>
+    disconnect: () => void
+    isConnected: boolean
+    isSpeaking: boolean
+    isListening: boolean
+    error: string | null
+    transcript: string
+    response: string
+    clearError: () => void
+}
+
+export function useRealtimeAudio(options: UseRealtimeAudioOptions): UseRealtimeAudioReturn {
+    const [isConnected, setIsConnected] = useState(false)
+    const [isSpeaking, setIsSpeaking] = useState(false)
+    const [isListening, setIsListening] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+    const [transcript, setTranscript] = useState('')
+    const [response, setResponse] = useState('')
+    const wsRef = useRef<WebSocket | null>(null)
+    const audioContextRef = useRef<AudioContext | null>(null)
+    const streamRef = useRef<MediaStream | null>(null)
+    const processorRef = useRef<ScriptProcessorNode | null>(null)
+
+    const connect = useCallback(async () => {
+        try {
+            setError(null)
+
+            // Get the WebSocket URL from backend if action provided
+            let wsUrl = options.wsUrl ?? 'wss://api.openai.com/v1/realtime'
+            if (options.getSessionAction) {
+                const session = await options.getSessionAction({
+                    model: options.model ?? 'gpt-4o-realtime-preview',
+                    voice: options.voice ?? 'alloy',
+                    instructions: options.instructions,
+                })
+                wsUrl = session.url ?? wsUrl
+            }
+
+            // Connect WebSocket
+            const ws = new WebSocket(wsUrl)
+            wsRef.current = ws
+
+            ws.onopen = () => {
+                setIsConnected(true)
+
+                // Send session config
+                ws.send(JSON.stringify({
+                    type: 'session.update',
+                    session: {
+                        model: options.model ?? 'gpt-4o-realtime-preview',
+                        voice: options.voice ?? 'alloy',
+                        instructions: options.instructions ?? 'You are a helpful assistant.',
+                        input_audio_format: options.inputAudioFormat ?? 'pcm16',
+                        output_audio_format: options.outputAudioFormat ?? 'pcm16',
+                        turn_detection: options.turnDetection ?? {
+                            type: 'server_vad',
+                            threshold: 0.5,
+                            prefix_padding_ms: 300,
+                            silence_duration_ms: 500,
+                        },
+                        tools: options.tools ?? [],
+                    },
+                }))
+
+                // Start capturing microphone audio
+                startAudioCapture(ws)
+            }
+
+            ws.onmessage = (event) => {
+                const data = JSON.parse(event.data) as AIRealtimeEvent
+                options.onEvent?.(data)
+
+                switch (data.type) {
+                    case 'input_audio_buffer.speech_started':
+                        setIsSpeaking(true)
+                        break
+                    case 'input_audio_buffer.speech_stopped':
+                        setIsSpeaking(false)
+                        break
+                    case 'response.text.delta':
+                        setResponse(prev => prev + data.delta)
+                        break
+                    case 'response.text.done':
+                        options.onResponse?.(data.text)
+                        setResponse('')
+                        break
+                    case 'response.audio.delta':
+                        playAudioDelta(data.delta)
+                        break
+                    case 'error':
+                        setError(data.error.message)
+                        break
+                }
+            }
+
+            ws.onerror = () => setError('WebSocket connection error')
+            ws.onclose = () => {
+                setIsConnected(false)
+                setIsListening(false)
+                stopAudioCapture()
+            }
+
+        } catch (err) {
+            setError(err instanceof Error ? err.message : 'Failed to connect')
+        }
+    }, [options])
+
+    const startAudioCapture = useCallback(async (ws: WebSocket) => {
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: { sampleRate: 24000, channelCount: 1 } })
+            streamRef.current = stream
+            const audioCtx = new AudioContext({ sampleRate: 24000 })
+            audioContextRef.current = audioCtx
+            const source = audioCtx.createMediaStreamSource(stream)
+            const processor = audioCtx.createScriptProcessor(4096, 1, 1)
+            processorRef.current = processor
+
+            processor.onaudioprocess = (e) => {
+                if (ws.readyState !== WebSocket.OPEN) return
+                const inputData = e.inputBuffer.getChannelData(0)
+                const pcm16 = new Int16Array(inputData.length)
+                for (let i = 0; i < inputData.length; i++) {
+                    const s = Math.max(-1, Math.min(1, inputData[i]!))
+                    pcm16[i] = s < 0 ? s * 0x8000 : s * 0x7FFF
+                }
+                const bytes = new Uint8Array(pcm16.buffer)
+                let binary = ''
+                for (let i = 0; i < bytes.length; i++) {
+                    binary += String.fromCharCode(bytes[i]!)
+                }
+                ws.send(JSON.stringify({
+                    type: 'input_audio_buffer.append',
+                    audio: btoa(binary),
+                }))
+            }
+
+            source.connect(processor)
+            processor.connect(audioCtx.destination)
+            setIsListening(true)
+        } catch (err) {
+            setError(err instanceof Error ? err.message : 'Microphone access denied')
+        }
+    }, [])
+
+    const stopAudioCapture = useCallback(() => {
+        processorRef.current?.disconnect()
+        processorRef.current = null
+        streamRef.current?.getTracks().forEach(t => t.stop())
+        streamRef.current = null
+        audioContextRef.current?.close()
+        audioContextRef.current = null
+        setIsListening(false)
+    }, [])
+
+    const playAudioDelta = useCallback((_delta: string) => {
+        // In production, queue PCM16 deltas and pipe to AudioWorklet
+        // Simplified: uses browser Audio element with base64 chunks
+        // Full implementation would use AudioContext + AudioWorkletNode
+    }, [])
+
+    const disconnect = useCallback(() => {
+        wsRef.current?.close()
+        wsRef.current = null
+        stopAudioCapture()
+        setIsConnected(false)
+    }, [stopAudioCapture])
+
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => { disconnect() }
+    }, [])
+
+    return {
+        connect, disconnect,
+        isConnected, isSpeaking, isListening,
+        error, transcript, response,
+        clearError: () => setError(null),
+    }
+}

package/packages/react/src/hooks/useSkills.ts

@@ -0,0 +1,114 @@
+// @geenius-ai/react — src/hooks/useSkills.ts
+
+import { useState, useCallback, useMemo } from 'react'
+import type {
+    SkillDefinition,
+    SkillContext,
+    SkillResult,
+    SkillCategory,
+} from '@geenius-ai/shared'
+import { BUILT_IN_SKILLS } from '@geenius-ai/shared'
+
+export interface UseSkillsOptions {
+    /** Convex action to execute a skill */
+    executeFn: (context: SkillContext) => Promise<SkillResult>
+    /** Additional custom skills to register */
+    customSkills?: SkillDefinition[]
+    /** Default model */
+    defaultModel?: string
+    /** User ID for personalization */
+    userId?: string
+}
+
+export interface UseSkillsReturn {
+    /** List all available skills */
+    skills: SkillDefinition[]
+    /** List skills by category */
+    byCategory: (category: SkillCategory) => SkillDefinition[]
+    /** Search skills */
+    search: (query: string) => SkillDefinition[]
+    /** Get a skill by ID */
+    getSkill: (id: string) => SkillDefinition | undefined
+    /** Execute a skill */
+    execute: (skillId: string, params: Record<string, unknown>, context?: Record<string, unknown>) => Promise<SkillResult>
+    /** Last result */
+    result: SkillResult | null
+    /** Loading state */
+    isExecuting: boolean
+    /** Error */
+    error: Error | null
+    /** Reset state */
+    reset: () => void
+}
+
+export function useSkills(options: UseSkillsOptions): UseSkillsReturn {
+    const { executeFn, customSkills = [], defaultModel, userId } = options
+    const [result, setResult] = useState<SkillResult | null>(null)
+    const [isExecuting, setIsExecuting] = useState(false)
+    const [error, setError] = useState<Error | null>(null)
+
+    const allSkills = useMemo(() => {
+        const map = new Map<string, SkillDefinition>()
+        for (const skill of Object.values(BUILT_IN_SKILLS)) map.set(skill.id, skill)
+        for (const skill of customSkills) map.set(skill.id, skill)
+        return Array.from(map.values())
+    }, [customSkills])
+
+    const byCategory = useCallback((category: SkillCategory) =>
+        allSkills.filter(s => s.category === category), [allSkills])
+
+    const searchSkills = useCallback((query: string) => {
+        const q = query.toLowerCase()
+        return allSkills.filter(s =>
+            s.name.toLowerCase().includes(q) ||
+            s.description.toLowerCase().includes(q) ||
+            s.tags?.some(t => t.toLowerCase().includes(q))
+        )
+    }, [allSkills])
+
+    const getSkill = useCallback((id: string) =>
+        allSkills.find(s => s.id === id), [allSkills])
+
+    const execute = useCallback(async (
+        skillId: string,
+        params: Record<string, unknown>,
+        context?: Record<string, unknown>,
+    ) => {
+        setIsExecuting(true)
+        setError(null)
+        try {
+            const res = await executeFn({
+                skillId,
+                params,
+                userId,
+                context,
+                model: defaultModel,
+            })
+            setResult(res)
+            return res
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e)
+            throw e
+        } finally {
+            setIsExecuting(false)
+        }
+    }, [executeFn, userId, defaultModel])
+
+    const reset = useCallback(() => {
+        setResult(null)
+        setError(null)
+    }, [])
+
+    return {
+        skills: allSkills,
+        byCategory,
+        search: searchSkills,
+        getSkill,
+        execute,
+        result,
+        isExecuting,
+        error,
+        reset,
+    }
+}

package/packages/react/src/hooks/useTextToSpeech.ts

@@ -0,0 +1,99 @@
+// @geenius-ai/react — src/hooks/useTextToSpeech.ts
+
+/**
+ * TTS hook — OpenAI TTS, ElevenLabs, etc.
+ */
+
+import { useState, useCallback, useRef } from 'react'
+import { useAction } from 'convex/react'
+
+export interface UseTextToSpeechOptions {
+    generateAudioAction: any
+    defaultVoice?: string
+    defaultModel?: string
+    autoPlay?: boolean
+}
+
+export interface UseTextToSpeechReturn {
+    speak: (text: string, options?: {
+        voice?: string; model?: string; speed?: number
+        voiceSettings?: {
+            stability?: number; similarityBoost?: number; style?: number
+        }
+    }) => Promise<string>
+    stop: () => void
+    isSpeaking: boolean
+    isGenerating: boolean
+    error: string | null
+    audioUrl: string | null
+    clearError: () => void
+}
+
+export function useTextToSpeech(options: UseTextToSpeechOptions): UseTextToSpeechReturn {
+    const [isGenerating, setIsGenerating] = useState(false)
+    const [isSpeaking, setIsSpeaking] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+    const [audioUrl, setAudioUrl] = useState<string | null>(null)
+    const audioRef = useRef<HTMLAudioElement | null>(null)
+    const action = useAction(options.generateAudioAction)
+
+    const speak = useCallback(async (text: string, opts?: {
+        voice?: string; model?: string; speed?: number
+        voiceSettings?: { stability?: number; similarityBoost?: number; style?: number }
+    }) => {
+        setIsGenerating(true)
+        setError(null)
+        try {
+            const base64 = await action({
+                prompt: text,
+                voice: opts?.voice ?? options.defaultVoice ?? 'alloy',
+                model: opts?.model ?? options.defaultModel,
+                speed: opts?.speed,
+                voiceSettings: opts?.voiceSettings,
+            })
+
+            const url = base64.startsWith('http')
+                ? base64
+                : `data:audio/mp3;base64,${base64}`
+
+            setAudioUrl(url)
+
+            // Auto-play if enabled
+            if (options.autoPlay !== false) {
+                if (audioRef.current) {
+                    audioRef.current.pause()
+                }
+                const audio = new Audio(url)
+                audioRef.current = audio
+                setIsSpeaking(true)
+                audio.onended = () => setIsSpeaking(false)
+                audio.onerror = () => {
+                    setIsSpeaking(false)
+                    setError('Audio playback failed')
+                }
+                await audio.play()
+            }
+
+            return url
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : 'TTS generation failed'
+            setError(msg)
+            throw err
+        } finally {
+            setIsGenerating(false)
+        }
+    }, [action, options])
+
+    const stop = useCallback(() => {
+        if (audioRef.current) {
+            audioRef.current.pause()
+            audioRef.current = null
+        }
+        setIsSpeaking(false)
+    }, [])
+
+    return {
+        speak, stop, isSpeaking, isGenerating, error, audioUrl,
+        clearError: () => setError(null),
+    }
+}