luca 2.0.0 → 3.0.0

package/docs/examples/python.md

@@ -0,0 +1,132 @@
+---
+title: "Python"
+tags: [python, scripting, virtualenv, integration]
+lastTested: null
+lastTestPassed: null
+---
+
+# python
+
+Python virtual machine feature for executing Python code, managing environments, and installing dependencies. Automatically detects uv, conda, venv, or system Python.
+
+## Overview
+
+The `python` feature provides a bridge between Luca and the Python ecosystem. It auto-detects the best available Python environment (uv, conda, venv, system), can install project dependencies, and execute Python code with variable injection and local variable capture. Requires Python to be installed on the host.
+
+## Enabling the Feature
+
+```ts
+const python = container.feature('python', { enable: true })
+console.log('Python feature enabled:', python.state.get('enabled'))
+console.log('Python ready:', python.state.get('isReady'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('python')
+console.log(docs)
+```
+
+## Environment Detection
+
+```ts
+const python = container.feature('python')
+await python.detectEnvironment()
+console.log('Environment type:', python.state.get('environmentType'))
+console.log('Python path:', python.state.get('pythonPath'))
+```
+
+## Running Inline Code
+
+Execute Python code directly and capture the output.
+
+```ts skip
+const result = await python.execute('print("Hello from Python!")')
+console.log('stdout:', result.stdout)
+console.log('exit code:', result.exitCode)
+```
+
+You can also pass variables into the Python context and capture locals after execution.
+
+```ts skip
+const result = await python.execute(
+  'greeting = f"Hello {name}, you are {age}!";\nprint(greeting)',
+  { name: 'Alice', age: 30 },
+  { captureLocals: true }
+)
+console.log('stdout:', result.stdout)
+console.log('locals:', result.locals)
+```
+
+The `captureLocals` option serializes all local variables from the script back to JavaScript as JSON.
+
+## Running a Script File
+
+Execute an existing `.py` file and capture its output.
+
+```ts skip
+const result = await python.executeFile('/path/to/analysis.py')
+console.log('stdout:', result.stdout)
+console.log('stderr:', result.stderr)
+```
+
+## Creating a Virtual Environment
+
+Install project dependencies using the auto-detected package manager.
+
+```ts skip
+const python = container.feature('python', {
+  dir: '/path/to/python-project',
+  installCommand: 'pip install -r requirements.txt'
+})
+const result = await python.installDependencies()
+console.log('Install exit code:', result.exitCode)
+```
+
+When no `installCommand` is provided, the feature infers the correct command from the detected environment type (e.g., `uv sync` for uv, `pip install -e .` for venv).
+
+## Persistent Sessions
+
+Start a long-lived Python process where state persists across calls. Ideal for working inside real Python codebases, data analysis, and anything with expensive setup.
+
+```ts skip
+const python = container.feature('python', { dir: '/path/to/python-project' })
+await python.enable()
+await python.startSession()
+
+// State persists across calls
+await python.run('x = 42')
+const result = await python.run('print(x * 2)')
+console.log('stdout:', result.stdout) // '84\n'
+
+// Evaluate expressions and get values back
+const val = await python.eval('x + 1')
+console.log('eval:', val) // 43
+
+// Import project modules (sys.path is set up automatically)
+await python.importModule('json')
+const encoded = await python.call('json.dumps', [{ key: 'value' }], { indent: 2 })
+console.log('call:', encoded)
+
+// Inspect the namespace
+const locals = await python.getLocals()
+console.log('locals:', Object.keys(locals))
+
+// Errors don't crash the session
+const bad = await python.run('raise ValueError("oops")')
+console.log('error:', bad.error) // 'oops'
+
+// Still alive
+const check = await python.run('print("still here")')
+console.log(check.stdout) // 'still here\n'
+
+// Clean up
+await python.stopSession()
+```
+
+See the [Python Sessions tutorial](../tutorials/19-python-sessions.md) for real-world patterns (data pipelines, Django, ML models).
+
+## Summary
+
+The `python` feature bridges Luca and Python by auto-detecting environments, managing dependencies, and providing both stateless execution and persistent sessions. It supports uv, conda, venv, and system Python installations.

package/docs/examples/repl.md

