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
@@ -30,6 +30,7 @@
|
|||||||
"eval:tournament": "node --import tsx src/eval/cli.ts tournament",
|
"eval:tournament": "node --import tsx src/eval/cli.ts tournament",
|
||||||
"eval:tournament:moderation": "node --import tsx src/eval/cli.ts tournament --skill=moderation",
|
"eval:tournament:moderation": "node --import tsx src/eval/cli.ts tournament --skill=moderation",
|
||||||
"eval:tournament-results": "node --import tsx src/eval/cli.ts tournament-results",
|
"eval:tournament-results": "node --import tsx src/eval/cli.ts tournament-results",
|
||||||
|
"ingest:knowledge": "node --import tsx scripts/ingest-knowledge.ts",
|
||||||
"review:list": "node --import tsx src/operations/cli.ts review:list",
|
"review:list": "node --import tsx src/operations/cli.ts review:list",
|
||||||
"review:show": "node --import tsx src/operations/cli.ts review:show",
|
"review:show": "node --import tsx src/operations/cli.ts review:show",
|
||||||
"review:resolve": "node --import tsx src/operations/cli.ts review:resolve",
|
"review:resolve": "node --import tsx src/operations/cli.ts review:resolve",
|
||||||
|
|||||||
@@ -0,0 +1,67 @@
|
|||||||
|
import { loadEnvironmentFromNodeEnv } from "../src/common/env-loader.js";
|
||||||
|
|
||||||
|
loadEnvironmentFromNodeEnv();
|
||||||
|
|
||||||
|
const { initLogger, getLogger } = await import("../src/observability/logger.js");
|
||||||
|
initLogger();
|
||||||
|
const logger = getLogger();
|
||||||
|
const { GarnetClient } = await import("../src/common/garnet.js");
|
||||||
|
const { getRawSecret } = await import("../src/common/secret-manager.js");
|
||||||
|
const { initMongoDB, closeMongoDB } = await import("../src/common/mongodb.js");
|
||||||
|
const { createMemoryService } = await import("../src/memory/memory-service.js");
|
||||||
|
const { ingestMarkdownResources } = await import("../src/memory/knowledge-ingest.js");
|
||||||
|
|
||||||
|
function firstNonEmpty(
|
||||||
|
...values: Array<string | null | undefined>
|
||||||
|
): string | undefined {
|
||||||
|
for (const value of values) {
|
||||||
|
if (value?.trim()) {
|
||||||
|
return value.trim();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
|
||||||
|
const dryRun = process.argv.includes("--dry-run");
|
||||||
|
const mongoConnectionString = firstNonEmpty(
|
||||||
|
getRawSecret("MONGODB_CONNECTION_STRING"),
|
||||||
|
process.env["MONGODB_CONNECTION_STRING"],
|
||||||
|
);
|
||||||
|
|
||||||
|
if (!mongoConnectionString) {
|
||||||
|
throw new Error("MONGODB_CONNECTION_STRING is required for knowledge ingest");
|
||||||
|
}
|
||||||
|
|
||||||
|
const garnetClient = new GarnetClient();
|
||||||
|
await garnetClient.connect();
|
||||||
|
|
||||||
|
try {
|
||||||
|
const mongoConnection = await initMongoDB(mongoConnectionString);
|
||||||
|
const memoryService = createMemoryService({
|
||||||
|
garnetClient,
|
||||||
|
mongooseConnection: mongoConnection,
|
||||||
|
});
|
||||||
|
|
||||||
|
const [onboarding, moderation] = await Promise.all([
|
||||||
|
ingestMarkdownResources(memoryService, {
|
||||||
|
baseDir: "src/skills/onboarding/resources",
|
||||||
|
category: "onboarding-step",
|
||||||
|
dryRun,
|
||||||
|
skill: "onboarding",
|
||||||
|
}),
|
||||||
|
ingestMarkdownResources(memoryService, {
|
||||||
|
baseDir: "src/skills/moderation/resources",
|
||||||
|
category: "rule",
|
||||||
|
dryRun,
|
||||||
|
skill: "moderation",
|
||||||
|
}),
|
||||||
|
]);
|
||||||
|
|
||||||
|
logger.info(
|
||||||
|
{ dryRun, moderation, onboarding },
|
||||||
|
"✓ Knowledge ingest completed",
|
||||||
|
);
|
||||||
|
} finally {
|
||||||
|
await closeMongoDB();
|
||||||
|
await garnetClient.close();
|
||||||
|
}
|
||||||
@@ -5,8 +5,11 @@ import {
|
|||||||
getAlertThresholdEvalScoreDropPct,
|
getAlertThresholdEvalScoreDropPct,
|
||||||
getAlertThresholdLlmErrorRate,
|
getAlertThresholdLlmErrorRate,
|
||||||
getAlertThresholdP95LatencyMs,
|
getAlertThresholdP95LatencyMs,
|
||||||
|
getEmbeddingModel,
|
||||||
|
getEmbeddingProvider,
|
||||||
getPhoenixLogPrompts,
|
getPhoenixLogPrompts,
|
||||||
getPhoenixOtlpEndpoint,
|
getPhoenixOtlpEndpoint,
|
||||||
|
getRagEnabled,
|
||||||
getSlackAlertWebhookUrl,
|
getSlackAlertWebhookUrl,
|
||||||
getSlackWebhookTimeoutMs,
|
getSlackWebhookTimeoutMs,
|
||||||
getSupervisorLlmResponseEnabled,
|
getSupervisorLlmResponseEnabled,
|
||||||
@@ -21,6 +24,9 @@ const ENV_KEYS = [
|
|||||||
"ALERT_THRESHOLD_LLM_ERROR_RATE_ONBOARDING",
|
"ALERT_THRESHOLD_LLM_ERROR_RATE_ONBOARDING",
|
||||||
"ALERT_THRESHOLD_P95_LATENCY_MS",
|
"ALERT_THRESHOLD_P95_LATENCY_MS",
|
||||||
"ALERT_THRESHOLD_P95_LATENCY_MS_ONBOARDING",
|
"ALERT_THRESHOLD_P95_LATENCY_MS_ONBOARDING",
|
||||||
|
"AGENT_RAG_ENABLED",
|
||||||
|
"EMBEDDING_MODEL",
|
||||||
|
"EMBEDDING_PROVIDER",
|
||||||
"PHOENIX_LOG_PROMPTS",
|
"PHOENIX_LOG_PROMPTS",
|
||||||
"PHOENIX_OTLP_ENDPOINT",
|
"PHOENIX_OTLP_ENDPOINT",
|
||||||
"SLACK_ALERT_WEBHOOK_URL",
|
"SLACK_ALERT_WEBHOOK_URL",
|
||||||
@@ -77,6 +83,20 @@ describe("config", () => {
|
|||||||
expect(getPhoenixLogPrompts()).toBe(true);
|
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", () => {
|
it("enables supervisor LLM user messages by default with env override", () => {
|
||||||
expect(getSupervisorLlmResponseEnabled()).toBe(true);
|
expect(getSupervisorLlmResponseEnabled()).toBe(true);
|
||||||
|
|
||||||
|
|||||||
@@ -129,6 +129,47 @@ export function getPhoenixLogPrompts(): boolean {
|
|||||||
return getBoolean("PHOENIX_LOG_PROMPTS", false);
|
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 {
|
export function getRequestSubject(): string {
|
||||||
return (
|
return (
|
||||||
process.env["AGENT_REQUEST_SUBJECT"]?.trim() || "lolympus-agent.request"
|
process.env["AGENT_REQUEST_SUBJECT"]?.trim() || "lolympus-agent.request"
|
||||||
|
|||||||
+8
-1
@@ -49,6 +49,7 @@ import type {
|
|||||||
EvalReportSummary,
|
EvalReportSummary,
|
||||||
EvalSummaryDelta,
|
EvalSummaryDelta,
|
||||||
} from "./types.js";
|
} from "./types.js";
|
||||||
|
import { createMemoryService } from "../memory/memory-service.js";
|
||||||
|
|
||||||
const DEFAULT_REPORTS_DIR = "eval-reports";
|
const DEFAULT_REPORTS_DIR = "eval-reports";
|
||||||
const LEGACY_BASELINE_FILE = `${DEFAULT_REPORTS_DIR}/baseline.json`;
|
const LEGACY_BASELINE_FILE = `${DEFAULT_REPORTS_DIR}/baseline.json`;
|
||||||
@@ -67,13 +68,19 @@ interface SkillRunnerDeps {
|
|||||||
}
|
}
|
||||||
|
|
||||||
const SKILL_RUNNER_FACTORIES: Record<string, (deps: SkillRunnerDeps) => Skill> = {
|
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) =>
|
onboarding: (deps) =>
|
||||||
new OnboardingSkill(
|
new OnboardingSkill(
|
||||||
deps.garnet,
|
deps.garnet,
|
||||||
deps.llm,
|
deps.llm,
|
||||||
deps.room,
|
deps.room,
|
||||||
noopShadowEvalPublisher,
|
noopShadowEvalPublisher,
|
||||||
|
undefined,
|
||||||
|
createMemoryService({ garnetClient: deps.garnet }),
|
||||||
),
|
),
|
||||||
supervisor: (deps) =>
|
supervisor: (deps) =>
|
||||||
new SupervisorSkill(deps.garnet, {
|
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 { LlmClient } = await import("./llm/index.js");
|
||||||
const { getRawSecret, getSecret } = await import("./common/secret-manager.js");
|
const { getRawSecret, getSecret } = await import("./common/secret-manager.js");
|
||||||
const { initMongoDB, closeMongoDB } = await import("./common/mongodb.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 { RoomContextService } = await import("./room-context/index.js");
|
||||||
const { startMetricsServer, stopMetricsServer } = await import(
|
const { startMetricsServer, stopMetricsServer } = await import(
|
||||||
"./observability/metrics-server.js"
|
"./observability/metrics-server.js"
|
||||||
@@ -201,13 +202,14 @@ async function bootstrap(): Promise<void> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// MongoDB + RoomContextService setup (optional)
|
// MongoDB + RoomContextService setup (optional)
|
||||||
|
let mongoConnection: Awaited<ReturnType<typeof initMongoDB>> | undefined;
|
||||||
let roomContextService: InstanceType<typeof RoomContextService> | undefined;
|
let roomContextService: InstanceType<typeof RoomContextService> | undefined;
|
||||||
const mongoConnectionString = firstNonEmpty(
|
const mongoConnectionString = firstNonEmpty(
|
||||||
getSecret("MONGODB_CONNECTION_STRING"),
|
getSecret("MONGODB_CONNECTION_STRING"),
|
||||||
process.env["MONGODB_CONNECTION_STRING"],
|
process.env["MONGODB_CONNECTION_STRING"],
|
||||||
);
|
);
|
||||||
if (mongoConnectionString) {
|
if (mongoConnectionString) {
|
||||||
await initMongoDB(mongoConnectionString);
|
mongoConnection = await initMongoDB(mongoConnectionString);
|
||||||
// 시크릿의 projectId를 환경변수로 전파 (config.ts에서 참조)
|
// 시크릿의 projectId를 환경변수로 전파 (config.ts에서 참조)
|
||||||
const mongoProjectId = firstNonEmpty(
|
const mongoProjectId = firstNonEmpty(
|
||||||
getSecret("MONGODB_PROJECT_ID"),
|
getSecret("MONGODB_PROJECT_ID"),
|
||||||
@@ -222,6 +224,11 @@ async function bootstrap(): Promise<void> {
|
|||||||
logger.warn("[MongoDB] No connection string configured — room context disabled");
|
logger.warn("[MongoDB] No connection string configured — room context disabled");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
const memoryService = createMemoryService({
|
||||||
|
garnetClient,
|
||||||
|
mongooseConnection: mongoConnection,
|
||||||
|
});
|
||||||
|
|
||||||
// Agent setup
|
// Agent setup
|
||||||
const conversationStore = new ConversationStore(garnetClient);
|
const conversationStore = new ConversationStore(garnetClient);
|
||||||
const skillRegistry = SkillRegistry.load(resolve(process.cwd(), "src", "skills"));
|
const skillRegistry = SkillRegistry.load(resolve(process.cwd(), "src", "skills"));
|
||||||
@@ -259,6 +266,7 @@ async function bootstrap(): Promise<void> {
|
|||||||
factory({
|
factory({
|
||||||
garnetClient,
|
garnetClient,
|
||||||
llmClient,
|
llmClient,
|
||||||
|
memoryService,
|
||||||
natsClient,
|
natsClient,
|
||||||
roomContextService,
|
roomContextService,
|
||||||
shadowEvalBus,
|
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 { ModerationSkill } from "./skill.js";
|
||||||
|
|
||||||
export function createModerationSkill(deps: SkillDeps): Skill {
|
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";
|
} from "@agent/types";
|
||||||
import type { LlmClient } from "@llm/llm-client";
|
import type { LlmClient } from "@llm/llm-client";
|
||||||
import type { ChatMessage } from "@llm/types";
|
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 { Skill } from "@skills/skill";
|
||||||
import type { SkillCapabilityCard } from "@skills/skill-loader";
|
import type { SkillCapabilityCard } from "@skills/skill-loader";
|
||||||
import { lookupRuleTool } from "@tools/moderation/lookup-rule";
|
import { lookupRuleTool } from "@tools/moderation/lookup-rule";
|
||||||
|
import { getRagEnabled } from "../../config.js";
|
||||||
import { classifyModerationIntent, type ModerationIntent } from "./intents.js";
|
import { classifyModerationIntent, type ModerationIntent } from "./intents.js";
|
||||||
import { MODERATION_PROMPT_DATA } from "./prompt-data.js";
|
import { MODERATION_PROMPT_DATA } from "./prompt-data.js";
|
||||||
import { createModerationToolRegistry } from "./tools.js";
|
import { createModerationToolRegistry } from "./tools.js";
|
||||||
@@ -137,18 +140,50 @@ function resolveRuleTopic(message: string): RuleTopic | null {
|
|||||||
async function lookupReferenceText(
|
async function lookupReferenceText(
|
||||||
intent: ModerationIntent,
|
intent: ModerationIntent,
|
||||||
message: string,
|
message: string,
|
||||||
|
memoryService?: MemoryService,
|
||||||
): Promise<string | undefined> {
|
): Promise<string | undefined> {
|
||||||
if (intent.kind !== "rule-question") {
|
if (intent.kind !== "rule-question") {
|
||||||
return undefined;
|
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);
|
const topic = resolveRuleTopic(message);
|
||||||
if (!topic) {
|
if (!topic) {
|
||||||
return undefined;
|
return undefined;
|
||||||
}
|
}
|
||||||
const result = await lookupRuleTool.execute({ topic }, {});
|
const result = await lookupRuleTool.execute(
|
||||||
|
{ topic },
|
||||||
|
{ memoryService },
|
||||||
|
);
|
||||||
return result.text;
|
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 {
|
function templateForIntent(intent: ModerationIntent): string {
|
||||||
switch (intent.kind) {
|
switch (intent.kind) {
|
||||||
case "appeal":
|
case "appeal":
|
||||||
@@ -169,7 +204,10 @@ export class ModerationSkill implements Skill {
|
|||||||
readonly priority = 50;
|
readonly priority = 50;
|
||||||
private readonly toolRegistry = createModerationToolRegistry();
|
private readonly toolRegistry = createModerationToolRegistry();
|
||||||
|
|
||||||
constructor(private readonly llmClient: LlmClient) {}
|
constructor(
|
||||||
|
private readonly llmClient: LlmClient,
|
||||||
|
private readonly memoryService?: MemoryService | undefined,
|
||||||
|
) {}
|
||||||
|
|
||||||
canHandle(request: AgentRequest): boolean {
|
canHandle(request: AgentRequest): boolean {
|
||||||
return request.skill === this.name;
|
return request.skill === this.name;
|
||||||
@@ -187,6 +225,7 @@ export class ModerationSkill implements Skill {
|
|||||||
const referenceText = await lookupReferenceText(
|
const referenceText = await lookupReferenceText(
|
||||||
classified.intent,
|
classified.intent,
|
||||||
request.userMessage ?? "",
|
request.userMessage ?? "",
|
||||||
|
this.memoryService,
|
||||||
);
|
);
|
||||||
const metadata = {
|
const metadata = {
|
||||||
intent: classified.intent.kind,
|
intent: classified.intent.kind,
|
||||||
|
|||||||
@@ -15,5 +15,6 @@ export function createOnboardingSkill(deps: SkillDeps): Skill {
|
|||||||
deps.roomContextService,
|
deps.roomContextService,
|
||||||
deps.shadowEvalBus,
|
deps.shadowEvalBus,
|
||||||
deps.natsClient,
|
deps.natsClient,
|
||||||
|
deps.memoryService,
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
@@ -123,6 +123,27 @@ function formatUserProfile(profile: UserProfile | null | undefined): string {
|
|||||||
].join('\n');
|
].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 {
|
export function personaLayer(): string {
|
||||||
return ONBOARDING_PROMPT_DATA.persona;
|
return ONBOARDING_PROMPT_DATA.persona;
|
||||||
}
|
}
|
||||||
@@ -201,5 +222,6 @@ export function contextLayer(context: PromptContext): string {
|
|||||||
formatUserProfile(context.userProfile),
|
formatUserProfile(context.userProfile),
|
||||||
]
|
]
|
||||||
: []),
|
: []),
|
||||||
|
...formatRetrievedKnowledge(context),
|
||||||
].join('\n');
|
].join('\n');
|
||||||
}
|
}
|
||||||
@@ -2,12 +2,14 @@ import type { AgentRequest, ConversationMessage } from '@agent/types';
|
|||||||
import type { GarnetClient } from '@common/garnet';
|
import type { GarnetClient } from '@common/garnet';
|
||||||
import { getConversationSummaryKey } from '@conv/conversation-store';
|
import { getConversationSummaryKey } from '@conv/conversation-store';
|
||||||
import type { ChatMessage } from '@llm/types';
|
import type { ChatMessage } from '@llm/types';
|
||||||
|
import type { MemoryService } from '../../../memory/memory-types.js';
|
||||||
import { getRequestLogger } from '@obs/context';
|
import { getRequestLogger } from '@obs/context';
|
||||||
import type { RoomContextService } from '@room/room-context-service';
|
import type { RoomContextService } from '@room/room-context-service';
|
||||||
import { meetsTrustTier } from '../../../eval/governance/trust.js';
|
import { meetsTrustTier } from '../../../eval/governance/trust.js';
|
||||||
import {
|
import {
|
||||||
getAgentTrustMinTier,
|
getAgentTrustMinTier,
|
||||||
getAgentUserMemoryEnabled,
|
getAgentUserMemoryEnabled,
|
||||||
|
getRagEnabled,
|
||||||
getPromptVariantId,
|
getPromptVariantId,
|
||||||
} from '../../../config.js';
|
} from '../../../config.js';
|
||||||
import {
|
import {
|
||||||
@@ -22,6 +24,7 @@ import type { OnboardingSession, PromptContext } from '../types.js';
|
|||||||
interface MessageBuilderDeps {
|
interface MessageBuilderDeps {
|
||||||
blackboardStore: OnboardingBlackboardStore;
|
blackboardStore: OnboardingBlackboardStore;
|
||||||
garnetClient: GarnetClient;
|
garnetClient: GarnetClient;
|
||||||
|
memoryService?: MemoryService | undefined;
|
||||||
roomContextService?: RoomContextService | undefined;
|
roomContextService?: RoomContextService | undefined;
|
||||||
userMemoryStore: UserMemoryStore;
|
userMemoryStore: UserMemoryStore;
|
||||||
}
|
}
|
||||||
@@ -67,6 +70,32 @@ async function loadConversationSummary(
|
|||||||
return (await garnetClient.getString(key)) ?? undefined;
|
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(
|
export async function buildLlmMessages(
|
||||||
deps: MessageBuilderDeps,
|
deps: MessageBuilderDeps,
|
||||||
input: MessageBuilderInput,
|
input: MessageBuilderInput,
|
||||||
@@ -85,7 +114,34 @@ export async function buildLlmMessages(
|
|||||||
return undefined;
|
return undefined;
|
||||||
})
|
})
|
||||||
: Promise.resolve(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) => {
|
? deps.userMemoryStore.load(request.userId).catch((error) => {
|
||||||
logger.warn(
|
logger.warn(
|
||||||
{ err: error },
|
{ err: error },
|
||||||
@@ -94,20 +150,40 @@ export async function buildLlmMessages(
|
|||||||
return null;
|
return null;
|
||||||
})
|
})
|
||||||
: Promise.resolve(null);
|
: Promise.resolve(null);
|
||||||
const [blackboard, summary, roomContext, userProfile] = await Promise.all([
|
const [
|
||||||
deps.blackboardStore.load(request.chatroomId, request.userId),
|
workingMemory,
|
||||||
loadConversationSummary(deps.garnetClient, request.chatroomId, request.userId),
|
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,
|
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 = {
|
const context: PromptContext = {
|
||||||
blackboard,
|
blackboard,
|
||||||
conversationHistory,
|
conversationHistory:
|
||||||
|
workingMemory && workingMemory.conversationHistory.length > 0
|
||||||
|
? workingMemory.conversationHistory
|
||||||
|
: conversationHistory,
|
||||||
roomContext,
|
roomContext,
|
||||||
summary,
|
retrievedKnowledge: workingMemory?.retrievedKnowledge,
|
||||||
|
summary: workingMemory?.summary ?? legacySummary,
|
||||||
userMessage: buildPromptUserMessage(request, derived),
|
userMessage: buildPromptUserMessage(request, derived),
|
||||||
userProfile,
|
userProfile: workingMemory?.userProfile ?? legacyUserProfile,
|
||||||
};
|
};
|
||||||
|
|
||||||
const builder = PromptBuilder.forDerived(derived, session, context);
|
const builder = PromptBuilder.forDerived(derived, session, context);
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
import type { AgentRequest, AgentResponse, ConversationMessage } from '@agent/types';
|
import type { AgentRequest, AgentResponse, ConversationMessage } from '@agent/types';
|
||||||
import type { GarnetClient } from '@common/garnet';
|
import type { GarnetClient } from '@common/garnet';
|
||||||
import type { NatsClient } from '@common/nats';
|
import type { NatsClient } from '@common/nats';
|
||||||
|
import type { MemoryService } from '../../memory/memory-types.js';
|
||||||
import { getContext, getRequestLogger } from '@obs/context';
|
import { getContext, getRequestLogger } from '@obs/context';
|
||||||
import type { LlmClient } from '@llm/llm-client';
|
import type { LlmClient } from '@llm/llm-client';
|
||||||
import type { RoomContextService } from '@room/room-context-service';
|
import type { RoomContextService } from '@room/room-context-service';
|
||||||
@@ -112,10 +113,17 @@ export class OnboardingSkill implements Skill {
|
|||||||
private readonly roomContextService?: RoomContextService,
|
private readonly roomContextService?: RoomContextService,
|
||||||
shadowEvalPublisher?: ShadowEvalPublisher,
|
shadowEvalPublisher?: ShadowEvalPublisher,
|
||||||
private readonly natsClient?: Pick<NatsClient, 'request'>,
|
private readonly natsClient?: Pick<NatsClient, 'request'>,
|
||||||
|
private readonly memoryService?: MemoryService,
|
||||||
) {
|
) {
|
||||||
this.classifier = new OnboardingIntentClassifier(llmClient);
|
this.classifier = new OnboardingIntentClassifier(llmClient);
|
||||||
this.blackboardStore = new OnboardingBlackboardStore(garnetClient);
|
this.blackboardStore = new OnboardingBlackboardStore(
|
||||||
this.userMemoryStore = new UserMemoryStore(garnetClient);
|
garnetClient,
|
||||||
|
memoryService?.session,
|
||||||
|
);
|
||||||
|
this.userMemoryStore = new UserMemoryStore(
|
||||||
|
garnetClient,
|
||||||
|
memoryService?.longTerm,
|
||||||
|
);
|
||||||
this.orchestrator = new OnboardingOrchestrator(llmClient);
|
this.orchestrator = new OnboardingOrchestrator(llmClient);
|
||||||
this.shadowEvalPublisher = shadowEvalPublisher ?? new ShadowEvalBus(garnetClient);
|
this.shadowEvalPublisher = shadowEvalPublisher ?? new ShadowEvalBus(garnetClient);
|
||||||
this.toolRegistry = createOnboardingToolRegistry();
|
this.toolRegistry = createOnboardingToolRegistry();
|
||||||
@@ -381,6 +389,7 @@ export class OnboardingSkill implements Skill {
|
|||||||
{
|
{
|
||||||
blackboardStore: this.blackboardStore,
|
blackboardStore: this.blackboardStore,
|
||||||
garnetClient: this.garnetClient,
|
garnetClient: this.garnetClient,
|
||||||
|
memoryService: this.memoryService,
|
||||||
roomContextService: this.roomContextService,
|
roomContextService: this.roomContextService,
|
||||||
userMemoryStore: this.userMemoryStore,
|
userMemoryStore: this.userMemoryStore,
|
||||||
},
|
},
|
||||||
@@ -474,6 +483,7 @@ export class OnboardingSkill implements Skill {
|
|||||||
userId: request.userId,
|
userId: request.userId,
|
||||||
session,
|
session,
|
||||||
garnetClient: this.garnetClient,
|
garnetClient: this.garnetClient,
|
||||||
|
memoryService: this.memoryService,
|
||||||
roomContextService: this.roomContextService,
|
roomContextService: this.roomContextService,
|
||||||
toolRegistry: this.toolRegistry,
|
toolRegistry: this.toolRegistry,
|
||||||
};
|
};
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
import type { GarnetClient } from "@common/garnet";
|
import type { GarnetClient } from "@common/garnet";
|
||||||
|
import type { SessionMemory } from "../../../memory/memory-types.js";
|
||||||
import { getBlackboardTtlSeconds } from "../../../config.js";
|
import { getBlackboardTtlSeconds } from "../../../config.js";
|
||||||
import type { Blackboard } from "../types.js";
|
import type { Blackboard } from "../types.js";
|
||||||
|
|
||||||
@@ -37,9 +38,21 @@ function mergeBlackboard(
|
|||||||
}
|
}
|
||||||
|
|
||||||
export class OnboardingBlackboardStore {
|
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> {
|
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 key = getBlackboardKey(chatroomId, userId);
|
||||||
const saved = await this.garnetClient.getJson<Blackboard>(key);
|
const saved = await this.garnetClient.getJson<Blackboard>(key);
|
||||||
return mergeBlackboard(saved, {});
|
return mergeBlackboard(saved, {});
|
||||||
@@ -50,6 +63,16 @@ export class OnboardingBlackboardStore {
|
|||||||
userId: string,
|
userId: string,
|
||||||
value: Blackboard,
|
value: Blackboard,
|
||||||
): Promise<void> {
|
): Promise<void> {
|
||||||
|
if (this.sessionMemory) {
|
||||||
|
await this.sessionMemory.setBlackboard(
|
||||||
|
"onboarding",
|
||||||
|
chatroomId,
|
||||||
|
userId,
|
||||||
|
value,
|
||||||
|
);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
const key = getBlackboardKey(chatroomId, userId);
|
const key = getBlackboardKey(chatroomId, userId);
|
||||||
await this.garnetClient.setJson(
|
await this.garnetClient.setJson(
|
||||||
key,
|
key,
|
||||||
|
|||||||
@@ -4,6 +4,7 @@ import {
|
|||||||
anonymizeText,
|
anonymizeText,
|
||||||
} from "@eval/anonymize";
|
} from "@eval/anonymize";
|
||||||
import { getAgentUserMemoryTtlDays } from "../../../config.js";
|
import { getAgentUserMemoryTtlDays } from "../../../config.js";
|
||||||
|
import type { LongTermMemory } from "../../../memory/memory-types.js";
|
||||||
import type { DerivedState, Intent } from "./onboarding-state.js";
|
import type { DerivedState, Intent } from "./onboarding-state.js";
|
||||||
|
|
||||||
export type PreferredStyle = "concise" | "neutral" | "warm";
|
export type PreferredStyle = "concise" | "neutral" | "warm";
|
||||||
@@ -86,9 +87,16 @@ function emptyProfile(userId: string, now = nowIso()): UserProfile {
|
|||||||
}
|
}
|
||||||
|
|
||||||
export class UserMemoryStore {
|
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> {
|
async load(userId: string): Promise<UserProfile | null> {
|
||||||
|
if (this.longTermMemory) {
|
||||||
|
return this.longTermMemory.loadUserProfile(userId);
|
||||||
|
}
|
||||||
|
|
||||||
return this.garnetClient.getJson<UserProfile>(profileKey(userId));
|
return this.garnetClient.getJson<UserProfile>(profileKey(userId));
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -125,7 +133,11 @@ export class UserMemoryStore {
|
|||||||
userId: current.userId,
|
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;
|
return next;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -1,4 +1,5 @@
|
|||||||
import type { ConversationMessage } from "@agent/types";
|
import type { ConversationMessage } from "@agent/types";
|
||||||
|
import type { RetrievedDocument } from "../../memory/memory-types.js";
|
||||||
import type { RoomMessage } from "@room/types";
|
import type { RoomMessage } from "@room/types";
|
||||||
import type { UserProfile } from "./state/user-memory.js";
|
import type { UserProfile } from "./state/user-memory.js";
|
||||||
|
|
||||||
@@ -27,6 +28,7 @@ export interface PromptContext {
|
|||||||
blackboard: Blackboard;
|
blackboard: Blackboard;
|
||||||
conversationHistory: ConversationMessage[];
|
conversationHistory: ConversationMessage[];
|
||||||
roomContext?: RoomMessage[] | undefined;
|
roomContext?: RoomMessage[] | undefined;
|
||||||
|
retrievedKnowledge?: RetrievedDocument[] | undefined;
|
||||||
summary?: string | undefined;
|
summary?: string | undefined;
|
||||||
userMessage: string;
|
userMessage: string;
|
||||||
userProfile?: UserProfile | null | undefined;
|
userProfile?: UserProfile | null | undefined;
|
||||||
|
|||||||
@@ -2,6 +2,7 @@ import type { GarnetClient } from "@common/garnet";
|
|||||||
import type { NatsClient } from "@common/nats";
|
import type { NatsClient } from "@common/nats";
|
||||||
import type { ShadowEvalBus } from "@eval/shadow-bus";
|
import type { ShadowEvalBus } from "@eval/shadow-bus";
|
||||||
import type { LlmClient } from "@llm/llm-client";
|
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 { RoomContextService } from "@room/room-context-service";
|
||||||
import type { Skill } from "./skill.js";
|
import type { Skill } from "./skill.js";
|
||||||
import type { SkillRegistry } from "./skill-loader.js";
|
import type { SkillRegistry } from "./skill-loader.js";
|
||||||
@@ -9,6 +10,7 @@ import type { SkillRegistry } from "./skill-loader.js";
|
|||||||
export interface SkillDeps {
|
export interface SkillDeps {
|
||||||
garnetClient: GarnetClient;
|
garnetClient: GarnetClient;
|
||||||
llmClient: LlmClient;
|
llmClient: LlmClient;
|
||||||
|
memoryService?: MemoryService | undefined;
|
||||||
natsClient: NatsClient;
|
natsClient: NatsClient;
|
||||||
roomContextService?: RoomContextService | undefined;
|
roomContextService?: RoomContextService | undefined;
|
||||||
shadowEvalBus: ShadowEvalBus;
|
shadowEvalBus: ShadowEvalBus;
|
||||||
|
|||||||
@@ -1,6 +1,13 @@
|
|||||||
import { describe, expect, it } from "vitest";
|
import { describe, expect, it } from "vitest";
|
||||||
|
import type { MemoryService } from "../../memory/memory-types.js";
|
||||||
import { lookupRuleTool } from "./lookup-rule.js";
|
import { lookupRuleTool } from "./lookup-rule.js";
|
||||||
|
|
||||||
|
const failingMemoryService = {
|
||||||
|
longTerm: {
|
||||||
|
search: () => Promise.reject(new Error("retrieval failed")),
|
||||||
|
},
|
||||||
|
} as unknown as MemoryService;
|
||||||
|
|
||||||
describe("lookupRuleTool", () => {
|
describe("lookupRuleTool", () => {
|
||||||
it("returns the matching community rule section", async () => {
|
it("returns the matching community rule section", async () => {
|
||||||
const result = await lookupRuleTool.execute({ topic: "ads" }, {});
|
const result = await lookupRuleTool.execute({ topic: "ads" }, {});
|
||||||
@@ -10,9 +17,21 @@ describe("lookupRuleTool", () => {
|
|||||||
expect(result.text).toContain("홍보");
|
expect(result.text).toContain("홍보");
|
||||||
});
|
});
|
||||||
|
|
||||||
it("validates topic enum values", () => {
|
it("accepts natural-language topics and falls back to local rules", async () => {
|
||||||
expect(() =>
|
const parsed = lookupRuleTool.argsSchema.parse({ topic: "광고 기준" });
|
||||||
lookupRuleTool.argsSchema.parse({ topic: "unknown" }),
|
const result = await lookupRuleTool.execute(parsed, {});
|
||||||
).toThrow();
|
|
||||||
|
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 { readFileSync } from "node:fs";
|
||||||
import { fileURLToPath } from "node:url";
|
import { fileURLToPath } from "node:url";
|
||||||
import { z } from "zod";
|
import { z } from "zod";
|
||||||
|
import { getRagEnabled } from "../../config.js";
|
||||||
|
import { getRequestLogger } from "../../observability/context.js";
|
||||||
import type { Tool } from "../tool.js";
|
import type { Tool } from "../tool.js";
|
||||||
|
|
||||||
const argsSchema = z.object({
|
const argsSchema = z.object({
|
||||||
topic: z.enum([
|
topic: z.string().min(1).describe("검색할 규칙 주제"),
|
||||||
"ads",
|
topK: z.number().int().min(1).max(10).optional(),
|
||||||
"appeal",
|
|
||||||
"minor-safety",
|
|
||||||
"off-topic",
|
|
||||||
"privacy",
|
|
||||||
"profanity",
|
|
||||||
"report",
|
|
||||||
"sanctions",
|
|
||||||
"spam",
|
|
||||||
]),
|
|
||||||
});
|
});
|
||||||
|
|
||||||
const resultSchema = z.object({
|
const resultSchema = z.object({
|
||||||
topic: argsSchema.shape.topic,
|
topic: argsSchema.shape.topic,
|
||||||
text: z.string(),
|
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(
|
const RULES_PATH = fileURLToPath(
|
||||||
new URL("../../skills/moderation/resources/community-rules.md", import.meta.url),
|
new URL("../../skills/moderation/resources/community-rules.md", import.meta.url),
|
||||||
@@ -36,6 +47,41 @@ function extractRuleSection(topic: RuleTopic): string {
|
|||||||
return match?.[1]?.trim() || "";
|
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<
|
export const lookupRuleTool: Tool<
|
||||||
z.infer<typeof argsSchema>,
|
z.infer<typeof argsSchema>,
|
||||||
z.infer<typeof resultSchema>
|
z.infer<typeof resultSchema>
|
||||||
@@ -45,11 +91,34 @@ export const lookupRuleTool: Tool<
|
|||||||
"광고, 도배, 욕설, 신고, 제재, 이의 제기, 개인정보 같은 moderation 규칙을 조회한다.",
|
"광고, 도배, 욕설, 신고, 제재, 이의 제기, 개인정보 같은 moderation 규칙을 조회한다.",
|
||||||
argsSchema,
|
argsSchema,
|
||||||
resultSchema,
|
resultSchema,
|
||||||
execute(args) {
|
async execute(args, ctx) {
|
||||||
return Promise.resolve({
|
if (ctx.memoryService && getRagEnabled()) {
|
||||||
topic: args.topic,
|
try {
|
||||||
text: extractRuleSection(args.topic),
|
const docs = await ctx.memoryService.longTerm.search(args.topic, {
|
||||||
source: "community-rules",
|
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 { z } from "zod";
|
||||||
|
import { getRagEnabled } from "../../config.js";
|
||||||
|
import { getRequestLogger } from "../../observability/context.js";
|
||||||
import {
|
import {
|
||||||
DEADLINE_NEAR_THRESHOLD_MIN,
|
DEADLINE_NEAR_THRESHOLD_MIN,
|
||||||
DISCORD_GUIDE_TEXT,
|
DISCORD_GUIDE_TEXT,
|
||||||
@@ -10,23 +12,34 @@ import {
|
|||||||
import type { Tool } from "../tool.js";
|
import type { Tool } from "../tool.js";
|
||||||
|
|
||||||
const argsSchema = z.object({
|
const argsSchema = z.object({
|
||||||
topic: z.enum([
|
topic: z.string().min(1).describe("검색할 온보딩 규칙 주제"),
|
||||||
"age",
|
topK: z.number().int().min(1).max(10).optional(),
|
||||||
"tier-codes",
|
|
||||||
"discord-link",
|
|
||||||
"heart-rule",
|
|
||||||
"nickname-format",
|
|
||||||
"deadline",
|
|
||||||
]),
|
|
||||||
});
|
});
|
||||||
|
|
||||||
const resultSchema = z.object({
|
const resultSchema = z.object({
|
||||||
topic: argsSchema.shape.topic,
|
topic: argsSchema.shape.topic,
|
||||||
text: z.string(),
|
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}세 이상이에요.`,
|
age: `가입 가능 연령은 ${MIN_AGE}세 이상이에요.`,
|
||||||
"tier-codes": `사용 가능한 티어 코드는 ${TIER_CODES_TEXT}예요.`,
|
"tier-codes": `사용 가능한 티어 코드는 ${TIER_CODES_TEXT}예요.`,
|
||||||
"discord-link": DISCORD_GUIDE_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}분 이하로 남으면 마감이 임박한 상태로 안내해요.`,
|
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<
|
export const lookupCommunityRuleTool: Tool<
|
||||||
z.infer<typeof argsSchema>,
|
z.infer<typeof argsSchema>,
|
||||||
z.infer<typeof resultSchema>
|
z.infer<typeof resultSchema>
|
||||||
> = {
|
> = {
|
||||||
name: "lookup-community-rule",
|
name: "lookup-community-rule",
|
||||||
description:
|
description:
|
||||||
"나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 상수에서 조회한다.",
|
"나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 조회한다.",
|
||||||
argsSchema,
|
argsSchema,
|
||||||
resultSchema,
|
resultSchema,
|
||||||
execute(args) {
|
async execute(args, ctx) {
|
||||||
return Promise.resolve({
|
if (ctx.memoryService && getRagEnabled()) {
|
||||||
topic: args.topic,
|
try {
|
||||||
text: TOPIC_TEXT[args.topic],
|
const docs = await ctx.memoryService.longTerm.search(args.topic, {
|
||||||
source: "constants",
|
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 { GarnetClient } from "@common/garnet";
|
||||||
|
import type { MemoryService } from "../memory/memory-types.js";
|
||||||
import type { NatsClient } from "@common/nats";
|
import type { NatsClient } from "@common/nats";
|
||||||
import type { RoomContextService } from "@room/room-context-service";
|
import type { RoomContextService } from "@room/room-context-service";
|
||||||
import type { ZodType } from "zod";
|
import type { ZodType } from "zod";
|
||||||
@@ -11,6 +12,7 @@ export interface ToolContext {
|
|||||||
userId?: string | undefined;
|
userId?: string | undefined;
|
||||||
session?: OnboardingSession | null | undefined;
|
session?: OnboardingSession | null | undefined;
|
||||||
garnetClient?: GarnetClient | undefined;
|
garnetClient?: GarnetClient | undefined;
|
||||||
|
memoryService?: MemoryService | undefined;
|
||||||
roomContextService?: RoomContextService | undefined;
|
roomContextService?: RoomContextService | undefined;
|
||||||
toolRegistry?: ToolRegistry | undefined;
|
toolRegistry?: ToolRegistry | undefined;
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in new issue
Block a user