Interface: IKbIngestor
Defined in: internal/kb-ingestor/types.ts:35
KB write path: MD → chunks → vectors → index.
Implemented by KbIngestor; the type of IAIGatewayDeps.kbIngestor, so a host may pass its own in overrides.
Methods
ingestDocument()
ingestDocument(
__namedParameters):Promise<IIngestReport>
Defined in: internal/kb-ingestor/types.ts:60
ingestDocument -- replaces a document's chunks in the index
About
Chunk, embed, then swap the old chunks for the new ones.
Chunks the document, embeds heading path + text of every chunk, deletes the document's old chunks and stores the
new ones with the Embedder's model id. The delete comes after the embedding, so a failed embedding leaves the
index as it was. Returns the counts, the estimated tokens embedded and the duration.
Throws a 400 before any model call when the Embedder and the index do not use the same embedding model and
dimensions (error 5372774697006), and the usage adapter's refusal of the embedding (a 429 whose code is
USAGE_DENIED_ERROR_CODE, data.denyCode the app's code) before anything is written.
Who needs it
The application's document save endpoint, through AIGateway.kbIngestor; reindexBook, per document.
Pitfalls
Between the delete and the upsert the document is briefly absent from the index: a search in that window misses
it. One document is one embed call per batchSize chunks, each checked by the usage adapter.
Parameters
__namedParameters
doc
tenantId
string
userId?
string
Admin performing the save; goes into the trace of the embed calls.
Returns
Promise<IIngestReport>
moveBook()
moveBook(
__namedParameters):Promise<number>
Defined in: internal/kb-ingestor/types.ts:110
moveBook -- moves a book to another library
About
A new shelf, the same vectors (D22).
VectorStore.moveBook: changes the libraryId of the book's chunks, no embedding. Returns the number of chunks
changed; 0 for a book that is not in the index.
Who needs it
The application's book move endpoint, through AIGateway.kbIngestor.
Parameters
__namedParameters
bookId
string
libraryId
string
tenantId
string
Returns
Promise<number>
reindexBook()
reindexBook(
__namedParameters):Promise<IIngestReport[]>
Defined in: internal/kb-ingestor/types.ts:147
reindexBook -- re-ingests every document of a book
About
The embedding model changed, or the book is in doubt: build it again, document by document.
ingestDocument for every document of docs, concurrency at a time; one report per document, in the order of
docs, each also given to onProgress as it completes. A document that fails does not stop the book: its report
carries the error (logged as 5372774696808) and its old chunks stay in the index.
Throws a 400 before anything is ingested when a document is not of the book (error 5372774696616), and the usage
adapter's refusal (429) as ingestDocument does: the documents ingested before it are in the index, the rest are
not.
Who needs it
The application's reindex endpoint or job, through AIGateway.kbIngestor, after a change of the embedding model
or of the chunker settings.
Pitfalls
The caller supplies docs: the gateway does not know which documents a book holds. A book with documents missing
from docs keeps their old chunks, embedded with the old ruler, and upsertChunks refuses nothing about them.
Parameters
__namedParameters
bookId
string
docs
onProgress?
(report) => void
Called after each document, failed ones included.
tenantId
string
userId?
string
Returns
Promise<IIngestReport[]>
removeDocument()
removeDocument(
__namedParameters):Promise<number>
Defined in: internal/kb-ingestor/types.ts:86
removeDocument -- removes a document from the index
About
The document was deleted in the editor; its chunks go.
VectorStore.deleteByDoc; returns the number of chunks removed, 0 for a document that is not in the index.
Who needs it
The application's document delete endpoint, through AIGateway.kbIngestor.
Parameters
__namedParameters
docId
string
tenantId
string
Returns
Promise<number>