@yolk-sdk/knowledge 0.0.1-canary.9 → 0.1.0-canary.101

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/README.md +160 -80
  2. package/dist/agent.d.mts +119 -16
  3. package/dist/agent.d.mts.map +1 -1
  4. package/dist/agent.mjs +255 -32
  5. package/dist/agent.mjs.map +1 -1
  6. package/dist/chunking.d.mts +5 -5
  7. package/dist/chunking.d.mts.map +1 -1
  8. package/dist/chunking.mjs +1 -1
  9. package/dist/chunking.mjs.map +1 -1
  10. package/dist/context.d.mts +3 -8
  11. package/dist/context.d.mts.map +1 -1
  12. package/dist/context.mjs +16 -11
  13. package/dist/context.mjs.map +1 -1
  14. package/dist/documents.d.mts +124 -70
  15. package/dist/documents.d.mts.map +1 -1
  16. package/dist/documents.mjs +88 -59
  17. package/dist/documents.mjs.map +1 -1
  18. package/dist/errors.d.mts +3 -3
  19. package/dist/errors.d.mts.map +1 -1
  20. package/dist/errors.mjs +11 -11
  21. package/dist/errors.mjs.map +1 -1
  22. package/dist/extraction.d.mts.map +1 -1
  23. package/dist/extraction.mjs.map +1 -1
  24. package/dist/files.d.mts +22 -0
  25. package/dist/files.d.mts.map +1 -0
  26. package/dist/files.mjs +7 -0
  27. package/dist/files.mjs.map +1 -0
  28. package/dist/index.d.mts +4 -4
  29. package/dist/index.mjs +4 -4
  30. package/dist/ingestion.d.mts +12 -10
  31. package/dist/ingestion.d.mts.map +1 -1
  32. package/dist/ingestion.mjs +10 -14
  33. package/dist/ingestion.mjs.map +1 -1
  34. package/dist/search.d.mts +3 -3
  35. package/dist/search.d.mts.map +1 -1
  36. package/dist/search.mjs +7 -9
  37. package/dist/search.mjs.map +1 -1
  38. package/dist/store.d.mts +88 -22
  39. package/dist/store.d.mts.map +1 -1
  40. package/dist/store.mjs +2 -1
  41. package/dist/store.mjs.map +1 -1
  42. package/dist/summarization.d.mts.map +1 -1
  43. package/dist/summarization.mjs.map +1 -1
  44. package/package.json +10 -40
  45. package/src/agent.ts +393 -65
  46. package/src/chunking.ts +27 -8
  47. package/src/context.ts +21 -16
  48. package/src/documents.ts +140 -71
  49. package/src/errors.ts +4 -4
  50. package/src/extraction.ts +4 -3
  51. package/src/files.ts +24 -0
  52. package/src/index.ts +6 -3
  53. package/src/ingestion.ts +46 -27
  54. package/src/search.ts +90 -62
  55. package/src/store.ts +139 -25
  56. package/src/summarization.ts +4 -3
  57. package/dist/artifacts.d.mts +0 -37
  58. package/dist/artifacts.d.mts.map +0 -1
  59. package/dist/artifacts.mjs +0 -28
  60. package/dist/artifacts.mjs.map +0 -1
  61. package/dist/links.d.mts +0 -17
  62. package/dist/links.d.mts.map +0 -1
  63. package/dist/links.mjs +0 -24
  64. package/dist/links.mjs.map +0 -1
  65. package/dist/provenance.d.mts +0 -20
  66. package/dist/provenance.d.mts.map +0 -1
  67. package/dist/provenance.mjs +0 -26
  68. package/dist/provenance.mjs.map +0 -1
  69. package/dist/records.d.mts +0 -59
  70. package/dist/records.d.mts.map +0 -1
  71. package/dist/records.mjs +0 -64
  72. package/dist/records.mjs.map +0 -1
  73. package/dist/representations.d.mts +0 -36
  74. package/dist/representations.d.mts.map +0 -1
  75. package/dist/representations.mjs +0 -44
  76. package/dist/representations.mjs.map +0 -1
  77. package/dist/search-store.d.mts +0 -77
  78. package/dist/search-store.d.mts.map +0 -1
  79. package/dist/search-store.mjs +0 -7
  80. package/dist/search-store.mjs.map +0 -1
  81. package/dist/vector-store.d.mts +0 -3
  82. package/dist/vector-store.mjs +0 -2
  83. package/src/artifacts.ts +0 -48
  84. package/src/links.ts +0 -23
  85. package/src/provenance.ts +0 -25
  86. package/src/records.ts +0 -76
  87. package/src/representations.ts +0 -51
  88. package/src/search-store.ts +0 -98
  89. package/src/vector-store.ts +0 -6