@@ -0,0 +1,93 @@
+---
+title: "REPL"
+tags: [repl, interactive, debugging, console]
+lastTested: null
+lastTestPassed: null
+---
+
+# repl
+
+Interactive read-eval-print loop with tab completion, history, and full container access.
+
+## Overview
+
+The `repl` feature is an on-demand feature that launches an interactive REPL session inside a VM context populated with the container and all its helpers. It supports tab completion for dot-notation property access, command history persistence, and top-level await. Since it is interactive, it cannot run inside a markdown code block -- instead, the typical workflow is to run `luca run somefile.md --console` which executes all code blocks first and then drops into a REPL with the accumulated context.
+
+## Feature Documentation
+
+Let us inspect the feature's built-in documentation.
+
+```ts
+const desc = container.features.describe('repl')
+console.log(desc)
+```
+
+The main method is `start(options?)` which begins the interactive session. It accepts an optional context object and history path.
+
+## Enabling the Feature
+
+We can enable the feature and inspect its state without starting the interactive session.
+
+```ts
+const repl = container.feature('repl', { enable: true })
+console.log('REPL enabled:', repl.state.enabled)
+console.log('REPL started:', repl.state.started)
+```
+
+The feature is enabled but not started. Starting it would block execution waiting for interactive input, which is not suitable for a markdown runner context.
+
+## Configuration Options
+
+The REPL feature accepts several options for customization.
+
+```ts
+const options = {
+  prompt: 'Custom prompt string displayed before each input line',
+  historyPath: 'Path to a file where command history is persisted between sessions',
+  context: 'Additional variables injected into the VM evaluation context',
+}
+for (const [key, desc] of Object.entries(options)) {
+  console.log(`  ${key}: ${desc}`)
+}
+```
+
+When you provide a `context` object to `start()`, those variables become globally available in the REPL session alongside the container and its helpers.
+
+## How to Use the REPL
+
+The recommended way to use the REPL is through the `--console` flag on `luca run`.
+
+```ts
+console.log('Usage patterns:')
+console.log('')
+console.log('  luca run script.md --console')
+console.log('    Run all code blocks, then drop into REPL with accumulated context')
+console.log('')
+console.log('  luca run setup.md --console')
+console.log('    Execute setup code, then explore interactively')
+console.log('')
+console.log('Inside the REPL:')
+console.log('  - Tab completion works on all container properties')
+console.log('  - Top-level await is supported')
+console.log('  - Type .exit or exit to quit')
+```
+
+This is especially powerful when combined with runnable markdown files: you define your setup and data loading in code blocks, then explore the results interactively in the REPL.
+
+## REPL Context
+
+When launched via `--console`, the REPL inherits everything from the markdown execution context. This means all variables, enabled features, and loaded data carry over.
+
+```ts
+console.log('The REPL context automatically includes:')
+const globals = ['container', 'fs', 'git', 'proc', 'grep', 'os', 'networking', 'ui', 'vm', 'esbuild', 'console']
+for (const name of globals) {
+  console.log(`  ${name}`)
+}
+console.log('')
+console.log('Plus any variables defined in preceding code blocks.')
+```
+
+## Summary
+
+This demo covered the `repl` feature, which provides an interactive REPL with tab completion, history, and async support. Since it is interactive by nature, it is best used via `luca run somefile.md --console` to combine scripted setup with interactive exploration. The REPL inherits the full container context plus any variables accumulated during markdown execution.

package/docs/examples/runpod.md

