@lota-sdk/core 0.1.5

package/src/services/learned-skill.service.ts

@@ -0,0 +1,328 @@
+import { recordIdStringSchema } from '@lota-sdk/shared/schemas/common'
+import { BoundQuery } from 'surrealdb'
+import { z } from 'zod'
+
+import { renderLearnedSkillInstructions } from '../ai/definitions'
+import { serverLogger } from '../config/logger'
+import { ensureRecordId } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import { createDefaultEmbeddings } from '../embeddings/provider'
+
+const embeddings = createDefaultEmbeddings()
+
+const PROMOTION_MIN_USES = 5
+const PROMOTION_MIN_SUCCESS_RATE = 0.6
+
+const LearnedSkillRowSchema = z.object({
+  id: recordIdStringSchema,
+  name: z.string(),
+  description: z.string(),
+  instructions: z.string(),
+  triggers: z.array(z.string()).default([]),
+  tags: z.array(z.string()).default([]),
+  examples: z.array(z.string()).default([]),
+  version: z.number().int().default(1),
+  sourceType: z.string(),
+  organizationId: recordIdStringSchema,
+  agentId: z.string().optional(),
+  status: z.enum(['learned', 'verified', 'promoted', 'archived']).default('learned'),
+  confidence: z.number().min(0).max(1).default(0.5),
+  usageCount: z.number().int().default(0),
+  successCount: z.number().int().default(0),
+  supersedes: recordIdStringSchema.optional(),
+  hash: z.string(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date().optional(),
+  lastUsedAt: z.coerce.date().optional(),
+  archivedAt: z.coerce.date().optional(),
+})
+
+type LearnedSkillRow = z.infer<typeof LearnedSkillRowSchema>
+
+const SearchResultRowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  instructions: z.string(),
+  confidence: z.number(),
+  similarity: z.number(),
+})
+
+type SearchResultRow = z.infer<typeof SearchResultRowSchema>
+
+export interface CreateLearnedSkillInput {
+  name: string
+  description: string
+  instructions: string
+  triggers: string[]
+  tags: string[]
+  examples: string[]
+  sourceType: string
+  organizationId: string
+  agentId: string | null
+  confidence: number
+  embedding: number[]
+  hash: string
+}
+
+export interface UpdateLearnedSkillInput {
+  name?: string
+  description?: string
+  instructions?: string
+  triggers?: string[]
+  tags?: string[]
+  examples?: string[]
+  confidence?: number
+  version?: number
+  embedding?: number[]
+  hash?: string
+  supersedes?: string
+}
+
+export interface RetrieveForTurnParams {
+  orgId: string
+  agentId: string
+  query: string
+  limit: number
+  minConfidence: number
+}
+
+class LearnedSkillService {
+  async create(input: CreateLearnedSkillInput): Promise<LearnedSkillRow> {
+    const orgRef = ensureRecordId(input.organizationId, TABLES.ORGANIZATION)
+
+    const data: Record<string, unknown> = {
+      name: input.name,
+      description: input.description,
+      instructions: input.instructions,
+      triggers: input.triggers,
+      tags: input.tags,
+      examples: input.examples,
+      sourceType: input.sourceType,
+      organizationId: orgRef,
+      agentId: input.agentId,
+      confidence: input.confidence,
+      embedding: input.embedding,
+      hash: input.hash,
+    }
+
+    return databaseService.create(TABLES.LEARNED_SKILL, data, LearnedSkillRowSchema)
+  }
+
+  async update(skillId: string, input: UpdateLearnedSkillInput): Promise<LearnedSkillRow> {
+    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+    const data: Record<string, unknown> = { updatedAt: new Date().toISOString() }
+
+    if (input.name !== undefined) data.name = input.name
+    if (input.description !== undefined) data.description = input.description
+    if (input.instructions !== undefined) data.instructions = input.instructions
+    if (input.triggers !== undefined) data.triggers = input.triggers
+    if (input.tags !== undefined) data.tags = input.tags
+    if (input.examples !== undefined) data.examples = input.examples
+    if (input.confidence !== undefined) data.confidence = input.confidence
+    if (input.version !== undefined) data.version = input.version
+    if (input.embedding !== undefined) data.embedding = input.embedding
+    if (input.hash !== undefined) data.hash = input.hash
+    if (input.supersedes !== undefined) data.supersedes = ensureRecordId(input.supersedes, TABLES.LEARNED_SKILL)
+
+    const updated = await databaseService.update(TABLES.LEARNED_SKILL, ref, data, LearnedSkillRowSchema)
+    if (!updated) throw new Error(`Learned skill ${skillId} not found`)
+    return updated
+  }
+
+  async archive(skillId: string): Promise<void> {
+    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+    await databaseService.update(
+      TABLES.LEARNED_SKILL,
+      ref,
+      { status: 'archived', archivedAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
+      LearnedSkillRowSchema,
+    )
+  }
+
+  async getById(skillId: string): Promise<LearnedSkillRow | null> {
+    return databaseService.findOne(
+      TABLES.LEARNED_SKILL,
+      { id: ensureRecordId(skillId, TABLES.LEARNED_SKILL) },
+      LearnedSkillRowSchema,
+    )
+  }
+
+  async searchForTurn(params: RetrieveForTurnParams): Promise<SearchResultRow[]> {
+    const orgRef = ensureRecordId(params.orgId, TABLES.ORGANIZATION)
+    const queryEmbedding = await embeddings.embedQuery(params.query)
+    if (queryEmbedding.length === 0) return []
+
+    const candidateLimit = params.limit * 4
+    const sql = `
+      LET $candidateRows = (
+        SELECT
+          id,
+          vector::distance::knn() AS distance
+        FROM ${TABLES.LEARNED_SKILL}
+        WHERE organizationId = $organizationId
+          AND status IN ['learned', 'verified', 'promoted']
+          AND archivedAt IS NONE
+          AND confidence >= $minConfidence
+          AND (agentId IS NONE OR agentId = $agentId)
+          AND embedding <|${candidateLimit}|> $embedding
+        ORDER BY distance ASC
+      );
+
+      SELECT
+        type::string(id) AS id,
+        name,
+        description,
+        instructions,
+        confidence,
+        vector::similarity::cosine(embedding, $embedding) AS similarity
+      FROM ${TABLES.LEARNED_SKILL}
+      WHERE id IN $candidateRows.id
+      ORDER BY similarity DESC
+      LIMIT $limit
+    `
+
+    const rows = await databaseService.query<unknown>(
+      new BoundQuery(sql, {
+        organizationId: orgRef,
+        embedding: queryEmbedding,
+        agentId: params.agentId,
+        minConfidence: params.minConfidence,
+        limit: params.limit,
+      }),
+    )
+
+    return rows.map((row) => SearchResultRowSchema.parse(row)).filter((row) => row.similarity >= 0.3)
+  }
+
+  async retrieveForTurn(params: RetrieveForTurnParams): Promise<string | undefined> {
+    const results = await this.searchForTurn(params)
+    if (results.length === 0) return undefined
+
+    for (const result of results) {
+      void this.recordUsage(result.id).catch((error) => {
+        serverLogger.warn`Failed to record learned skill usage for ${result.id}: ${error}`
+      })
+    }
+
+    const section = renderLearnedSkillInstructions(
+      results.map((row) => ({ name: row.name, instructions: row.instructions })),
+    )
+    return section || undefined
+  }
+
+  async recordUsage(skillId: string): Promise<void> {
+    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+    await databaseService.query<unknown>(
+      new BoundQuery(`UPDATE ${TABLES.LEARNED_SKILL} SET usageCount += 1, lastUsedAt = time::now() WHERE id = $id`, {
+        id: ref,
+      }),
+    )
+  }
+
+  async recordSuccess(skillId: string): Promise<void> {
+    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+    await databaseService.query<unknown>(
+      new BoundQuery(`UPDATE ${TABLES.LEARNED_SKILL} SET successCount += 1 WHERE id = $id`, { id: ref }),
+    )
+  }
+
+  async promoteIfEligible(skillId: string): Promise<boolean> {
+    const skill = await this.getById(skillId)
+    if (!skill) return false
+    if (skill.status !== 'learned') return false
+    if (skill.usageCount < PROMOTION_MIN_USES) return false
+
+    const successRate = skill.successCount / skill.usageCount
+    if (successRate < PROMOTION_MIN_SUCCESS_RATE) return false
+
+    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+    await databaseService.update(
+      TABLES.LEARNED_SKILL,
+      ref,
+      { status: 'verified', confidence: Math.min(skill.confidence + 0.1, 1.0), updatedAt: new Date().toISOString() },
+      LearnedSkillRowSchema,
+    )
+    return true
+  }
+
+  async findMostSimilar(orgId: string, description: string): Promise<LearnedSkillRow | null> {
+    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+    const descEmbedding = await embeddings.embedQuery(description)
+    if (descEmbedding.length === 0) return null
+
+    const sql = `
+      LET $candidateRows = (
+        SELECT
+          id,
+          vector::distance::knn() AS distance
+        FROM ${TABLES.LEARNED_SKILL}
+        WHERE organizationId = $organizationId
+          AND status IN ['learned', 'verified', 'promoted']
+          AND archivedAt IS NONE
+          AND embedding <|3|> $embedding
+        ORDER BY distance ASC
+      );
+
+      SELECT *,
+        type::string(id) AS id,
+        type::string(organizationId) AS organizationId,
+        vector::similarity::cosine(embedding, $embedding) AS similarity
+      FROM ${TABLES.LEARNED_SKILL}
+      WHERE id IN $candidateRows.id
+      ORDER BY similarity DESC
+      LIMIT 1
+    `
+
+    const rows = await databaseService.query<unknown>(
+      new BoundQuery(sql, { organizationId: orgRef, embedding: descEmbedding }),
+    )
+
+    if (rows.length === 0) return null
+    return LearnedSkillRowSchema.parse(rows[0])
+  }
+
+  async listForOrg(orgId: string): Promise<LearnedSkillRow[]> {
+    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+    return databaseService.queryMany(
+      new BoundQuery(
+        `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
+         FROM ${TABLES.LEARNED_SKILL}
+         WHERE organizationId = $organizationId
+           AND status IN ['learned', 'verified', 'promoted']
+           AND archivedAt IS NONE
+         ORDER BY createdAt DESC`,
+        { organizationId: orgRef },
+      ),
+      LearnedSkillRowSchema,
+    )
+  }
+
+  generateHash(description: string, instructions: string): string {
+    const hasher = new Bun.CryptoHasher('sha256')
+    hasher.update(description.trim().toLowerCase())
+    hasher.update(instructions.trim().toLowerCase())
+    return hasher.digest('hex')
+  }
+
+  async findByHash(orgId: string, hash: string): Promise<LearnedSkillRow | null> {
+    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+    const rows = await databaseService.queryMany(
+      new BoundQuery(
+        `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
+         FROM ${TABLES.LEARNED_SKILL}
+         WHERE organizationId = $organizationId
+           AND hash = $hash
+           AND status IN ['learned', 'verified', 'promoted']
+           AND archivedAt IS NONE
+         LIMIT 1`,
+        { organizationId: orgRef, hash },
+      ),
+      LearnedSkillRowSchema,
+    )
+    return rows[0] ?? null
+  }
+}
+
+export const learnedSkillService = new LearnedSkillService()

package/src/services/memory-assessment.service.ts

@@ -0,0 +1,43 @@
+import type { z } from 'zod'
+
+import { MemoryImportanceAssessmentSchema } from '../db/memory-types'
+import { createHelperModelRuntime } from '../runtime/helper-model'
+import { createOrgMemoryAgent } from '../system-agents/memory.agent'
+
+type MemoryImportanceAssessment = z.infer<typeof MemoryImportanceAssessmentSchema>
+const MEMORY_IMPORTANCE_ASSESSMENT_TIMEOUT_MS = 10 * 60 * 1000
+const helperModelRuntime = createHelperModelRuntime()
+
+export function clampMemoryImportance(value: number): number {
+  return Math.max(0.2, Math.min(0.95, value))
+}
+
+export async function assessMemoryImportance(params: {
+  content: string
+  targetScope: 'agent' | 'global'
+  tag?: string
+}): Promise<MemoryImportanceAssessment> {
+  const prompt = [
+    'Assess whether this memory should be persisted in long-term memory.',
+    `targetScope: ${params.targetScope}`,
+    `memory: ${params.content}`,
+    '',
+    'Rules:',
+    '- importance: number between 0 and 1 for long-term usefulness.',
+    '- durability: core|standard|ephemeral.',
+    '- classification: durable|transient|uncertain.',
+    '- rationale: short and concrete.',
+    '',
+    'The caller enforces a structured output schema.',
+    'Return only schema fields.',
+  ].join('\n')
+
+  return await helperModelRuntime.generateHelperStructured({
+    tag: params.tag ?? 'memory-importance-assessment',
+    createAgent: createOrgMemoryAgent,
+    systemPrompt: 'You are a strict long-term memory quality assessor for an AI agent.',
+    messages: [{ role: 'user', content: prompt }],
+    schema: MemoryImportanceAssessmentSchema,
+    timeoutMs: MEMORY_IMPORTANCE_ASSESSMENT_TIMEOUT_MS,
+  })
+}