package/README.md CHANGED
@@ -1,106 +1,186 @@
1
1
  # @yolk-sdk/knowledge
2
2
 
3
- Domain-free knowledge record, artifact, representation, search, provenance, link, store, and context contracts.
3
+ Domain-free knowledge document/source/file/context, ingestion, hybrid search, and lookup/manage tool helpers for agents.
4
4
 
5
5
  ## Install
6
6
 
7
7
  ```bash
8
- pnpm add @yolk-sdk/knowledge@canary @yolk-sdk/agent@canary effect
8
+ pnpm add @yolk-sdk/knowledge@canary @yolk-sdk/agent@canary effect@4.0.0
9
9
  ```
10
10
 
11
11
  Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
12
+ Use the SDK's matching Effect version (`4.0.0`) in host code.
13
+ Published package metadata requires Node.js 22+.
14
+
15
+ ## Model
16
+
17
+ ```txt
18
+ KnowledgeDocument
19
+ id
20
+ slug
21
+ title
22
+ purpose
23
+ origin
24
+ content
25
+ summary?
26
+ errorMessage?
27
+ reviewedAt?
28
+ metadata?
29
+ status: processing | ready | error
30
+ availability: pinned | searchable | archived
31
+ createdAt
32
+ updatedAt
33
+ ```
34
+
35
+ - `pinned`: host may inject into startup context and search.
36
+ - `searchable`: host may expose through search tools.
37
+ - `archived`: retained, normally omitted from prompt and search.
38
+
39
+ Optional files and chunks are modeled as `KnowledgeFile` and `KnowledgeChunk`. File records carry
40
+ metadata and host-owned blob keys; `KnowledgeFileBlobStore` stores the bytes separately. Chunks are
41
+ search-index records. Hosts own blob storage, chunk persistence, transactions, and lifecycle.
42
+
43
+ `KnowledgeSource` is a separate ingestion ADT. Build variants with `Schema.TaggedStruct` constructors
44
+ from `@yolk-sdk/knowledge/documents`:
45
+
46
+ - `KnowledgeFileSource.make({ ref, name?, mediaType? })` — host-owned `ref` plus optional name/media type
47
+ - `KnowledgeUrlSource.make({ url })` — host-owned URL string
48
+ - `KnowledgeTextSource.make({ label? })` — optional label; bytes/text arrive through `LoadedKnowledgeSource.content`
49
+
50
+ `IndexedKnowledgeDocument` is the search-index record. It carries `source`, indexing `status`, and
51
+ optional title/summary/error/hash/count metadata. It is distinct from the content-oriented
52
+ `KnowledgeDocument` managed through `KnowledgeStore`.
53
+
54
+ Status and availability are independent:
55
+
56
+ - `processing`: saved/indexing, not ready for prompt or search
57
+ - `ready`: usable when availability allows
58
+ - `error`: retained with an ingestion/indexing failure
59
+ - `pinned`: host may include in startup context and search
60
+ - `searchable`: host may expose through search
61
+ - `archived`: retained but normally omitted from prompt and search
62
+
63
+ These are contracts, not automatic policy. `buildKnowledgeContext` formats exactly the documents
64
+ you pass; `searchKnowledge` delegates candidate filtering to `SearchIndexStore`. Hosts must select
65
+ ready/pinned documents and exclude processing, error, or archived records as appropriate.
66
+
67
+ `KnowledgeScope` and `KnowledgeSearchScope` are opaque, caller-provided routing metadata. Hosts
68
+ construct and enforce them; the package does not infer identity, tenancy, or permissions from scope
69
+ ids or kinds. The **value** `KnowledgeSearchScope` is the single-id constructor
70
+ (`KnowledgeSearchScope.make({ id })`, tag `KnowledgeScope`). `KnowledgeSearchScopes.make({ ids })`
71
+ is the non-empty-ids variant. The **type** `KnowledgeSearchScope` remains the union of both.
72
+ Scope and document references use the branded `KnowledgeScopeId` and `KnowledgeDocumentId`
73
+ (non-empty trimmed strings, same wire representation). Hosts Effect-decode raw external/persisted
74
+ ids at their boundary and use `.make` for trusted constants and minted values.
12
75
 
