@vpxa/kb 0.1.1

package/packages/core/dist/constants.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Default constants for the Knowledge Base system.
+ */
+/** Default chunk sizes by content type */
+export declare const CHUNK_SIZES: {
+    readonly markdown: {
+        readonly max: 1500;
+        readonly min: 100;
+    };
+    readonly code: {
+        readonly max: 2000;
+        readonly min: 50;
+    };
+    readonly config: {
+        readonly max: 3000;
+        readonly min: 50;
+    };
+    readonly default: {
+        readonly max: 1500;
+        readonly min: 100;
+        readonly overlap: 200;
+    };
+};
+/** Default embedding config */
+export declare const EMBEDDING_DEFAULTS: {
+    readonly model: "mixedbread-ai/mxbai-embed-large-v1";
+    readonly dimensions: 1024;
+};
+/** Default store config */
+export declare const STORE_DEFAULTS: {
+    readonly backend: "lancedb";
+    readonly path: ".kb-data";
+    readonly tableName: "knowledge";
+};
+/** File size limits */
+export declare const FILE_LIMITS: {
+    readonly maxFileSizeBytes: 1000000;
+    readonly maxCuratedFileSizeBytes: 50000;
+};
+/** Search defaults */
+export declare const SEARCH_DEFAULTS: {
+    readonly maxResults: 10;
+    readonly minScore: 0.25;
+};
+/** Category validation regex */
+export declare const CATEGORY_PATTERN: RegExp;
+/** Default knowledge categories */
+export declare const DEFAULT_CATEGORIES: readonly ["decisions", "patterns", "troubleshooting", "conventions", "architecture"];
+//# sourceMappingURL=constants.d.ts.map

package/packages/core/dist/constants.js

@@ -0,0 +1,43 @@
+const CHUNK_SIZES = {
+  markdown: { max: 1500, min: 100 },
+  code: { max: 2e3, min: 50 },
+  config: { max: 3e3, min: 50 },
+  default: { max: 1500, min: 100, overlap: 200 }
+};
+const EMBEDDING_DEFAULTS = {
+  model: "mixedbread-ai/mxbai-embed-large-v1",
+  dimensions: 1024
+};
+const STORE_DEFAULTS = {
+  backend: "lancedb",
+  path: ".kb-data",
+  tableName: "knowledge"
+};
+const FILE_LIMITS = {
+  maxFileSizeBytes: 1e6,
+  // 1MB — skip larger files
+  maxCuratedFileSizeBytes: 5e4
+  // 50KB for curated knowledge
+};
+const SEARCH_DEFAULTS = {
+  maxResults: 10,
+  minScore: 0.25
+};
+const CATEGORY_PATTERN = /^[a-z][a-z0-9-]*$/;
+const DEFAULT_CATEGORIES = [
+  "decisions",
+  "patterns",
+  "troubleshooting",
+  "conventions",
+  "architecture"
+];
+export {
+  CATEGORY_PATTERN,
+  CHUNK_SIZES,
+  DEFAULT_CATEGORIES,
+  EMBEDDING_DEFAULTS,
+  FILE_LIMITS,
+  SEARCH_DEFAULTS,
+  STORE_DEFAULTS
+};
+//# sourceMappingURL=constants.js.map

package/packages/core/dist/content-detector.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Detects content type from file path and extension.
+ */
+import type { ContentType } from './types.js';
+/**
+ * Detect the content type of a file based on its path.
+ */
+export declare function detectContentType(filePath: string): ContentType;
+//# sourceMappingURL=content-detector.d.ts.map

package/packages/core/dist/content-detector.js

@@ -0,0 +1,79 @@
+import { basename, extname } from "node:path";
+const EXTENSION_MAP = {
+  ".ts": "code-typescript",
+  ".tsx": "code-typescript",
+  ".mts": "code-typescript",
+  ".cts": "code-typescript",
+  ".js": "code-javascript",
+  ".jsx": "code-javascript",
+  ".mjs": "code-javascript",
+  ".cjs": "code-javascript",
+  ".py": "code-python",
+  ".json": "config-json",
+  ".yaml": "config-yaml",
+  ".yml": "config-yaml",
+  ".toml": "config-toml",
+  ".env": "config-env",
+  ".md": "markdown",
+  ".mdx": "markdown"
+};
+const TEST_PATTERNS = [
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /(^|\/)__tests__\//,
+  /(^|\/)test\//,
+  /(^|\/)tests\//,
+  /(^|\/)spec\//,
+  /(^|\/)fixtures\//
+];
+const CDK_PATTERNS = [/\.stack\.[jt]s$/, /(^|\/)stacks\//, /(^|\/)constructs\//, /cdk\.json$/];
+function detectContentType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  const name = basename(filePath).toLowerCase();
+  if (filePath.includes("curated/")) {
+    return "curated-knowledge";
+  }
+  if (TEST_PATTERNS.some((p) => p.test(filePath))) {
+    return "test-code";
+  }
+  if (CDK_PATTERNS.some((p) => p.test(filePath))) {
+    return "cdk-stack";
+  }
+  if (ext in EXTENSION_MAP) {
+    return EXTENSION_MAP[ext];
+  }
+  if (name.startsWith(".env")) {
+    return "config-env";
+  }
+  const codeExtensions = [
+    ".go",
+    ".rs",
+    ".java",
+    ".rb",
+    ".php",
+    ".sh",
+    ".ps1",
+    ".sql",
+    ".graphql",
+    ".proto",
+    ".css",
+    ".scss",
+    ".less",
+    ".html",
+    ".htm",
+    ".vue",
+    ".svelte",
+    ".astro",
+    ".hbs",
+    ".ejs",
+    ".svg"
+  ];
+  if (codeExtensions.includes(ext)) {
+    return "code-other";
+  }
+  return "unknown";
+}
+export {
+  detectContentType
+};
+//# sourceMappingURL=content-detector.js.map

