@soleri/core 0.0.1 → 2.0.0

package/src/cognee/client.ts

@@ -0,0 +1,350 @@
+import type {
+  CogneeConfig,
+  CogneeSearchResult,
+  CogneeSearchType,
+  CogneeStatus,
+  CogneeAddResult,
+  CogneeCognifyResult,
+} from './types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── Defaults ──────────────────────────────────────────────────────
+// Aligned with Salvador MCP's battle-tested Cognee integration.
+
+const DEFAULT_SERVICE_EMAIL = 'soleri-agent@cognee.dev';
+const DEFAULT_SERVICE_PASSWORD = 'soleri-cognee-local';
+
+/** Only allow default service credentials for local endpoints. */
+function isLocalUrl(url: string): boolean {
+  try {
+    const { hostname } = new URL(url);
+    return (
+      hostname === 'localhost' ||
+      hostname === '127.0.0.1' ||
+      hostname === '::1' ||
+      hostname === '0.0.0.0'
+    );
+  } catch {
+    return false;
+  }
+}
+
+const DEFAULT_CONFIG: CogneeConfig = {
+  baseUrl: 'http://localhost:8000',
+  dataset: 'vault',
+  timeoutMs: 30_000,
+  searchTimeoutMs: 120_000, // Ollama cold start can take 90s
+  healthTimeoutMs: 5_000,
+  healthCacheTtlMs: 60_000,
+  cognifyDebounceMs: 30_000,
+};
+
+// ─── CogneeClient ──────────────────────────────────────────────────
+
+export class CogneeClient {
+  private config: CogneeConfig;
+  private healthCache: { status: CogneeStatus; cachedAt: number } | null = null;
+  private accessToken: string | null = null;
+  private cognifyTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+  private pendingDatasets: Set<string> = new Set();
+
+  constructor(config?: Partial<CogneeConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    // Strip trailing slash
+    this.config.baseUrl = this.config.baseUrl.replace(/\/+$/, '');
+    // Pre-set token if provided
+    if (this.config.apiToken) {
+      this.accessToken = this.config.apiToken;
+    }
+  }
+
+  // ─── Health ────────────────────────────────────────────────────
+
+  get isAvailable(): boolean {
+    if (!this.healthCache) return false;
+    const age = Date.now() - this.healthCache.cachedAt;
+    if (age > this.config.healthCacheTtlMs) return false;
+    return this.healthCache.status.available;
+  }
+
+  async healthCheck(): Promise<CogneeStatus> {
+    const start = Date.now();
+    try {
+      // Cognee health endpoint is GET / (returns {"message":"Hello, World, I am alive!"})
+      const res = await globalThis.fetch(`${this.config.baseUrl}/`, {
+        signal: AbortSignal.timeout(this.config.healthTimeoutMs),
+      });
+      const latencyMs = Date.now() - start;
+      if (res.ok) {
+        const status: CogneeStatus = { available: true, url: this.config.baseUrl, latencyMs };
+        this.healthCache = { status, cachedAt: Date.now() };
+        return status;
+      }
+      const status: CogneeStatus = {
+        available: false,
+        url: this.config.baseUrl,
+        latencyMs,
+        error: `HTTP ${res.status}`,
+      };
+      this.healthCache = { status, cachedAt: Date.now() };
+      return status;
+    } catch (err) {
+      const latencyMs = Date.now() - start;
+      const status: CogneeStatus = {
+        available: false,
+        url: this.config.baseUrl,
+        latencyMs,
+        error: err instanceof Error ? err.message : String(err),
+      };
+      this.healthCache = { status, cachedAt: Date.now() };
+      return status;
+    }
+  }
+
+  // ─── Ingest ────────────────────────────────────────────────────
+
+  async addEntries(entries: IntelligenceEntry[]): Promise<CogneeAddResult> {
+    if (!this.isAvailable || entries.length === 0) return { added: 0 };
+
+    try {
+      const token = await this.ensureAuth().catch(() => null);
+
+      // Cognee /add expects multipart/form-data with files + datasetName
+      const formData = new FormData();
+      formData.append('datasetName', this.config.dataset);
+
+      for (const entry of entries) {
+        const text = this.serializeEntry(entry);
+        const blob = new Blob([text], { type: 'text/plain' });
+        formData.append('data', blob, `${entry.id}.txt`);
+      }
+
+      const headers: Record<string, string> = {};
+      if (token) headers.Authorization = `Bearer ${token}`;
+
+      const res = await globalThis.fetch(`${this.config.baseUrl}/api/v1/add`, {
+        method: 'POST',
+        headers,
+        body: formData,
+        signal: AbortSignal.timeout(this.config.timeoutMs),
+      });
+
+      if (!res.ok) return { added: 0 };
+
+      // Schedule debounced cognify (multiple rapid ingests coalesce)
+      this.scheduleCognify(this.config.dataset);
+
+      return { added: entries.length };
+    } catch {
+      return { added: 0 };
+    }
+  }
+
+  async cognify(dataset?: string): Promise<CogneeCognifyResult> {
+    if (!this.isAvailable) return { status: 'unavailable' };
+
+    try {
+      const res = await this.post('/api/v1/cognify', {
+        datasets: [dataset ?? this.config.dataset],
+      });
+
+      if (!res.ok) return { status: `error: HTTP ${res.status}` };
+      return { status: 'ok' };
+    } catch (err) {
+      return { status: `error: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+
+  // ─── Cognify debounce ───────────────────────────────────────────
+
+  /**
+   * Schedule a debounced cognify for a dataset.
+   * Sliding window: each call resets the timer. When it expires,
+   * cognify fires once. Prevents pipeline dedup on rapid ingests.
+   */
+  private scheduleCognify(dataset: string): void {
+    const existing = this.cognifyTimers.get(dataset);
+    if (existing) clearTimeout(existing);
+
+    this.pendingDatasets.add(dataset);
+
+    const timer = setTimeout(() => {
+      this.cognifyTimers.delete(dataset);
+      this.pendingDatasets.delete(dataset);
+      this.post('/api/v1/cognify', { datasets: [dataset] }).catch(() => {});
+    }, this.config.cognifyDebounceMs);
+
+    // Unref so the timer doesn't keep the process alive during shutdown
+    if (typeof timer === 'object' && 'unref' in timer) (timer as NodeJS.Timeout).unref();
+
+    this.cognifyTimers.set(dataset, timer);
+  }
+
+  /** Flush all pending debounced cognify calls immediately. */
+  async flushPendingCognify(): Promise<void> {
+    const datasets = [...this.pendingDatasets];
+    for (const timer of this.cognifyTimers.values()) clearTimeout(timer);
+    this.cognifyTimers.clear();
+    this.pendingDatasets.clear();
+
+    if (datasets.length === 0) return;
+
+    await Promise.allSettled(
+      datasets.map((ds) => this.post('/api/v1/cognify', { datasets: [ds] }).catch(() => {})),
+    );
+  }
+
+  /** Cancel all pending cognify calls without firing them. For test teardown. */
+  resetPendingCognify(): void {
+    for (const timer of this.cognifyTimers.values()) clearTimeout(timer);
+    this.cognifyTimers.clear();
+    this.pendingDatasets.clear();
+  }
+
+  // ─── Search ────────────────────────────────────────────────────
+
+  async search(
+    query: string,
+    opts?: { searchType?: CogneeSearchType; limit?: number },
+  ): Promise<CogneeSearchResult[]> {
+    if (!this.isAvailable) return [];
+
+    // Default to CHUNKS (pure vector similarity) — GRAPH_COMPLETION requires
+    // the LLM to produce instructor-compatible JSON which small local models
+    // (llama3.2) can't do reliably, causing infinite retries and timeouts.
+    const searchType = opts?.searchType ?? 'CHUNKS';
+    const topK = opts?.limit ?? 10;
+
+    try {
+      const res = await this.post(
+        '/api/v1/search',
+        { query, search_type: searchType, datasets: [this.config.dataset], topK },
+        this.config.searchTimeoutMs,
+      );
+
+      if (!res.ok) return [];
+
+      const data = (await res.json()) as Array<{
+        id?: string;
+        text?: string;
+        score?: number;
+        payload?: { id?: string };
+      }>;
+
+      // Position-based scoring when Cognee omits scores.
+      // Cognee returns results ordered by relevance but may not include numeric scores.
+      return data.slice(0, topK).map((item, idx) => ({
+        id: item.payload?.id ?? item.id ?? '',
+        score: item.score ?? positionScore(idx, data.length),
+        text: typeof item.text === 'string' ? item.text : String(item.text ?? ''),
+        searchType,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  // ─── Config access ─────────────────────────────────────────────
+
+  getConfig(): Readonly<CogneeConfig> {
+    return { ...this.config };
+  }
+
+  getStatus(): CogneeStatus | null {
+    return this.healthCache?.status ?? null;
+  }
+
+  // ─── Auth ──────────────────────────────────────────────────────
+  // Auto-register + login pattern from Salvador MCP.
+  // Tries login first (account may already exist), falls back to register.
+
+  private async ensureAuth(): Promise<string> {
+    if (this.accessToken) return this.accessToken;
+
+    const email = this.config.serviceEmail ?? DEFAULT_SERVICE_EMAIL;
+    const password = this.config.servicePassword ?? DEFAULT_SERVICE_PASSWORD;
+
+    // Refuse default credentials for non-local endpoints
+    if (
+      !isLocalUrl(this.config.baseUrl) &&
+      email === DEFAULT_SERVICE_EMAIL &&
+      password === DEFAULT_SERVICE_PASSWORD
+    ) {
+      throw new Error('Explicit Cognee credentials are required for non-local endpoints');
+    }
+
+    // Try login first
+    const loginResp = await globalThis.fetch(`${this.config.baseUrl}/api/v1/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `username=${encodeURIComponent(email)}&password=${encodeURIComponent(password)}`,
+      signal: AbortSignal.timeout(this.config.healthTimeoutMs),
+    });
+
+    if (loginResp.ok) {
+      const data = (await loginResp.json()) as { access_token: string };
+      this.accessToken = data.access_token;
+      return this.accessToken;
+    }
+
+    // Register, then retry login
+    await globalThis.fetch(`${this.config.baseUrl}/api/v1/auth/register`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+      signal: AbortSignal.timeout(this.config.healthTimeoutMs),
+    });
+
+    const retryLogin = await globalThis.fetch(`${this.config.baseUrl}/api/v1/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `username=${encodeURIComponent(email)}&password=${encodeURIComponent(password)}`,
+      signal: AbortSignal.timeout(this.config.healthTimeoutMs),
+    });
+
+    if (!retryLogin.ok) {
+      throw new Error(`Cognee auth failed: HTTP ${retryLogin.status}`);
+    }
+
+    const retryData = (await retryLogin.json()) as { access_token: string };
+    this.accessToken = retryData.access_token;
+    return this.accessToken;
+  }
+
+  private async authHeaders(): Promise<Record<string, string>> {
+    try {
+      const token = await this.ensureAuth();
+      return { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` };
+    } catch {
+      // Fall back to no auth (works if AUTH_REQUIRED=false)
+      return { 'Content-Type': 'application/json' };
+    }
+  }
+
+  // ─── Private helpers ───────────────────────────────────────────
+
+  private serializeEntry(entry: IntelligenceEntry): string {
+    const parts = [entry.title, entry.description];
+    if (entry.context) parts.push(entry.context);
+    if (entry.tags.length > 0) parts.push(`Tags: ${entry.tags.join(', ')}`);
+    return parts.join('\n');
+  }
+
+  private async post(path: string, body: unknown, timeoutMs?: number): Promise<Response> {
+    const headers = await this.authHeaders();
+    return globalThis.fetch(`${this.config.baseUrl}${path}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs ?? this.config.timeoutMs),
+    });
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+/** Position-based score: first result gets ~1.0, last gets ~0.05. */
+function positionScore(index: number, total: number): number {
+  if (total <= 1) return 1.0;
+  return Math.max(0.05, 1.0 - (index / (total - 1)) * 0.95);
+}

package/src/cognee/types.ts

@@ -0,0 +1,62 @@
+// ─── Cognee Integration Types ──────────────────────────────────────
+
+export interface CogneeConfig {
+  /** Base URL of the Cognee API (default: http://localhost:8000) */
+  baseUrl: string;
+  /** Dataset name for this agent's vault entries */
+  dataset: string;
+  /** Bearer token for Cognee API authentication (auto-acquired if not set) */
+  apiToken?: string;
+  /** Service account email for auto-login (default: soleri-agent@cognee.dev) */
+  serviceEmail?: string;
+  /** Service account password for auto-login */
+  servicePassword?: string;
+  /** Default request timeout in milliseconds (default: 30000) */
+  timeoutMs: number;
+  /** Search timeout in milliseconds — Ollama cold start can take 90s (default: 120000) */
+  searchTimeoutMs: number;
+  /** Health check timeout in milliseconds (default: 5000) */
+  healthTimeoutMs: number;
+  /** Health check cache TTL in milliseconds (default: 60000) */
+  healthCacheTtlMs: number;
+  /** Cognify debounce window in milliseconds (default: 30000) */
+  cognifyDebounceMs: number;
+}
+
+export interface CogneeSearchResult {
+  /** Vault entry ID (cross-reference key) */
+  id: string;
+  /** Relevance score (0–1). Position-based when Cognee omits scores. */
+  score: number;
+  /** Text content from Cognee */
+  text: string;
+  /** Cognee search type that produced this result */
+  searchType: CogneeSearchType;
+}
+
+export type CogneeSearchType =
+  | 'SUMMARIES'
+  | 'CHUNKS'
+  | 'RAG_COMPLETION'
+  | 'TRIPLET_COMPLETION'
+  | 'GRAPH_COMPLETION'
+  | 'GRAPH_SUMMARY_COMPLETION'
+  | 'NATURAL_LANGUAGE'
+  | 'GRAPH_COMPLETION_COT'
+  | 'FEELING_LUCKY'
+  | 'CHUNKS_LEXICAL';
+
+export interface CogneeStatus {
+  available: boolean;
+  url: string;
+  latencyMs: number;
+  error?: string;
+}
+
+export interface CogneeAddResult {
+  added: number;
+}
+
+export interface CogneeCognifyResult {
+  status: string;
+}

package/src/facades/facade-factory.ts

@@ -0,0 +1,64 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { FacadeConfig, FacadeResponse } from './types.js';
+
+export function registerFacade(server: McpServer, facade: FacadeConfig): void {
+  const opNames = facade.ops.map((o) => o.name);
+
+  server.tool(
+    facade.name,
+    `${facade.description}\n\nOperations: ${opNames.join(', ')}`,
+    {
+      op: z.string().describe(`Operation: ${opNames.join(' | ')}`),
+      params: z.record(z.unknown()).optional().default({}).describe('Operation parameters'),
+    },
+    async ({ op, params }): Promise<{ content: Array<{ type: 'text'; text: string }> }> => {
+      const response = await dispatchOp(facade, op, params);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }] };
+    },
+  );
+}
+
+async function dispatchOp(
+  facade: FacadeConfig,
+  opName: string,
+  params: Record<string, unknown>,
+): Promise<FacadeResponse> {
+  const op = facade.ops.find((o) => o.name === opName);
+  if (!op) {
+    return {
+      success: false,
+      error: `Unknown operation "${opName}" on ${facade.name}. Available: ${facade.ops.map((o) => o.name).join(', ')}`,
+      op: opName,
+      facade: facade.name,
+    };
+  }
+
+  try {
+    let validatedParams = params;
+    if (op.schema) {
+      const result = op.schema.safeParse(params);
+      if (!result.success) {
+        return {
+          success: false,
+          error: `Invalid params for ${opName}: ${result.error.message}`,
+          op: opName,
+          facade: facade.name,
+        };
+      }
+      validatedParams = result.data as Record<string, unknown>;
+    }
+
+    const data = await op.handler(validatedParams);
+    return { success: true, data, op: opName, facade: facade.name };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, error: message, op: opName, facade: facade.name };
+  }
+}
+
+export function registerAllFacades(server: McpServer, facades: FacadeConfig[]): void {
+  for (const facade of facades) {
+    registerFacade(server, facade);
+  }
+}

package/src/facades/types.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+
+/** Handler function for a single facade operation */
+export type OpHandler = (params: Record<string, unknown>) => Promise<unknown>;
+
+/** Auth level required for an operation */
+export type AuthLevel = 'read' | 'write' | 'admin';
+
+/** Operation definition within a facade */
+export interface OpDefinition {
+  name: string;
+  description: string;
+  auth: AuthLevel;
+  handler: OpHandler;
+  schema?: z.ZodType;
+}
+
+/** Facade configuration — one MCP tool */
+export interface FacadeConfig {
+  /** MCP tool name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Domain operations */
+  ops: OpDefinition[];
+}
+
+/** Standard facade response envelope */
+export interface FacadeResponse {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  op?: string;
+  facade?: string;
+}
+
+export const facadeInputSchema = z.object({
+  op: z.string().describe('Operation name'),
+  params: z.record(z.unknown()).optional().default({}),
+});
+
+export type FacadeInput = z.infer<typeof facadeInputSchema>;

package/src/index.ts

@@ -0,0 +1,75 @@
+// ─── Intelligence ────────────────────────────────────────────────────
+export type { IntelligenceEntry, IntelligenceBundle } from './intelligence/types.js';
+export { loadIntelligenceData } from './intelligence/loader.js';
+
+// ─── Vault ───────────────────────────────────────────────────────────
+export { Vault } from './vault/vault.js';
+export type { SearchResult, VaultStats, ProjectInfo, Memory, MemoryStats } from './vault/vault.js';
+
+// ─── Brain ───────────────────────────────────────────────────────────
+export { Brain } from './brain/brain.js';
+export type {
+  ScoringWeights,
+  ScoreBreakdown,
+  RankedResult,
+  SearchOptions,
+  CaptureResult,
+  BrainStats,
+  QueryContext,
+} from './brain/brain.js';
+
+// ─── Cognee ─────────────────────────────────────────────────────────
+export { CogneeClient } from './cognee/client.js';
+export type {
+  CogneeConfig,
+  CogneeSearchResult,
+  CogneeSearchType,
+  CogneeStatus,
+  CogneeAddResult,
+  CogneeCognifyResult,
+} from './cognee/types.js';
+
+// ─── Planning ────────────────────────────────────────────────────────
+export { Planner } from './planning/planner.js';
+export type { PlanStatus, TaskStatus, PlanTask, Plan, PlanStore } from './planning/planner.js';
+
+// ─── LLM Types ───────────────────────────────────────────────────────
+export { SecretString, LLMError } from './llm/types.js';
+export type {
+  LLMCallOptions,
+  LLMCallResult,
+  CircuitState,
+  CircuitBreakerConfig,
+  CircuitBreakerSnapshot,
+  KeyPoolConfig,
+  KeyStatus,
+  RouteEntry,
+  RoutingConfig,
+  RateLimitInfo,
+  RetryConfig,
+} from './llm/types.js';
+
+// ─── LLM Utils ───────────────────────────────────────────────────────
+export {
+  CircuitBreaker,
+  CircuitOpenError,
+  computeDelay,
+  retry,
+  parseRateLimitHeaders,
+} from './llm/utils.js';
+
+// ─── LLM Key Pool ───────────────────────────────────────────────────
+export { KeyPool, loadKeyPoolConfig } from './llm/key-pool.js';
+export type { KeyPoolFiles } from './llm/key-pool.js';
+
+// ─── Facades ─────────────────────────────────────────────────────────
+export { registerFacade, registerAllFacades } from './facades/facade-factory.js';
+export { facadeInputSchema } from './facades/types.js';
+export type {
+  OpHandler,
+  AuthLevel,
+  OpDefinition,
+  FacadeConfig,
+  FacadeResponse,
+  FacadeInput,
+} from './facades/types.js';

package/src/intelligence/loader.ts

@@ -0,0 +1,42 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { IntelligenceBundle, IntelligenceEntry } from './types.js';
+
+export function loadIntelligenceData(dataDir: string): IntelligenceEntry[] {
+  const entries: IntelligenceEntry[] = [];
+  let files: string[];
+  try {
+    files = readdirSync(dataDir).filter((f) => f.endsWith('.json'));
+  } catch {
+    console.warn('Intelligence data directory not found: ' + dataDir);
+    return entries;
+  }
+
+  for (const file of files) {
+    try {
+      const raw = readFileSync(join(dataDir, file), 'utf-8');
+      const bundle = JSON.parse(raw) as IntelligenceBundle;
+      if (!bundle.entries || !Array.isArray(bundle.entries)) continue;
+      for (const entry of bundle.entries) {
+        if (validateEntry(entry)) entries.push(entry);
+      }
+    } catch (err) {
+      console.warn('Failed to load ' + file + ': ' + (err instanceof Error ? err.message : err));
+    }
+  }
+  return entries;
+}
+
+function validateEntry(entry: IntelligenceEntry): boolean {
+  return (
+    typeof entry.id === 'string' &&
+    entry.id.length > 0 &&
+    ['pattern', 'anti-pattern', 'rule'].includes(entry.type) &&
+    typeof entry.title === 'string' &&
+    entry.title.length > 0 &&
+    typeof entry.description === 'string' &&
+    entry.description.length > 0 &&
+    ['critical', 'warning', 'suggestion'].includes(entry.severity) &&
+    Array.isArray(entry.tags)
+  );
+}

package/src/intelligence/types.ts

@@ -0,0 +1,20 @@
+export interface IntelligenceEntry {
+  id: string;
+  type: 'pattern' | 'anti-pattern' | 'rule';
+  domain: string;
+  title: string;
+  severity: 'critical' | 'warning' | 'suggestion';
+  description: string;
+  context?: string;
+  example?: string;
+  counterExample?: string;
+  why?: string;
+  tags: string[];
+  appliesTo?: string[];
+}
+
+export interface IntelligenceBundle {
+  domain: string;
+  version: string;
+  entries: IntelligenceEntry[];
+}