13
76
  ## Subpaths
14
77
 
15
- | Subpath | Purpose |
16
- | --- | --- |
17
- | `@yolk-sdk/knowledge/records` | Knowledge record schemas and roles |
18
- | `@yolk-sdk/knowledge/artifacts` | Artifact catalog and blob-store contract |
19
- | `@yolk-sdk/knowledge/representations` | Agent-readable/searchable representations |
20
- | `@yolk-sdk/knowledge/chunking` | Search chunker contracts and defaults |
21
- | `@yolk-sdk/knowledge/embeddings` | Embedder contract and vector types |
22
- | `@yolk-sdk/knowledge/errors` | Shared knowledge error types |
23
- | `@yolk-sdk/knowledge/extraction` | Loaded source/extractor contract |
24
- | `@yolk-sdk/knowledge/ingestion` | Generic search ingestion pipeline |
25
- | `@yolk-sdk/knowledge/search` | Search interface, hybrid search, context packing |
26
- | `@yolk-sdk/knowledge/documents` | Collection, document, chunk, and search scope schemas |
27
- | `@yolk-sdk/knowledge/search-store` | Collection/document/chunk/search lifecycle store |
28
- | `@yolk-sdk/knowledge/vector-store` | Compatibility aliases for vector search/store types |
29
- | `@yolk-sdk/knowledge/summarization` | Optional title/summary service contract |
30
- | `@yolk-sdk/knowledge/provenance` | Source/provenance metadata |
31
- | `@yolk-sdk/knowledge/links` | Typed links between records |
32
- | `@yolk-sdk/knowledge/store` | Knowledge store lifecycle contract |
33
- | `@yolk-sdk/knowledge/context` | Context assembly helpers |
34
- | `@yolk-sdk/knowledge/agent` | Agent-facing helper contracts |
78
+ | Subpath | Purpose |
79
+ | ----------------------------------- | ---------------------------------------------------------------------- |
80
+ | `@yolk-sdk/knowledge` | Root context/store/file/error helpers |
81
+ | `@yolk-sdk/knowledge/documents` | Document, source, file, chunk, status, availability, and scope schemas |
82
+ | `@yolk-sdk/knowledge/files` | File blob-store contract |
83
+ | `@yolk-sdk/knowledge/store` | Document store and search-index store contracts |
84
+ | `@yolk-sdk/knowledge/context` | Pinned context builder |
85
+ | `@yolk-sdk/knowledge/chunking` | Text chunker contracts and defaults |
86
+ | `@yolk-sdk/knowledge/embeddings` | Embedder contract and vector types |
87
+ | `@yolk-sdk/knowledge/extraction` | Source/extractor contract |
88
+ | `@yolk-sdk/knowledge/ingestion` | Extract/chunk/embed/summarize/index pipeline |
89
+ | `@yolk-sdk/knowledge/search` | Vector/hybrid chunk search helpers |
90
+ | `@yolk-sdk/knowledge/summarization` | Optional title/summary service contract |
91
+ | `@yolk-sdk/knowledge/agent` | `knowledge_lookup` and `knowledge_manage` tool factories |
92
+ | `@yolk-sdk/knowledge/errors` | Shared error types |
35
93
 
36
94
  ## Imports
37
95
 
