@yolk-sdk/knowledge 0.0.1-canary.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yolk SDK contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @yolk-sdk/knowledge
+
+Domain-free knowledge record, artifact, representation, search, provenance, link, store, and context contracts.
+
+## Install
+
+```bash
+pnpm add @yolk-sdk/knowledge@canary @yolk-sdk/agent@canary effect
+```
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+
+## Subpaths
+
+| Subpath | Purpose |
+| --- | --- |
+| `@yolk-sdk/knowledge/records` | Knowledge record schemas and roles |
+| `@yolk-sdk/knowledge/artifacts` | Artifact catalog and blob-store contract |
+| `@yolk-sdk/knowledge/representations` | Agent-readable/searchable representations |
+| `@yolk-sdk/knowledge/chunking` | Search chunker contracts and defaults |
+| `@yolk-sdk/knowledge/embeddings` | Embedder contract and vector types |
+| `@yolk-sdk/knowledge/extraction` | Loaded source/extractor contract |
+| `@yolk-sdk/knowledge/ingestion` | Generic search ingestion pipeline |
+| `@yolk-sdk/knowledge/search` | Search interface, hybrid search, context packing |
+| `@yolk-sdk/knowledge/documents` | Collection, document, chunk, and search scope schemas |
+| `@yolk-sdk/knowledge/search-store` | Collection/document/chunk/search lifecycle store |
+| `@yolk-sdk/knowledge/summarization` | Optional title/summary service contract |
+| `@yolk-sdk/knowledge/provenance` | Source/provenance metadata |
+| `@yolk-sdk/knowledge/links` | Typed links between records |
+| `@yolk-sdk/knowledge/store` | Knowledge store lifecycle contract |
+| `@yolk-sdk/knowledge/context` | Context assembly helpers |
+| `@yolk-sdk/knowledge/agent` | Agent-facing helper contracts |
+
+## Imports
+
+```ts
+import { buildKnowledgeContext, KnowledgeStore } from '@yolk-sdk/knowledge'
+import { KnowledgeRecord } from '@yolk-sdk/knowledge/records'
+import { KnowledgeArtifactStore } from '@yolk-sdk/knowledge/artifacts'
+import { makeDefaultKnowledgeChunker } from '@yolk-sdk/knowledge/chunking'
+import { searchKnowledge } from '@yolk-sdk/knowledge/search'
+```
+
+## Migration
+
+Search APIs use canonical search naming. Removed APIs are intentionally not backward-compatible.
+
+| Removed | Use |
+| --- | --- |
+| `@yolk-sdk/knowledge/retrieval` | `@yolk-sdk/knowledge/search` |
+| `KnowledgeRetriever` | `KnowledgeSearcher` |
+| `retrieve(input)` | `search(input)` |
+| `KnowledgeRetrievalError` | `KnowledgeSearchError` |
+
+## Glossary
+
+| Term | Meaning |
+| --- | --- |
+| Knowledge record | Stable logical thing an agent can know about. Domain-free; hosts decide product meaning. |
+| Artifact | Stored source/blob attached to knowledge, such as a file or captured output. |
+| Representation | Agent-readable or searchable form of knowledge, usually text plus metadata. |
+| Provenance | Source metadata explaining where knowledge came from and how it was produced. |
+| Link | Typed relationship between knowledge records. |
+| Context | Model-ready knowledge selected for a run. Built from host policy. |
+| Context policy | Host intent for use: `pinned`, `routable`, `searchable`, or `archival`. |
+| Search index | Searchable corpus built from source documents, chunks, embeddings, and metadata. |
+| Collection | Named searchable document group with shared embedding and chunking config. |
+| Document | Source item tracked through search ingestion: pending, processing, ready, or error. |
+| Source | Document origin: file ref, URL, or raw text. |
+| Chunk | Searchable slice of a document with position and token count. |
+| Embedding | Numeric vector for semantic search. Hosts provide the embedding provider. |
+| Chunker | Service that splits extracted text into chunks. |
+| Extractor | Service that loads source content into text/title/summary/metadata. |
+| Ingestion | Pipeline that extracts, chunks, embeds, stores chunks, and marks document status. |
+| Search | Query-time search over search chunks, optionally packed into context text. |
+| Hybrid search | Search mode that fuses vector and text search rankings. |
+| Search scope | Caller-provided collection or collections to search. Package does not interpret tenant semantics. |
+| Search index store | Persistence contract for collections, documents, chunks, status, and search. |
+| Vector store | Lower-level vector persistence/search contract. |
+| Knowledge store | Persistence contract for non-index knowledge records and context assembly. |
+| Artifact store | Persistence contract for artifact bytes/metadata. |
+| Host | App using the package; owns auth, DB, object storage, providers, permissions, and policy. |
+
+## Context policy
+
+| Policy | Meaning |
+| --- | --- |
+| `pinned` | Host may inject into model startup context |
+| `routable` | Host may use for routing/dispatch decisions |
+| `searchable` | Host may expose through search tools |
+| `archival` | Retained but normally omitted from active context/search |
+
+## Host responsibilities
+
+- Own users, teams, permissions, routing, and product policy.
+- Implement `KnowledgeStore` and `KnowledgeArtifactStore` with app storage.
+- Own concrete extraction, embeddings, search ingestion, R2/S3 layout, and DB schema.
+- Decide which knowledge is pinned, searchable, routable, or archival.
+
+## Boundaries
+
+- No app auth, DB drivers, object storage SDKs, React, Next.js, or provider SDKs.
+- Search/chunking APIs are exposed as flat knowledge subpaths; concrete stores and providers remain app-owned.
+- Package owns semantics and contracts only.

package/dist/agent.d.mts

@@ -0,0 +1,26 @@
+import { KnowledgeScope } from "./records.mjs";
+import { KnowledgeSearchScope } from "./documents.mjs";
+import { KnowledgeSearcher } from "./search.mjs";
+import { Effect } from "effect";
+import { ToolError } from "@yolk-sdk/agent/loop";
+import { ToolRegistration } from "@yolk-sdk/agent/tools";
+
+//#region src/agent.d.ts
+type ResolveKnowledgeScope<Context> = (context: Context) => KnowledgeScope;
+type KnowledgeAgentContextOptions = {
+  readonly maxPinnedContextCharacters: number;
+};
+declare const defaultKnowledgeAgentContextOptions: KnowledgeAgentContextOptions;
+type KnowledgeSearchToolScopeResolver<Context> = KnowledgeSearchScope | ((context: Context) => Effect.Effect<KnowledgeSearchScope, ToolError>);
+type MakeKnowledgeSearchToolOptions<Context> = {
+  readonly scope: KnowledgeSearchToolScopeResolver<Context>;
+  readonly name?: string;
+  readonly description?: string;
+  readonly limit?: number;
+  readonly minScore?: number;
+  readonly contextChunks?: number;
+};
+declare const makeKnowledgeSearchTool: <Context>(searcher: KnowledgeSearcher, options: MakeKnowledgeSearchToolOptions<Context>) => ToolRegistration<Context>;
+//#endregion
+export { KnowledgeAgentContextOptions, KnowledgeSearchToolScopeResolver, MakeKnowledgeSearchToolOptions, ResolveKnowledgeScope, defaultKnowledgeAgentContextOptions, makeKnowledgeSearchTool };
+//# sourceMappingURL=agent.d.mts.map

