@soederpop/luca 0.0.31 → 0.0.34

package/docs/introspection.md

@@ -7,7 +7,7 @@ Luca's introspection system lets you discover everything about a container and i
 The container knows what it is, what registries it has, and what's available in each one.
 
 ```ts
-const info = container.inspect()
+const info = container.introspect()
 console.log(info.className)
 console.log(info.registries.map(r => `${r.name}: ${r.available.length} available`))
 console.log('factories:', info.factoryNames)
@@ -17,17 +17,17 @@ console.log('enabled features:', info.enabledFeatures)
 You can get the full introspection as markdown:
 
 ```ts
-console.log(container.inspectAsText())
+console.log(container.introspectAsText())
 ```
 
 Or request a single section:
 
 ```ts
-console.log(container.inspectAsText('methods'))
+console.log(container.introspectAsText('methods'))
 ```
 
 ```ts
-console.log(container.inspectAsText('getters'))
+console.log(container.introspectAsText('getters'))
 ```
 
 ## Querying Registries
@@ -60,6 +60,16 @@ console.log(`${allFeatureDocs.length} features documented`)
 console.log(allFeatureDocs[0].slice(0, 200) + '...')
 ```
 
+## Helper Introspection — Quick Discovery
+
+Every helper instance exposes `$methods` and `$getters` for a quick look at what's available:
+
+```ts
+const git = container.feature('git')
+console.log('methods:', git.$methods)
+console.log('getters:', git.$getters)
+```
+
 ## Helper Introspection — Structured Data
 
 Every helper instance (feature, client, server, etc.) can introspect itself. The result is a typed object you can traverse programmatically.
@@ -126,7 +136,7 @@ const git = container.feature('git')
 console.log(git.introspectAsText('methods', 3)) // headings start at ###
 ```
 
-## Inspecting State and Options
+## Introspecting State and Options
 
 Features that declare Zod schemas for state and options expose them through introspection:
 

package/docs/tutorials/00-bootstrap.md

@@ -101,8 +101,8 @@ fs.introspectAsText()
 The container itself is introspectable:
 
 ```js
-container.inspect()          // structured object with all registries, state, events
-container.inspectAsText()    // full markdown overview
+container.introspect()          // structured object with all registries, state, events
+container.introspectAsText()    // full markdown overview
 ```
 
 ## The REPL
@@ -137,7 +137,7 @@ luca eval "grep.search('.', 'TODO')"
 | Structured introspection?      | `feature.introspect()`                 |
 | What state does it have?       | `feature.state.current`               |
 | What events does it emit?      | `feature.introspect().events`          |
-| Full container overview?       | `container.inspectAsText()`            |
+| Full container overview?       | `container.introspectAsText()`            |
 | CLI docs for a helper?         | `luca describe <name>`                 |
 
 ## Gotchas

package/docs/tutorials/02-container.md

@@ -201,10 +201,10 @@ Discover everything about the container at runtime:
 
 ```typescript
 // Structured introspection data
-const info = container.inspect()
+const info = container.introspect()
 
 // Human-readable markdown
-const docs = container.inspectAsText()
+const docs = container.introspectAsText()
 ```
 
 This is what makes Luca especially powerful for AI agents -- they can discover the entire API surface at runtime without reading documentation.

package/docs/tutorials/10-creating-features.md

@@ -187,6 +187,11 @@ Then anyone (human or AI) can discover your feature:
 ```typescript
 container.features.describe('sessionManager')
 // Returns the full markdown documentation extracted from your JSDoc
+
+// Quick discovery — list available methods and getters
+const session = container.feature('sessionManager')
+session.$methods  // => ['createSession', ...]
+session.$getters  // => ['activeCount', ...]
 ```
 
 ## Best Practices

package/docs/tutorials/13-introspection.md

@@ -18,11 +18,11 @@ Introspection serves two audiences:
 
 ```typescript
 // Structured data about the entire container
-const info = container.inspect()
+const info = container.introspect()
 // Returns: registries, enabled features, state schema, available helpers
 
 // Human-readable markdown
-const docs = container.inspectAsText()
+const docs = container.introspectAsText()
 ```
 
 ## Registry-Level Discovery
@@ -73,6 +73,16 @@ const info = fs.introspect()
 const docs = fs.introspectAsText()
 ```
 
+### Quick Discovery with $getters and $methods
+
+Every helper exposes `$getters` and `$methods` — string arrays listing what's available on the instance. Useful for quick exploration without parsing the full introspection object:
+
+```typescript
+const fs = container.feature('fs')
+fs.$methods  // => ['readFile', 'writeFile', 'walk', 'readdir', ...]
+fs.$getters  // => ['cwd', 'sep', ...]
+```
+
 ### What's in the Introspection Data?
 
 - **Class name** and description (from JSDoc)