38
96
  ```ts
39
97
  import { buildKnowledgeContext, KnowledgeStore } from '@yolk-sdk/knowledge'
40
- import { KnowledgeRecord } from '@yolk-sdk/knowledge/records'
41
- import { KnowledgeArtifactStore } from '@yolk-sdk/knowledge/artifacts'
42
- import { makeDefaultKnowledgeChunker } from '@yolk-sdk/knowledge/chunking'
43
- import { searchKnowledge } from '@yolk-sdk/knowledge/search'
98
+ import {
99
+ KnowledgeFileSource,
100
+ KnowledgeSearchScope,
101
+ KnowledgeSearchScopes,
102
+ KnowledgeTextSource,
103
+ KnowledgeUrlSource,
104
+ type KnowledgeDocument
105
+ } from '@yolk-sdk/knowledge/documents'
106
+ import { KnowledgeFileBlobStore } from '@yolk-sdk/knowledge/files'
107
+ import { makeKnowledgeLookupTool, makeKnowledgeManageTool } from '@yolk-sdk/knowledge/agent'
44
108
  ```
45
109
 
46
- ## Migration
47
-
48
- Search APIs use canonical search naming. Removed retrieval APIs are intentionally not backward-compatible.
49
-
50
- | Removed | Use |
51
- | --- | --- |
52
- | Retrieval subpath | `@yolk-sdk/knowledge/search` |
53
- | `KnowledgeRetriever` | `KnowledgeSearcher` |
54
- | `retrieve(input)` | `search(input)` |
55
- | `KnowledgeRetrievalError` | `KnowledgeSearchError` |
56
-
57
- ## Glossary
58
-
59
- | Term | Meaning |
60
- | --- | --- |
61
- | Knowledge record | Stable logical thing an agent can know about. Domain-free; hosts decide product meaning. |
62
- | Artifact | Stored source/blob attached to knowledge, such as a file or captured output. |
63
- | Representation | Agent-readable or searchable form of knowledge, usually text plus metadata. |
64
- | Provenance | Source metadata explaining where knowledge came from and how it was produced. |
65
- | Link | Typed relationship between knowledge records. |
66
- | Context | Model-ready knowledge selected for a run. Built from host policy. |
67
- | Context policy | Host intent for use: `pinned`, `routable`, `searchable`, or `archived`. |
68
- | Search index | Searchable corpus built from source documents, chunks, embeddings, and metadata. |
69
- | Collection | Named searchable document group with shared embedding and chunking config. |
70
- | Document | Source item tracked through search ingestion: pending, processing, ready, or error. |
71
- | Source | Document origin: file ref, URL, or raw text. |
72
- | Chunk | Searchable slice of a document with position and token count. |
73
- | Embedding | Numeric vector for semantic search. Hosts provide the embedding provider. |
74
- | Chunker | Service that splits extracted text into chunks. |
75
- | Extractor | Service that loads source content into text/title/summary/metadata. |
76
- | Ingestion | Pipeline that extracts, chunks, embeds, stores chunks, and marks document status. |
77
- | Search | Query-time search over search chunks, optionally packed into context text. |
78
- | Hybrid search | Search mode that fuses vector and text search rankings. |
79
- | Search scope | Caller-provided collection or collections to search. Package does not interpret tenant semantics. |
80
- | Search index store | Persistence contract for collections, documents, chunks, status, and search. |
81
- | Vector store | Compatibility naming over search-store chunk search contracts. |
82
- | Knowledge store | Persistence contract for non-index knowledge records and context assembly. |
83
- | Artifact store | Persistence contract for artifact bytes/metadata. |
84
- | Host | App using the package; owns auth, DB, object storage, providers, permissions, and policy. |
85
-
86
- ## Context policy
87
-
88
- | Policy | Meaning |
89
- | --- | --- |
90
- | `pinned` | Host may inject into model startup context |
91
- | `routable` | Host may use for routing/dispatch decisions |
92
- | `searchable` | Host may expose through search tools |
93
- | `archived` | Retained but normally omitted from active context/search |
110
+ ## Use pinned knowledge as context
111
+
112
+ ```ts
113
+ import { buildKnowledgeContext } from '@yolk-sdk/knowledge/context'
114
+
115
+ const context = buildKnowledgeContext({
116
+ documents,
117
+ maxCharacters: 6000
118
+ })
119
+ ```
120
+
121
+ Add the resulting text to your system prompt. Your app chooses which documents are pinned.
122
+
123
+ ## Agent tools
124
+
125
+ `makeKnowledgeLookupTool` creates the read-only `knowledge_lookup` tool with `search` and `get`
126
+ operations. `makeKnowledgeManageTool` creates the write-classified `knowledge_manage` tool with
127
+ `upsert`, `set_availability`, `rename_slug`, and `delete` operations.
128
+
129
+ ```ts
130
+ import { makeKnowledgeLookupTool, makeKnowledgeManageTool } from '@yolk-sdk/knowledge/agent'
131
+
132
+ const lookupTool = makeKnowledgeLookupTool({ search: searchKnowledge, get: getKnowledge })
133
+ const manageTool = makeKnowledgeManageTool({
134
+ upsert: upsertKnowledge,
135
+ setAvailability: setKnowledgeAvailability,
136
+ renameSlug: renameKnowledgeSlug,
137
+ delete: deleteKnowledge
138
+ })
139
+ ```
140
+
141
+ The callbacks are host adapters and receive the agent tool context. Hosts own authorization,
142
+ storage, scope enforcement, and safe `ToolError` mapping.
143
+
144
+ Both tools declare an output (`KnowledgeLookupOutput`, `KnowledgeManageOutput`) and return its JSON
145
+ encoding as `structuredContent` (dates as ISO strings) next to the text, so code mode scripts get
146
+ `{ operation: 'search', results }`, `{ operation: 'get', document }`, or
147
+ `{ operation, document: { id, slug, title } }`. A handler value that does not encode fails the call
148
+ with an `execution` `ToolError`. Unknown argument keys are model-visible validation errors with a
149
+ hint naming the allowed keys, not stripped.
150
+
151
+ ## Ingestion semantics
152
+
153
+ `ingestKnowledgeDocument` upserts a `processing` index record, extracts, chunks, embeds and
154
+ summarizes concurrently, checks embedding cardinality, calls `replaceDocumentChunks`, then marks
155
+ the index record `ready`.
156
+
157
+ `DefaultKnowledgeChunkerLive` uses the bundled `gpt-tokenizer` `o200k_base` encoding for default
158
+ chunk boundaries and token counts. Hosts can provide another `KnowledgeChunker` layer when they
159
+ need model-specific tokenization.
160
+
161
+ Failures are returned as `KnowledgeIngestionError` with a `store`, `extract`, `chunk`, `embed`, or
162
+ `summarize` stage. The pipeline then best-effort calls `markDocumentError` with the error message;
163
+ failure to mark the error is suppressed so the original failure survives.
164
+
165
+ The pipeline is not a transaction and does not update `KnowledgeStore`. The host
166
+ `SearchIndexStore` adapter owns atomic chunk replacement, rollback/transaction behavior, ready/error
167
+ filtering, and any coordination with the content document store.
94
168
 
