@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.cjs +289 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +526 -3
- package/dist/index.d.ts +526 -3
- package/dist/index.js +289 -6
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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.
|
|
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,
|
|
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 };
|