@supersemantics/vsl-core 0.2.3 → 0.2.5
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/README.md +62 -0
- package/dist/cjs/ledger.js +2 -2
- package/dist/ledger.d.ts +2 -2
- package/dist/ledger.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,6 +17,68 @@ runtime alongside them.
|
|
|
17
17
|
- A byte-for-byte transliteration. A handful of things are deliberately adapted to TypeScript/Node rather than translated line-by-line -- see "Where this diverges from `vsl-core`" below. Every departure is a conscious design decision, documented in code and here, not an oversight.
|
|
18
18
|
- A framework adapter. This package ships no LangGraph.js, LangChain.js, or other framework integration. Those belong in separate `@supersemantics/vsl-<framework>` packages, the same separation `vsl-core`'s Python ecosystem already follows (`vsl-langgraph`, `vsl-langchain`, `vsl-maf`).
|
|
19
19
|
|
|
20
|
+
## Quickstart: gate a tool call in 5 lines
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
npm install @supersemantics/vsl-core
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Your agent has a tool, say `issueRefund`. You want a rule checked **before** the tool runs, and the
|
|
27
|
+
call stopped if the rule fails. That check is a gate:
|
|
28
|
+
|
|
29
|
+
```javascript
|
|
30
|
+
import {
|
|
31
|
+
AssuranceBasis, F2Modification, Invariant, InvariantViolation, PlainJsReferenceAdapter,
|
|
32
|
+
} from "@supersemantics/vsl-core";
|
|
33
|
+
|
|
34
|
+
const withinCap = async (args) => args.amount <= 500;
|
|
35
|
+
const cap = new Invariant({ name: "refund-cap", description: "Refunds of $500 or less.", rule: withinCap,
|
|
36
|
+
assuranceBasis: new AssuranceBasis(true, F2Modification.NONE) });
|
|
37
|
+
const gate = new PlainJsReferenceAdapter().compileInvariant(cap);
|
|
38
|
+
|
|
39
|
+
async function refund(args) {
|
|
40
|
+
await gate(args); // throws InvariantViolation if the rule fails
|
|
41
|
+
return issueRefund(args); // only reached when it holds
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
What each line does:
|
|
46
|
+
|
|
47
|
+
- `withinCap` is the rule: plain code that answers yes or no for this one call.
|
|
48
|
+
- `Invariant` gives the rule a name and says how strong the check is. It runs before the action
|
|
49
|
+
(`true`: F1) and changes nothing about what a model produces (`F2Modification.NONE`). That makes its
|
|
50
|
+
assurance level LOW: it blocks, but it doesn't steer a model. `vsl-core`'s README explains
|
|
51
|
+
[F1/F2](https://github.com/supersemantics/VSL-Core#the-f1f2-assurance-distinction-read-this-before-trusting-any-assurance-level).
|
|
52
|
+
- `compileInvariant` turns the rule into a gate: an async function that resolves when the rule holds
|
|
53
|
+
and throws when it doesn't. `PlainJsReferenceAdapter` is the adapter for plain JavaScript, with no
|
|
54
|
+
agent framework underneath.
|
|
55
|
+
- `await gate(args)` goes right before the tool. If it throws, the tool never runs.
|
|
56
|
+
|
|
57
|
+
`refund({ orderId: "A200", amount: 9000 })` throws `InvariantViolation` ("Invariant 'refund-cap'
|
|
58
|
+
violated") and no refund is issued. The whole file, ready to run, is
|
|
59
|
+
[`examples/quickstart.mjs`](https://github.com/supersemantics/VSL-Corejs/blob/HEAD/examples/quickstart.mjs).
|
|
60
|
+
|
|
61
|
+
**Keep a record of each decision.** The gate blocks on its own, but writes nothing down. To keep a
|
|
62
|
+
hash-chained record of every allow and deny, write it from the rule:
|
|
63
|
+
|
|
64
|
+
```javascript
|
|
65
|
+
import { VerbaLedger } from "@supersemantics/vsl-core";
|
|
66
|
+
|
|
67
|
+
const ledger = new VerbaLedger(); // in memory; new VerbaLedger(new JsonlLedgerStore("decisions.jsonl")) for a file
|
|
68
|
+
|
|
69
|
+
const withinCap = async (args) => {
|
|
70
|
+
const allowed = args.amount <= 500;
|
|
71
|
+
await ledger.writeGateDecision("refund-agent", "refund-cap", { allowed });
|
|
72
|
+
return allowed;
|
|
73
|
+
};
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`await ledger.verifyIntegrity()` returns `true` while no entry has been changed.
|
|
77
|
+
|
|
78
|
+
**Using LangGraph.js?** [`@supersemantics/vsl-langgraph`](https://github.com/supersemantics/VSL-Langgraphjs)
|
|
79
|
+
compiles the same `Invariant` into a graph node. For a complete agent to start from, see the
|
|
80
|
+
[LangGraph.js starter](https://github.com/supersemantics/supersemantics-VSL-Starters/tree/main/langgraph-js).
|
|
81
|
+
|
|
20
82
|
## Quick taste
|
|
21
83
|
|
|
22
84
|
```typescript
|
package/dist/cjs/ledger.js
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
* Port of vsl_core/ledger.py, with one deliberate design departure: the
|
|
6
6
|
* LedgerStore interface here is async (Promise/AsyncIterable-returning),
|
|
7
7
|
* where Python's is fully synchronous. This isn't a 1:1 translation
|
|
8
|
-
* choice -- it's forward-looking:
|
|
9
|
-
*
|
|
8
|
+
* choice -- it's forward-looking: any LedgerStore that does network or
|
|
9
|
+
* database I/O cannot be synchronous in JS (there is no synchronous
|
|
10
10
|
* fetch), so making every LedgerStore implementation async from the start
|
|
11
11
|
* -- including the in-memory/file ones below, even though neither strictly
|
|
12
12
|
* needs it -- keeps the interface uniform rather than breaking it later.
|
package/dist/ledger.d.ts
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
* Port of vsl_core/ledger.py, with one deliberate design departure: the
|
|
5
5
|
* LedgerStore interface here is async (Promise/AsyncIterable-returning),
|
|
6
6
|
* where Python's is fully synchronous. This isn't a 1:1 translation
|
|
7
|
-
* choice -- it's forward-looking:
|
|
8
|
-
*
|
|
7
|
+
* choice -- it's forward-looking: any LedgerStore that does network or
|
|
8
|
+
* database I/O cannot be synchronous in JS (there is no synchronous
|
|
9
9
|
* fetch), so making every LedgerStore implementation async from the start
|
|
10
10
|
* -- including the in-memory/file ones below, even though neither strictly
|
|
11
11
|
* needs it -- keeps the interface uniform rather than breaking it later.
|
package/dist/ledger.js
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
* Port of vsl_core/ledger.py, with one deliberate design departure: the
|
|
5
5
|
* LedgerStore interface here is async (Promise/AsyncIterable-returning),
|
|
6
6
|
* where Python's is fully synchronous. This isn't a 1:1 translation
|
|
7
|
-
* choice -- it's forward-looking:
|
|
8
|
-
*
|
|
7
|
+
* choice -- it's forward-looking: any LedgerStore that does network or
|
|
8
|
+
* database I/O cannot be synchronous in JS (there is no synchronous
|
|
9
9
|
* fetch), so making every LedgerStore implementation async from the start
|
|
10
10
|
* -- including the in-memory/file ones below, even though neither strictly
|
|
11
11
|
* needs it -- keeps the interface uniform rather than breaking it later.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@supersemantics/vsl-core",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.5",
|
|
4
4
|
"description": "Framework-agnostic and model-agnostic VSL (VERBA Specification Language) governance primitives -- TypeScript port of vsl-core.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|