@kb-labs/adapters 0.5.0

package/packages/adapters-pino-http/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/adapters-pino-http/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kb-labs/adapters-pino-http",
+  "version": "0.5.0",
+  "description": "Pino HTTP transport for streaming logs to REST API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "pino": "latest",
+    "pino-abstract-transport": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-pino-http/src/index.ts

@@ -0,0 +1,229 @@
+/**
+ * @module @kb-labs/adapters-pino-http
+ * Pino HTTP transport for streaming logs to REST API
+ *
+ * This transport receives logs from Pino, batches them, and sends to
+ * REST API's /logs/ingest endpoint via HTTP POST.
+ *
+ * Features:
+ * - Batching (configurable batch size and flush interval)
+ * - Retry with exponential backoff
+ * - Graceful shutdown (flushes pending logs before exit)
+ * - Error handling (logs to stderr if HTTP fails)
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import pinoHttp from '@kb-labs/adapters-pino-http';
+ *
+ * const logger = pino({
+ *   transport: {
+ *     target: '@kb-labs/adapters-pino-http',
+ *     options: {
+ *       url: 'http://localhost:5050/api/v1/logs/ingest',
+ *       batchSize: 50,
+ *       flushIntervalMs: 3000,
+ *     },
+ *   },
+ * });
+ *
+ * logger.info('Hello from Pino HTTP Transport!');
+ * ```
+ */
+
+import build from "pino-abstract-transport";
+
+/**
+ * Configuration for HTTP transport
+ */
+export interface HTTPTransportOptions {
+  /** REST API URL for log ingestion (default: http://localhost:5050/api/v1/logs/ingest) */
+  url?: string;
+
+  /** Number of logs to batch before sending (default: 50) */
+  batchSize?: number;
+
+  /** Max time in ms to wait before flushing batch (default: 3000ms = 3s) */
+  flushIntervalMs?: number;
+
+  /** Number of retry attempts on HTTP failure (default: 3) */
+  retryAttempts?: number;
+
+  /** Initial retry delay in ms (default: 1000ms = 1s) */
+  retryDelayMs?: number;
+
+  /** Custom HTTP headers (e.g., for authentication) */
+  headers?: Record<string, string>;
+
+  /** Enable debug logging to stderr (default: false) */
+  debug?: boolean;
+}
+
+/**
+ * Create Pino HTTP transport
+ *
+ * This is the main export that Pino will call when loading the transport.
+ * Pino expects a function that returns a Promise resolving to a writable stream.
+ */
+export default async function (opts: HTTPTransportOptions) {
+  const config = {
+    url: opts.url || "http://localhost:5050/api/v1/logs/ingest",
+    batchSize: opts.batchSize || 50,
+    flushIntervalMs: opts.flushIntervalMs || 3000,
+    retryAttempts: opts.retryAttempts || 3,
+    retryDelayMs: opts.retryDelayMs || 1000,
+    headers: opts.headers || {},
+    debug: opts.debug || false,
+  };
+
+  const batch: any[] = [];
+  let flushTimer: NodeJS.Timeout | null = null;
+  let isShuttingDown = false;
+
+  /**
+   * Send batch to REST API with retry logic
+   */
+  const flush = async (): Promise<void> => {
+    if (batch.length === 0) {
+      return;
+    }
+
+    // Copy batch and clear immediately to avoid blocking
+    const logs = [...batch];
+    batch.length = 0;
+
+    if (config.debug) {
+      console.error(`[PinoHTTP] Flushing ${logs.length} logs to ${config.url}`);
+    }
+
+    // Retry with exponential backoff
+    for (let attempt = 0; attempt < config.retryAttempts; attempt++) {
+      try {
+         
+        const response = await fetch(config.url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...config.headers,
+          },
+          body: JSON.stringify(logs),
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        if (config.debug) {
+          console.error("[PinoHTTP] Flush successful");
+        }
+
+        return; // Success!
+      } catch (error) {
+        const isLastAttempt = attempt === config.retryAttempts - 1;
+
+        if (isLastAttempt) {
+          console.error("[PinoHTTP] Failed to send logs after retries:", error);
+          return; // Give up after max retries
+        }
+
+        // Exponential backoff: 1s, 2s, 4s, 8s...
+        const delayMs = config.retryDelayMs * Math.pow(2, attempt);
+
+        if (config.debug) {
+          console.error(
+            `[PinoHTTP] Retry ${attempt + 1}/${config.retryAttempts} after ${delayMs}ms`,
+          );
+        }
+
+         
+        await new Promise((resolve) => {
+          setTimeout(resolve, delayMs);
+        });
+      }
+    }
+  };
+
+  /**
+   * Schedule next flush
+   */
+  const scheduleFlush = (): void => {
+    if (flushTimer !== null) {
+      return;
+    } // Timer already scheduled
+
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush(); // Fire and forget
+    }, config.flushIntervalMs);
+  };
+
+  /**
+   * Graceful shutdown: flush pending logs before exit
+   */
+  const shutdown = async (): Promise<void> => {
+    if (isShuttingDown) {
+      return;
+    }
+    isShuttingDown = true;
+
+    if (config.debug) {
+      console.error("[PinoHTTP] Shutting down, flushing pending logs...");
+    }
+
+    // Clear timer
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+
+    // Flush remaining logs
+    await flush();
+
+    if (config.debug) {
+      console.error("[PinoHTTP] Shutdown complete");
+    }
+  };
+
+  // Register shutdown handlers
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  process.on("beforeExit", shutdown);
+
+  /**
+   * Build abstract transport stream
+   *
+   * Pino will write log objects to this stream.
+   * We batch them and send to HTTP endpoint.
+   */
+  return build(
+    async (source) => {
+      for await (const log of source) {
+        if (isShuttingDown) {
+          // Ignore new logs during shutdown
+          continue;
+        }
+
+        // Add log to batch
+        batch.push(log);
+
+        // Immediate flush if batch is full
+        if (batch.length >= config.batchSize) {
+          if (flushTimer !== null) {
+            clearTimeout(flushTimer);
+            flushTimer = null;
+          }
+          await flush();
+        } else {
+          // Schedule delayed flush
+          scheduleFlush();
+        }
+      }
+    },
+    {
+      // Close handler - flush remaining logs
+      close: async () => {
+        await shutdown();
+      },
+    },
+  );
+}

