@vibe-agent-toolkit/rag 0.1.6 → 0.1.8

package/README.md

@@ -16,6 +16,75 @@ This package provides the core interfaces and schemas for RAG functionality in V
 **What's NOT included:**
 - Vector database implementations (see `@vibe-agent-toolkit/rag-lancedb`)
 
+## Custom Metadata
+
+By default, RAG chunks include sensible metadata fields optimized for markdown documentation (filePath, tags, type, headingPath, etc.). You can extend or completely replace these defaults with your own custom metadata.
+
+### Architecture
+
+RAG chunks are composed of two parts:
+
+1. **CoreRAGChunk** - Required fields for RAG functionality (identity, content, vectors, context)
+2. **Metadata** - Flexible fields for filtering and organization
+
+The default `RAGChunk` type is `CoreRAGChunk & DefaultRAGMetadata`.
+
+### Defining Custom Metadata
+
+Use Zod to define your custom metadata schema:
+
+```typescript
+import { z } from 'zod';
+import {
+  createCustomRAGChunkSchema,
+  CoreRAGChunkSchema,
+  DefaultRAGMetadataSchema,
+} from '@vibe-agent-toolkit/rag';
+
+// Option 1: Extend default metadata
+const ExtendedMetadataSchema = DefaultRAGMetadataSchema.extend({
+  domain: z.string(),
+  priority: z.number().optional(),
+});
+
+// Option 2: Replace with custom metadata
+const CustomMetadataSchema = z.object({
+  sourceUrl: z.string(),
+  domain: z.string(),
+  category: z.string().optional(),
+  keywords: z.array(z.string()),
+});
+
+// Create chunk schema
+const CustomChunkSchema = createCustomRAGChunkSchema(CustomMetadataSchema);
+type CustomChunk = z.infer<typeof CustomChunkSchema>;
+```
+
+### Type Safety
+
+TypeScript automatically infers types from your Zod schema:
+
+```typescript
+const chunk: CustomChunk = {
+  // Core fields (required)
+  chunkId: 'chunk-1',
+  resourceId: 'doc-1',
+  content: 'Authentication guide',
+  contentHash: 'abc123',
+  tokenCount: 50,
+  embedding: [0.1, 0.2, 0.3],
+  embeddingModel: 'text-embedding-3-small',
+  embeddedAt: new Date(),
+
+  // Custom metadata fields
+  sourceUrl: 'https://example.com/docs/auth.md',
+  domain: 'security',
+  keywords: ['auth', 'oauth', 'jwt'],
+};
+```
+
+See the [LanceDB provider documentation](../rag-lancedb/README.md) for usage with databases.
+
 ## Installation
 
 ```bash

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Abstract RAG interfaces and shared implementations for vibe-agent-toolkit.
  */
 export type { RAGQuery, RAGChunk, RAGResult, RAGStats, IndexResult, RAGQueryProvider, RAGAdminProvider, EmbeddingProvider, TokenCounter, } from './interfaces/index.js';
-export { RAGChunkSchema, RAGQuerySchema, RAGResultSchema, RAGStatsSchema, IndexResultSchema, } from './schemas/index.js';
+export { CoreRAGChunkSchema, type CoreRAGChunk, DefaultRAGMetadataSchema, type DefaultRAGMetadata, RAGChunkSchema, RAGQuerySchema, RAGResultSchema, RAGStatsSchema, IndexResultSchema, createCustomRAGChunkSchema, } from './schemas/index.js';
 export { RAGChunkJsonSchema, RAGQueryJsonSchema, RAGResultJsonSchema, RAGStatsJsonSchema, IndexResultJsonSchema, jsonSchemas, } from './schemas/json-schema.js';
 export { ApproximateTokenCounter, FastTokenCounter } from './token-counters/index.js';
 export { OpenAIEmbeddingProvider, TransformersEmbeddingProvider, type OpenAIEmbeddingConfig, type TransformersEmbeddingConfig, } from './embedding-providers/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGtF,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,QAAQ,GACd,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGtF,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,QAAQ,GACd,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -4,7 +4,7 @@
  * Abstract RAG interfaces and shared implementations for vibe-agent-toolkit.
  */
 // Schemas (Zod)
-export { RAGChunkSchema, RAGQuerySchema, RAGResultSchema, RAGStatsSchema, IndexResultSchema, } from './schemas/index.js';
+export { CoreRAGChunkSchema, DefaultRAGMetadataSchema, RAGChunkSchema, RAGQuerySchema, RAGResultSchema, RAGStatsSchema, IndexResultSchema, createCustomRAGChunkSchema, } from './schemas/index.js';
 // JSON Schemas
 export { RAGChunkJsonSchema, RAGQueryJsonSchema, RAGResultJsonSchema, RAGStatsJsonSchema, IndexResultJsonSchema, jsonSchemas, } from './schemas/json-schema.js';
 // Token Counters

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,gBAAgB;AAChB,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAe;AACf,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAElC,iBAAiB;AACjB,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEtF,sBAAsB;AACtB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAG9B,MAAM,gCAAgC,CAAC;AAExC,WAAW;AACX,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GAKjB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,gBAAgB;AAChB,OAAO,EACL,kBAAkB,EAElB,wBAAwB,EAExB,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,eAAe;AACf,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAElC,iBAAiB;AACjB,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEtF,sBAAsB;AACtB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAG9B,MAAM,gCAAgC,CAAC;AAExC,WAAW;AACX,OAAO,EACL,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GAKjB,MAAM,qBAAqB,CAAC"}

package/dist/interfaces/chunk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * RAGChunk interface
+ *
+ * Backward-compatible alias combining CoreRAGChunk + DefaultRAGMetadata.
+ * Existing code using RAGChunk continues to work unchanged.
+ */
+import type { CoreRAGChunk } from '../schemas/core-chunk.js';
+import type { DefaultRAGMetadata } from '../schemas/default-metadata.js';
+/**
+ * RAGChunk
+ *
+ * Standard RAG chunk type with default metadata.
+ * This is the backward-compatible type that existing code uses.
+ */
+export type RAGChunk = CoreRAGChunk & DefaultRAGMetadata;
+//# sourceMappingURL=chunk.d.ts.map

package/dist/interfaces/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/interfaces/chunk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,kBAAkB,CAAC"}

package/dist/interfaces/chunk.js

@@ -0,0 +1,8 @@
+/**
+ * RAGChunk interface
+ *
+ * Backward-compatible alias combining CoreRAGChunk + DefaultRAGMetadata.
+ * Existing code using RAGChunk continues to work unchanged.
+ */
+export {};
+//# sourceMappingURL=chunk.js.map

package/dist/interfaces/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/interfaces/chunk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/interfaces/index.d.ts

@@ -3,7 +3,10 @@
  *
  * Core contracts for RAG providers, embedding providers, and token counters.
  */
-export type { RAGQuery, RAGChunk, RAGResult, RAGStats, IndexResult, RAGQueryProvider, RAGAdminProvider, } from './provider.js';
+export type { CoreRAGChunk } from '../schemas/core-chunk.js';
+export type { DefaultRAGMetadata } from '../schemas/default-metadata.js';
+export type { RAGChunk } from './chunk.js';
+export type { RAGQuery, RAGResult, RAGStats, IndexResult, RAGQueryProvider, RAGAdminProvider, } from './provider.js';
 export type { EmbeddingProvider } from './embedding.js';
 export type { TokenCounter } from './token-counter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/interfaces/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,YAAY,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/interfaces/provider.d.ts

@@ -5,29 +5,29 @@
  * Separates read operations (RAGQueryProvider) from write operations (RAGAdminProvider).
  */
 import type { ResourceMetadata } from '@vibe-agent-toolkit/resources';
+import type { CoreRAGChunk } from '../schemas/core-chunk.js';
+import type { DefaultRAGMetadata } from '../schemas/default-metadata.js';
 /**
  * Query for RAG database
+ *
+ * Generic over metadata type for type-safe filtering.
  */
-export interface RAGQuery {
+export interface RAGQuery<TMetadata extends Record<string, unknown> = DefaultRAGMetadata> {
     /** Search query text */
     text: string;
     /** Maximum results to return (default: 10) */
     limit?: number;
-    /** Metadata filters */
+    /** Filters */
     filters?: {
         /** Filter by resource ID(s) */
         resourceId?: string | string[];
-        /** Filter by tags */
-        tags?: string[];
-        /** Filter by resource type */
-        type?: string;
-        /** Filter by heading path (e.g., "Architecture > RAG Design") */
-        headingPath?: string;
         /** Filter by date range */
         dateRange?: {
             start: Date;
             end: Date;
         };
+        /** Metadata filters (type-safe based on TMetadata) */
+        metadata?: Partial<TMetadata>;
     };
     /** Hybrid search configuration (vector + keyword) */
     hybridSearch?: {
@@ -39,33 +39,18 @@ export interface RAGQuery {
 /**
  * Chunk returned from RAG query
  * Note: Full schema defined in schemas/chunk.ts
+ *
+ * Re-exported here for convenience.
  */
-export interface RAGChunk {
-    chunkId: string;
-    resourceId: string;
-    content: string;
-    contentHash: string;
-    tokenCount: number;
-    headingPath?: string;
-    headingLevel?: number;
-    startLine?: number;
-    endLine?: number;
-    filePath: string;
-    tags?: string[];
-    type?: string;
-    title?: string;
-    embedding: number[];
-    embeddingModel: string;
-    embeddedAt: Date;
-    previousChunkId?: string;
-    nextChunkId?: string;
-}
+export type { RAGChunk } from './chunk.js';
 /**
  * Result from RAG query
+ *
+ * Generic over metadata type - chunks have type CoreRAGChunk & TMetadata.
  */
-export interface RAGResult {
+export interface RAGResult<TMetadata extends Record<string, unknown> = DefaultRAGMetadata> {
     /** Matched chunks, sorted by relevance */
-    chunks: RAGChunk[];
+    chunks: Array<CoreRAGChunk & TMetadata>;
     /** Search statistics */
     stats: {
         totalMatches: number;
@@ -105,12 +90,13 @@ export interface IndexResult {
  * RAG Query Provider (read-only)
  *
  * This is what agents use at runtime to query the RAG database.
+ * Generic over metadata type for type-safe queries and results.
  */
-export interface RAGQueryProvider {
+export interface RAGQueryProvider<TMetadata extends Record<string, unknown> = DefaultRAGMetadata> {
     /**
      * Query the RAG database
      */
-    query(query: RAGQuery): Promise<RAGResult>;
+    query(query: RAGQuery<TMetadata>): Promise<RAGResult<TMetadata>>;
     /**
      * Get database statistics
      */
@@ -121,8 +107,9 @@ export interface RAGQueryProvider {
  *
  * This is what build tools and admin processes use to index/update the RAG database.
  * Extends RAGQueryProvider to include write operations.
+ * Generic over metadata type for type-safe operations.
  */
-export interface RAGAdminProvider extends RAGQueryProvider {
+export interface RAGAdminProvider<TMetadata extends Record<string, unknown> = DefaultRAGMetadata> extends RAGQueryProvider<TMetadata> {
     /**
      * Index resources into the RAG database
      * - Detects changes via content hash

package/dist/interfaces/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/interfaces/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/interfaces/provider.ts"],"names":[],"mappings":"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"}

package/dist/schemas/chunk.d.ts

@@ -1,14 +1,15 @@
 /**
  * RAGChunk Zod schema
  *
- * Defines the structure of a chunk in the RAG database.
+ * Backward-compatible schema combining CoreRAGChunkSchema + DefaultRAGMetadataSchema.
  */
-import { z } from 'zod';
+import type { z } from 'zod';
+import { CoreRAGChunkSchema } from './core-chunk.js';
 /**
- * RAGChunk Schema
+ * RAGChunkSchema
  *
- * Rich metadata schema for RAG chunks, enabling filtered searches
- * and context expansion.
+ * Standard RAG chunk schema with default metadata.
+ * Composed from CoreRAGChunkSchema + DefaultRAGMetadataSchema.
  */
 export declare const RAGChunkSchema: z.ZodObject<{
     chunkId: z.ZodString;
@@ -16,60 +17,77 @@ export declare const RAGChunkSchema: z.ZodObject<{
     content: z.ZodString;
     contentHash: z.ZodString;
     tokenCount: z.ZodNumber;
-    headingPath: z.ZodOptional<z.ZodString>;
-    headingLevel: z.ZodOptional<z.ZodNumber>;
-    startLine: z.ZodOptional<z.ZodNumber>;
-    endLine: z.ZodOptional<z.ZodNumber>;
-    filePath: z.ZodString;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    type: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
     embedding: z.ZodArray<z.ZodNumber, "many">;
     embeddingModel: z.ZodString;
     embeddedAt: z.ZodDate;
     previousChunkId: z.ZodOptional<z.ZodString>;
     nextChunkId: z.ZodOptional<z.ZodString>;
+} & {
+    filePath: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    type: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    headingPath: z.ZodOptional<z.ZodString>;
+    headingLevel: z.ZodOptional<z.ZodNumber>;
+    startLine: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     chunkId: string;
     resourceId: string;
     content: string;
     contentHash: string;
     tokenCount: number;
-    filePath: string;
     embedding: number[];
     embeddingModel: string;
     embeddedAt: Date;
+    filePath: string;
+    type?: string | undefined;
+    previousChunkId?: string | undefined;
+    nextChunkId?: string | undefined;
+    tags?: string[] | undefined;
+    title?: string | undefined;
     headingPath?: string | undefined;
     headingLevel?: number | undefined;
     startLine?: number | undefined;
     endLine?: number | undefined;
-    type?: string | undefined;
-    tags?: string[] | undefined;
-    title?: string | undefined;
-    previousChunkId?: string | undefined;
-    nextChunkId?: string | undefined;
 }, {
     chunkId: string;
     resourceId: string;
     content: string;
     contentHash: string;
     tokenCount: number;
-    filePath: string;
     embedding: number[];
     embeddingModel: string;
     embeddedAt: Date;
+    filePath: string;
+    type?: string | undefined;
+    previousChunkId?: string | undefined;
+    nextChunkId?: string | undefined;
+    tags?: string[] | undefined;
+    title?: string | undefined;
     headingPath?: string | undefined;
     headingLevel?: number | undefined;
     startLine?: number | undefined;
     endLine?: number | undefined;
-    type?: string | undefined;
-    tags?: string[] | undefined;
-    title?: string | undefined;
-    previousChunkId?: string | undefined;
-    nextChunkId?: string | undefined;
 }>;
 /**
  * RAGChunk TypeScript type (inferred from schema)
  */
 export type RAGChunk = z.infer<typeof RAGChunkSchema>;
+/**
+ * Helper function to create custom RAG chunk schemas
+ *
+ * @param metadataSchema - Custom metadata schema
+ * @returns Merged schema (CoreRAGChunk + custom metadata)
+ *
+ * @example
+ * const MyMetadataSchema = z.object({
+ *   domain: z.string(),
+ *   category: z.string().optional(),
+ * });
+ *
+ * const MyChunkSchema = createCustomRAGChunkSchema(MyMetadataSchema);
+ * type MyChunk = z.infer<typeof MyChunkSchema>;
+ */
+export declare function createCustomRAGChunkSchema<T extends z.ZodRawShape>(metadataSchema: z.ZodObject<T>): z.ZodObject<z.objectUtil.extendShape<typeof CoreRAGChunkSchema.shape, T>>;
 //# sourceMappingURL=chunk.d.ts.map

package/dist/schemas/chunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/schemas/chunk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BzB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/schemas/chunk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAqD,CAAC;AAEjF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAChE,cAAc,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAE3E"}

package/dist/schemas/chunk.js

@@ -1,39 +1,33 @@
 /**
  * RAGChunk Zod schema
  *
- * Defines the structure of a chunk in the RAG database.
+ * Backward-compatible schema combining CoreRAGChunkSchema + DefaultRAGMetadataSchema.
  */
-import { z } from 'zod';
+import { CoreRAGChunkSchema } from './core-chunk.js';
+import { DefaultRAGMetadataSchema } from './default-metadata.js';
 /**
- * RAGChunk Schema
+ * RAGChunkSchema
  *
- * Rich metadata schema for RAG chunks, enabling filtered searches
- * and context expansion.
+ * Standard RAG chunk schema with default metadata.
+ * Composed from CoreRAGChunkSchema + DefaultRAGMetadataSchema.
  */
-export const RAGChunkSchema = z.object({
-    // Identity
-    chunkId: z.string().describe('Unique chunk identifier (uuid)'),
-    resourceId: z.string().describe('Source resource ID from ResourceRegistry'),
-    // Content
-    content: z.string().describe('The actual text chunk'),
-    contentHash: z.string().describe('Hash of content for change detection'),
-    tokenCount: z.number().describe('Accurate token count from TokenCounter'),
-    // Structure (from markdown parsing)
-    headingPath: z.string().optional().describe('Full heading hierarchy: "Architecture > RAG Design"'),
-    headingLevel: z.number().optional().describe('Heading level (1-6) if chunk is under a heading'),
-    startLine: z.number().optional().describe('Starting line number in source file'),
-    endLine: z.number().optional().describe('Ending line number in source file'),
-    // Resource metadata (from ResourceRegistry - may be from frontmatter, inference, defaults, or config)
-    filePath: z.string().describe('Source file path'),
-    tags: z.array(z.string()).optional().describe('Resource tags'),
-    type: z.string().optional().describe('Resource type'),
-    title: z.string().optional().describe('Resource title'),
-    // Embedding metadata
-    embedding: z.array(z.number()).describe('Vector embedding'),
-    embeddingModel: z.string().describe('Model used: "text-embedding-3-small", "all-MiniLM-L6-v2", etc.'),
-    embeddedAt: z.date().describe('When embedding was generated'),
-    // Context (for retrieval)
-    previousChunkId: z.string().optional().describe('Previous chunk in document (for context)'),
-    nextChunkId: z.string().optional().describe('Next chunk in document (for context)'),
-});
+export const RAGChunkSchema = CoreRAGChunkSchema.merge(DefaultRAGMetadataSchema);
+/**
+ * Helper function to create custom RAG chunk schemas
+ *
+ * @param metadataSchema - Custom metadata schema
+ * @returns Merged schema (CoreRAGChunk + custom metadata)
+ *
+ * @example
+ * const MyMetadataSchema = z.object({
+ *   domain: z.string(),
+ *   category: z.string().optional(),
+ * });
+ *
+ * const MyChunkSchema = createCustomRAGChunkSchema(MyMetadataSchema);
+ * type MyChunk = z.infer<typeof MyChunkSchema>;
+ */
+export function createCustomRAGChunkSchema(metadataSchema) {
+    return CoreRAGChunkSchema.merge(metadataSchema);
+}
 //# sourceMappingURL=chunk.js.map

package/dist/schemas/chunk.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/schemas/chunk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,WAAW;IACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAC9D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IAE3E,UAAU;IACV,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACrD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACxE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAEzE,oCAAoC;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;IAClG,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAC/F,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IAChF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IAE5E,sGAAsG;IACtG,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACjD,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IAC9D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IACrD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAEvD,qBAAqB;IACrB,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC3D,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;IACrG,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAE7D,0BAA0B;IAC1B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IAC3F,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;CACpF,CAAC,CAAC"}
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/schemas/chunk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAOjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,0BAA0B,CACxC,cAA8B;IAE9B,OAAO,kBAAkB,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;AAClD,CAAC"}

package/dist/schemas/core-chunk.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Core RAG Chunk Zod schema
+ *
+ * Defines required fields for RAG functionality.
+ */
+import { z } from 'zod';
+/**
+ * CoreRAGChunkSchema
+ *
+ * Zod schema for core RAG chunk fields.
+ * These fields are required for all RAG implementations.
+ */
+export declare const CoreRAGChunkSchema: z.ZodObject<{
+    chunkId: z.ZodString;
+    resourceId: z.ZodString;
+    content: z.ZodString;
+    contentHash: z.ZodString;
+    tokenCount: z.ZodNumber;
+    embedding: z.ZodArray<z.ZodNumber, "many">;
+    embeddingModel: z.ZodString;
+    embeddedAt: z.ZodDate;
+    previousChunkId: z.ZodOptional<z.ZodString>;
+    nextChunkId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    chunkId: string;
+    resourceId: string;
+    content: string;
+    contentHash: string;
+    tokenCount: number;
+    embedding: number[];
+    embeddingModel: string;
+    embeddedAt: Date;
+    previousChunkId?: string | undefined;
+    nextChunkId?: string | undefined;
+}, {
+    chunkId: string;
+    resourceId: string;
+    content: string;
+    contentHash: string;
+    tokenCount: number;
+    embedding: number[];
+    embeddingModel: string;
+    embeddedAt: Date;
+    previousChunkId?: string | undefined;
+    nextChunkId?: string | undefined;
+}>;
+/**
+ * CoreRAGChunk TypeScript type (inferred from schema)
+ */
+export type CoreRAGChunk = z.infer<typeof CoreRAGChunkSchema>;
+//# sourceMappingURL=core-chunk.d.ts.map

package/dist/schemas/core-chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-chunk.d.ts","sourceRoot":"","sources":["../../src/schemas/core-chunk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkB7B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/schemas/core-chunk.js

@@ -0,0 +1,29 @@
+/**
+ * Core RAG Chunk Zod schema
+ *
+ * Defines required fields for RAG functionality.
+ */
+import { z } from 'zod';
+/**
+ * CoreRAGChunkSchema
+ *
+ * Zod schema for core RAG chunk fields.
+ * These fields are required for all RAG implementations.
+ */
+export const CoreRAGChunkSchema = z.object({
+    // Identity
+    chunkId: z.string().describe('Unique chunk identifier (uuid)'),
+    resourceId: z.string().describe('Source resource ID from ResourceRegistry'),
+    // Content
+    content: z.string().describe('The actual text chunk'),
+    contentHash: z.string().describe('Hash of content for change detection'),
+    tokenCount: z.number().describe('Accurate token count from TokenCounter'),
+    // Vectors
+    embedding: z.array(z.number()).describe('Vector embedding'),
+    embeddingModel: z.string().describe('Model used: "text-embedding-3-small", "all-MiniLM-L6-v2", etc.'),
+    embeddedAt: z.date().describe('When embedding was generated'),
+    // Context linking
+    previousChunkId: z.string().optional().describe('Previous chunk in document (for context expansion)'),
+    nextChunkId: z.string().optional().describe('Next chunk in document (for context expansion)'),
+});
+//# sourceMappingURL=core-chunk.js.map

package/dist/schemas/core-chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-chunk.js","sourceRoot":"","sources":["../../src/schemas/core-chunk.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,WAAW;IACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAC9D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IAE3E,UAAU;IACV,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACrD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACxE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAEzE,UAAU;IACV,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC3D,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;IACrG,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAE7D,kBAAkB;IAClB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;IACrG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;CAC9F,CAAC,CAAC"}

package/dist/schemas/default-metadata.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Default RAG Metadata Zod schema
+ *
+ * Defines sensible default metadata fields for markdown-centric RAG.
+ */
+import { z } from 'zod';
+/**
+ * DefaultRAGMetadataSchema
+ *
+ * Zod schema for default metadata fields.
+ * Optimized for markdown documentation with headings and structure.
+ */
+export declare const DefaultRAGMetadataSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    type: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    headingPath: z.ZodOptional<z.ZodString>;
+    headingLevel: z.ZodOptional<z.ZodNumber>;
+    startLine: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    filePath: string;
+    type?: string | undefined;
+    tags?: string[] | undefined;
+    title?: string | undefined;
+    headingPath?: string | undefined;
+    headingLevel?: number | undefined;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+}, {
+    filePath: string;
+    type?: string | undefined;
+    tags?: string[] | undefined;
+    title?: string | undefined;
+    headingPath?: string | undefined;
+    headingLevel?: number | undefined;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+}>;
+/**
+ * DefaultRAGMetadata TypeScript type (inferred from schema)
+ */
+export type DefaultRAGMetadata = z.infer<typeof DefaultRAGMetadataSchema>;
+//# sourceMappingURL=default-metadata.d.ts.map

package/dist/schemas/default-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-metadata.d.ts","sourceRoot":"","sources":["../../src/schemas/default-metadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYnC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/schemas/default-metadata.js

@@ -0,0 +1,25 @@
+/**
+ * Default RAG Metadata Zod schema
+ *
+ * Defines sensible default metadata fields for markdown-centric RAG.
+ */
+import { z } from 'zod';
+/**
+ * DefaultRAGMetadataSchema
+ *
+ * Zod schema for default metadata fields.
+ * Optimized for markdown documentation with headings and structure.
+ */
+export const DefaultRAGMetadataSchema = z.object({
+    // Source tracking
+    filePath: z.string().describe('Source file path (or URL, package ref, S3 URI, etc.)'),
+    // Optional markdown-centric fields
+    tags: z.array(z.string()).optional().describe('Resource tags for filtering'),
+    type: z.string().optional().describe('Resource type (e.g., "documentation", "api-reference")'),
+    title: z.string().optional().describe('Resource title'),
+    headingPath: z.string().optional().describe('Full heading hierarchy: "Architecture > RAG Design"'),
+    headingLevel: z.number().optional().describe('Heading level (1-6) if chunk is under a heading'),
+    startLine: z.number().optional().describe('Starting line number in source file'),
+    endLine: z.number().optional().describe('Ending line number in source file'),
+});
+//# sourceMappingURL=default-metadata.js.map

package/dist/schemas/default-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-metadata.js","sourceRoot":"","sources":["../../src/schemas/default-metadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,kBAAkB;IAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IAErF,mCAAmC;IACnC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC5E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;IAC9F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;IAClG,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAC/F,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IAChF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;CAC7E,CAAC,CAAC"}

package/dist/schemas/index.d.ts

@@ -3,7 +3,9 @@
  *
  * Zod schemas for RAG data structures with generated JSON schemas.
  */
-export { RAGChunkSchema, type RAGChunk } from './chunk.js';
+export { CoreRAGChunkSchema, type CoreRAGChunk } from './core-chunk.js';
+export { DefaultRAGMetadataSchema, type DefaultRAGMetadata } from './default-metadata.js';
+export { RAGChunkSchema, type RAGChunk, createCustomRAGChunkSchema } from './chunk.js';
 export { RAGQuerySchema, RAGResultSchema, type RAGQuery, type RAGResult } from './query.js';
 export { RAGStatsSchema, IndexResultSchema, type RAGStats, type IndexResult } from './admin.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/schemas/index.js

@@ -3,7 +3,9 @@
  *
  * Zod schemas for RAG data structures with generated JSON schemas.
  */
-export { RAGChunkSchema } from './chunk.js';
+export { CoreRAGChunkSchema } from './core-chunk.js';
+export { DefaultRAGMetadataSchema } from './default-metadata.js';
+export { RAGChunkSchema, createCustomRAGChunkSchema } from './chunk.js';
 export { RAGQuerySchema, RAGResultSchema } from './query.js';
 export { RAGStatsSchema, IndexResultSchema } from './admin.js';
 //# sourceMappingURL=index.js.map

package/dist/schemas/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAiC,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAmC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAA2B,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAiB,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAiC,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAmC,MAAM,YAAY,CAAC"}

package/dist/schemas/query.d.ts

@@ -35,18 +35,18 @@ export declare const RAGQuerySchema: z.ZodObject<{
         }>>;
     }, "strip", z.ZodTypeAny, {
         resourceId?: string | string[] | undefined;
-        headingPath?: string | undefined;
         type?: string | undefined;
         tags?: string[] | undefined;
+        headingPath?: string | undefined;
         dateRange?: {
             start: Date;
             end: Date;
         } | undefined;
     }, {
         resourceId?: string | string[] | undefined;
-        headingPath?: string | undefined;
         type?: string | undefined;
         tags?: string[] | undefined;
+        headingPath?: string | undefined;
         dateRange?: {
             start: Date;
             end: Date;
@@ -68,9 +68,9 @@ export declare const RAGQuerySchema: z.ZodObject<{
     limit?: number | undefined;
     filters?: {
         resourceId?: string | string[] | undefined;
-        headingPath?: string | undefined;
         type?: string | undefined;
         tags?: string[] | undefined;
+        headingPath?: string | undefined;
         dateRange?: {
             start: Date;
             end: Date;
@@ -85,9 +85,9 @@ export declare const RAGQuerySchema: z.ZodObject<{
     limit?: number | undefined;
     filters?: {
         resourceId?: string | string[] | undefined;
-        headingPath?: string | undefined;
         type?: string | undefined;
         tags?: string[] | undefined;
+        headingPath?: string | undefined;
         dateRange?: {
             start: Date;
             end: Date;
@@ -115,57 +115,58 @@ export declare const RAGResultSchema: z.ZodObject<{
         content: z.ZodString;
         contentHash: z.ZodString;
         tokenCount: z.ZodNumber;
-        headingPath: z.ZodOptional<z.ZodString>;
-        headingLevel: z.ZodOptional<z.ZodNumber>;
-        startLine: z.ZodOptional<z.ZodNumber>;
-        endLine: z.ZodOptional<z.ZodNumber>;
-        filePath: z.ZodString;
-        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        type: z.ZodOptional<z.ZodString>;
-        title: z.ZodOptional<z.ZodString>;
         embedding: z.ZodArray<z.ZodNumber, "many">;
         embeddingModel: z.ZodString;
         embeddedAt: z.ZodDate;
         previousChunkId: z.ZodOptional<z.ZodString>;
         nextChunkId: z.ZodOptional<z.ZodString>;
+    } & {
+        filePath: z.ZodString;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        type: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        headingPath: z.ZodOptional<z.ZodString>;
+        headingLevel: z.ZodOptional<z.ZodNumber>;
+        startLine: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         chunkId: string;
         resourceId: string;
         content: string;
         contentHash: string;
         tokenCount: number;
-        filePath: string;
         embedding: number[];
         embeddingModel: string;
         embeddedAt: Date;
+        filePath: string;
+        type?: string | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+        tags?: string[] | undefined;
+        title?: string | undefined;
         headingPath?: string | undefined;
         headingLevel?: number | undefined;
         startLine?: number | undefined;
         endLine?: number | undefined;
-        type?: string | undefined;
-        tags?: string[] | undefined;
-        title?: string | undefined;
-        previousChunkId?: string | undefined;
-        nextChunkId?: string | undefined;
     }, {
         chunkId: string;
         resourceId: string;
         content: string;
         contentHash: string;
         tokenCount: number;
-        filePath: string;
         embedding: number[];
         embeddingModel: string;
         embeddedAt: Date;
+        filePath: string;
+        type?: string | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+        tags?: string[] | undefined;
+        title?: string | undefined;
         headingPath?: string | undefined;
         headingLevel?: number | undefined;
         startLine?: number | undefined;
         endLine?: number | undefined;
-        type?: string | undefined;
-        tags?: string[] | undefined;
-        title?: string | undefined;
-        previousChunkId?: string | undefined;
-        nextChunkId?: string | undefined;
     }>, "many">;
     /** Search statistics */
     stats: z.ZodObject<{
@@ -203,19 +204,19 @@ export declare const RAGResultSchema: z.ZodObject<{
         content: string;
         contentHash: string;
         tokenCount: number;
-        filePath: string;
         embedding: number[];
         embeddingModel: string;
         embeddedAt: Date;
+        filePath: string;
+        type?: string | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+        tags?: string[] | undefined;
+        title?: string | undefined;
         headingPath?: string | undefined;
         headingLevel?: number | undefined;
         startLine?: number | undefined;
         endLine?: number | undefined;
-        type?: string | undefined;
-        tags?: string[] | undefined;
-        title?: string | undefined;
-        previousChunkId?: string | undefined;
-        nextChunkId?: string | undefined;
     }[];
     stats: {
         totalMatches: number;
@@ -232,19 +233,19 @@ export declare const RAGResultSchema: z.ZodObject<{
         content: string;
         contentHash: string;
         tokenCount: number;
-        filePath: string;
         embedding: number[];
         embeddingModel: string;
         embeddedAt: Date;
+        filePath: string;
+        type?: string | undefined;
+        previousChunkId?: string | undefined;
+        nextChunkId?: string | undefined;
+        tags?: string[] | undefined;
+        title?: string | undefined;
         headingPath?: string | undefined;
         headingLevel?: number | undefined;
         startLine?: number | undefined;
         endLine?: number | undefined;
-        type?: string | undefined;
-        tags?: string[] | undefined;
-        title?: string | undefined;
-        previousChunkId?: string | undefined;
-        nextChunkId?: string | undefined;
     }[];
     stats: {
         totalMatches: number;

package/dist/schemas/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/schemas/query.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,wBAAwB;;IAGxB,8CAA8C;;IAG9C,uBAAuB;;QAErB,+BAA+B;;QAE/B,qBAAqB;;QAErB,8BAA8B;;QAE9B,6BAA6B;;QAE7B,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAO7B,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKlC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAC1B,0CAA0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAG1C,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASxB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/schemas/query.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,wBAAwB;;IAGxB,8CAA8C;;IAG9C,uBAAuB;;QAErB,+BAA+B;;QAE/B,qBAAqB;;QAErB,8BAA8B;;QAE9B,6BAA6B;;QAE7B,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAO7B,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKlC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAC1B,0CAA0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAG1C,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASxB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/rag",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "description": "Abstract RAG (Retrieval-Augmented Generation) interfaces and shared implementations",
   "keywords": [
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/resources": "0.1.6",
-    "@vibe-agent-toolkit/utils": "0.1.6",
+    "@vibe-agent-toolkit/resources": "0.1.8",
+    "@vibe-agent-toolkit/utils": "0.1.8",
     "@xenova/transformers": "^2.17.0",
     "gpt-tokenizer": "^2.6.0",
     "zod": "^3.22.0",