@@ -0,0 +1,119 @@
+---
+title: "RunPod GPU Cloud"
+tags: [runpod, gpu, cloud, pods, ssh, infrastructure]
+lastTested: null
+lastTestPassed: null
+---
+
+# runpod
+
+GPU cloud pod management via the RunPod REST API and CLI. Provision GPU instances, manage network volumes, SSH into pods, and transfer files.
+
+## Overview
+
+Use the `runpod` feature when you need to manage GPU cloud infrastructure. It provides a complete interface for creating and managing RunPod GPU pods, including template selection, volume management, SSH access, file transfers, and lifecycle operations (start, stop, remove). Integrates with the `secureShell` feature for remote command execution.
+
+Requires a `RUNPOD_API_KEY` environment variable or an `apiKey` option.
+
+## Enabling the Feature
+
+```ts
+const runpod = container.feature('runpod', {
+  dataCenterId: 'US-TX-3'
+})
+console.log('RunPod feature created')
+console.log('Data center:', runpod.dataCenterId)
+console.log('API key configured:', !!runpod.apiKey)
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('runpod')
+console.log(info)
+```
+
+## Listing Pods and GPUs
+
+Query your existing pods and available GPU types.
+
+```ts skip
+const pods = await runpod.getpods()
+pods.forEach(p => console.log(`${p.name}: ${p.desiredStatus} - $${p.costPerHr}/hr`))
+
+const gpus = await runpod.listSecureGPUs()
+gpus.forEach(g => console.log(`${g.gpuType}: $${g.ondemandPrice}/hr`))
+```
+
+Use `getpods()` for detailed REST API data including port mappings and public IP, or `listPods()` for a quick summary via the CLI.
+
+## Creating and Managing Pods
+
+Provision a new GPU pod and manage its lifecycle.
+
+```ts skip
+const pod = await runpod.createPod({
+  name: 'my-training-pod',
+  gpuTypeId: 'NVIDIA RTX 4090',
+  templateId: 'abc123',
+  volumeInGb: 50,
+  containerDiskInGb: 50,
+  ports: ['8888/http', '22/tcp']
+})
+console.log(`Pod ${pod.id} created`)
+
+const ready = await runpod.waitForPod(pod.id, 'RUNNING', { timeout: 120000 })
+console.log('Pod is running:', ready.desiredStatus)
+```
+
+After creation, use `waitForPod()` to poll until the pod reaches the desired status.
+
+## Pod Lifecycle
+
+```ts skip
+await runpod.stopPod('pod-abc123')
+console.log('Pod stopped')
+
+await runpod.startPod('pod-abc123')
+console.log('Pod restarted')
+
+await runpod.removePod('pod-abc123')
+console.log('Pod permanently deleted')
+```
+
+Stopping a pod preserves its disk; removing it is permanent.
+
+## SSH and Remote Execution
+
+Connect to a running pod and execute commands remotely.
+
+```ts skip
+const shell = await runpod.getShell('pod-abc123')
+const output = await shell.exec('nvidia-smi')
+console.log(output)
+
+const ls = await shell.exec('ls /workspace')
+console.log('Workspace files:', ls)
+```
+
+The `getShell()` method uses REST API data for reliable SSH connections. Use it over `createRemoteShell()` which depends on the CLI.
+
+## Network Volumes
+
+Manage persistent storage that survives pod restarts.
+
+```ts skip
+const vol = await runpod.createVolume({ name: 'my-models', size: 100 })
+console.log(`Created volume ${vol.id}`)
+
+const volumes = await runpod.listVolumes()
+volumes.forEach(v => console.log(`${v.name}: ${v.size}GB`))
+
+await runpod.removeVolume('vol-abc123')
+```
+
+Attach network volumes to pods via the `networkVolumeId` option in `createPod()`.
+
+## Summary
+
+The `runpod` feature provides complete GPU cloud management. Create pods from templates, manage lifecycle (start/stop/remove), SSH into running pods, and manage network storage volumes. Supports polling for readiness and file transfer operations. Key methods: `createPod()`, `getpods()`, `waitForPod()`, `getShell()`, `listVolumes()`, `createVolume()`.

package/docs/examples/secure-shell.md