package/docs/tutorials/19-python-sessions.md

@@ -0,0 +1,401 @@
+---
+title: Working with Python Projects
+tags: [python, sessions, persistent, bridge, codebase, interop, data-science]
+---
+
+# Working with Python Projects
+
+Luca's `python` feature has two modes: **stateless** execution (fire-and-forget, one process per call) and **persistent sessions** (a long-lived Python process that maintains state across calls). This tutorial focuses on sessions — the mode that lets you actually work inside a Python codebase.
+
+## When to Use Sessions
+
+Stateless `execute()` is fine for one-off scripts. But if you need any of these, you want a session:
+
+- **Imports that persist** — load `pandas` once, use it across many calls
+- **State that builds up** — query a database, filter results, then export
+- **Working inside a real project** — import your own modules, call your own functions
+- **Expensive setup** — ML model loading, database connections, API client initialization
+
+## Quick Start
+
+```ts skip
+const python = container.feature('python', { dir: '/path/to/my-python-project' })
+await python.enable()
+await python.startSession()
+
+// Everything below runs in the same Python process.
+// Variables, imports, and state persist across calls.
+
+await python.run('import pandas as pd')
+await python.run('df = pd.read_csv("data/sales.csv")')
+
+const result = await python.run('print(df.shape)')
+console.log(result.stdout) // '(1000, 12)\n'
+
+const total = await python.eval('df["revenue"].sum()')
+console.log('Total revenue:', total)
+
+await python.stopSession()
+```
+
+## Project Directory
+
+The `dir` option tells Luca where the Python project lives. This determines:
+
+1. **sys.path** — the bridge adds the project root (and `src/`, `lib/` if they exist) so your imports work
+2. **Environment detection** — Luca looks for `uv.lock`, `pyproject.toml`, `venv/`, etc. in this directory
+3. **Working directory** — the bridge process runs with `cwd` set to this path
+
+```ts skip
+// Explicit project directory
+const python = container.feature('python', { dir: '/Users/me/projects/my-api' })
+
+// Or defaults to wherever luca was invoked from
+const python = container.feature('python')
+```
+
+If your project uses a `src/` layout (common in modern Python), the bridge automatically adds it to `sys.path`:
+
+```
+my-project/
+  src/
+    myapp/
+      __init__.py
+      models.py
+  pyproject.toml
+```
+
+```ts skip
+await python.startSession()
+// This works because src/ was added to sys.path
+await python.importModule('myapp.models', 'models')
+```
+
+## Session Lifecycle
+
+### Starting
+
+`startSession()` spawns a Python bridge process that talks to Luca over stdin/stdout using a JSON-line protocol. The bridge sets up `sys.path` and signals when it's ready.
+
+```ts skip
+await python.enable()
+await python.startSession()
+
+console.log(python.state.get('sessionActive')) // true
+console.log(python.state.get('sessionId'))     // uuid
+```
+
+### Stopping
+
+`stopSession()` kills the bridge process and cleans up. Any pending requests are rejected.
+
+```ts skip
+await python.stopSession()
+console.log(python.state.get('sessionActive')) // false
+```
+
+### Crash Recovery
+
+If the Python process dies unexpectedly (segfault, killed externally), the feature:
+- Sets `sessionActive` to `false`
+- Rejects all pending requests
+- Emits a `sessionError` event
+
+```ts skip
+python.on('sessionError', ({ error, sessionId }) => {
+  console.error('Python session error:', error)
+  // You could restart: await python.startSession()
+})
+```
+
+## The Session API
+
+### run(code, variables?)
+
+Execute Python code in the persistent namespace. This is the workhorse method.
+
+```ts skip
+// Simple execution
+const result = await python.run('print("hello")')
+// result.ok === true
+// result.stdout === 'hello\n'
+
+// With variable injection
+const result = await python.run('print(f"Processing {count} items")', { count: 42 })
+
+// Errors don't crash the session
+const bad = await python.run('raise ValueError("oops")')
+// bad.ok === false
+// bad.error === 'oops'
+// bad.traceback === 'Traceback (most recent call last):\n...'
+
+// Session still alive after error
+const good = await python.run('print("still here")')
+// good.ok === true
+```
+
+### eval(expression)
+
+Evaluate a Python expression and return its value to JavaScript.
+
+```ts skip
+await python.run('x = [1, 2, 3]')
+const length = await python.eval('len(x)')      // 3
+const doubled = await python.eval('[i*2 for i in x]') // [2, 4, 6]
+```
+
+Values are JSON-serialized. Complex types that can't be serialized come back as their `repr()` string.
+
+### importModule(name, alias?)
+
+Import a module into the session namespace. The alias defaults to the last segment of the module path.
+
+```ts skip
+await python.importModule('json')                    // import json
+await python.importModule('myapp.models', 'models')  // import myapp.models as models
+await python.importModule('os.path')                 // import os.path (available as "path")
+```
+
+### call(funcPath, args?, kwargs?)
+
+Call a function by its dotted path in the namespace.
+
+```ts skip
+await python.importModule('json')
+const encoded = await python.call('json.dumps', [{ a: 1 }], { indent: 2 })
+// '{\n  "a": 1\n}'
+
+// Works with your own functions too
+await python.run('def add(a, b): return a + b')
+const sum = await python.call('add', [3, 4]) // 7
+```
+
+### getLocals()
+
+Inspect everything in the session namespace.
+
+```ts skip
+await python.run('x = 42')
+await python.importModule('json')
+const locals = await python.getLocals()
+// { x: 42, json: '<module ...>' }
+```
+
+### resetSession()
+
+Clear all variables and imports without restarting the process.
+
+```ts skip
+await python.run('big_model = load_model()')
+await python.resetSession()
+// big_model is gone, but the session process is still running
+```
+
+## Real-World Patterns
+
+### Data Analysis Pipeline
+
+```ts skip
+const python = container.feature('python', { dir: '/path/to/analytics' })
+await python.enable()
+await python.startSession()
+
+// Setup
+await python.run('import pandas as pd')
+await python.run('import matplotlib')
+await python.run('matplotlib.use("Agg")')  // headless
+await python.run('import matplotlib.pyplot as plt')
+
+// Load and analyze
+await python.run('df = pd.read_csv("data/events.csv")')
+const shape = await python.eval('list(df.shape)')
+console.log(`Loaded ${shape[0]} rows, ${shape[1]} columns`)
+
+const columns = await python.eval('list(df.columns)')
+console.log('Columns:', columns)
+
+// Filter and aggregate
+await python.run(`
+filtered = df[df["status"] == "completed"]
+summary = filtered.groupby("category")["amount"].agg(["sum", "mean", "count"])
+`)
+
+const summary = await python.eval('summary.to_dict()')
+console.log('Summary:', summary)
+
+// Generate a chart
+await python.run(`
+fig, ax = plt.subplots(figsize=(10, 6))
+summary["sum"].plot(kind="bar", ax=ax)
+ax.set_title("Revenue by Category")
+fig.savefig("output/revenue.png", dpi=150, bbox_inches="tight")
+plt.close(fig)
+`)
+
+await python.stopSession()
+```
+
+### Working with a Django Project
+
+```ts skip
+const python = container.feature('python', { dir: '/path/to/django-project' })
+await python.enable()
+await python.startSession()
+
+// Django requires this before you can import models
+await python.run(`
+import os
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+import django
+django.setup()
+`)
+
+// Now you can work with the ORM
+await python.run('from myapp.models import User, Order')
+
+const userCount = await python.eval('User.objects.count()')
+console.log(`${userCount} users in database`)
+
+const recentOrders = await python.eval(`
+list(Order.objects.filter(status="pending").values("id", "total", "created_at")[:10])
+`)
+console.log('Recent pending orders:', recentOrders)
+
+await python.stopSession()
+```
+
+### ML Model Interaction
+
+```ts skip
+const python = container.feature('python', { dir: '/path/to/ml-project' })
+await python.enable()
+await python.startSession()
+
+// Expensive setup — only happens once
+await python.run(`
+from transformers import pipeline
+classifier = pipeline("sentiment-analysis")
+print("Model loaded")
+`)
+
+// Now you can call it cheaply many times
+async function classify(text: string) {
+  return python.call('classifier', [text])
+}
+
+const results = await Promise.all([
+  classify('I love this product!'),
+  classify('Terrible experience.'),
+  classify('It was okay, nothing special.'),
+])
+
+console.log(results)
+// [
+//   [{ label: 'POSITIVE', score: 0.9998 }],
+//   [{ label: 'NEGATIVE', score: 0.9994 }],
+//   [{ label: 'NEGATIVE', score: 0.7231 }],
+// ]
+
+await python.stopSession()
+```
+
+### Luca Command That Uses Python
+
+```ts skip
+// commands/analyze.ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const positionals = ['target']
+export const argsSchema = CommandOptionsSchema.extend({
+  target: z.string().describe('Path to CSV file to analyze'),
+})
+
+async function handler(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const container = context.container as any
+  const python = container.feature('python')
+  await python.enable()
+  await python.startSession()
+
+  try {
+    await python.run('import pandas as pd')
+    await python.run(`df = pd.read_csv("${options.target}")`)
+
+    const shape = await python.eval('list(df.shape)')
+    const dtypes = await python.eval('dict(df.dtypes.astype(str))')
+    const nulls = await python.eval('dict(df.isnull().sum())')
+
+    console.log(`Rows: ${shape[0]}, Columns: ${shape[1]}`)
+    console.log('Column types:', dtypes)
+    console.log('Null counts:', nulls)
+  } finally {
+    await python.stopSession()
+  }
+}
+
+export default {
+  description: 'Analyze a CSV file using pandas',
+  argsSchema,
+  handler,
+}
+```
+
+```bash
+luca analyze data/sales.csv
+```
+
+## Stateless vs. Session: Choosing the Right Mode
+
+| | `execute()` (stateless) | `run()` (session) |
+|---|---|---|
+| Process | Fresh per call | Shared, long-lived |
+| State | None — each call starts clean | Persists across calls |
+| Imports | Re-imported every time | Imported once, reused |
+| Startup cost | ~50-200ms per call | ~200ms once, then ~1ms per call |
+| Use case | One-off scripts, simple eval | Real projects, data pipelines, REPL-like |
+| Error isolation | Perfect — crash is contained | Errors caught, session survives |
+
+Both modes use the same environment detection (uv, conda, venv, system) and respect the same `dir` and `pythonPath` options.
+
+## Environment Detection
+
+The feature detects Python environments in this order:
+
+1. **Explicit** — `pythonPath` option overrides everything
+2. **uv** — `uv.lock` or `pyproject.toml` present, `uv run python` works
+3. **conda** — `environment.yml` or `conda.yml` present
+4. **venv** — `venv/` or `.venv/` directory with a Python binary inside
+5. **system** — falls back to `python3` or `python` on PATH
+
+```ts skip
+const python = container.feature('python', { dir: '/path/to/project' })
+await python.enable()
+console.log(python.environmentType) // 'uv' | 'conda' | 'venv' | 'system'
+console.log(python.pythonPath)      // e.g. '/Users/me/.local/bin/uv run python'
+```
+
+## Events
+
+The session emits events you can listen to for monitoring and debugging:
+
+```ts skip
+python.on('sessionStarted', ({ sessionId }) => {
+  console.log('Session started:', sessionId)
+})
+
+python.on('sessionStopped', ({ sessionId }) => {
+  console.log('Session stopped:', sessionId)
+})
+
+python.on('sessionError', ({ error, sessionId }) => {
+  console.error('Session error:', error)
+})
+```
+
+## What's Next
+
+- [Creating Features](./10-creating-features.md) — build your own feature that wraps a Python service
+- [Commands](./08-commands.md) — create CLI commands that leverage Python
+- [Servers and Endpoints](./06-servers.md) — expose Python-powered analysis via HTTP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.31",
+  "version": "0.0.34",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",
@@ -34,6 +34,8 @@
     "./container": "./src/container.ts",
     "./client": "./src/client.ts",
     "./clients/*": "./src/clients/*",
