dictionary_hypernyms

Instructions

Implementation Reference

• src/tools/relations.ts:157-158 (handler)

  Handler for dictionary_hypernyms tool. Delegates to fetchRelation with 'IsA' relation and direction 'start' (i.e., broader concepts where the query word is the start/child).

  handler: async (args: { word: string; language?: string; limit?: number }) =>
    fetchRelation(args.word, args.language ?? "en", "IsA", args.limit ?? 50, "start"),

• src/tools/relations.ts:152-156 (schema)

  Input schema for dictionary_hypernyms: word (string, required), language (string, default 'en'), limit (int 1-1000, default 50).

  inputSchema: z.object({
    word: z.string(),
    language: z.string().default("en"),
    limit: z.number().int().min(1).max(1000).default(50),
  }),

• src/tools/relations.ts:149-158 (registration)

  Tool definition object for dictionary_hypernyms within the relationTools array. Registered with name, description, inputSchema, and handler.

  {
    name: "dictionary_hypernyms",
    description: "Hypernyms (broader concepts) via offline ConceptNet IsA. E.g. dog -> mammal.",
    inputSchema: z.object({
      word: z.string(),
      language: z.string().default("en"),
      limit: z.number().int().min(1).max(1000).default(50),
    }),
    handler: async (args: { word: string; language?: string; limit?: number }) =>
      fetchRelation(args.word, args.language ?? "en", "IsA", args.limit ?? 50, "start"),

• src/tools/relations.ts:40-54 (helper)

  fetchRelation helper function called by dictionary_hypernyms handler. Queries local ConceptNet SQLite edges filtered by relation type 'IsA' and direction 'start'.

  function fetchRelation(
    word: string,
    language: string,
    rel: string,
    limit: number,
    direction: "start" | "end" | "any" = "any"
  ): RelationResult[] {
    const local = localConceptNetEdges({ word, language, rel, direction, limit });
    if (local === undefined) {
      throw new Error(
        `ConceptNet relation lookup needs the offline data. Install state: ${dataInstallSummary()}. Use dictionary_status to track progress.`
      );
    }
    return local.map((e) => localEdgeToResult(e, word, language));
  }

• src/data/local-store.ts:81-143 (helper)

  localConceptNetEdges function that queries the ConceptNet SQLite database. Called by fetchRelation with the 'IsA' relation to retrieve hypernym edges.

  export function localConceptNetEdges(opts: {
    word: string;
    language: string;
    rel?: string;
    direction?: "start" | "end" | "any";
    otherLanguage?: string;
    limit: number;
  }): LocalEdge[] | undefined {
    const db = conceptnetDb();
    if (!db) return undefined;
    const node = `/c/${opts.language}/${normalizeWord(opts.word)}`;
    const direction = opts.direction ?? "any";
    const where: string[] = [];
    const params: unknown[] = [];
    if (direction === "start" || direction === "any") {
      where.push("start_uri = ?");
      params.push(node);
    }
    if (direction === "end") {
      where.push("end_uri = ?");
      params.push(node);
    }
    let whereSql = direction === "any" ? "(start_uri = ? OR end_uri = ?)" : where.join(" AND ");
    let actualParams: unknown[] = direction === "any" ? [node, node] : params;
    if (opts.rel) {
      whereSql += " AND rel = ?";
      actualParams.push(opts.rel);
    }
    if (opts.otherLanguage) {
      whereSql += " AND (start_lang = ? OR end_lang = ?)";
      actualParams.push(opts.otherLanguage, opts.otherLanguage);
    }
    const rows = db
      .prepare(
        `SELECT rel, start_uri, end_uri, start_lang, end_lang, start_label, end_label, weight, surface_text
         FROM edges
         WHERE ${whereSql}
         ORDER BY weight DESC
         LIMIT ?`
      )
      .all(...actualParams, opts.limit) as Array<{
      rel: string;
      start_uri: string;
      end_uri: string;
      start_lang: string;
      end_lang: string;
      start_label: string;
      end_label: string;
      weight: number;
      surface_text: string | null;
    }>;
    return rows.map((r) => ({
      rel: r.rel,
      start: r.start_uri,
      end: r.end_uri,
      startLang: r.start_lang,
      endLang: r.end_lang,
      startLabel: r.start_label,
      endLabel: r.end_label,
      weight: r.weight,
      surfaceText: r.surface_text,
    }));
  }