onbuzz 4.8.3 → 4.9.1

package/src/services/embeddings/embeddingsConfig.js

@@ -0,0 +1,203 @@
+/**
+ * Embeddings configuration shape + helpers.
+ *
+ * Defaults:
+ *   - Embeddings start DISABLED. The user must opt-in via Settings.
+ *     This keeps the install footprint smaller (no model downloads,
+ *     no API calls) and avoids accidentally embedding sensitive data
+ *     before the user has chosen between cloud and local.
+ *   - When enabled, local is the recommended default (privacy, $0).
+ *
+ * Provider config is read from the top-level Loxia config under
+ * `embeddings.*`. Per-agent overrides live in the agent's toolConfig
+ * (`agent.toolConfig.embeddings.provider`) — handled by the consumer,
+ * not this module.
+ *
+ * Why a module for this: validation + defaults in one place means the
+ * UI form, the tests, and the orchestrator all agree on the shape and
+ * never drift.
+ */
+
+import { DEFAULT_LOCAL_MODEL, LOCAL_MODELS } from './providers/localProvider.js';
+
+/** All known provider names. */
+export const PROVIDERS = Object.freeze(['local', 'azure', 'openai', 'azure-custom', 'disabled']);
+
+export const DEFAULT_CONFIG = Object.freeze({
+  provider: 'disabled',
+
+  local: Object.freeze({
+    modelId: DEFAULT_LOCAL_MODEL,
+    // null → use Transformers.js default cache dir; the orchestrator
+    // will resolve to `<userDataDir>/state/embeddings/cache/` for us
+    // so downloads live alongside other state and survive backups.
+    cacheDir: null,
+    maxBatchSize: 32,
+  }),
+
+  azure: Object.freeze({
+    // Loxia backend routes both autopilot + onbuzz to the same shared
+    // deployment per current architectural decision. The deployment
+    // name lives on the backend side.
+    modelId: 'text-embedding-3-small',
+    dimensions: 1536,
+    maxBatchSize: 16,
+  }),
+
+  openai: Object.freeze({
+    modelId: 'text-embedding-3-small',
+    dimensions: 1536,
+    maxBatchSize: 16,
+    url: null, // null → official api.openai.com
+  }),
+
+  // Azure custom deployment (OpenAI-compat endpoint hosting any embedding
+  // model — e.g. Cohere embed-v-4-0, third-party models published to
+  // Azure AI Foundry). Speaks the OpenAI REST shape but at the user's
+  // own deployment URL. Required: endpoint, deployment, dimensions, key.
+  azureCustom: Object.freeze({
+    endpoint: '',                // e.g. https://<resource>.services.ai.azure.com/openai/v1/
+    deployment: '',              // e.g. "embed-v-4-0"
+    dimensions: 1536,            // model-dependent — user supplies
+    maxBatchSize: 16,
+  }),
+
+  // Per-day soft cap on embedding tokens. Hitting the cap disables
+  // cloud embedding for the rest of the day; local is unaffected.
+  // Set to 0 / null to disable the cap.
+  budget: Object.freeze({
+    dailyTokenLimit: 1_000_000,
+  }),
+
+  // Auto-recall (silent retrieval injected into the system prompt
+  // per-turn). When enabled, the agent's "recent text" is embedded
+  // and used to look up high-similarity items from memory + reminisce
+  // pools, which are then injected under a clearly-labelled section.
+  // Defaults match the literature: threshold ~0.78, topK 3, ~400-token
+  // budget — see the Phase 6 design document and the Mem0 / ChatGPT
+  // memory reference shapes.
+  autoRecall: Object.freeze({
+    enabled: false,         // opt-in; the explicit semantic-search action remains the primary path
+    threshold: 0.78,        // cosine cutoff — items below this are not injected
+    topK: 3,                // max items per turn
+    maxTokens: 400,         // hard cap on total recalled token budget per turn
+    surfaces: Object.freeze(['memory', 'reminisce']),  // which pools to recall from
+  }),
+});
+
+/**
+ * Deep-merge a user config object into DEFAULT_CONFIG. Frozen defaults
+ * stay intact; user overrides win on a per-leaf basis.
+ *
+ * @param {object|null|undefined} userConfig
+ * @returns {object} a fresh, mutable config
+ */
+export function mergeConfig(userConfig) {
+  const out = {
+    provider: DEFAULT_CONFIG.provider,
+    local: { ...DEFAULT_CONFIG.local },
+    azure: { ...DEFAULT_CONFIG.azure },
+    openai: { ...DEFAULT_CONFIG.openai },
+    azureCustom: { ...DEFAULT_CONFIG.azureCustom },
+    budget: { ...DEFAULT_CONFIG.budget },
+    autoRecall: { ...DEFAULT_CONFIG.autoRecall, surfaces: [...DEFAULT_CONFIG.autoRecall.surfaces] },
+  };
+  if (!userConfig || typeof userConfig !== 'object') return out;
+  if (typeof userConfig.provider === 'string') out.provider = userConfig.provider;
+  for (const key of ['local', 'azure', 'openai', 'azureCustom', 'budget', 'autoRecall']) {
+    if (userConfig[key] && typeof userConfig[key] === 'object') {
+      out[key] = { ...out[key], ...userConfig[key] };
+      // Defensive copy for nested arrays so user mutation doesn't leak
+      if (key === 'autoRecall' && Array.isArray(out[key].surfaces)) {
+        out[key].surfaces = [...out[key].surfaces];
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Lint a config without throwing — returns `{ ok, errors[] }`.
+ * Used by the Settings UI to render inline error messages and by the
+ * orchestrator to bail loudly on bad config.
+ *
+ * @param {object} config
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== 'object') {
+    return { ok: false, errors: ['config must be an object'] };
+  }
+  if (!PROVIDERS.includes(config.provider)) {
+    errors.push(`provider must be one of ${PROVIDERS.join(', ')}`);
+  }
+  if (config.provider === 'local') {
+    const modelId = config.local?.modelId;
+    if (!modelId) errors.push('local.modelId is required');
+    // Unknown models are allowed (custom HuggingFace IDs work), but we
+    // warn-by-comment in the UI; here we just don't reject them.
+    if (config.local?.maxBatchSize != null && (!Number.isInteger(config.local.maxBatchSize) || config.local.maxBatchSize <= 0)) {
+      errors.push('local.maxBatchSize must be a positive integer');
+    }
+  }
+  if (config.provider === 'azure') {
+    if (!config.azure?.modelId) errors.push('azure.modelId is required');
+  }
+  if (config.provider === 'openai') {
+    if (!config.openai?.modelId) errors.push('openai.modelId is required');
+  }
+  if (config.provider === 'azure-custom') {
+    if (!config.azureCustom?.endpoint) {
+      errors.push('azureCustom.endpoint is required (e.g. https://<resource>.services.ai.azure.com/openai/v1/)');
+    }
+    if (!config.azureCustom?.deployment) {
+      errors.push('azureCustom.deployment is required (your deployed model name, e.g. embed-v-4-0)');
+    }
+    if (config.azureCustom?.dimensions != null) {
+      const d = config.azureCustom.dimensions;
+      if (!Number.isInteger(d) || d <= 0) {
+        errors.push('azureCustom.dimensions must be a positive integer');
+      }
+    }
+  }
+  if (config.budget?.dailyTokenLimit != null) {
+    const lim = config.budget.dailyTokenLimit;
+    if (!(lim === 0 || (Number.isInteger(lim) && lim > 0))) {
+      errors.push('budget.dailyTokenLimit must be 0 or a positive integer');
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Surface the list of "known" models the UI can offer to users.
+ * Cloud models are static; local models come from the LOCAL_MODELS
+ * catalog so adding one there propagates to the UI automatically.
+ */
+export function getProviderModelOptions(provider) {
+  if (provider === 'local') {
+    return Object.entries(LOCAL_MODELS).map(([id, info]) => ({
+      id,
+      description: info.description,
+      dimensions: info.dimensions,
+    }));
+  }
+  if (provider === 'azure' || provider === 'openai') {
+    return [
+      { id: 'text-embedding-3-small', description: 'Best price / quality. Recommended.', dimensions: 1536 },
+      { id: 'text-embedding-3-large', description: 'Higher recall, ~5× cost.',           dimensions: 3072 },
+    ];
+  }
+  return [];
+}
+
+/**
+ * A rough token estimator for telemetry / budget purposes. Real
+ * tokenization happens server-side; this is just for the cost-tracking
+ * dashboard. ~4 chars/token is the long-standing rule of thumb.
+ */
+export function estimateTokens(text) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  return Math.ceil(text.length / 4);
+}

package/src/services/embeddings/indexers/__tests__/agentIndexer.test.js

@@ -0,0 +1,232 @@
+/**
+ * AgentIndexer tests.
+ *
+ * Pins:
+ *   - GLOBAL scope (one shared store under surface='agents')
+ *   - agentToText pack order: type → name → systemPrompt → capabilities → skills
+ *   - systemPrompt is truncated past maxPromptChars
+ *   - backfill batches into ONE embed call + drops prior index
+ *   - Search hits expose name + type + capabilities + skills + promptSnippet
+ *   - excludeIds filter removes the requester's own id
+ *   - Hybrid search surfaces substring-only matches
+ *   - Disabled path returns structured falsy results
+ */
+
+import { describe, test, expect, jest, beforeEach, afterEach } from '@jest/globals';
+import os from 'os';
+import fsp from 'fs/promises';
+import path from 'path';
+import { AgentIndexer, agentToText } from '../agentIndexer.js';
+import { EmbeddingService } from '../../embeddingService.js';
+import { EmbeddingProvider } from '../../providerInterface.js';
+
+class StubProvider extends EmbeddingProvider {
+  constructor(dimensions = 8) {
+    super();
+    this._dimensions = dimensions;
+    this.calls = [];
+  }
+  getInfo() {
+    return {
+      name: 'azure', modelId: 'stub-agents', dimensions: this._dimensions,
+      maxBatchSize: 32, maxTokensPerText: 1000,
+      distinguishesQueryAndDocument: false, isLocal: false,
+    };
+  }
+  getModelFingerprint() { return 'stub-agents:v1'; }
+  async _embed(texts) {
+    this.calls.push({ texts: [...texts] });
+    return texts.map(t => {
+      const vec = Array(this._dimensions).fill(0);
+      vec[(t.charCodeAt(0) || 0) % this._dimensions] = 1;
+      vec[((t.charCodeAt(20) || 0) + 1) % this._dimensions] += 0.5;
+      return vec;
+    });
+  }
+}
+
+function makeIndexer({ tmpDir, enabled = true } = {}) {
+  const apiKeyManager = { getEmbeddingApiKey: () => 'k' };
+  if (!enabled) {
+    const svc = new EmbeddingService({ apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir });
+    return { indexer: new AgentIndexer({ embeddingService: svc }), svc };
+  }
+  const provider = new StubProvider();
+  const svc = new EmbeddingService({
+    config: { provider: 'azure' },
+    apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir,
+    providerOverrides: { azure: () => provider },
+  });
+  return { indexer: new AgentIndexer({ embeddingService: svc }), svc, provider };
+}
+
+const agentSQL = {
+  id: 'agent-dba',
+  name: 'Database Specialist',
+  type: 'data-engineer',
+  systemPrompt: 'You are a senior database engineer. Specialise in SQL migrations, schema design, and query performance tuning.',
+  capabilities: ['terminal', 'filesystem', 'staticanalysis'],
+  skills: ['migrations', 'indexing'],
+};
+const agentFrontend = {
+  id: 'agent-fe',
+  name: 'Frontend Developer',
+  type: 'developer',
+  systemPrompt: 'You are a frontend developer. Build React components, handle CSS, and ship visual changes.',
+  capabilities: ['filesystem', 'terminal', 'visual-editor'],
+  skills: ['react', 'css'],
+};
+const agentDevOps = {
+  id: 'agent-devops',
+  name: 'DevOps Engineer',
+  type: 'devops',
+  systemPrompt: 'You are a DevOps engineer. Set up CI/CD, manage Docker images, and run kubectl.',
+  capabilities: ['terminal', 'web'],
+  skills: ['docker', 'kubernetes'],
+};
+
+describe('agentToText', () => {
+  test('pack order: [type] → name → systemPrompt → capabilities → skills', () => {
+    const text = agentToText(agentSQL);
+    const tType   = text.indexOf('[data-engineer]');
+    const tName   = text.indexOf('Database Specialist');
+    const tPrompt = text.indexOf('SQL migrations');
+    const tCap    = text.indexOf('capabilities:');
+    const tSkill  = text.indexOf('skills:');
+    expect(tType).toBe(0);
+    expect(tName).toBeGreaterThan(tType);
+    expect(tPrompt).toBeGreaterThan(tName);
+    expect(tCap).toBeGreaterThan(tPrompt);
+    expect(tSkill).toBeGreaterThan(tCap);
+  });
+
+  test('truncates systemPrompt past maxPromptChars', () => {
+    const long = { id: 'x', name: 'L', systemPrompt: 'A'.repeat(5000) };
+    const out = agentToText(long, { maxPromptChars: 100 });
+    // 100-char prompt slice should be inside, but no 'A'.repeat(2000) lump.
+    expect(out).toContain('A'.repeat(100));
+    expect(out).not.toContain('A'.repeat(101));
+  });
+
+  test('falls back to originalSystemPrompt when systemPrompt is empty', () => {
+    const out = agentToText({ id: 'x', originalSystemPrompt: 'OG prompt content' });
+    expect(out).toContain('OG prompt content');
+  });
+
+  test('null / no-id agent returns empty', () => {
+    expect(agentToText(null)).toBe('');
+    expect(agentToText({})).toBe('');
+  });
+
+  test('skips capabilities / skills sections when empty', () => {
+    const text = agentToText({ id: 'x', name: 'Y', systemPrompt: 'Z' });
+    expect(text).not.toContain('capabilities:');
+    expect(text).not.toContain('skills:');
+  });
+});
+
+describe('AgentIndexer — disabled path', () => {
+  let tmpDir;
+  beforeEach(async () => { tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-aidx-')); });
+  afterEach(async () => { await fsp.rm(tmpDir, { recursive: true, force: true }); });
+
+  test('indexOne / backfill / search return disabled-shaped results', async () => {
+    const { indexer } = makeIndexer({ tmpDir, enabled: false });
+    expect(await indexer.indexOne(agentSQL)).toEqual({ indexed: false, reason: 'disabled' });
+    expect(await indexer.search('migration')).toEqual({ enabled: false, hits: [] });
+    expect(await indexer.backfill([agentSQL])).toEqual({ ok: false, reason: 'disabled', indexed: 0, skipped: 0, failed: 0 });
+  });
+});
+
+describe('AgentIndexer — round-trip', () => {
+  let tmpDir, indexer, svc, provider;
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-aidx-'));
+    ({ indexer, svc, provider } = makeIndexer({ tmpDir }));
+  });
+  afterEach(async () => { await fsp.rm(tmpDir, { recursive: true, force: true }); });
+
+  test('indexOne + search returns the agent as a hit', async () => {
+    await indexer.indexOne(agentSQL);
+    const r = await indexer.search('database migration expert');
+    expect(r.enabled).toBe(true);
+    expect(r.hits.find(h => h.agentId === agentSQL.id)).toBeDefined();
+  });
+
+  test('backfill indexes all agents in ONE embed call', async () => {
+    const r = await indexer.backfill([agentSQL, agentFrontend, agentDevOps]);
+    expect(r.ok).toBe(true);
+    expect(r.indexed).toBe(3);
+    expect(provider.calls).toHaveLength(1);
+    expect(provider.calls[0].texts).toHaveLength(3);
+  });
+
+  test('backfill drops the prior index (full-rebuild semantics)', async () => {
+    await indexer.backfill([agentSQL, agentFrontend, agentDevOps]);
+    const before = (await indexer.stats()).count;
+    expect(before).toBe(3);
+    await indexer.backfill([agentSQL]);   // only one remains
+    expect((await indexer.stats()).count).toBe(1);
+  });
+
+  test('deleteOne removes the agent', async () => {
+    await indexer.backfill([agentSQL, agentFrontend]);
+    expect((await indexer.stats()).count).toBe(2);
+    const r = await indexer.deleteOne(agentSQL.id);
+    expect(r.deleted).toBe(true);
+    expect((await indexer.stats()).count).toBe(1);
+  });
+
+  test('search excludeIds filters out a list of agent ids', async () => {
+    await indexer.backfill([agentSQL, agentFrontend, agentDevOps]);
+    const r = await indexer.search('engineer', { topK: 5, excludeIds: [agentSQL.id, agentDevOps.id] });
+    expect(r.hits.every(h => h.agentId === agentFrontend.id)).toBe(true);
+  });
+
+  test('search hits expose name + type + capabilities + skills + promptSnippet', async () => {
+    await indexer.backfill([agentSQL, agentFrontend]);
+    const r = await indexer.search('react', { topK: 1 });
+    const hit = r.hits[0];
+    expect(hit).toMatchObject({
+      name: expect.any(String),
+      type: expect.any(String),
+      capabilities: expect.any(Array),
+      skills: expect.any(Array),
+      promptSnippet: expect.any(String),
+    });
+  });
+
+  test('hybrid mode surfaces substring matches (slug-like terms)', async () => {
+    await indexer.backfill([agentSQL, agentFrontend, agentDevOps]);
+    // "kubernetes" appears verbatim in devops skills; hybrid should rank it.
+    const r = await indexer.search('kubernetes', { topK: 3 });
+    expect(r.hits.find(h => h.agentId === agentDevOps.id)).toBeDefined();
+  });
+
+  test('skips invalid / no-text agents during backfill', async () => {
+    const r = await indexer.backfill([
+      agentSQL,
+      { /* no id */ name: 'nameless' },
+      { id: 'empty' /* no prompt / name */ },
+    ]);
+    expect(r.indexed).toBe(1);
+    expect(r.skipped).toBe(2);
+  });
+
+  test('embed failure reports failed counts cleanly', async () => {
+    const apiKeyManager = { getEmbeddingApiKey: () => 'k' };
+    class FailingProvider extends StubProvider {
+      async _embed() { throw new Error('rate-limited'); }
+    }
+    const svc = new EmbeddingService({
+      config: { provider: 'azure' },
+      apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir,
+      providerOverrides: { azure: () => new FailingProvider() },
+    });
+    const idx = new AgentIndexer({ embeddingService: svc });
+    const r = await idx.backfill([agentSQL, agentFrontend]);
+    expect(r.ok).toBe(false);
+    expect(r.failed).toBe(2);
+    expect(r.error).toMatch(/rate-limited/);
+  });
+});