@jupyterlite/ai 0.18.0 → 0.19.0

package/lib/providers/provider-registry.d.ts

@@ -1,49 +0,0 @@
-import { ISignal } from '@lumino/signaling';
-import type { LanguageModel } from 'ai';
-import type { IModelOptions } from './models';
-import { IProviderInfo, IProviderRegistry } from '../tokens';
-/**
- * Implementation of the provider registry
- */
-export declare class ProviderRegistry implements IProviderRegistry {
-    /**
-     * Get a copy of all registered providers
-     */
-    get providers(): Record<string, IProviderInfo>;
-    /**
-     * Signal emitted when providers are added or removed
-     */
-    get providersChanged(): ISignal<IProviderRegistry, void>;
-    /**
-     * Register a new provider
-     * @param info Provider information with factories for chat and completion
-     */
-    registerProvider(info: IProviderInfo): void;
-    /**
-     * Get provider information by ID
-     * @param id Provider ID
-     * @returns Provider info or null if not found
-     */
-    getProviderInfo(id: string): IProviderInfo | null;
-    /**
-     * Create a chat model instance using the specified provider
-     * @param id Provider ID
-     * @param options Model configuration options
-     * @returns Chat model instance or null if creation fails
-     */
-    createChatModel(id: string, options: IModelOptions): LanguageModel | null;
-    /**
-     * Create a completion model instance using the specified provider
-     * @param id Provider ID
-     * @param options Model configuration options
-     * @returns Language model instance or null if creation fails
-     */
-    createCompletionModel(id: string, options: IModelOptions): LanguageModel | null;
-    /**
-     * Get list of all available provider IDs
-     * @returns Array of provider IDs
-     */
-    getAvailableProviders(): string[];
-    private _providers;
-    private _providersChanged;
-}

package/lib/providers/provider-registry.js

@@ -1,72 +0,0 @@
-import { Signal } from '@lumino/signaling';
-/**
- * Implementation of the provider registry
- */
-export class ProviderRegistry {
-    /**
-     * Get a copy of all registered providers
-     */
-    get providers() {
-        return { ...this._providers };
-    }
-    /**
-     * Signal emitted when providers are added or removed
-     */
-    get providersChanged() {
-        return this._providersChanged;
-    }
-    /**
-     * Register a new provider
-     * @param info Provider information with factories for chat and completion
-     */
-    registerProvider(info) {
-        if (info.id in this._providers) {
-            throw new Error(`Provider with id "${info.id}" is already registered`);
-        }
-        this._providers[info.id] = { ...info };
-        this._providersChanged.emit();
-    }
-    /**
-     * Get provider information by ID
-     * @param id Provider ID
-     * @returns Provider info or null if not found
-     */
-    getProviderInfo(id) {
-        return this._providers[id] || null;
-    }
-    /**
-     * Create a chat model instance using the specified provider
-     * @param id Provider ID
-     * @param options Model configuration options
-     * @returns Chat model instance or null if creation fails
-     */
-    createChatModel(id, options) {
-        const provider = this._providers[id];
-        if (!provider) {
-            return null;
-        }
-        return provider.factory(options);
-    }
-    /**
-     * Create a completion model instance using the specified provider
-     * @param id Provider ID
-     * @param options Model configuration options
-     * @returns Language model instance or null if creation fails
-     */
-    createCompletionModel(id, options) {
-        const provider = this._providers[id];
-        if (!provider) {
-            return null;
-        }
-        return provider.factory(options);
-    }
-    /**
-     * Get list of all available provider IDs
-     * @returns Array of provider IDs
-     */
-    getAvailableProviders() {
-        return Object.keys(this._providers);
-    }
-    _providers = {};
-    _providersChanged = new Signal(this);
-}

package/lib/providers/provider-tools.d.ts

@@ -1,36 +0,0 @@
-import type { Tool } from 'ai';
-import type { IProviderInfo } from '../tokens';
-type ToolMap = Record<string, Tool>;
-interface IWebSearchSettings {
-    enabled?: boolean;
-    externalWebAccess?: boolean;
-    searchContextSize?: 'low' | 'medium' | 'high';
-    allowedDomains?: string[];
-    blockedDomains?: string[];
-    maxUses?: number;
-}
-interface IWebFetchSettings {
-    enabled?: boolean;
-    maxUses?: number;
-    maxContentTokens?: number;
-    allowedDomains?: string[];
-    blockedDomains?: string[];
-    citationsEnabled?: boolean;
-}
-/**
- * Provider-level custom settings that control built-in web tools.
- */
-export interface IProviderCustomSettings {
-    webSearch?: IWebSearchSettings;
-    webFetch?: IWebFetchSettings;
-}
-interface IProviderToolContext {
-    providerInfo?: IProviderInfo | null;
-    customSettings?: IProviderCustomSettings;
-    hasFunctionTools: boolean;
-}
-/**
- * Create provider-defined tools from custom settings and provider capabilities.
- */
-export declare function createProviderTools(options: IProviderToolContext): ToolMap;
-export {};

