@jupyterlite/ai 0.17.0 → 0.19.0

package/src/providers/provider-tools.ts

@@ -1,179 +0,0 @@
-import { anthropic } from '@ai-sdk/anthropic';
-import { openai } from '@ai-sdk/openai';
-import type { Tool } from 'ai';
-
-import type {
-  IProviderInfo,
-  IProviderWebFetchImplementation,
-  IProviderWebSearchImplementation
-} 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;
-}
-
-const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES = 2;
-const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS = 12000;
-
-function normalizeDomain(value: string): string {
-  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?: string[]): string[] {
-  value = value || [];
-  const values = Array.from(
-    new Set(value.map(normalizeDomain).filter(domain => domain.length > 0))
-  );
-
-  return values;
-}
-
-function createOpenAIWebSearchTool(
-  webSearchSettings: IWebSearchSettings
-): Tool {
-  const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
-  return openai.tools.webSearch({
-    externalWebAccess: webSearchSettings.externalWebAccess,
-    searchContextSize: webSearchSettings.searchContextSize,
-    filters: allowedDomains.length > 0 ? { allowedDomains } : undefined
-  });
-}
-
-function createAnthropicWebSearchTool(
-  webSearchSettings: IWebSearchSettings
-): Tool {
-  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: IWebFetchSettings
-): Tool {
-  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: IProviderWebSearchImplementation,
-  webSearchSettings: IWebSearchSettings
-): Tool {
-  switch (implementation) {
-    case 'openai':
-      return createOpenAIWebSearchTool(webSearchSettings);
-    case 'anthropic':
-      return createAnthropicWebSearchTool(webSearchSettings);
-    default:
-      throw new Error(
-        `Unsupported web search implementation: ${implementation}`
-      );
-  }
-}
-
-function createWebFetchTool(
-  implementation: IProviderWebFetchImplementation,
-  webFetchSettings: IWebFetchSettings
-): Tool {
-  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: IProviderToolContext): ToolMap {
-  const tools: ToolMap = {};
-  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/src/skills/index.ts

@@ -1,14 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-
-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/src/skills/parse-skill.ts

@@ -1,91 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-
-import { parse as parseYaml } from 'yaml';
-
-/**
- * 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 function parseSkillMd(content: string): IParsedSkill {
-  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: string[] = [];
-  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: unknown;
-  try {
-    metadata = parseYaml(frontmatter);
-  } catch (error) {
-    throw new Error(
-      `Invalid SKILL.md: YAML frontmatter parse failed: ${error}`
-    );
-  }
-
-  const data = metadata as Record<string, unknown> | null;
-  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/src/skills/skill-loader.ts

@@ -1,175 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-
-import { Contents } from '@jupyterlab/services';
-import { PathExt } from '@jupyterlab/coreutils';
-
-import { parseSkillMd, 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 async function loadSkillsFromPaths(
-  contentsManager: Contents.IManager,
-  skillsPaths: string[]
-): Promise<ISkillFileDefinition[]> {
-  const seen = new Set<string>();
-  const merged: ISkillFileDefinition[] = [];
-
-  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: Contents.IManager,
-  skillsPath: string
-): Promise<ISkillFileDefinition[]> {
-  const skills: ISkillFileDefinition[] = [];
-
-  // 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: Contents.IModel;
-    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 ?? []) as Contents.IModel[];
-    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 as Contents.IModel[]) {
-    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 ?? []) as Contents.IModel[];
-    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: Contents.IManager,
-  basePath: string
-): Promise<string[]> {
-  const resourcePaths: string[] = [];
-
-  async function walk(dirPath: string): Promise<void> {
-    let dirModel: Contents.IModel;
-    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 as Contents.IModel[]) {
-      // 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/src/skills/skill-registry.ts

@@ -1,137 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-
-import { DisposableDelegate } from '@lumino/disposable';
-import { ISignal, Signal } from '@lumino/signaling';
-
-import {
-  ISkillDefinition,
-  ISkillRegistration,
-  ISkillResourceResult,
-  ISkillSummary
-} from './types';
-import { ISkillRegistry } from '../tokens';
-
-interface ISkillEntry {
-  definition: ISkillDefinition;
-  loadResource?: (resource: string) => Promise<ISkillResourceResult>;
-  registrationId: number;
-}
-
-export class SkillRegistry implements ISkillRegistry {
-  /**
-   * Signal emitted when skills change.
-   */
-  get skillsChanged(): ISignal<ISkillRegistry, void> {
-    return this._skillsChanged;
-  }
-
-  /**
-   * Register a single skill.
-   */
-  registerSkill(skill: ISkillRegistration): DisposableDelegate {
-    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?: string): ISkillSummary[] {
-    const summaries: ISkillSummary[] = [];
-    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: string): ISkillDefinition | null {
-    const entry = this._skills.get(name);
-    return entry ? entry.definition : null;
-  }
-
-  /**
-   * Load a resource for a skill.
-   */
-  async getSkillResource(
-    name: string,
-    resource: string
-  ): Promise<ISkillResourceResult> {
-    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);
-  }
-
-  private _registerSkillInternal(
-    skill: ISkillRegistration
-  ): ISkillEntry | null {
-    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: ISkillEntry = {
-      definition,
-      loadResource,
-      registrationId: this._nextRegistrationId++
-    };
-    this._skills.set(skill.name, entry);
-    return entry;
-  }
-
-  private _skills = new Map<string, ISkillEntry>();
-  private _skillsChanged = new Signal<ISkillRegistry, void>(this);
-  private _nextRegistrationId = 0;
-}

package/src/skills/types.ts

@@ -1,37 +0,0 @@
-/*
- * Copyright (c) Jupyter Development Team.
- * Distributed under the terms of the Modified BSD License.
- */
-
-/**
- * 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>;
-}