@kortexya/reasoninglayer 0.2.1 → 0.2.2

package/README.md

@@ -7,8 +7,8 @@ TypeScript SDK for the [Reasoning Layer](https://kortexya.com) API — a knowled
 - **Zero runtime dependencies** — only `fetch` and `AbortController` (ES2022)
 - **Dual ESM/CJS** — works in Node 18+, modern browsers, Deno, and Bun
 - **Full type safety** — strict TypeScript with discriminated unions, no `any` types
-- **28 resource clients** covering sorts, terms, inference, query, fuzzy logic, cognitive agents, causal reasoning, and more
-- **7 builder namespaces** — `Value`, `FeatureInput`, `TermInput`, `guard`, `SortBuilder`, `psi`, `allen`
+- **29 resource clients** covering sorts, terms, inference, query, fuzzy logic, cognitive agents, causal reasoning, optimization, and more
+- **8 builder namespaces** — `Value`, `FeatureInput`, `TermInput`, `guard`, `SortBuilder`, `psi`, `allen`, `LP`
 - **Automatic retry** — exponential backoff with jitter on 429 and 503 responses
 - **WebSocket** — real-time cognitive agent event subscriptions with auto-reconnect
 - **Error hierarchy** — typed errors for constraint violations, rate limits, timeouts, and network failures
@@ -107,6 +107,7 @@ console.log(result.solutions); // Solutions with bindings
 | `actionReviews` | Action reviews | approve, reject, modify autonomous actions |
 | `discovery` | Discovery | causal effect discovery, prediction |
 | `extract` | Extraction | entity extraction from text |
+| `optimize` | Optimization | LP solve, KB-driven optimization |
 
 ## Configuration
 
@@ -167,7 +168,7 @@ try {
 The SDK provides builder functions for constructing API request values with full type safety:
 
 ```typescript
-import { Value, FeatureInput, TermInput, guard, allen, SortBuilder, psi } from '@kortexya/reasoninglayer';
+import { Value, FeatureInput, TermInput, guard, allen, SortBuilder, psi, LP } from '@kortexya/reasoninglayer';
 
 // Tagged values (term CRUD)
 Value.string('hello')           // { type: 'String', value: 'hello' }
@@ -185,6 +186,11 @@ guard('gt', 100)                // { guard: { op: 'gt', value: 100 } }
 // Allen temporal relations
 allen('before')                 // { allen: 'before' }
 
+// LP optimization
+LP.maximize({ x: 3, y: 5 })    // objective function
+LP.constraint({ x: 1, y: 3 }, '<=', 12)  // linear constraint
+LP.nonNegative('x', 'y')       // variable bounds
+
 // Fluent sort builder
 new SortBuilder('employee')
   .parents(['person'])

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/config.ts
-var SDK_VERSION = "0.2.1";
+var SDK_VERSION = "0.2.2";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -12548,6 +12548,553 @@ var RagClient = class {
   }
 };
 
+// src/builders/lp.ts
+var LP = {
+  /**
+   * Create a maximization objective.
+   *
+   * @param coefficients - Map of variable names to their objective coefficients.
+   * @returns An objective function to maximize.
+   *
+   * @remarks Serialization format: SDK-internal (compiled to constraint sorts).
+   *
+   * @example
+   * ```typescript
+   * LP.maximize({ chairs: 3, tables: 5 })
+   * // { direction: 'maximize', coefficients: { chairs: 3, tables: 5 } }
+   * ```
+   */
+  maximize(coefficients) {
+    return { direction: "maximize", coefficients };
+  },
+  /**
+   * Create a minimization objective.
+   *
+   * @param coefficients - Map of variable names to their objective coefficients.
+   * @returns An objective function to minimize.
+   *
+   * @remarks Serialization format: SDK-internal (compiled to constraint sorts).
+   *
+   * @example
+   * ```typescript
+   * LP.minimize({ cost_a: 2, cost_b: 5 })
+   * // { direction: 'minimize', coefficients: { cost_a: 2, cost_b: 5 } }
+   * ```
+   */
+  minimize(coefficients) {
+    return { direction: "minimize", coefficients };
+  },
+  /**
+   * Create a linear constraint.
+   *
+   * @param coefficients - Map of variable names to their constraint coefficients.
+   * @param op - Comparison operator: '<=', '>=', or '='.
+   * @param rhs - Right-hand side constant.
+   * @param label - Optional human-readable label.
+   * @returns A linear constraint.
+   *
+   * @remarks Serialization format: SDK-internal (compiled to constraint sorts).
+   *
+   * @example
+   * ```typescript
+   * LP.constraint({ chairs: 1, tables: 3 }, '<=', 12, 'wood')
+   * // { coefficients: { chairs: 1, tables: 3 }, op: '<=', rhs: 12, label: 'wood' }
+   * ```
+   */
+  constraint(coefficients, op, rhs, label) {
+    return label !== void 0 ? { coefficients, op, rhs, label } : { coefficients, op, rhs };
+  },
+  /**
+   * Create non-negativity bounds (>= 0) for the given variables.
+   *
+   * @param variables - Variable names to constrain to be non-negative.
+   * @returns A bounds map with `{ min: 0 }` for each variable.
+   *
+   * @remarks Serialization format: SDK-internal (compiled to constraint sorts).
+   *
+   * @example
+   * ```typescript
+   * LP.nonNegative('chairs', 'tables')
+   * // { chairs: { min: 0 }, tables: { min: 0 } }
+   * ```
+   */
+  nonNegative(...variables) {
+    const bounds = {};
+    for (const v of variables) {
+      bounds[v] = { min: 0 };
+    }
+    return bounds;
+  },
+  /**
+   * Create bounds for a variable.
+   *
+   * @param min - Lower bound (omit for unbounded below).
+   * @param max - Upper bound (omit for unbounded above).
+   * @returns Variable bounds specification.
+   *
+   * @remarks Serialization format: SDK-internal (compiled to constraint sorts).
+   *
+   * @example
+   * ```typescript
+   * LP.bounds(0, 100)
+   * // { min: 0, max: 100 }
+   * ```
+   */
+  bounds(min, max) {
+    const b = {};
+    if (min !== void 0) b.min = min;
+    if (max !== void 0) b.max = max;
+    return b;
+  }
+};
+function compileLP(problem, solutionSortName) {
+  const counter = { value: 0 };
+  const nextVar = () => `?_lp_${counter.value++}`;
+  const variableNames = discoverVariables(problem);
+  if (variableNames.length === 0) {
+    throw new Error("LP problem has no variables. At least one variable must appear in the objective or constraints.");
+  }
+  const varRefs = {};
+  for (const name of variableNames) {
+    varRefs[name] = { name: `?${name}` };
+  }
+  const allAntecedents = [];
+  if (problem.bounds) {
+    for (const [varName, bounds] of Object.entries(problem.bounds)) {
+      if (!(varName in varRefs)) continue;
+      const ref = varRefs[varName];
+      if (bounds.min !== void 0 && bounds.max !== void 0) {
+        allAntecedents.push({
+          sort_name: "real_between_constraint",
+          features: {
+            var: ref,
+            lower: bounds.min,
+            upper: bounds.max
+          }
+        });
+      } else {
+        if (bounds.min !== void 0) {
+          allAntecedents.push({
+            sort_name: "real_ge_constraint",
+            features: {
+              left: ref,
+              right: bounds.min
+            }
+          });
+        }
+        if (bounds.max !== void 0) {
+          allAntecedents.push({
+            sort_name: "real_le_constraint",
+            features: {
+              left: ref,
+              right: bounds.max
+            }
+          });
+        }
+      }
+    }
+  }
+  for (const constraint of problem.constraints) {
+    const compiled = compileLinearExpression(constraint.coefficients, varRefs, nextVar);
+    allAntecedents.push(...compiled.antecedents);
+    const sortName = constraintOpToSort(constraint.op);
+    allAntecedents.push({
+      sort_name: sortName,
+      features: {
+        left: compiled.resultRef,
+        right: constraint.rhs
+      }
+    });
+  }
+  const objectiveCompiled = compileLinearExpression(
+    problem.objective.coefficients,
+    varRefs,
+    nextVar
+  );
+  allAntecedents.push(...objectiveCompiled.antecedents);
+  let objectiveRef = objectiveCompiled.resultRef;
+  if (typeof objectiveRef === "number") {
+    const objVar = { name: "?_lp_objective" };
+    allAntecedents.push({
+      sort_name: "real_eq_constraint",
+      features: {
+        left: objVar,
+        right: objectiveRef
+      }
+    });
+    objectiveRef = objVar;
+  }
+  const objectiveSortName = problem.objective.direction === "maximize" ? "maximize_objective" : "minimize_objective";
+  allAntecedents.push({
+    sort_name: objectiveSortName,
+    features: {
+      expression: objectiveRef,
+      name: "objective"
+    }
+  });
+  const variableRefList = variableNames.map(
+    (name) => varRefs[name]
+  );
+  allAntecedents.push({
+    sort_name: "real_labeling_constraint",
+    features: {
+      variables: variableRefList
+    }
+  });
+  const solutionFeatures = {};
+  for (const name of variableNames) {
+    solutionFeatures[name] = varRefs[name];
+  }
+  solutionFeatures["_objective"] = objectiveRef;
+  const solutionTerm = {
+    sort_name: solutionSortName,
+    features: solutionFeatures
+  };
+  return { solutionTerm, antecedents: allAntecedents };
+}
+function discoverVariables(problem) {
+  const vars = /* @__PURE__ */ new Set();
+  for (const name of Object.keys(problem.objective.coefficients)) {
+    vars.add(name);
+  }
+  for (const constraint of problem.constraints) {
+    for (const name of Object.keys(constraint.coefficients)) {
+      vars.add(name);
+    }
+  }
+  if (problem.bounds) {
+    for (const name of Object.keys(problem.bounds)) {
+      vars.add(name);
+    }
+  }
+  return Array.from(vars).sort();
+}
+function compileLinearExpression(expression, varRefs, nextVar) {
+  const antecedents = [];
+  const termResults = [];
+  for (const [varName, coefficient] of Object.entries(expression)) {
+    if (coefficient === 0) continue;
+    const varRef = varRefs[varName];
+    if (!varRef) continue;
+    if (coefficient === 1) {
+      termResults.push(varRef);
+    } else {
+      const resultVar = { name: nextVar() };
+      antecedents.push({
+        sort_name: "real_times_constraint",
+        features: {
+          coefficient,
+          variable: varRef,
+          result: resultVar
+        }
+      });
+      termResults.push(resultVar);
+    }
+  }
+  if (termResults.length === 0) {
+    return { antecedents, resultRef: 0 };
+  }
+  if (termResults.length === 1) {
+    return { antecedents, resultRef: termResults[0] };
+  }
+  let current = termResults[0];
+  for (let i = 1; i < termResults.length; i++) {
+    const sumVar = { name: nextVar() };
+    antecedents.push({
+      sort_name: "real_plus_constraint",
+      features: {
+        left: current,
+        right: termResults[i],
+        result: sumVar
+      }
+    });
+    current = sumVar;
+  }
+  return { antecedents, resultRef: current };
+}
+function constraintOpToSort(op) {
+  switch (op) {
+    case "<=":
+      return "real_le_constraint";
+    case ">=":
+      return "real_ge_constraint";
+    case "=":
+      return "real_eq_constraint";
+  }
+}
+
+// src/resources/optimize.ts
+var OptimizeClient = class {
+  /** @internal */
+  inferenceApi;
+  /** @internal */
+  sortsApi;
+  /** @internal */
+  queryApi;
+  /** @internal */
+  termsApi;
+  /** @internal */
+  tenantId;
+  /** @internal */
+  constructor(inferenceApi, sortsApi, queryApi, termsApi, tenantId) {
+    this.inferenceApi = inferenceApi;
+    this.sortsApi = sortsApi;
+    this.queryApi = queryApi;
+    this.termsApi = termsApi;
+    this.tenantId = tenantId;
+  }
+  /**
+   * Solve a linear program.
+   *
+   * @param problem - The LP problem definition with objective, constraints, and bounds.
+   * @param options - Optional solver configuration (timeout, cleanup, etc.).
+   * @returns The optimization result with variable values and objective value.
+   *
+   * @throws {Error} If the problem has no variables.
+   *
+   * @remarks
+   * Internally creates a temporary sort and inference rule, runs backward chaining
+   * to trigger the CLP(Q) simplex solver, then cleans up temporary artifacts.
+   *
+   * The solver uses exact rational arithmetic (Rational64). Solutions are converted
+   * to JavaScript numbers (f64 approximation) for the response.
+   *
+   * @example
+   * ```typescript
+   * import { LP } from '@kortexya/reasoninglayer';
+   *
+   * const result = await client.optimize.solve({
+   *   objective: LP.maximize({ x: 1, y: 2 }),
+   *   constraints: [
+   *     LP.constraint({ x: 1, y: 1 }, '<=', 10),
+   *   ],
+   *   bounds: LP.nonNegative('x', 'y'),
+   * });
+   *
+   * if (result.status === 'optimal') {
+   *   console.log(result.variables);      // { x: 0, y: 10 }
+   *   console.log(result.objectiveValue); // 20
+   * }
+   * ```
+   */
+  async solve(problem, options) {
+    const cleanup = options?.cleanup !== false;
+    const timeoutMs = options?.timeoutMs ?? 3e4;
+    const maxDepth = options?.maxDepth ?? 50;
+    const suffix = generateShortId();
+    const solutionSortName = `_lp_solution_${suffix}`;
+    const compiled = compileLP(problem, solutionSortName);
+    let sortId;
+    let ruleTermId;
+    try {
+      const sortResponse = await this.sortsApi.bulkCreateSorts({
+        sorts: [{ name: solutionSortName, parents: ["thing"] }]
+      });
+      sortId = sortResponse.data.sort_ids[solutionSortName];
+      const ruleResponse = await this.inferenceApi.addRule({
+        term: compiled.solutionTerm,
+        antecedents: compiled.antecedents,
+        certainty: 1
+      });
+      ruleTermId = ruleResponse.data.term.term_id;
+      const bcResponse = await this.inferenceApi.backwardChain({
+        goal: { sort_name: solutionSortName },
+        max_solutions: 1,
+        max_depth: maxDepth,
+        timeout_ms: timeoutMs
+      });
+      const queryTimeMs = bcResponse.data.query_time_ms;
+      if (bcResponse.data.solutions.length === 0) {
+        return { status: "infeasible", solveTimeMs: queryTimeMs };
+      }
+      const solution = bcResponse.data.solutions[0];
+      const variables = {};
+      let objectiveValue = 0;
+      for (const binding of solution.substitution.bindings) {
+        const varName = binding.variable_name;
+        if (!varName) continue;
+        const value = parseFloat(binding.bound_to_display);
+        if (isNaN(value)) continue;
+        if (varName === "?_lp_objective") {
+          objectiveValue = value;
+        } else if (varName.startsWith("?") && !varName.startsWith("?_lp_")) {
+          variables[varName.slice(1)] = value;
+        }
+      }
+      return {
+        status: "optimal",
+        variables,
+        objectiveValue,
+        solveTimeMs: queryTimeMs
+      };
+    } finally {
+      if (cleanup) {
+        await this.cleanupArtifacts(ruleTermId, sortId);
+      }
+    }
+  }
+  /**
+   * Solve an LP problem with variables and coefficients discovered from the knowledge base.
+   *
+   * @param config - Configuration specifying which sorts/features to query and how to
+   *   map them to LP variables, objective, and constraints.
+   * @param options - Optional solver configuration.
+   * @returns The optimization result plus the auto-generated LP and discovered terms.
+   *
+   * @throws {Error} If the specified sort is not found.
+   * @throws {Error} If no terms are found for the variable sort.
+   * @throws {Error} If a required feature is missing or non-numeric on a term.
+   *
+   * @remarks
+   * This method queries existing knowledge base data to build the LP automatically:
+   * 1. Resolves the variable sort name to its sort ID
+   * 2. Queries all terms of that sort
+   * 3. Extracts feature values to compute objective coefficients and constraint coefficients
+   * 4. Builds and solves the LP
+   *
+   * @example
+   * ```typescript
+   * // Given products in the KB with features: name, profit, wood_cost, labor_cost
+   * const result = await client.optimize.fromKnowledgeBase({
+   *   variables: { sort: 'product', nameFeature: 'name' },
+   *   objective: { direction: 'maximize', coefficientFeature: 'profit' },
+   *   resourceConstraints: [
+   *     { costFeature: 'wood_cost', capacity: 12, label: 'wood' },
+   *     { costFeature: 'labor_cost', capacity: 8, label: 'labor' },
+   *   ],
+   *   nonNegative: true,
+   * });
+   *
+   * if (result.result.status === 'optimal') {
+   *   console.log(result.result.variables); // { chair: 2.4, table: 3.2 }
+   * }
+   * console.log(result.generatedProblem);   // The auto-generated LP for inspection
+   * ```
+   */
+  async fromKnowledgeBase(config, options) {
+    const sortId = await this.resolveSortName(config.variables.sort);
+    const queryResponse = await this.queryApi.findBySort({
+      sort_id: sortId
+    });
+    const terms = queryResponse.data.terms;
+    if (terms.length === 0) {
+      throw new Error(
+        `No terms found for sort '${config.variables.sort}'. Create terms with features [${config.objective.coefficientFeature}, ${config.resourceConstraints.map((r) => r.costFeature).join(", ")}] first.`
+      );
+    }
+    const variableNames = [];
+    const objectiveCoeffs = {};
+    const constraintCoeffsMap = {};
+    for (const rc of config.resourceConstraints) {
+      constraintCoeffsMap[rc.costFeature] = {};
+    }
+    for (const term of terms) {
+      const name = extractStringValue(term.features, config.variables.nameFeature);
+      if (!name) {
+        throw new Error(
+          `Term ${term.id} of sort '${config.variables.sort}' is missing the name feature '${config.variables.nameFeature}' or it is not a string.`
+        );
+      }
+      variableNames.push(name);
+      const objCoeff = extractNumericValue(term.features, config.objective.coefficientFeature);
+      if (objCoeff === null) {
+        throw new Error(
+          `Term '${name}' (${term.id}) is missing numeric feature '${config.objective.coefficientFeature}' for the objective.`
+        );
+      }
+      objectiveCoeffs[name] = objCoeff;
+      for (const rc of config.resourceConstraints) {
+        const costCoeff = extractNumericValue(term.features, rc.costFeature);
+        if (costCoeff === null) {
+          throw new Error(
+            `Term '${name}' (${term.id}) is missing numeric feature '${rc.costFeature}' for the resource constraint.`
+          );
+        }
+        constraintCoeffsMap[rc.costFeature][name] = costCoeff;
+      }
+    }
+    const constraints = config.resourceConstraints.map((rc) => ({
+      coefficients: constraintCoeffsMap[rc.costFeature],
+      op: rc.op ?? "<=",
+      rhs: rc.capacity,
+      ...rc.label ? { label: rc.label } : {}
+    }));
+    if (config.additionalConstraints) {
+      constraints.push(...config.additionalConstraints);
+    }
+    const generatedProblem = {
+      objective: {
+        direction: config.objective.direction,
+        coefficients: objectiveCoeffs
+      },
+      constraints,
+      bounds: config.nonNegative ? Object.fromEntries(variableNames.map((n) => [n, { min: 0 }])) : void 0
+    };
+    const result = await this.solve(generatedProblem, options);
+    return {
+      result,
+      generatedProblem,
+      discoveredTerms: terms
+    };
+  }
+  /**
+   * Resolve a sort name to its sort ID by listing the tenant's sorts.
+   *
+   * @internal
+   */
+  async resolveSortName(sortName) {
+    const response = await this.sortsApi.listSorts(this.tenantId);
+    const sorts = response.data.sorts;
+    const match = sorts.find((s) => s.name === sortName);
+    if (!match) {
+      const available = sorts.slice(0, 10).map((s) => s.name).join(", ");
+      throw new Error(
+        `Sort '${sortName}' not found. Available sorts: ${available}${sorts.length > 10 ? "..." : ""}`
+      );
+    }
+    return match.id;
+  }
+  /**
+   * Clean up temporary sort and rule artifacts (best-effort).
+   *
+   * @internal
+   */
+  async cleanupArtifacts(ruleTermId, sortId) {
+    const promises = [];
+    if (ruleTermId) {
+      promises.push(
+        this.termsApi.deleteTerm(ruleTermId).catch(() => {
+        })
+      );
+    }
+    if (sortId) {
+      promises.push(
+        this.sortsApi.deleteSort(sortId).catch(() => {
+        })
+      );
+    }
+    await Promise.all(promises);
+  }
+};
+function generateShortId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `${timestamp}_${random}`;
+}
+function extractStringValue(features, featureName) {
+  const value = features[featureName];
+  if (!value) return null;
+  if (value.type === "String") return value.value;
+  return null;
+}
+function extractNumericValue(features, featureName) {
+  const value = features[featureName];
+  if (!value) return null;
+  if (value.type === "Integer") return value.value;
+  if (value.type === "Real") return value.value;
+  return null;
+}
+
 // src/client.ts
 var ReasoningLayerClient = class {
   /** Sort (type hierarchy) operations. */
@@ -12634,6 +13181,8 @@ var ReasoningLayerClient = class {
   generation;
   /** Ontology RAG operations (embedding search + feature unification). */
   rag;
+  /** Linear program optimization (CLP(Q) simplex solver via backward chaining). */
+  optimize;
   /**
    * Create a new ReasoningLayerClient.
    *
@@ -12736,6 +13285,7 @@ var ReasoningLayerClient = class {
     this.ontology = new OntologyClient(generatedOntology);
     this.generation = new GenerationClient(generatedGeneration);
     this.rag = new RagClient(generatedRag);
+    this.optimize = new OptimizeClient(generatedInference, generatedSorts, generatedQuery, generatedTerms, resolved.tenantId);
   }
 };
 
@@ -13610,6 +14160,7 @@ exports.ConstraintViolationError = ConstraintViolationError;
 exports.FeatureInput = FeatureInput;
 exports.FuzzyShape = FuzzyShape;
 exports.InternalServerError = InternalServerError;
+exports.LP = LP;
 exports.NetworkError = NetworkError;
 exports.NotFoundError = NotFoundError;
 exports.RateLimitError = RateLimitError;