95
169
  ## Host responsibilities
96
170
 
97
- - Own users, teams, permissions, routing, and product policy.
98
- - Implement `KnowledgeStore` and `KnowledgeArtifactStore` with app storage.
99
- - Own concrete extraction, embeddings, search ingestion, R2/S3 layout, and DB schema.
100
- - Decide which knowledge is pinned, searchable, routable, or archived.
171
+ - Own users, workspaces, permissions, routing, and product policy.
172
+ - Implement `KnowledgeStore` with app storage.
173
+ - Implement `KnowledgeFileBlobStore` with R2/S3/blob storage when files are needed.
174
+ - When using ingestion, provide `KnowledgeExtractor`, `KnowledgeChunker`, `KnowledgeEmbedder`,
175
+ `KnowledgeSummarizer`, and `SearchIndexStore` layers. Summary/title values may be absent, but the
176
+ current pipeline still requires the summarizer service.
177
+ - Own concrete extraction, embeddings, search SQL/vector storage, and upload URLs.
178
+ `@yolk-sdk/extractors/knowledge` provides a `KnowledgeExtractor` for PDF, DOCX, XLSX, PPTX, and
179
+ text files (`FileKnowledgeExtractorLayer`) on top of its Node `FileExtractor`.
180
+ - Keep slug uniqueness scoped to the host boundary.
101
181
 
102
182
  ## Boundaries
103
183
 
104
184
  - No app auth, DB drivers, object storage SDKs, React, Next.js, or provider SDKs.
