@soederpop/luca 0.0.2

package/scripts/examples/using-docker-shell.ts

@@ -0,0 +1,75 @@
+import container from '@soederpop/luca/node'
+
+async function main() {
+	const docker = container.feature('docker', { enable: true, autoRefresh: true })
+
+	// List running containers so we can pick one
+	const containers = await docker.listContainers()
+	console.log('Running containers:', containers.map((c) => `${c.name} (${c.image})`).join(', ') || 'none')
+
+	if (!containers.length) {
+		console.log('\nNo running containers. Starting an alpine container for the demo...')
+		await docker.runContainer('alpine:latest', {
+			name: 'luca-shell-demo',
+			detach: true,
+			command: ['sleep', 'infinity'],
+		})
+		console.log('Started luca-shell-demo')
+	}
+
+	const target = containers[0]?.name || 'luca-shell-demo'
+
+	// --- Basic shell (no volumes) ---
+	console.log(`\n--- Basic shell against "${target}" ---`)
+	const shell = await docker.createShell(target)
+
+	await shell.run('echo "Hello from inside the container"')
+	console.log('stdout:', shell.last!.stdout.trim())
+
+	await shell.run('uname -a')
+	console.log('uname:', shell.last!.stdout.trim())
+
+	await shell.run('ls /')
+	console.log('root listing:', shell.last!.stdout.trim())
+
+	// --- Shell with volume mounts ---
+	// This creates a new helper container from the same image with the mounts applied
+	console.log(`\n--- Shell with volume mount ---`)
+	const mounted = await docker.createShell(target, {
+		volumes: [`${process.cwd()}:/workspace`],
+		workdir: '/workspace',
+	})
+
+	console.log('Helper container:', mounted.containerId)
+
+	await mounted.run('ls -la')
+	console.log('workspace files:\n', mounted.last!.stdout)
+
+	await mounted.run('wc -l package.json')
+	console.log('package.json lines:', mounted.last!.stdout.trim())
+
+	// Write a file from inside the container, visible on the host
+	await mounted.run('echo "written by docker shell" > /workspace/.docker-shell-test')
+	console.log('Wrote .docker-shell-test (exit code:', mounted.last!.exitCode, ')')
+
+	// Clean up the helper container
+	await mounted.destroy()
+	console.log('Helper container destroyed')
+
+	// --- Using execCommand directly with volumes (one-shot) ---
+	console.log(`\n--- One-shot execCommand with volumes ---`)
+	const result = await docker.execCommand(target, ['cat', '/data/package.json'], {
+		volumes: [`${process.cwd()}/package.json:/data/package.json:ro`],
+	})
+	console.log('package.json name:', JSON.parse(result.stdout).name)
+
+	// Clean up demo container if we created it
+	if (!containers.length) {
+		await docker.removeContainer('luca-shell-demo', { force: true })
+		console.log('\nCleaned up luca-shell-demo')
+	}
+
+	console.log('\nDone!')
+}
+
+main().catch(console.error)

package/scripts/examples/using-elevenlabs.ts

@@ -0,0 +1,25 @@
+import container from '@soederpop/luca/node'
+import '../../src/clients/elevenlabs'
+
+async function main() {
+	const phrase = container.argv.phrase || 'Hello! This is a test of the ElevenLabs text to speech client.'
+	const voiceId = container.argv.voice || 'D3LWHMMgiK6AHC5Bl7dE'
+	const outputPath = `/tmp/elevenlabs-${Date.now()}.mp3`
+
+	const el = container.client('elevenlabs')
+	await el.connect()
+
+	console.log('Synthesizing:', phrase)
+	const audio = await el.synthesize(phrase, { voiceId })
+	console.log(`Audio size: ${(audio.length / 1024).toFixed(1)} KB`)
+
+	await container.fs.writeFileAsync(outputPath, audio)
+	console.log(`Saved to: ${outputPath}`)
+
+	console.log('Playing...')
+	const proc = container.feature('proc')
+	await proc.spawnAndCapture('afplay', [outputPath])
+	console.log('Done!')
+}
+
+main().catch(console.error)

