nebula-notebook 0.1.0

package/node-server/dist/routes/llm.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * LLM API Routes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.llmService = void 0;
+exports.default = llmRoutes;
+const llm_service_1 = require("../llm/llm-service");
+const llmService = new llm_service_1.LLMService();
+exports.llmService = llmService;
+async function llmRoutes(fastify) {
+    /**
+     * List available LLM providers and models
+     */
+    fastify.get('/llm/providers', async (_request, reply) => {
+        const providers = llmService.getAvailableProviders();
+        return reply.send({ providers });
+    });
+    /**
+     * Generate text/code from LLM
+     */
+    fastify.post('/llm/generate', async (request, reply) => {
+        try {
+            const { prompt, system_prompt, provider = 'google', model = 'gemini-2.5-flash', temperature = 0.2, images, } = request.body;
+            // Check for API key from header
+            const apiKey = request.headers['x-api-key'];
+            const apiProvider = request.headers['x-api-provider'];
+            const response = await llmService.generate({
+                prompt,
+                systemPrompt: system_prompt,
+                config: {
+                    provider: provider,
+                    model,
+                    temperature,
+                    apiKey: apiProvider === provider ? apiKey : undefined,
+                },
+                images: images,
+            });
+            return reply.send({ response });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Generate structured JSON response from LLM
+     */
+    fastify.post('/llm/generate-structured', async (request, reply) => {
+        try {
+            const { prompt, system_prompt, provider = 'google', model = 'gemini-2.5-flash', temperature = 0.2, } = request.body;
+            // Check for API key from header
+            const apiKey = request.headers['x-api-key'];
+            const apiProvider = request.headers['x-api-provider'];
+            const response = await llmService.generateStructured({
+                prompt,
+                systemPrompt: system_prompt,
+                config: {
+                    provider: provider,
+                    model,
+                    temperature,
+                    apiKey: apiProvider === provider ? apiKey : undefined,
+                },
+            });
+            return reply.send({ response });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Chat with LLM including history
+     */
+    fastify.post('/llm/chat', async (request, reply) => {
+        try {
+            const { message, history = [], system_prompt, provider = 'google', model = 'gemini-2.5-flash', temperature = 0.2, images, } = request.body;
+            // Check for API key from header
+            const apiKey = request.headers['x-api-key'];
+            const apiProvider = request.headers['x-api-provider'];
+            // Convert history format
+            const chatHistory = history.map((h) => ({
+                role: h.role,
+                content: h.content,
+            }));
+            const response = await llmService.chat({
+                message,
+                history: chatHistory,
+                systemPrompt: system_prompt,
+                config: {
+                    provider: provider,
+                    model,
+                    temperature,
+                    apiKey: apiProvider === provider ? apiKey : undefined,
+                },
+                images: images,
+            });
+            return reply.send({ response });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+}

package/node-server/dist/routes/notebook.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Notebook API Routes
+ */
+import { FastifyInstance } from 'fastify';
+import { fsService } from '../fs/fs-service';
+import { operationRouter } from '../notebook/operation-router';
+import { HeadlessOperationHandler } from '../notebook/headless-handler';
+declare const headlessHandler: HeadlessOperationHandler;
+export default function notebookRoutes(fastify: FastifyInstance): Promise<void>;
+export { fsService, operationRouter, headlessHandler };

package/node-server/dist/routes/notebook.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * Notebook API Routes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.headlessHandler = exports.operationRouter = exports.fsService = void 0;
+exports.default = notebookRoutes;
+const fs_service_1 = require("../fs/fs-service");
+Object.defineProperty(exports, "fsService", { enumerable: true, get: function () { return fs_service_1.fsService; } });
+const operation_router_1 = require("../notebook/operation-router");
+Object.defineProperty(exports, "operationRouter", { enumerable: true, get: function () { return operation_router_1.operationRouter; } });
+const headless_handler_1 = require("../notebook/headless-handler");
+const kernel_1 = require("./kernel");
+// Initialize headless handler with kernel service for cell execution
+const headlessHandler = new headless_handler_1.HeadlessOperationHandler(fs_service_1.fsService, operation_router_1.operationRouter, kernel_1.kernelService);
+exports.headlessHandler = headlessHandler;
+operation_router_1.operationRouter.setHeadlessHandler(headlessHandler);
+async function notebookRoutes(fastify) {
+    /**
+     * Get cell metadata schema
+     */
+    fastify.get('/cell/metadata-schema', async (_request, reply) => {
+        return reply.send({
+            id: {
+                type: 'string',
+                description: 'Unique cell identifier. Agent-created cells should use human-readable IDs.',
+                agentMutable: true,
+            },
+            type: {
+                type: 'enum',
+                values: ['code', 'markdown'],
+                description: 'Cell type: code for executable cells, markdown for documentation.',
+                agentMutable: true,
+            },
+            scrolled: {
+                type: 'boolean',
+                description: 'Whether cell output is collapsed (Jupyter standard).',
+                agentMutable: true,
+                default: false,
+            },
+            scrolledHeight: {
+                type: 'number',
+                description: 'Height in pixels when output is collapsed.',
+                agentMutable: true,
+            },
+        });
+    });
+    /**
+     * Get notebook cells in internal format
+     */
+    fastify.get('/notebook/cells', async (request, reply) => {
+        try {
+            const filePath = request.query.path;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path query parameter is required' });
+            }
+            const normalizedPath = fs_service_1.fsService.normalizePath(filePath);
+            const result = await fs_service_1.fsService.getNotebookCellsWithKernel(filePath);
+            return reply.send({
+                path: normalizedPath,
+                cells: result.cells,
+                metadata: result.metadata,
+                kernelspec: result.kernelspec,
+                mtime: result.mtime,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes('not found')) {
+                return reply.code(404).send({ detail: err.message });
+            }
+            else {
+                const message = err instanceof Error ? err.message : 'Unknown error';
+                return reply.code(500).send({ detail: message });
+            }
+        }
+    });
+    /**
+     * Save notebook cells
+     */
+    fastify.post('/notebook/save', async (request, reply) => {
+        try {
+            const { path: filePath, cells, kernel_name, history } = request.body;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path is required' });
+            }
+            if (!cells) {
+                return reply.code(400).send({ detail: 'cells is required' });
+            }
+            const result = await fs_service_1.fsService.saveNotebookBundle(filePath, cells, kernel_name, history);
+            return reply.send({ status: 'ok', path: filePath, mtime: result.mtime });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Load operation history for a notebook
+     */
+    fastify.get('/notebook/history', async (request, reply) => {
+        try {
+            const notebookPath = request.query.notebook_path;
+            if (!notebookPath) {
+                return reply.code(400).send({ detail: 'notebook_path query parameter is required' });
+            }
+            const history = fs_service_1.fsService.loadHistory(notebookPath);
+            return reply.send({ notebook_path: notebookPath, history });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Save operation history for a notebook
+     */
+    fastify.post('/notebook/history', async (request, reply) => {
+        try {
+            const { notebook_path, history } = request.body;
+            if (!notebook_path) {
+                return reply.code(400).send({ detail: 'notebook_path is required' });
+            }
+            await fs_service_1.fsService.saveHistory(notebook_path, history || []);
+            return reply.send({ status: 'ok', notebook_path });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Load session state for a notebook
+     */
+    fastify.get('/notebook/session', async (request, reply) => {
+        try {
+            const notebookPath = request.query.notebook_path;
+            if (!notebookPath) {
+                return reply.code(400).send({ detail: 'notebook_path query parameter is required' });
+            }
+            const session = fs_service_1.fsService.loadSession(notebookPath);
+            return reply.send({ notebook_path: notebookPath, session });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Save session state for a notebook
+     */
+    fastify.post('/notebook/session', async (request, reply) => {
+        try {
+            const { notebook_path, session } = request.body;
+            if (!notebook_path) {
+                return reply.code(400).send({ detail: 'notebook_path is required' });
+            }
+            await fs_service_1.fsService.saveSession(notebook_path, session || {});
+            return reply.send({ status: 'ok', notebook_path });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Grant or revoke agent permission to modify a notebook
+     */
+    fastify.post('/notebook/permit-agent', async (request, reply) => {
+        try {
+            const { notebook_path, permitted = true } = request.body;
+            if (!notebook_path) {
+                return reply.code(400).send({ detail: 'notebook_path is required' });
+            }
+            const result = await fs_service_1.fsService.setAgentPermission(notebook_path, permitted);
+            if (!result.success) {
+                return reply.code(400).send({ detail: result.error || 'Failed to update notebook' });
+            }
+            return reply.send({
+                status: 'ok',
+                notebook_path,
+                ...(result.status || fs_service_1.fsService.getAgentPermissionStatus(notebook_path)),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Get agent permission status for a notebook
+     */
+    fastify.get('/notebook/agent-status', async (request, reply) => {
+        try {
+            const filePath = request.query.path;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path query parameter is required' });
+            }
+            const status = fs_service_1.fsService.getAgentPermissionStatus(filePath);
+            return reply.send({
+                notebook_path: filePath,
+                ...status,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Read notebook via operation router
+     *
+     * Supports output truncation for large outputs.
+     * When include_outputs=true (default), outputs are truncated with defaults.
+     *
+     * Uses operation router to get live state from UI if connected,
+     * otherwise reads from file.
+     */
+    fastify.get('/notebook/read', async (request, reply) => {
+        try {
+            const filePath = request.query.path;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path query parameter is required' });
+            }
+            const includeOutputs = request.query.include_outputs !== 'false';
+            const maxLines = request.query.max_lines ? parseInt(request.query.max_lines, 10) : undefined;
+            const maxChars = request.query.max_chars ? parseInt(request.query.max_chars, 10) : undefined;
+            const maxLinesError = request.query.max_lines_error ? parseInt(request.query.max_lines_error, 10) : undefined;
+            const maxCharsError = request.query.max_chars_error ? parseInt(request.query.max_chars_error, 10) : undefined;
+            // Use operation router to get state from UI if connected, otherwise from file
+            const result = await operation_router_1.operationRouter.readNotebook(filePath, includeOutputs, maxLines, maxChars, maxLinesError, maxCharsError);
+            return reply.send(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.send({ success: false, error: message });
+        }
+    });
+    /**
+     * Check if UI is connected for a notebook
+     */
+    fastify.get('/notebook/has-ui', async (request, reply) => {
+        const filePath = request.query.path;
+        if (!filePath) {
+            return reply.code(400).send({ detail: 'path query parameter is required' });
+        }
+        const hasUI = operation_router_1.operationRouter.hasUI(filePath);
+        return reply.send({ hasUI, path: filePath });
+    });
+    /**
+     * Apply a notebook operation
+     *
+     * Routes to UI if connected, otherwise uses headless handler.
+     */
+    fastify.post('/notebook/operation', async (request, reply) => {
+        try {
+            // Python uses {operation: {...}} wrapper via NotebookOperationRequest model
+            const operation = request.body.operation || request.body;
+            if (!operation || !operation.type) {
+                return reply.code(400).send({ detail: 'Operation with type is required' });
+            }
+            const result = await operation_router_1.operationRouter.applyOperation(operation);
+            return reply.send(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.send({ success: false, error: message });
+        }
+    });
+    /**
+     * Get notebook settings (nebula metadata)
+     */
+    fastify.get('/notebook/settings', async (request, reply) => {
+        try {
+            const filePath = request.query.path;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path query parameter is required' });
+            }
+            const metadata = fs_service_1.fsService.getNotebookMetadata(filePath);
+            const nebula = (metadata.nebula || {});
+            return reply.send({
+                notebook_path: filePath,
+                output_logging: nebula.output_logging || 'minimal',
+                full_width: nebula.full_width === true,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Update notebook settings (nebula metadata)
+     */
+    fastify.post('/notebook/settings', async (request, reply) => {
+        try {
+            const { path: filePath, output_logging, full_width } = request.body;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path is required' });
+            }
+            // Validate output_logging value
+            if (output_logging !== undefined && output_logging !== 'minimal' && output_logging !== 'full') {
+                return reply.code(400).send({ detail: 'output_logging must be "minimal" or "full"' });
+            }
+            if (full_width !== undefined && typeof full_width !== 'boolean') {
+                return reply.code(400).send({ detail: 'full_width must be a boolean' });
+            }
+            // Get existing metadata
+            const metadata = fs_service_1.fsService.getNotebookMetadata(filePath);
+            const nebula = (metadata.nebula || {});
+            // Update settings
+            if (output_logging !== undefined) {
+                nebula.output_logging = output_logging;
+            }
+            if (full_width !== undefined) {
+                nebula.full_width = full_width;
+            }
+            // Save back
+            const updateResult = await fs_service_1.fsService.updateNotebookMetadata(filePath, { nebula });
+            if (!updateResult.success) {
+                return reply.code(500).send({ detail: updateResult.error || 'Failed to update notebook metadata' });
+            }
+            return reply.send({
+                status: 'ok',
+                notebook_path: filePath,
+                output_logging: nebula.output_logging || 'minimal',
+                full_width: nebula.full_width === true,
+                mtime: updateResult.mtime,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+}

package/node-server/dist/routes/python.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Python Discovery API Routes
+ */
+import { FastifyInstance } from 'fastify';
+import { PythonDiscoveryService } from '../discovery/discovery-service';
+declare const discoveryService: PythonDiscoveryService;
+export default function pythonRoutes(fastify: FastifyInstance): Promise<void>;
+export { discoveryService };

package/node-server/dist/routes/python.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Python Discovery API Routes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoveryService = void 0;
+exports.default = pythonRoutes;
+const discovery_service_1 = require("../discovery/discovery-service");
+const types_1 = require("../discovery/types");
+const kernelspec_1 = require("../kernel/kernelspec");
+const default_kernel_1 = require("../kernel/default-kernel");
+const server_registry_1 = require("../cluster/server-registry");
+const kernel_1 = require("./kernel");
+const discoveryService = new discovery_service_1.PythonDiscoveryService();
+exports.discoveryService = discoveryService;
+async function pythonRoutes(fastify) {
+    /**
+     * List all discovered Python environments
+     * Transforms to snake_case to match Python API format expected by frontend
+     */
+    fastify.get('/python/environments', async (request, reply) => {
+        try {
+            const refresh = request.query.refresh === 'true';
+            const serverId = request.query.server_id;
+            const localServerId = server_registry_1.serverRegistry.getLocalServerId();
+            if (serverId && serverId !== localServerId && serverId !== 'local') {
+                const server = server_registry_1.serverRegistry.getServer(serverId);
+                if (!server) {
+                    return reply.code(404).send({ detail: `Server not found: ${serverId}` });
+                }
+                if (server.status !== 'online') {
+                    return reply.code(503).send({ detail: `Server is offline: ${serverId}` });
+                }
+                const response = await fetch(`${server.url}/api/python/environments?refresh=${refresh ? 'true' : 'false'}`, {
+                    headers: process.env.NEBULA_CLUSTER_SECRET ? { 'X-Nebula-Cluster-Secret': process.env.NEBULA_CLUSTER_SECRET } : undefined,
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+                    return reply.code(response.status).send({ detail: error.detail || 'Failed to fetch Python environments' });
+                }
+                const data = await response.json();
+                return reply.send(data);
+            }
+            // Get Jupyter kernelspecs and transform to snake_case
+            const kernelspecs = (0, kernelspec_1.discoverKernelSpecs)(refresh).map(k => ({
+                name: k.name,
+                display_name: k.displayName,
+                language: k.language,
+                path: k.path,
+                python_path: k.argv?.[0] || null, // First element of argv is typically the Python executable
+            }));
+            const kernelspecNames = new Set(kernelspecs.map(k => k.name));
+            // Get discovered Python environments
+            const environments = await discoveryService.discover({ forceRefresh: refresh });
+            // Convert to snake_case and match with kernelspecs
+            const envObjects = environments.map(env => ({
+                path: env.path,
+                version: env.version,
+                display_name: env.displayName,
+                env_type: env.envType,
+                env_name: env.envName,
+                has_ipykernel: env.hasIpykernel,
+                externally_managed: env.externallyManaged,
+                install_hint: env.installHint,
+                kernel_name: env.kernelName && kernelspecNames.has(env.kernelName) ? env.kernelName : null,
+            }));
+            return reply.send({
+                kernelspecs,
+                environments: envObjects,
+                cache_info: discoveryService.getCacheInfo(),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+    /**
+     * Install ipykernel and register a Python environment as a Jupyter kernel
+     */
+    fastify.post('/python/install-kernel', async (request, reply) => {
+        try {
+            const { python_path, kernel_name, server_id } = request.body;
+            if (!python_path) {
+                return reply.code(400).send({ detail: 'python_path is required' });
+            }
+            const localServerId = server_registry_1.serverRegistry.getLocalServerId();
+            if (server_id && server_id !== localServerId && server_id !== 'local') {
+                const server = server_registry_1.serverRegistry.getServer(server_id);
+                if (!server) {
+                    return reply.code(404).send({ detail: `Server not found: ${server_id}` });
+                }
+                if (server.status !== 'online') {
+                    return reply.code(503).send({ detail: `Server is offline: ${server_id}` });
+                }
+                const response = await fetch(`${server.url}/api/python/install-kernel`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(process.env.NEBULA_CLUSTER_SECRET ? { 'X-Nebula-Cluster-Secret': process.env.NEBULA_CLUSTER_SECRET } : {}),
+                    },
+                    body: JSON.stringify({ python_path, kernel_name }),
+                });
+                if (!response.ok) {
+                    // Forward the structured error (code + install_hint) so cluster clients
+                    // get the same guidance as a local externally-managed env.
+                    const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+                    return reply.code(response.status).send({
+                        detail: error.detail || 'Failed to install kernel',
+                        code: error.code,
+                        install_hint: error.install_hint,
+                    });
+                }
+                const data = await response.json();
+                return reply.send(data);
+            }
+            const result = await discoveryService.installKernel(python_path, kernel_name);
+            // Invalidate caches so the new kernel is discovered without a restart.
+            (0, kernelspec_1.invalidateKernelspecCache)();
+            (0, default_kernel_1.invalidateDefaultKernelName)();
+            kernel_1.kernelService.refreshKernelSpecs();
+            // snake_case to match the frontend KernelService client contract.
+            return reply.send({
+                kernel_name: result.kernelName,
+                python_path: result.pythonPath,
+                message: result.message,
+            });
+        }
+        catch (err) {
+            // Structured provisioning errors carry a stable code + guidance hint so the
+            // UI can show actionable help instead of a raw traceback.
+            if (err instanceof types_1.KernelProvisionError) {
+                const status = err.code === 'python_not_found' ? 404
+                    : err.code === 'externally_managed' || err.code === 'needs_ipykernel' ? 422
+                        : 500;
+                return reply.code(status).send({ detail: err.message, code: err.code, install_hint: err.installHint });
+            }
+            if (err instanceof Error) {
+                if (err.message.includes('not found') || err.message.includes('ENOENT')) {
+                    return reply.code(404).send({ detail: err.message });
+                }
+                else {
+                    return reply.code(500).send({ detail: err.message });
+                }
+            }
+            else {
+                return reply.code(500).send({ detail: 'Unknown error' });
+            }
+        }
+    });
+    /**
+     * Force refresh the Python environment cache
+     */
+    fastify.post('/python/refresh', async (request, reply) => {
+        try {
+            const serverId = request.query.server_id;
+            const localServerId = server_registry_1.serverRegistry.getLocalServerId();
+            if (serverId && serverId !== localServerId && serverId !== 'local') {
+                const server = server_registry_1.serverRegistry.getServer(serverId);
+                if (!server) {
+                    return reply.code(404).send({ detail: `Server not found: ${serverId}` });
+                }
+                if (server.status !== 'online') {
+                    return reply.code(503).send({ detail: `Server is offline: ${serverId}` });
+                }
+                const response = await fetch(`${server.url}/api/python/refresh`, {
+                    headers: process.env.NEBULA_CLUSTER_SECRET ? { 'X-Nebula-Cluster-Secret': process.env.NEBULA_CLUSTER_SECRET } : undefined,
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+                    return reply.code(response.status).send({ detail: error.detail || 'Failed to refresh Python environments' });
+                }
+                const data = await response.json();
+                return reply.send(data);
+            }
+            const environments = await discoveryService.discover({ forceRefresh: true });
+            return reply.send({
+                count: environments.length,
+                cache_info: discoveryService.getCacheInfo(),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
+}

package/node-server/dist/routes/resources.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resources API Routes
+ *
+ * Provides endpoints for system resource monitoring (RAM, GPU).
+ */
+import { FastifyInstance } from 'fastify';
+export default function resourceRoutes(fastify: FastifyInstance): Promise<void>;