@kortexya/reasoninglayer 1.14.0 → 1.15.0

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 = "1.14.0";
+declare const SDK_VERSION = "1.15.0";
 /**
  * Authentication mode for the SDK.
  *
@@ -144,7 +144,7 @@ type AuthConfig = {
  * @example Bearer token (server-side)
  * ```typescript
  * const config: ClientConfig = {
- *   baseUrl: 'http://localhost:8083',
+ *   baseUrl: 'http://localhost:8085',
  *   tenantId: '550e8400-e29b-41d4-a716-446655440000',
  *   auth: { mode: 'bearer', token: process.env.RL_API_TOKEN! },
  * };
@@ -160,7 +160,7 @@ type AuthConfig = {
  * ```
  */
 interface ClientConfig {
-    /** Base URL of the Reasoning Layer API (e.g., `"http://localhost:8083"`). */
+    /** Base URL of the Reasoning Layer API (e.g., `"http://localhost:8085"`). */
     baseUrl: string;
     /** Tenant UUID. Set once, NOT overridable per-call. */
     tenantId: string;
@@ -6632,6 +6632,8 @@ interface DocumentBatchResultDto$1 {
     error?: string | null;
     /** Ingestion statistics (if successful) */
     ingestion_stats?: null | IngestionStatsDto$1;
+    /** Markdown generated by the document parser (if successful). */
+    markdown?: string | null;
     /** Document metadata (if successful) */
     metadata?: null | ParsedDocumentMetadataDto$1;
     /** Parse statistics (if successful) */
@@ -11666,6 +11668,13 @@ interface IngestDocumentRequest$1 {
      * @format uuid
      */
     owner_id: string;
+    /**
+     * Parse and return Markdown without creating semantic Ψ-terms.
+     *
+     * This lets a client persist parser output on its own authoritative term
+     * instead of creating a detached duplicate document representation.
+     */
+    parse_only?: boolean;
 }
 /** Response from document ingestion */
 interface IngestDocumentResponse$1 {
@@ -11673,6 +11682,14 @@ interface IngestDocumentResponse$1 {
     error?: string | null;
     /** Markdown ingestion statistics (from the markdown pipeline) */
     ingestion_stats: IngestionStatsDto$1;
+    /**
+     * Markdown generated by the document parser.
+     *
+     * Present whenever parsing succeeds, including OCR output for scanned
+     * documents. Returning this keeps the parser output usable by clients
+     * without requiring them to create a second, detached representation.
+     */
+    markdown?: string | null;
     /** Document metadata */
     metadata: ParsedDocumentMetadataDto$1;
     /** Document parsing statistics */
@@ -13568,6 +13585,11 @@ interface ListScenariosResponse$1 {
      */
     total: number;
 }
+/** Response listing the registrable source types of this build (#71). */
+interface ListSourceTypesResponse$1 {
+    /** Every source type the registration factory knows how to build. */
+    types: SourceTypeDto$1[];
+}
 /** Response listing registered sources. */
 interface ListSourcesResponse$1 {
     /** List of registered source summaries */
@@ -18118,9 +18140,15 @@ interface RegisterSourceRequest$1 {
      *   source is honored as a column→feature PROJECTION, so ingested facts land
      *   on the sort's DECLARED feature names.
      *
-     * Omitted ⇒ capability-grounded default: `transpile` for `postgres`
-     * (`postgresql`), `ingest` for every other source type (postgres is the only
-     * adapter whose transpiled SQL the engine can execute).
+     * Omitted ⇒ `ingest`, for every source type (#71). It is the only mode that
+     * populates the knowledge base and the one path every adapter can serve;
+     * `transpile` is an explicit opt-in.
+     *
+     * `transpile` is accepted only for a source whose adapter can execute
+     * transpiled SQL (Postgres, MySQL, SQLite). Requesting it for any other
+     * source is refused with **422**: there would be nothing to run the SQL an
+     * OSFQL MATCH compiles to, and ingest on such a source is refused as a
+     * category error — leaving it with no working write path at all.
      *
      * Any other string is rejected with **422** (not 400): serde fails the
      * variant at deserialization, so axum's JSON extractor refuses the body
@@ -18158,6 +18186,14 @@ interface RegisterSourceResponse$1 {
     source_type: string;
     /** Whether registration was successful */
     success: boolean;
+    /**
+     * The write-path modes this source's ADAPTER can serve (#71) — the same
+     * set `GET /api/v1/sources/{id}` reports. Echoed at registration so a
+     * client learns, at the moment the choice is made, whether `transpile`
+     * was even on the table (a mode change requires DELETE + re-register).
+     * @example ["ingest","transpile"]
+     */
+    supported_modes: string[];
 }
 type RegressionBasisDto = "linear" | "cubic_polynomial";
 /** Request to reject an action */
@@ -21105,6 +21141,20 @@ interface SourceDetailResponse$1 {
     source_id: string;
     /** Source type */
     source_type: string;
+    /**
+     * The write-path modes this source's ADAPTER can actually serve (#71).
+     *
+     * Always contains `"ingest"` — every adapter can materialize. Contains
+     * `"transpile"` only when the adapter executes transpiled SQL, which is what
+     * a live view requires; registering the other modes is refused with a 422.
+     *
+     * A client rendering a mode selector should offer exactly these, rather than
+     * hard-coding a list of source types: the set is derived from the adapter's
+     * declared capability, so it stays correct as adapters gain the ability
+     * (MySQL and SQLite did in #70).
+     * @example ["ingest","transpile"]
+     */
+    supported_modes: string[];
 }
 /** Source excerpt DTO */
 interface SourceExcerptDto$2 {
@@ -21123,6 +21173,37 @@ interface SourceSummaryDto$1 {
     /** Source type */
     source_type: string;
 }
+/**
+ * One registrable source TYPE and its capabilities (#71).
+ *
+ * The pre-registration half of the mode-discovery surface: a client rendering
+ * a "new source" picker asks `GET /api/v1/sources/types` which types this
+ * build can register and which write-path modes each would serve — BEFORE any
+ * source exists. The per-source half (`GET /api/v1/sources/{id}`) answers the
+ * same mode question for a source that does.
+ */
+interface SourceTypeDto$1 {
+    /** Alternate spellings registration also accepts (e.g. `postgresql`). */
+    aliases: string[];
+    /**
+     * Whether this build can register the type. `false` means the adapter is
+     * behind a cargo feature that is not compiled in: registration would be
+     * refused, so a picker should not offer it (or should show it disabled).
+     */
+    available: boolean;
+    /**
+     * Canonical type string accepted by `POST /api/v1/sources`.
+     * @example "mysql"
+     */
+    source_type: string;
+    /**
+     * The write-path modes this type's adapter can serve: always `"ingest"`,
+     * plus `"transpile"` when the adapter executes transpiled SQL. The same
+     * set the per-source endpoints report after registration.
+     * @example ["ingest","transpile"]
+     */
+    supported_modes: string[];
+}
 /**
  * A constraint in the space
  *
@@ -26152,7 +26233,18 @@ declare class Terms<SecurityDataType = unknown> {
      * @request GET:/api/v1/terms
      * @secure
      */
-    listTerms: (params?: RequestParams) => Promise<HttpResponse<TermListResponse$1, any>>;
+    listTerms: (query?: {
+        /**
+         * Max terms to return; omit for all, hard-capped at 10000
+         * @min 0
+         */
+        limit?: number;
+        /**
+         * Zero-based index of the first term (default 0)
+         * @min 0
+         */
+        offset?: number;
+    }, params?: RequestParams) => Promise<HttpResponse<TermListResponse$1, any>>;
     /**
      * No description
      *
@@ -27164,7 +27256,7 @@ declare class Inference<SecurityDataType = unknown> {
      */
     addRule: (data: AddRuleRequest$1, params?: RequestParams) => Promise<HttpResponse<AddRuleResponse$1, any>>;
     /**
-     * @description # TRUE HOMOICONIC API Request contains a goal term and optional constraints. Response returns solutions with term-based substitutions. ## Temporal Reasoning Use constraints to filter by temporal relations: ```json { "goal": {"sort_name": "Employment", "features": {"valid_to": {"name": "?EndTime"}}}, "constraints": [{"type": "Guard", "left": "?EndTime", "op": "lt", "right": "1583020800000"}] } ``` # Authorization Requires X-Tenant-Id header.
+     * @description # TRUE HOMOICONIC API Request contains a goal term and optional constraints. Response returns solutions with term-based substitutions. ## Temporal Reasoning Use constraints to filter by temporal relations: ```json { "goal": {"sort_name": "Employment", "features": {"valid_to": {"name": "?EndTime"}}}, "constraints": [{"type": "Guard", "left": "?EndTime", "op": "lt", "right": "1583020800000"}] } ``` # Authorization Requires X-Tenant-Id header. Traced: this is the path the zanzibar gateway hits for every permission check, so it is where an end-to-end trace either explains a slow request or does not. `skip_all` because the request body can be large and has no business in a span attribute.
      *
      * @tags inference
      * @name BackwardChain
@@ -27315,7 +27407,18 @@ declare class Inference<SecurityDataType = unknown> {
      * @request GET:/api/v1/inference/facts/{tenant_id}
      * @secure
      */
-    getFacts: (tenantId: string, params?: RequestParams) => Promise<HttpResponse<GetFactsResponse$1, any>>;
+    getFacts: (tenantId: string, query?: {
+        /**
+         * Max facts to return; omit for all, hard-capped at 10000
+         * @min 0
+         */
+        limit?: number;
+        /**
+         * Zero-based index of the first fact (default 0)
+         * @min 0
+         */
+        offset?: number;
+    }, params?: RequestParams) => Promise<HttpResponse<GetFactsResponse$1, any>>;
     /**
      * @description # TRUE HOMOICONICITY Returns the full goal term with all its referenced terms. # Authorization Requires X-Tenant-Id header.
      *
@@ -37677,7 +37780,7 @@ declare class Ingestion<SecurityDataType = unknown> {
      */
     getQueueMetrics: (params?: RequestParams) => Promise<HttpResponse<QueueMetricsResponse, void>>;
     /**
-     * @description POST /api/v1/ingest/document This endpoint accepts a document (as base64 or URL) and: 1. Parses it to Markdown using the document parser service (Docling) 2. Processes the Markdown through the existing ingestion pipeline 3. Returns combined statistics from both stages # Headers - `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required) # Request Body - `document`: Document source (base64 or URL) - `document_type`: Optional type hint (auto-detected if not provided) - `owner_id`: User ID who owns the ingested data - `ocr_config`: Optional OCR/parsing configuration - `ingestion_config`: Optional markdown ingestion configuration # Response - `success`: Whether ingestion completed successfully - `parse_stats`: Statistics from document parsing - `metadata`: Extracted document metadata - `ingestion_stats`: Statistics from markdown ingestion - `pending_review`: Entities that need human review
+     * @description POST /api/v1/ingest/document This endpoint accepts a document (as base64 or URL) and: 1. Parses it to Markdown using the document parser service (Docling) 2. Returns the generated Markdown to the caller 3. Unless `parse_only` is true, processes the Markdown through ingestion 4. Returns combined statistics from the completed stages # Headers - `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required) # Request Body - `document`: Document source (base64 or URL) - `document_type`: Optional type hint (auto-detected if not provided) - `owner_id`: User ID who owns the ingested data - `ocr_config`: Optional OCR/parsing configuration - `ingestion_config`: Optional markdown ingestion configuration - `parse_only`: Return Markdown without creating sessions or semantic terms # Response - `success`: Whether ingestion completed successfully - `parse_stats`: Statistics from document parsing - `metadata`: Extracted document metadata - `markdown`: Markdown generated by Docling/OCR - `ingestion_stats`: Statistics from markdown ingestion - `pending_review`: Entities that need human review
      *
      * @tags ingestion
      * @name IngestDocument
@@ -43150,6 +43253,16 @@ declare class StructuredIngestion<SecurityDataType = unknown> {
      * @secure
      */
     listSourceTables: (sourceId: string, params?: RequestParams) => Promise<HttpResponse<ListTablesResponse$1, void>>;
+    /**
+     * @description The pre-registration half of #71's mode-discovery surface: a client rendering a "new source" picker learns, at type-selection time, which types registration would accept and which write-path modes each would serve — without constructing a source (postgres, for example, opens a connection pool eagerly). Static per build, so no tenant state is consulted; auth is still required, as for every route under `/api/v1`.
+     *
+     * @tags structured_ingestion
+     * @name ListSourceTypesCatalog
+     * @summary List the source types this build can register, with their mode capabilities.
+     * @request GET:/api/v1/sources/types
+     * @secure
+     */
+    listSourceTypesCatalog: (params?: RequestParams) => Promise<HttpResponse<ListSourceTypesResponse$1, any>>;
     /**
      * @description Creates a connector instance from the provided configuration and registers it with the structured ingestion service for subsequent schema discovery and data ingestion.
      *
@@ -43315,10 +43428,16 @@ interface RegisterSourceRequest {
     /**
      * Declared write-path intent — see {@link SourceWriteMode}.
      *
-     * Omitted ⇒ capability-grounded default: `transpile` for `postgres` (`postgresql`),
-     * `ingest` for every other source type (postgres is the only adapter whose transpiled
-     * SQL the engine can execute). The resolved value is always echoed back on
+     * Omitted ⇒ `ingest`, for every source type (#71). Ingest is the only mode that
+     * populates the knowledge base and the one path every adapter can serve; `transpile`
+     * is an explicit opt-in. The resolved value is always echoed back on
      * {@link RegisterSourceResponse.mode}, so the applied default is never invisible.
+     *
+     * `transpile` is accepted only for a source whose adapter executes transpiled SQL
+     * (Postgres, MySQL, SQLite). Requesting it for any other source is refused with
+     * **422** — there would be nothing to run the SQL an OSFQL MATCH compiles to. The
+     * set a type accepts is advertised by {@link SourcesClient.listSourceTypes}, so a
+     * caller can avoid the refusal rather than discover it.
      */
     mode?: SourceWriteMode | null;
 }
@@ -43341,6 +43460,15 @@ interface RegisterSourceResponse {
      * Typed as `string` for the reason given on {@link SourceSummaryDto.mode}.
      */
     mode: string;
+    /**
+     * The write-path modes this source's adapter can serve (#71) — the same set
+     * {@link SourcesClient.getSource | getSource} reports. Always contains
+     * `'ingest'`; contains `'transpile'` only when the adapter executes
+     * transpiled SQL. Echoed at registration so a client learns, at the moment
+     * the choice is made, whether `transpile` was even on the table (a mode
+     * change requires DELETE + re-register).
+     */
+    supportedModes: string[];
     /** Status message. */
     message: string;
 }
@@ -43368,6 +43496,60 @@ interface SourceDetailResponse {
      * Typed as `string` for the reason given on {@link SourceSummaryDto.mode}.
      */
     mode: string;
+    /**
+     * The write-path modes this source's adapter can actually serve (#71).
+     *
+     * Always contains `'ingest'` — every adapter can materialize. Contains
+     * `'transpile'` only when the adapter executes transpiled SQL, which is what
+     * a live view requires. A client rendering a mode selector should offer
+     * exactly these, rather than hard-coding a list of source types: the set is
+     * derived from the adapter's declared capability, so it stays correct as
+     * adapters gain the ability.
+     */
+    supportedModes: string[];
+}
+/**
+ * One registrable source TYPE and its capabilities (#71).
+ *
+ * @remarks
+ * The pre-registration half of the mode-discovery surface: a client rendering
+ * a "new source" picker asks {@link SourcesClient.listSourceTypes} which types
+ * this build can register and which write-path modes each would serve — BEFORE
+ * any source exists. The per-source half ({@link SourceDetailResponse}) answers
+ * the same mode question for a source that does.
+ */
+interface SourceTypeDto {
+    /** Canonical type string accepted by `POST /api/v1/sources` (e.g. `"mysql"`). */
+    sourceType: string;
+    /**
+     * Alternate spellings registration also accepts (e.g. `"postgresql"` for
+     * `"postgres"`). A picker that lets the user type a type name should accept
+     * these as equivalent.
+     */
+    aliases: string[];
+    /**
+     * Whether this build can register the type. `false` means the adapter is
+     * behind a cargo feature that is not compiled in: registration would be
+     * refused, so a picker should not offer it (or should show it disabled).
+     */
+    available: boolean;
+    /**
+     * The write-path modes this type's adapter can serve: always `'ingest'`,
+     * plus `'transpile'` when the adapter executes transpiled SQL. The same set
+     * the per-source endpoints report after registration.
+     */
+    supportedModes: string[];
+}
+/**
+ * Response listing the registrable source types of this build (#71).
+ *
+ * @remarks
+ * Returned by `GET /api/v1/sources/types`. Static per build — no tenant state
+ * is consulted — so the catalog is the same for every caller of a given build.
+ */
+interface ListSourceTypesResponse {
+    /** Every source type the registration factory knows how to build. */
+    types: SourceTypeDto[];
 }
 /**
  * One discoverable type of a source, as reported by the cheap name-only listing.
@@ -43504,16 +43686,18 @@ type sources_DiscoveredSortDto = DiscoveredSortDto;
 type sources_DiscoveredSourceRelationDto = DiscoveredSourceRelationDto;
 type sources_IngestFromSourceRequest = IngestFromSourceRequest;
 type sources_IngestFromSourceResponse = IngestFromSourceResponse;
+type sources_ListSourceTypesResponse = ListSourceTypesResponse;
 type sources_ListSourcesResponse = ListSourcesResponse;
 type sources_ListTablesResponse = ListTablesResponse;
 type sources_RegisterSourceRequest = RegisterSourceRequest;
 type sources_RegisterSourceResponse = RegisterSourceResponse;
 type sources_SourceDetailResponse = SourceDetailResponse;
 type sources_SourceSummaryDto = SourceSummaryDto;
+type sources_SourceTypeDto = SourceTypeDto;
 type sources_SourceWriteMode = SourceWriteMode;
 type sources_StructuredIngestionStatsDto = StructuredIngestionStatsDto;
 declare namespace sources {
-  export type { sources_DiscoverSchemaRequest as DiscoverSchemaRequest, sources_DiscoverSchemaResponse as DiscoverSchemaResponse, sources_DiscoverableTypeDto as DiscoverableTypeDto, sources_DiscoveredFeatureDto as DiscoveredFeatureDto, sources_DiscoveredSortDto as DiscoveredSortDto, sources_DiscoveredSourceRelationDto as DiscoveredSourceRelationDto, sources_IngestFromSourceRequest as IngestFromSourceRequest, sources_IngestFromSourceResponse as IngestFromSourceResponse, sources_ListSourcesResponse as ListSourcesResponse, sources_ListTablesResponse as ListTablesResponse, sources_RegisterSourceRequest as RegisterSourceRequest, sources_RegisterSourceResponse as RegisterSourceResponse, sources_SourceDetailResponse as SourceDetailResponse, sources_SourceSummaryDto as SourceSummaryDto, sources_SourceWriteMode as SourceWriteMode, sources_StructuredIngestionStatsDto as StructuredIngestionStatsDto };
+  export type { sources_DiscoverSchemaRequest as DiscoverSchemaRequest, sources_DiscoverSchemaResponse as DiscoverSchemaResponse, sources_DiscoverableTypeDto as DiscoverableTypeDto, sources_DiscoveredFeatureDto as DiscoveredFeatureDto, sources_DiscoveredSortDto as DiscoveredSortDto, sources_DiscoveredSourceRelationDto as DiscoveredSourceRelationDto, sources_IngestFromSourceRequest as IngestFromSourceRequest, sources_IngestFromSourceResponse as IngestFromSourceResponse, sources_ListSourceTypesResponse as ListSourceTypesResponse, sources_ListSourcesResponse as ListSourcesResponse, sources_ListTablesResponse as ListTablesResponse, sources_RegisterSourceRequest as RegisterSourceRequest, sources_RegisterSourceResponse as RegisterSourceResponse, sources_SourceDetailResponse as SourceDetailResponse, sources_SourceSummaryDto as SourceSummaryDto, sources_SourceTypeDto as SourceTypeDto, sources_SourceWriteMode as SourceWriteMode, sources_StructuredIngestionStatsDto as StructuredIngestionStatsDto };
 }
 
 /**
@@ -43535,17 +43719,21 @@ declare class SourcesClient {
      *
      * @param request - Source registration request. Set `mode` to declare the write-path
      *   intent (`'transpile'` for live SQL views, `'ingest'` to materialize rows as
-     *   Ψ-term facts); omit it to take the capability-grounded default (`transpile` for
-     *   postgres, `ingest` otherwise).
+     *   Ψ-term facts); omit it to take the default, which is `'ingest'` for every
+     *   source type (#71).
      * @returns Registration result. `mode` always carries the **resolved** write-path
-     *   mode, including when the default applied.
-     * @throws {ApiError} If registration fails, or with **422** if `mode` is not one of
-     *   `transpile` / `ingest`.
+     *   mode, including when the default applied; `supportedModes` advertises which
+     *   modes this source's adapter can serve.
+     * @throws {ApiError} If registration fails, with **422** if `mode` is not one of
+     *   `transpile` / `ingest`, or with **422** if `mode: 'transpile'` is requested
+     *   for a source whose adapter cannot execute transpiled SQL (a live view over it
+     *   could never be queried).
      *
      * @remarks
      * Registering with `mode: 'transpile'` makes {@link SourcesClient.ingest} refuse this
      * source with a **409** — materializing a transpiled source would create a second,
-     * divergent namespace over the same rows.
+     * divergent namespace over the same rows. To learn which types accept `transpile`
+     * before registering, call {@link SourcesClient.listSourceTypes}.
      *
      * @example
      * ```typescript
@@ -43557,9 +43745,38 @@ declare class SourcesClient {
      *   mode: 'ingest',
      * });
      * console.log(result.mode); // 'ingest'
+     * console.log(result.supportedModes); // ['ingest', 'transpile']
      * ```
      */
     register(request: RegisterSourceRequest): Promise<RegisterSourceResponse>;
+    /**
+     * List the source types this build can register, with their mode capabilities.
+     *
+     * @returns Every registrable source type, its availability in this build, and the
+     *   write-path modes each would serve — before any source exists.
+     * @throws {ApiError} If the request fails.
+     *
+     * @remarks
+     * Sent to `GET /api/v1/sources/types`. The pre-registration half of #71's
+     * mode-discovery surface: a client rendering a "new source" picker learns, at
+     * type-selection time, which types registration would accept (`available` — a
+     * type behind an uncompiled cargo feature is `false`) and which modes each
+     * would serve (`supportedModes` — always `'ingest'`, plus `'transpile'` only
+     * for the SQL engines). Static per build, so no tenant state is consulted.
+     *
+     * Drive a mode selector from `supportedModes` rather than a hard-coded list of
+     * source types: the set is the adapter's declared capability, so it stays
+     * correct as adapters gain the ability (MySQL and SQLite did in #70).
+     *
+     * @example
+     * ```typescript
+     * const { types } = await client.sources.listSourceTypes();
+     * const postgres = types.find((t) => t.sourceType === 'postgres');
+     * console.log(postgres?.supportedModes); // ['ingest', 'transpile']
+     * console.log(postgres?.aliases); // ['postgresql']
+     * ```
+     */
+    listSourceTypes(): Promise<ListSourceTypesResponse>;
     /**
      * List all registered data sources.
      *
@@ -65588,7 +65805,7 @@ interface SystemGroup {
  * import { ReasoningLayerClient } from '@kortexya/reasoning-layer';
  *
  * const client = new ReasoningLayerClient({
- *   baseUrl: 'http://localhost:8083',
+ *   baseUrl: 'http://localhost:8085',
  *   tenantId: 'my-tenant-uuid',
  * });
  *