package/scripts/examples/using-google-calendar.ts

@@ -0,0 +1,57 @@
+import container from '@soederpop/luca/node'
+
+async function main() {
+	// GoogleAuth reads GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from env.
+	// On first run it opens your browser for OAuth2 consent.
+	// The refresh token is saved in diskCache so subsequent runs skip the browser.
+	const auth = container.feature('googleAuth', {
+		scopes: ['https://www.googleapis.com/auth/calendar.readonly'],
+	})
+
+	const restored = await auth.tryRestoreTokens()
+
+	if (restored) {
+		console.log(`Restored session for ${auth.state.get('email')}`)
+	} else {
+		console.log('No cached credentials found — opening browser for authorization...')
+		await auth.authorize()
+		console.log(`Authorized as ${auth.state.get('email')}`)
+	}
+
+	const calendar = container.feature('googleCalendar', {
+		timeZone: 'America/Chicago',
+	})
+
+	// List accessible calendars
+	const calendars = await calendar.listCalendars()
+	console.log(`\nYou have access to ${calendars.length} calendars:`)
+	for (const cal of calendars) {
+		const tag = cal.primary ? ' (primary)' : ''
+		console.log(`  - ${cal.summary}${tag}`)
+	}
+
+	// Today's events
+	const today = await calendar.getToday()
+	console.log(`\nToday's events (${today.length}):`)
+	for (const event of today) {
+		const time = event.start.dateTime
+			? new Date(event.start.dateTime).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+			: 'All day'
+		console.log(`  ${time}  ${event.summary}`)
+	}
+
+	// Upcoming 7 days
+	const upcoming = await calendar.getUpcoming(7)
+	console.log(`\nNext 7 days (${upcoming.length} events):`)
+	for (const event of upcoming) {
+		const date = event.start.dateTime
+			? new Date(event.start.dateTime).toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' })
+			: event.start.date || ''
+		const time = event.start.dateTime
+			? new Date(event.start.dateTime).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+			: 'All day'
+		console.log(`  ${date}  ${time}  ${event.summary}`)
+	}
+}
+
+main().catch(console.error)

package/scripts/examples/using-google-docs.ts

@@ -0,0 +1,74 @@
+import container from '@soederpop/luca/node'
+
+// Pass a document ID as the first argument, or omit to list available docs.
+// You can find the ID in a Google Docs URL:
+//   https://docs.google.com/document/d/DOCUMENT_ID/edit
+const documentId = process.argv[2]
+
+async function main() {
+	// GoogleAuth reads GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from env.
+	// On first run it opens your browser for OAuth2 consent.
+	// The refresh token is saved in diskCache so subsequent runs skip the browser.
+	const auth = container.feature('googleAuth', {
+		scopes: [
+			'https://www.googleapis.com/auth/documents.readonly',
+			'https://www.googleapis.com/auth/drive.readonly',
+		],
+	})
+
+	const restored = await auth.tryRestoreTokens()
+
+	if (restored) {
+		console.log(`Restored session for ${auth.state.get('email')}`)
+	} else {
+		console.log('No cached credentials found — opening browser for authorization...')
+		await auth.authorize()
+		console.log(`Authorized as ${auth.state.get('email')}`)
+	}
+
+	const docs = container.feature('googleDocs')
+
+	// List recent Google Docs
+	const allDocs = await docs.listDocs()
+	console.log(`\n--- Your Google Docs (${allDocs.length}) ---`)
+	for (const doc of allDocs.slice(0, 15)) {
+		const modified = doc.modifiedTime
+			? new Date(doc.modifiedTime).toLocaleDateString()
+			: ''
+		console.log(`  ${doc.name}  ${modified}`)
+		console.log(`    id: ${doc.id}`)
+	}
+	if (allDocs.length > 15) {
+		console.log(`  ... and ${allDocs.length - 15} more`)
+	}
+
+	// If a document ID was provided, read it
+	if (documentId) {
+		// Plain text
+		const text = await docs.getAsText(documentId)
+		const lines = text.split('\n')
+		console.log(`\n--- Document as Plain Text (first 20 lines) ---`)
+		for (const line of lines.slice(0, 20)) {
+			console.log(`  ${line}`)
+		}
+		if (lines.length > 20) {
+			console.log(`  ... and ${lines.length - 20} more lines`)
+		}
+
+		// Markdown
+		const markdown = await docs.getAsMarkdown(documentId)
+		const mdLines = markdown.split('\n')
+		console.log(`\n--- Document as Markdown (first 30 lines) ---`)
+		for (const line of mdLines.slice(0, 30)) {
+			console.log(`  ${line}`)
+		}
+		if (mdLines.length > 30) {
+			console.log(`  ... and ${mdLines.length - 30} more lines`)
+		}
+	} else {
+		console.log('\nTip: pass a document ID to read its contents:')
+		console.log('  bun run scripts/examples/using-google-docs.ts <document-id>')
+	}
+}
+
+main().catch(console.error)

