@kortexya/reasoninglayer 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -109,7 +109,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
109
109
  * This is the single source of truth for the version constant.
110
110
  * The `scripts/release.sh` script updates this value alongside `package.json`.
111
111
  */
112
- declare const SDK_VERSION = "1.2.0";
112
+ declare const SDK_VERSION = "1.3.0";
113
113
  /**
114
114
  * Authentication mode for the SDK.
115
115
  *
@@ -2058,6 +2058,55 @@ interface BulkRejectRequest$1 {
2058
2058
  */
2059
2059
  reviewed_by: string;
2060
2060
  }
2061
+ /**
2062
+ * Request body for bulk-retract: list of term ids to retract.
2063
+ *
2064
+ * Phase 2 v2 entry point for retraction. The supervisor downstream
2065
+ * BFS-retracts every dependent derived fact through
2066
+ * [`DerivedFactsRepository::find_dependents`](osfkb_domain::ports::DerivedFactsRepository::find_dependents)
2067
+ * + [`DerivedFactsRepository::decrement_proof_count`](osfkb_domain::ports::DerivedFactsRepository::decrement_proof_count).
2068
+ *
2069
+ * # Tenant Context
2070
+ * The tenant is determined from the `X-Tenant-Id` header. The
2071
+ * `term_ids` are resolved against that tenant's working memory only.
2072
+ */
2073
+ interface BulkRetractTermsRequest {
2074
+ /**
2075
+ * Identifiers of the terms to remove from the working memory.
2076
+ * Phase 2 supervisor downstream BFS-retracts every dependent
2077
+ * derived fact through `find_dependents` + `decrement_proof_count`.
2078
+ */
2079
+ term_ids: string[];
2080
+ }
2081
+ /**
2082
+ * Response from bulk term retraction.
2083
+ *
2084
+ * Mirrors [`BulkAddTermsResponse`] with retraction-specific semantics.
2085
+ * The endpoint is idempotent: term ids that do not exist in the
2086
+ * working memory are silently skipped (symmetric with how
2087
+ * `bulk_add_terms` ignores duplicate ids when an explicit `id` is
2088
+ * supplied for a term that already exists).
2089
+ */
2090
+ interface BulkRetractTermsResponse {
2091
+ /**
2092
+ * Processing time including PG removal + supervisor enqueue.
2093
+ * @min 0
2094
+ */
2095
+ processing_time_ms: number;
2096
+ /**
2097
+ * The subset of `term_ids` actually removed (those that existed).
2098
+ * Order matches the input order, restricted to the ids that were
2099
+ * present in the working memory.
2100
+ */
2101
+ removed_term_ids: string[];
2102
+ /**
2103
+ * Number of terms successfully removed (those not present in the
2104
+ * store are silently skipped — symmetric with `bulk_add_terms`'s
2105
+ * idempotency).
2106
+ * @min 0
2107
+ */
2108
+ terms_removed: number;
2109
+ }
2061
2110
  /** Response from bulk review actions */
