@jsonfirst/sdk 1.3.0 → 1.4.1
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 +53 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -71,6 +71,50 @@ console.log(result.jdons[0].object); // { type: "order", ... }
|
|
|
71
71
|
|
|
72
72
|
---
|
|
73
73
|
|
|
74
|
+
## Recoverable Agents — Full Pipeline
|
|
75
|
+
|
|
76
|
+
JSONFIRST closes the full loop: `intent → validation → snapshot → execution → receipt → rollback`
|
|
77
|
+
|
|
78
|
+
### 1. Snapshot (before execution)
|
|
79
|
+
|
|
80
|
+
```javascript
|
|
81
|
+
const snap = await client.snapshot({
|
|
82
|
+
jdon_id: 'jdon_abc123',
|
|
83
|
+
description: 'before delete user 1234',
|
|
84
|
+
state: { user_id: '1234', status: 'active', balance: 500 },
|
|
85
|
+
rollback_webhook: 'https://yourapp.com/webhooks/rollback' // optional
|
|
86
|
+
});
|
|
87
|
+
// → { snapshot_id: 'uuid', status: 'AVAILABLE' }
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 2. Receipt (after execution — verify intent match)
|
|
91
|
+
|
|
92
|
+
```javascript
|
|
93
|
+
const receipt = await client.receipt({
|
|
94
|
+
jdon_id: 'jdon_abc123',
|
|
95
|
+
output_summary: 'User 1234 deleted from production database',
|
|
96
|
+
mode: 'PRODUCTION_LOCK',
|
|
97
|
+
original_intent: result // the JSONFIRST parse output
|
|
98
|
+
});
|
|
99
|
+
// → { intent_match_score: 0.95, verification_status: 'VERIFIED', drift_detected: false }
|
|
100
|
+
// or → { verification_status: 'INTENT_MISMATCH', flags: ['ROLLBACK_SUGGESTED'] }
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 3. Rollback (if drift detected)
|
|
104
|
+
|
|
105
|
+
```javascript
|
|
106
|
+
if (receipt.receipt.flags.includes('ROLLBACK_SUGGESTED')) {
|
|
107
|
+
const rb = await client.rollback({
|
|
108
|
+
snapshot_id: snap.snapshot_id,
|
|
109
|
+
reason: 'INTENT_MISMATCH_DETECTED'
|
|
110
|
+
});
|
|
111
|
+
// → { status: 'ROLLED_BACK', restored_state: { user_id: '1234', ... } }
|
|
112
|
+
// Webhook fired automatically if configured
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
74
118
|
## Governance Modes
|
|
75
119
|
|
|
76
120
|
22 modes ship with this SDK. Pass `execution_mode` to `parse()` to activate.
|
|
@@ -110,6 +154,15 @@ console.log(JsonFirst.MODE_IDS); // all 22 mode IDs
|
|
|
110
154
|
|
|
111
155
|
---
|
|
112
156
|
|
|
157
|
+
## Works with
|
|
158
|
+
|
|
159
|
+
- **LangChain** — use JSONFIRST to parse user inputs before passing structured intents to your chains
|
|
160
|
+
- **LlamaIndex** — feed validated JDON objects as structured queries to your indexes and agents
|
|
161
|
+
- **CrewAI** — turn natural language tasks into executable JDONs your crew agents can act on reliably
|
|
162
|
+
- **Any LLM** — framework-agnostic, works with OpenAI, Anthropic, Gemini, Mistral, and any model
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
113
166
|
## Links
|
|
114
167
|
|
|
115
168
|
- [Get your API key](https://jsonfirst.com/developers)
|