Add memory layers and RAG retrieval
This commit is contained in:
1 parent
1d0be56842
commit
1a86bded0b
31 files changed
+1592
-58
No files matched your search
@@ -5,8 +5,11 @@ import {
|
||||
getAlertThresholdEvalScoreDropPct,
|
||||
getAlertThresholdLlmErrorRate,
|
||||
getAlertThresholdP95LatencyMs,
|
||||
getEmbeddingModel,
|
||||
getEmbeddingProvider,
|
||||
getPhoenixLogPrompts,
|
||||
getPhoenixOtlpEndpoint,
|
||||
getRagEnabled,
|
||||
getSlackAlertWebhookUrl,
|
||||
getSlackWebhookTimeoutMs,
|
||||
getSupervisorLlmResponseEnabled,
|
||||
@@ -21,6 +24,9 @@ const ENV_KEYS = [
|
||||
"ALERT_THRESHOLD_LLM_ERROR_RATE_ONBOARDING",
|
||||
"ALERT_THRESHOLD_P95_LATENCY_MS",
|
||||
"ALERT_THRESHOLD_P95_LATENCY_MS_ONBOARDING",
|
||||
"AGENT_RAG_ENABLED",
|
||||
"EMBEDDING_MODEL",
|
||||
"EMBEDDING_PROVIDER",
|
||||
"PHOENIX_LOG_PROMPTS",
|
||||
"PHOENIX_OTLP_ENDPOINT",
|
||||
"SLACK_ALERT_WEBHOOK_URL",
|
||||
@@ -77,6 +83,20 @@ describe("config", () => {
|
||||
expect(getPhoenixLogPrompts()).toBe(true);
|
||||
});
|
||||
|
||||
it("reads RAG and embedding configuration", () => {
|
||||
expect(getRagEnabled()).toBe(true);
|
||||
expect(getEmbeddingProvider()).toBe("openrouter");
|
||||
expect(getEmbeddingModel()).toBe("openai/text-embedding-3-small");
|
||||
|
||||
vi.stubEnv("AGENT_RAG_ENABLED", "false");
|
||||
vi.stubEnv("EMBEDDING_PROVIDER", "openai");
|
||||
vi.stubEnv("EMBEDDING_MODEL", "custom-embedding");
|
||||
|
||||
expect(getRagEnabled()).toBe(false);
|
||||
expect(getEmbeddingProvider()).toBe("openai");
|
||||
expect(getEmbeddingModel()).toBe("custom-embedding");
|
||||
});
|
||||
|
||||
it("enables supervisor LLM user messages by default with env override", () => {
|
||||
expect(getSupervisorLlmResponseEnabled()).toBe(true);
|
||||
|
||||
|
||||
@@ -129,6 +129,47 @@ export function getPhoenixLogPrompts(): boolean {
|
||||
return getBoolean("PHOENIX_LOG_PROMPTS", false);
|
||||
}
|
||||
|
||||
export function getRagEnabled(): boolean {
|
||||
return getBoolean("AGENT_RAG_ENABLED", true);
|
||||
}
|
||||
|
||||
export function getEmbeddingProvider(): "openrouter" | "openai" {
|
||||
const raw = process.env["EMBEDDING_PROVIDER"]?.trim().toLowerCase();
|
||||
return raw === "openai" ? "openai" : "openrouter";
|
||||
}
|
||||
|
||||
export function getEmbeddingModel(provider = getEmbeddingProvider()): string {
|
||||
const configured = process.env["EMBEDDING_MODEL"]?.trim();
|
||||
if (configured) {
|
||||
return configured;
|
||||
}
|
||||
return provider === "openai"
|
||||
? "text-embedding-3-small"
|
||||
: "openai/text-embedding-3-small";
|
||||
}
|
||||
|
||||
export function getEmbeddingApiUrl(provider = getEmbeddingProvider()): string {
|
||||
const configured = process.env["EMBEDDING_API_URL"]?.trim();
|
||||
if (configured) {
|
||||
return configured;
|
||||
}
|
||||
return provider === "openai"
|
||||
? "https://api.openai.com/v1"
|
||||
: "https://openrouter.ai/api/v1";
|
||||
}
|
||||
|
||||
export function getEmbeddingDimensions(): number {
|
||||
return getPositiveNumber("EMBEDDING_DIMENSIONS", 1536);
|
||||
}
|
||||
|
||||
export function getEmbeddingRequestTimeoutMs(): number {
|
||||
return getPositiveNumber("EMBEDDING_REQUEST_TIMEOUT_MS", 30_000);
|
||||
}
|
||||
|
||||
export function getKnowledgeSearchCandidateLimit(): number {
|
||||
return getPositiveNumber("KNOWLEDGE_SEARCH_CANDIDATE_LIMIT", 500);
|
||||
}
|
||||
|
||||
export function getRequestSubject(): string {
|
||||
return (
|
||||
process.env["AGENT_REQUEST_SUBJECT"]?.trim() || "lolympus-agent.request"
|
||||
|
||||
+8
-1
@@ -49,6 +49,7 @@ import type {
|
||||
EvalReportSummary,
|
||||
EvalSummaryDelta,
|
||||
} from "./types.js";
|
||||
import { createMemoryService } from "../memory/memory-service.js";
|
||||
|
||||
const DEFAULT_REPORTS_DIR = "eval-reports";
|
||||
const LEGACY_BASELINE_FILE = `${DEFAULT_REPORTS_DIR}/baseline.json`;
|
||||
@@ -67,13 +68,19 @@ interface SkillRunnerDeps {
|
||||
}
|
||||
|
||||
const SKILL_RUNNER_FACTORIES: Record<string, (deps: SkillRunnerDeps) => Skill> = {
|
||||
moderation: (deps) => new ModerationSkill(deps.llm),
|
||||
moderation: (deps) =>
|
||||
new ModerationSkill(
|
||||
deps.llm,
|
||||
createMemoryService({ garnetClient: deps.garnet }),
|
||||
),
|
||||
onboarding: (deps) =>
|
||||
new OnboardingSkill(
|
||||
deps.garnet,
|
||||
deps.llm,
|
||||
deps.room,
|
||||
noopShadowEvalPublisher,
|
||||
undefined,
|
||||
createMemoryService({ garnetClient: deps.garnet }),
|
||||
),
|
||||
supervisor: (deps) =>
|
||||
new SupervisorSkill(deps.garnet, {
|
||||
|
||||
+9
-1
@@ -30,6 +30,7 @@ const { ShadowEvalBus } = await import("./eval/shadow-bus.js");
|
||||
const { LlmClient } = await import("./llm/index.js");
|
||||
const { getRawSecret, getSecret } = await import("./common/secret-manager.js");
|
||||
const { initMongoDB, closeMongoDB } = await import("./common/mongodb.js");
|
||||
const { createMemoryService } = await import("./memory/memory-service.js");
|
||||
const { RoomContextService } = await import("./room-context/index.js");
|
||||
const { startMetricsServer, stopMetricsServer } = await import(
|
||||
"./observability/metrics-server.js"
|
||||
@@ -201,13 +202,14 @@ async function bootstrap(): Promise<void> {
|
||||
}
|
||||
|
||||
// MongoDB + RoomContextService setup (optional)
|
||||
let mongoConnection: Awaited<ReturnType<typeof initMongoDB>> | undefined;
|
||||
let roomContextService: InstanceType<typeof RoomContextService> | undefined;
|
||||
const mongoConnectionString = firstNonEmpty(
|
||||
getSecret("MONGODB_CONNECTION_STRING"),
|
||||
process.env["MONGODB_CONNECTION_STRING"],
|
||||
);
|
||||
if (mongoConnectionString) {
|
||||
await initMongoDB(mongoConnectionString);
|
||||
mongoConnection = await initMongoDB(mongoConnectionString);
|
||||
// 시크릿의 projectId를 환경변수로 전파 (config.ts에서 참조)
|
||||
const mongoProjectId = firstNonEmpty(
|
||||
getSecret("MONGODB_PROJECT_ID"),
|
||||
@@ -222,6 +224,11 @@ async function bootstrap(): Promise<void> {
|
||||
logger.warn("[MongoDB] No connection string configured — room context disabled");
|
||||
}
|
||||
|
||||
const memoryService = createMemoryService({
|
||||
garnetClient,
|
||||
mongooseConnection: mongoConnection,
|
||||
});
|
||||
|
||||
// Agent setup
|
||||
const conversationStore = new ConversationStore(garnetClient);
|
||||
const skillRegistry = SkillRegistry.load(resolve(process.cwd(), "src", "skills"));
|
||||
@@ -259,6 +266,7 @@ async function bootstrap(): Promise<void> {
|
||||
factory({
|
||||
garnetClient,
|
||||
llmClient,
|
||||
memoryService,
|
||||
natsClient,
|
||||
roomContextService,
|
||||
shadowEvalBus,
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { cosineSimilarity, rankByCosineSimilarity } from "./cosine.js";
|
||||
|
||||
describe("cosineSimilarity", () => {
|
||||
it("scores identical vectors above unrelated vectors", () => {
|
||||
expect(cosineSimilarity([1, 0], [1, 0])).toBeCloseTo(1);
|
||||
expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0);
|
||||
});
|
||||
|
||||
it("ranks documents by cosine score", () => {
|
||||
const ranked = rankByCosineSimilarity(
|
||||
[1, 0],
|
||||
[
|
||||
{ embedding: [0, 1], id: "b" },
|
||||
{ embedding: [1, 0], id: "a" },
|
||||
],
|
||||
1,
|
||||
);
|
||||
|
||||
expect(ranked).toEqual([
|
||||
expect.objectContaining({
|
||||
id: "a",
|
||||
score: 1,
|
||||
}),
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,40 @@
|
||||
export function cosineSimilarity(a: number[], b: number[]): number {
|
||||
if (a.length === 0 || a.length !== b.length) {
|
||||
return 0;
|
||||
}
|
||||
|
||||
let dot = 0;
|
||||
let magnitudeA = 0;
|
||||
let magnitudeB = 0;
|
||||
for (let index = 0; index < a.length; index += 1) {
|
||||
const left = a[index] ?? 0;
|
||||
const right = b[index] ?? 0;
|
||||
dot += left * right;
|
||||
magnitudeA += left * left;
|
||||
magnitudeB += right * right;
|
||||
}
|
||||
|
||||
if (magnitudeA === 0 || magnitudeB === 0) {
|
||||
return 0;
|
||||
}
|
||||
|
||||
return dot / (Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB));
|
||||
}
|
||||
|
||||
export function rankByCosineSimilarity<T extends { embedding: number[] }>(
|
||||
query: number[],
|
||||
docs: T[],
|
||||
topK: number,
|
||||
): Array<T & { score: number }> {
|
||||
if (topK <= 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return docs
|
||||
.map((doc) => ({
|
||||
...doc,
|
||||
score: cosineSimilarity(query, doc.embedding),
|
||||
}))
|
||||
.sort((left, right) => right.score - left.score)
|
||||
.slice(0, topK);
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
import { getRawSecret } from "@common/secret-manager";
|
||||
import { getLogger } from "@obs/logger";
|
||||
import {
|
||||
getEmbeddingApiUrl,
|
||||
getEmbeddingDimensions,
|
||||
getEmbeddingModel,
|
||||
getEmbeddingProvider,
|
||||
getEmbeddingRequestTimeoutMs,
|
||||
} from "../config.js";
|
||||
|
||||
export interface EmbeddingClient {
|
||||
embed(text: string): Promise<number[]>;
|
||||
embedBatch(texts: string[]): Promise<number[][]>;
|
||||
readonly model: string;
|
||||
readonly dimensions: number;
|
||||
}
|
||||
|
||||
interface EmbeddingResponse {
|
||||
data?: Array<{
|
||||
embedding?: number[] | undefined;
|
||||
index?: number | undefined;
|
||||
}> | undefined;
|
||||
model?: string | undefined;
|
||||
}
|
||||
|
||||
abstract class HttpEmbeddingClient implements EmbeddingClient {
|
||||
constructor(
|
||||
readonly model: string,
|
||||
readonly dimensions: number,
|
||||
private readonly apiKey: string | undefined,
|
||||
private readonly baseUrl: string,
|
||||
) {}
|
||||
|
||||
async embed(text: string): Promise<number[]> {
|
||||
const [embedding] = await this.embedBatch([text]);
|
||||
if (!embedding) {
|
||||
throw new Error("Embedding response did not include an embedding");
|
||||
}
|
||||
return embedding;
|
||||
}
|
||||
|
||||
async embedBatch(texts: string[]): Promise<number[][]> {
|
||||
const input = texts.map((text) => text.trim()).filter(Boolean);
|
||||
if (input.length === 0) {
|
||||
return [];
|
||||
}
|
||||
if (!this.apiKey) {
|
||||
throw new Error(`${this.constructor.name} requires an embedding API key`);
|
||||
}
|
||||
|
||||
const response = await fetch(`${this.baseUrl.replace(/\/+$/u, "")}/embeddings`, {
|
||||
body: JSON.stringify({
|
||||
dimensions: this.dimensions,
|
||||
input,
|
||||
model: this.model,
|
||||
}),
|
||||
headers: {
|
||||
Authorization: `Bearer ${this.apiKey}`,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
method: "POST",
|
||||
signal: AbortSignal.timeout(getEmbeddingRequestTimeoutMs()),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const body = (await response.text()).slice(0, 500);
|
||||
throw new Error(`Embedding request failed (${response.status}): ${body}`);
|
||||
}
|
||||
|
||||
const payload = (await response.json()) as EmbeddingResponse;
|
||||
const rows = payload.data ?? [];
|
||||
return rows
|
||||
.sort((left, right) => (left.index ?? 0) - (right.index ?? 0))
|
||||
.map((row) => row.embedding ?? []);
|
||||
}
|
||||
}
|
||||
|
||||
export class OpenRouterEmbeddingClient extends HttpEmbeddingClient {
|
||||
constructor() {
|
||||
super(
|
||||
getEmbeddingModel("openrouter"),
|
||||
getEmbeddingDimensions(),
|
||||
getRawSecret("EMBEDDING_API_KEY") ?? getRawSecret("OPENROUTER_API_KEY"),
|
||||
getEmbeddingApiUrl("openrouter"),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export class OpenAIEmbeddingClient extends HttpEmbeddingClient {
|
||||
constructor() {
|
||||
super(
|
||||
getEmbeddingModel("openai").replace(/^openai\//u, ""),
|
||||
getEmbeddingDimensions(),
|
||||
getRawSecret("EMBEDDING_API_KEY") ?? getRawSecret("OPENAI_API_KEY"),
|
||||
getEmbeddingApiUrl("openai"),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
class FallbackEmbeddingClient implements EmbeddingClient {
|
||||
readonly model: string;
|
||||
readonly dimensions: number;
|
||||
private readonly logger = getLogger();
|
||||
|
||||
constructor(
|
||||
private readonly primary: EmbeddingClient,
|
||||
private readonly fallback: EmbeddingClient,
|
||||
) {
|
||||
this.model = primary.model;
|
||||
this.dimensions = primary.dimensions;
|
||||
}
|
||||
|
||||
embed(text: string): Promise<number[]> {
|
||||
return this.embedBatch([text]).then((embeddings) => {
|
||||
const [embedding] = embeddings;
|
||||
if (!embedding) {
|
||||
throw new Error("Embedding response did not include an embedding");
|
||||
}
|
||||
return embedding;
|
||||
});
|
||||
}
|
||||
|
||||
async embedBatch(texts: string[]): Promise<number[][]> {
|
||||
try {
|
||||
return await this.primary.embedBatch(texts);
|
||||
} catch (error) {
|
||||
this.logger.warn(
|
||||
{ err: error, provider: "openrouter" },
|
||||
"[Memory] Primary embedding provider failed; falling back",
|
||||
);
|
||||
return this.fallback.embedBatch(texts);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function createEmbeddingClient(): EmbeddingClient {
|
||||
const provider = getEmbeddingProvider();
|
||||
if (provider === "openai") {
|
||||
return new OpenAIEmbeddingClient();
|
||||
}
|
||||
|
||||
return new FallbackEmbeddingClient(
|
||||
new OpenRouterEmbeddingClient(),
|
||||
new OpenAIEmbeddingClient(),
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { GarnetSessionMemory, getSessionBlackboardKey } from "./garnet-session-memory.js";
|
||||
|
||||
class MemoryGarnet {
|
||||
readonly records = new Map<string, unknown>();
|
||||
|
||||
getJson<T>(key: string): Promise<T | null> {
|
||||
return Promise.resolve((this.records.get(key) as T | undefined) ?? null);
|
||||
}
|
||||
|
||||
setJson(key: string, value: unknown): Promise<void> {
|
||||
this.records.set(key, value);
|
||||
return Promise.resolve();
|
||||
}
|
||||
|
||||
getString(): Promise<string | null> {
|
||||
return Promise.resolve(null);
|
||||
}
|
||||
|
||||
setString(): Promise<void> {
|
||||
return Promise.resolve();
|
||||
}
|
||||
}
|
||||
|
||||
describe("GarnetSessionMemory", () => {
|
||||
it("keeps onboarding blackboard namespace backward compatible", async () => {
|
||||
const garnet = new MemoryGarnet();
|
||||
const memory = new GarnetSessionMemory(garnet as never);
|
||||
|
||||
await memory.setBlackboard("onboarding", "room-1", "user-1", { ok: true });
|
||||
|
||||
expect(getSessionBlackboardKey("onboarding", "room-1", "user-1")).toBe(
|
||||
"lolympus-agent:bb:room-1:user-1",
|
||||
);
|
||||
expect(garnet.records.get("lolympus-agent:bb:room-1:user-1")).toEqual({
|
||||
ok: true,
|
||||
});
|
||||
});
|
||||
|
||||
it("separates non-onboarding blackboards by skill", async () => {
|
||||
const garnet = new MemoryGarnet();
|
||||
const memory = new GarnetSessionMemory(garnet as never);
|
||||
|
||||
await memory.setBlackboard("moderation", "room-1", "user-1", { ok: true });
|
||||
|
||||
expect(getSessionBlackboardKey("moderation", "room-1", "user-1")).toBe(
|
||||
"lolympus-agent:bb:moderation:room-1:user-1",
|
||||
);
|
||||
expect(garnet.records.has("lolympus-agent:bb:room-1:user-1")).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,75 @@
|
||||
import type { ConversationMessage } from "@agent/types";
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import { ConversationStore } from "@conv/conversation-store";
|
||||
import { getBlackboardTtlSeconds } from "../config.js";
|
||||
import type { SessionMemory } from "./memory-types.js";
|
||||
|
||||
export function getSessionBlackboardKey(
|
||||
skill: string,
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
): string {
|
||||
const normalizedSkill = skill.trim() || "unknown";
|
||||
if (normalizedSkill === "onboarding") {
|
||||
return `lolympus-agent:bb:${chatroomId}:${userId}`;
|
||||
}
|
||||
return `lolympus-agent:bb:${normalizedSkill}:${chatroomId}:${userId}`;
|
||||
}
|
||||
|
||||
export class GarnetSessionMemory implements SessionMemory {
|
||||
private readonly conversationStore: ConversationStore;
|
||||
|
||||
constructor(private readonly garnetClient: GarnetClient) {
|
||||
this.conversationStore = new ConversationStore(garnetClient);
|
||||
}
|
||||
|
||||
getBlackboard<T>(
|
||||
skill: string,
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
): Promise<T | null> {
|
||||
return this.garnetClient.getJson<T>(
|
||||
getSessionBlackboardKey(skill, chatroomId, userId),
|
||||
);
|
||||
}
|
||||
|
||||
setBlackboard<T>(
|
||||
skill: string,
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
value: T,
|
||||
): Promise<void> {
|
||||
return this.garnetClient.setJson(
|
||||
getSessionBlackboardKey(skill, chatroomId, userId),
|
||||
value,
|
||||
getBlackboardTtlSeconds(),
|
||||
);
|
||||
}
|
||||
|
||||
getConversationHistory(
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
): Promise<ConversationMessage[]> {
|
||||
return this.conversationStore.getHistory(chatroomId, userId);
|
||||
}
|
||||
|
||||
appendMessage(
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
message: ConversationMessage,
|
||||
): Promise<void> {
|
||||
return this.conversationStore.appendMessage(chatroomId, userId, message);
|
||||
}
|
||||
|
||||
getSummary(chatroomId: string, userId: string): Promise<string | null> {
|
||||
return this.conversationStore.getSummary(chatroomId, userId);
|
||||
}
|
||||
|
||||
setSummary(
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
summary: string,
|
||||
): Promise<void> {
|
||||
return this.conversationStore.setSummary(chatroomId, userId, summary);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { readdir, readFile } from "node:fs/promises";
|
||||
import { basename, join, relative } from "node:path";
|
||||
import type { MemoryService } from "./memory-types.js";
|
||||
|
||||
export interface IngestOptions {
|
||||
skill?: string | undefined;
|
||||
category: string;
|
||||
baseDir: string;
|
||||
dryRun?: boolean | undefined;
|
||||
}
|
||||
|
||||
export interface IngestResult {
|
||||
inserted: number;
|
||||
updated: number;
|
||||
skipped: number;
|
||||
}
|
||||
|
||||
interface Chunk {
|
||||
id: string;
|
||||
sectionTitle: string;
|
||||
sourceFile: string;
|
||||
text: string;
|
||||
}
|
||||
|
||||
interface LongTermWithLookup {
|
||||
hasDocument(id: string): Promise<boolean>;
|
||||
}
|
||||
|
||||
function hasDocumentLookup(value: unknown): value is LongTermWithLookup {
|
||||
return (
|
||||
typeof value === "object" &&
|
||||
value !== null &&
|
||||
"hasDocument" in value &&
|
||||
typeof (value as { hasDocument?: unknown }).hasDocument === "function"
|
||||
);
|
||||
}
|
||||
|
||||
function normalizeTitle(value: string, fallback: string): string {
|
||||
const trimmed = value
|
||||
.replace(/^#+\s*/u, "")
|
||||
.replace(/^\[/u, "")
|
||||
.replace(/\]$/u, "")
|
||||
.trim();
|
||||
return trimmed || fallback;
|
||||
}
|
||||
|
||||
function stableChunkId(input: {
|
||||
category: string;
|
||||
sectionTitle: string;
|
||||
skill?: string | undefined;
|
||||
sourceFile: string;
|
||||
}): string {
|
||||
const hash = createHash("sha256")
|
||||
.update(JSON.stringify(input))
|
||||
.digest("hex")
|
||||
.slice(0, 24);
|
||||
return `knowledge_${hash}`;
|
||||
}
|
||||
|
||||
function splitMarkdown(filePath: string, content: string, options: IngestOptions): Chunk[] {
|
||||
const sourceFile = relative(process.cwd(), filePath);
|
||||
const headingPattern = /^##\s+(.+)$/gmu;
|
||||
const headings = [...content.matchAll(headingPattern)];
|
||||
|
||||
if (headings.length === 0) {
|
||||
const firstLine = content.split(/\r?\n/u)[0] ?? basename(filePath);
|
||||
const sectionTitle = normalizeTitle(firstLine, basename(filePath, ".md"));
|
||||
return [
|
||||
{
|
||||
id: stableChunkId({
|
||||
category: options.category,
|
||||
sectionTitle,
|
||||
skill: options.skill,
|
||||
sourceFile,
|
||||
}),
|
||||
sectionTitle,
|
||||
sourceFile,
|
||||
text: content.trim(),
|
||||
},
|
||||
].filter((chunk) => chunk.text.length > 0);
|
||||
}
|
||||
|
||||
return headings.flatMap((heading, index) => {
|
||||
const start = heading.index + heading[0].length;
|
||||
const nextHeading = headings[index + 1];
|
||||
const end = nextHeading ? nextHeading.index : content.length;
|
||||
const sectionTitle = normalizeTitle(heading[1] ?? "", basename(filePath, ".md"));
|
||||
const body = content.slice(start, end).trim();
|
||||
if (!body) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return [
|
||||
{
|
||||
id: stableChunkId({
|
||||
category: options.category,
|
||||
sectionTitle,
|
||||
skill: options.skill,
|
||||
sourceFile,
|
||||
}),
|
||||
sectionTitle,
|
||||
sourceFile,
|
||||
text: `## ${sectionTitle}\n${body}`,
|
||||
},
|
||||
];
|
||||
});
|
||||
}
|
||||
|
||||
export async function ingestMarkdownResources(
|
||||
memoryService: MemoryService,
|
||||
options: IngestOptions,
|
||||
): Promise<IngestResult> {
|
||||
const files = (await readdir(options.baseDir))
|
||||
.filter((file) => file.endsWith(".md"))
|
||||
.sort();
|
||||
const result: IngestResult = {
|
||||
inserted: 0,
|
||||
skipped: 0,
|
||||
updated: 0,
|
||||
};
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = join(options.baseDir, file);
|
||||
const content = await readFile(filePath, "utf8");
|
||||
const chunks = splitMarkdown(filePath, content, options);
|
||||
|
||||
for (const chunk of chunks) {
|
||||
if (!chunk.text.trim()) {
|
||||
result.skipped += 1;
|
||||
continue;
|
||||
}
|
||||
|
||||
const existed = hasDocumentLookup(memoryService.longTerm)
|
||||
? await memoryService.longTerm.hasDocument(chunk.id)
|
||||
: false;
|
||||
|
||||
if (options.dryRun) {
|
||||
if (existed) {
|
||||
result.updated += 1;
|
||||
} else {
|
||||
result.inserted += 1;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
await memoryService.longTerm.upsertDocument({
|
||||
id: chunk.id,
|
||||
category: options.category,
|
||||
metadata: {
|
||||
sectionTitle: chunk.sectionTitle,
|
||||
sourceFile: chunk.sourceFile,
|
||||
},
|
||||
skill: options.skill,
|
||||
text: chunk.text,
|
||||
});
|
||||
|
||||
if (existed) {
|
||||
result.updated += 1;
|
||||
} else {
|
||||
result.inserted += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { DefaultMemoryService } from "./memory-service.js";
|
||||
import type { LongTermMemory, SessionMemory } from "./memory-types.js";
|
||||
|
||||
const session: SessionMemory = {
|
||||
appendMessage: () => Promise.resolve(),
|
||||
getBlackboard: <T>() =>
|
||||
Promise.resolve({ flaggedIssues: ["x"] } as T),
|
||||
getConversationHistory: () =>
|
||||
Promise.resolve([{ role: "user", content: "hi", timestamp: "t" }]),
|
||||
getSummary: () => Promise.resolve("summary"),
|
||||
setBlackboard: () => Promise.resolve(),
|
||||
setSummary: () => Promise.resolve(),
|
||||
};
|
||||
|
||||
const longTerm: LongTermMemory = {
|
||||
deleteDocument: () => Promise.resolve(),
|
||||
loadUserProfile: () => Promise.resolve(null),
|
||||
search: () =>
|
||||
Promise.resolve([
|
||||
{
|
||||
category: "rule",
|
||||
id: "doc-1",
|
||||
score: 0.9,
|
||||
text: "rule text",
|
||||
},
|
||||
]),
|
||||
updateUserProfile: () => Promise.resolve(),
|
||||
upsertDocument: () => Promise.resolve("doc-1"),
|
||||
};
|
||||
|
||||
describe("DefaultMemoryService", () => {
|
||||
it("assembles working memory from session and long-term layers", async () => {
|
||||
const memory = new DefaultMemoryService(session, longTerm);
|
||||
|
||||
const working = await memory.assembleWorkingMemory({
|
||||
skill: "onboarding",
|
||||
chatroomId: "room-1",
|
||||
userId: "user-1",
|
||||
includeBlackboard: true,
|
||||
retrieval: { query: "rule" },
|
||||
});
|
||||
|
||||
expect(working.summary).toBe("summary");
|
||||
expect(working.blackboard?.flaggedIssues).toEqual(["x"]);
|
||||
expect(working.conversationHistory).toHaveLength(1);
|
||||
expect(working.retrievedKnowledge?.[0]?.text).toBe("rule text");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,95 @@
|
||||
import type mongoose from "mongoose";
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import type { Blackboard } from "@skills/onboarding/types";
|
||||
import { createEmbeddingClient } from "./embedding-client.js";
|
||||
import { GarnetSessionMemory } from "./garnet-session-memory.js";
|
||||
import {
|
||||
MongoLongTermMemory,
|
||||
NoopLongTermMemory,
|
||||
} from "./mongo-long-term-memory.js";
|
||||
import type {
|
||||
LongTermMemory,
|
||||
MemoryService,
|
||||
SearchOptions,
|
||||
SessionMemory,
|
||||
WorkingMemory,
|
||||
} from "./memory-types.js";
|
||||
|
||||
interface CreateMemoryServiceOptions {
|
||||
garnetClient: GarnetClient;
|
||||
mongooseConnection?: mongoose.Connection | undefined;
|
||||
}
|
||||
|
||||
function defaultBlackboard(): Blackboard {
|
||||
return {
|
||||
flaggedIssues: [],
|
||||
openQuestions: [],
|
||||
recentNicknameAttempts: [],
|
||||
toneMemory: {},
|
||||
};
|
||||
}
|
||||
|
||||
export class DefaultMemoryService implements MemoryService {
|
||||
constructor(
|
||||
readonly session: SessionMemory,
|
||||
readonly longTerm: LongTermMemory,
|
||||
) {}
|
||||
|
||||
async assembleWorkingMemory(input: {
|
||||
skill: string;
|
||||
chatroomId: string;
|
||||
userId: string;
|
||||
includeBlackboard?: boolean;
|
||||
includeProfile?: boolean;
|
||||
retrieval?: { query: string; options?: SearchOptions | undefined } | undefined;
|
||||
}): Promise<WorkingMemory> {
|
||||
const [
|
||||
conversationHistory,
|
||||
summary,
|
||||
blackboard,
|
||||
userProfile,
|
||||
retrievedKnowledge,
|
||||
] = await Promise.all([
|
||||
this.session.getConversationHistory(input.chatroomId, input.userId),
|
||||
this.session.getSummary(input.chatroomId, input.userId),
|
||||
input.includeBlackboard
|
||||
? this.session.getBlackboard<Blackboard>(
|
||||
input.skill,
|
||||
input.chatroomId,
|
||||
input.userId,
|
||||
)
|
||||
: Promise.resolve(null),
|
||||
input.includeProfile
|
||||
? this.longTerm.loadUserProfile(input.userId)
|
||||
: Promise.resolve(null),
|
||||
input.retrieval
|
||||
? this.longTerm.search(input.retrieval.query, input.retrieval.options ?? {})
|
||||
: Promise.resolve(undefined),
|
||||
]);
|
||||
|
||||
return {
|
||||
conversationHistory,
|
||||
...(summary ? { summary } : {}),
|
||||
...(input.includeBlackboard
|
||||
? { blackboard: blackboard ?? defaultBlackboard() }
|
||||
: {}),
|
||||
...(userProfile ? { userProfile } : {}),
|
||||
...(retrievedKnowledge ? { retrievedKnowledge } : {}),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
export function createMemoryService(
|
||||
options: CreateMemoryServiceOptions,
|
||||
): MemoryService {
|
||||
const session = new GarnetSessionMemory(options.garnetClient);
|
||||
const longTerm = options.mongooseConnection
|
||||
? new MongoLongTermMemory(
|
||||
options.garnetClient,
|
||||
options.mongooseConnection,
|
||||
createEmbeddingClient(),
|
||||
)
|
||||
: new NoopLongTermMemory(options.garnetClient);
|
||||
|
||||
return new DefaultMemoryService(session, longTerm);
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
import type { ConversationMessage } from "@agent/types";
|
||||
import type { Blackboard } from "@skills/onboarding/types";
|
||||
import type { UserProfile } from "@skills/onboarding/state/user-memory";
|
||||
|
||||
export interface RetrievedDocument {
|
||||
id: string;
|
||||
text: string;
|
||||
category: string;
|
||||
skill?: string | undefined;
|
||||
score: number;
|
||||
metadata?: Record<string, unknown> | undefined;
|
||||
}
|
||||
|
||||
export interface KnowledgeDocument {
|
||||
id?: string | undefined;
|
||||
skill?: string | undefined;
|
||||
category: string;
|
||||
text: string;
|
||||
embedding?: number[] | undefined;
|
||||
metadata?: Record<string, unknown> | undefined;
|
||||
embeddingModel?: string | undefined;
|
||||
}
|
||||
|
||||
export interface WorkingMemory {
|
||||
conversationHistory: ConversationMessage[];
|
||||
summary?: string | undefined;
|
||||
blackboard?: Blackboard | undefined;
|
||||
userProfile?: UserProfile | undefined;
|
||||
retrievedKnowledge?: RetrievedDocument[] | undefined;
|
||||
}
|
||||
|
||||
export interface SessionMemory {
|
||||
getBlackboard<T>(skill: string, chatroomId: string, userId: string): Promise<T | null>;
|
||||
setBlackboard<T>(
|
||||
skill: string,
|
||||
chatroomId: string,
|
||||
userId: string,
|
||||
value: T,
|
||||
): Promise<void>;
|
||||
getConversationHistory(chatroomId: string, userId: string): Promise<ConversationMessage[]>;
|
||||
appendMessage(chatroomId: string, userId: string, message: ConversationMessage): Promise<void>;
|
||||
getSummary(chatroomId: string, userId: string): Promise<string | null>;
|
||||
setSummary(chatroomId: string, userId: string, summary: string): Promise<void>;
|
||||
}
|
||||
|
||||
export interface SearchOptions {
|
||||
skill?: string | undefined;
|
||||
category?: string | undefined;
|
||||
topK?: number | undefined;
|
||||
}
|
||||
|
||||
export interface LongTermMemory {
|
||||
loadUserProfile(userId: string): Promise<UserProfile | null>;
|
||||
updateUserProfile(userId: string, patch: Partial<UserProfile>): Promise<void>;
|
||||
search(query: string, options: SearchOptions): Promise<RetrievedDocument[]>;
|
||||
upsertDocument(doc: KnowledgeDocument): Promise<string>;
|
||||
deleteDocument(id: string): Promise<void>;
|
||||
}
|
||||
|
||||
export interface MemoryService {
|
||||
session: SessionMemory;
|
||||
longTerm: LongTermMemory;
|
||||
assembleWorkingMemory(input: {
|
||||
skill: string;
|
||||
chatroomId: string;
|
||||
userId: string;
|
||||
includeBlackboard?: boolean;
|
||||
includeProfile?: boolean;
|
||||
retrieval?: { query: string; options?: SearchOptions | undefined } | undefined;
|
||||
}): Promise<WorkingMemory>;
|
||||
}
|
||||
@@ -0,0 +1,266 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import type mongoose from "mongoose";
|
||||
import { Schema } from "mongoose";
|
||||
import { anonymizeIdentifier } from "@eval/anonymize";
|
||||
import { withSpan } from "@obs/spans";
|
||||
import { getAgentUserMemoryTtlDays, getKnowledgeSearchCandidateLimit } from "../config.js";
|
||||
import type { UserProfile } from "@skills/onboarding/state/user-memory";
|
||||
import { USER_MEMORY_KEY_PREFIX } from "@skills/onboarding/state/user-memory";
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import { rankByCosineSimilarity } from "./cosine.js";
|
||||
import type {
|
||||
KnowledgeDocument,
|
||||
LongTermMemory,
|
||||
RetrievedDocument,
|
||||
SearchOptions,
|
||||
} from "./memory-types.js";
|
||||
import type { EmbeddingClient } from "./embedding-client.js";
|
||||
|
||||
export const KNOWLEDGE_COLLECTION = "knowledge_documents";
|
||||
|
||||
interface KnowledgeDocumentRecord {
|
||||
_id: string;
|
||||
skill?: string | undefined;
|
||||
category: string;
|
||||
text: string;
|
||||
embedding: number[];
|
||||
embeddingModel: string;
|
||||
metadata?: Record<string, unknown> | undefined;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
const KnowledgeSchema = new Schema<KnowledgeDocumentRecord>(
|
||||
{
|
||||
_id: { type: String, required: true },
|
||||
skill: { type: String, index: true },
|
||||
category: { type: String, required: true, index: true },
|
||||
text: { type: String, required: true },
|
||||
embedding: { type: [Number], required: true },
|
||||
embeddingModel: { type: String, required: true },
|
||||
metadata: { type: Schema.Types.Mixed },
|
||||
createdAt: { type: Date, default: Date.now },
|
||||
updatedAt: { type: Date, default: Date.now, index: true },
|
||||
},
|
||||
{ versionKey: false },
|
||||
);
|
||||
|
||||
function userProfileKey(userId: string): string {
|
||||
return `${USER_MEMORY_KEY_PREFIX}:${anonymizeIdentifier("user", userId) ?? "unknown"}`;
|
||||
}
|
||||
|
||||
function userProfileTtlSeconds(): number {
|
||||
return getAgentUserMemoryTtlDays() * 24 * 60 * 60;
|
||||
}
|
||||
|
||||
function nowIso(): string {
|
||||
return new Date().toISOString();
|
||||
}
|
||||
|
||||
function emptyProfile(userId: string, now = nowIso()): UserProfile {
|
||||
return {
|
||||
firstSeenAt: now,
|
||||
flaggedIssues: [],
|
||||
lastSeenAt: now,
|
||||
pastIntents: [],
|
||||
preferredStyle: "neutral",
|
||||
totalTurns: 0,
|
||||
userId: anonymizeIdentifier("user", userId) ?? "user_unknown",
|
||||
};
|
||||
}
|
||||
|
||||
function stableDocumentId(doc: KnowledgeDocument): string {
|
||||
const hash = createHash("sha256")
|
||||
.update(JSON.stringify({
|
||||
category: doc.category,
|
||||
metadata: doc.metadata ?? {},
|
||||
skill: doc.skill ?? "",
|
||||
text: doc.text,
|
||||
}))
|
||||
.digest("hex")
|
||||
.slice(0, 24);
|
||||
return `knowledge_${hash}`;
|
||||
}
|
||||
|
||||
function buildFilter(options: SearchOptions): Record<string, unknown> {
|
||||
const filter: Record<string, unknown> = {};
|
||||
if (options.skill?.trim()) {
|
||||
filter["skill"] = options.skill.trim();
|
||||
}
|
||||
if (options.category?.trim()) {
|
||||
filter["category"] = options.category.trim();
|
||||
}
|
||||
return filter;
|
||||
}
|
||||
|
||||
export class MongoLongTermMemory implements LongTermMemory {
|
||||
private readonly model: mongoose.Model<KnowledgeDocumentRecord>;
|
||||
|
||||
constructor(
|
||||
private readonly garnetClient: Pick<GarnetClient, "getJson" | "setJson">,
|
||||
connection: mongoose.Connection,
|
||||
private readonly embeddingClient: EmbeddingClient,
|
||||
) {
|
||||
this.model =
|
||||
(connection.models["KnowledgeDocument"] as mongoose.Model<KnowledgeDocumentRecord> | undefined) ??
|
||||
connection.model<KnowledgeDocumentRecord>(
|
||||
"KnowledgeDocument",
|
||||
KnowledgeSchema,
|
||||
KNOWLEDGE_COLLECTION,
|
||||
);
|
||||
}
|
||||
|
||||
loadUserProfile(userId: string): Promise<UserProfile | null> {
|
||||
return this.garnetClient.getJson<UserProfile>(userProfileKey(userId));
|
||||
}
|
||||
|
||||
async updateUserProfile(
|
||||
userId: string,
|
||||
patch: Partial<UserProfile>,
|
||||
): Promise<void> {
|
||||
const current = (await this.loadUserProfile(userId)) ?? emptyProfile(userId);
|
||||
const next: UserProfile = {
|
||||
...current,
|
||||
...patch,
|
||||
firstSeenAt: patch.firstSeenAt ?? current.firstSeenAt,
|
||||
flaggedIssues: patch.flaggedIssues ?? current.flaggedIssues,
|
||||
lastSeenAt: patch.lastSeenAt ?? nowIso(),
|
||||
pastIntents: patch.pastIntents ?? current.pastIntents,
|
||||
preferredStyle: patch.preferredStyle ?? current.preferredStyle,
|
||||
totalTurns: patch.totalTurns ?? current.totalTurns,
|
||||
userId: current.userId,
|
||||
};
|
||||
await this.garnetClient.setJson(
|
||||
userProfileKey(userId),
|
||||
next,
|
||||
userProfileTtlSeconds(),
|
||||
);
|
||||
}
|
||||
|
||||
async search(
|
||||
query: string,
|
||||
options: SearchOptions = {},
|
||||
): Promise<RetrievedDocument[]> {
|
||||
const trimmed = query.trim();
|
||||
if (!trimmed) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return withSpan(
|
||||
"memory.retrieval",
|
||||
{
|
||||
"memory.retrieval.category": options.category,
|
||||
"memory.retrieval.skill": options.skill,
|
||||
"memory.retrieval.top_k": options.topK ?? 5,
|
||||
},
|
||||
async (span) => {
|
||||
const startedAt = Date.now();
|
||||
const queryEmbedding = await this.embeddingClient.embed(trimmed);
|
||||
const docs = (await this.model
|
||||
.find(buildFilter(options))
|
||||
.sort({ updatedAt: -1 })
|
||||
.limit(getKnowledgeSearchCandidateLimit())
|
||||
.lean()
|
||||
.exec()) as KnowledgeDocumentRecord[];
|
||||
const ranked = rankByCosineSimilarity(
|
||||
queryEmbedding,
|
||||
docs.filter((doc) =>
|
||||
Array.isArray(doc.embedding) &&
|
||||
doc.embedding.length === queryEmbedding.length
|
||||
),
|
||||
options.topK ?? 5,
|
||||
);
|
||||
|
||||
span.setAttributes({
|
||||
"memory.retrieval.candidate_count": docs.length,
|
||||
"memory.retrieval.duration_ms": Math.max(0, Date.now() - startedAt),
|
||||
"memory.retrieval.top_score": ranked[0]?.score,
|
||||
});
|
||||
|
||||
return ranked.map((doc) => ({
|
||||
id: doc._id,
|
||||
category: doc.category,
|
||||
metadata: doc.metadata,
|
||||
score: doc.score,
|
||||
skill: doc.skill,
|
||||
text: doc.text,
|
||||
}));
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
async upsertDocument(doc: KnowledgeDocument): Promise<string> {
|
||||
const id = doc.id?.trim() || stableDocumentId(doc);
|
||||
const embedding = doc.embedding ?? await this.embeddingClient.embed(doc.text);
|
||||
if (embedding.length !== this.embeddingClient.dimensions) {
|
||||
throw new Error(
|
||||
`Embedding dimension mismatch: expected ${this.embeddingClient.dimensions}, got ${embedding.length}`,
|
||||
);
|
||||
}
|
||||
|
||||
const updatedAt = new Date();
|
||||
await this.model.updateOne(
|
||||
{ _id: id },
|
||||
{
|
||||
$set: {
|
||||
category: doc.category,
|
||||
embedding,
|
||||
embeddingModel: doc.embeddingModel ?? this.embeddingClient.model,
|
||||
metadata: doc.metadata,
|
||||
skill: doc.skill,
|
||||
text: doc.text,
|
||||
updatedAt,
|
||||
},
|
||||
$setOnInsert: {
|
||||
createdAt: updatedAt,
|
||||
},
|
||||
},
|
||||
{ upsert: true },
|
||||
).exec();
|
||||
return id;
|
||||
}
|
||||
|
||||
async hasDocument(id: string): Promise<boolean> {
|
||||
return Boolean(await this.model.exists({ _id: id }).exec());
|
||||
}
|
||||
|
||||
async deleteDocument(id: string): Promise<void> {
|
||||
await this.model.deleteOne({ _id: id }).exec();
|
||||
}
|
||||
}
|
||||
|
||||
export class NoopLongTermMemory implements LongTermMemory {
|
||||
constructor(private readonly garnetClient: Pick<GarnetClient, "getJson" | "setJson">) {}
|
||||
|
||||
loadUserProfile(userId: string): Promise<UserProfile | null> {
|
||||
return this.garnetClient.getJson<UserProfile>(userProfileKey(userId));
|
||||
}
|
||||
|
||||
async updateUserProfile(
|
||||
userId: string,
|
||||
patch: Partial<UserProfile>,
|
||||
): Promise<void> {
|
||||
const current = (await this.loadUserProfile(userId)) ?? emptyProfile(userId);
|
||||
await this.garnetClient.setJson(
|
||||
userProfileKey(userId),
|
||||
{ ...current, ...patch, userId: current.userId },
|
||||
userProfileTtlSeconds(),
|
||||
);
|
||||
}
|
||||
|
||||
search(): Promise<RetrievedDocument[]> {
|
||||
return Promise.resolve([]);
|
||||
}
|
||||
|
||||
upsertDocument(doc: KnowledgeDocument): Promise<string> {
|
||||
return Promise.reject(
|
||||
new Error(
|
||||
`Knowledge memory is unavailable; cannot upsert ${doc.id ?? doc.category}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
deleteDocument(): Promise<void> {
|
||||
return Promise.resolve();
|
||||
}
|
||||
}
|
||||
@@ -5,5 +5,5 @@ import { ModerationSkill } from "./skill.js";
|
||||
export { ModerationSkill } from "./skill.js";
|
||||
|
||||
export function createModerationSkill(deps: SkillDeps): Skill {
|
||||
return new ModerationSkill(deps.llmClient);
|
||||
return new ModerationSkill(deps.llmClient, deps.memoryService);
|
||||
}
|
||||
@@ -5,9 +5,12 @@ import type {
|
||||
} from "@agent/types";
|
||||
import type { LlmClient } from "@llm/llm-client";
|
||||
import type { ChatMessage } from "@llm/types";
|
||||
import type { MemoryService, RetrievedDocument } from "../../memory/memory-types.js";
|
||||
import { getRequestLogger } from "@obs/context";
|
||||
import type { Skill } from "@skills/skill";
|
||||
import type { SkillCapabilityCard } from "@skills/skill-loader";
|
||||
import { lookupRuleTool } from "@tools/moderation/lookup-rule";
|
||||
import { getRagEnabled } from "../../config.js";
|
||||
import { classifyModerationIntent, type ModerationIntent } from "./intents.js";
|
||||
import { MODERATION_PROMPT_DATA } from "./prompt-data.js";
|
||||
import { createModerationToolRegistry } from "./tools.js";
|
||||
@@ -137,18 +140,50 @@ function resolveRuleTopic(message: string): RuleTopic | null {
|
||||
async function lookupReferenceText(
|
||||
intent: ModerationIntent,
|
||||
message: string,
|
||||
memoryService?: MemoryService,
|
||||
): Promise<string | undefined> {
|
||||
if (intent.kind !== "rule-question") {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
if (memoryService && getRagEnabled()) {
|
||||
try {
|
||||
const docs = await memoryService.longTerm.search(message, {
|
||||
category: "rule",
|
||||
skill: "moderation",
|
||||
topK: 3,
|
||||
});
|
||||
if (docs.length > 0) {
|
||||
return formatRetrievedReference(docs);
|
||||
}
|
||||
} catch (error) {
|
||||
getRequestLogger().warn(
|
||||
{ err: error },
|
||||
"[ModerationSkill] Knowledge retrieval failed; using local rules",
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
const topic = resolveRuleTopic(message);
|
||||
if (!topic) {
|
||||
return undefined;
|
||||
}
|
||||
const result = await lookupRuleTool.execute({ topic }, {});
|
||||
const result = await lookupRuleTool.execute(
|
||||
{ topic },
|
||||
{ memoryService },
|
||||
);
|
||||
return result.text;
|
||||
}
|
||||
|
||||
function formatRetrievedReference(docs: RetrievedDocument[]): string {
|
||||
return docs
|
||||
.map((doc, index) => {
|
||||
const score = Number.isFinite(doc.score) ? doc.score.toFixed(3) : "0.000";
|
||||
return [`#${index + 1} score=${score}`, doc.text.trim()].join("\n");
|
||||
})
|
||||
.join("\n\n");
|
||||
}
|
||||
|
||||
function templateForIntent(intent: ModerationIntent): string {
|
||||
switch (intent.kind) {
|
||||
case "appeal":
|
||||
@@ -169,7 +204,10 @@ export class ModerationSkill implements Skill {
|
||||
readonly priority = 50;
|
||||
private readonly toolRegistry = createModerationToolRegistry();
|
||||
|
||||
constructor(private readonly llmClient: LlmClient) {}
|
||||
constructor(
|
||||
private readonly llmClient: LlmClient,
|
||||
private readonly memoryService?: MemoryService | undefined,
|
||||
) {}
|
||||
|
||||
canHandle(request: AgentRequest): boolean {
|
||||
return request.skill === this.name;
|
||||
@@ -187,6 +225,7 @@ export class ModerationSkill implements Skill {
|
||||
const referenceText = await lookupReferenceText(
|
||||
classified.intent,
|
||||
request.userMessage ?? "",
|
||||
this.memoryService,
|
||||
);
|
||||
const metadata = {
|
||||
intent: classified.intent.kind,
|
||||
|
||||
@@ -15,5 +15,6 @@ export function createOnboardingSkill(deps: SkillDeps): Skill {
|
||||
deps.roomContextService,
|
||||
deps.shadowEvalBus,
|
||||
deps.natsClient,
|
||||
deps.memoryService,
|
||||
);
|
||||
}
|
||||
@@ -123,6 +123,27 @@ function formatUserProfile(profile: UserProfile | null | undefined): string {
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
function formatRetrievedKnowledge(context: PromptContext): string[] {
|
||||
const docs = context.retrievedKnowledge ?? [];
|
||||
if (docs.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return [
|
||||
'',
|
||||
'[reference]',
|
||||
docs
|
||||
.map((doc, index) => {
|
||||
const score = Number.isFinite(doc.score) ? doc.score.toFixed(3) : '0.000';
|
||||
return [
|
||||
`#${index + 1} (${doc.category}, score=${score})`,
|
||||
doc.text.trim(),
|
||||
].join('\n');
|
||||
})
|
||||
.join('\n\n'),
|
||||
];
|
||||
}
|
||||
|
||||
export function personaLayer(): string {
|
||||
return ONBOARDING_PROMPT_DATA.persona;
|
||||
}
|
||||
@@ -201,5 +222,6 @@ export function contextLayer(context: PromptContext): string {
|
||||
formatUserProfile(context.userProfile),
|
||||
]
|
||||
: []),
|
||||
...formatRetrievedKnowledge(context),
|
||||
].join('\n');
|
||||
}
|
||||
@@ -2,12 +2,14 @@ import type { AgentRequest, ConversationMessage } from '@agent/types';
|
||||
import type { GarnetClient } from '@common/garnet';
|
||||
import { getConversationSummaryKey } from '@conv/conversation-store';
|
||||
import type { ChatMessage } from '@llm/types';
|
||||
import type { MemoryService } from '../../../memory/memory-types.js';
|
||||
import { getRequestLogger } from '@obs/context';
|
||||
import type { RoomContextService } from '@room/room-context-service';
|
||||
import { meetsTrustTier } from '../../../eval/governance/trust.js';
|
||||
import {
|
||||
getAgentTrustMinTier,
|
||||
getAgentUserMemoryEnabled,
|
||||
getRagEnabled,
|
||||
getPromptVariantId,
|
||||
} from '../../../config.js';
|
||||
import {
|
||||
@@ -22,6 +24,7 @@ import type { OnboardingSession, PromptContext } from '../types.js';
|
||||
interface MessageBuilderDeps {
|
||||
blackboardStore: OnboardingBlackboardStore;
|
||||
garnetClient: GarnetClient;
|
||||
memoryService?: MemoryService | undefined;
|
||||
roomContextService?: RoomContextService | undefined;
|
||||
userMemoryStore: UserMemoryStore;
|
||||
}
|
||||
@@ -67,6 +70,32 @@ async function loadConversationSummary(
|
||||
return (await garnetClient.getString(key)) ?? undefined;
|
||||
}
|
||||
|
||||
function shouldRetrieve(derived: DerivedState): boolean {
|
||||
return (
|
||||
getRagEnabled() &&
|
||||
(
|
||||
derived.intent.kind === 'help-how' ||
|
||||
derived.intent.kind === 'help-where' ||
|
||||
derived.intent.kind === 'nickname-question' ||
|
||||
derived.intent.kind === 'discord-question' ||
|
||||
derived.intent.kind === 'age-question'
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
function buildRetrievalQuery(
|
||||
request: AgentRequest,
|
||||
derived: DerivedState,
|
||||
): string {
|
||||
return [
|
||||
request.userMessage?.trim(),
|
||||
derived.intent.kind,
|
||||
derived.phase.kind,
|
||||
]
|
||||
.filter(Boolean)
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
export async function buildLlmMessages(
|
||||
deps: MessageBuilderDeps,
|
||||
input: MessageBuilderInput,
|
||||
@@ -85,7 +114,34 @@ export async function buildLlmMessages(
|
||||
return undefined;
|
||||
})
|
||||
: Promise.resolve(undefined);
|
||||
const userProfilePromise = getAgentUserMemoryEnabled()
|
||||
const workingMemoryPromise = deps.memoryService
|
||||
? deps.memoryService
|
||||
.assembleWorkingMemory({
|
||||
skill: 'onboarding',
|
||||
chatroomId: request.chatroomId,
|
||||
userId: request.userId,
|
||||
includeBlackboard: true,
|
||||
includeProfile: getAgentUserMemoryEnabled(),
|
||||
retrieval: shouldRetrieve(derived)
|
||||
? {
|
||||
query: buildRetrievalQuery(request, derived),
|
||||
options: {
|
||||
category: 'onboarding-step',
|
||||
skill: 'onboarding',
|
||||
topK: 2,
|
||||
},
|
||||
}
|
||||
: undefined,
|
||||
})
|
||||
.catch((error) => {
|
||||
logger.warn(
|
||||
{ err: error },
|
||||
'[OnboardingSkill] Failed to assemble working memory',
|
||||
);
|
||||
return null;
|
||||
})
|
||||
: Promise.resolve(null);
|
||||
const legacyUserProfilePromise = getAgentUserMemoryEnabled()
|
||||
? deps.userMemoryStore.load(request.userId).catch((error) => {
|
||||
logger.warn(
|
||||
{ err: error },
|
||||
@@ -94,20 +150,40 @@ export async function buildLlmMessages(
|
||||
return null;
|
||||
})
|
||||
: Promise.resolve(null);
|
||||
const [blackboard, summary, roomContext, userProfile] = await Promise.all([
|
||||
deps.blackboardStore.load(request.chatroomId, request.userId),
|
||||
loadConversationSummary(deps.garnetClient, request.chatroomId, request.userId),
|
||||
const [
|
||||
workingMemory,
|
||||
legacyBlackboard,
|
||||
legacySummary,
|
||||
roomContext,
|
||||
legacyUserProfile,
|
||||
] = await Promise.all([
|
||||
workingMemoryPromise,
|
||||
deps.memoryService
|
||||
? Promise.resolve(undefined)
|
||||
: deps.blackboardStore.load(request.chatroomId, request.userId),
|
||||
deps.memoryService
|
||||
? Promise.resolve(undefined)
|
||||
: loadConversationSummary(deps.garnetClient, request.chatroomId, request.userId),
|
||||
roomContextPromise,
|
||||
userProfilePromise,
|
||||
deps.memoryService ? Promise.resolve(null) : legacyUserProfilePromise,
|
||||
]);
|
||||
|
||||
const blackboard = workingMemory?.blackboard ?? legacyBlackboard;
|
||||
if (!blackboard) {
|
||||
throw new Error('Failed to load onboarding blackboard');
|
||||
}
|
||||
|
||||
const context: PromptContext = {
|
||||
blackboard,
|
||||
conversationHistory,
|
||||
conversationHistory:
|
||||
workingMemory && workingMemory.conversationHistory.length > 0
|
||||
? workingMemory.conversationHistory
|
||||
: conversationHistory,
|
||||
roomContext,
|
||||
summary,
|
||||
retrievedKnowledge: workingMemory?.retrievedKnowledge,
|
||||
summary: workingMemory?.summary ?? legacySummary,
|
||||
userMessage: buildPromptUserMessage(request, derived),
|
||||
userProfile,
|
||||
userProfile: workingMemory?.userProfile ?? legacyUserProfile,
|
||||
};
|
||||
|
||||
const builder = PromptBuilder.forDerived(derived, session, context);
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import type { AgentRequest, AgentResponse, ConversationMessage } from '@agent/types';
|
||||
import type { GarnetClient } from '@common/garnet';
|
||||
import type { NatsClient } from '@common/nats';
|
||||
import type { MemoryService } from '../../memory/memory-types.js';
|
||||
import { getContext, getRequestLogger } from '@obs/context';
|
||||
import type { LlmClient } from '@llm/llm-client';
|
||||
import type { RoomContextService } from '@room/room-context-service';
|
||||
@@ -112,10 +113,17 @@ export class OnboardingSkill implements Skill {
|
||||
private readonly roomContextService?: RoomContextService,
|
||||
shadowEvalPublisher?: ShadowEvalPublisher,
|
||||
private readonly natsClient?: Pick<NatsClient, 'request'>,
|
||||
private readonly memoryService?: MemoryService,
|
||||
) {
|
||||
this.classifier = new OnboardingIntentClassifier(llmClient);
|
||||
this.blackboardStore = new OnboardingBlackboardStore(garnetClient);
|
||||
this.userMemoryStore = new UserMemoryStore(garnetClient);
|
||||
this.blackboardStore = new OnboardingBlackboardStore(
|
||||
garnetClient,
|
||||
memoryService?.session,
|
||||
);
|
||||
this.userMemoryStore = new UserMemoryStore(
|
||||
garnetClient,
|
||||
memoryService?.longTerm,
|
||||
);
|
||||
this.orchestrator = new OnboardingOrchestrator(llmClient);
|
||||
this.shadowEvalPublisher = shadowEvalPublisher ?? new ShadowEvalBus(garnetClient);
|
||||
this.toolRegistry = createOnboardingToolRegistry();
|
||||
@@ -381,6 +389,7 @@ export class OnboardingSkill implements Skill {
|
||||
{
|
||||
blackboardStore: this.blackboardStore,
|
||||
garnetClient: this.garnetClient,
|
||||
memoryService: this.memoryService,
|
||||
roomContextService: this.roomContextService,
|
||||
userMemoryStore: this.userMemoryStore,
|
||||
},
|
||||
@@ -474,6 +483,7 @@ export class OnboardingSkill implements Skill {
|
||||
userId: request.userId,
|
||||
session,
|
||||
garnetClient: this.garnetClient,
|
||||
memoryService: this.memoryService,
|
||||
roomContextService: this.roomContextService,
|
||||
toolRegistry: this.toolRegistry,
|
||||
};
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import type { SessionMemory } from "../../../memory/memory-types.js";
|
||||
import { getBlackboardTtlSeconds } from "../../../config.js";
|
||||
import type { Blackboard } from "../types.js";
|
||||
|
||||
@@ -37,9 +38,21 @@ function mergeBlackboard(
|
||||
}
|
||||
|
||||
export class OnboardingBlackboardStore {
|
||||
constructor(private readonly garnetClient: GarnetClient) {}
|
||||
constructor(
|
||||
private readonly garnetClient: GarnetClient,
|
||||
private readonly sessionMemory?: SessionMemory | undefined,
|
||||
) {}
|
||||
|
||||
async load(chatroomId: string, userId: string): Promise<Blackboard> {
|
||||
if (this.sessionMemory) {
|
||||
const saved = await this.sessionMemory.getBlackboard<Blackboard>(
|
||||
"onboarding",
|
||||
chatroomId,
|
||||
userId,
|
||||
);
|
||||
return mergeBlackboard(saved, {});
|
||||
}
|
||||
|
||||
const key = getBlackboardKey(chatroomId, userId);
|
||||
const saved = await this.garnetClient.getJson<Blackboard>(key);
|
||||
return mergeBlackboard(saved, {});
|
||||
@@ -50,6 +63,16 @@ export class OnboardingBlackboardStore {
|
||||
userId: string,
|
||||
value: Blackboard,
|
||||
): Promise<void> {
|
||||
if (this.sessionMemory) {
|
||||
await this.sessionMemory.setBlackboard(
|
||||
"onboarding",
|
||||
chatroomId,
|
||||
userId,
|
||||
value,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const key = getBlackboardKey(chatroomId, userId);
|
||||
await this.garnetClient.setJson(
|
||||
key,
|
||||
|
||||
@@ -4,6 +4,7 @@ import {
|
||||
anonymizeText,
|
||||
} from "@eval/anonymize";
|
||||
import { getAgentUserMemoryTtlDays } from "../../../config.js";
|
||||
import type { LongTermMemory } from "../../../memory/memory-types.js";
|
||||
import type { DerivedState, Intent } from "./onboarding-state.js";
|
||||
|
||||
export type PreferredStyle = "concise" | "neutral" | "warm";
|
||||
@@ -86,9 +87,16 @@ function emptyProfile(userId: string, now = nowIso()): UserProfile {
|
||||
}
|
||||
|
||||
export class UserMemoryStore {
|
||||
constructor(private readonly garnetClient: UserMemoryGarnetClient) {}
|
||||
constructor(
|
||||
private readonly garnetClient: UserMemoryGarnetClient,
|
||||
private readonly longTermMemory?: LongTermMemory | undefined,
|
||||
) {}
|
||||
|
||||
async load(userId: string): Promise<UserProfile | null> {
|
||||
if (this.longTermMemory) {
|
||||
return this.longTermMemory.loadUserProfile(userId);
|
||||
}
|
||||
|
||||
return this.garnetClient.getJson<UserProfile>(profileKey(userId));
|
||||
}
|
||||
|
||||
@@ -125,7 +133,11 @@ export class UserMemoryStore {
|
||||
userId: current.userId,
|
||||
};
|
||||
|
||||
await this.garnetClient.setJson(profileKey(userId), next, ttlSeconds());
|
||||
if (this.longTermMemory) {
|
||||
await this.longTermMemory.updateUserProfile(userId, next);
|
||||
} else {
|
||||
await this.garnetClient.setJson(profileKey(userId), next, ttlSeconds());
|
||||
}
|
||||
return next;
|
||||
}
|
||||
}
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { ConversationMessage } from "@agent/types";
|
||||
import type { RetrievedDocument } from "../../memory/memory-types.js";
|
||||
import type { RoomMessage } from "@room/types";
|
||||
import type { UserProfile } from "./state/user-memory.js";
|
||||
|
||||
@@ -27,6 +28,7 @@ export interface PromptContext {
|
||||
blackboard: Blackboard;
|
||||
conversationHistory: ConversationMessage[];
|
||||
roomContext?: RoomMessage[] | undefined;
|
||||
retrievedKnowledge?: RetrievedDocument[] | undefined;
|
||||
summary?: string | undefined;
|
||||
userMessage: string;
|
||||
userProfile?: UserProfile | null | undefined;
|
||||
|
||||
@@ -2,6 +2,7 @@ import type { GarnetClient } from "@common/garnet";
|
||||
import type { NatsClient } from "@common/nats";
|
||||
import type { ShadowEvalBus } from "@eval/shadow-bus";
|
||||
import type { LlmClient } from "@llm/llm-client";
|
||||
import type { MemoryService } from "../memory/memory-types.js";
|
||||
import type { RoomContextService } from "@room/room-context-service";
|
||||
import type { Skill } from "./skill.js";
|
||||
import type { SkillRegistry } from "./skill-loader.js";
|
||||
@@ -9,6 +10,7 @@ import type { SkillRegistry } from "./skill-loader.js";
|
||||
export interface SkillDeps {
|
||||
garnetClient: GarnetClient;
|
||||
llmClient: LlmClient;
|
||||
memoryService?: MemoryService | undefined;
|
||||
natsClient: NatsClient;
|
||||
roomContextService?: RoomContextService | undefined;
|
||||
shadowEvalBus: ShadowEvalBus;
|
||||
|
||||
@@ -1,6 +1,13 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import type { MemoryService } from "../../memory/memory-types.js";
|
||||
import { lookupRuleTool } from "./lookup-rule.js";
|
||||
|
||||
const failingMemoryService = {
|
||||
longTerm: {
|
||||
search: () => Promise.reject(new Error("retrieval failed")),
|
||||
},
|
||||
} as unknown as MemoryService;
|
||||
|
||||
describe("lookupRuleTool", () => {
|
||||
it("returns the matching community rule section", async () => {
|
||||
const result = await lookupRuleTool.execute({ topic: "ads" }, {});
|
||||
@@ -10,9 +17,21 @@ describe("lookupRuleTool", () => {
|
||||
expect(result.text).toContain("홍보");
|
||||
});
|
||||
|
||||
it("validates topic enum values", () => {
|
||||
expect(() =>
|
||||
lookupRuleTool.argsSchema.parse({ topic: "unknown" }),
|
||||
).toThrow();
|
||||
it("accepts natural-language topics and falls back to local rules", async () => {
|
||||
const parsed = lookupRuleTool.argsSchema.parse({ topic: "광고 기준" });
|
||||
const result = await lookupRuleTool.execute(parsed, {});
|
||||
|
||||
expect(result.source).toBe("community-rules");
|
||||
expect(result.text).toContain("광고");
|
||||
});
|
||||
|
||||
it("falls back to local rules when knowledge retrieval fails", async () => {
|
||||
const result = await lookupRuleTool.execute(
|
||||
{ topic: "광고 기준" },
|
||||
{ memoryService: failingMemoryService },
|
||||
);
|
||||
|
||||
expect(result.source).toBe("community-rules");
|
||||
expect(result.text).toContain("광고");
|
||||
});
|
||||
});
|
||||
@@ -1,29 +1,40 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { z } from "zod";
|
||||
import { getRagEnabled } from "../../config.js";
|
||||
import { getRequestLogger } from "../../observability/context.js";
|
||||
import type { Tool } from "../tool.js";
|
||||
|
||||
const argsSchema = z.object({
|
||||
topic: z.enum([
|
||||
"ads",
|
||||
"appeal",
|
||||
"minor-safety",
|
||||
"off-topic",
|
||||
"privacy",
|
||||
"profanity",
|
||||
"report",
|
||||
"sanctions",
|
||||
"spam",
|
||||
]),
|
||||
topic: z.string().min(1).describe("검색할 규칙 주제"),
|
||||
topK: z.number().int().min(1).max(10).optional(),
|
||||
});
|
||||
|
||||
const resultSchema = z.object({
|
||||
topic: argsSchema.shape.topic,
|
||||
text: z.string(),
|
||||
source: z.literal("community-rules"),
|
||||
source: z.enum(["community-rules", "knowledge_documents"]),
|
||||
matches: z
|
||||
.array(
|
||||
z.object({
|
||||
id: z.string(),
|
||||
score: z.number(),
|
||||
text: z.string(),
|
||||
}),
|
||||
)
|
||||
.optional(),
|
||||
});
|
||||
|
||||
type RuleTopic = z.infer<typeof argsSchema>["topic"];
|
||||
type RuleTopic =
|
||||
| "ads"
|
||||
| "appeal"
|
||||
| "minor-safety"
|
||||
| "off-topic"
|
||||
| "privacy"
|
||||
| "profanity"
|
||||
| "report"
|
||||
| "sanctions"
|
||||
| "spam";
|
||||
|
||||
const RULES_PATH = fileURLToPath(
|
||||
new URL("../../skills/moderation/resources/community-rules.md", import.meta.url),
|
||||
@@ -36,6 +47,41 @@ function extractRuleSection(topic: RuleTopic): string {
|
||||
return match?.[1]?.trim() || "";
|
||||
}
|
||||
|
||||
function resolveLegacyTopic(topic: string): RuleTopic | null {
|
||||
if (
|
||||
topic === "ads" ||
|
||||
topic === "appeal" ||
|
||||
topic === "minor-safety" ||
|
||||
topic === "off-topic" ||
|
||||
topic === "privacy" ||
|
||||
topic === "profanity" ||
|
||||
topic === "report" ||
|
||||
topic === "sanctions" ||
|
||||
topic === "spam"
|
||||
) {
|
||||
return topic;
|
||||
}
|
||||
if (/(광고|홍보|링크)/u.test(topic)) return "ads";
|
||||
if (/(도배|반복|스팸)/u.test(topic)) return "spam";
|
||||
if (/(욕설|혐오|차별|비하)/u.test(topic)) return "profanity";
|
||||
if (/(신고|제보|위반)/u.test(topic)) return "report";
|
||||
if (/(경고|제재|강퇴|처벌)/u.test(topic)) return "sanctions";
|
||||
if (/(이의|소명|억울|정지|벤|밴|차단)/u.test(topic)) return "appeal";
|
||||
if (/(미성년|미자|성적|보호)/u.test(topic)) return "minor-safety";
|
||||
if (/(개인정보|전화번호|주소|실명|계정)/u.test(topic)) return "privacy";
|
||||
if (/(잡담|주제|오프토픽|off-topic)/iu.test(topic)) return "off-topic";
|
||||
return null;
|
||||
}
|
||||
|
||||
function legacyLookupRule(topic: string): z.infer<typeof resultSchema> {
|
||||
const resolved = resolveLegacyTopic(topic);
|
||||
return {
|
||||
topic,
|
||||
text: resolved ? extractRuleSection(resolved) : RULES_TEXT.trim(),
|
||||
source: "community-rules",
|
||||
};
|
||||
}
|
||||
|
||||
export const lookupRuleTool: Tool<
|
||||
z.infer<typeof argsSchema>,
|
||||
z.infer<typeof resultSchema>
|
||||
@@ -45,11 +91,34 @@ export const lookupRuleTool: Tool<
|
||||
"광고, 도배, 욕설, 신고, 제재, 이의 제기, 개인정보 같은 moderation 규칙을 조회한다.",
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
execute(args) {
|
||||
return Promise.resolve({
|
||||
topic: args.topic,
|
||||
text: extractRuleSection(args.topic),
|
||||
source: "community-rules",
|
||||
});
|
||||
async execute(args, ctx) {
|
||||
if (ctx.memoryService && getRagEnabled()) {
|
||||
try {
|
||||
const docs = await ctx.memoryService.longTerm.search(args.topic, {
|
||||
category: "rule",
|
||||
skill: "moderation",
|
||||
topK: args.topK ?? 3,
|
||||
});
|
||||
if (docs.length > 0) {
|
||||
return {
|
||||
topic: args.topic,
|
||||
text: docs.map((doc) => doc.text).join("\n\n"),
|
||||
source: "knowledge_documents",
|
||||
matches: docs.map((doc) => ({
|
||||
id: doc.id,
|
||||
score: doc.score,
|
||||
text: doc.text,
|
||||
})),
|
||||
};
|
||||
}
|
||||
} catch (error) {
|
||||
getRequestLogger().warn(
|
||||
{ err: error, topic: args.topic },
|
||||
"[lookup-rule] Knowledge retrieval failed; using local rules",
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
return legacyLookupRule(args.topic);
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,56 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import type { MemoryService } from "../../memory/memory-types.js";
|
||||
import { lookupCommunityRuleTool } from "./lookup-community-rule.js";
|
||||
|
||||
const failingMemoryService = {
|
||||
longTerm: {
|
||||
search: () => Promise.reject(new Error("retrieval failed")),
|
||||
},
|
||||
} as unknown as MemoryService;
|
||||
|
||||
describe("lookupCommunityRuleTool", () => {
|
||||
it("accepts natural-language topics and falls back to constants", async () => {
|
||||
const parsed = lookupCommunityRuleTool.argsSchema.parse({
|
||||
topic: "디스코드 안내",
|
||||
});
|
||||
const result = await lookupCommunityRuleTool.execute(parsed, {});
|
||||
|
||||
expect(result.source).toBe("constants");
|
||||
expect(result.text).toContain("디스코드");
|
||||
});
|
||||
|
||||
it("uses retrieved onboarding knowledge when available", async () => {
|
||||
const memoryService = {
|
||||
longTerm: {
|
||||
search: () =>
|
||||
Promise.resolve([
|
||||
{
|
||||
category: "onboarding-step",
|
||||
id: "doc-1",
|
||||
score: 0.91,
|
||||
text: "디스코드 닉네임은 롤 닉네임과 맞춰주세요.",
|
||||
},
|
||||
]),
|
||||
},
|
||||
} as unknown as MemoryService;
|
||||
|
||||
const result = await lookupCommunityRuleTool.execute(
|
||||
{ topic: "디스코드 닉네임" },
|
||||
{ memoryService },
|
||||
);
|
||||
|
||||
expect(result.source).toBe("knowledge_documents");
|
||||
expect(result.matches?.[0]?.id).toBe("doc-1");
|
||||
expect(result.text).toContain("롤 닉네임");
|
||||
});
|
||||
|
||||
it("falls back to constants when knowledge retrieval fails", async () => {
|
||||
const result = await lookupCommunityRuleTool.execute(
|
||||
{ topic: "닉네임 형식" },
|
||||
{ memoryService: failingMemoryService },
|
||||
);
|
||||
|
||||
expect(result.source).toBe("constants");
|
||||
expect(result.text).toContain("닉네임");
|
||||
});
|
||||
});
|
||||
@@ -1,4 +1,6 @@
|
||||
import { z } from "zod";
|
||||
import { getRagEnabled } from "../../config.js";
|
||||
import { getRequestLogger } from "../../observability/context.js";
|
||||
import {
|
||||
DEADLINE_NEAR_THRESHOLD_MIN,
|
||||
DISCORD_GUIDE_TEXT,
|
||||
@@ -10,23 +12,34 @@ import {
|
||||
import type { Tool } from "../tool.js";
|
||||
|
||||
const argsSchema = z.object({
|
||||
topic: z.enum([
|
||||
"age",
|
||||
"tier-codes",
|
||||
"discord-link",
|
||||
"heart-rule",
|
||||
"nickname-format",
|
||||
"deadline",
|
||||
]),
|
||||
topic: z.string().min(1).describe("검색할 온보딩 규칙 주제"),
|
||||
topK: z.number().int().min(1).max(10).optional(),
|
||||
});
|
||||
|
||||
const resultSchema = z.object({
|
||||
topic: argsSchema.shape.topic,
|
||||
text: z.string(),
|
||||
source: z.literal("constants"),
|
||||
source: z.enum(["constants", "knowledge_documents"]),
|
||||
matches: z
|
||||
.array(
|
||||
z.object({
|
||||
id: z.string(),
|
||||
score: z.number(),
|
||||
text: z.string(),
|
||||
}),
|
||||
)
|
||||
.optional(),
|
||||
});
|
||||
|
||||
const TOPIC_TEXT: Record<z.infer<typeof argsSchema>["topic"], string> = {
|
||||
type LegacyTopic =
|
||||
| "age"
|
||||
| "tier-codes"
|
||||
| "discord-link"
|
||||
| "heart-rule"
|
||||
| "nickname-format"
|
||||
| "deadline";
|
||||
|
||||
const TOPIC_TEXT: Record<LegacyTopic, string> = {
|
||||
age: `가입 가능 연령은 ${MIN_AGE}세 이상이에요.`,
|
||||
"tier-codes": `사용 가능한 티어 코드는 ${TIER_CODES_TEXT}예요.`,
|
||||
"discord-link": DISCORD_GUIDE_TEXT,
|
||||
@@ -35,20 +48,74 @@ const TOPIC_TEXT: Record<z.infer<typeof argsSchema>["topic"], string> = {
|
||||
deadline: `데드라인이 ${DEADLINE_NEAR_THRESHOLD_MIN}분 이하로 남으면 마감이 임박한 상태로 안내해요.`,
|
||||
};
|
||||
|
||||
function resolveLegacyTopic(topic: string): LegacyTopic | null {
|
||||
if (
|
||||
topic === "age" ||
|
||||
topic === "tier-codes" ||
|
||||
topic === "discord-link" ||
|
||||
topic === "heart-rule" ||
|
||||
topic === "nickname-format" ||
|
||||
topic === "deadline"
|
||||
) {
|
||||
return topic;
|
||||
}
|
||||
if (/(나이|연령|age)/iu.test(topic)) return "age";
|
||||
if (/(티어|tier|랭크)/iu.test(topic)) return "tier-codes";
|
||||
if (/(디스코드|디코|discord)/iu.test(topic)) return "discord-link";
|
||||
if (/(하트|인증|사진|heart)/iu.test(topic)) return "heart-rule";
|
||||
if (/(닉네임|형식|이름|nickname)/iu.test(topic)) return "nickname-format";
|
||||
if (/(마감|데드라인|deadline|시간)/iu.test(topic)) return "deadline";
|
||||
return null;
|
||||
}
|
||||
|
||||
function legacyLookupCommunityRule(topic: string): z.infer<typeof resultSchema> {
|
||||
const resolved = resolveLegacyTopic(topic);
|
||||
return {
|
||||
topic,
|
||||
text: resolved
|
||||
? TOPIC_TEXT[resolved]
|
||||
: Object.values(TOPIC_TEXT).join("\n"),
|
||||
source: "constants",
|
||||
};
|
||||
}
|
||||
|
||||
export const lookupCommunityRuleTool: Tool<
|
||||
z.infer<typeof argsSchema>,
|
||||
z.infer<typeof resultSchema>
|
||||
> = {
|
||||
name: "lookup-community-rule",
|
||||
description:
|
||||
"나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 상수에서 조회한다.",
|
||||
"나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 조회한다.",
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
execute(args) {
|
||||
return Promise.resolve({
|
||||
topic: args.topic,
|
||||
text: TOPIC_TEXT[args.topic],
|
||||
source: "constants",
|
||||
});
|
||||
async execute(args, ctx) {
|
||||
if (ctx.memoryService && getRagEnabled()) {
|
||||
try {
|
||||
const docs = await ctx.memoryService.longTerm.search(args.topic, {
|
||||
category: "onboarding-step",
|
||||
skill: "onboarding",
|
||||
topK: args.topK ?? 3,
|
||||
});
|
||||
if (docs.length > 0) {
|
||||
return {
|
||||
topic: args.topic,
|
||||
text: docs.map((doc) => doc.text).join("\n\n"),
|
||||
source: "knowledge_documents",
|
||||
matches: docs.map((doc) => ({
|
||||
id: doc.id,
|
||||
score: doc.score,
|
||||
text: doc.text,
|
||||
})),
|
||||
};
|
||||
}
|
||||
} catch (error) {
|
||||
getRequestLogger().warn(
|
||||
{ err: error, topic: args.topic },
|
||||
"[lookup-community-rule] Knowledge retrieval failed; using constants",
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
return legacyLookupCommunityRule(args.topic);
|
||||
},
|
||||
};
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import type { MemoryService } from "../memory/memory-types.js";
|
||||
import type { NatsClient } from "@common/nats";
|
||||
import type { RoomContextService } from "@room/room-context-service";
|
||||
import type { ZodType } from "zod";
|
||||
@@ -11,6 +12,7 @@ export interface ToolContext {
|
||||
userId?: string | undefined;
|
||||
session?: OnboardingSession | null | undefined;
|
||||
garnetClient?: GarnetClient | undefined;
|
||||
memoryService?: MemoryService | undefined;
|
||||
roomContextService?: RoomContextService | undefined;
|
||||
toolRegistry?: ToolRegistry | undefined;
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user