2062
2111
  interface BulkReviewResponse {
2063
2112
  /** Review IDs that failed with reasons */
@@ -10585,6 +10634,37 @@ interface MatchedEntityDto$1 {
10585
10634
  */
10586
10635
  term_id: string;
10587
10636
  }
10637
+ /**
10638
+ * Snapshot of the per-tenant Phase 2 materialization sentinel for the
10639
+ * status endpoint.
10640
+ */
10641
+ interface MaterializationStateSnapshot {
10642
+ /**
10643
+ * Tenant `derived_facts` count when the sentinel was written.
10644
+ * @format int64
10645
+ * @min 0
10646
+ */
10647
+ derived_count_at_bootstrap: number;
10648
+ /**
10649
+ * Tenant `terms` count when the sentinel was written.
10650
+ * @format int64
10651
+ * @min 0
10652
+ */
10653
+ fact_count_at_bootstrap: number;
10654
+ /**
10655
+ * Wall-clock instant of the most recent rebuild handler call,
10656
+ * in Unix milliseconds.
10657
+ * @format int64
10658
+ * @min 0
10659
+ */
10660
+ last_bootstrap_at_ms: number;
10661
+ /**
10662
+ * Supervisor LSN observed at the moment the sentinel was written.
10663
+ * @format int64
10664
+ * @min 0
10665
+ */
10666
+ last_bootstrap_lsn: number;
10667
+ }
10588
10668
  /** Summary of materialization results. */
10589
10669
  interface MaterializationSummaryDto$1 {
10590
10670
  /**
@@ -13026,6 +13106,27 @@ interface ReExtractResponse {
13026
13106
  */
13027
13107
  pending_review_count: number;
13028
13108
  }
13109
+ /** Response payload for `POST /api/v1/admin/derived-facts/rebuild/{tenant_id}`. */
13110
+ interface RebuildDerivedFactsResponse {
13111
+ /**
13112
+ * Per-tenant materialization LSN at the moment the response was
13113
+ * produced. Read-side caches consult this value to know whether
13114
+ * they have observed every successfully applied event.
13115
+ * @format int64
13116
+ * @min 0
13117
+ */
13118
+ materialization_lsn: number;
13119
+ /**
13120
+ * Number of rows truncated from `derived_facts` for this tenant.
13121
+ * @min 0
13122
+ */
13123
+ removed: number;
13124
+ /**
13125
+ * Number of `BootstrapRule` events queued to the supervisor.
13126
+ * @min 0
13127
+ */
13128
+ rules_queued: number;
13129
+ }
13029
13130
  /** Request to recall similar episodes. */
13030
13131
  interface RecallEpisodesRequest$1 {
13031
13132
  /**
@@ -14744,6 +14845,43 @@ type SearchResponse = {
14744
14845
  */
14745
14846
  variables: Record<string, VariableFeasibilityDto$1>;
14746
14847
  };
14848
+ /**
14849
+ * PG-direct name search across the tenant's sorts. Used by the
14850
+ * viewer when the in-memory hierarchy returns 0 hits because the
14851
+ * user is exploring a million-scale tenant where most sorts aren't
14852
+ * hydrated. Returns `{matches: [{id, name, depth}]}` ordered by
14853
+ * exact-match-first, then prefix, then by name length.
14854
+ * One row of [`SearchSortsResponse::matches`] — a single matching sort.
14855
+ */
14856
+ interface SearchSortsMatch {
14857
+ /**
14858
+ * Hierarchy depth — `0` is a root sort. Always populated: the
14859
+ * upstream port (`SortVisualizationPort::search_sorts_by_name`)
14860
+ * returns an `i32` directly, with no nullable code path.
14861
+ * @format int32
14862
+ */
14863
+ depth: number;
14864
+ /**
14865
+ * Sort identifier (UUID).
14866
+ * @format uuid
14867
+ */
14868
+ id: string;
14869
+ /** Sort name as stored in PG. */
14870
+ name: string;
14871
+ }
14872
+ /** Response body for `GET /api/v1/sorts/search`. */
14873
+ interface SearchSortsResponse {
14874
+ /**
14875
+ * Number of returned matches (≤ requested limit, ≤ 100).
14876
+ * @min 0
14877
+ */
14878
+ count: number;
14879
+ /**
14880
+ * Matching sorts, ordered exact-match-first, then prefix, then by
14881
+ * shortest name.
14882
+ */
14883
+ matches: SearchSortsMatch[];
14884
+ }
14747
14885
  /**
14748
14886
  * Search statistics collected during a search operation.
14749
14887
  *
@@ -16209,6 +16347,117 @@ interface SummaryResponse$1 {
16209
16347
  ts_first?: string | null;
16210
16348
  ts_last?: string | null;
16211
16349
  }
16350
+ /**
16351
+ * Snapshot of the most recent handler error observed by the
16352
+ * supervisor's metrics, surfaced through the status endpoint.
16353
+ */
16354
+ interface SupervisorErrorSnapshot {
16355
+ /**
16356
+ * Unix-millisecond timestamp at which the failure was recorded.
16357
+ * @format int64
16358
+ * @min 0
16359
+ */
16360
+ at_ms: number;
16361
+ /** Truncated error message (≤ 512 chars). */
16362
+ message: string;
16363
+ }
16364
+ /**
16365
+ * Response payload for
16366
+ * `GET /api/v1/admin/derived-facts/status/{tenant_id}`.
16367
+ *
16368
+ * Aggregates per-tenant supervisor health (event counters, last
16369
+ * error, materialization LSN, queue depth approximation) and
16370
+ * rebuild-state (sentinel snapshot, lock-held hint).
16371
+ */
16372
+ interface SupervisorStatusResponse {
16373
+ /**
16374
+ * Total `derived_facts` rows for this tenant, queried at
16375
+ * response time. Operators compare this against
16376
+ * `materialization_state.derived_count_at_bootstrap` to estimate
16377
+ * derivation growth since the last rebuild.
16378
+ * @min 0
16379
+ */
16380
+ derived_facts_count: number;
16381
+ /**
16382
+ * Cumulative count of events whose handler returned `Err(_)`.
16383
+ * @format int64
16384
+ * @min 0
16385
+ */
16386
+ events_failed: number;
16387
+ /**
16388
+ * Events currently inside the handler closure.
16389
+ * @min 0
16390
+ */
16391
+ events_in_flight: number;
16392
+ /**
16393
+ * Cumulative count of events whose handler returned `Ok(())`.
16394
+ * @format int64
16395
+ * @min 0
16396
+ */
16397
+ events_processed: number;
16398
+ /**
16399
+ * Cumulative count of events accepted by `submit`.
16400
+ * @format int64
16401
+ * @min 0
16402
+ */
16403
+ events_submitted: number;
16404
+ /**
16405
+ * Sum of `elapsed_ms` across all handler invocations.
16406
+ * @format int64
16407
+ * @min 0
16408
+ */
16409
+ handler_millis_total: number;
16410
+ /**
16411
+ * Unix-millisecond timestamp of the most recent handler return.
16412
+ * @format int64
16413
+ * @min 0
16414
+ */
16415
+ last_complete_ms: number;
16416
+ /** Most recently observed handler error, if any. */
16417
+ last_error?: null | SupervisorErrorSnapshot;
16418
+ /**
16419
+ * Unix-millisecond timestamp of the most recent `submit` call.
16420
+ * @format int64
16421
+ * @min 0
16422
+ */
16423
+ last_submit_ms: number;
16424
+ /**
16425
+ * Per-tenant materialization LSN as of the response. Read-side
16426
+ * caches keyed on this value compare against it to detect new
16427
+ * derivations.
16428
+ * @format int64
16429
+ * @min 0
16430
+ */
16431
+ materialization_lsn: number;
16432
+ /**
16433
+ * Per-tenant Phase 2 materialization sentinel, or `None` if the
16434
+ * tenant has never been rebuilt.
16435
+ */
16436
+ materialization_state?: null | MaterializationStateSnapshot;
16437
+ /**
16438
+ * Approximate channel depth: `submitted − processed − failed −
16439
+ * in_flight`. Saturates at zero on the rare race where a handler
16440
+ * returned between two field reads.
16441
+ * @min 0
16442
+ */
16443
+ queue_depth_approx: number;
16444
+ /**
16445
+ * **Racy hint**: `true` if the per-tenant rebuild mutex is
16446
+ * currently held. Computed via `try_lock()` and can briefly
16447
+ * disagree with the actual lock state (the lock may drop
16448
+ * between the probe and the read), so operators must not treat
16449
+ * this as authoritative. Use it as a "rebuild appears to be in
16450
+ * flight" signal only.
16451
+ */
16452
+ rebuild_in_flight: boolean;
16453
+ /**
16454
+ * `true` if a [`DataflowSupervisor`] has been spawned for this
16455
+ * tenant. `false` indicates the tenant has never had an event
16456
+ * submitted on its behalf and the metrics fields are returned
16457
+ * at their initial zero values.
16458
+ */
16459
+ supervisor_active: boolean;
16460
+ }
16212
16461
  /** Information about a suspended (incomplete) query */
16213
16462
  interface SuspendedQueryDto$1 {
16214
16463
  /**
@@ -18220,6 +18469,22 @@ declare class Sorts<SecurityDataType = unknown> {
18220
18469
  * @request POST:/api/v1/sorts/learned-similarities/reject
18221
18470
  */
18222
18471
  rejectLearnedSimilarity: (data: RejectLearnedSimilarityRequest$1, params?: RequestParams) => Promise<HttpResponse<RejectLearnedSimilarityResponse$1, any>>;
18472
+ /**
18473
+ * No description
18474
+ *
18475
+ * @tags sorts
18476
+ * @name SearchSortsByName
18477
+ * @request GET:/api/v1/sorts/search
18478
+ */
18479
+ searchSortsByName: (query: {
18480
+ /**
18481
+ * Max results (default 20, capped at 100)
18482
+ * @min 0
18483
+ */
18484
+ limit?: number;
18485
+ /** Search query (sort name substring) */
18486
+ q: string;
18487
+ }, params?: RequestParams) => Promise<HttpResponse<SearchSortsResponse, any>>;
18223
18488
  /**
18224
18489
  * @description Similarity is symmetric: ∼(s₁, s₂) = ∼(s₂, s₁) Degree must be in [0, 1] range.
18225
18490
  *
@@ -20825,6 +21090,16 @@ declare class Inference<SecurityDataType = unknown> {
20825
21090
  * @secure
20826
21091
  */
20827
21092
  bulkFuzzyProve: (data: BulkFuzzyProveRequest$1, params?: RequestParams) => Promise<HttpResponse<BulkFuzzyProveResponse$1, void>>;
21093
+ /**
21094
+ * @description Phase 2 v2 entry point for retraction: 1. Removes each term from PG + in-memory stores via [`HomoiconicTermService::remove_term`](osfkb_application::services::HomoiconicTermService::remove_term). 2. When `state.use_plan_engine` is on, submits a single [`DeltaEvent::Retract`](osfkb_application::services::dataflow::DeltaEvent::Retract) to the per-tenant supervisor so the Backward/Forward backward chase decrements every dependent derived fact's `proof_count` (and deletes those whose count reaches zero). Symmetric to [`bulk_add_terms`]; idempotent (term ids absent from the working memory are silently skipped — same shape as [`delete_term`] returning 404, except in the bulk path the missing ids simply don't appear in `removed_term_ids`). Best-effort supervisor enqueue: a supervisor failure does NOT fail the 2xx response — the persist path has succeeded and a future bootstrap can recover any missed retraction. # Mid-batch error handling If `remove_term` fails for a term partway through the batch, the handler **stops accumulating successes**, runs cache invalidation for the prefix that did succeed, submits a single [`DeltaEvent::Retract`](osfkb_application::services::dataflow::DeltaEvent::Retract) covering that prefix, and **then** surfaces the error. This keeps the supervisor and the in-memory caches in sync with the actual store state — a leaked Retract event would orphan derived facts whose only antecedent is now removed, which is a critical correctness violation. # Authorization Requires `X-Tenant-Id` header. The `term_ids` are resolved against that tenant's working memory only — cross-tenant retraction is impossible by construction (the per-tenant `HomoiconicTermService` only sees its own tenant's terms).
21095
+ *
21096
+ * @tags inference
21097
+ * @name BulkRetractTerms
21098
+ * @summary Bulk-retract terms from the working memory.
21099
+ * @request POST:/api/v1/inference/facts/bulk-retract
21100
+ * @secure
21101
+ */
21102
+ bulkRetractTerms: (data: BulkRetractTermsRequest, params?: RequestParams) => Promise<HttpResponse<BulkRetractTermsResponse, any>>;
20828
21103
  /**
20829
21104
  * @description # DEPRECATED This endpoint is deprecated. Use `DELETE /api/v1/terms/{term_id}` for individual terms. # TRUE HOMOICONIC API # Authorization Requires X-Tenant-Id header.
20830
21105
  *
@@ -20877,7 +21152,7 @@ declare class Inference<SecurityDataType = unknown> {
20877
21152
  * @request POST:/api/v1/inference/forward-chain
20878
21153
  * @secure
20879
21154
  */
20880
- forwardChain: (data: ForwardChainRequest$1, params?: RequestParams) => Promise<HttpResponse<ForwardChainResponse$1, any>>;
21155
+ forwardChain: (data: ForwardChainRequest$1, params?: RequestParams) => Promise<HttpResponse<ForwardChainResponse$1, void>>;
20881
21156
  /**
20882
21157
  * @description Runs forward chaining with probabilistic provenance tags. Each derived fact carries a confidence value computed from the provenance semiring operations (noisy-or for disjunction, product for conjunction). This extends the standard forward chain endpoint by tracking how confidence propagates through rule application, enabling probabilistic reasoning over the knowledge base.
20883
21158
  *
@@ -39372,6 +39647,24 @@ declare class Admin<SecurityDataType = unknown> {
39372
39647
  * @request GET:/api/v1/admin/tenants
39373
39648
  */
39374
39649
  listTenants: (params?: RequestParams) => Promise<HttpResponse<ListTenantsResponse$1, any>>;
39650
+ /**
39651
+ * @description Truncates the derived_facts table for the given tenant and queues a BootstrapAll event covering every analyzed rule. Asynchronous: returns the queue depth and current materialization LSN, not the final state. Concurrent rebuilds for the same tenant are rejected with 409 (per-tenant mutex). Full operational runbook (prerequisites, timings, monitoring, failure recovery, known limitations) lives in .claude/SUB_MS_FORWARD_CHAINING_STATUS.md, section 'Operator runbook — derived-facts rebuild'.
39652
+ *
39653
+ * @tags admin
39654
+ * @name RebuildDerivedFacts
39655
+ * @summary Rebuild derived facts for a tenant
39656
+ * @request POST:/api/v1/admin/derived-facts/rebuild/{tenant_id}
39657
+ */
39658
+ rebuildDerivedFacts: (tenantId: string, params?: RequestParams) => Promise<HttpResponse<RebuildDerivedFactsResponse, void>>;
39659
+ /**
39660
+ * @description Returns event-processing counters (submitted/processed/failed/in-flight), the materialization LSN, the last handler error (if any, truncated to 512 chars), the per-tenant materialization sentinel, the current derived-facts row count, and a racy hint about whether a rebuild is in flight. Intended for operator dashboards; the supervisor itself does not depend on this endpoint.
39661
+ *
39662
+ * @tags admin
39663
+ * @name SupervisorStatus
39664
+ * @summary Get per-tenant supervisor + materialization status
39665
+ * @request GET:/api/v1/admin/derived-facts/status/{tenant_id}
39666
+ */
39667
+ supervisorStatus: (tenantId: string, params?: RequestParams) => Promise<HttpResponse<SupervisorStatusResponse, void>>;
39375
39668
  }
39376
39669
 
39377
39670
  /**
@@ -44512,6 +44805,236 @@ declare const LP: {
44512
44805
  readonly bounds: (min?: number, max?: number) => VariableBounds;
44513
44806
  };
44514
44807
 
44808
+ /**
44809
+ * Builder namespace for network-flow constraint problems on the
44810
+ * `flow_constraint` family of meta-sorts.
44811
+ *
44812
+ * @remarks
44813
+ * Produces a list of psi-terms that encode an edge set, an objective
44814
+ * (max flow / min cut / min-cost-max-flow / classify edges), and a
44815
+ * `flow_solve_constraint` trigger. The returned `constraints` array
44816
+ * can be used directly as the body of a clause goal, the antecedents
44817
+ * of an inference rule, or spliced alongside other CLP constraints
44818
+ * (e.g., CLP(FD)) inside one query.
44819
+ *
44820
+ * Node identity is encoded via auto-generated psi-variables: every
44821
+ * unique node name maps to one variable (`?N_<sanitized_name>`) so
44822
+ * the backend chainer sees the same TermId every time the same name
44823
+ * appears.
44824
+ *
44825
+ * @example
44826
+ * ```typescript
44827
+ * import { Flow, psi } from '@kortexya/reasoninglayer';
44828
+ *
44829
+ * const { constraints, vars } = Flow.maxFlow({
44830
+ * source: 's',
44831
+ * sink: 't',
44832
+ * edges: [
44833
+ * ['s', 'a', 10],
44834
+ * ['s', 'b', 5],
44835
+ * ['a', 'b', 15],
44836
+ * ['a', 't', 10],
44837
+ * ['b', 't', 10],
44838
+ * ],
44839
+ * });
44840
+ *
44841
+ * const response = await client.inference.backwardChain({
44842
+ * goal: psi('clause', { antecedents: constraints }),
44843
+ * max_solutions: 1,
44844
+ * });
44845
+ * // Read `vars.flowValue` from response.solutions[0].substitution.
44846
+ * ```
44847
+ */
44848
+ /** Logical node identifier — any string. Used to coordinate identity
44849
+ * across `src` / `dst` / `source` / `sink` references in one problem. */
44850
+ type FlowNode = string;
44851
+ /** A flow edge declaration. Tuple form `[from, to, cap]` or
44852
+ * `[from, to, cap, options]`, or an explicit object form. */
44853
+ type FlowEdgeInput = [FlowNode, FlowNode, number] | [FlowNode, FlowNode, number, FlowEdgeOptions] | (FlowEdgeOptions & {
44854
+ from: FlowNode;
44855
+ to: FlowNode;
44856
+ cap: number;
44857
+ });
44858
+ /** Optional per-edge attributes. */
44859
+ interface FlowEdgeOptions {
44860
+ /** Output variable name (e.g., `?F_sa`). If omitted, an auto-generated
44861
+ * name is used and returned in `vars.edgeFlows`. */
44862
+ flow?: string;
44863
+ /** Per-unit-flow cost. Defaults to 0. Only consulted by
44864
+ * `Flow.minCostMaxFlow`. */
44865
+ cost?: number;
44866
+ /** Optional edge label. Surfaces in min-cut / classification outputs. */
44867
+ label?: string;
44868
+ }
44869
+ /** Output variables surfaced by `Flow.maxFlow`. */
44870
+ interface MaxFlowVars {
44871
+ /** Variable name bound to the total flow source → sink. */
44872
+ flowValue: string;
44873
+ /** Per-edge output variables in declaration order. */
44874
+ edgeFlows: Array<{
44875
+ from: FlowNode;
44876
+ to: FlowNode;
44877
+ var: string;
44878
+ }>;
44879
+ }
44880
+ /** Output variables surfaced by `Flow.minCut`. */
44881
+ interface MinCutVars {
44882
+ cutValue: string;
44883
+ cutEdges: string;
44884
+ sourceSide: string;
44885
+ sinkSide: string;
44886
+ edgeFlows: Array<{
44887
+ from: FlowNode;
44888
+ to: FlowNode;
44889
+ var: string;
44890
+ }>;
44891
+ }
44892
+ /** Output variables surfaced by `Flow.minCostMaxFlow`. */
44893
+ interface MinCostMaxFlowVars {
44894
+ flowValue: string;
44895
+ totalCost: string;
44896
+ edgeFlows: Array<{
44897
+ from: FlowNode;
44898
+ to: FlowNode;
44899
+ var: string;
44900
+ }>;
44901
+ }
44902
+ /** Output variables surfaced by `Flow.classifyEdges`. */
44903
+ interface ClassifyEdgesVars {
44904
+ classifications: string;
44905
+ edgeFlows: Array<{
44906
+ from: FlowNode;
44907
+ to: FlowNode;
44908
+ var: string;
44909
+ }>;
44910
+ }
44911
+ /** Result returned by each `Flow.*` constructor: the constraint
44912
+ * psi-terms plus the output variable names needed to read results. */
44913
+ interface FlowProblem<V> {
44914
+ constraints: TermInputArg[];
44915
+ vars: V;
44916
+ }
44917
+ /** Common inputs accepted by every objective constructor. */
44918
+ interface FlowProblemInputBase {
44919
+ /** Source node identifier. */
44920
+ source: FlowNode;
44921
+ /** Sink node identifier. */
44922
+ sink: FlowNode;
44923
+ /** Edge declarations (tuple or object form). */
44924
+ edges: readonly FlowEdgeInput[];
44925
+ }
44926
+ /** Inputs for `Flow.maxFlow`. */
44927
+ interface MaxFlowInput extends FlowProblemInputBase {
44928
+ /** Optional explicit name for the `flow_value` output variable. */
44929
+ flowValue?: string;
44930
+ }
44931
+ /** Inputs for `Flow.minCut`. */
44932
+ interface MinCutInput extends FlowProblemInputBase {
44933
+ cutValue?: string;
44934
+ cutEdges?: string;
44935
+ sourceSide?: string;
44936
+ sinkSide?: string;
44937
+ }
44938
+ /** Inputs for `Flow.minCostMaxFlow`. */
44939
+ interface MinCostMaxFlowInput extends FlowProblemInputBase {
44940
+ flowValue?: string;
44941
+ totalCost?: string;
44942
+ }
44943
+ /** Inputs for `Flow.classifyEdges`. */
44944
+ interface ClassifyEdgesInput extends FlowProblemInputBase {
44945
+ classifications?: string;
44946
+ /** When true, use min-cost-max-flow as the underlying solution
44947
+ * space (requires edges to carry `cost`). */
44948
+ optimal?: boolean;
44949
+ }
44950
+ declare const Flow: {
44951
+ /**
44952
+ * Build a max-flow problem.
44953
+ *
44954
+ * Emits one `flow_edge_constraint` per edge, one
44955
+ * `flow_max_constraint` with the requested output binding, and a
44956
+ * `flow_solve_constraint` trigger. Returns the constraint terms
44957
+ * plus the names of every output variable.
44958
+ */
44959
+ maxFlow(input: MaxFlowInput): FlowProblem<MaxFlowVars>;
44960
+ /**
44961
+ * Build a min-cut problem.
44962
+ *
44963
+ * Emits `flow_min_cut_constraint` and binds `cut_value`,
44964
+ * `cut_edges`, `source_side`, `sink_side` to the requested
44965
+ * variable names (auto-generated when omitted).
44966
+ */
44967
+ minCut(input: MinCutInput): FlowProblem<MinCutVars>;
44968
+ /**
44969
+ * Build a min-cost-max-flow problem. Per-edge `cost` is required
44970
+ * for the optimisation to be meaningful (defaults to 0 if absent).
44971
+ */
44972
+ minCostMaxFlow(input: MinCostMaxFlowInput): FlowProblem<MinCostMaxFlowVars>;
44973
+ /**
44974
+ * Build a Dulmage-Mendelsohn edge-classification problem.
44975
+ *
44976
+ * Each edge is classified as `"always"`, `"never"`, or
44977
+ * `"sometimes"` used across the space of all max flows (or all
44978
+ * min-cost max flows when `optimal: true`).
44979
+ */
44980
+ classifyEdges(input: ClassifyEdgesInput): FlowProblem<ClassifyEdgesVars>;
44981
+ /** Low-level: build a single `flow_edge_constraint` psi-term. */
44982
+ edge(from: FlowNode, to: FlowNode, cap: number, options?: FlowEdgeOptions): TermInputArg;
44983
+ /** Low-level: build a single `flow_solve_constraint` psi-term. */
44984
+ solve(source: FlowNode, sink: FlowNode): TermInputArg;
44985
+ /**
44986
+ * Low-level: build a single `flow_max_constraint` psi-term.
44987
+ *
44988
+ * @example
44989
+ * ```typescript
44990
+ * const constraints = [
44991
+ * Flow.edge('s', 'a', 10),
44992
+ * Flow.edge('a', 't', 10),
44993
+ * Flow.maxObjective({ source: 's', sink: 't', flowValue: '?V' }),
44994
+ * Flow.solve('s', 't'),
44995
+ * ];
44996
+ * ```
44997
+ */
44998
+ maxObjective(opts: {
44999
+ source: FlowNode;
45000
+ sink: FlowNode;
45001
+ flowValue: string;
45002
+ }): TermInputArg;
45003
+ /** Low-level: build a single `flow_min_cut_constraint` psi-term. */
45004
+ minCutObjective(opts: {
45005
+ source: FlowNode;
45006
+ sink: FlowNode;
45007
+ cutValue: string;
45008
+ cutEdges: string;
45009
+ sourceSide: string;
45010
+ sinkSide: string;
45011
+ }): TermInputArg;
45012
+ /** Low-level: build a single `flow_min_cost_max_flow_constraint` psi-term. */
45013
+ minCostMaxFlowObjective(opts: {
45014
+ source: FlowNode;
45015
+ sink: FlowNode;
45016
+ flowValue: string;
45017
+ totalCost: string;
45018
+ }): TermInputArg;
45019
+ /** Low-level: build a single `flow_classify_edges_constraint` psi-term. */
45020
+ classifyEdgesObjective(opts: {
45021
+ source: FlowNode;
45022
+ sink: FlowNode;
45023
+ classifications: string;
45024
+ optimal?: boolean;
45025
+ }): TermInputArg;
45026
+ /**
45027
+ * Low-level: get the node-variable reference used to identify a
45028
+ * node name in goals built by this builder. Exposed so callers
45029
+ * composing constraints by hand can refer to the same logical node
45030
+ * the high-level helpers would produce — e.g., to add a feature
45031
+ * test on the same node term inside the same goal.
45032
+ */
45033
+ node(name: FlowNode): {
45034
+ name: string;
45035
+ };
45036
+ };
45037
+
44515
45038
  /**
44516
45039
  * Check if a string matches UUID v4 format.
44517
45040
  *
@@ -44696,4 +45219,4 @@ declare function toUntaggedFeatures(features: PlainFeatureMap): Record<string, F
44696
45219
  */
44697
45220
  declare function toTermInputDto(input: PsiTermInput | TermInputDto): TermInputDto;
44698
45221
 
44699
- export { ANY_ROLE, actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, type AuthConfig, 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, compliance as Compliance, 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, flowNetworks as FlowNetworks, 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, operations as Operations, 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, scheduling as Scheduling, 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 };
45222
+ export { ANY_ROLE, actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, type AuthConfig, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClassifyEdgesInput, type ClassifyEdgesVars, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, compliance as Compliance, 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, Flow, type FlowProblem as FlowBuilderProblem, type FlowEdgeInput, type FlowEdgeOptions, flowNetworks as FlowNetworks, type FlowNode, type FlowProblemInputBase, 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, type MaxFlowInput, type MaxFlowVars, type MinCostMaxFlowInput, type MinCostMaxFlowVars, type MinCutInput, type MinCutVars, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, operations as Operations, 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, scheduling as Scheduling, 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 };