package/packages/adapters-pino-http/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-pino-http/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-pino-http/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  dts: true,
+});

package/packages/adapters-qdrant/README.md

@@ -0,0 +1,166 @@
+# @kb-labs/adapters-qdrant
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+High-performance vector database adapter for semantic search and RAG applications using Qdrant.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `IVectorStore` |
+| **Type** | `core` |
+| **Requires** | None |
+| **Category** | Database / AI |
+
+## Features
+
+- **Vector Search** - Fast nearest neighbor search
+- **Hybrid Search** - Combine dense and sparse vectors
+- **Filtering** - Payload-based filtering with any query
+- **Batch Operations** - Efficient bulk upsert and delete
+- **Scalable** - Handles millions of vectors
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-qdrant
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "vectorStore": "@kb-labs/adapters-qdrant"
+    },
+    "adapterOptions": {
+      "vectorStore": {
+        "url": "http://localhost:6333",
+        "collectionName": "kb-vectors",
+        "dimension": 1536
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | - | Qdrant server URL |
+| `apiKey` | `string` | - | API key for authentication (optional) |
+| `collectionName` | `string` | `"kb-vectors"` | Collection name |
+| `dimension` | `number` | `1536` | Vector dimension (1536 for OpenAI) |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Upsert vectors
+await platform.vectorStore.upsert([
+  {
+    id: 'doc-1',
+    vector: [0.1, 0.2, ...], // 1536 dimensions
+    payload: { title: 'Document 1', category: 'tech' }
+  }
+]);
+
+// Search
+const results = await platform.vectorStore.search({
+  vector: queryVector,
+  limit: 10,
+  filter: { category: 'tech' }
+});
+
+// Delete
+await platform.vectorStore.delete(['doc-1', 'doc-2']);
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-qdrant';
+
+const vectorStore = createAdapter({
+  url: 'http://localhost:6333',
+  collectionName: 'test-vectors',
+  dimension: 1536
+});
+
+await vectorStore.upsert([{ id: '1', vector: [...], payload: {} }]);
+```
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'qdrant-vectorstore',
+  name: 'Qdrant Vector Store',
+  version: '1.0.0',
+  implements: 'IVectorStore',
+  capabilities: {
+    search: true,
+    batch: true,
+    custom: {
+      hybridSearch: true,
+      filtering: true,
+    },
+  },
+}
+```
+
+## FAQ
+
+<details>
+<summary><strong>Q: How do I start Qdrant locally?</strong></summary>
+
+Use Docker:
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+</details>
+
+<details>
+<summary><strong>Q: What embedding dimension should I use?</strong></summary>
+
+- OpenAI `text-embedding-3-small`: 1536
+- OpenAI `text-embedding-3-large`: 3072
+- Cohere: 1024
+</details>
+
+<details>
+<summary><strong>Q: How do I use hybrid search?</strong></summary>
+
+Enable hybrid search in your query:
+
+```typescript
+const results = await vectorStore.search({
+  vector: denseVector,
+  sparseVector: sparseVector,
+  limit: 10
+});
+```
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-openai` | Generate embeddings for vectors |
+| `@kb-labs/adapters-mongodb` | Document storage alongside vectors |
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-qdrant/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/adapters-qdrant/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kb-labs/adapters-qdrant",
+  "version": "0.5.0",
+  "description": "Qdrant adapter implementing IVectorStore interface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@qdrant/js-client-rest": "^1.12.0"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}