package/scripts/examples/using-google-drive.ts

@@ -0,0 +1,74 @@
+import container from '@soederpop/luca/node'
+
+async function main() {
+	// GoogleAuth reads GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from env.
+	// On first run it opens your browser for OAuth2 consent.
+	// The refresh token is saved in diskCache so subsequent runs skip the browser.
+	const auth = container.feature('googleAuth', {
+		scopes: ['https://www.googleapis.com/auth/drive.readonly'],
+	})
+
+	const restored = await auth.tryRestoreTokens()
+
+	if (restored) {
+		console.log(`Restored session for ${auth.state.get('email')}`)
+	} else {
+		console.log('No cached credentials found — opening browser for authorization...')
+		await auth.authorize()
+		console.log(`Authorized as ${auth.state.get('email')}`)
+	}
+
+	const drive = container.feature('googleDrive')
+
+	// List recent files
+	const { files: recent } = await drive.listFiles(undefined, { pageSize: 10 })
+	console.log(`\n--- 10 Most Recently Modified Files ---`)
+	for (const file of recent) {
+		const modified = file.modifiedTime
+			? new Date(file.modifiedTime).toLocaleDateString()
+			: ''
+		const size = file.size ? `${(parseInt(file.size) / 1024).toFixed(1)} KB` : ''
+		console.log(`  ${file.name}  ${modified}  ${size}`)
+		console.log(`    type: ${file.mimeType}`)
+	}
+
+	// Browse root folder
+	const root = await drive.browse('root')
+	console.log(`\n--- Root Folder ---`)
+	console.log(`Folders (${root.folders.length}):`)
+	for (const folder of root.folders.slice(0, 10)) {
+		console.log(`  📁 ${folder.name}`)
+	}
+	console.log(`Files (${root.files.length}):`)
+	for (const file of root.files.slice(0, 10)) {
+		console.log(`  📄 ${file.name}  (${file.mimeType})`)
+	}
+
+	// Search for documents
+	const { files: docs } = await drive.search('report', {
+		mimeType: 'application/vnd.google-apps.document',
+		pageSize: 5,
+	})
+	console.log(`\n--- Search: "report" (Google Docs only) ---`)
+	if (docs.length === 0) {
+		console.log('  No matching documents found.')
+	} else {
+		for (const doc of docs) {
+			console.log(`  ${doc.name}`)
+			if (doc.webViewLink) console.log(`    ${doc.webViewLink}`)
+		}
+	}
+
+	// List shared drives
+	const sharedDrives = await drive.listDrives()
+	console.log(`\n--- Shared Drives (${sharedDrives.length}) ---`)
+	if (sharedDrives.length === 0) {
+		console.log('  No shared drives found.')
+	} else {
+		for (const sd of sharedDrives) {
+			console.log(`  ${sd.name}  (${sd.id})`)
+		}
+	}
+}
+
+main().catch(console.error)

package/scripts/examples/using-google-sheets.ts