package/dist/agent.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../src/agent.ts"],"mappings":";;;;;;;;KAUY,qBAAA,aAAkC,OAAA,EAAS,OAAA,KAAY,cAAc;AAAA,KAErE,4BAAA;EAAA,SACD,0BAA0B;AAAA;AAAA,cAGxB,mCAAA,EAAqC,4BAEjD;AAAA,KAWW,gCAAA,YACR,oBAAA,KACE,OAAA,EAAS,OAAA,KAAY,MAAA,CAAO,MAAA,CAAO,oBAAA,EAAsB,SAAA;AAAA,KAEnD,8BAAA;EAAA,SACD,KAAA,EAAO,gCAAgC,CAAC,OAAA;EAAA,SACxC,IAAA;EAAA,SACA,WAAA;EAAA,SACA,KAAA;EAAA,SACA,QAAA;EAAA,SACA,aAAA;AAAA;AAAA,cAWE,uBAAA,YACX,QAAA,EAAU,iBAAA,EACV,OAAA,EAAS,8BAAA,CAA+B,OAAA,MACvC,gBAAA,CAAiB,OAAA"}

package/dist/agent.mjs

@@ -0,0 +1,45 @@
+import { packKnowledgeSearchContext } from "./search.mjs";
+import { Effect } from "effect";
+import * as Schema$1 from "effect/Schema";
+import { ToolError } from "@yolk-sdk/agent/loop";
+import { ToolResult } from "@yolk-sdk/agent/protocol";
+import { makeTool } from "@yolk-sdk/agent/tools";
+//#region src/agent.ts
+const defaultKnowledgeAgentContextOptions = { maxPinnedContextCharacters: 6e3 };
+const KnowledgeSearchToolParams = Schema$1.Struct({ query: Schema$1.Trimmed.pipe(Schema$1.check(Schema$1.isNonEmpty()), Schema$1.annotate({ description: "Search query for the configured knowledge search." })) });
+const isToolError = Schema$1.is(ToolError);
+const resolveScope = (resolver, context) => {
+	if (typeof resolver === "function") return resolver(context);
+	return Effect.succeed(resolver);
+};
+const makeKnowledgeSearchTool = (searcher, options) => {
+	return makeTool({
+		name: options.name ?? "search_knowledge",
+		description: options.description ?? "Search the configured knowledge search.",
+		parameters: KnowledgeSearchToolParams,
+		access: "read",
+		invalidParamsMessage: (error) => error instanceof Error ? error.message : String(error),
+		execute: (input) => resolveScope(options.scope, input.context).pipe(Effect.flatMap((scope) => searcher.search({
+			scope,
+			query: input.params.query,
+			limit: options.limit,
+			minScore: options.minScore,
+			contextChunks: options.contextChunks
+		})), Effect.map((results) => packKnowledgeSearchContext(input.params.query, results)), Effect.map((context) => ToolResult.make({
+			toolCallId: input.call.id,
+			content: context.text,
+			structuredContent: context
+		})), Effect.mapError((error) => {
+			if (isToolError(error)) return error;
+			return new ToolError({
+				tool: input.call.name,
+				message: error.message,
+				cause: "execution"
+			});
+		}))
+	});
+};
+//#endregion
+export { defaultKnowledgeAgentContextOptions, makeKnowledgeSearchTool };
+
+//# sourceMappingURL=agent.mjs.map

package/dist/agent.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.mjs","names":["Schema"],"sources":["../src/agent.ts"],"sourcesContent":["import { Effect } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport { ToolError } from '@yolk-sdk/agent/loop'\nimport { ToolResult } from '@yolk-sdk/agent/protocol'\nimport { makeTool, type ToolRegistration } from '@yolk-sdk/agent/tools'\nimport type { KnowledgeScope } from './records.ts'\nimport type { KnowledgeSearchScope } from './documents.ts'\nimport type { KnowledgeSearcher } from './search.ts'\nimport { packKnowledgeSearchContext } from './search.ts'\n\nexport type ResolveKnowledgeScope<Context> = (context: Context) => KnowledgeScope\n\nexport type KnowledgeAgentContextOptions = {\n  readonly maxPinnedContextCharacters: number\n}\n\nexport const defaultKnowledgeAgentContextOptions: KnowledgeAgentContextOptions = {\n  maxPinnedContextCharacters: 6000\n}\n\nconst KnowledgeSearchToolParams = Schema.Struct({\n  query: Schema.Trimmed.pipe(\n    Schema.check(Schema.isNonEmpty()),\n    Schema.annotate({ description: 'Search query for the configured knowledge search.' })\n  )\n})\n\nconst isToolError = Schema.is(ToolError)\n\nexport type KnowledgeSearchToolScopeResolver<Context> =\n  | KnowledgeSearchScope\n  | ((context: Context) => Effect.Effect<KnowledgeSearchScope, ToolError>)\n\nexport type MakeKnowledgeSearchToolOptions<Context> = {\n  readonly scope: KnowledgeSearchToolScopeResolver<Context>\n  readonly name?: string\n  readonly description?: string\n  readonly limit?: number\n  readonly minScore?: number\n  readonly contextChunks?: number\n}\n\nconst resolveScope = <Context>(resolver: KnowledgeSearchToolScopeResolver<Context>, context: Context) => {\n  if (typeof resolver === 'function') {\n    return resolver(context)\n  }\n\n  return Effect.succeed(resolver)\n}\n\nexport const makeKnowledgeSearchTool = <Context>(\n  searcher: KnowledgeSearcher,\n  options: MakeKnowledgeSearchToolOptions<Context>\n): ToolRegistration<Context> => {\n  const name = options.name ?? 'search_knowledge'\n\n  return makeTool({\n    name,\n    description: options.description ?? 'Search the configured knowledge search.',\n    parameters: KnowledgeSearchToolParams,\n    access: 'read',\n    invalidParamsMessage: error => error instanceof Error ? error.message : String(error),\n    execute: input =>\n      resolveScope(options.scope, input.context).pipe(\n        Effect.flatMap(scope =>\n          searcher.search({\n            scope,\n            query: input.params.query,\n            limit: options.limit,\n            minScore: options.minScore,\n            contextChunks: options.contextChunks\n          })\n        ),\n        Effect.map(results => packKnowledgeSearchContext(input.params.query, results)),\n        Effect.map(\n          context =>\n            ToolResult.make({\n              toolCallId: input.call.id,\n              content: context.text,\n              structuredContent: context\n            })\n        ),\n        Effect.mapError(error => {\n          if (isToolError(error)) {\n            return error\n          }\n\n          return new ToolError({\n            tool: input.call.name,\n            message: error.message,\n            cause: 'execution'\n          })\n        })\n      )\n  })\n}\n"],"mappings":";;;;;;;AAgBA,MAAa,sCAAoE,EAC/E,4BAA4B,IAC9B;AAEA,MAAM,4BAA4BA,SAAO,OAAO,EAC9C,OAAOA,SAAO,QAAQ,KACpBA,SAAO,MAAMA,SAAO,WAAW,CAAC,GAChCA,SAAO,SAAS,EAAE,aAAa,oDAAoD,CAAC,CACtF,EACF,CAAC;AAED,MAAM,cAAcA,SAAO,GAAG,SAAS;AAevC,MAAM,gBAAyB,UAAqD,YAAqB;CACvG,IAAI,OAAO,aAAa,YACtB,OAAO,SAAS,OAAO;CAGzB,OAAO,OAAO,QAAQ,QAAQ;AAChC;AAEA,MAAa,2BACX,UACA,YAC8B;CAG9B,OAAO,SAAS;EACd,MAHW,QAAQ,QAAQ;EAI3B,aAAa,QAAQ,eAAe;EACpC,YAAY;EACZ,QAAQ;EACR,uBAAsB,UAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACpF,UAAS,UACP,aAAa,QAAQ,OAAO,MAAM,OAAO,EAAE,KACzC,OAAO,SAAQ,UACb,SAAS,OAAO;GACd;GACA,OAAO,MAAM,OAAO;GACpB,OAAO,QAAQ;GACf,UAAU,QAAQ;GAClB,eAAe,QAAQ;EACzB,CAAC,CACH,GACA,OAAO,KAAI,YAAW,2BAA2B,MAAM,OAAO,OAAO,OAAO,CAAC,GAC7E,OAAO,KACL,YACE,WAAW,KAAK;GACd,YAAY,MAAM,KAAK;GACvB,SAAS,QAAQ;GACjB,mBAAmB;EACrB,CAAC,CACL,GACA,OAAO,UAAS,UAAS;GACvB,IAAI,YAAY,KAAK,GACnB,OAAO;GAGT,OAAO,IAAI,UAAU;IACnB,MAAM,MAAM,KAAK;IACjB,SAAS,MAAM;IACf,OAAO;GACT,CAAC;EACH,CAAC,CACH;CACJ,CAAC;AACH"}

