@kortexya/reasoninglayer 0.11.0 → 0.12.1

package/dist/index.d.cts

@@ -109,7 +109,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
  * This is the single source of truth for the version constant.
  * The `scripts/release.sh` script updates this value alongside `package.json`.
  */
-declare const SDK_VERSION = "0.11.0";
+declare const SDK_VERSION = "0.12.1";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -4306,7 +4306,7 @@ interface DocumentParseStatsDto$1 {
 /** Available document parsers */
 type DocumentParser$1 = "docling" | "dotsocr" | "olmocr" | "auto";
 /** Live progress snapshot for a single document being ingested. */
-interface DocumentProgressDto {
+interface DocumentProgressDto$1 {
     /**
      * Number of chunks that failed.
      * @min 0
@@ -4449,7 +4449,7 @@ interface DocumentProgressDto {
     /** When ingestion started (ISO 8601). */
     started_at: string;
     /** Chronological log of pipeline events. */
-    step_log: StepLogEntryDto[];
+    step_log: StepLogEntryDto$1[];
     /**
      * Total input tokens consumed.
      * @min 0
@@ -4480,7 +4480,7 @@ type DocumentSource$1 = {
     url: string;
 };
 /** Stats for a single document within a session */
-interface DocumentStatsDto {
+interface DocumentStatsDto$1 {
     /**
      * Number of chunks successfully processed
      * @min 0
@@ -13409,9 +13409,9 @@ interface SendMessageResponse$1 {
     timestamp: string;
 }
 /** Response containing live progress for all documents in a session. */
-interface SessionProgressResponse {
+interface SessionProgressResponse$1 {
     /** Documents currently being processed (with live progress). */
-    documents: DocumentProgressDto[];
+    documents: DocumentProgressDto$1[];
     /**
      * Session ID.
      * @format uuid
@@ -13419,9 +13419,9 @@ interface SessionProgressResponse {
     session_id: string;
 }
 /** Response for GET /api/v1/ingest/sessions/{session_id}/stats */
-interface SessionStatsResponse {
+interface SessionStatsResponse$1 {
     /** Stats per document (only completed documents included) */
-    documents: DocumentStatsDto[];
+    documents: DocumentStatsDto$1[];
     /**
      * Session identifier
      * @format uuid
@@ -14303,7 +14303,7 @@ interface StatisticalSuccessResponse$1 {
     success: boolean;
 }
 /** A timestamped log entry from a pipeline step. */
-interface StepLogEntryDto {
+interface StepLogEntryDto$1 {
     /** Human-readable description of what happened. */
     message: string;
     /** Pipeline step that produced this event. */
@@ -24523,7 +24523,7 @@ declare class Execution<SecurityDataType = unknown> {
      * @request GET:/api/v1/execution/stats
      * @secure
      */
-    getSessionStats: (params?: RequestParams) => Promise<HttpResponse<SessionStatsResponse, void>>;
+    getSessionStats: (params?: RequestParams) => Promise<HttpResponse<SessionStatsResponse$1, void>>;
     /**
      * No description
      *
@@ -25969,7 +25969,7 @@ declare class Ingestion<SecurityDataType = unknown> {
      * @request GET:/api/v1/ingest/sessions/{session_id}/progress
      * @secure
      */
-    getIngestionProgress: (sessionId: string, params?: RequestParams) => Promise<HttpResponse<SessionProgressResponse, void>>;
+    getIngestionProgress: (sessionId: string, params?: RequestParams) => Promise<HttpResponse<SessionProgressResponse$1, void>>;
     /**
      * @description GET /api/v1/ingest/sessions/{session_id} Returns details of a specific ingestion session. # Path Parameters - `session_id`: UUID of the session # Headers - `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required) # Response - Session details including status and progress
      *
@@ -25989,7 +25989,7 @@ declare class Ingestion<SecurityDataType = unknown> {
      * @request GET:/api/v1/ingest/sessions/{session_id}/stats
      * @secure
      */
-    getIngestionSessionStats: (sessionId: string, params?: RequestParams) => Promise<HttpResponse<SessionStatsResponse, void>>;
+    getIngestionSessionStats: (sessionId: string, params?: RequestParams) => Promise<HttpResponse<SessionStatsResponse$1, void>>;
     /**
      * @description Returns current queue depth, document counts by status, circuit breaker state, and worker count.
      *
@@ -26143,6 +26143,177 @@ declare class Ingestion<SecurityDataType = unknown> {
     startIngestionSession: (data: StartIngestionSessionRequest$1, params?: RequestParams) => Promise<HttpResponse<IngestionSessionResponse$1, void>>;
 }
 
+/**
+ * Response from async ingestion (sync=false). Returned with HTTP 202.
+ *
+ * @remarks
+ * The backend returns this when `sync=false` is passed as a query parameter.
+ * Use the `sessionId` to poll for progress and stats via the session endpoints.
+ */
+interface AsyncIngestionResponse {
+    /** Document ID assigned by the backend (UUID). */
+    documentId: string;
+    /** Session ID for tracking (UUID). */
+    sessionId: string;
+    /** Initial status — always `"pending"` on creation. */
+    status: string;
+    /** URL path to check session status. */
+    statusUrl: string;
+}
+/**
+ * A chronological log entry from the ingestion pipeline.
+ */
+interface StepLogEntryDto {
+    /** Human-readable description of what happened. */
+    message: string;
+    /** Pipeline step that produced this event. */
+    step: string;
+    /** When this event occurred (ISO 8601). */
+    timestamp: string;
+}
+/**
+ * Live progress snapshot for a single document being ingested.
+ *
+ * @remarks
+ * Returned by `GET /api/v1/ingest/sessions/{session_id}/progress`.
+ * Provides real-time counters and pipeline step information.
+ */
+interface DocumentProgressDto {
+    /** Number of chunks that failed. */
+    chunksFailed: number;
+    /** Number of chunks fully processed. */
+    chunksProcessed: number;
+    /** Current chunk index (0-based). */
+    currentChunk: number;
+    /** Preview of the chunk currently being processed. */
+    currentChunkPreview?: string | null;
+    /** Current pipeline step (e.g., "chunking", "llm_extraction", "sort_reconciliation"). */
+    currentStep: string;
+    /** Human-readable label for the current step. */
+    currentStepLabel: string;
+    /** Entity types discovered during schema discovery. */
+    discoveredEntityTypes?: string[];
+    /** Relation types discovered during schema discovery. */
+    discoveredRelationTypes?: string[];
+    /** Document ID (UUID). */
+    documentId: string;
+    /** Domain summary from schema discovery. */
+    domainSummary?: string | null;
+    /** Elapsed seconds since start. */
+    elapsedSeconds: number;
+    /** New entities created. */
+    entitiesCreated: number;
+    /** Entities extracted so far. */
+    entitiesExtracted: number;
+    /** Entities filtered out by validation. */
+    entitiesFiltered: number;
+    /** Entities merged via deduplication. */
+    entitiesMerged: number;
+    /** Entities pending review. */
+    entitiesPendingReview: number;
+    /** Estimated USD cost. */
+    estimatedCostUsd?: number | null;
+    /** Extraction strategy ("llm", "local_ner", "hybrid", "schema_guided", "adaptive"). */
+    extractionStrategy: string;
+    /** Inference rules applied. */
+    inferenceRulesApplied: number;
+    /** LLM model name (if applicable). */
+    modelName?: string | null;
+    /** OSF residuations created. */
+    osfResiduationsCreated: number;
+    /** OSF residuations resumed. */
+    osfResiduationsResumed: number;
+    /** References resolved. */
+    referencesResolved: number;
+    /** Unresolved references. */
+    referencesUnresolved: number;
+    /** Relations extracted so far. */
+    relationsExtracted: number;
+    /** Relations from inference rules. */
+    relationsFromInference: number;
+    /** Relations integrated as OSF features. */
+    relationsIntegrated: number;
+    /** Reviews persisted. */
+    reviewsPersisted: number;
+    /** Sort names created or reused. */
+    sortNames?: string[];
+    /** New sorts created. */
+    sortsCreated: number;
+    /** Existing sorts reused (exact match). */
+    sortsReused: number;
+    /** Sorts reused via GLB/feature matching. */
+    sortsReusedGlb: number;
+    /** Sorts reused via semantic matching. */
+    sortsReusedSemantic: number;
+    /** When ingestion started (ISO 8601). */
+    startedAt: string;
+    /** Chronological log of pipeline events. */
+    stepLog: StepLogEntryDto[];
+    /** Total input tokens consumed. */
+    tokensInput: number;
+    /** Total output tokens consumed. */
+    tokensOutput: number;
+    /** Total number of chunks in the document. */
+    totalChunks: number;
+    /** Last progress update (ISO 8601). */
+    updatedAt: string;
+}
+/**
+ * Response containing live progress for all documents in a session.
+ */
+interface SessionProgressResponse {
+    /** Documents currently being processed (with live progress). */
+    documents: DocumentProgressDto[];
+    /** Session ID (UUID). */
+    sessionId: string;
+}
+/**
+ * Stats for a single completed document within a session.
+ */
+interface DocumentStatsDto {
+    /** Number of chunks successfully processed. */
+    chunksProcessed: number;
+    /** When ingestion completed (ISO 8601). */
+    completedAt?: string | null;
+    /** Document identifier (UUID). */
+    documentId: string;
+    /** Number of entities extracted from text. */
+    entitiesExtracted: number;
+    /** Processing time in milliseconds. */
+    processingTimeMs: number;
+    /** Number of relations extracted from text. */
+    relationsExtracted: number;
+    /** Names of sorts created/reused. */
+    sortNames: string[];
+    /** IDs of terms created/updated during ingestion. */
+    termIds: string[];
+    /** Total tokens consumed across all LLM calls. */
+    totalTokens: number;
+}
+/**
+ * Response for session-level stats (all completed documents).
+ */
+interface SessionStatsResponse {
+    /** Stats per document (only completed documents included). */
+    documents: DocumentStatsDto[];
+    /** Session identifier (UUID). */
+    sessionId: string;
+    /** Total number of documents with stats. */
+    total: number;
+}
+/**
+ * Options for polling an async ingestion session to completion.
+ */
+interface IngestionPollOptions {
+    /** Abort signal to cancel polling. */
+    signal?: AbortSignal;
+    /** Interval between polls in milliseconds. @defaultValue 2000 */
+    pollIntervalMs?: number;
+    /** Maximum time to wait before throwing a timeout error, in milliseconds. @defaultValue 300000 */
+    timeoutMs?: number;
+    /** Optional callback invoked with progress data on each poll cycle. */
+    onProgress?: (progress: SessionProgressResponse) => void;
+}
 /**
  * Ingestion session status.
  */
@@ -26740,6 +26911,7 @@ interface ResumeDocumentIngestionResponse {
     success: boolean;
 }
 
+type ingestion_AsyncIngestionResponse = AsyncIngestionResponse;
 type ingestion_CandidateMatchDto = CandidateMatchDto;
 type ingestion_ChunkFailureDto = ChunkFailureDto;
 type ingestion_CommunityStatsDto = CommunityStatsDto;
@@ -26748,7 +26920,9 @@ type ingestion_DocumentBatchResultDto = DocumentBatchResultDto;
 type ingestion_DocumentMetadataDto = DocumentMetadataDto;
 type ingestion_DocumentParseStatsDto = DocumentParseStatsDto;
 type ingestion_DocumentParser = DocumentParser;
+type ingestion_DocumentProgressDto = DocumentProgressDto;
 type ingestion_DocumentSource = DocumentSource;
+type ingestion_DocumentStatsDto = DocumentStatsDto;
 type ingestion_DocumentType = DocumentType;
 type ingestion_GroundingStatsDto = GroundingStatsDto;
 type ingestion_IncompleteDocumentDto = IncompleteDocumentDto;
@@ -26762,6 +26936,7 @@ type ingestion_IngestMarkdownResponse = IngestMarkdownResponse;
 type ingestion_IngestRdfRequest = IngestRdfRequest;
 type ingestion_IngestRdfResponse = IngestRdfResponse;
 type ingestion_IngestionConfigDto = IngestionConfigDto;
+type ingestion_IngestionPollOptions = IngestionPollOptions;
 type ingestion_IngestionSessionResponse = IngestionSessionResponse;
 type ingestion_IngestionSessionStatusDto = IngestionSessionStatusDto;
 type ingestion_IngestionStatsDto = IngestionStatsDto;
@@ -26775,12 +26950,289 @@ type ingestion_PipelineQualityStatsDto = PipelineQualityStatsDto;
 type ingestion_RdfFormatDto = RdfFormatDto;
 type ingestion_ResumeDocumentIngestionRequest = ResumeDocumentIngestionRequest;
 type ingestion_ResumeDocumentIngestionResponse = ResumeDocumentIngestionResponse;
+type ingestion_SessionProgressResponse = SessionProgressResponse;
+type ingestion_SessionStatsResponse = SessionStatsResponse;
 type ingestion_StartIngestionSessionRequest = StartIngestionSessionRequest;
+type ingestion_StepLogEntryDto = StepLogEntryDto;
 type ingestion_TokenUsageDto = TokenUsageDto;
 declare namespace ingestion {
-  export type { ingestion_CandidateMatchDto as CandidateMatchDto, ingestion_ChunkFailureDto as ChunkFailureDto, ingestion_CommunityStatsDto as CommunityStatsDto, ingestion_DocumentBatchItem as DocumentBatchItem, ingestion_DocumentBatchResultDto as DocumentBatchResultDto, ingestion_DocumentMetadataDto as DocumentMetadataDto, ingestion_DocumentParseStatsDto as DocumentParseStatsDto, ingestion_DocumentParser as DocumentParser, ingestion_DocumentSource as DocumentSource, ingestion_DocumentType as DocumentType, ingestion_GroundingStatsDto as GroundingStatsDto, ingestion_IncompleteDocumentDto as IncompleteDocumentDto, ingestion_IngestDocumentBatchRequest as IngestDocumentBatchRequest, ingestion_IngestDocumentBatchResponse as IngestDocumentBatchResponse, ingestion_IngestDocumentRequest as IngestDocumentRequest, ingestion_IngestDocumentResponse as IngestDocumentResponse, ingestion_IngestMarkdownBatchRequest as IngestMarkdownBatchRequest, ingestion_IngestMarkdownRequest as IngestMarkdownRequest, ingestion_IngestMarkdownResponse as IngestMarkdownResponse, ingestion_IngestRdfRequest as IngestRdfRequest, ingestion_IngestRdfResponse as IngestRdfResponse, ingestion_IngestionConfigDto as IngestionConfigDto, ingestion_IngestionSessionResponse as IngestionSessionResponse, ingestion_IngestionSessionStatusDto as IngestionSessionStatusDto, ingestion_IngestionStatsDto as IngestionStatsDto, ingestion_ListIncompleteDocumentsResponse as ListIncompleteDocumentsResponse, ingestion_ListIngestionSessionsResponse as ListIngestionSessionsResponse, ingestion_MarkdownDocumentDto as MarkdownDocumentDto, ingestion_OcrConfigDto as OcrConfigDto, ingestion_ParsedDocumentMetadataDto as ParsedDocumentMetadataDto, ingestion_PendingReviewDto as PendingReviewDto, ingestion_PipelineQualityStatsDto as PipelineQualityStatsDto, ingestion_RdfFormatDto as RdfFormatDto, ingestion_ResumeDocumentIngestionRequest as ResumeDocumentIngestionRequest, ingestion_ResumeDocumentIngestionResponse as ResumeDocumentIngestionResponse, ingestion_StartIngestionSessionRequest as StartIngestionSessionRequest, ingestion_TokenUsageDto as TokenUsageDto };
+  export type { ingestion_AsyncIngestionResponse as AsyncIngestionResponse, ingestion_CandidateMatchDto as CandidateMatchDto, ingestion_ChunkFailureDto as ChunkFailureDto, ingestion_CommunityStatsDto as CommunityStatsDto, ingestion_DocumentBatchItem as DocumentBatchItem, ingestion_DocumentBatchResultDto as DocumentBatchResultDto, ingestion_DocumentMetadataDto as DocumentMetadataDto, ingestion_DocumentParseStatsDto as DocumentParseStatsDto, ingestion_DocumentParser as DocumentParser, ingestion_DocumentProgressDto as DocumentProgressDto, ingestion_DocumentSource as DocumentSource, ingestion_DocumentStatsDto as DocumentStatsDto, ingestion_DocumentType as DocumentType, ingestion_GroundingStatsDto as GroundingStatsDto, ingestion_IncompleteDocumentDto as IncompleteDocumentDto, ingestion_IngestDocumentBatchRequest as IngestDocumentBatchRequest, ingestion_IngestDocumentBatchResponse as IngestDocumentBatchResponse, ingestion_IngestDocumentRequest as IngestDocumentRequest, ingestion_IngestDocumentResponse as IngestDocumentResponse, ingestion_IngestMarkdownBatchRequest as IngestMarkdownBatchRequest, ingestion_IngestMarkdownRequest as IngestMarkdownRequest, ingestion_IngestMarkdownResponse as IngestMarkdownResponse, ingestion_IngestRdfRequest as IngestRdfRequest, ingestion_IngestRdfResponse as IngestRdfResponse, ingestion_IngestionConfigDto as IngestionConfigDto, ingestion_IngestionPollOptions as IngestionPollOptions, ingestion_IngestionSessionResponse as IngestionSessionResponse, ingestion_IngestionSessionStatusDto as IngestionSessionStatusDto, ingestion_IngestionStatsDto as IngestionStatsDto, ingestion_ListIncompleteDocumentsResponse as ListIncompleteDocumentsResponse, ingestion_ListIngestionSessionsResponse as ListIngestionSessionsResponse, ingestion_MarkdownDocumentDto as MarkdownDocumentDto, ingestion_OcrConfigDto as OcrConfigDto, ingestion_ParsedDocumentMetadataDto as ParsedDocumentMetadataDto, ingestion_PendingReviewDto as PendingReviewDto, ingestion_PipelineQualityStatsDto as PipelineQualityStatsDto, ingestion_RdfFormatDto as RdfFormatDto, ingestion_ResumeDocumentIngestionRequest as ResumeDocumentIngestionRequest, ingestion_ResumeDocumentIngestionResponse as ResumeDocumentIngestionResponse, ingestion_SessionProgressResponse as SessionProgressResponse, ingestion_SessionStatsResponse as SessionStatsResponse, ingestion_StartIngestionSessionRequest as StartIngestionSessionRequest, ingestion_StepLogEntryDto as StepLogEntryDto, ingestion_TokenUsageDto as TokenUsageDto };
+}
+
+/**
+ * Base error class for all Reasoning Layer SDK errors.
+ *
+ * All errors thrown by the SDK extend this class, enabling catch-all handling:
+ * ```typescript
+ * try { ... } catch (e) {
+ *   if (e instanceof ReasoningLayerError) { ... }
+ * }
+ * ```
+ */
+declare class ReasoningLayerError extends Error {
+    name: string;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * HTTP API error (4xx/5xx response from the backend).
+ *
+ * Carries the HTTP status code, parsed response body, and response headers.
+ */
+declare class ApiError extends ReasoningLayerError {
+    name: string;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Backend error code (from response body `error` field), if present. */
+    readonly errorCode: string | undefined;
+    /** Parsed response body. */
+    readonly body: unknown;
+    /** Response headers. */
+    readonly headers: Headers;
+    constructor(message: string, status: number, body: unknown, headers: Headers, errorCode?: string);
+}
+/**
+ * Bad request error (HTTP 400).
+ *
+ * The request was malformed or contained invalid parameters.
+ */
+declare class BadRequestError extends ApiError {
+    name: string;
+    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
+}
+/**
+ * Authentication error (HTTP 401).
+ *
+ * The request lacked valid authentication credentials.
+ */
+declare class AuthenticationError extends ApiError {
+    name: string;
+    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
+}
+/**
+ * Forbidden error (HTTP 403).
+ *
+ * The authenticated user does not have permission to perform the requested action.
+ */
+declare class ForbiddenError extends ApiError {
+    name: string;
+    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
+}
+/**
+ * Not found error (HTTP 404).
+ *
+ * The requested resource does not exist.
+ */
+declare class NotFoundError extends ApiError {
+    name: string;
+    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
+}
+/**
+ * Constraint violation error (HTTP 409).
+ *
+ * A type constraint or uniqueness constraint was violated.
+ * Carries structured information about which term, feature, and constraint failed.
+ */
+declare class ConstraintViolationError extends ApiError {
+    name: string;
+    /** Term ID that violated the constraint, if available. */
+    readonly termId: string | undefined;
+    /** Feature name that violated the constraint, if available. */
+    readonly feature: string | undefined;
+    /** Constraint description, if available. */
+    readonly constraint: string | undefined;
+    constructor(message: string, body: unknown, headers: Headers, errorCode?: string, termId?: string, feature?: string, constraint?: string);
+}
+/**
+ * Rate limit error (HTTP 429).
+ *
+ * The request was rate-limited. Carries rate limit metadata from response headers.
+ */
+declare class RateLimitError extends ApiError {
+    name: string;
+    /** Seconds to wait before retrying, or null if not specified. */
+    readonly retryAfter: number | null;
+    /** Maximum requests allowed in the current window, or null if not specified. */
+    readonly limit: number | null;
+    /** Requests remaining in the current window, or null if not specified. */
+    readonly remaining: number | null;
+    constructor(message: string, body: unknown, headers: Headers, errorCode?: string, retryAfter?: number | null, limit?: number | null, remaining?: number | null);
+}
+/**
+ * Internal server error (HTTP 500+).
+ *
+ * An unexpected error occurred on the backend.
+ */
+declare class InternalServerError extends ApiError {
+    name: string;
+    constructor(message: string, status: number, body: unknown, headers: Headers, errorCode?: string);
+}
+/**
+ * Timeout error.
+ *
+ * The request exceeded the configured timeout duration.
+ */
+declare class TimeoutError extends ReasoningLayerError {
+    name: string;
+    /** The timeout duration in milliseconds that was exceeded. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Client-side validation error.
+ *
+ * Thrown before a request is sent when input fails client-side validation.
+ */
+declare class ValidationError extends ReasoningLayerError {
+    name: string;
+    /** The field that failed validation, if applicable. */
+    readonly field: string | undefined;
+    constructor(message: string, field?: string);
+}
+/**
+ * Network error.
+ *
+ * Wraps `fetch` connection failures (DNS resolution, connection refused, etc.).
+ */
+declare class NetworkError extends ReasoningLayerError {
+    name: string;
+    constructor(message: string, cause?: Error);
+}
+
+/**
+ * Error thrown when an async ingestion session fails on the backend.
+ *
+ * @remarks
+ * Detected during polling when the session status transitions to `"failed"`.
+ */
+declare class IngestionFailedError extends ReasoningLayerError {
+    name: string;
+    /** The session ID that failed. */
+    readonly sessionId: string;
+    /** The last known session state. */
+    readonly session: IngestionSessionResponse;
+    constructor(session: IngestionSessionResponse);
+}
+/**
+ * Handle for an async ingestion session, returned when `sync: false`.
+ *
+ * Provides methods to poll for completion, check progress, and retrieve
+ * final stats. Wraps the session tracking endpoints.
+ *
+ * @example
+ * ```ts
+ * const session = await client.ingestion.ingestMarkdown(request, { sync: false });
+ * console.log(session.sessionId); // UUID
+ *
+ * // Poll until done (with optional progress callback)
+ * const stats = await session.waitForCompletion({
+ *   onProgress: (p) => console.log(p.documents[0]?.currentStepLabel),
+ *   pollIntervalMs: 3000,
+ * });
+ *
+ * // Or check manually
+ * const progress = await session.getProgress();
+ * const sessionInfo = await session.getSession();
+ * ```
+ *
+ * @remarks
+ * The session handle does not hold an open connection. All methods
+ * are independent HTTP requests using the session endpoints.
+ */
+declare class IngestionSession {
+    /** The session ID (UUID). */
+    readonly sessionId: string;
+    /** The document ID (UUID). */
+    readonly documentId: string;
+    /** The initial status (always `"pending"` on creation). */
+    readonly status: string;
+    /** URL path to check session status. */
+    readonly statusUrl: string;
+    /** @internal */
+    private readonly api;
+    /** @internal */
+    constructor(api: Ingestion, response: AsyncIngestionResponse);
+    /**
+     * Get the current session details (status, document counts).
+     *
+     * @returns The session information.
+     *
+     * @remarks
+     * Maps to `GET /api/v1/ingest/sessions/{session_id}`.
+     */
+    getSession(): Promise<IngestionSessionResponse>;
+    /**
+     * Get live pipeline progress for all documents in the session.
+     *
+     * @returns Progress snapshots for each document being processed.
+     *
+     * @remarks
+     * Maps to `GET /api/v1/ingest/sessions/{session_id}/progress`.
+     * Returns real-time counters, current pipeline step, and step log.
+     */
+    getProgress(): Promise<SessionProgressResponse>;
+    /**
+     * Get stats for all completed documents in the session.
+     *
+     * @returns Per-document stats (term IDs, sort names, token usage, etc.).
+     *
+     * @remarks
+     * Maps to `GET /api/v1/ingest/sessions/{session_id}/stats`.
+     * May be empty if no documents have completed yet.
+     */
+    getStats(): Promise<SessionStatsResponse>;
+    /**
+     * Poll the session until it completes or fails, then return final stats.
+     *
+     * @param options - Polling configuration (interval, timeout, progress callback, abort signal).
+     * @returns Final session stats once all documents are complete.
+     * @throws {@link IngestionFailedError} If the session status becomes `"failed"`.
+     * @throws {@link TimeoutError} If `timeoutMs` is exceeded.
+     * @throws {@link ReasoningLayerError} If the abort signal is triggered.
+     *
+     * @example
+     * ```ts
+     * 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
+     * Polls `getSession()` to check status, and calls `onProgress` with live
+     * progress data between checks. Terminal states are `"complete"` and `"failed"`.
+     */
+    waitForCompletion(options?: IngestionPollOptions): Promise<SessionStatsResponse>;
+    /** @internal */
+    private sleep;
 }
 
+/**
+ * Options controlling synchronous vs asynchronous ingestion.
+ *
+ * @remarks
+ * When `sync` is `true` (default), the request blocks until LLM extraction
+ * completes and returns the full result. When `sync` is `false`, the backend
+ * returns immediately with HTTP 202 and an {@link IngestionSession} handle
+ * for polling progress.
+ */
+interface IngestionSyncOptions {
+    /**
+     * Whether to process synchronously.
+     *
+     * - `true` (default): blocks until complete, returns full result.
+     * - `false`: returns immediately with an {@link IngestionSession} handle.
+     *
+     * @defaultValue true
+     */
+    sync?: boolean;
+}
 /**
  * Resource client for document, markdown, and RDF ingestion.
  *
@@ -26790,6 +27242,10 @@ declare namespace ingestion {
  * tracking with resumption for incomplete documents.
  * Uses normalizers to convert between camelCase (SDK surface) and
  * snake_case (wire format) at the boundary.
+ *
+ * All ingestion methods that support the `sync` query parameter accept
+ * an optional `{ sync: false }` option to enable async mode, returning
+ * an {@link IngestionSession} handle instead of blocking for the result.
  */
 declare class IngestionClient {
     /** @internal */
@@ -26797,30 +27253,57 @@ declare class IngestionClient {
     /** @internal */
     constructor(api: Ingestion);
     /**
-     * Ingest a single document.
+     * Ingest markdown content synchronously (default).
      *
-     * @param request - Document ingestion request with source, config, and owner.
-     * @returns Ingestion result with stats, metadata, and parse info.
+     * @param request - Markdown ingestion request with content and owner.
+     * @returns Ingestion statistics and review items.
      */
-    ingestDocument(request: IngestDocumentRequest): Promise<IngestDocumentResponse>;
+    ingestMarkdown(request: IngestMarkdownRequest): Promise<IngestMarkdownResponse>;
     /**
-     * Ingest a batch of documents.
+     * Ingest markdown content synchronously.
      *
-     * @param request - Batch ingestion request with documents, config, and owner.
-     * @returns Batch results with per-document status.
+     * @param request - Markdown ingestion request with content and owner.
+     * @param options - Options with `sync: true`.
+     * @returns Ingestion statistics and review items.
      */
-    ingestDocumentBatch(request: IngestDocumentBatchRequest): Promise<IngestDocumentBatchResponse>;
+    ingestMarkdown(request: IngestMarkdownRequest, options: {
+        sync: true;
+    }): Promise<IngestMarkdownResponse>;
     /**
-     * Ingest markdown content.
+     * Ingest markdown content asynchronously.
      *
      * @param request - Markdown ingestion request with content and owner.
-     * @returns Ingestion statistics and review items.
+     * @param options - Options with `sync: false`.
+     * @returns An {@link IngestionSession} handle for polling progress and retrieving stats.
+     *
+     * @example
+     * ```ts
+     * // Fire-and-forget with polling
+     * const session = await client.ingestion.ingestMarkdown(request, { sync: false });
+     * const stats = await session.waitForCompletion({
+     *   onProgress: (p) => console.log(p.documents[0]?.currentStepLabel),
+     * });
+     *
+     * // Or check manually
+     * const progress = await session.getProgress();
+     * ```
      *
      * @remarks
-     * Uses synchronous mode (sync=true) by default. The generated endpoint
-     * returns void for the response type; we use a fallback to get the typed response.
+     * The backend returns HTTP 202 with a session ID. Use the returned
+     * {@link IngestionSession} to poll for completion, check progress,
+     * or retrieve final stats. The session supports `AbortSignal` for cancellation.
      */
-    ingestMarkdown(request: IngestMarkdownRequest): Promise<IngestMarkdownResponse>;
+    ingestMarkdown(request: IngestMarkdownRequest, options: {
+        sync: false;
+    }): Promise<IngestionSession>;
+    /**
+     * Ingest markdown content with configurable sync/async mode.
+     *
+     * @param request - Markdown ingestion request with content and owner.
+     * @param options - Options with `sync` flag.
+     * @returns Either the full result (sync) or an {@link IngestionSession} handle (async).
+     */
+    ingestMarkdown(request: IngestMarkdownRequest, options: IngestionSyncOptions): Promise<IngestMarkdownResponse | IngestionSession>;
     /**
      * Ingest a batch of markdown documents.
      *
@@ -26831,6 +27314,84 @@ declare class IngestionClient {
      * The generated endpoint returns void; we use a fallback to get the typed response.
      */
     ingestMarkdownBatch(request: IngestMarkdownBatchRequest): Promise<IngestMarkdownResponse>;
+    /**
+     * Ingest a single document synchronously (default).
+     *
+     * @param request - Document ingestion request with source, config, and owner.
+     * @returns Ingestion result with stats, metadata, and parse info.
+     */
+    ingestDocument(request: IngestDocumentRequest): Promise<IngestDocumentResponse>;
+    /**
+     * Ingest a single document synchronously.
+     *
+     * @param request - Document ingestion request with source, config, and owner.
+     * @param options - Options with `sync: true`.
+     * @returns Ingestion result with stats, metadata, and parse info.
+     */
+    ingestDocument(request: IngestDocumentRequest, options: {
+        sync: true;
+    }): Promise<IngestDocumentResponse>;
+    /**
+     * Ingest a single document asynchronously.
+     *
+     * @param request - Document ingestion request with source, config, and owner.
+     * @param options - Options with `sync: false`.
+     * @returns An {@link IngestionSession} handle for polling progress and retrieving stats.
+     *
+     * @remarks
+     * The backend returns HTTP 202 with a session ID. Use the returned
+     * {@link IngestionSession} to poll for completion.
+     */
+    ingestDocument(request: IngestDocumentRequest, options: {
+        sync: false;
+    }): Promise<IngestionSession>;
+    /**
+     * Ingest a single document with configurable sync/async mode.
+     *
+     * @param request - Document ingestion request with source, config, and owner.
+     * @param options - Options with `sync` flag.
+     * @returns Either the full result (sync) or an {@link IngestionSession} handle (async).
+     */
+    ingestDocument(request: IngestDocumentRequest, options: IngestionSyncOptions): Promise<IngestDocumentResponse | IngestionSession>;
+    /**
+     * Ingest a batch of documents synchronously (default).
+     *
+     * @param request - Batch ingestion request with documents, config, and owner.
+     * @returns Batch results with per-document status.
+     */
+    ingestDocumentBatch(request: IngestDocumentBatchRequest): Promise<IngestDocumentBatchResponse>;
+    /**
+     * Ingest a batch of documents synchronously.
+     *
+     * @param request - Batch ingestion request with documents, config, and owner.
+     * @param options - Options with `sync: true`.
+     * @returns Batch results with per-document status.
+     */
+    ingestDocumentBatch(request: IngestDocumentBatchRequest, options: {
+        sync: true;
+    }): Promise<IngestDocumentBatchResponse>;
+    /**
+     * Ingest a batch of documents asynchronously.
+     *
+     * @param request - Batch ingestion request with documents, config, and owner.
+     * @param options - Options with `sync: false`.
+     * @returns An {@link IngestionSession} handle for polling progress and retrieving stats.
+     *
+     * @remarks
+     * The backend returns HTTP 202 with a session ID. Use the returned
+     * {@link IngestionSession} to poll for completion.
+     */
+    ingestDocumentBatch(request: IngestDocumentBatchRequest, options: {
+        sync: false;
+    }): Promise<IngestionSession>;
+    /**
+     * Ingest a batch of documents with configurable sync/async mode.
+     *
+     * @param request - Batch ingestion request with documents, config, and owner.
+     * @param options - Options with `sync` flag.
+     * @returns Either the full result (sync) or an {@link IngestionSession} handle (async).
+     */
+    ingestDocumentBatch(request: IngestDocumentBatchRequest, options: IngestionSyncOptions): Promise<IngestDocumentBatchResponse | IngestionSession>;
     /**
      * Ingest RDF content (Turtle, N-Triples, RDF/XML, or JSON-LD).
      *
@@ -26864,6 +27425,28 @@ declare class IngestionClient {
      * @param sessionId - Session UUID.
      */
     deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Get live pipeline progress for all documents in a session.
+     *
+     * @param sessionId - Session UUID.
+     * @returns Progress snapshots for each document being processed.
+     *
+     * @remarks
+     * Maps to `GET /api/v1/ingest/sessions/{session_id}/progress`.
+     * Returns real-time counters, current pipeline step, and step log.
+     */
+    getSessionProgress(sessionId: string): Promise<SessionProgressResponse>;
+    /**
+     * Get stats for all completed documents in a session.
+     *
+     * @param sessionId - Session UUID.
+     * @returns Per-document stats (term IDs, sort names, token usage, etc.).
+     *
+     * @remarks
+     * Maps to `GET /api/v1/ingest/sessions/{session_id}/stats`.
+     * May be empty if no documents have completed yet.
+     */
+    getSessionStats(sessionId: string): Promise<SessionStatsResponse>;
     /**
      * List incomplete documents in a session that can be resumed.
      *
@@ -39532,147 +40115,6 @@ declare class ReasoningLayerClient {
     constructor(config: ClientConfig);
 }
 
-/**
- * Base error class for all Reasoning Layer SDK errors.
- *
- * All errors thrown by the SDK extend this class, enabling catch-all handling:
- * ```typescript
- * try { ... } catch (e) {
- *   if (e instanceof ReasoningLayerError) { ... }
- * }
- * ```
- */
-declare class ReasoningLayerError extends Error {
-    name: string;
-    constructor(message: string, options?: {
-        cause?: Error;
-    });
-}
-/**
- * HTTP API error (4xx/5xx response from the backend).
- *
- * Carries the HTTP status code, parsed response body, and response headers.
- */
-declare class ApiError extends ReasoningLayerError {
-    name: string;
-    /** HTTP status code. */
-    readonly status: number;
-    /** Backend error code (from response body `error` field), if present. */
-    readonly errorCode: string | undefined;
-    /** Parsed response body. */
-    readonly body: unknown;
-    /** Response headers. */
-    readonly headers: Headers;
-    constructor(message: string, status: number, body: unknown, headers: Headers, errorCode?: string);
-}
-/**
- * Bad request error (HTTP 400).
- *
- * The request was malformed or contained invalid parameters.
- */
-declare class BadRequestError extends ApiError {
-    name: string;
-    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
-}
-/**
- * Authentication error (HTTP 401).
- *
- * The request lacked valid authentication credentials.
- */
-declare class AuthenticationError extends ApiError {
-    name: string;
-    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
-}
-/**
- * Forbidden error (HTTP 403).
- *
- * The authenticated user does not have permission to perform the requested action.
- */
-declare class ForbiddenError extends ApiError {
-    name: string;
-    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
-}
-/**
- * Not found error (HTTP 404).
- *
- * The requested resource does not exist.
- */
-declare class NotFoundError extends ApiError {
-    name: string;
-    constructor(message: string, body: unknown, headers: Headers, errorCode?: string);
-}
-/**
- * Constraint violation error (HTTP 409).
- *
- * A type constraint or uniqueness constraint was violated.
- * Carries structured information about which term, feature, and constraint failed.
- */
-declare class ConstraintViolationError extends ApiError {
-    name: string;
-    /** Term ID that violated the constraint, if available. */
-    readonly termId: string | undefined;
-    /** Feature name that violated the constraint, if available. */
-    readonly feature: string | undefined;
-    /** Constraint description, if available. */
-    readonly constraint: string | undefined;
-    constructor(message: string, body: unknown, headers: Headers, errorCode?: string, termId?: string, feature?: string, constraint?: string);
-}
-/**
- * Rate limit error (HTTP 429).
- *
- * The request was rate-limited. Carries rate limit metadata from response headers.
- */
-declare class RateLimitError extends ApiError {
-    name: string;
-    /** Seconds to wait before retrying, or null if not specified. */
-    readonly retryAfter: number | null;
-    /** Maximum requests allowed in the current window, or null if not specified. */
-    readonly limit: number | null;
-    /** Requests remaining in the current window, or null if not specified. */
-    readonly remaining: number | null;
-    constructor(message: string, body: unknown, headers: Headers, errorCode?: string, retryAfter?: number | null, limit?: number | null, remaining?: number | null);
-}
-/**
- * Internal server error (HTTP 500+).
- *
- * An unexpected error occurred on the backend.
- */
-declare class InternalServerError extends ApiError {
-    name: string;
-    constructor(message: string, status: number, body: unknown, headers: Headers, errorCode?: string);
-}
-/**
- * Timeout error.
- *
- * The request exceeded the configured timeout duration.
- */
-declare class TimeoutError extends ReasoningLayerError {
-    name: string;
-    /** The timeout duration in milliseconds that was exceeded. */
-    readonly timeoutMs: number;
-    constructor(timeoutMs: number);
-}
-/**
- * Client-side validation error.
- *
- * Thrown before a request is sent when input fails client-side validation.
- */
-declare class ValidationError extends ReasoningLayerError {
-    name: string;
-    /** The field that failed validation, if applicable. */
-    readonly field: string | undefined;
-    constructor(message: string, field?: string);
-}
-/**
- * Network error.
- *
- * Wraps `fetch` connection failures (DNS resolution, connection refused, etc.).
- */
-declare class NetworkError extends ReasoningLayerError {
-    name: string;
-    constructor(message: string, cause?: Error);
-}
-
 /**
  * Builder namespace for complex tagged `ValueDto` values that have no plain JS equivalent.
  *
@@ -40708,4 +41150,4 @@ declare function toUntaggedFeatures(features: PlainFeatureMap): Record<string, F
  */
 declare function toTermInputDto(input: PsiTermInput | TermInputDto): TermInputDto;
 
-export { actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, type ConstrainedPlainVar, ConstraintViolationError, constraints as Constraints, control as Control, conversation as Conversation, type ConversationMessageRequest, type ConversationMessageResponse, type ConversationSummaryDto, type ConversationTurnsResponse, type CoreGroup, type CreateResearchSessionRequest, type CreateResearchSessionResponse, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type ErrorResponse$1 as ErrorResponse, execution as Execution, extract as Extract, type FeatureInputValueDto, type FeatureValueDto, ForbiddenError, type ForwardChainRequest, type ForwardChainResponse, functions as Functions, fuzzy as Fuzzy, FuzzyShape, type FuzzyShapeDto, generation as Generation, type GlbRequest, type GlbResponse, health as Health, homoiconic as Homoiconic, ilp as ILP, imageExtraction as ImageExtraction, inference as Inference, type IngestPaperRequest, type IngestPaperResponse, ingestion as Ingestion, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type ListConversationsResponse, type LubRequest, type LubResponse, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, osfql as Osfql, type OsfqlRequest, type OsfqlResponse, type OsfqlValue, oversight as Oversight, type PaginationParams, type PaperMetadataDto, type PaperSource, type PlainFeatureMap, type PlainFeatureValue, plainValues as PlainValues, preferences as Preferences, proofEngine as ProofEngine, type PsiTermDto, type PsiTermInput, query as Query, rag as RAG, RateLimitError, type RateLimitInfo, reasoning as Reasoning, type ReasoningGroup, ReasoningLayerClient, ReasoningLayerError, type RequestOptions, research as Research, type ResearchContradictionsResponse, type ResearchCycleResponse, type ResearchFindingsResponse, type ResearchGapsResponse, type ResearchReportResponse, type ResearchSessionResponse, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, type SearchPapersRequest, type SearchPapersResponse, SortBuilder, type SortDto, type SortInfoDto, sorts as Sorts, sources as Sources, spaces as Spaces, statistical as Statistical, synthetic as Synthetic, type SystemGroup, type TermDto, type TermInputArg, type TermInputDto, type TermListResponse, type TermPatternDto, type TermResponse, terms as Terms, TimeoutError, type TurnDto, type UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, type VerifyClaimRequest, type VerifyClaimResponse, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
+export { actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, type ConstrainedPlainVar, ConstraintViolationError, constraints as Constraints, control as Control, conversation as Conversation, type ConversationMessageRequest, type ConversationMessageResponse, type ConversationSummaryDto, type ConversationTurnsResponse, type CoreGroup, type CreateResearchSessionRequest, type CreateResearchSessionResponse, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type ErrorResponse$1 as ErrorResponse, execution as Execution, extract as Extract, type FeatureInputValueDto, type FeatureValueDto, ForbiddenError, type ForwardChainRequest, type ForwardChainResponse, functions as Functions, fuzzy as Fuzzy, FuzzyShape, type FuzzyShapeDto, generation as Generation, type GlbRequest, type GlbResponse, health as Health, homoiconic as Homoiconic, ilp as ILP, imageExtraction as ImageExtraction, inference as Inference, type IngestPaperRequest, type IngestPaperResponse, ingestion as Ingestion, IngestionFailedError, IngestionSession, type IngestionSyncOptions, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type ListConversationsResponse, type LubRequest, type LubResponse, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, osfql as Osfql, type OsfqlRequest, type OsfqlResponse, type OsfqlValue, oversight as Oversight, type PaginationParams, type PaperMetadataDto, type PaperSource, type PlainFeatureMap, type PlainFeatureValue, plainValues as PlainValues, preferences as Preferences, proofEngine as ProofEngine, type PsiTermDto, type PsiTermInput, query as Query, rag as RAG, RateLimitError, type RateLimitInfo, reasoning as Reasoning, type ReasoningGroup, ReasoningLayerClient, ReasoningLayerError, type RequestOptions, research as Research, type ResearchContradictionsResponse, type ResearchCycleResponse, type ResearchFindingsResponse, type ResearchGapsResponse, type ResearchReportResponse, type ResearchSessionResponse, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, type SearchPapersRequest, type SearchPapersResponse, SortBuilder, type SortDto, type SortInfoDto, sorts as Sorts, sources as Sources, spaces as Spaces, statistical as Statistical, synthetic as Synthetic, type SystemGroup, type TermDto, type TermInputArg, type TermInputDto, type TermListResponse, type TermPatternDto, type TermResponse, terms as Terms, TimeoutError, type TurnDto, type UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, type VerifyClaimRequest, type VerifyClaimResponse, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };