@kortexya/reasoninglayer 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -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.4.1";
+declare const SDK_VERSION = "0.5.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -10355,6 +10355,77 @@ interface OsfSearchStatsDto$1 {
      */
     relationsDiscovered: number;
 }
+/** Error response for OSFQL execution failures. */
+interface OsfqlErrorResponse {
+    /** Error type: "parse", "compile", or "execution". */
+    errorType: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/** Request to execute an OSFQL program. */
+interface OsfqlRequest$1 {
+    /**
+     * OSFQL program text (one or more statements separated by `;`).
+     *
+     * # Examples
+     *
+     * ```text
+     * MATCH person(name: ?N, age: ?A) WHERE ?A > 18;
+     * ```
+     *
+     * ```text
+     * INSERT person(name: "Alice", age: 30);
+     * MATCH person(name: ?N);
+     * ```
+     */
+    query: string;
+}
+/** Response from executing an OSFQL program. */
+interface OsfqlResponse$1 {
+    /** Variable bindings from MATCH queries. */
+    bindings: Record<string, OsfqlValueDto>[];
+    /** IDs of newly defined sorts (from DEFINE statements). */
+    definedSortIds?: string[];
+    /** Diagnostic messages from the execution pipeline. */
+    diagnostics: string[];
+    /** IDs of produced/modified terms (from INSERT, DERIVE, etc.). */
+    producedTermIds: string[];
+    /**
+     * Number of statements executed.
+     * @min 0
+     */
+    statementCount: number;
+    /** Whether the execution succeeded. */
+    success: boolean;
+}
+/** A bound value in an OSFQL result. */
+type OsfqlValueDto = {
+    type: "integer";
+    /**
+     * Integer value.
+     * @format int64
+     */
+    value: number;
+} | {
+    type: "float";
+    /**
+     * Floating-point value.
+     * @format double
+     */
+    value: number;
+} | {
+    type: "string";
+    /** String value. */
+    value: string;
+} | {
+    type: "boolean";
+    /** Boolean value. */
+    value: boolean;
+} | {
+    type: "term_ref";
+    /** Reference to a term (by UUID). */
+    value: string;
+};
 /** An alert DTO for live oversight sessions. */
 interface OversightAlertDto$1 {
     /** Agent ID responsible (for multi-agent systems) */
@@ -36904,6 +36975,335 @@ declare class OptimizeClient {
     private cleanupArtifacts;
 }
 
+declare class Osfql<SecurityDataType = unknown> {
+    http: HttpClient<SecurityDataType>;
+    constructor(http: HttpClient<SecurityDataType>);
+    /**
+     * @description Parses, compiles, and executes an OSFQL program against the caller's tenant-isolated knowledge base. Supports all OSFQL statement types: MATCH, INSERT, RETRACT, DERIVE, UNIFY, AWAIT, COUNTERFACTUAL, CAUSES. # Examples ```json { "query": "INSERT person(name: \"Alice\", age: 30);" } ``` ```json { "query": "MATCH person(name: ?N, age: ?A) WHERE ?A > 18;" } ```
+     *
+     * @tags osfql
+     * @name ExecuteOsfql
+     * @summary Execute an OSFQL program.
+     * @request POST:/api/v1/osfql
+     * @secure
+     */
+    executeOsfql: (data: OsfqlRequest$1, params?: RequestParams) => Promise<HttpResponse<OsfqlResponse$1, OsfqlErrorResponse>>;
+}
+
+/**
+ * Request to execute an OSFQL program.
+ *
+ * @remarks
+ * The query field accepts one or more OSFQL statements separated by semicolons.
+ * Supported statement types include MATCH, INSERT, RETRACT, DERIVE, UNIFY,
+ * DEFINE, AWAIT, COUNTERFACTUAL, and CAUSES.
+ */
+interface OsfqlRequest {
+    /** The OSFQL program text (one or more statements separated by `;`). */
+    query: string;
+}
+/**
+ * A bound value from OSFQL execution.
+ *
+ * @remarks
+ * Uses a tagged discriminated union with `type` as the discriminant.
+ * Represents the possible value types that can appear in OSFQL variable bindings.
+ */
+type OsfqlValue = {
+    type: 'integer';
+    value: number;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'string';
+    value: string;
+} | {
+    type: 'boolean';
+    value: boolean;
+} | {
+    type: 'term_ref';
+    value: string;
+};
+/**
+ * Response from OSFQL execution.
+ *
+ * @remarks
+ * Contains the results of executing an OSFQL program, including variable
+ * bindings from MATCH queries, IDs of produced terms and defined sorts,
+ * and diagnostic messages from the execution pipeline.
+ */
+interface OsfqlResponse {
+    /** Whether execution succeeded. */
+    success: boolean;
+    /** Variable bindings from MATCH queries. Each entry represents one solution. */
+    bindings: Record<string, OsfqlValue>[];
+    /** Term IDs produced by INSERT or DERIVE statements. */
+    producedTermIds: string[];
+    /** Sort IDs produced by DEFINE statements. */
+    definedSortIds?: string[];
+    /** Diagnostic messages from the execution pipeline. */
+    diagnostics: string[];
+    /** Number of statements executed. */
+    statementCount: number;
+}
+
+type osfql_OsfqlRequest = OsfqlRequest;
+type osfql_OsfqlResponse = OsfqlResponse;
+type osfql_OsfqlValue = OsfqlValue;
+declare namespace osfql {
+  export type { osfql_OsfqlRequest as OsfqlRequest, osfql_OsfqlResponse as OsfqlResponse, osfql_OsfqlValue as OsfqlValue };
+}
+
+/**
+ * Resource client for OSFQL (OSF Query Language) operations.
+ *
+ * @remarks
+ * Provides access to the OSFQL execution endpoint, which parses, compiles,
+ * and executes OSFQL programs against the tenant-isolated knowledge base.
+ *
+ * Supported statement types include MATCH, INSERT, RETRACT, DERIVE, UNIFY,
+ * DEFINE, AWAIT, COUNTERFACTUAL, and CAUSES.
+ *
+ * Delegates to generated route classes for type-safe HTTP calls.
+ */
+declare class OsfqlClient {
+    /** @internal */
+    private readonly api;
+    /** @internal */
+    constructor(api: Osfql);
+    /**
+     * Execute an OSFQL program.
+     *
+     * @param query - The OSFQL program text (one or more statements separated by `;`).
+     * @returns The execution result including variable bindings, produced term IDs,
+     *   defined sort IDs, diagnostics, and statement count.
+     * @throws {ApiError} If the request fails.
+     *
+     * @remarks
+     * The query is parsed, compiled, and executed against the caller's tenant-isolated
+     * knowledge base. Results include variable bindings from MATCH queries and IDs of
+     * any terms or sorts created by INSERT, DERIVE, or DEFINE statements.
+     *
+     * @example
+     * ```typescript
+     * // Insert a record and query it back
+     * const result = await client.osfql.execute(
+     *   'INSERT person(name: "Alice", age: 30); MATCH person(name: ?N);'
+     * );
+     * console.log(result.success);          // true
+     * console.log(result.bindings);         // [{ N: { type: "string", value: "Alice" } }]
+     * console.log(result.producedTermIds);  // ["<uuid>"]
+     * console.log(result.statementCount);   // 2
+     * ```
+     */
+    execute(query: string): Promise<OsfqlResponse>;
+}
+
+/**
+ * Request to send a message in a conversation.
+ *
+ * @remarks
+ * The conversation service translates natural language to OSFQL,
+ * executes it (with up to 3 self-correction retries on failure),
+ * and returns both the generated OSFQL and the results.
+ *
+ * Reuse `conversationId` from a previous response for multi-turn
+ * context (pronoun resolution, follow-up queries).
+ */
+interface ConversationMessageRequest {
+    /** The user's natural language message. */
+    message: string;
+    /**
+     * Optional conversation ID to continue an existing conversation.
+     * If omitted, a new conversation is created.
+     */
+    conversationId?: string | null;
+    /** Session ID for session tracking. */
+    sessionId?: string | null;
+    /** Optional sort name hint from the current page context. */
+    currentSortContext?: string | null;
+}
+/**
+ * Response from processing a conversation message.
+ *
+ * @remarks
+ * Contains the assistant's NL response, the OSFQL that was generated
+ * and executed, query results (for MATCH queries), and contextual
+ * suggestions for follow-up queries.
+ */
+interface ConversationMessageResponse {
+    /** The assistant's natural language response. */
+    assistantMessage: string;
+    /** The conversation ID (existing or newly created). */
+    conversationId: string;
+    /** Classified intent type (e.g., "query", "insert", "define"). */
+    intent: string;
+    /** OSFQL that was executed (if any). */
+    osfqlExecuted?: string | null;
+    /** Query results (if OSFQL was a MATCH). Each entry maps variable names to bound values. */
+    queryResults?: Record<string, OsfqlValue>[] | null;
+    /** IDs of terms produced by the OSFQL execution. */
+    producedTermIds: string[];
+    /** Sort ID referenced in the message (for UI rendering). */
+    uiSortId?: string | null;
+    /** Contextual OSFQL suggestions for follow-up queries. */
+    suggestions: string[];
+}
+/**
+ * A single conversation turn (message).
+ */
+interface TurnDto {
+    /** Turn ID. */
+    id: string;
+    /** "user" or "assistant". */
+    role: string;
+    /** Message content. */
+    content: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Classified intent (assistant turns only). */
+    intent?: string | null;
+    /** OSFQL generated (assistant turns only). */
+    osfql?: string | null;
+}
+/**
+ * A conversation summary.
+ */
+interface ConversationSummaryDto {
+    /** Conversation ID. */
+    id: string;
+    /** Session ID. */
+    sessionId?: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** Number of turns. */
+    turnCount: number;
+}
+/**
+ * Response for listing conversations.
+ */
+interface ListConversationsResponse {
+    conversations: ConversationSummaryDto[];
+}
+/**
+ * Response for getting conversation turns.
+ */
+interface ConversationTurnsResponse {
+    conversationId: string;
+    turns: TurnDto[];
+}
+
+type conversation_ConversationMessageRequest = ConversationMessageRequest;
+type conversation_ConversationMessageResponse = ConversationMessageResponse;
+type conversation_ConversationSummaryDto = ConversationSummaryDto;
+type conversation_ConversationTurnsResponse = ConversationTurnsResponse;
+type conversation_ListConversationsResponse = ListConversationsResponse;
+type conversation_TurnDto = TurnDto;
+declare namespace conversation {
+  export type { conversation_ConversationMessageRequest as ConversationMessageRequest, conversation_ConversationMessageResponse as ConversationMessageResponse, conversation_ConversationSummaryDto as ConversationSummaryDto, conversation_ConversationTurnsResponse as ConversationTurnsResponse, conversation_ListConversationsResponse as ListConversationsResponse, conversation_TurnDto as TurnDto };
+}
+
+/**
+ * Resource client for conversational AI operations.
+ *
+ * @remarks
+ * Wraps the conversation endpoint which translates natural language
+ * to OSFQL, executes it (with self-correction on failure), and returns
+ * results along with the generated OSFQL and contextual suggestions.
+ *
+ * Multi-turn context is supported by reusing the `conversationId` from
+ * a previous response — the backend maintains conversation history for
+ * pronoun resolution and follow-up queries.
+ *
+ * Delegates to the generated HTTP client for type-safe transport with
+ * automatic serialization, authentication, retry, and timeout behavior.
+ */
+declare class ConversationClient {
+    /** @internal */
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Send a natural language message and receive OSFQL-powered results.
+     *
+     * @param request - The conversation message request.
+     * @returns The assistant's response including generated OSFQL, query results, and suggestions.
+     * @throws {ApiError} If the request fails.
+     *
+     * @remarks
+     * The conversation service:
+     * 1. Classifies the intent (query, insert, define, etc.)
+     * 2. Generates OSFQL from the natural language
+     * 3. Executes the OSFQL against the knowledge base
+     * 4. Self-corrects up to 3 times if execution fails
+     * 5. Returns results + the generated OSFQL + suggestions
+     *
+     * Reuse `conversationId` from a previous response for multi-turn context.
+     *
+     * @example
+     * ```typescript
+     * // First message — starts a new conversation
+     * const first = await client.conversation.sendMessage({
+     *   message: 'Who are the prime suspects?',
+     * });
+     * console.log(first.osfqlExecuted);   // "PROVE prime_suspect(name: ?N, motive: ?M);"
+     * console.log(first.queryResults);    // [{ N: ..., M: ... }, ...]
+     *
+     * // Follow-up — reuses conversation context
+     * const followUp = await client.conversation.sendMessage({
+     *   message: 'Which of them had a key?',
+     *   conversationId: first.conversationId,
+     * });
+     * ```
+     */
+    sendMessage(request: ConversationMessageRequest): Promise<ConversationMessageResponse>;
+    /**
+     * List recent conversations for the authenticated user.
+     *
+     * @returns List of conversation summaries.
+     * @throws {ApiError} If the request fails.
+     *
+     * @example
+     * ```typescript
+     * const { conversations } = await client.conversation.listConversations();
+     * for (const c of conversations) {
+     *   console.log(`${c.id}: ${c.turnCount} turns (${c.createdAt})`);
+     * }
+     * ```
+     */
+    listConversations(): Promise<ListConversationsResponse>;
+    /**
+     * Get all turns for a conversation.
+     *
+     * @param conversationId - The conversation ID.
+     * @returns All turns in the conversation.
+     * @throws {ApiError} If the request fails.
+     *
+     * @example
+     * ```typescript
+     * const { turns } = await client.conversation.getTurns('conv-uuid');
+     * for (const turn of turns) {
+     *   console.log(`[${turn.role}] ${turn.content}`);
+     *   if (turn.osfql) console.log(`  OSFQL: ${turn.osfql}`);
+     * }
+     * ```
+     */
+    getTurns(conversationId: string): Promise<ConversationTurnsResponse>;
+    /**
+     * Delete a conversation and all its turns.
+     *
+     * @param conversationId - The conversation ID to delete.
+     * @throws {ApiError} If the request fails.
+     *
+     * @example
+     * ```typescript
+     * await client.conversation.deleteConversation('conv-uuid');
+     * ```
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+}
+
 /** Core knowledge base operations — types, records, rules, functions, constraints, and queries. */
 interface CoreGroup {
     readonly types: SortsClient;
@@ -37073,6 +37473,10 @@ declare class ReasoningLayerClient {
     readonly rag: RagClient;
     /** Linear program optimization (CLP(Q) simplex solver via backward chaining). */
     readonly optimize: OptimizeClient;
+    /** OSFQL (OSF Query Language) execution operations. */
+    readonly osfql: OsfqlClient;
+    /** Conversational AI operations (NL → OSFQL with self-correction). */
+    readonly conversation: ConversationClient;
     private _core?;
     private _ai?;
     private _reasoning?;
@@ -37467,7 +37871,7 @@ declare const FuzzyShape: {
  *
  * @remarks
  * Serialization format: Untagged (TermInputDto). Used as the `constraint` argument
- * to `FeatureInput.constrainedVar()`.
+ * to `constrained()`.
  *
  * This function constructs object literals directly matching the `TermInputDto` and
  * `FeatureInputValueDto` shapes. It does NOT import from other builder files.
@@ -37479,15 +37883,15 @@ declare const FuzzyShape: {
  *
  * @example
  * ```typescript
- * import { FeatureInput, guard } from '@kortexya/reasoninglayer';
+ * import { psi, constrained, guard } from '@kortexya/reasoninglayer';
  *
- * // Shorthand:
- * const salary = FeatureInput.constrainedVar("?Salary", guard("gt", 100));
+ * // Use with constrained():
+ * const salary = constrained("?Salary", guard("gt", 100));
  *
- * // Equivalent to:
- * const salaryExplicit = FeatureInput.constrainedVar("?Salary",
- *   { sort_name: "guard_constraint", features: { op: "gt", right: 100 } }
- * );
+ * // In a rule:
+ * psi("employee", {
+ *   salary: constrained("?Salary", guard("gt", 100)),
+ * })
  * ```
  */
 declare function guard(op: GuardOp, right: number | string | boolean): TermInputDto;
@@ -37513,9 +37917,9 @@ declare function guard(op: GuardOp, right: number | string | boolean): TermInput
  *   })
  *   .feature({ name: "department", required: true })
  *   .boundConstraint({
- *     constraint_type: "upper",
+ *     constraintType: "upper",
  *     target: "end_date",
- *     source_path: "company.dissolutionDate",
+ *     sourcePath: "company.dissolutionDate",
  *   })
  *   .description("An employee at a company")
  *   .build();
@@ -37610,9 +38014,9 @@ declare class SortBuilder {
      * @example
      * ```typescript
      * builder.boundConstraint({
-     *   constraint_type: "upper",
+     *   constraintType: "upper",
      *   target: "end_date",
-     *   source_path: "company.dissolutionDate",
+     *   sourcePath: "company.dissolutionDate",
      * })
      * ```
      */
@@ -38053,4 +38457,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, type CoreGroup, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type 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, ingestion as Ingestion, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type LubRequest, type LubResponse, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, oversight as Oversight, type PaginationParams, 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, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, 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 UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, 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 CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type 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, 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 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, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, 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, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };