Abstract Class: IngestionSessionHandle
@kortexya/reasoninglayer / IngestionSessionHandle
Abstract Class: IngestionSessionHandle
Section titled “Abstract Class: IngestionSessionHandle”Defined in: src/resources/ingestion-session.ts:199
What a handle of a queued ingestion session shares, whether the session tracks one document or a batch.
Remarks
Section titled “Remarks”Provides methods to poll for completion, check progress, and retrieve final stats. Wraps the session tracking endpoints. The handle does not hold an open connection: every method is an independent HTTP request.
The engine derives the session status from the statuses of its documents:
active while any document is pending or in progress, then failed if any
document failed, else complete.
Example
Section titled “Example”function track(handle: IngestionSessionHandle) { return handle.waitForCompletion({ pollIntervalMs: 3000 });}Extended by
Section titled “Extended by”Properties
Section titled “Properties”sessionId
Section titled “sessionId”
readonlysessionId:string
Defined in: src/resources/ingestion-session.ts:201
The session ID (UUID).
status
Section titled “status”
readonlystatus:string
Defined in: src/resources/ingestion-session.ts:204
The status at enqueue time. The engine always sends "pending".
statusUrl
Section titled “statusUrl”
readonlystatusUrl:string
Defined in: src/resources/ingestion-session.ts:207
Path of the session resource (/api/v1/ingest/sessions/<sessionId>).
Methods
Section titled “Methods”getDocumentStats()
Section titled “getDocumentStats()”getDocumentStats(
documentId,requestOptions?):Promise<DocumentStatsDto|null>
Defined in: src/resources/ingestion-session.ts:315
Get the stats of one document of the session.
Parameters
Section titled “Parameters”documentId
Section titled “documentId”string
The document’s session-tracking id (the documentId
the 202 answer, or DocumentStatsDto.documentId, names).
requestOptions?
Section titled “requestOptions?”Per-call request options.
Returns
Section titled “Returns”Promise<DocumentStatsDto | null>
The document’s stats once it completed, or null while it is
still pending or in progress (HTTP 204).
Throws
Section titled “Throws”404 if the session or the document does not
exist, the document is an RDF import (its receipt is on
IngestionSessionHandle.getSession), or it completed without recording stats.
Throws
Section titled “Throws”409 if the document failed or was
cancelled; the reason is documents[].error on IngestionSessionHandle.getSession.
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}/documents/{document_id}/stats.
The engine publishes DocumentStatsDto as the 200 body; a 204 (still
pending or in progress) reads as null.
DocumentStatsDto.alreadyIngested tells a duplicate upload from a
fresh ingestion.
Example
Section titled “Example”const stats = await session.getDocumentStats(documentId);if (stats?.alreadyIngested) console.log(`already in the library as ${stats.documentTermId}`);getProgress()
Section titled “getProgress()”getProgress(
requestOptions?):Promise<SessionProgressResponse>
Defined in: src/resources/ingestion-session.ts:263
Get live pipeline progress for all documents in the session.
Parameters
Section titled “Parameters”requestOptions?
Section titled “requestOptions?”Returns
Section titled “Returns”Promise<SessionProgressResponse>
Progress snapshots for each document being processed.
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}/progress.
Returns real-time counters, current pipeline step, and step log.
getSession()
Section titled “getSession()”getSession(
requestOptions?):Promise<IngestionSessionDetailResponse>
Defined in: src/resources/ingestion-session.ts:246
Get the current session details: status, document counts, and every document with how its ingestion ended.
Parameters
Section titled “Parameters”requestOptions?
Section titled “requestOptions?”Per-call request options.
Returns
Section titled “Returns”Promise<IngestionSessionDetailResponse>
The session, with documents[]: each document’s status, its
failure reason (error) and, once complete, its receipt.
Throws
Section titled “Throws”404 if the session does not exist.
Throws
Section titled “Throws”If the request fails.
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}. A receipt is tagged by
kind: markdown carries the document stats, rdf the RDF import counts
(an RDF document has no other stats route).
Example
Section titled “Example”const session = await handle.getSession();for (const doc of session.documents) { if (doc.receipt?.kind === 'rdf') console.log(`${doc.receipt.sortsCreated} sorts`);}getStats()
Section titled “getStats()”getStats(
requestOptions?):Promise<SessionStatsResponse>
Defined in: src/resources/ingestion-session.ts:280
Get stats for all completed documents in the session.
Parameters
Section titled “Parameters”requestOptions?
Section titled “requestOptions?”Returns
Section titled “Returns”Promise<SessionStatsResponse>
Per-document stats (term IDs, sort names, token usage, etc.).
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}/stats.
May be empty if no documents have completed yet.
waitForCompletion()
Section titled “waitForCompletion()”waitForCompletion(
options?):Promise<SessionStatsResponse>
Defined in: src/resources/ingestion-session.ts:351
Poll the session until it completes or fails, then return final stats.
Parameters
Section titled “Parameters”options?
Section titled “options?”Polling configuration (interval, timeout, progress callback, abort signal).
Returns
Section titled “Returns”Promise<SessionStatsResponse>
Final session stats once all documents are complete. These are
the markdown pipeline’s stats: an RDF document has none, so for an
ingestRdf session use IngestionSessionHandle.waitForSession,
whose documents carry the RDF receipt.
Throws
Section titled “Throws”IngestionFailedError If the session status becomes "failed".
Throws
Section titled “Throws”TimeoutError If timeoutMs is exceeded.
Throws
Section titled “Throws”ReasoningLayerError If the abort signal is triggered.
Example
Section titled “Example”const stats = await session.waitForCompletion({ pollIntervalMs: 2000, timeoutMs: 300_000, onProgress: (p) => { const doc = p.documents[0]; if (doc) console.log(`${doc.currentStepLabel} — chunk ${doc.chunksProcessed}/${doc.totalChunks}`); },});console.log(`Created ${stats.documents[0]?.termIds.length} terms`);Remarks
Section titled “Remarks”Polls getSession() to check status, and calls onProgress with live
progress data between checks. Terminal states are "complete" and "failed".
waitForSession()
Section titled “waitForSession()”waitForSession(
options?):Promise<IngestionSessionDetailResponse>
Defined in: src/resources/ingestion-session.ts:382
Poll the session until it completes or fails, then return the session with every document’s receipt.
Parameters
Section titled “Parameters”options?
Section titled “options?”Polling configuration (interval, timeout, progress callback, abort signal).
Returns
Section titled “Returns”Promise<IngestionSessionDetailResponse>
The completed session. Each document carries its receipt:
kind: 'markdown' with the document stats, or kind: 'rdf' with the
RDF import counts.
Throws
Section titled “Throws”IngestionFailedError If the session status becomes
"failed"; its session.documents[].error names each reason.
Throws
Section titled “Throws”TimeoutError If timeoutMs is exceeded.
Throws
Section titled “Throws”ReasoningLayerError If the abort signal is triggered.
Remarks
Section titled “Remarks”Polls getSession() the same way IngestionSessionHandle.waitForCompletion
does, and returns its last answer instead of fetching the markdown stats.
Use it for an ingestRdf session queued with sync: false.
Example
Section titled “Example”const handle = await client.ingestion.ingestRdf(request, { sync: false });const session = await handle.waitForSession();const receipt = session.documents[0]?.receipt;if (receipt?.kind === 'rdf') console.log(`${receipt.termsCreated} terms`);