package/dist/artifacts.d.mts

@@ -0,0 +1,37 @@
+import { KnowledgeArtifactError } from "./errors.mjs";
+import { Context, Effect } from "effect";
+import * as Schema$1 from "effect/Schema";
+
+//#region src/artifacts.d.ts
+declare const KnowledgeArtifactKindSchema: Schema$1.Literals<readonly ["original", "extracted_text", "thumbnail", "transcript", "caption", "structured"]>;
+type KnowledgeArtifactKind = Schema$1.Schema.Type<typeof KnowledgeArtifactKindSchema>;
+declare const KnowledgeArtifactSchema: Schema$1.Struct<{
+  readonly id: Schema$1.Trimmed;
+  readonly recordId: Schema$1.Trimmed;
+  readonly kind: Schema$1.Literals<readonly ["original", "extracted_text", "thumbnail", "transcript", "caption", "structured"]>;
+  readonly storageKey: Schema$1.Trimmed;
+  readonly mediaType: Schema$1.optional<Schema$1.Trimmed>;
+  readonly byteSize: Schema$1.optional<Schema$1.Int>;
+  readonly checksum: Schema$1.optional<Schema$1.Trimmed>;
+  readonly metadata: Schema$1.optional<Schema$1.$Record<Schema$1.String, Schema$1.Unknown>>;
+  readonly createdAt: Schema$1.DateTimeUtc;
+}>;
+type KnowledgeArtifact = Schema$1.Schema.Type<typeof KnowledgeArtifactSchema>;
+type PutKnowledgeArtifactInput = {
+  readonly storageKey: string;
+  readonly mediaType?: string;
+  readonly bytes: Uint8Array;
+};
+type GetKnowledgeArtifactInput = {
+  readonly storageKey: string;
+};
+type KnowledgeArtifactStoreApi = {
+  readonly putArtifact: (input: PutKnowledgeArtifactInput) => Effect.Effect<void, KnowledgeArtifactError>;
+  readonly getArtifact: (input: GetKnowledgeArtifactInput) => Effect.Effect<Uint8Array, KnowledgeArtifactError>;
+  readonly deleteArtifact: (input: GetKnowledgeArtifactInput) => Effect.Effect<void, KnowledgeArtifactError>;
+};
+declare const KnowledgeArtifactStore_base: Context.ServiceClass<KnowledgeArtifactStore, "@yolk-sdk/knowledge/KnowledgeArtifactStore", KnowledgeArtifactStoreApi>;
+declare class KnowledgeArtifactStore extends KnowledgeArtifactStore_base {}
+//#endregion
+export { GetKnowledgeArtifactInput, KnowledgeArtifact, KnowledgeArtifactKind, KnowledgeArtifactKindSchema, KnowledgeArtifactSchema, KnowledgeArtifactStore, KnowledgeArtifactStoreApi, PutKnowledgeArtifactInput };
+//# sourceMappingURL=artifacts.d.mts.map

package/dist/artifacts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.mts","names":[],"sources":["../src/artifacts.ts"],"mappings":";;;;;cAMa,2BAAA,EAA2B,QAAA,CAAA,QAAA;AAAA,KAQ5B,qBAAA,GAAwB,QAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,2BAAA;AAAA,cAEjD,uBAAA,EAAuB,QAAA,CAAA,MAAA;EAAA;;;;;;;;;;KAWxB,iBAAA,GAAoB,QAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,uBAAA;AAAA,KAE9C,yBAAA;EAAA,SACD,UAAA;EAAA,SACA,SAAA;EAAA,SACA,KAAA,EAAO,UAAU;AAAA;AAAA,KAGhB,yBAAA;EAAA,SACD,UAAU;AAAA;AAAA,KAGT,yBAAA;EAAA,SACD,WAAA,GAAc,KAAA,EAAO,yBAAA,KAA8B,MAAA,CAAO,MAAA,OAAa,sBAAA;EAAA,SACvE,WAAA,GAAc,KAAA,EAAO,yBAAA,KAA8B,MAAA,CAAO,MAAA,CAAO,UAAA,EAAY,sBAAA;EAAA,SAC7E,cAAA,GAAiB,KAAA,EAAO,yBAAA,KAA8B,MAAA,CAAO,MAAA,OAAa,sBAAA;AAAA;AAAA,cACpF,2BAAA;cAEY,sBAAA,SAA+B,2BAE3C"}

package/dist/artifacts.mjs

