@jupyternaut/persona 0.0.0 → 0.20.0

package/lib/models/settings-model.js

@@ -0,0 +1,356 @@
+import { VDomModel } from '@jupyterlab/ui-components';
+const PLUGIN_ID = '@jupyternaut/persona:settings-model';
+export class AISettingsModel extends VDomModel {
+    _config = {
+        useSecretsManager: true,
+        providers: [],
+        defaultProvider: '',
+        activeCompleterProvider: undefined,
+        useSameProviderForChatAndCompleter: true,
+        contextAwareness: true,
+        codeExecution: false,
+        toolsEnabled: true,
+        showCellDiff: true,
+        showFileDiff: true,
+        diffDisplayMode: 'split',
+        skillsPaths: ['.agents/skills', '_agents/skills'],
+        commandsRequiringApproval: [
+            'notebook:restart-run-all',
+            'notebook:run-cell',
+            'notebook:run-cell-and-select-next',
+            'notebook:run-cell-and-insert-below',
+            'notebook:run-all-cells',
+            'notebook:run-all-above',
+            'notebook:run-all-below',
+            'console:execute',
+            'console:execute-forced',
+            'fileeditor:run-code',
+            'kernelmenu:run',
+            'kernelmenu:restart-and-run-all',
+            'runmenu:run-all',
+            'jupyterlab-ai-commands:run-cell'
+        ],
+        commandsAutoRenderMimeBundles: ['jupyterlab-ai-commands:execute-in-kernel'],
+        trustedMimeTypesForAutoRender: ['text/html'],
+        systemPrompt: `You are Jupyternaut, an AI coding assistant built specifically for the JupyterLab environment.
+
+## Your Core Mission
+You're designed to be a capable partner for data science, research, and development work in Jupyter notebooks. You can help with everything from quick code snippets to complex multi-notebook projects.
+
+## Your Capabilities
+**📁 File & Project Management:**
+- Create, read, edit, and organize files and notebooks in any language
+- Manage project structure and navigate file systems
+- Help with version control and project organization
+
+**📊 Notebook Operations:**
+- Create new notebooks and manage existing ones
+- Add, edit, delete, and run cells (both code and markdown)
+- Help with notebook structure and organization
+- Retrieve and analyze cell outputs and execution results
+
+**⚡ Kernel Management:**
+- Start new kernels with specified language or kernel name
+- Execute code directly in a kernel using jupyterlab-ai-commands execution commands (not console), without creating cells
+- List running kernels and monitor their status
+- Manage kernel lifecycle (start, monitor, shutdown)
+
+**🧠 Coding & Development:**
+- Write, debug, and optimize code in any language supported by Jupyter kernels (Python, R, Julia, JavaScript, C++, and more)
+- Explain complex algorithms and data structures
+- Help with data analysis, visualization, and machine learning
+- Support for libraries and packages across different languages
+- Code reviews and best practices recommendations
+
+**💡 Adaptive Assistance:**
+- Understand context from the user's current work environment
+- Provide suggestions tailored to the user's specific use case
+- Help with both quick fixes and long-term project planning
+
+## How You Work
+You interact with the user's JupyterLab environment primarily through the command system:
+- Use 'discover_commands' to find available JupyterLab commands
+- Use 'execute_command' to perform operations
+- For file and notebook operations, use commands from the jupyterlab-ai-commands extension (prefixed with 'jupyterlab-ai-commands:')
+- These commands provide comprehensive file and notebook manipulation: create, read, edit files/notebooks, manage cells, run code, etc.
+- You can make systematic changes across multiple files and perform complex multi-step operations
+- Skills are available via the skills tools: discover_skills (list) and load_skill (load instructions/resources)
+
+## Tool & Skill Use Policy
+- When tools or skills are available and the task requires actions or environment-specific facts, use them instead of guessing
+- Never guess command IDs. Always use discover_commands with a relevant query before execute_command, unless you already discovered the command earlier in this conversation
+- If a preloaded skills snapshot is provided in the system prompt, use it instead of calling discover_skills to list skills
+- Only call discover_skills if the user explicitly asks for the latest list or you need to verify a skill not in the snapshot
+- When a skill is relevant, call load_skill with the skill name to load instructions; if it returns a non-empty resources array, load each listed resource with load_skill before proceeding
+- If you're unsure how to perform a request, discover relevant commands (discover_commands with task keywords)
+- Use a relevant skill even when the user doesn't explicitly mention it
+- Prefer the single most relevant tool or skill; if multiple could apply, ask a brief clarifying question
+- Ask for missing required inputs before calling a tool or skill
+- Before calling a tool or skill, briefly state why you're calling it, then make the tool call in the same response
+- Never end your response after only announcing what you are about to do: whenever you say you will use a tool or perform an action, the corresponding tool call must be part of that same response
+
+## Code Execution Strategy
+When asked to run code or perform computations, choose the most appropriate approach:
+- **For quick computations or one-off code execution**: Use the kernel execution commands from jupyterlab-ai-commands to run code directly (no notebook/console). Discover these commands first with query 'jupyterlab-ai-commands' and use the returned command IDs. This is ideal for calculations, data lookups, or testing code snippets.
+- **For work that should be saved**: Create or use notebooks when the user needs a persistent record of their work, wants to iterate on code, or is building something they'll return to later.
+
+This means if the user asks you to "calculate the factorial of 100" or "check what library version is installed", run that directly with the jupyterlab-ai-commands kernel execution command rather than creating a new notebook file.
+
+## Notebook State and Cell Identity
+When working with an existing notebook, use the notebook's current structure and kernel state as the source of truth.
+- Before changing notebook content or structure, inspect the notebook and any target cells with the relevant notebook commands you have discovered.
+- If the user may have edited the notebook, or if a previous command could have changed it, refresh your view before continuing rather than relying on earlier results.
+- Treat variables from previously executed cells as part of the active kernel state. When the user asks you to work with existing data or variables, use them by name instead of recreating them unless the user asks you to redefine them or the kernel state is unavailable.
+- Be explicit about the kind of cell reference you are using. A visible execution count (for example In [6]), a notebook position, and an internal cell ID or UUID are different identifiers and may not match.
+- When the user identifies a cell by execution count, relative position, or content, verify the target cell from the current notebook contents before editing it or inserting cells relative to it.
+- For relative insertions, anchor the change to the confirmed target cell rather than to empty placeholder or trailing cells unless the user explicitly refers to those cells.
+
+## Your Approach
+- **Context-aware**: You understand the user is working in a data science/research environment
+- **Practical**: You focus on actionable solutions that work in the user's current setup
+- **Educational**: You explain your reasoning and teach best practices along the way
+- **Collaborative**: You are a pair programming partner, not just a code generator
+
+## Communication Style & Agent Behavior
+IMPORTANT: Follow this message flow pattern for better user experience:
+
+1. FIRST: Explain what you're going to do and your approach
+2. THEN: Execute tools (these will show automatically with step numbers)
+3. FINALLY: Provide a concise summary of what was accomplished
+
+Example flow:
+- "I'll help you create a notebook with example cells. Let me first create the file structure, then add Python and Markdown cells."
+- [Tool executions happen with automatic step display]
+- "Successfully created your notebook with 3 cells: a title, code example, and visualization cell."
+
+Guidelines:
+- Start responses with your plan/approach before tool execution
+- Let the system handle tool execution display (don't duplicate details)
+- End with a brief summary of accomplishments
+- Use natural, conversational tone throughout
+
+- **Conversational**: You maintain a friendly, natural conversation flow throughout the interaction
+- **Progress Updates**: You write brief progress messages between tool uses that appear directly in the conversation
+- **No Filler**: You avoid empty acknowledgments like "Sounds good!" or "Okay, I will..." - you get straight to work
+- **Purposeful Communication**: You start with what you're doing, use tools, then share what you found and what's next
+- **Active Narration**: You actively write progress updates like "Looking at the current code structure..." or "Found the issue in the notebook..." between tool calls
+- **Checkpoint Updates**: After several operations, you summarize what you've accomplished and what remains
+- **Natural Flow**: Your explanations and progress reports appear as normal conversation text, not just in tool blocks
+
+## IMPORTANT: Always write progress messages between tools that explain what you're doing and what you found. These should be conversational updates that help the user follow along with your work.
+
+## Technical Communication
+- Code is formatted in proper markdown blocks with syntax highlighting
+- Mathematical notation uses LaTeX formatting: \\(equations\\) and \\[display math\\]
+- You provide context for your actions and explain your reasoning as you work
+- When creating or modifying multiple files, you give brief summaries of changes
+- You keep users informed of progress while staying focused on the task
+
+## Multi-Step Task Handling
+When users request complex tasks, you use the command system to accomplish them:
+- For file and notebook operations, use discover_commands with query 'jupyterlab-ai-commands' to find the curated set of AI commands (~22 commands)
+- For other JupyterLab operations (terminal, launcher, UI), use specific keywords like 'terminal', 'launcher', etc.
+- IMPORTANT: Always use 'jupyterlab-ai-commands' as the query for file/notebook tasks - this returns a focused set instead of 100+ generic commands
+- For example, to create a notebook with cells:
+  1. discover_commands with query 'jupyterlab-ai-commands' to find available file/notebook commands
+  2. execute_command with 'jupyterlab-ai-commands:create-notebook' and required arguments
+  3. execute_command with 'jupyterlab-ai-commands:add-cell' multiple times to add cells
+  4. execute_command with 'jupyterlab-ai-commands:set-cell-content' to add content to cells
+  5. execute_command with 'jupyterlab-ai-commands:run-cell' when appropriate
+
+## Kernel Preference for Notebooks and Consoles
+When creating notebooks or consoles for a specific programming language, use the 'kernelPreference' argument:
+Only create consoles when the user explicitly asks for one; otherwise prefer the jupyterlab-ai-commands kernel execution commands for running code.
+- To specify by language: { "kernelPreference": { "language": "python" } } or { "kernelPreference": { "language": "julia" } }
+- To specify by kernel name: { "kernelPreference": { "name": "python3" } } or { "kernelPreference": { "name": "julia-1.10" } }
+- Example: execute_command with commandId="notebook:create-new" and args={ "kernelPreference": { "language": "python" } }
+- Example: execute_command with commandId="console:create" and args={ "kernelPreference": { "name": "python3" } }
+- Common kernel names: "python3" (Python), "julia-1.10" (Julia), "ir" (R), "xpython" (xeus-python)
+- If unsure of exact kernel name, prefer using "language" which will match any kernel supporting that language
+
+Always think through multi-step tasks and use commands to fully complete the user's request rather than stopping after just one action.
+
+You are ready to help users build something great!`,
+        // Completion system prompt - also defined in schema/settings-model.json
+        // This serves as a fallback if settings fail to load or are not available
+        completionSystemPrompt: `You are an AI code completion assistant. Complete the given code fragment with appropriate code.
+Rules:
+- Return only the completion text, no explanations or comments
+- Do not include code block markers (\`\`\` or similar)
+- Make completions contextually relevant to the surrounding code and notebook context
+- Follow the language-specific conventions and style guidelines for the detected programming language
+- Keep completions concise but functional
+- Do not repeat the existing code that comes before the cursor
+- Use variables, imports, functions, and other definitions from previous notebook cells when relevant`
+    };
+    _settingRegistry;
+    _settings = null;
+    constructor(options) {
+        super();
+        this._settingRegistry = options.settingRegistry;
+        this._initializeSettings();
+    }
+    async _initializeSettings() {
+        try {
+            this._settings = await this._settingRegistry.load(PLUGIN_ID);
+            this._loadFromSettings();
+            // Listen for settings changes
+            this._settings.changed.connect(this._onSettingsChanged, this);
+            this.stateChanged.emit(void 0);
+        }
+        catch (error) {
+            console.warn('Failed to load JupyterLab settings:', error);
+            this.stateChanged.emit(void 0);
+        }
+    }
+    _onSettingsChanged() {
+        this._loadFromSettings();
+        this.stateChanged.emit(void 0);
+    }
+    _loadFromSettings() {
+        if (!this._settings) {
+            return;
+        }
+        // Merge JupyterLab settings with defaults
+        const settingsData = this._settings.composite;
+        this._config = {
+            ...this._config,
+            ...settingsData
+        };
+    }
+    get config() {
+        return { ...this._config };
+    }
+    get providers() {
+        return [...this._config.providers];
+    }
+    getProvider(id) {
+        return this._config.providers.find(p => p.id === id);
+    }
+    getDefaultProvider() {
+        return this.getProvider(this._config.defaultProvider);
+    }
+    getCompleterProvider() {
+        if (this._config.useSameProviderForChatAndCompleter) {
+            return this.getDefaultProvider();
+        }
+        return this._config.activeCompleterProvider
+            ? this.getProvider(this._config.activeCompleterProvider)
+            : undefined;
+    }
+    async addProvider(providerConfig) {
+        const id = `${providerConfig.provider}-${Date.now()}`;
+        const newProvider = {
+            id,
+            name: providerConfig.name,
+            provider: providerConfig.provider,
+            model: providerConfig.model,
+            apiKey: providerConfig.apiKey,
+            baseURL: providerConfig.baseURL,
+            headers: providerConfig.headers,
+            parameters: providerConfig.parameters,
+            customSettings: providerConfig.customSettings
+        };
+        this._config.providers.push(newProvider);
+        // If this is the first provider, make it active
+        if (this._config.providers.length === 1) {
+            // Save both providers and defaultProvider
+            await this._saveSetting('providers', this._config.providers);
+            this._config.defaultProvider = id;
+            await this._saveSetting('defaultProvider', this._config.defaultProvider);
+        }
+        else {
+            // Only save providers
+            await this._saveSetting('providers', this._config.providers);
+        }
+        return id;
+    }
+    async removeProvider(id) {
+        const index = this._config.providers.findIndex(p => p.id === id);
+        if (index === -1) {
+            return;
+        }
+        this._config.providers.splice(index, 1);
+        await this._saveSetting('providers', this._config.providers);
+        // If this was the active provider, select a new one
+        if (this._config.defaultProvider === id) {
+            this._config.defaultProvider =
+                this._config.providers.length > 0 ? this._config.providers[0].id : '';
+            await this._saveSetting('defaultProvider', this._config.defaultProvider);
+        }
+        if (this._config.activeCompleterProvider === id) {
+            this._config.activeCompleterProvider = undefined;
+            await this._saveSetting('activeCompleterProvider', this._config.activeCompleterProvider);
+        }
+    }
+    async updateProvider(id, updates) {
+        const provider = this.getProvider(id);
+        if (!provider) {
+            return;
+        }
+        Object.assign(provider, updates);
+        Object.keys(provider).forEach(key => {
+            if (key !== 'id' && updates[key] === undefined) {
+                delete provider[key];
+            }
+        });
+        await this._saveSetting('providers', this._config.providers);
+    }
+    async setActiveProvider(id) {
+        if (this.getProvider(id)) {
+            this._config.defaultProvider = id;
+            await this._saveSetting('defaultProvider', this._config.defaultProvider);
+        }
+    }
+    async setActiveCompleterProvider(id) {
+        this._config.activeCompleterProvider = id;
+        await this._saveSetting('activeCompleterProvider', this._config.activeCompleterProvider);
+    }
+    async updateConfig(updates) {
+        // Update config and save only changed settings
+        const promises = [];
+        for (const [key, value] of Object.entries(updates)) {
+            if (key in this._config &&
+                this._config[key] !== value) {
+                this._config[key] = value;
+                promises.push(this._saveSetting(key, value));
+            }
+        }
+        // Wait for all settings to be saved
+        await Promise.all(promises);
+    }
+    /**
+     * Get the API key saved in the settings file for a given provider.
+     *
+     * @param id - the id of the provider.
+     */
+    getApiKey(id) {
+        // First check the active completer provider
+        const activeCompleterProvider = this.getCompleterProvider();
+        if (activeCompleterProvider && activeCompleterProvider.id === id) {
+            return activeCompleterProvider.apiKey || '';
+        }
+        // Fallback to active chat provider
+        const activeProvider = this.getProvider(id);
+        if (activeProvider) {
+            return activeProvider.apiKey || '';
+        }
+        return '';
+    }
+    async _saveSetting(key, value) {
+        try {
+            if (this._settings) {
+                // Only save the specific setting that changed
+                if (value !== undefined) {
+                    await this._settings.set(key, value);
+                }
+                else {
+                    await this._settings.remove(key);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to save setting '${key}' to JupyterLab settings, falling back to localStorage:`, error);
+        }
+    }
+}

package/lib/persona-registry.d.ts

@@ -0,0 +1,15 @@
+import type { IChatModel } from '@jupyter/chat';
+import { IAgentManager } from '@jupyternaut/agent';
+import { ISignal } from '@lumino/signaling';
+import type { IPersona, IPersonaRegistry, IPersonaRegistryOptions } from './tokens';
+export declare class PersonaRegistry implements IPersonaRegistry {
+    constructor(options: IPersonaRegistryOptions);
+    get(model: IChatModel): IPersona | undefined;
+    register(model: IChatModel, agentManager: IAgentManager): void;
+    unregister(model: IChatModel): void;
+    get personaAdded(): ISignal<IPersonaRegistry, IPersona>;
+    private _options;
+    private _personas;
+    private _personaAdded;
+}
+//# sourceMappingURL=persona-registry.d.ts.map

package/lib/persona-registry.js

@@ -0,0 +1,29 @@
+import { Signal } from '@lumino/signaling';
+import { Persona } from './persona';
+export class PersonaRegistry {
+    constructor(options) {
+        this._options = options;
+    }
+    get(model) {
+        return this._personas.get(model);
+    }
+    register(model, agentManager) {
+        const persona = new Persona({
+            model,
+            agentManager,
+            ...this._options
+        });
+        this._personas.set(model, persona);
+        this._personaAdded.emit(persona);
+    }
+    unregister(model) {
+        this.get(model)?.dispose();
+        this._personas.delete(model);
+    }
+    get personaAdded() {
+        return this._personaAdded;
+    }
+    _options;
+    _personas = new Map();
+    _personaAdded = new Signal(this);
+}

package/lib/persona.d.ts

@@ -0,0 +1,66 @@
+import { IChatModel, IUser } from '@jupyter/chat';
+import type { IDocumentManager } from '@jupyterlab/docmanager';
+import type { IAgentManager, IAISettingsModel, IProviderRegistry } from '@jupyternaut/agent';
+import { ISignal } from '@lumino/signaling';
+import type { IPersona } from './tokens';
+/**
+ * Links an IAgentManager to an IChatModel for the Jupyternaut persona.
+ *
+ * Monitors new messages arriving on the chat model and responds when the
+ * persona trigger string is mentioned. The handler and its agent stay alive
+ * as long as the associated chat widget is open, so conversation history is
+ * preserved across multiple mentions.
+ */
+export declare class Persona implements IPersona {
+    constructor(options: Persona.IOptions);
+    dispose(): void;
+    get agentManager(): IAgentManager;
+    get model(): IChatModel;
+    get isBusy(): boolean;
+    get busyChanged(): ISignal<IPersona, boolean>;
+    private _onMessagesUpdated;
+    private _respond;
+    rebuildHistory(): Promise<void>;
+    private _onActiveProviderChanged;
+    private _rebuildHistory;
+    private _onAgentEvent;
+    private _handleMessageStart;
+    private _handleMessageChunk;
+    private _handleMessageComplete;
+    private _handleToolCallStart;
+    private _handleToolCallComplete;
+    private _computeShouldAutoRenderMimeBundles;
+    private _handleToolApprovalRequest;
+    private _handleToolApprovalResolved;
+    private _handleError;
+    private _updateToolCallUI;
+    /**
+     * Whether a mention is required to trigger a response.
+     * When false, the persona responds to all non-bot messages.
+     * Defaults to true.
+     */
+    requireMention: boolean;
+    private readonly _model;
+    private readonly _agent;
+    private readonly _persona;
+    private readonly _settingsModel;
+    private readonly _providerRegistry;
+    private readonly _documentManager;
+    private _respondedToIds;
+    private _currentModelKey;
+    private _busy;
+    private _busyChanged;
+    private _streamingMessage;
+    private _toolContexts;
+}
+export declare namespace Persona {
+    interface IOptions {
+        model: IChatModel;
+        agentManager: IAgentManager;
+        persona: IUser;
+        settingsModel: IAISettingsModel;
+        providerRegistry?: IProviderRegistry;
+        documentManager?: IDocumentManager;
+    }
+}
+//# sourceMappingURL=persona.d.ts.map