+    "./server": "./src/server.ts",
+    "./servers/*": "./src/servers/*",
     "./feature": "./src/feature.ts",
     "./react": "./src/react/index.ts",
     "./introspection": "./src/introspection/index.ts"
@@ -48,13 +50,14 @@
     "clean": "rm -rf dist build package",
     "build:web": "bun run scripts/build-web.ts",
     "build:introspection": "bun run src/cli/cli.ts introspect",
-    "compile": "bun run build:introspection && bun run build:scaffolds && bun run build:bootstrap && bash scripts/stamp-build.sh && bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
+    "compile": "bun run build:introspection && bun run build:scaffolds && bun run build:bootstrap && bun run build:python-bridge && bash scripts/stamp-build.sh && bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build:scaffolds": "bun run src/cli/cli.ts build-scaffolds",
     "build:bootstrap": "bun run src/cli/cli.ts build-bootstrap",
+    "build:python-bridge": "bun run src/cli/cli.ts build-python-bridge",
     "test": "bun test test/*.test.ts",
-    "update-all-docs": "bun run test && bun run build:introspection && bun run src/cli/cli.ts generate-api-docs && bun run build:scaffolds && bun run build:bootstrap",
-    "precommit": "bun run update-all-docs && git add docs/apis/ src/introspection/generated.*.ts src/scaffolds/generated.ts src/bootstrap/generated.ts && bun compile",
+    "update-all-docs": "bun run test && bun run build:introspection && bun run src/cli/cli.ts generate-api-docs && bun run build:scaffolds && bun run build:bootstrap && bun run build:python-bridge",
+    "precommit": "bun run update-all-docs && git add docs/apis/ src/introspection/generated.*.ts src/scaffolds/generated.ts src/bootstrap/generated.ts src/python/generated.ts && bun compile",
     "test:integration": "bun test ./test-integration/"
   },
   "devDependencies": {
@@ -117,6 +120,7 @@
     "inflect": "^0.5.0",
     "ink": "^6.7.0",
     "inquirer": "^9.1.5",
+    "ioredis": "^5.10.1",
     "isomorphic-vm": "^0.0.1",
     "isomorphic-ws": "^5.0.0",
     "js-tiktoken": "^1.0.21",

package/src/agi/container.server.ts

@@ -14,6 +14,8 @@ import { SkillsLibrary } from './features/skills-library'
 import { BrowserUse } from './features/browser-use'
 import { SemanticSearch } from '@soederpop/luca/node/features/semantic-search'
 import { ContentDb } from '@soederpop/luca/node/features/content-db'
+import { FileTools } from './features/file-tools'
+import { LucaCoder } from './features/luca-coder'
 
 import type { ConversationTool } from './features/conversation'
 import type { ZodType } from 'zod'
@@ -28,6 +30,8 @@ export {
 	DocsReader,
 	SkillsLibrary,
 	BrowserUse,
+	FileTools,
+	LucaCoder,
 	SemanticSearch,
 	ContentDb,
 	NodeContainer,
@@ -52,6 +56,8 @@ export interface AGIFeatures extends NodeFeatures {
 	docsReader: typeof DocsReader
 	skillsLibrary: typeof SkillsLibrary
 	browserUse: typeof BrowserUse
+	fileTools: typeof FileTools
+	lucaCoder: typeof LucaCoder
 }
 
 export interface ConversationFactoryOptions {
@@ -125,6 +131,8 @@ const container = new AGIContainer()
 	.use(DocsReader)
 	.use(SkillsLibrary)
 	.use(BrowserUse)
+	.use(FileTools)
+	.use(LucaCoder)
 	.use(SemanticSearch)
 
 container.docs = container.feature('contentDb', {

package/src/agi/features/assistant.ts

@@ -79,6 +79,18 @@ export const AssistantOptionsSchema = FeatureOptionsSchema.extend({
 	/** Maximum number of output tokens per completion */
 
 	maxTokens: z.number().optional().describe('Maximum number of output tokens per completion'),
+	/** Sampling temperature (0-2). Higher = more random, lower = more deterministic. */
+	temperature: z.number().min(0).max(2).optional().describe('Sampling temperature (0-2)'),
+	/** Nucleus sampling cutoff (0-1). */
+	topP: z.number().min(0).max(1).optional().describe('Nucleus sampling cutoff (0-1)'),
+	/** Top-K sampling. Only supported by local/Anthropic models. */
+	topK: z.number().optional().describe('Top-K sampling. Only supported by local/Anthropic models'),
+	/** Frequency penalty (-2 to 2). */
+	frequencyPenalty: z.number().min(-2).max(2).optional().describe('Frequency penalty (-2 to 2)'),
+	/** Presence penalty (-2 to 2). */
+	presencePenalty: z.number().min(-2).max(2).optional().describe('Presence penalty (-2 to 2)'),
+	/** Stop sequences. */
+	stop: z.array(z.string()).optional().describe('Stop sequences'),
 
 	local: z.boolean().default(false).describe('Whether to use our local models for this'),
 
@@ -261,6 +273,12 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 				tools: this.tools,
 				api: 'chat',
 				...(this.options.maxTokens ? { maxTokens: this.options.maxTokens } : {}),
+				...(this.options.temperature != null ? { temperature: this.options.temperature } : {}),
+				...(this.options.topP != null ? { topP: this.options.topP } : {}),
+				...(this.options.topK != null ? { topK: this.options.topK } : {}),
+				...(this.options.frequencyPenalty != null ? { frequencyPenalty: this.options.frequencyPenalty } : {}),
+				...(this.options.presencePenalty != null ? { presencePenalty: this.options.presencePenalty } : {}),
+				...(this.options.stop ? { stop: this.options.stop } : {}),
 				history: [
 					{ role: 'system', content: this.effectiveSystemPrompt },
 				],
@@ -962,6 +980,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	}
 
 	private unbindHooksFromEvents() {
+		if (!this._boundHookListeners) return
 		for (const { event, listener } of this._boundHookListeners) {
 			this.off(event as any, listener)
 		}