@@ -0,0 +1,89 @@
+import container from '@soederpop/luca/node'
+
+// Pass a spreadsheet ID as the first argument, or set DEFAULT_SPREADSHEET_ID env var.
+// You can find the ID in a Google Sheets URL:
+//   https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit
+const spreadsheetId = process.argv[2] || process.env.DEFAULT_SPREADSHEET_ID
+
+async function main() {
+	if (!spreadsheetId) {
+		console.error('Usage: bun run scripts/examples/using-google-sheets.ts <spreadsheet-id>')
+		console.error('  or set DEFAULT_SPREADSHEET_ID env var')
+		process.exit(1)
+	}
+
+	// GoogleAuth reads GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from env.
+	// On first run it opens your browser for OAuth2 consent.
+	// The refresh token is saved in diskCache so subsequent runs skip the browser.
+	const auth = container.feature('googleAuth', {
+		scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
+	})
+
+	const restored = await auth.tryRestoreTokens()
+
+	if (restored) {
+		console.log(`Restored session for ${auth.state.get('email')}`)
+	} else {
+		console.log('No cached credentials found — opening browser for authorization...')
+		await auth.authorize()
+		console.log(`Authorized as ${auth.state.get('email')}`)
+	}
+
+	const sheets = container.feature('googleSheets', {
+		defaultSpreadsheetId: spreadsheetId,
+	})
+
+	// Get spreadsheet metadata
+	const meta = await sheets.getSpreadsheet()
+	console.log(`\n--- Spreadsheet: "${meta.title}" ---`)
+	console.log(`Locale: ${meta.locale}`)
+	console.log(`Sheets (${meta.sheets.length}):`)
+	for (const sheet of meta.sheets) {
+		console.log(`  ${sheet.title}  (${sheet.rowCount} rows × ${sheet.columnCount} cols)`)
+	}
+
+	// Read first sheet as JSON (first row = headers)
+	const firstSheet = meta.sheets[0]
+	if (!firstSheet) {
+		console.log('\nNo sheets found in this spreadsheet.')
+		return
+	}
+
+	const data = await sheets.getAsJson(firstSheet.title)
+	console.log(`\n--- "${firstSheet.title}" as JSON (first 5 rows) ---`)
+	if (data.length === 0) {
+		console.log('  (empty or header-only sheet)')
+	} else {
+		const headers = Object.keys(data[0]!)
+		console.log(`  Columns: ${headers.join(', ')}`)
+		for (const row of data.slice(0, 5)) {
+			console.log(`  ${JSON.stringify(row)}`)
+		}
+		if (data.length > 5) {
+			console.log(`  ... and ${data.length - 5} more rows`)
+		}
+	}
+
+	// Read as CSV
+	const csv = await sheets.getAsCsv(firstSheet.title)
+	const csvLines = csv.split('\n')
+	console.log(`\n--- "${firstSheet.title}" as CSV (first 5 lines) ---`)
+	for (const line of csvLines.slice(0, 5)) {
+		console.log(`  ${line}`)
+	}
+	if (csvLines.length > 5) {
+		console.log(`  ... and ${csvLines.length - 5} more lines`)
+	}
+
+	// Read a specific range if there are enough rows
+	if (firstSheet.rowCount >= 2 && firstSheet.columnCount >= 2) {
+		const range = `${firstSheet.title}!A1:B5`
+		const values = await sheets.getRange(range)
+		console.log(`\n--- Range: ${range} ---`)
+		for (const row of values) {
+			console.log(`  ${row.join('\t')}`)
+		}
+	}
+}
+
+main().catch(console.error)

package/scripts/examples/using-nlp.ts