package/packages/core/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class KBError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+export declare class EmbeddingError extends KBError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class StoreError extends KBError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class IndexError extends KBError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class ConfigError extends KBError {
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/packages/core/dist/errors.js

@@ -0,0 +1,40 @@
+class KBError extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "KBError";
+  }
+}
+class EmbeddingError extends KBError {
+  constructor(message, cause) {
+    super(message, "EMBEDDING_ERROR", cause);
+    this.name = "EmbeddingError";
+  }
+}
+class StoreError extends KBError {
+  constructor(message, cause) {
+    super(message, "STORE_ERROR", cause);
+    this.name = "StoreError";
+  }
+}
+class IndexError extends KBError {
+  constructor(message, cause) {
+    super(message, "INDEX_ERROR", cause);
+    this.name = "IndexError";
+  }
+}
+class ConfigError extends KBError {
+  constructor(message, cause) {
+    super(message, "CONFIG_ERROR", cause);
+    this.name = "ConfigError";
+  }
+}
+export {
+  ConfigError,
+  EmbeddingError,
+  IndexError,
+  KBError,
+  StoreError
+};
+//# sourceMappingURL=errors.js.map

package/packages/core/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './constants.js';
+export { detectContentType } from './content-detector.js';
+export * from './errors.js';
+export * from './logger.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./constants.js";
+import { detectContentType } from "./content-detector.js";
+export * from "./errors.js";
+export * from "./logger.js";
+export * from "./types.js";
+export {
+  detectContentType
+};
+//# sourceMappingURL=index.js.map

package/packages/core/dist/logger.d.ts

@@ -0,0 +1,9 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function setLogLevel(level: LogLevel): void;
+export declare function createLogger(component: string): {
+    debug: (msg: string, data?: Record<string, unknown>) => void;
+    info: (msg: string, data?: Record<string, unknown>) => void;
+    warn: (msg: string, data?: Record<string, unknown>) => void;
+    error: (msg: string, data?: Record<string, unknown>) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/packages/core/dist/logger.js

@@ -0,0 +1,34 @@
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+let currentLevel = process.env.KB_LOG_LEVEL ?? "info";
+function setLogLevel(level) {
+  currentLevel = level;
+}
+function createLogger(component) {
+  function log(level, message, data) {
+    if (LOG_LEVELS[level] < LOG_LEVELS[currentLevel]) return;
+    const entry = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      component,
+      msg: message,
+      ...data
+    };
+    console.error(JSON.stringify(entry));
+  }
+  return {
+    debug: (msg, data) => log("debug", msg, data),
+    info: (msg, data) => log("info", msg, data),
+    warn: (msg, data) => log("warn", msg, data),
+    error: (msg, data) => log("error", msg, data)
+  };
+}
+export {
+  createLogger,
+  setLogLevel
+};
+//# sourceMappingURL=logger.js.map