@@ -0,0 +1,92 @@
+---
+title: "Secure Shell"
+tags: [secureShell, ssh, scp, remote, deployment]
+lastTested: null
+lastTestPassed: null
+---
+
+# secureShell
+
+SSH command execution and SCP file transfers. Uses the system `ssh` and `scp` binaries to run commands on remote hosts and transfer files securely.
+
+## Overview
+
+The `secureShell` feature provides an SSH client for executing commands on remote machines and transferring files via SCP. It supports both key-based and password-based authentication. All operations require a reachable SSH target host, so the actual connection and command examples use skip blocks.
+
+## Enabling the Feature
+
+```ts
+const ssh = container.feature('secureShell', {
+  host: 'example.com',
+  username: 'deploy',
+  key: '~/.ssh/id_ed25519',
+  enable: true
+})
+console.log('SSH enabled:', ssh.state.get('enabled'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('secureShell')
+console.log(docs)
+```
+
+## Feature Options
+
+```ts
+const ssh = container.feature('secureShell', {
+  host: '192.168.1.100',
+  port: 22,
+  username: 'admin',
+  key: '~/.ssh/id_rsa'
+})
+console.log('Host configured:', ssh.options.host)
+console.log('Port:', ssh.options.port || 22)
+```
+
+## Testing the Connection
+
+Verify that the SSH target is reachable before running commands.
+
+```ts skip
+const ok = await ssh.testConnection()
+console.log('Connection OK:', ok)
+console.log('State connected:', ssh.state.get('connected'))
+```
+
+The `testConnection` method runs a simple echo command on the remote host. If it succeeds, `state.connected` is set to `true`.
+
+## Executing a Remote Command
+
+Run a shell command on the remote host and capture its output.
+
+```ts skip
+const uptime = await ssh.exec('uptime')
+console.log('Remote uptime:', uptime)
+
+const listing = await ssh.exec('ls -la /var/log')
+console.log(listing)
+```
+
+The `exec` method returns the command's stdout as a string. It uses the configured host, username, and authentication credentials.
+
+## Uploading and Downloading Files
+
+Transfer files between the local machine and the remote host using SCP.
+
+```ts skip
+await ssh.upload('./build/app.tar.gz', '/opt/releases/app.tar.gz')
+console.log('Upload complete')
+```
+
+```ts skip
+await ssh.download('/var/log/app.log', './logs/app.log')
+console.log('Download complete')
+```
+
+Both methods use the same authentication credentials configured on the feature instance. Paths on the remote side are absolute or relative to the user's home directory.
+
+## Summary
+
+The `secureShell` feature wraps the system `ssh` and `scp` commands to provide remote command execution and file transfers. It supports key-based and password-based authentication, connection testing, and maintains connection state on the feature instance.

package/docs/examples/sqlite.md

@@ -0,0 +1,86 @@
+---
+title: "SQLite"
+tags: [sqlite, database, sql, storage]
+lastTested: null
+lastTestPassed: null
+---
+
+# sqlite
+
+In-process SQLite database via Bun's native binding. Create tables, insert rows, and query data with parameterized SQL or tagged templates.
+
+## Overview
+
+The `sqlite` feature is on-demand. Pass `{ path: ':memory:' }` for an in-memory database or a file path for persistence. It supports parameterized queries to prevent SQL injection and a convenient tagged-template syntax for inline SQL.
+
+## Creating an In-Memory Database
+
+Enable the feature with an in-memory path. No files are created on disk.
+
+```ts
+const db = container.feature('sqlite', { path: ':memory:' })
+console.log('SQLite enabled:', db.state.get('enabled'))
+```
+
+The database is ready for queries immediately.
+
+## Creating a Table
+
+Use `execute()` for DDL and write statements.
+
+```ts
+await db.execute(`
+  CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT NOT NULL UNIQUE,
+    active INTEGER DEFAULT 1
+  )
+`)
+console.log('Table created')
+```
+
+The `execute()` method returns metadata including the number of changes and the last inserted row ID.
+
+## Inserting Rows
+
+Insert data using parameterized queries to keep values safe.
+
+```ts
+await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['Alice', 'alice@example.com'])
+await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['Bob', 'bob@example.com'])
+const result = await db.execute('INSERT INTO users (name, email, active) VALUES (?, ?, ?)', ['Charlie', 'charlie@example.com', 0])
+console.log('Last insert ID:', result.lastInsertRowid)
+console.log('Changes:', result.changes)
+```
+
+Each `?` placeholder is bound to the corresponding value in the array, preventing SQL injection.
+
+## Querying Rows
+
+Use `query()` for SELECT statements that return result rows.
+
+```ts
+const users = await db.query('SELECT * FROM users WHERE active = ?', [1])
+console.log('Active users:')
+users.forEach(u => console.log(`  ${u.id}: ${u.name} <${u.email}>`))
+```
+
+Results come back as an array of plain objects with column names as keys.
+
+## Tagged Template Queries
+
+The `sql` tagged template lets you write queries with inline interpolation that is still safely parameterized.
+
+```ts
+const emailDomain = '%example.com'
+const rows = await db.sql`SELECT name, email FROM users WHERE email LIKE ${emailDomain}`
+console.log('Users matching domain:')
+rows.forEach(r => console.log(`  ${r.name}: ${r.email}`))
+```
+
+Interpolated values become bound parameters automatically. This combines readability with safety.
+
+## Summary
+
+This demo covered creating an in-memory SQLite database, defining tables, inserting rows with parameterized queries, reading data back, and using the tagged-template SQL syntax. The `sqlite` feature gives you a full relational database with zero setup.

package/docs/examples/structured-output-with-assistants.md