@@ -0,0 +1,55 @@
+import container from '@soederpop/luca/node'
+
+const nlp = container.feature('nlp', { enable: true })
+
+// --- parse(): compromise-powered verb normalization + structure extraction ---
+console.log('=== parse() ===\n')
+
+const commands = [
+	'open the terminal',
+	'draw a diagram of the auth flow',
+	'write something about baseball',
+	'quickly search for recent logs',
+	'deploy the new build to staging',
+]
+
+for (const cmd of commands) {
+	const result = nlp.parse(cmd)
+	console.log(`"${cmd}"`)
+	console.log(`  intent: ${result.intent}, target: ${result.target}, subject: ${result.subject}`)
+	if (result.modifiers.length) console.log(`  modifiers: ${result.modifiers.join(', ')}`)
+	console.log()
+}
+
+// --- analyze(): wink-nlp POS tagging + named entity recognition ---
+console.log('=== analyze() ===\n')
+
+const sentences = [
+	'meet john at 3pm about the deployment',
+	'send the report to sarah by friday',
+	'there are 42 open issues in the repo',
+]
+
+for (const sentence of sentences) {
+	const result = nlp.analyze(sentence)
+	console.log(`"${sentence}"`)
+	console.log(`  tokens: ${result.tokens.map(t => `${t.value}/${t.pos}`).join(' ')}`)
+	if (result.entities.length) {
+		console.log(`  entities: ${result.entities.map(e => `${e.value} (${e.type})`).join(', ')}`)
+	}
+	console.log()
+}
+
+// --- understand(): combined parse + analyze ---
+console.log('=== understand() ===\n')
+
+const utterance = 'create a new project for the dashboard'
+const full = nlp.understand(utterance)
+console.log(`"${utterance}"`)
+console.log(`  intent: ${full.intent}`)
+console.log(`  target: ${full.target}`)
+console.log(`  subject: ${full.subject}`)
+console.log(`  tokens: ${full.tokens.map(t => `${t.value}/${t.pos}`).join(' ')}`)
+if (full.entities.length) {
+	console.log(`  entities: ${full.entities.map(e => `${e.value} (${e.type})`).join(', ')}`)
+}

package/scripts/examples/using-ollama.ts

@@ -0,0 +1,10 @@
+import container from '@soederpop/luca/agi'
+
+const conversation = container.feature('conversation', {
+	local: true,
+	model: "qwen2.5:7b"
+})
+
+const response = await conversation.ask('What model am I using?')
+
+console.log(response)

package/scripts/examples/using-openai-codex.ts

@@ -0,0 +1,23 @@
+import container from '@soederpop/luca/agi'
+
+const codex = container.feature('openaiCodex')
+
+// Stream deltas as they come in
+codex.on('session:delta', ({ text }: any) => process.stdout.write(text))
+codex.on('session:exec', ({ exec }: any) => console.log(`\n[exec] ${exec.command?.join(' ')}`))
+codex.on('session:patch', ({ patch }: any) => console.log(`\n[patch] ${patch.path}`))
+
+async function main() {
+	const session = await codex.run('Explain the purpose of this project in a few sentences.', {
+		fullAuto: true,
+	})
+
+	console.log('\n---')
+	console.log('Status:', session.status)
+	console.log('Result:', session.result)
+	console.log('Turns:', session.turns)
+	console.log('Patches:', session.patches.length)
+	console.log('Execs:', session.executions.length)
+}
+
+main()

package/scripts/examples/using-postgres.ts

@@ -0,0 +1,55 @@
+import container from '@soederpop/luca/node'
+
+const DEFAULT_DATABASE_URL = 'postgresql://postgres:postgres@127.0.0.1:54322/postgres'
+
+type TableRow = {
+  table_schema: string
+  table_name: string
+}
+
+async function main() {
+  const url = process.env.DATABASE_URL || DEFAULT_DATABASE_URL
+  const postgres = container.feature('postgres', { url })
+
+  try {
+    const tables = await withTimeout(
+      postgres.query<TableRow>(
+        `
+        select table_schema, table_name
+        from information_schema.tables
+        where table_type = 'BASE TABLE'
+          and table_schema not in ('pg_catalog', 'information_schema')
+        order by table_schema, table_name
+        `
+      ),
+      8000,
+      `Timed out connecting/querying ${url}`
+    )
+
+    if (tables.length === 0) {
+      console.log('No user tables found.')
+      return
+    }
+
+    console.log(`Found ${tables.length} table(s):`)
+    for (const table of tables) {
+      console.log(`- ${table.table_schema}.${table.table_name}`)
+    }
+  } finally {
+    await withTimeout(postgres.close(), 1000, 'Timed out while closing Postgres connection').catch(() => {})
+  }
+}
+
+main().catch((error) => {
+  console.error('Failed to list Postgres tables:', error)
+  process.exit(1)
+})
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => {
+      setTimeout(() => reject(new Error(message)), timeoutMs)
+    }),
+  ])
+}