@@ -0,0 +1,28 @@
+import { KnowledgeMetadataSchema, NonEmptyTrimmedString, NonNegativeInteger } from "./records.mjs";
+import { Context } from "effect";
+import * as Schema$1 from "effect/Schema";
+//#region src/artifacts.ts
+const KnowledgeArtifactKindSchema = Schema$1.Literals([
+	"original",
+	"extracted_text",
+	"thumbnail",
+	"transcript",
+	"caption",
+	"structured"
+]);
+const KnowledgeArtifactSchema = Schema$1.Struct({
+	id: NonEmptyTrimmedString,
+	recordId: NonEmptyTrimmedString,
+	kind: KnowledgeArtifactKindSchema,
+	storageKey: NonEmptyTrimmedString,
+	mediaType: Schema$1.optional(NonEmptyTrimmedString),
+	byteSize: Schema$1.optional(NonNegativeInteger),
+	checksum: Schema$1.optional(NonEmptyTrimmedString),
+	metadata: Schema$1.optional(KnowledgeMetadataSchema),
+	createdAt: Schema$1.DateTimeUtc
+});
+var KnowledgeArtifactStore = class extends Context.Service()("@yolk-sdk/knowledge/KnowledgeArtifactStore") {};
+//#endregion
+export { KnowledgeArtifactKindSchema, KnowledgeArtifactSchema, KnowledgeArtifactStore };
+
+//# sourceMappingURL=artifacts.mjs.map

package/dist/artifacts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.mjs","names":["Schema"],"sources":["../src/artifacts.ts"],"sourcesContent":["import { Context } from 'effect'\nimport type { Effect } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport type { KnowledgeArtifactError } from './errors.ts'\nimport { KnowledgeMetadataSchema, NonEmptyTrimmedString, NonNegativeInteger } from './records.ts'\n\nexport const KnowledgeArtifactKindSchema = Schema.Literals([\n  'original',\n  'extracted_text',\n  'thumbnail',\n  'transcript',\n  'caption',\n  'structured'\n])\nexport type KnowledgeArtifactKind = Schema.Schema.Type<typeof KnowledgeArtifactKindSchema>\n\nexport const KnowledgeArtifactSchema = Schema.Struct({\n  id: NonEmptyTrimmedString,\n  recordId: NonEmptyTrimmedString,\n  kind: KnowledgeArtifactKindSchema,\n  storageKey: NonEmptyTrimmedString,\n  mediaType: Schema.optional(NonEmptyTrimmedString),\n  byteSize: Schema.optional(NonNegativeInteger),\n  checksum: Schema.optional(NonEmptyTrimmedString),\n  metadata: Schema.optional(KnowledgeMetadataSchema),\n  createdAt: Schema.DateTimeUtc\n})\nexport type KnowledgeArtifact = Schema.Schema.Type<typeof KnowledgeArtifactSchema>\n\nexport type PutKnowledgeArtifactInput = {\n  readonly storageKey: string\n  readonly mediaType?: string\n  readonly bytes: Uint8Array\n}\n\nexport type GetKnowledgeArtifactInput = {\n  readonly storageKey: string\n}\n\nexport type KnowledgeArtifactStoreApi = {\n  readonly putArtifact: (input: PutKnowledgeArtifactInput) => Effect.Effect<void, KnowledgeArtifactError>\n  readonly getArtifact: (input: GetKnowledgeArtifactInput) => Effect.Effect<Uint8Array, KnowledgeArtifactError>\n  readonly deleteArtifact: (input: GetKnowledgeArtifactInput) => Effect.Effect<void, KnowledgeArtifactError>\n}\n\nexport class KnowledgeArtifactStore extends Context.Service<KnowledgeArtifactStore, KnowledgeArtifactStoreApi>()(\n  '@yolk-sdk/knowledge/KnowledgeArtifactStore'\n) {}\n"],"mappings":";;;;AAMA,MAAa,8BAA8BA,SAAO,SAAS;CACzD;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AAGD,MAAa,0BAA0BA,SAAO,OAAO;CACnD,IAAI;CACJ,UAAU;CACV,MAAM;CACN,YAAY;CACZ,WAAWA,SAAO,SAAS,qBAAqB;CAChD,UAAUA,SAAO,SAAS,kBAAkB;CAC5C,UAAUA,SAAO,SAAS,qBAAqB;CAC/C,UAAUA,SAAO,SAAS,uBAAuB;CACjD,WAAWA,SAAO;AACpB,CAAC;AAmBD,IAAa,yBAAb,cAA4C,QAAQ,QAA2D,EAC7G,4CACF,EAAE,CAAC"}

package/dist/chunking.d.mts

@@ -0,0 +1,38 @@
+import { KnowledgeChunk, KnowledgeMetadata } from "./documents.mjs";
+import { KnowledgeChunkingError } from "./errors.mjs";
+import { Context, Effect, Layer } from "effect";
+
+//#region src/chunking.d.ts
+type ChunkKnowledgeDocumentInput = {
+  readonly collectionId: string;
+  readonly documentId: string;
+  readonly content: string;
+  readonly maxTokens?: number;
+  readonly metadata?: KnowledgeMetadata;
+};
+type KnowledgeChunkerApi = {
+  readonly chunk: (input: ChunkKnowledgeDocumentInput) => Effect.Effect<ReadonlyArray<KnowledgeChunk>, KnowledgeChunkingError>;
+};
+declare const KnowledgeChunker_base: Context.ServiceClass<KnowledgeChunker, "@yolk-sdk/knowledge/KnowledgeChunker", KnowledgeChunkerApi>;
+declare class KnowledgeChunker extends KnowledgeChunker_base {}
+declare const countKnowledgeChunkTokens: (text: string) => number;
+declare const chunkKnowledgeText: (input: ChunkKnowledgeDocumentInput, maxTokens: number) => Effect.Effect<{
+  id: string;
+  collectionId: string;
+  documentId: string;
+  content: string;
+  position: number;
+  tokenCount: number;
+  metadata: {
+    readonly [x: string]: unknown;
+  } | undefined;
+}[], KnowledgeChunkingError, never>;
+declare const makeDefaultKnowledgeChunker: (input: {
+  readonly maxTokens: number;
+}) => KnowledgeChunkerApi;
+declare const DefaultKnowledgeChunkerLive: (input?: {
+  readonly maxTokens: number;
+}) => Layer.Layer<KnowledgeChunker, never, never>;
+//#endregion
+export { ChunkKnowledgeDocumentInput, DefaultKnowledgeChunkerLive, KnowledgeChunker, KnowledgeChunkerApi, chunkKnowledgeText, countKnowledgeChunkTokens, makeDefaultKnowledgeChunker };
+//# sourceMappingURL=chunking.d.mts.map