@@ -0,0 +1,144 @@
+---
+title: "Structured Output with Assistants"
+tags: [assistant, conversation, structured-output, zod, openai]
+lastTested: null
+lastTestPassed: null
+---
+
+# Structured Output with Assistants
+
+Get typed, schema-validated JSON responses from OpenAI instead of raw text strings.
+
+## Overview
+
+OpenAI's Structured Outputs feature constrains the model to return JSON that exactly matches a schema you provide. Combined with Zod, this means `ask()` can return parsed objects instead of strings — no regex parsing, no "please respond in JSON", no malformed output.
+
+Pass a `schema` option to `ask()` and the response comes back as a parsed object guaranteed to match your schema.
+
+## Basic: Extract Structured Data
+
+The simplest use case — ask a question and get structured data back.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a helpful data extraction assistant.' }]
+})
+
+const result = await conversation.ask('The founders of Apple are Steve Jobs, Steve Wozniak, and Ronald Wayne. They started it in 1976 in Los Altos, California.', {
+  schema: z.object({
+    company: z.string(),
+    foundedYear: z.number(),
+    location: z.string(),
+    founders: z.array(z.string()),
+  }).describe('CompanyInfo')
+})
+
+console.log('Company:', result.company)
+console.log('Founded:', result.foundedYear)
+console.log('Location:', result.location)
+console.log('Founders:', result.founders)
+```
+
+The `.describe()` on the schema gives OpenAI the schema name — keep it short and descriptive.
+
+## Enums and Categorization
+
+Structured outputs work great for classification tasks where you want the model to pick from a fixed set of values.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a helpful assistant.' }]
+})
+
+const sentiment = await conversation.ask('I absolutely love this product, it changed my life!', {
+  schema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral', 'mixed']),
+    confidence: z.number(),
+    reasoning: z.string(),
+  }).describe('SentimentAnalysis')
+})
+
+console.log('Sentiment:', sentiment.sentiment)
+console.log('Confidence:', sentiment.confidence)
+console.log('Reasoning:', sentiment.reasoning)
+```
+
+Because the model is constrained by the schema, `sentiment` will always be one of the four allowed values.
+
+## Nested Objects and Arrays
+
+Schemas can be as complex as you need. Here we extract a structured analysis with nested objects.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a technical analyst.' }]
+})
+
+const analysis = await conversation.ask(
+  'TypeScript 5.5 introduced inferred type predicates, which automatically narrow types in filter callbacks. It also added isolated declarations for faster builds in monorepos, and a new regex syntax checking feature.',
+  {
+    schema: z.object({
+      subject: z.string(),
+      version: z.string(),
+      features: z.array(z.object({
+        name: z.string(),
+        category: z.enum(['type-system', 'performance', 'developer-experience', 'syntax', 'other']),
+        summary: z.string(),
+      })),
+      featureCount: z.number(),
+    }).describe('ReleaseAnalysis')
+  }
+)
+
+console.log('Subject:', analysis.subject, analysis.version)
+console.log('Features:')
+for (const f of analysis.features) {
+  console.log(`  [${f.category}] ${f.name}: ${f.summary}`)
+}
+console.log('Total features:', analysis.featureCount)
+```
+
+Every level of nesting is validated — the model cannot return a feature without a category or skip required fields.
+
+## With an Assistant
+
+Structured outputs work the same way through the assistant API. The schema passes straight through to the underlying conversation.
+
+```ts
+const { z } = container
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You are a code review assistant. You analyze code snippets and provide structured feedback.',
+  model: 'gpt-4.1-mini',
+})
+
+const review = await assistant.ask(
+  'Review this: function add(a, b) { return a + b }',
+  {
+    schema: z.object({
+      issues: z.array(z.object({
+        severity: z.enum(['info', 'warning', 'error']),
+        message: z.string(),
+      })),
+      suggestion: z.string(),
+      score: z.number(),
+    }).describe('CodeReview')
+  }
+)
+
+console.log('Score:', review.score)
+console.log('Suggestion:', review.suggestion)
+console.log('Issues:')
+for (const issue of review.issues) {
+  console.log(`  [${issue.severity}] ${issue.message}`)
+}
+```
+
+## Summary
+
+This demo covered extracting structured data, classification with enums, nested schema validation, and using structured outputs through both the conversation and assistant APIs. The key is passing a Zod schema via `{ schema }` in the options to `ask()` — OpenAI guarantees the response matches, and you get a parsed object back.