105
- - Search/chunking APIs are exposed as flat knowledge subpaths; concrete stores and providers remain app-owned.
106
- - Package owns semantics and contracts only.
185
+ - Package owns simple schemas, contracts, context formatting, tool factories, chunking, and search helpers.
186
+ - Host owns all IO and policy.
package/dist/agent.d.mts CHANGED
@@ -1,26 +1,129 @@
1
- import { KnowledgeScope } from "./records.mjs";
2
- import { KnowledgeSearchScope } from "./documents.mjs";
3
- import { KnowledgeSearcher } from "./search.mjs";
1
+ import { KnowledgeAvailability, KnowledgeDocument } from "./documents.mjs";
4
2
  import { Effect } from "effect";
3
+ import * as Schema from "effect/Schema";
5
4
  import { ToolError } from "@yolk-sdk/agent/loop";
6
5
  import { ToolRegistration } from "@yolk-sdk/agent/tools";
7
6
 
8
7
  //#region src/agent.d.ts
9
- type ResolveKnowledgeScope<Context> = (context: Context) => KnowledgeScope;
10
- type KnowledgeAgentContextOptions = {
11
- readonly maxPinnedContextCharacters: number;
8
+ /** Declared output of `makeKnowledgeLookupTool`; `structuredContent` is its JSON encoding
9
+ * (`Schema.toCodecJson`: document dates become ISO strings). */
10
+ declare const KnowledgeLookupOutput: Schema.Union<readonly [Schema.Struct<{
11
+ readonly operation: Schema.Literal<"search">;
12
+ readonly results: Schema.$Array<Schema.Struct<{
13
+ readonly document: Schema.Struct<{
14
+ readonly id: Schema.brand<Schema.Trimmed, "KnowledgeDocumentId">;
15
+ readonly slug: Schema.Trimmed;
16
+ readonly title: Schema.Trimmed;
17
+ readonly purpose: Schema.Trimmed;
18
+ readonly origin: Schema.Trimmed;
19
+ readonly content: Schema.Trimmed;
20
+ readonly status: Schema.Literals<readonly ["processing", "ready", "error"]>;
21
+ readonly availability: Schema.Literals<readonly ["pinned", "searchable", "archived"]>;
22
+ readonly summary: Schema.optional<Schema.String>;
23
+ readonly errorMessage: Schema.optional<Schema.String>;
24
+ readonly reviewedAt: Schema.optional<Schema.DateTimeUtc>;
25
+ readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
26
+ readonly createdAt: Schema.DateTimeUtc;
27
+ readonly updatedAt: Schema.DateTimeUtc;
28
+ }>;
29
+ readonly score: Schema.optionalKey<Schema.Number>;
30
+ readonly context: Schema.optionalKey<Schema.$Array<Schema.Struct<{
31
+ readonly content: Schema.String;
32
+ }>>>;
33
+ }>>;
34
+ }>, Schema.Struct<{
35
+ readonly operation: Schema.Literal<"get">;
36
+ readonly document: Schema.Struct<{
37
+ readonly id: Schema.brand<Schema.Trimmed, "KnowledgeDocumentId">;
38
+ readonly slug: Schema.Trimmed;
39
+ readonly title: Schema.Trimmed;
40
+ readonly purpose: Schema.Trimmed;
41
+ readonly origin: Schema.Trimmed;
42
+ readonly content: Schema.Trimmed;
43
+ readonly status: Schema.Literals<readonly ["processing", "ready", "error"]>;
44
+ readonly availability: Schema.Literals<readonly ["pinned", "searchable", "archived"]>;
45
+ readonly summary: Schema.optional<Schema.String>;
46
+ readonly errorMessage: Schema.optional<Schema.String>;
47
+ readonly reviewedAt: Schema.optional<Schema.DateTimeUtc>;
48
+ readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
49
+ readonly createdAt: Schema.DateTimeUtc;
50
+ readonly updatedAt: Schema.DateTimeUtc;
51
+ }>;
52
+ }>]>;
53
+ type KnowledgeLookupOutput = typeof KnowledgeLookupOutput.Type;
54
+ /** Declared output of `makeKnowledgeManageTool`; `structuredContent` is its JSON encoding. */
55
+ declare const KnowledgeManageOutput: Schema.Struct<{
56
+ readonly operation: Schema.Literals<readonly ["upsert", "set_availability", "rename_slug", "delete"]>;
57
+ readonly document: Schema.Struct<{
58
+ readonly id: Schema.String;
59
+ readonly slug: Schema.String;
60
+ readonly title: Schema.String;
61
+ }>;
62
+ }>;
63
+ type KnowledgeManageOutput = typeof KnowledgeManageOutput.Type;
64
+ type KnowledgeTarget = {
65
+ readonly slug: string;
66
+ readonly scope?: string;
12
67
  };
13
- declare const defaultKnowledgeAgentContextOptions: KnowledgeAgentContextOptions;
14
- type KnowledgeSearchToolScopeResolver<Context> = KnowledgeSearchScope | ((context: Context) => Effect.Effect<KnowledgeSearchScope, ToolError>);
15
- type MakeKnowledgeSearchToolOptions<Context> = {
16
- readonly scope: KnowledgeSearchToolScopeResolver<Context>;
68
+ type KnowledgeLookupResult = {
69
+ readonly document: KnowledgeDocument;
70
+ readonly score?: number;
71
+ readonly context?: ReadonlyArray<{
72
+ readonly content: string;
73
+ }>;
74
+ };
75
+ type KnowledgeSavedDocument = {
76
+ readonly id: string;
77
+ readonly slug: string;
78
+ readonly title: string;
79
+ };
80
+ type KnowledgeLookupHandlers<Context> = {
81
+ readonly search: (input: {
82
+ readonly context: Context;
83
+ readonly query: string;
84
+ readonly limit?: number;
85
+ readonly minScore?: number;
86
+ readonly contextChunks?: number;
87
+ }) => Effect.Effect<ReadonlyArray<KnowledgeLookupResult>, ToolError>;
88
+ readonly get: (input: {
89
+ readonly context: Context;
90
+ readonly id?: string;
91
+ readonly target?: KnowledgeTarget;
92
+ }) => Effect.Effect<KnowledgeDocument, ToolError>;
93
+ };
94
+ type KnowledgeManageHandlers<Context> = {
95
+ readonly upsert: (input: {
96
+ readonly context: Context;
97
+ readonly target: KnowledgeTarget;
98
+ readonly title: string;
99
+ readonly purpose: string;
100
+ readonly origin: string;
101
+ readonly content: string;
102
+ readonly availability: KnowledgeAvailability;
103
+ }) => Effect.Effect<KnowledgeSavedDocument, ToolError>;
104
+ readonly setAvailability: (input: {
105
+ readonly context: Context;
106
+ readonly target: KnowledgeTarget;
107
+ readonly availability: KnowledgeAvailability;
108
+ }) => Effect.Effect<KnowledgeSavedDocument, ToolError>;
109
+ readonly renameSlug: (input: {
110
+ readonly context: Context;
111
+ readonly target: KnowledgeTarget;
112
+ readonly nextSlug: string;
113
+ }) => Effect.Effect<KnowledgeSavedDocument, ToolError>;
114
+ readonly delete: (input: {
115
+ readonly context: Context;
116
+ readonly target: KnowledgeTarget;
117
+ }) => Effect.Effect<KnowledgeSavedDocument, ToolError>;
118
+ };
119
+ declare const makeKnowledgeLookupTool: <Context>(handlers: KnowledgeLookupHandlers<Context>, options?: {
17
120
  readonly name?: string;
18
121
  readonly description?: string;
19
- readonly limit?: number;
20
- readonly minScore?: number;
21
- readonly contextChunks?: number;
22
- };
23
- declare const makeKnowledgeSearchTool: <Context>(searcher: KnowledgeSearcher, options: MakeKnowledgeSearchToolOptions<Context>) => ToolRegistration<Context>;
122
+ }) => ToolRegistration<Context>;
123
+ declare const makeKnowledgeManageTool: <Context>(handlers: KnowledgeManageHandlers<Context>, options?: {
124
+ readonly name?: string;
125
+ readonly description?: string;
126
+ }) => ToolRegistration<Context>;
24
127
  //#endregion
25
- export { KnowledgeAgentContextOptions, KnowledgeSearchToolScopeResolver, MakeKnowledgeSearchToolOptions, ResolveKnowledgeScope, defaultKnowledgeAgentContextOptions, makeKnowledgeSearchTool };
128
+ export { KnowledgeLookupHandlers, KnowledgeLookupOutput, KnowledgeLookupResult, KnowledgeManageHandlers, KnowledgeManageOutput, KnowledgeSavedDocument, KnowledgeTarget, makeKnowledgeLookupTool, makeKnowledgeManageTool };
26
129
  //# sourceMappingURL=agent.d.mts.map
@@ -1 +1 @@
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"}
1
+ {"version":3,"file":"agent.d.mts","names":[],"sources":["../src/agent.ts"],"mappings":";;;;;;;;;cA6Ea,qBAAA,EAAqB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAWtB,qBAAA,UAA+B,qBAAA,CAAsB,IAAI;;cAGxD,qBAAA,EAAqB,MAAA,CAAA,MAAA;EAAA;;;;;;;KAKtB,qBAAA,UAA+B,qBAAA,CAAsB,IAAI;AAAA,KAqBzD,eAAA;EAAA,SACD,IAAA;EAAA,SACA,KAAK;AAAA;AAAA,KAGJ,qBAAA;EAAA,SACD,QAAA,EAAU,iBAAA;EAAA,SACV,KAAA;EAAA,SACA,OAAA,GAAU,aAAa;IAAA,SAAY,OAAA;EAAA;AAAA;AAAA,KAGlC,sBAAA;EAAA,SACD,EAAA;EAAA,SACA,IAAA;EAAA,SACA,KAAA;AAAA;AAAA,KAGC,uBAAA;EAAA,SACD,MAAA,GAAS,KAAA;IAAA,SACP,OAAA,EAAS,OAAA;IAAA,SACT,KAAA;IAAA,SACA,KAAA;IAAA,SACA,QAAA;IAAA,SACA,aAAA;EAAA,MACL,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,qBAAA,GAAwB,SAAA;EAAA,SACjD,GAAA,GAAM,KAAA;IAAA,SACJ,OAAA,EAAS,OAAA;IAAA,SACT,EAAA;IAAA,SACA,MAAA,GAAS,eAAA;EAAA,MACd,MAAA,CAAO,MAAA,CAAO,iBAAA,EAAmB,SAAA;AAAA;AAAA,KAG7B,uBAAA;EAAA,SACD,MAAA,GAAS,KAAA;IAAA,SACP,OAAA,EAAS,OAAA;IAAA,SACT,MAAA,EAAQ,eAAA;IAAA,SACR,KAAA;IAAA,SACA,OAAA;IAAA,SACA,MAAA;IAAA,SACA,OAAA;IAAA,SACA,YAAA,EAAc,qBAAA;EAAA,MACnB,MAAA,CAAO,MAAA,CAAO,sBAAA,EAAwB,SAAA;EAAA,SACnC,eAAA,GAAkB,KAAA;IAAA,SAChB,OAAA,EAAS,OAAA;IAAA,SACT,MAAA,EAAQ,eAAA;IAAA,SACR,YAAA,EAAc,qBAAA;EAAA,MACnB,MAAA,CAAO,MAAA,CAAO,sBAAA,EAAwB,SAAA;EAAA,SACnC,UAAA,GAAa,KAAA;IAAA,SACX,OAAA,EAAS,OAAA;IAAA,SACT,MAAA,EAAQ,eAAA;IAAA,SACR,QAAA;EAAA,MACL,MAAA,CAAO,MAAA,CAAO,sBAAA,EAAwB,SAAA;EAAA,SACnC,MAAA,GAAS,KAAA;IAAA,SACP,OAAA,EAAS,OAAA;IAAA,SACT,MAAA,EAAQ,eAAA;EAAA,MACb,MAAA,CAAO,MAAA,CAAO,sBAAA,EAAwB,SAAA;AAAA;AAAA,cA2FjC,uBAAA,YACX,QAAA,EAAU,uBAAA,CAAwB,OAAA,GAClC,OAAA;EAAA,SAAoB,IAAA;EAAA,SAAwB,WAAA;AAAA,MAC3C,gBAAA,CAAiB,OAAA;AAAA,cA0DP,uBAAA,YACX,QAAA,EAAU,uBAAA,CAAwB,OAAA,GAClC,OAAA;EAAA,SAAoB,IAAA;EAAA,SAAwB,WAAA;AAAA,MAC3C,gBAAA,CAAiB,OAAA"}