package/packages/core/dist/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Core types for the MCP Knowledge Base system.
+ */
+/** The origin of a knowledge record — how it was created */
+export type KnowledgeOrigin = 'indexed' | 'curated' | 'produced';
+/** Content type classification */
+export type ContentType = 'documentation' | 'code-typescript' | 'code-javascript' | 'code-python' | 'code-other' | 'config-json' | 'config-yaml' | 'config-toml' | 'config-env' | 'test-code' | 'cdk-stack' | 'markdown' | 'curated-knowledge' | 'produced-knowledge' | 'unknown';
+/** A single knowledge record stored in the vector DB */
+export interface KnowledgeRecord {
+    /** Unique identifier (deterministic hash of source + chunk index) */
+    id: string;
+    /** The text content of this chunk */
+    content: string;
+    /** Source file path relative to workspace root */
+    sourcePath: string;
+    /** Content type classification */
+    contentType: ContentType;
+    /** Heading path for markdown (e.g., "## Setup > ### Prerequisites") */
+    headingPath?: string;
+    /** Zero-based chunk index within the source file */
+    chunkIndex: number;
+    /** Total number of chunks from this source file */
+    totalChunks: number;
+    /** Start line in source file (1-based) */
+    startLine: number;
+    /** End line in source file (1-based) */
+    endLine: number;
+    /** File hash for incremental indexing */
+    fileHash: string;
+    /** ISO timestamp when this record was created/updated */
+    indexedAt: string;
+    /** How this record was created */
+    origin: KnowledgeOrigin;
+    /** User-defined tags for categorization */
+    tags: string[];
+    /** Category for curated/produced knowledge */
+    category?: string;
+    /** Version number for curated knowledge updates */
+    version: number;
+}
+/** A raw chunk produced by a chunker before embedding */
+export interface RawChunk {
+    /** The text content */
+    text: string;
+    /** Source file path */
+    sourcePath: string;
+    /** Content type */
+    contentType: ContentType;
+    /** Heading path (markdown only) */
+    headingPath?: string;
+    /** Chunk index */
+    chunkIndex: number;
+    /** Total chunks from this file */
+    totalChunks: number;
+    /** Start line (1-based) */
+    startLine: number;
+    /** End line (1-based) */
+    endLine: number;
+}
+/** Metadata passed to a chunker */
+export interface ChunkMetadata {
+    /** File path relative to workspace root */
+    sourcePath: string;
+    /** Detected content type */
+    contentType: ContentType;
+}
+/** Search result returned by the store */
+export interface SearchResult {
+    /** The matching knowledge record */
+    record: KnowledgeRecord;
+    /** Similarity score (0-1, higher = more similar) */
+    score: number;
+}
+/** Configuration loaded from kb.config.json */
+export interface KBConfig {
+    sources: Array<{
+        path: string;
+        excludePatterns: string[];
+    }>;
+    indexing: {
+        chunkSize: number;
+        chunkOverlap: number;
+        minChunkSize: number;
+        /** Max files processed concurrently. Defaults to half of available CPU cores. */
+        concurrency?: number;
+    };
+    embedding: {
+        model: string;
+        dimensions: number;
+    };
+    store: {
+        backend: string;
+        path: string;
+    };
+    curated: {
+        path: string;
+    };
+}
+/** Index statistics */
+export interface IndexStats {
+    totalRecords: number;
+    totalFiles: number;
+    contentTypeBreakdown: Record<string, number>;
+    lastIndexedAt: string | null;
+    storeBackend: string;
+    embeddingModel: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/core/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/packages/embeddings/dist/embedder.interface.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Embedding abstraction — allows swapping embedding models.
+ */
+export interface IEmbedder {
+    /** Generate an embedding vector for a single text string (used for documents/passages) */
+    embed(text: string): Promise<Float32Array>;
+    /**
+     * Generate an embedding vector for a search query.
+     * Some models (e.g., BGE) use a query prefix for asymmetric retrieval.
+     * Falls back to embed() if the model doesn't need query prefixing.
+     */
+    embedQuery(query: string): Promise<Float32Array>;
+    /** Generate embeddings for multiple text strings (batched, for documents/passages) */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /** The dimensionality of the embedding vectors */
+    readonly dimensions: number;
+    /** The model identifier */
+    readonly modelId: string;
+    /** Initialize the model (download if needed, load into memory) */
+    initialize(): Promise<void>;
+    /** Release model resources */
+    shutdown?(): Promise<void>;
+}
+//# sourceMappingURL=embedder.interface.d.ts.map

package/packages/embeddings/dist/embedder.interface.js

@@ -0,0 +1 @@
+//# sourceMappingURL=embedder.interface.js.map

package/packages/embeddings/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { IEmbedder } from './embedder.interface.js';
+export { OnnxEmbedder } from './onnx-embedder.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/embeddings/dist/index.js

@@ -0,0 +1,5 @@
+import { OnnxEmbedder } from "./onnx-embedder.js";
+export {
+  OnnxEmbedder
+};
+//# sourceMappingURL=index.js.map

package/packages/embeddings/dist/onnx-embedder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ONNX-based embedder using @huggingface/transformers.
+ * Uses mixedbread-ai/mxbai-embed-large-v1 (1024 dimensions, ~1.3GB ONNX model).
+ * BGE-derived models use query prefixing for asymmetric retrieval (short query → long document).
+ */
+import type { IEmbedder } from './embedder.interface.js';
+export declare class OnnxEmbedder implements IEmbedder {
+    private pipe;
+    readonly dimensions: number;
+    readonly modelId: string;
+    private readonly queryPrefix;
+    constructor(options?: {
+        model?: string;
+        dimensions?: number;
+        queryPrefix?: string;
+    });
+    private detectQueryPrefix;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    embed(text: string): Promise<Float32Array>;
+    embedQuery(query: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+}
+//# sourceMappingURL=onnx-embedder.d.ts.map

package/packages/embeddings/dist/onnx-embedder.js

@@ -0,0 +1,82 @@
+import { pipeline } from "@huggingface/transformers";
+import { EMBEDDING_DEFAULTS } from "@kb/core";
+class OnnxEmbedder {
+  pipe = null;
+  dimensions;
+  modelId;
+  queryPrefix;
+  constructor(options) {
+    this.modelId = options?.model ?? EMBEDDING_DEFAULTS.model;
+    this.dimensions = options?.dimensions ?? EMBEDDING_DEFAULTS.dimensions;
+    this.queryPrefix = options?.queryPrefix ?? this.detectQueryPrefix(this.modelId);
+  }
+  detectQueryPrefix(modelId) {
+    const id = modelId.toLowerCase();
+    if (id.includes("bge") || id.includes("mxbai-embed")) {
+      return "Represent this sentence for searching relevant passages: ";
+    }
+    if (id.includes("/e5-") || id.includes("multilingual-e5")) {
+      return "query: ";
+    }
+    return "";
+  }
+  async initialize() {
+    if (this.pipe) return;
+    try {
+      this.pipe = await pipeline("feature-extraction", this.modelId, {
+        dtype: "fp32"
+      });
+    } catch (err) {
+      throw new Error(
+        `Failed to initialize embedding model "${this.modelId}": ${err.message}`
+      );
+    }
+  }
+  async shutdown() {
+    this.pipe = null;
+  }
+  async embed(text) {
+    if (!this.pipe) {
+      await this.initialize();
+    }
+    const output = await this.pipe?.(text, {
+      pooling: "mean",
+      normalize: true
+    });
+    if (!output) throw new Error("Embedding pipeline returned no output");
+    return new Float32Array(output.data);
+  }
+  async embedQuery(query) {
+    return this.embed(this.queryPrefix + query);
+  }
+  async embedBatch(texts) {
+    if (texts.length === 0) return [];
+    if (!this.pipe) {
+      await this.initialize();
+    }
+    const results = [];
+    const BATCH_SIZE = 32;
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+      const batch = texts.slice(i, i + BATCH_SIZE);
+      const output = await this.pipe?.(batch, {
+        pooling: "mean",
+        normalize: true
+      });
+      if (!output) throw new Error("Embedding pipeline returned no output");
+      if (batch.length === 1) {
+        results.push(new Float32Array(output.data));
+      } else {
+        for (let j = 0; j < batch.length; j++) {
+          const start = j * this.dimensions;
+          const slice = output.data.slice(start, start + this.dimensions);
+          results.push(new Float32Array(slice));
+        }
+      }
+    }
+    return results;
+  }
+}
+export {
+  OnnxEmbedder
+};
+//# sourceMappingURL=onnx-embedder.js.map

package/packages/indexer/dist/file-hasher.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate a deterministic hash for a file's content.
+ * Used for incremental indexing -- skip files that haven't changed.
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Generate a deterministic ID for a knowledge record.
+ * Based on source path + chunk index to ensure idempotent upserts.
+ */
+export declare function generateRecordId(sourcePath: string, chunkIndex: number): string;
+//# sourceMappingURL=file-hasher.d.ts.map

package/packages/indexer/dist/file-hasher.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+function generateRecordId(sourcePath, chunkIndex) {
+  const input = `${sourcePath}:${chunkIndex}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+export {
+  generateRecordId,
+  hashContent
+};
+//# sourceMappingURL=file-hasher.js.map

package/packages/indexer/dist/filesystem-crawler.d.ts

@@ -0,0 +1,27 @@
+export interface CrawlResult {
+    /** File path relative to workspace root */
+    relativePath: string;
+    /** Absolute file path */
+    absolutePath: string;
+    /** File content */
+    content: string;
+    /** File extension (lowercase, with dot) */
+    extension: string;
+}
+export interface CrawlOptions {
+    /** Glob patterns to exclude */
+    excludePatterns: string[];
+    /** Root directory to crawl */
+    rootDir: string;
+}
+/**
+ * Crawl a directory tree and yield files that should be indexed.
+ */
+export declare class FilesystemCrawler {
+    /** Binary file extensions that should always be skipped */
+    private static readonly BINARY_EXTENSIONS;
+    crawl(options: CrawlOptions): Promise<CrawlResult[]>;
+    private walkDir;
+    private isExcluded;
+}
+//# sourceMappingURL=filesystem-crawler.d.ts.map