package/scripts/examples/using-runpod.ts

@@ -0,0 +1,32 @@
+import container from '@soederpop/luca/node'
+
+async function main() {
+	const runpod = container.feature('runpod')
+
+	// List available GPUs with pricing
+	const gpus = await runpod.listSecureGPUs()
+	console.log('Available GPUs:')
+	console.table(gpus)
+
+	// List RunPod's official templates
+	const templates = await runpod.listTemplates({ includeRunpod: true })
+	console.log('\nAvailable Templates:')
+	for (const t of templates) {
+		console.log(`  ${t.id} - ${t.name} (${t.imageName})`)
+	}
+
+	// Launch a pod from a template on an RTX 4090
+	// const pod = await runpod.createPod({
+	// 	name: 'my-workspace',
+	// 	templateId: templates[0].id,
+	// 	gpuTypeId: 'NVIDIA GeForce RTX 4090',
+	// })
+	// console.log('Created pod:', pod.id)
+
+	// List running pods
+	const pods = await runpod.listPods()
+	console.log('\nRunning Pods:')
+	console.table(pods.map(p => ({ id: p.id, name: p.name, gpu: p.gpu, status: p.status })))
+}
+
+main()

package/scripts/examples/using-tts.ts

@@ -0,0 +1,40 @@
+import container from '@soederpop/luca/node'
+
+async function main() {
+	const tts = container.feature('tts', { enable: true })
+
+	console.log('Available voices:', tts.voices.join(', '))
+	console.log('Output directory:', tts.outputDir)
+	console.log()
+
+	// Synthesize a simple phrase
+	console.log('Synthesizing with default voice (lucy)...')
+	const path1 = await tts.synthesize('Hello! This is a test of the Chatterbox text to speech system.')
+	console.log(`  Saved to: ${path1}`)
+
+	// Try a different voice
+	console.log('\nSynthesizing with voice "ethan"...')
+	const path2 = await tts.synthesize('Good morning. How can I help you today?', { voice: 'ethan' })
+	console.log(`  Saved to: ${path2}`)
+
+	// Listen for events
+	tts.on('synthesized', (text, path, voice, durationMs) => {
+		console.log(`\n[event] synthesized "${text.slice(0, 40)}..." voice=${voice} took=${durationMs}ms`)
+	})
+
+	// Synthesize a longer passage
+	console.log('\nSynthesizing a longer passage with voice "evelyn"...')
+	const path3 = await tts.synthesize(
+		'The quick brown fox jumps over the lazy dog. This sentence contains every letter of the English alphabet, making it a perfect pangram for testing.',
+		{ voice: 'evelyn' }
+	)
+	console.log(`  Saved to: ${path3}`)
+
+	// Play the last file with the system player (macOS)
+	console.log('\nPlaying last generated audio...')
+	const proc = container.feature('proc')
+	await proc.spawnAndCapture('afplay', [path3])
+	console.log('Done!')
+}
+
+main().catch(console.error)

package/scripts/examples/vm-loading-esm-modules.ts

@@ -0,0 +1,16 @@
+import container from '@soederpop/luca/agi'
+
+async function main() {
+	const vm = container.feature('vm')
+	const skillsFile = container.paths.resolve('experts/luca-core-framework/skills.ts')
+	const skills = await container.fs.readFile(skillsFile)
+	const transformedSkills = await container.feature('esbuild').transform(skills.toString(), { format: 'cjs' })
+
+	const mod = { exports: {} as Record<string, any> }
+	await vm.run(transformedSkills.code, { container, module: mod, exports: mod.exports })
+
+	console.log('Loaded skills:', Object.keys(mod.exports))
+	console.log(mod.exports)
+}
+
+main()