Add skill governance and runtime routing

This commit is contained in:
dahyeon committed 2026-05-14 14:28:59 -07:00
1 parent 6f09408423
commit 41dcfcdef7
71 files changed
+7057 -102

No files matched your search

+42
View File
@@ -0,0 +1,42 @@
import { z } from "zod";
import { describe, expect, it } from "vitest";
import { ToolRegistry } from "./registry.js";
import type { Tool } from "./tool.js";
function tool(name: string, description: string): Tool<unknown, unknown> {
return {
argsSchema: z.object({}),
description,
execute: () => Promise.resolve({}),
name,
resultSchema: z.object({}),
};
}
describe("ToolRegistry.searchByDescription", () => {
it("finds nickname validation tools from mixed Korean and English queries", () => {
const registry = new ToolRegistry()
.register(tool("lookup-weather", "날씨와 기온 정보를 확인한다."))
.register(tool("validate-nickname", "닉네임 형식과 티어 코드를 검사한다."))
.register(tool("lookup-community-rule", "커뮤니티 규칙과 나이 제한을 조회한다."));
expect(registry.searchByDescription("nickname validation", 1)[0]?.name).toBe(
"validate-nickname",
);
});
it("returns the top k ranked tools", () => {
const registry = new ToolRegistry()
.register(tool("verify-discord-nickname", "디스코드 닉네임 변경 여부를 확인한다."))
.register(tool("lookup-community-rule", "디스코드 닉네임 운영 규칙을 조회한다."))
.register(tool("get-room-context", "최근 채팅방 대화 맥락을 조회한다."));
const results = registry.searchByDescription("discord nickname", 2);
expect(results.map((result) => result.name)).toEqual([
"verify-discord-nickname",
"lookup-community-rule",
]);
});
});
+86
View File
@@ -1,5 +1,37 @@
import type { Tool } from "./tool.js";
const TOKEN_SYNONYMS: Record<string, string[]> = {
age: ["age", "나이", "연령"],
discord: ["discord", "디스코드", "디코"],
nickname: ["nickname", "닉네임", "이름"],
photo: ["photo", "사진", "하트", "인증"],
progress: ["progress", "진행", "상태", "완료"],
room: ["room", "방", "채팅방"],
validate: ["validate", "validation", "검사", "확인"],
};
function tokenize(value: string): string[] {
return value
.toLowerCase()
.match(/[a-z0-9가-힣#-]+/gu) ?? [];
}
function expandQueryTokens(tokens: string[]): string[] {
return [
...new Set(
tokens.flatMap((token) => TOKEN_SYNONYMS[token] ?? [token]),
),
];
}
function countTokens(tokens: readonly string[]): Map<string, number> {
const counts = new Map<string, number>();
for (const token of tokens) {
counts.set(token, (counts.get(token) ?? 0) + 1);
}
return counts;
}
export class ToolRegistry {
private readonly tools = new Map<string, Tool<unknown, unknown>>();
@@ -29,4 +61,58 @@ export class ToolRegistry {
.filter((name) => this.tools.has(name))
.map((name) => this.get(name));
}
searchByDescription(query: string, k = 3): Tool<unknown, unknown>[] {
const queryTokens = expandQueryTokens(tokenize(query));
if (queryTokens.length === 0 || k <= 0) {
return [];
}
const docs = this.list().map((tool) => {
const tokens = tokenize(`${tool.name} ${tool.description}`);
return {
counts: countTokens(tokens),
length: Math.max(1, tokens.length),
tool,
};
});
const avgLength =
docs.reduce((sum, doc) => sum + doc.length, 0) / Math.max(1, docs.length);
const docFreq = new Map<string, number>();
for (const token of queryTokens) {
docFreq.set(
token,
docs.filter((doc) => doc.counts.has(token)).length,
);
}
const scored = docs.map((doc) => {
const score = queryTokens.reduce((sum, token) => {
const tf = doc.counts.get(token) ?? 0;
if (tf === 0) {
return sum;
}
const df = docFreq.get(token) ?? 0;
const idf = Math.log(1 + (docs.length - df + 0.5) / (df + 0.5));
const k1 = 1.2;
const b = 0.75;
const normalizedTf =
(tf * (k1 + 1)) /
(tf + k1 * (1 - b + b * (doc.length / avgLength)));
const nameBoost = doc.tool.name.toLowerCase().includes(token) ? 0.3 : 0;
return sum + idf * normalizedTf + nameBoost;
}, 0);
return {
score,
tool: doc.tool,
};
});
return scored
.filter((item) => item.score > 0)
.sort((left, right) => right.score - left.score)
.slice(0, k)
.map((item) => item.tool);
}
}
+44
View File
@@ -0,0 +1,44 @@
import { z } from "zod";
import { describe, expect, it } from "vitest";
import { ToolRegistry } from "./registry.js";
import type { Tool } from "./tool.js";
import { createToolSearchTool } from "./tool-search.js";
function tool(name: string, description: string): Tool<unknown, unknown> {
return {
argsSchema: z.object({}),
description,
execute: () => Promise.resolve({}),
name,
resultSchema: z.object({}),
};
}
describe("createToolSearchTool", () => {
it("returns matching tool descriptors", async () => {
const registry = new ToolRegistry()
.register(tool("validate-nickname", "닉네임 형식을 검사한다."))
.register(tool("lookup-community-rule", "나이 제한과 커뮤니티 규칙을 조회한다."));
const searchTool = createToolSearchTool(registry);
await expect(searchTool.execute({ query: "nickname", topK: 1 }, {})).resolves.toEqual({
tools: [
{
description: "닉네임 형식을 검사한다.",
name: "validate-nickname",
},
],
});
});
it("validates query arguments", () => {
const searchTool = createToolSearchTool(new ToolRegistry());
expect(() => searchTool.argsSchema.parse({ query: "x", topK: 1 })).toThrow();
expect(searchTool.argsSchema.parse({ query: "nickname" })).toEqual({
query: "nickname",
topK: 3,
});
});
});
+43
View File
@@ -0,0 +1,43 @@
import { z } from "zod";
import type { Tool, ToolContext } from "./tool.js";
import type { ToolRegistry } from "./registry.js";
const argsSchema = z.object({
query: z.string().trim().min(2),
topK: z.number().int().min(1).max(5).default(3),
});
const resultSchema = z.object({
tools: z.array(
z.object({
description: z.string(),
name: z.string(),
}),
),
});
export type ToolSearchArgs = z.infer<typeof argsSchema>;
export type ToolSearchResult = z.infer<typeof resultSchema>;
export function createToolSearchTool(
registry: ToolRegistry,
): Tool<ToolSearchArgs, ToolSearchResult> {
return {
argsSchema,
description: "도구 카탈로그에서 가장 적합한 도구 후보를 검색합니다.",
execute(args: ToolSearchArgs, _ctx: ToolContext) {
return Promise.resolve({
tools: registry
.searchByDescription(args.query, args.topK)
.filter((tool) => tool.name !== "search_tools")
.map((tool) => ({
description: tool.description,
name: tool.name,
})),
});
},
name: "search_tools",
resultSchema,
};
}
+16
View File
@@ -3,6 +3,7 @@ import type { NatsClient } from "@common/nats";
import type { RoomContextService } from "@room/room-context-service";
import type { ZodType } from "zod";
import type { OnboardingSession } from "@skills/onboarding/types";
import type { ToolRegistry } from "./registry.js";
export interface ToolContext {
chatroomId?: string | undefined;
@@ -11,6 +12,21 @@ export interface ToolContext {
session?: OnboardingSession | null | undefined;
garnetClient?: GarnetClient | undefined;
roomContextService?: RoomContextService | undefined;
toolRegistry?: ToolRegistry | undefined;
}
export type ToolErrorKind =
| "args-invalid"
| "transient"
| "precondition-failed"
| "permanent";
export interface ToolExecutionFailure {
kind: ToolErrorKind;
toolName: string;
message: string;
retryable: boolean;
details?: unknown;
}
export interface Tool<A, R> {