package/lib/providers/provider-tools.js

@@ -1,93 +0,0 @@
-import { anthropic } from '@ai-sdk/anthropic';
-import { openai } from '@ai-sdk/openai';
-const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES = 2;
-const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS = 12000;
-function normalizeDomain(value) {
-    const normalized = (value || '').trim().toLowerCase();
-    const withoutProtocol = normalized.replace(/^https?:\/\//, '');
-    const hostname = withoutProtocol.split('/')[0].trim();
-    // Treat "*.example.com" as "example.com" for provider domain filters.
-    return hostname.startsWith('*.') ? hostname.slice(2) : hostname;
-}
-function collectDomains(value) {
-    value = value || [];
-    const values = Array.from(new Set(value.map(normalizeDomain).filter(domain => domain.length > 0)));
-    return values;
-}
-function createOpenAIWebSearchTool(webSearchSettings) {
-    const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
-    return openai.tools.webSearch({
-        externalWebAccess: webSearchSettings.externalWebAccess,
-        searchContextSize: webSearchSettings.searchContextSize,
-        filters: allowedDomains.length > 0 ? { allowedDomains } : undefined
-    });
-}
-function createAnthropicWebSearchTool(webSearchSettings) {
-    const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
-    const blockedDomains = collectDomains(webSearchSettings.blockedDomains);
-    return anthropic.tools.webSearch_20250305({
-        maxUses: webSearchSettings.maxUses,
-        allowedDomains: allowedDomains.length > 0 ? allowedDomains : undefined,
-        blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined
-    });
-}
-function createAnthropicWebFetchTool(webFetchSettings) {
-    const maxUses = webFetchSettings.maxUses ?? DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES;
-    const maxContentTokens = webFetchSettings.maxContentTokens ??
-        DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS;
-    const allowedDomains = collectDomains(webFetchSettings.allowedDomains);
-    const blockedDomains = collectDomains(webFetchSettings.blockedDomains);
-    const citationsEnabled = webFetchSettings.citationsEnabled;
-    return anthropic.tools.webFetch_20250910({
-        maxUses,
-        maxContentTokens,
-        allowedDomains: allowedDomains.length > 0 ? allowedDomains : undefined,
-        blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined,
-        citations: citationsEnabled !== undefined ? { enabled: citationsEnabled } : undefined
-    });
-}
-function createWebSearchTool(implementation, webSearchSettings) {
-    switch (implementation) {
-        case 'openai':
-            return createOpenAIWebSearchTool(webSearchSettings);
-        case 'anthropic':
-            return createAnthropicWebSearchTool(webSearchSettings);
-        default:
-            throw new Error(`Unsupported web search implementation: ${implementation}`);
-    }
-}
-function createWebFetchTool(implementation, webFetchSettings) {
-    switch (implementation) {
-        case 'anthropic':
-            return createAnthropicWebFetchTool(webFetchSettings);
-        default:
-            throw new Error(`Unsupported web fetch implementation: ${implementation}`);
-    }
-}
-/**
- * Create provider-defined tools from custom settings and provider capabilities.
- */
-export function createProviderTools(options) {
-    const tools = {};
-    if (!options.customSettings ||
-        !options.providerInfo?.providerToolCapabilities) {
-        return tools;
-    }
-    const capabilities = options.providerInfo.providerToolCapabilities;
-    const webSearchSettings = options.customSettings.webSearch;
-    const webFetchSettings = options.customSettings.webFetch;
-    const webSearchEnabled = webSearchSettings?.enabled === true;
-    const webFetchEnabled = webFetchSettings?.enabled === true;
-    const webSearchCapability = capabilities.webSearch;
-    if (webSearchEnabled && webSearchSettings && webSearchCapability) {
-        const requiresNoFunctionTools = webSearchCapability.requiresNoFunctionTools === true;
-        if (!requiresNoFunctionTools || !options.hasFunctionTools) {
-            tools.web_search = createWebSearchTool(webSearchCapability.implementation, webSearchSettings);
-        }
-    }
-    const webFetchCapability = capabilities.webFetch;
-    if (webFetchEnabled && webFetchSettings && webFetchCapability) {
-        tools.web_fetch = createWebFetchTool(webFetchCapability.implementation, webFetchSettings);
-    }
-    return tools;
-}

package/lib/skills/index.d.ts

@@ -1,4 +0,0 @@
-export { parseSkillMd, type IParsedSkill } from './parse-skill';
-export { loadSkillsFromPaths, type ISkillFileDefinition } from './skill-loader';
-export type { ISkillDefinition, ISkillRegistration, ISkillResourceResult, ISkillSummary } from './types';
-export { SkillRegistry } from './skill-registry';

package/lib/skills/index.js

@@ -1,7 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-export { parseSkillMd } from './parse-skill';
-export { loadSkillsFromPaths } from './skill-loader';
-export { SkillRegistry } from './skill-registry';

package/lib/skills/parse-skill.d.ts

@@ -1,25 +0,0 @@
-/**
- * Parsed skill definition from a SKILL.md file.
- */
-export interface IParsedSkill {
-    name: string;
-    description: string;
-    instructions: string;
-}
-/**
- * Parse a SKILL.md file content into a structured skill definition.
- *
- * Expected format:
- * ```
- * ---
- * name: my-skill
- * description: A brief description of the skill
- * ---
- * Full instructions body here...
- * ```
- *
- * @param content - The raw content of a SKILL.md file
- * @returns Parsed skill with name, description, and instructions
- * @throws Error if the frontmatter is missing or invalid
- */
-export declare function parseSkillMd(content: string): IParsedSkill;

package/lib/skills/parse-skill.js

@@ -1,69 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-import { parse as parseYaml } from 'yaml';
-/**
- * Parse a SKILL.md file content into a structured skill definition.
- *
- * Expected format:
- * ```
- * ---
- * name: my-skill
- * description: A brief description of the skill
- * ---
- * Full instructions body here...
- * ```
- *
- * @param content - The raw content of a SKILL.md file
- * @returns Parsed skill with name, description, and instructions
- * @throws Error if the frontmatter is missing or invalid
- */
-export function parseSkillMd(content) {
-    const normalizedContent = content
-        .replace(/^\uFEFF/, '')
-        .replace(/\r\n/g, '\n');
-    const lines = normalizedContent.split('\n');
-    if (lines[0]?.trim() !== '---') {
-        throw new Error('Invalid SKILL.md: missing frontmatter delimiters (---)');
-    }
-    const frontmatterLines = [];
-    let i = 1;
-    for (; i < lines.length; i++) {
-        const line = lines[i];
-        const trimmed = line.trim();
-        if (trimmed === '---') {
-            break;
-        }
-        frontmatterLines.push(line);
-    }
-    if (i >= lines.length) {
-        throw new Error('Invalid SKILL.md: missing frontmatter delimiters (---)');
-    }
-    const frontmatter = frontmatterLines.join('\n');
-    const instructions = lines
-        .slice(i + 1)
-        .join('\n')
-        .trim();
-    let metadata;
-    try {
-        metadata = parseYaml(frontmatter);
-    }
-    catch (error) {
-        throw new Error(`Invalid SKILL.md: YAML frontmatter parse failed: ${error}`);
-    }
-    const data = metadata;
-    const name = data?.name;
-    const description = data?.description;
-    if (typeof name !== 'string' || name.trim().length === 0) {
-        throw new Error('Invalid SKILL.md: missing "name" in frontmatter');
-    }
-    if (typeof description !== 'string' || description.trim().length === 0) {
-        throw new Error('Invalid SKILL.md: missing "description" in frontmatter');
-    }
-    return {
-        name: name.trim(),
-        description: description.trim(),
-        instructions
-    };
-}

package/lib/skills/skill-loader.d.ts

@@ -1,25 +0,0 @@
-import { Contents } from '@jupyterlab/services';
-import { IParsedSkill } from './parse-skill';
-/**
- * A skill definition loaded from the filesystem.
- */
-export interface ISkillFileDefinition extends IParsedSkill {
-    /**
-     * Path to the skill directory (e.g. ".agents/skills/my-skill").
-     */
-    path: string;
-    /**
-     * Paths to resource files relative to the skill directory.
-     */
-    resources: string[];
-}
-/**
- * Load skills from multiple directories. Each path is scanned in order;
- * when the same skill name appears in more than one path, the first
- * occurrence wins.
- *
- * @param contentsManager - The Jupyter contents manager
- * @param skillsPaths - Ordered list of directories to scan
- * @returns Merged array of loaded skill definitions
- */
-export declare function loadSkillsFromPaths(contentsManager: Contents.IManager, skillsPaths: string[]): Promise<ISkillFileDefinition[]>;

package/lib/skills/skill-loader.js

@@ -1,133 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-import { PathExt } from '@jupyterlab/coreutils';
-import { parseSkillMd } from './parse-skill';
-/**
- * Load skills from multiple directories. Each path is scanned in order;
- * when the same skill name appears in more than one path, the first
- * occurrence wins.
- *
- * @param contentsManager - The Jupyter contents manager
- * @param skillsPaths - Ordered list of directories to scan
- * @returns Merged array of loaded skill definitions
- */
-export async function loadSkillsFromPaths(contentsManager, skillsPaths) {
-    const seen = new Set();
-    const merged = [];
-    for (const skillsPath of skillsPaths) {
-        const skills = await loadSkills(contentsManager, skillsPath);
-        for (const skill of skills) {
-            if (seen.has(skill.name)) {
-                console.debug(`Skipping duplicate skill "${skill.name}" from "${skillsPath}" (already loaded from an earlier path).`);
-                continue;
-            }
-            seen.add(skill.name);
-            merged.push(skill);
-        }
-    }
-    return merged;
-}
-/**
- * Load skills from the filesystem by scanning a directory for subdirectories
- * containing SKILL.md files.
- *
- * @param contentsManager - The Jupyter contents manager
- * @param skillsPath - Path to the skills directory (e.g. ".agents/skills")
- * @returns Array of loaded skill definitions
- */
-async function loadSkills(contentsManager, skillsPath) {
-    const skills = [];
-    // Walk each path segment from root to verify the directory exists before fetching it.
-    const segments = skillsPath.split('/').filter(s => s.length > 0);
-    let currentPath = '';
-    for (const segment of segments) {
-        let listing;
-        try {
-            listing = await contentsManager.get(currentPath, { content: true });
-        }
-        catch (error) {
-            console.debug(`Skills path segment not found at "${currentPath}":`, error);
-            return skills;
-        }
-        const children = (listing.content ?? []);
-        if (!children.some(c => c.type === 'directory' && c.name === segment)) {
-            return skills;
-        }
-        currentPath = PathExt.join(currentPath, segment);
-    }
-    const dirModel = await contentsManager.get(skillsPath, { content: true });
-    if (dirModel.type !== 'directory' || !dirModel.content) {
-        return skills;
-    }
-    for (const child of dirModel.content) {
-        if (child.type !== 'directory') {
-            continue;
-        }
-        // List the subdirectory to check if SKILL.md exists before requesting it
-        const subDir = await contentsManager.get(child.path, { content: true });
-        const subChildren = (subDir.content ?? []);
-        if (!subChildren.some(f => f.type === 'file' && f.name === 'SKILL.md')) {
-            continue;
-        }
-        const skillMdPath = `${child.path}/SKILL.md`;
-        const fileModel = await contentsManager.get(skillMdPath, {
-            content: true
-        });
-        if (typeof fileModel.content !== 'string') {
-            console.warn(`Skipping ${skillMdPath}: content is not a string`);
-            continue;
-        }
-        try {
-            const parsed = parseSkillMd(fileModel.content);
-            const resources = await collectResourcePaths(contentsManager, child.path);
-            skills.push({
-                ...parsed,
-                path: child.path,
-                resources
-            });
-        }
-        catch (error) {
-            console.warn(`Skipping skill at ${child.path}:`, error);
-        }
-    }
-    return skills;
-}
-/**
- * Recursively collect paths to all resource files in a skill directory,
- * excluding `SKILL.md`. Content is loaded on-demand when the agent
- * requests a specific resource.
- */
-async function collectResourcePaths(contentsManager, basePath) {
-    const resourcePaths = [];
-    async function walk(dirPath) {
-        let dirModel;
-        try {
-            dirModel = await contentsManager.get(dirPath, { content: true });
-        }
-        catch (error) {
-            console.warn(`Failed to list directory ${dirPath}:`, error);
-            return;
-        }
-        if (dirModel.type !== 'directory' || !dirModel.content) {
-            return;
-        }
-        for (const item of dirModel.content) {
-            // Skip checkpoint directories
-            if (item.name === '.ipynb_checkpoints') {
-                continue;
-            }
-            if (item.type === 'directory') {
-                await walk(item.path);
-            }
-            else if (item.type === 'file' && item.name !== 'SKILL.md') {
-                // Store path relative to the skill directory
-                const relativePath = PathExt.relative(basePath, item.path);
-                resourcePaths.push(relativePath);
-            }
-        }
-    }
-    await walk(basePath);
-    return resourcePaths;
-}

package/lib/skills/skill-registry.d.ts

@@ -1,31 +0,0 @@
-import { DisposableDelegate } from '@lumino/disposable';
-import { ISignal } from '@lumino/signaling';
-import { ISkillDefinition, ISkillRegistration, ISkillResourceResult, ISkillSummary } from './types';
-import { ISkillRegistry } from '../tokens';
-export declare class SkillRegistry implements ISkillRegistry {
-    /**
-     * Signal emitted when skills change.
-     */
-    get skillsChanged(): ISignal<ISkillRegistry, void>;
-    /**
-     * Register a single skill.
-     */
-    registerSkill(skill: ISkillRegistration): DisposableDelegate;
-    /**
-     * List all registered skills with summary info, optionally filtered by a
-     * search query (matches name or description, case-insensitive).
-     */
-    listSkills(query?: string): ISkillSummary[];
-    /**
-     * Get the full definition for a skill.
-     */
-    getSkill(name: string): ISkillDefinition | null;
-    /**
-     * Load a resource for a skill.
-     */
-    getSkillResource(name: string, resource: string): Promise<ISkillResourceResult>;
-    private _registerSkillInternal;
-    private _skills;
-    private _skillsChanged;
-    private _nextRegistrationId;
-}

package/lib/skills/skill-registry.js

@@ -1,100 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-import { DisposableDelegate } from '@lumino/disposable';
-import { Signal } from '@lumino/signaling';
-export class SkillRegistry {
-    /**
-     * Signal emitted when skills change.
-     */
-    get skillsChanged() {
-        return this._skillsChanged;
-    }
-    /**
-     * Register a single skill.
-     */
-    registerSkill(skill) {
-        const entry = this._registerSkillInternal(skill);
-        if (!entry) {
-            return new DisposableDelegate(() => undefined);
-        }
-        this._skillsChanged.emit(void 0);
-        const registrationId = entry.registrationId;
-        const name = skill.name;
-        return new DisposableDelegate(() => {
-            const current = this._skills.get(name);
-            if (!current || current.registrationId !== registrationId) {
-                return;
-            }
-            this._skills.delete(name);
-            this._skillsChanged.emit(void 0);
-        });
-    }
-    /**
-     * List all registered skills with summary info, optionally filtered by a
-     * search query (matches name or description, case-insensitive).
-     */
-    listSkills(query) {
-        const summaries = [];
-        for (const entry of this._skills.values()) {
-            summaries.push({
-                name: entry.definition.name,
-                description: entry.definition.description
-            });
-        }
-        summaries.sort((a, b) => a.name.localeCompare(b.name));
-        if (!query) {
-            return summaries;
-        }
-        const term = query.toLowerCase();
-        return summaries.filter(skill => skill.name.toLowerCase().includes(term) ||
-            skill.description.toLowerCase().includes(term));
-    }
-    /**
-     * Get the full definition for a skill.
-     */
-    getSkill(name) {
-        const entry = this._skills.get(name);
-        return entry ? entry.definition : null;
-    }
-    /**
-     * Load a resource for a skill.
-     */
-    async getSkillResource(name, resource) {
-        const entry = this._skills.get(name);
-        if (!entry) {
-            return {
-                name,
-                resource,
-                error: `Skill not found: ${name}`
-            };
-        }
-        if (!entry.loadResource) {
-            return {
-                name,
-                resource,
-                error: `Skill does not provide resources: ${name}`
-            };
-        }
-        return entry.loadResource(resource);
-    }
-    _registerSkillInternal(skill) {
-        const existing = this._skills.get(skill.name);
-        if (existing) {
-            console.warn(`Skipping duplicate skill name "${skill.name}".`);
-            return null;
-        }
-        const { loadResource, ...definition } = skill;
-        const entry = {
-            definition,
-            loadResource,
-            registrationId: this._nextRegistrationId++
-        };
-        this._skills.set(skill.name, entry);
-        return entry;
-    }
-    _skills = new Map();
-    _skillsChanged = new Signal(this);
-    _nextRegistrationId = 0;
-}

package/lib/skills/types.d.ts

@@ -1,29 +0,0 @@
-/**
- * Summary information about a skill.
- */
-export interface ISkillSummary {
-    name: string;
-    description: string;
-}
-/**
- * Full skill definition loaded from a SKILL.md file or registry.
- */
-export interface ISkillDefinition extends ISkillSummary {
-    instructions: string;
-    resources: string[];
-}
-/**
- * Result for loading a skill resource.
- */
-export interface ISkillResourceResult {
-    name: string;
-    resource: string;
-    content?: string;
-    error?: string;
-}
-/**
- * Skill registration payload for the skill registry.
- */
-export interface ISkillRegistration extends ISkillDefinition {
-    loadResource?: (resource: string) => Promise<ISkillResourceResult>;
-}