package/dist/chunking.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.d.mts","names":[],"sources":["../src/chunking.ts"],"mappings":";;;;;KASY,2BAAA;EAAA,SACD,YAAA;EAAA,SACA,UAAA;EAAA,SACA,OAAA;EAAA,SACA,SAAA;EAAA,SACA,QAAA,GAAW,iBAAiB;AAAA;AAAA,KAG3B,mBAAA;EAAA,SACD,KAAA,GACP,KAAA,EAAO,2BAAA,KACJ,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,cAAA,GAAiB,sBAAA;AAAA;AAAA,cACnD,qBAAA;cAEY,gBAAA,SAAyB,qBAErC;AAAA,cAEY,yBAAA,GAA6B,IAAY;AAAA,cA+GzC,kBAAA,GAAsB,KAAA,EAAO,2BAAA,EAA6B,SAAA,aAAiB,MAAA,CAAA,MAAA;;;;;;;;;;;cA+B3E,2BAAA,GAA+B,KAAA;EAAA,SAAkB,SAAA;AAAA,MAAsB,mBAElF;AAAA,cAEW,2BAAA,GAA+B,KAAA;EAAA,SAAkB,SAAA;AAAA,MAAwC,KAAA,CAAA,KAAA,CAAA,gBAAA"}

package/dist/chunking.mjs

@@ -0,0 +1,93 @@
+import { KnowledgeChunkingError } from "./errors.mjs";
+import { Context, Effect, Layer } from "effect";
+import { countTokens, decode, encode } from "gpt-tokenizer/encoding/o200k_base";
+//#region src/chunking.ts
+const SENTENCE_PATTERN = /[^.!?]+[.!?]+(?:["')\]]+)?\s*|[^.!?]+$/g;
+const PARAGRAPH_BREAK_PATTERN = /(\n{2,})/;
+const WORD_PATTERN = /\S+\s*/g;
+var KnowledgeChunker = class extends Context.Service()("@yolk-sdk/knowledge/KnowledgeChunker") {};
+const countKnowledgeChunkTokens = (text) => countTokens(text);
+const sanitizeText = (text) => text.replace(/\r\n/g, "\n").replace(/[\t ]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+const splitSentences = (text) => text.split(PARAGRAPH_BREAK_PATTERN).flatMap((part) => {
+	if (part.length === 0) return [];
+	if (/^\n{2,}$/.test(part)) return ["\n\n"];
+	return part.match(SENTENCE_PATTERN) ?? [part];
+}).filter((unit) => unit.length > 0);
+const splitEncodedTokens = (text, maxTokens) => {
+	const tokens = encode(text);
+	return Array.from({ length: Math.ceil(tokens.length / maxTokens) }, (_, index) => decode(tokens.slice(index * maxTokens, index * maxTokens + maxTokens)).trim()).filter((chunk) => chunk.length > 0);
+};
+const splitOversizedUnit = (text, maxTokens) => {
+	const words = text.match(WORD_PATTERN) ?? [];
+	const chunks = [];
+	let current = "";
+	let currentTokenCount = 0;
+	for (const word of words) {
+		const wordTokenCount = countTokens(word);
+		if (wordTokenCount > maxTokens) {
+			const currentChunk = current.trim();
+			if (currentChunk.length > 0) chunks.push(currentChunk);
+			chunks.push(...splitEncodedTokens(word, maxTokens));
+			current = "";
+			currentTokenCount = 0;
+			continue;
+		}
+		if (currentTokenCount > 0 && currentTokenCount + wordTokenCount > maxTokens) {
+			const currentChunk = current.trim();
+			if (currentChunk.length > 0) chunks.push(currentChunk);
+			current = word;
+			currentTokenCount = wordTokenCount;
+			continue;
+		}
+		current = `${current}${word}`;
+		currentTokenCount += wordTokenCount;
+	}
+	const finalChunk = current.trim();
+	if (finalChunk.length > 0) chunks.push(finalChunk);
+	return chunks;
+};
+const splitUnitsBySize = (units, maxTokens) => units.flatMap((unit) => countTokens(unit) <= maxTokens ? [unit] : splitOversizedUnit(unit, maxTokens));
+const buildChunkContents = (units, maxTokens) => {
+	const chunks = [];
+	let current = "";
+	let currentTokenCount = 0;
+	const pushCurrent = () => {
+		const content = current.trim();
+		if (content.length > 0) chunks.push(content);
+	};
+	for (const unit of units) {
+		const unitTokenCount = countTokens(unit);
+		if (currentTokenCount > 0 && currentTokenCount + unitTokenCount > maxTokens) {
+			pushCurrent();
+			current = unit;
+			currentTokenCount = unitTokenCount;
+			continue;
+		}
+		current = `${current}${unit}`;
+		currentTokenCount += unitTokenCount;
+	}
+	pushCurrent();
+	return chunks;
+};
+const chunkKnowledgeText = (input, maxTokens) => Effect.gen(function* () {
+	if (!Number.isInteger(maxTokens) || maxTokens < 1) return yield* Effect.fail(new KnowledgeChunkingError({ message: "Chunk maxTokens must be a positive integer" }));
+	const sanitized = sanitizeText(input.content);
+	if (sanitized.length === 0) return yield* Effect.fail(new KnowledgeChunkingError({ message: "Cannot chunk empty content" }));
+	const contents = buildChunkContents(splitUnitsBySize(splitSentences(sanitized), maxTokens), maxTokens);
+	if (contents.length === 0) return yield* Effect.fail(new KnowledgeChunkingError({ message: "No chunks produced" }));
+	return contents.map((content, position) => ({
+		id: `${input.documentId}:chunk:${position}`,
+		collectionId: input.collectionId,
+		documentId: input.documentId,
+		content,
+		position,
+		tokenCount: countTokens(content),
+		metadata: input.metadata
+	}));
+});
+const makeDefaultKnowledgeChunker = (input) => ({ chunk: (document) => chunkKnowledgeText(document, document.maxTokens ?? input.maxTokens) });
+const DefaultKnowledgeChunkerLive = (input = { maxTokens: 512 }) => Layer.succeed(KnowledgeChunker, makeDefaultKnowledgeChunker(input));
+//#endregion
+export { DefaultKnowledgeChunkerLive, KnowledgeChunker, chunkKnowledgeText, countKnowledgeChunkTokens, makeDefaultKnowledgeChunker };
+
+//# sourceMappingURL=chunking.mjs.map

package/dist/chunking.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.mjs","names":[],"sources":["../src/chunking.ts"],"sourcesContent":["import { Context, Effect, Layer } from 'effect'\nimport { countTokens, decode, encode } from 'gpt-tokenizer/encoding/o200k_base'\nimport type { KnowledgeChunk, KnowledgeMetadata } from './documents.ts'\nimport { KnowledgeChunkingError } from './errors.ts'\n\nconst SENTENCE_PATTERN = /[^.!?]+[.!?]+(?:[\"')\\]]+)?\\s*|[^.!?]+$/g\nconst PARAGRAPH_BREAK_PATTERN = /(\\n{2,})/\nconst WORD_PATTERN = /\\S+\\s*/g\n\nexport type ChunkKnowledgeDocumentInput = {\n  readonly collectionId: string\n  readonly documentId: string\n  readonly content: string\n  readonly maxTokens?: number\n  readonly metadata?: KnowledgeMetadata\n}\n\nexport type KnowledgeChunkerApi = {\n  readonly chunk: (\n    input: ChunkKnowledgeDocumentInput\n  ) => Effect.Effect<ReadonlyArray<KnowledgeChunk>, KnowledgeChunkingError>\n}\n\nexport class KnowledgeChunker extends Context.Service<KnowledgeChunker, KnowledgeChunkerApi>()(\n  '@yolk-sdk/knowledge/KnowledgeChunker'\n) {}\n\nexport const countKnowledgeChunkTokens = (text: string) => countTokens(text)\n\nconst sanitizeText = (text: string) =>\n  text\n    .replace(/\\r\\n/g, '\\n')\n    .replace(/[\\t ]+/g, ' ')\n    .replace(/\\n{3,}/g, '\\n\\n')\n    .trim()\n\nconst splitSentences = (text: string) =>\n  text\n    .split(PARAGRAPH_BREAK_PATTERN)\n    .flatMap(part => {\n      if (part.length === 0) {\n        return []\n      }\n\n      if (/^\\n{2,}$/.test(part)) {\n        return ['\\n\\n']\n      }\n\n      return part.match(SENTENCE_PATTERN) ?? [part]\n    })\n    .filter(unit => unit.length > 0)\n\nconst splitEncodedTokens = (text: string, maxTokens: number) => {\n  const tokens = encode(text)\n  return Array.from({ length: Math.ceil(tokens.length / maxTokens) }, (_, index) =>\n    decode(tokens.slice(index * maxTokens, index * maxTokens + maxTokens)).trim()\n  ).filter(chunk => chunk.length > 0)\n}\n\nconst splitOversizedUnit = (text: string, maxTokens: number) => {\n  const words = text.match(WORD_PATTERN) ?? []\n  const chunks: string[] = []\n  let current = ''\n  let currentTokenCount = 0\n\n  for (const word of words) {\n    const wordTokenCount = countTokens(word)\n\n    if (wordTokenCount > maxTokens) {\n      const currentChunk = current.trim()\n      if (currentChunk.length > 0) {\n        chunks.push(currentChunk)\n      }\n\n      chunks.push(...splitEncodedTokens(word, maxTokens))\n      current = ''\n      currentTokenCount = 0\n      continue\n    }\n\n    if (currentTokenCount > 0 && currentTokenCount + wordTokenCount > maxTokens) {\n      const currentChunk = current.trim()\n      if (currentChunk.length > 0) {\n        chunks.push(currentChunk)\n      }\n\n      current = word\n      currentTokenCount = wordTokenCount\n      continue\n    }\n\n    current = `${current}${word}`\n    currentTokenCount += wordTokenCount\n  }\n\n  const finalChunk = current.trim()\n  if (finalChunk.length > 0) {\n    chunks.push(finalChunk)\n  }\n\n  return chunks\n}\n\nconst splitUnitsBySize = (units: ReadonlyArray<string>, maxTokens: number) =>\n  units.flatMap(unit =>\n    countTokens(unit) <= maxTokens ? [unit] : splitOversizedUnit(unit, maxTokens)\n  )\n\nconst buildChunkContents = (units: ReadonlyArray<string>, maxTokens: number) => {\n  const chunks: string[] = []\n  let current = ''\n  let currentTokenCount = 0\n\n  const pushCurrent = () => {\n    const content = current.trim()\n    if (content.length > 0) {\n      chunks.push(content)\n    }\n  }\n\n  for (const unit of units) {\n    const unitTokenCount = countTokens(unit)\n\n    if (currentTokenCount > 0 && currentTokenCount + unitTokenCount > maxTokens) {\n      pushCurrent()\n      current = unit\n      currentTokenCount = unitTokenCount\n      continue\n    }\n\n    current = `${current}${unit}`\n    currentTokenCount += unitTokenCount\n  }\n\n  pushCurrent()\n  return chunks\n}\n\nexport const chunkKnowledgeText = (input: ChunkKnowledgeDocumentInput, maxTokens: number) =>\n  Effect.gen(function* () {\n    if (!Number.isInteger(maxTokens) || maxTokens < 1) {\n      return yield* Effect.fail(\n        new KnowledgeChunkingError({ message: 'Chunk maxTokens must be a positive integer' })\n      )\n    }\n\n    const sanitized = sanitizeText(input.content)\n    if (sanitized.length === 0) {\n      return yield* Effect.fail(new KnowledgeChunkingError({ message: 'Cannot chunk empty content' }))\n    }\n\n    const units = splitUnitsBySize(splitSentences(sanitized), maxTokens)\n    const contents = buildChunkContents(units, maxTokens)\n\n    if (contents.length === 0) {\n      return yield* Effect.fail(new KnowledgeChunkingError({ message: 'No chunks produced' }))\n    }\n\n    return contents.map((content, position) => ({\n      id: `${input.documentId}:chunk:${position}`,\n      collectionId: input.collectionId,\n      documentId: input.documentId,\n      content,\n      position,\n      tokenCount: countTokens(content),\n      metadata: input.metadata\n    })) satisfies ReadonlyArray<KnowledgeChunk>\n  })\n\nexport const makeDefaultKnowledgeChunker = (input: { readonly maxTokens: number }): KnowledgeChunkerApi => ({\n  chunk: document => chunkKnowledgeText(document, document.maxTokens ?? input.maxTokens)\n})\n\nexport const DefaultKnowledgeChunkerLive = (input: { readonly maxTokens: number } = { maxTokens: 512 }) =>\n  Layer.succeed(KnowledgeChunker, makeDefaultKnowledgeChunker(input))\n"],"mappings":"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"}

package/dist/context.d.mts

@@ -0,0 +1,16 @@
+import { KnowledgeRecord } from "./records.mjs";
+import { KnowledgeRepresentation } from "./representations.mjs";
+
+//#region src/context.d.ts
+type KnowledgeContextItem = {
+  readonly record: KnowledgeRecord;
+  readonly representation?: KnowledgeRepresentation;
+};
+type BuildKnowledgeContextInput = {
+  readonly items: ReadonlyArray<KnowledgeContextItem>;
+  readonly maxCharacters: number;
+};
+declare const buildKnowledgeContext: (input: BuildKnowledgeContextInput) => string;
+//#endregion
+export { BuildKnowledgeContextInput, KnowledgeContextItem, buildKnowledgeContext };
+//# sourceMappingURL=context.d.mts.map

package/dist/context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.mts","names":[],"sources":["../src/context.ts"],"mappings":";;;;KAIY,oBAAA;EAAA,SACD,MAAA,EAAQ,eAAA;EAAA,SACR,cAAA,GAAiB,uBAAuB;AAAA;AAAA,KAGvC,0BAAA;EAAA,SACD,KAAA,EAAO,aAAa,CAAC,oBAAA;EAAA,SACrB,aAAA;AAAA;AAAA,cAeE,qBAAA,GAAyB,KAAiC,EAA1B,0BAA0B"}

package/dist/context.mjs

@@ -0,0 +1,25 @@
+import { Array } from "effect";
+//#region src/context.ts
+const truncationMarker = "\n\n[truncated: pinned knowledge exceeded context budget]";
+const recordHeader = (record) => `## ${record.title}\nrole: ${record.role}\nstatus: ${record.status}\ncontext: ${record.contextPolicy}`;
+const itemBody = (item) => {
+	const representationText = item.representation?.summary ?? item.representation?.contentText;
+	return [
+		recordHeader(item.record),
+		item.record.summary,
+		representationText
+	].filter((section) => section !== void 0 && section.trim().length > 0).join("\n");
+};
+const buildKnowledgeContext = (input) => {
+	const sections = Array.map(input.items, itemBody).filter((section) => section.trim().length > 0);
+	const header = "# Pinned knowledge\nUse this durable user knowledge as high-priority context. Cite knowledge records when relevant.";
+	const body = sections.join("\n\n");
+	const context = body.length === 0 ? "" : `${header}\n\n${body}`;
+	if (context.length <= input.maxCharacters) return context;
+	if (input.maxCharacters <= 55) return context.slice(0, input.maxCharacters).trimEnd();
+	return `${context.slice(0, input.maxCharacters - 55).trimEnd()}${truncationMarker}`;
+};
+//#endregion
+export { buildKnowledgeContext };
+
+//# sourceMappingURL=context.mjs.map

package/dist/context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.mjs","names":["Arr"],"sources":["../src/context.ts"],"sourcesContent":["import { Array as Arr } from 'effect'\nimport type { KnowledgeRecord } from './records.ts'\nimport type { KnowledgeRepresentation } from './representations.ts'\n\nexport type KnowledgeContextItem = {\n  readonly record: KnowledgeRecord\n  readonly representation?: KnowledgeRepresentation\n}\n\nexport type BuildKnowledgeContextInput = {\n  readonly items: ReadonlyArray<KnowledgeContextItem>\n  readonly maxCharacters: number\n}\n\nconst truncationMarker = '\\n\\n[truncated: pinned knowledge exceeded context budget]'\n\nconst recordHeader = (record: KnowledgeRecord) =>\n  `## ${record.title}\\nrole: ${record.role}\\nstatus: ${record.status}\\ncontext: ${record.contextPolicy}`\n\nconst itemBody = (item: KnowledgeContextItem) => {\n  const representationText = item.representation?.summary ?? item.representation?.contentText\n  return [recordHeader(item.record), item.record.summary, representationText]\n    .filter(section => section !== undefined && section.trim().length > 0)\n    .join('\\n')\n}\n\nexport const buildKnowledgeContext = (input: BuildKnowledgeContextInput) => {\n  const sections = Arr.map(input.items, itemBody).filter(section => section.trim().length > 0)\n  const header = '# Pinned knowledge\\nUse this durable user knowledge as high-priority context. Cite knowledge records when relevant.'\n  const body = sections.join('\\n\\n')\n  const context = body.length === 0 ? '' : `${header}\\n\\n${body}`\n\n  if (context.length <= input.maxCharacters) {\n    return context\n  }\n\n  if (input.maxCharacters <= truncationMarker.length) {\n    return context.slice(0, input.maxCharacters).trimEnd()\n  }\n\n  return `${context.slice(0, input.maxCharacters - truncationMarker.length).trimEnd()}${truncationMarker}`\n}\n"],"mappings":";;AAcA,MAAM,mBAAmB;AAEzB,MAAM,gBAAgB,WACpB,MAAM,OAAO,MAAM,UAAU,OAAO,KAAK,YAAY,OAAO,OAAO,aAAa,OAAO;AAEzF,MAAM,YAAY,SAA+B;CAC/C,MAAM,qBAAqB,KAAK,gBAAgB,WAAW,KAAK,gBAAgB;CAChF,OAAO;EAAC,aAAa,KAAK,MAAM;EAAG,KAAK,OAAO;EAAS;CAAkB,EACvE,QAAO,YAAW,YAAY,KAAA,KAAa,QAAQ,KAAK,EAAE,SAAS,CAAC,EACpE,KAAK,IAAI;AACd;AAEA,MAAa,yBAAyB,UAAsC;CAC1E,MAAM,WAAWA,MAAI,IAAI,MAAM,OAAO,QAAQ,EAAE,QAAO,YAAW,QAAQ,KAAK,EAAE,SAAS,CAAC;CAC3F,MAAM,SAAS;CACf,MAAM,OAAO,SAAS,KAAK,MAAM;CACjC,MAAM,UAAU,KAAK,WAAW,IAAI,KAAK,GAAG,OAAO,MAAM;CAEzD,IAAI,QAAQ,UAAU,MAAM,eAC1B,OAAO;CAGT,IAAI,MAAM,iBAAiB,IACzB,OAAO,QAAQ,MAAM,GAAG,MAAM,aAAa,EAAE,QAAQ;CAGvD,OAAO,GAAG,QAAQ,MAAM,GAAG,MAAM,gBAAgB,EAAuB,EAAE,QAAQ,IAAI;AACxF"}

package/dist/documents.d.mts

@@ -0,0 +1,105 @@
+import { Schema } from "effect";
+
+//#region src/documents.d.ts
+declare const KnowledgeMetadataSchema: Schema.$Record<Schema.String, Schema.Unknown>;
+type KnowledgeMetadata = Schema.Schema.Type<typeof KnowledgeMetadataSchema>;
+declare const KnowledgeDocumentStatusSchema: Schema.Literals<readonly ["pending", "processing", "ready", "error"]>;
+type KnowledgeDocumentStatus = Schema.Schema.Type<typeof KnowledgeDocumentStatusSchema>;
+declare const KnowledgeSourceSchema: Schema.Union<readonly [Schema.Struct<{
+  readonly _tag: Schema.Literal<"File">;
+  readonly ref: Schema.Trimmed;
+  readonly name: Schema.optional<Schema.Trimmed>;
+  readonly mediaType: Schema.optional<Schema.Trimmed>;
+}>, Schema.Struct<{
+  readonly _tag: Schema.Literal<"Url">;
+  readonly url: Schema.Trimmed;
+}>, Schema.Struct<{
+  readonly _tag: Schema.Literal<"Text">;
+  readonly label: Schema.optional<Schema.Trimmed>;
+}>]>;
+type KnowledgeSource = Schema.Schema.Type<typeof KnowledgeSourceSchema>;
+declare const KnowledgeEmbeddingConfigSchema: Schema.Struct<{
+  readonly model: Schema.Trimmed;
+  readonly dimensions: Schema.Int;
+}>;
+type KnowledgeEmbeddingConfig = Schema.Schema.Type<typeof KnowledgeEmbeddingConfigSchema>;
+declare const KnowledgeChunkingConfigSchema: Schema.Struct<{
+  readonly strategy: Schema.Literal<"sentence-token">;
+  readonly maxTokens: Schema.Int;
+}>;
+type KnowledgeChunkingConfig = Schema.Schema.Type<typeof KnowledgeChunkingConfigSchema>;
+declare const KnowledgeCollectionSchema: Schema.Struct<{
+  readonly id: Schema.Trimmed;
+  readonly label: Schema.optional<Schema.Trimmed>;
+  readonly embeddingConfig: Schema.Struct<{
+    readonly model: Schema.Trimmed;
+    readonly dimensions: Schema.Int;
+  }>;
+  readonly chunkingConfig: Schema.Struct<{
+    readonly strategy: Schema.Literal<"sentence-token">;
+    readonly maxTokens: Schema.Int;
+  }>;
+  readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+type KnowledgeCollection = Schema.Schema.Type<typeof KnowledgeCollectionSchema>;
+declare const KnowledgeDocumentSchema: Schema.Struct<{
+  readonly id: Schema.Trimmed;
+  readonly collectionId: Schema.Trimmed;
+  readonly source: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.Literal<"File">;
+    readonly ref: Schema.Trimmed;
+    readonly name: Schema.optional<Schema.Trimmed>;
+    readonly mediaType: Schema.optional<Schema.Trimmed>;
+  }>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Url">;
+    readonly url: Schema.Trimmed;
+  }>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Text">;
+    readonly label: Schema.optional<Schema.Trimmed>;
+  }>]>;
+  readonly status: Schema.Literals<readonly ["pending", "processing", "ready", "error"]>;
+  readonly title: Schema.optional<Schema.Trimmed>;
+  readonly summary: Schema.optional<Schema.String>;
+  readonly errorMessage: Schema.optional<Schema.String>;
+  readonly contentHash: Schema.optional<Schema.Trimmed>;
+  readonly tokenCount: Schema.optional<Schema.Int>;
+  readonly chunkCount: Schema.optional<Schema.Int>;
+  readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+type KnowledgeDocument = Schema.Schema.Type<typeof KnowledgeDocumentSchema>;
+declare const KnowledgeChunkSchema: Schema.Struct<{
+  readonly id: Schema.Trimmed;
+  readonly collectionId: Schema.Trimmed;
+  readonly documentId: Schema.Trimmed;
+  readonly content: Schema.Trimmed;
+  readonly position: Schema.Int;
+  readonly tokenCount: Schema.Int;
+  readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+type KnowledgeChunk = Schema.Schema.Type<typeof KnowledgeChunkSchema>;
+declare const ExtractedKnowledgeDocumentSchema: Schema.Struct<{
+  readonly content: Schema.Trimmed;
+  readonly title: Schema.optional<Schema.Trimmed>;
+  readonly summary: Schema.optional<Schema.String>;
+  readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+type ExtractedKnowledgeDocument = Schema.Schema.Type<typeof ExtractedKnowledgeDocumentSchema>;
+declare const KnowledgeSearchScopeSchema: Schema.Union<readonly [Schema.Struct<{
+  readonly _tag: Schema.Literal<"KnowledgeCollection">;
+  readonly id: Schema.Trimmed;
+}>, Schema.Struct<{
+  readonly _tag: Schema.Literal<"KnowledgeCollections">;
+  readonly ids: Schema.$Array<Schema.Trimmed>;
+}>]>;
+type KnowledgeSearchScope = Schema.Schema.Type<typeof KnowledgeSearchScopeSchema>;
+declare const defaultKnowledgeChunkingConfig: KnowledgeChunkingConfig;
+declare const makeKnowledgeCollection: (input: {
+  readonly id: string;
+  readonly label?: string;
+  readonly embeddingConfig: KnowledgeEmbeddingConfig;
+  readonly chunkingConfig?: KnowledgeChunkingConfig;
+  readonly metadata?: KnowledgeMetadata;
+}) => KnowledgeCollection;
+//#endregion
+export { ExtractedKnowledgeDocument, ExtractedKnowledgeDocumentSchema, KnowledgeChunk, KnowledgeChunkSchema, KnowledgeChunkingConfig, KnowledgeChunkingConfigSchema, KnowledgeCollection, KnowledgeCollectionSchema, KnowledgeDocument, KnowledgeDocumentSchema, KnowledgeDocumentStatus, KnowledgeDocumentStatusSchema, KnowledgeEmbeddingConfig, KnowledgeEmbeddingConfigSchema, KnowledgeMetadata, KnowledgeMetadataSchema, KnowledgeSearchScope, KnowledgeSearchScopeSchema, KnowledgeSource, KnowledgeSourceSchema, defaultKnowledgeChunkingConfig, makeKnowledgeCollection };
+//# sourceMappingURL=documents.d.mts.map

package/dist/documents.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.mts","names":[],"sources":["../src/documents.ts"],"mappings":";;;cAMa,uBAAA,EAAuB,MAAA,CAAA,OAAA,CAAA,MAAA,CAAA,MAAA,EAAA,MAAA,CAAA,OAAA;AAAA,KACxB,iBAAA,GAAoB,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,uBAAA;AAAA,cAE7C,6BAAA,EAA6B,MAAA,CAAA,QAAA;AAAA,KAC9B,uBAAA,GAA0B,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,6BAAA;AAAA,cAEnD,qBAAA,EAAqB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;KAgBtB,eAAA,GAAkB,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,qBAAA;AAAA,cAE3C,8BAAA,EAA8B,MAAA,CAAA,MAAA;EAAA;;;KAI/B,wBAAA,GAA2B,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,8BAAA;AAAA,cAEpD,6BAAA,EAA6B,MAAA,CAAA,MAAA;EAAA;;;KAI9B,uBAAA,GAA0B,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,6BAAA;AAAA,cAEnD,yBAAA,EAAyB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;KAO1B,mBAAA,GAAsB,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,yBAAA;AAAA,cAE/C,uBAAA,EAAuB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;KAaxB,iBAAA,GAAoB,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,uBAAA;AAAA,cAE7C,oBAAA,EAAoB,MAAA,CAAA,MAAA;EAAA;;;;;;;;KASrB,cAAA,GAAiB,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,oBAAA;AAAA,cAE1C,gCAAA,EAAgC,MAAA,CAAA,MAAA;EAAA;;;;;KAMjC,0BAAA,GAA6B,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,gCAAA;AAAA,cAEtD,0BAAA,EAA0B,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;KAI3B,oBAAA,GAAuB,MAAA,CAAO,MAAA,CAAO,IAAI,QAAQ,0BAAA;AAAA,cAEhD,8BAAA,EAAgC,uBAG5C;AAAA,cAEY,uBAAA,GAA2B,KAAA;EAAA,SAC7B,EAAA;EAAA,SACA,KAAA;EAAA,SACA,eAAA,EAAiB,wBAAA;EAAA,SACjB,cAAA,GAAiB,uBAAA;EAAA,SACjB,QAAA,GAAW,iBAAA;AAAA,MAClB,mBAAA"}