@nika-open/nika 0.0.0-stage → 0.124.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/LICENSE +202 -0
- package/README.md +776 -2
- package/dist/bin/nika.js +450 -0
- package/dist/index.cjs +5921 -0
- package/dist/index.d.cts +1913 -0
- package/dist/index.d.ts +1913 -0
- package/dist/index.js +5865 -0
- package/docs/README.md +69 -0
- package/docs/architecture.md +163 -0
- package/docs/compile.md +486 -0
- package/docs/errors.md +154 -0
- package/docs/glossary.md +41 -0
- package/docs/http-api.md +396 -0
- package/docs/migrating-to-0.116.md +164 -0
- package/docs/receipts.md +156 -0
- package/docs/runs.md +670 -0
- package/docs/server.md +543 -0
- package/docs/testing.md +244 -0
- package/docs/upgrading-to-0.123.md +190 -0
- package/openapi.json +3067 -0
- package/package.json +92 -4
package/docs/compile.md
ADDED
|
@@ -0,0 +1,486 @@
|
|
|
1
|
+
# Compile: from an intention to a checked workflow
|
|
2
|
+
|
|
3
|
+
`nika.compile(request)` asks the engine for a candidate workflow and runs
|
|
4
|
+
nothing. The outcome is data: `ready`, `incomplete` and `refused` all resolve,
|
|
5
|
+
and only transport, protocol, compatibility and engine-stamped failures throw.
|
|
6
|
+
A ready candidate is ordinary `.nika` source; you write it to a file and
|
|
7
|
+
`run(path)` admits it again, exactly like any other workflow.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
compile(request) ──▶ outcome
|
|
11
|
+
ready ──────▶ write outcome.candidate ──▶ run(path) Check admits it again
|
|
12
|
+
incomplete ─▶ outcome.questions ──▶ nextCompileRequest(request, outcome, answers)
|
|
13
|
+
└──▶ compile(next request) ... (bounded: stop
|
|
14
|
+
when a round brings no new answer)
|
|
15
|
+
refused ────▶ outcome.diagnostics stop
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The SDK holds no compiler. Both doors print the engine's one machine document
|
|
19
|
+
(`nika-compile/src/wire.rs::outcome_document`); the SDK validates it, keeps the
|
|
20
|
+
engine's fields verbatim and adds only `ready`, the replay token of a kept
|
|
21
|
+
round (HTTP) and the CLI's own facts (local engine).
|
|
22
|
+
|
|
23
|
+
## Start here: no model, no key
|
|
24
|
+
|
|
25
|
+
Without a provider, compile resolves the exact skeleton names
|
|
26
|
+
`nika compile --list` shows (`hello` and `classify-and-route` among them) and
|
|
27
|
+
edits the constants of an existing workflow; other free text comes back
|
|
28
|
+
`incomplete` with its questions.
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { Nika } from '@nika-open/nika';
|
|
32
|
+
|
|
33
|
+
const nika = new Nika();
|
|
34
|
+
const candidate = await nika.compile({
|
|
35
|
+
intent: 'classify-and-route',
|
|
36
|
+
answers: { 'const.request': 'An outage affects support customers.' },
|
|
37
|
+
}, { timeoutMs: 15_000 });
|
|
38
|
+
|
|
39
|
+
// Every outcome is data: ready, incomplete and refused alike.
|
|
40
|
+
console.log(candidate.status, candidate.questions, candidate.diagnostics);
|
|
41
|
+
if (candidate.ready && candidate.candidate !== null) {
|
|
42
|
+
const edited = await nika.compile({
|
|
43
|
+
workflow: candidate.candidate,
|
|
44
|
+
change: { set_constant: { name: 'request', value: 'One customer is affected.' } },
|
|
45
|
+
});
|
|
46
|
+
console.log(edited.candidate);
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Measured on engine 0.123.0: the first call is `ready` at `compile_version` 1
|
|
51
|
+
with an `applied` diagnostic on `const.request`, and the edit is `ready` with
|
|
52
|
+
the new constant. An edit also accepts text, such as
|
|
53
|
+
`Set const.request to "One customer"`. A free intent such as
|
|
54
|
+
`'Every Monday at 9am summarize the support queue into ./digest.md'` comes
|
|
55
|
+
back `incomplete`, asking `model` (text), `trigger.timezone` (text),
|
|
56
|
+
`trigger.missed` and `trigger.overlap` (choices) and `trigger.ceiling`
|
|
57
|
+
(literal). The candidate is `.nika` source, never a run: write it to a file,
|
|
58
|
+
then `run(path)` admits it again like any other workflow.
|
|
59
|
+
|
|
60
|
+
**Watch a free intent become a ready candidate in two rounds, with no model call.**
|
|
61
|
+
|
|
62
|
+
<p align="center">
|
|
63
|
+
<picture>
|
|
64
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-compile.png">
|
|
65
|
+
<img src="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/gifs/sdk-compile.gif" alt="node author.mts with the intent Every morning, summarize ./inbox/*.md into ./digest.md prints round 1 incomplete · 1 required, 4 optional question(s), the required question model, and every morning is a trigger, not a task; answer model = mock/echo; round 2 ready · provider calls: none; trigger schedule · daily · requires_binding; check clean · exit 0 · kept as digest.nika. Then the candidate's permits: read ./inbox/**, write ./digest.md, five nika: tools; then nika check plans it in 9 waves from glob_source to write_output" width="860">
|
|
66
|
+
</picture>
|
|
67
|
+
</p>
|
|
68
|
+
<p align="center"><sub>No provider is seated, so no model is called. Round 1 is <code>incomplete</code>: one required question, the runtime <code>model</code>, four optional ones, and <code>every morning</code> recorded as a trigger, not a task. Answering <code>model = mock/echo</code> through <code>nextCompileRequest()</code> makes round 2 <code>ready</code>; the schedule still <code>requires_binding</code>. The candidate asks to read <code>./inbox/**</code>, write <code>./digest.md</code> and call five <code>nika:</code> tools, and <code>nika check</code> plans it in 9 waves; nothing runs. Recorded from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine.<br>▶ <a href="https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-compile.mp4?raw=true">MP4</a> · <a href="https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-compile.txt">transcript</a> · <a href="https://github.com/nika-open/nika-client/blob/main/scripts/media/scenes/sdk-compile/author.mts">the program</a></sub></p>
|
|
69
|
+
|
|
70
|
+
## Two doors
|
|
71
|
+
|
|
72
|
+
| | `new Nika({ url, token })` | `new Nika()` (local engine) |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| Route | `POST /v1/compile` of `nika serve --bind` | `nika compile --json` |
|
|
75
|
+
| Deterministic compile | `compile` capability in `/health` | `compile` capability in `--sdk-identity` |
|
|
76
|
+
| Provider round | `cognition: 'explicitProvider'`; `/health` must advertise `compileNativeV2` | `authoringModel: 'provider/name'` |
|
|
77
|
+
| Who chooses the model | the server's operator (`nika serve --authoring-model`) | you, per request |
|
|
78
|
+
| Credentials | the server's environment | the local engine's environment |
|
|
79
|
+
| Answer round | the kept round's judged answer round by its `replay_token` (judge calls only) where `/health` lists `compileJudgedAnswerRound`, else a fresh round carrying the answers; or its zero-call replay | the engine replays the plan it recorded under `.nika/compile/` |
|
|
80
|
+
| The files the intent names | observed by the LOCAL engine in the client's `cwd` and sent as `observed_world` where `/health` lists `compileObservedWorld` (see below) | observed by the engine in its working directory |
|
|
81
|
+
| Who judges a candidate | the operator's decision model where `/health` lists `compileDecisionSeat` (`nika serve --decision-model`), else the authoring model | `decisionModel`, else the authoring model |
|
|
82
|
+
|
|
83
|
+
A door that lacks what a request needs refuses it with
|
|
84
|
+
`NikaCompatibilityError` before anything is posted or spawned, and the SDK
|
|
85
|
+
never compiles locally as a substitute for a server.
|
|
86
|
+
|
|
87
|
+
## The files your intent names, over HTTP
|
|
88
|
+
|
|
89
|
+
A server never reads your files. So that its seat does not ask you for a
|
|
90
|
+
field name, a key or a shape it could have read, every generation-2 request
|
|
91
|
+
(a provider round, a judged answer round, a zero-call replay) asks the local
|
|
92
|
+
engine what it observes of the files the request states — `nika compile
|
|
93
|
+
--observe-only -- <intent>` (a text revision: its `original_intent` and its
|
|
94
|
+
change), run in the client's `cwd` — and sends that document unchanged as
|
|
95
|
+
`observed_world`. It holds what `nika compile` hands its own seat: a CSV's
|
|
96
|
+
header, a JSON file's keys and nested key paths, a column's short repeated
|
|
97
|
+
values (a status, a kind), counts of value kinds, the absent and
|
|
98
|
+
outside-the-project states — never a row. The server admits it only in that
|
|
99
|
+
shape, about paths the request states, at most 64 rows and 256 KiB
|
|
100
|
+
(`422 compile_observation_refused` otherwise); its seat, its grounding law
|
|
101
|
+
and its judge then read it.
|
|
102
|
+
|
|
103
|
+
| `observe` option | Behavior |
|
|
104
|
+
|---|---|
|
|
105
|
+
| absent (default) | sent when `/health` lists `compileObservedWorld`; nothing otherwise |
|
|
106
|
+
| `true` | required: a server without the capability is a `NikaCompatibilityError` (`capability: 'compileObservedWorld'`) before anything is posted |
|
|
107
|
+
| `false` | never observed, never sent |
|
|
108
|
+
|
|
109
|
+
Where `/health` also lists `compileTrialInputs` (a server that tries
|
|
110
|
+
candidates), the same request carries `trial_inputs`: the text of the files
|
|
111
|
+
the observation read (the engine offers them only when they are UTF-8 text
|
|
112
|
+
and at most 1 MiB in all). The server writes them into a scratch project of
|
|
113
|
+
its own and tries each final candidate there before it can be `ready`, in the
|
|
114
|
+
observed room `nika compile` and the Session use; the trial's report reaches
|
|
115
|
+
its judge and its repairs (`provenance.decision.rehearsal`). These bytes go
|
|
116
|
+
to the server that will run the workflow on the same files anyway; they are
|
|
117
|
+
never sent to a model nor echoed back. `observe: false` sends neither.
|
|
118
|
+
|
|
119
|
+
The observation is part of a kept round's input: its answer rounds observe
|
|
120
|
+
again, and a file that changed in between makes another input
|
|
121
|
+
(`409 compile_replay_input_changed`): author again. A local engine that cannot
|
|
122
|
+
print the document (one from before the flag) fails typed with
|
|
123
|
+
`capability: 'compileObservedWorld'` and nothing is posted; pass
|
|
124
|
+
`{ observe: false }` to compile without it. A local compile ignores the
|
|
125
|
+
option: the engine always observes its own working directory.
|
|
126
|
+
|
|
127
|
+
## What is a provider call, and what is not
|
|
128
|
+
|
|
129
|
+
- Without an opt-in, compile is deterministic. It contacts no provider, even
|
|
130
|
+
when a key sits in the environment: an ambient key is never consent.
|
|
131
|
+
- HTTP `cognition: 'explicitProvider'` opts one fresh round into the server's
|
|
132
|
+
seated model. It may spend. Its `limits` may only narrow the operator's
|
|
133
|
+
bounds; above them the server answers `422 compile_limit`, never a clamp.
|
|
134
|
+
- A local `authoringModel` seats that model for this request. A local
|
|
135
|
+
`decisionModel` seats a bounded-decision capability for finite ambiguities;
|
|
136
|
+
its choices are recorded in `provenance.decision` and its cognition reads
|
|
137
|
+
`explicitDecision`.
|
|
138
|
+
- An outcome is `compile_version: 2` exactly when a provider call happened;
|
|
139
|
+
`provenance.authoring` is then the receipt (model, logical `calls`, token
|
|
140
|
+
counters, `backend.authority`). Token usage is not an invoice.
|
|
141
|
+
- A judged answer round (`explicitProvider` with a kept round's
|
|
142
|
+
`replay_token`) replays the kept plan with your answers and asks the seat
|
|
143
|
+
only to judge it: judge calls, `compile_version` 2, never a second authoring
|
|
144
|
+
call. It still may spend, on the judge.
|
|
145
|
+
- A zero-call replay (`deterministicOnly` with a `replay_token`) makes no call
|
|
146
|
+
and answers generation 1; it asks no verifier either. A local answer round
|
|
147
|
+
replays the recorded plan with no authoring call; a verifier that round asks
|
|
148
|
+
makes its own calls.
|
|
149
|
+
- Compile creates no run, job, approval, trace, schedule or permission. The
|
|
150
|
+
SDK reads no credential and sends none.
|
|
151
|
+
|
|
152
|
+
## The request
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
// HTTP: one provider round under the server's seat, narrowed by limits.
|
|
156
|
+
const first = await nika.compile({
|
|
157
|
+
intent: 'Every morning at 9, summarize ./inbox/*.md into ./digest.md',
|
|
158
|
+
cognition: 'explicitProvider',
|
|
159
|
+
limits: { max_calls: 6, deadline_ms: 120_000 },
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
// Local engine: the model you seat, its key read by the engine.
|
|
163
|
+
const local = await new Nika().compile({
|
|
164
|
+
intent: 'Every morning at 9, summarize ./inbox/*.md into ./digest.md',
|
|
165
|
+
authoringModel: 'mistral/mistral-small-latest',
|
|
166
|
+
limits: { max_calls: 6 },
|
|
167
|
+
});
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Fields that exist on the HTTP wire keep their wire spelling; fields that only
|
|
171
|
+
a local engine has are named after the flag they become.
|
|
172
|
+
|
|
173
|
+
| SDK field | HTTP body | Local engine argv |
|
|
174
|
+
|---|---|---|
|
|
175
|
+
| `intent` | `mode: "create"`, `intent` | the positional after `--` |
|
|
176
|
+
| `workflow` + `change` | `mode: "edit"`, `source`, `change: {text}` or `{set_constant}` | `--base <scratch file>` and `--change=<text>`; a `set_constant` becomes `Set const.NAME to JSON` |
|
|
177
|
+
| `original_intent` (edit) | `original_intent` | the positional beside `--base` |
|
|
178
|
+
| `workflow_id` (create) | `workflow_id` | refused: the `output` file name names the workflow |
|
|
179
|
+
| `answers` | `answers`, each a JSON value | `--answer=KEY=JSON`, once per key |
|
|
180
|
+
| `cognition` | `cognition` | refused |
|
|
181
|
+
| `limits.max_calls` | `limits.max_calls` | `--authoring-max-calls` |
|
|
182
|
+
| `limits.repairs` | `limits.repairs` | `--authoring-repairs` |
|
|
183
|
+
| `limits.max_tokens` | `limits.max_tokens` | `--authoring-max-tokens` |
|
|
184
|
+
| `limits.call_timeout_ms` | `limits.call_timeout_ms` | `--authoring-timeout`, whole seconds only |
|
|
185
|
+
| `limits.deadline_ms` | `limits.deadline_ms` | refused: no flag; bound the child with `timeoutMs` |
|
|
186
|
+
| `replay_token` | `replay_token`: with `explicitProvider` the judged answer round, with `deterministicOnly` the zero-call replay | refused |
|
|
187
|
+
| `authoringModel` | refused | `--authoring-model` |
|
|
188
|
+
| `decisionModel` (create) | refused | `--decision-model` |
|
|
189
|
+
| `fresh` (create) | refused | `--fresh` |
|
|
190
|
+
| `output` | refused | `--output` |
|
|
191
|
+
|
|
192
|
+
Over HTTP the request picks the wire generation:
|
|
193
|
+
|
|
194
|
+
| Request | Body | `/health` must advertise |
|
|
195
|
+
|---|---|---|
|
|
196
|
+
| no `cognition` | `compile_version: 1` | `compile` |
|
|
197
|
+
| `cognition: 'deterministicOnly'`, no token | `compile_version: 1` with that cognition | `compile` |
|
|
198
|
+
| `cognition: 'explicitProvider'` | `compile_version: 2`, a fresh round | `compileNativeV2` |
|
|
199
|
+
| `cognition: 'explicitProvider'` and `replay_token` | `compile_version: 2`, the kept round's judged answer round | `compileNativeV2` and `compileJudgedAnswerRound` |
|
|
200
|
+
| `cognition: 'deterministicOnly'` and `replay_token` | `compile_version: 2`, the kept round's zero-call replay | `compileNativeV2` |
|
|
201
|
+
|
|
202
|
+
The SDK refuses with `NikaConfigurationError`, before any request or process,
|
|
203
|
+
what the published wire refuses by shape: an unknown field; `intent` mixed
|
|
204
|
+
with `workflow`/`change`; a `replay_token` without a cognition or that is not
|
|
205
|
+
64 lowercase hex digits; `limits` without a provider opt-in or beside
|
|
206
|
+
`deterministicOnly`; a limit that is not an integer within its published range
|
|
207
|
+
(`max_calls` and `max_tokens` 1–4294967295, `repairs` 0–4294967295, the two
|
|
208
|
+
durations from 1 ms); `original_intent` beside `set_constant`; a create-only
|
|
209
|
+
field on an edit. Over HTTP it also refuses `original_intent` on generation 1
|
|
210
|
+
and a generation-2 text change without `original_intent`. A field the chosen
|
|
211
|
+
door does not have is a `NikaCompatibilityError` with `capability:
|
|
212
|
+
'compileOptions'`. Answers and constant values are strict JSON, judged without
|
|
213
|
+
running caller code; a key cannot be empty or contain `=`.
|
|
214
|
+
|
|
215
|
+
Not exposed: `--authoring-samples`, `--authoring-strategy`,
|
|
216
|
+
`--authoring-reasoning`, `--knowledge`, `--knowledge-exclude`,
|
|
217
|
+
`--knowledge-pack`, `--no-knowledge`, `--hot-policy`, `--force`,
|
|
218
|
+
`--private-authoring-capture` and `--list`. A local engine still reads
|
|
219
|
+
`NIKA_AUTHORING_REASONING` and `NIKA_KNOWLEDGE*` from its own environment.
|
|
220
|
+
|
|
221
|
+
## The outcome
|
|
222
|
+
|
|
223
|
+
| Field | Meaning |
|
|
224
|
+
|---|---|
|
|
225
|
+
| `compile_version` | `2` when a provider call happened, else `1` |
|
|
226
|
+
| `status`, `ready` | the engine's completeness word; `ready` is exactly `status === 'ready'` |
|
|
227
|
+
| `candidate` | `.nika` source. Proposed only when ready; under `incomplete` a non-null candidate is a preview |
|
|
228
|
+
| `questions[]` | `key`, `label`, `type` (`text`, `literal` or `choice` with `options[]`), `why`, `mandatory`. A `choice` (engine 0.123, machine protocol 2) carries at least one option and is answered with one option's `key`; no other question carries options. `mandatory: false` belongs to a binding outside the program (a schedule's timezone, missed-run and overlap policies, ceiling) and never blocks ready |
|
|
229
|
+
| `diagnostics[]` | `kind`, `target`, `message`. Compiler targets include `semantic_verification`, `verify_held` and `verify_resume` |
|
|
230
|
+
| `requested_boundary` | the permits the candidate requests; never a grant |
|
|
231
|
+
| `requested_trigger` | the trigger the request names (`kind`, `status`, `cadence`, `cron`…), a requirement you bind through the schedule contract; absent on engines before the field |
|
|
232
|
+
| `check_preview` | the source-only Check report; never admission |
|
|
233
|
+
| `provenance` | `compiler_version`, `spec_pin`, `skeleton`, `cognition`, and when present `strategy`, `suggested_file`, `plan`, `decision`, `authoring` |
|
|
234
|
+
| `replay_token` | HTTP only: the `Nika-Compile-Replay` header of a provider round whose plan the server keeps |
|
|
235
|
+
| `judged_answer_round_available` | HTTP only, beside a kept round: whether the server that answered lists `compileJudgedAnswerRound` in `/health`. An SDK fact, read by `nextCompileRequest()` |
|
|
236
|
+
| `written`, `existing_destination` | local engine only, when the request named `output` |
|
|
237
|
+
| `plan_record_error`, `declined_record_error` | local engine only: it could not keep or remove a record under `.nika/compile/` |
|
|
238
|
+
|
|
239
|
+
Showing or hiding any of these is your application's choice; the SDK imposes
|
|
240
|
+
no display or masking.
|
|
241
|
+
|
|
242
|
+
## Answer rounds
|
|
243
|
+
|
|
244
|
+
`nextCompileRequest(request, outcome, answers, options?)` builds the next
|
|
245
|
+
request: the same input with these answers merged over the previous ones. It
|
|
246
|
+
maps; it judges nothing.
|
|
247
|
+
|
|
248
|
+
- **HTTP, a kept round: the judged answer round.** When a provider round
|
|
249
|
+
answered a `replay_token` and its server serves the judged answer round
|
|
250
|
+
(`outcome.judged_answer_round_available`, from the `/health` capability
|
|
251
|
+
`compileJudgedAnswerRound`), the next request is that round's judged answer
|
|
252
|
+
round: the exact input, the merged answers, `cognition: 'explicitProvider'`,
|
|
253
|
+
the token and the previous `limits` (which may narrow it). The server
|
|
254
|
+
replays the kept plan with the answers and asks its seat only to judge the
|
|
255
|
+
replayed bytes: judge calls, `compile_version` 2, never a second authoring
|
|
256
|
+
call. A candidate the seat accepts is `ready`. One it does not accept is
|
|
257
|
+
held (`verify_held`, `incomplete`, no new token) and the server forgets the
|
|
258
|
+
token: any later request with it answers `409 compile_replay_unavailable`.
|
|
259
|
+
If the judged round answers new questions instead, the next request answers
|
|
260
|
+
them by the same token (or by a newer one the round answered).
|
|
261
|
+
- **HTTP, a kept round on a server that does not judge.** Where the server
|
|
262
|
+
does not list `compileJudgedAnswerRound`, the next request is a new fresh
|
|
263
|
+
round carrying the answers (no token): the one round there that can judge
|
|
264
|
+
them. It authors again and may spend. `{ cognition: 'deterministicOnly' }`
|
|
265
|
+
asks for the zero-call replay instead; `{ cognition: 'explicitProvider' }`
|
|
266
|
+
asks for the judged round whatever the server advertised, and the client
|
|
267
|
+
then refuses it before posting.
|
|
268
|
+
- **HTTP, a kept round: the zero-call replay.** Pass `{ cognition:
|
|
269
|
+
'deterministicOnly' }` for the replay that makes no call: the exact input,
|
|
270
|
+
the token, no `limits`. It binds the answers into the kept plan but asks no
|
|
271
|
+
judge, so a model-authored candidate comes back `incomplete`, a preview with
|
|
272
|
+
its judgment pending (`provenance.decision.pending`); replaying again
|
|
273
|
+
returns the same document. From a replay, the next request stays a replay
|
|
274
|
+
unless you pass `{ cognition: 'explicitProvider' }`.
|
|
275
|
+
- **Either way,** the server compares the input byte for byte
|
|
276
|
+
(`409 compile_replay_input_changed` otherwise). Tokens live in that server
|
|
277
|
+
run only: a restart forgets them (`409 compile_replay_unavailable`), an
|
|
278
|
+
operator may limit their count and lifetime, and a lost first answer leaves
|
|
279
|
+
no token. Keep a token as you keep the request; do not log it.
|
|
280
|
+
- **HTTP, without a token.** A held candidate, a cold plan round or a round
|
|
281
|
+
that needed no call keeps no plan. The next request is a new fresh round
|
|
282
|
+
and may spend again. The `cognition` option is refused there: there is no
|
|
283
|
+
kept round to answer.
|
|
284
|
+
- **Local engine.** The next request repeats the intent with every answer as
|
|
285
|
+
`--answer`. When a round carries at least one answer, the engine replays
|
|
286
|
+
the plan it recorded for that intent under `.nika/compile/` in its working
|
|
287
|
+
directory, with no authoring call, and the seat's verifier may decide it in
|
|
288
|
+
that round; keep the same `cwd` between rounds. `fresh` is dropped. A round
|
|
289
|
+
with no answer reads the intent again and may spend.
|
|
290
|
+
- **A held outcome has no next round.** `nextCompileRequest()` refuses it with
|
|
291
|
+
`NikaConfigurationError`: its token is forgotten and asking again would
|
|
292
|
+
author anew. Stop there, or send a new request yourself.
|
|
293
|
+
- **`intent.clarification`.** Its answer replaces the whole request. A server
|
|
294
|
+
refuses it as an answer (`422 compile_new_intent_required` on a fresh or
|
|
295
|
+
judged round, `409 compile_replay_input_changed` on a replay): start a new
|
|
296
|
+
create request with the replacement intent. A local engine consumes it as an
|
|
297
|
+
`--answer` only beside a seat.
|
|
298
|
+
|
|
299
|
+
A loop must be bounded: stop on a held or refused outcome, when a round brings
|
|
300
|
+
no new answer, and after a few rounds.
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
let request: NikaCompileRequest = { intent, cognition: 'explicitProvider', limits: { max_calls: 8 } };
|
|
304
|
+
let outcome = await nika.compile(request);
|
|
305
|
+
for (let round = 0; !outcome.ready && round < 4; round += 1) {
|
|
306
|
+
if (isNikaCompileHeld(outcome) || outcome.status === 'refused') break;
|
|
307
|
+
const answers = await askYourUser(outcome.questions); // your application's choice
|
|
308
|
+
if (Object.keys(answers).length === 0) break;
|
|
309
|
+
// After a provider round that kept its plan: its judged answer round where the
|
|
310
|
+
// server serves it, else a fresh round carrying the answers.
|
|
311
|
+
request = nextCompileRequest(request, outcome, answers);
|
|
312
|
+
outcome = await nika.compile(request);
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Servers without the judged answer round
|
|
317
|
+
|
|
318
|
+
The judged answer round needs a server that serves it, which `/health` says
|
|
319
|
+
with the capability `compileJudgedAnswerRound`. Engine 0.123.0 lists it beside
|
|
320
|
+
`compileNativeV2` on every native server, that is whenever the operator seats
|
|
321
|
+
a model with `nika serve --authoring-model` (measured with `mock/echo`: the
|
|
322
|
+
seated `/health` lists `compileNativeV2`, `compileJudgedAnswerRound`,
|
|
323
|
+
`compileObservedWorld` and `compileTrialInputs`, the unseated one none of
|
|
324
|
+
them). The SDK gates the round the way it gates generation 2: on a
|
|
325
|
+
server without the capability it refuses a judged answer round with
|
|
326
|
+
`NikaCompatibilityError` (`capability: 'compileJudgedAnswerRound'`) after
|
|
327
|
+
`/health` alone, before anything is posted, and the kept round stays
|
|
328
|
+
untouched. Beside every kept round it also sets
|
|
329
|
+
`outcome.judged_answer_round_available`, so `nextCompileRequest()` chooses a
|
|
330
|
+
round the server serves.
|
|
331
|
+
|
|
332
|
+
A server from before the round (the released 0.121.0 and 0.122.0) parsed
|
|
333
|
+
`explicitProvider` with a `replay_token` as `422 malformed_compile_request`,
|
|
334
|
+
before any slot or call; this package refuses those servers at their identity
|
|
335
|
+
anyway, since they speak machine protocol 1. The SDK still reports that
|
|
336
|
+
refusal to a judged answer round as the same `NikaCompatibilityError`,
|
|
337
|
+
defensively, for a server replaced since this client read its `/health` (once
|
|
338
|
+
per client).
|
|
339
|
+
|
|
340
|
+
## Held candidates
|
|
341
|
+
|
|
342
|
+
When the verifier answers on a candidate's bytes and does not accept them, the
|
|
343
|
+
engine marks the outcome with an `applied` diagnostic targeting `verify_held`
|
|
344
|
+
and leaves it `incomplete`. `candidate` then holds a preview to show at most:
|
|
345
|
+
never run it or save it as an accepted result. `isNikaCompileHeld(outcome)`
|
|
346
|
+
reads the marker. A server keeps no replay token for it, and a held judged
|
|
347
|
+
answer round forgets the token it answered (a later request with it answers
|
|
348
|
+
`409 compile_replay_unavailable`), so asking again is a fresh round. A `verify_resume` marker means no admitted judgment was made: the
|
|
349
|
+
candidate is withdrawn and the round's record kept.
|
|
350
|
+
|
|
351
|
+
The SDK refuses with `NikaProtocolError` an outcome that calls itself `ready`
|
|
352
|
+
while carrying either marker, so a held or withdrawn candidate never reads as
|
|
353
|
+
ready.
|
|
354
|
+
|
|
355
|
+
## Errors
|
|
356
|
+
|
|
357
|
+
| Error | When |
|
|
358
|
+
|---|---|
|
|
359
|
+
| `NikaConfigurationError` | the request or options break a shape law (above); nothing was sent or spawned |
|
|
360
|
+
| `NikaCompatibilityError` | the door lacks `compile`, `compileNativeV2`, `compileJudgedAnswerRound`, a required `compileObservedWorld` or a field (`compileOptions`); the local engine could not observe the request's files; or the answer carries a wire generation this request cannot receive |
|
|
361
|
+
| `NikaProtocolError` | the answer breaks the contract: malformed JSON, a ready outcome without candidate or with a held marker, generation 2 without its receipt, a replay token where none can be, a destination the request never named |
|
|
362
|
+
| `NikaTransportError` | aborted, timed out, the engine could not be spawned or was killed |
|
|
363
|
+
| `NikaOperationError` | the engine refused: `code` is its machine code, `status` the HTTP status or the local exit code |
|
|
364
|
+
|
|
365
|
+
`POST /v1/compile` refusals, as `NikaOperationError.code`:
|
|
366
|
+
|
|
367
|
+
| Status | Codes |
|
|
368
|
+
|---|---|
|
|
369
|
+
| 401 | `unauthorized` |
|
|
370
|
+
| 408 | `request_timeout` (intake, generation 1, replays) · `compile_deadline_exceeded` (a fresh round's absolute deadline passed; a call in flight may still be billed) |
|
|
371
|
+
| 409 | `compile_replay_unavailable` (an unknown, expired or forgotten token: a held judged round forgets its own) · `compile_replay_input_changed` · `compile_context_changed` (the server's pinned knowledge snapshot moved; nothing was sent) |
|
|
372
|
+
| 413 | `body_too_large` |
|
|
373
|
+
| 415 | `unsupported_media_type` · `unsupported_content_encoding` |
|
|
374
|
+
| 422 | `malformed_compile_request` · `compile_version_unsupported` · `compile_mode_unsupported` · `compile_cognition_unsupported` · `compile_limit` · `compile_new_intent_required` · `compile_observation_refused` · `compile_trial_inputs_refused` |
|
|
375
|
+
| 500 | `internal_error` · `compile_disclosure_refused` (the answer would carry a withheld credential) |
|
|
376
|
+
| 503 | `compile_busy` · `compile_replay_capacity` · `stopping` |
|
|
377
|
+
|
|
378
|
+
Local engine refusals arrive with exit 2 (`destination_name`,
|
|
379
|
+
`invalid_answer`, `authoring_authority`) or exit 3 (`read_base`, `knowledge`,
|
|
380
|
+
`authoring_config`, `compile_error`, `destination`). An engine that does not
|
|
381
|
+
know a flag answers with its usage error and no machine document; the SDK
|
|
382
|
+
reports it as `NikaProtocolError` quoting that error. The type
|
|
383
|
+
`NikaCompileRefusalCode` lists these words without closing the vocabulary.
|
|
384
|
+
|
|
385
|
+
## Time and cancellation
|
|
386
|
+
|
|
387
|
+
`signal` and `timeoutMs` stop this request or child only. Over HTTP:
|
|
388
|
+
|
|
389
|
+
- a generation-1 request or a replay keeps the client's `requestTimeout`
|
|
390
|
+
unless `timeoutMs` is set;
|
|
391
|
+
- a provider round (fresh or judged) with `limits.deadline_ms` waits for that
|
|
392
|
+
deadline, the server's 5 s handoff and one `requestTimeout` more, so the
|
|
393
|
+
server's own `408 compile_deadline_exceeded` arrives before the client stops
|
|
394
|
+
waiting;
|
|
395
|
+
- a provider round without `timeoutMs` or `limits.deadline_ms` gets no SDK
|
|
396
|
+
deadline. The server sets none either unless its operator configured one
|
|
397
|
+
(`nika serve --authoring-deadline`): the round runs until it settles.
|
|
398
|
+
|
|
399
|
+
Stopping your wait stops neither the server's round nor its spend, and loses
|
|
400
|
+
its answer and replay token. The server sends its headers only when the round
|
|
401
|
+
settles, and Node's built-in `fetch` stops waiting for response headers after
|
|
402
|
+
300 seconds. So a provider round with no deadline is posted through
|
|
403
|
+
`node:http`/`node:https`, which set no header or body deadline: only your
|
|
404
|
+
`signal` or the server ends the wait. A `fetch` you pass in the configuration
|
|
405
|
+
is used for every request, this one included, with its own timeouts: give it
|
|
406
|
+
a dispatcher that allows the round's length, or set `limits.deadline_ms`. A
|
|
407
|
+
local compile has no deadline unless you set one; a stopped child receives
|
|
408
|
+
SIGTERM, then SIGKILL after two seconds.
|
|
409
|
+
|
|
410
|
+
Responses are bounded: 8 MiB for a local compile and for an HTTP
|
|
411
|
+
generation-2 request, whose answer carries the round's plan, decision records
|
|
412
|
+
and receipt. An HTTP generation-1 answer keeps the smaller of
|
|
413
|
+
`machineBufferBytes` (16 MiB by default, so 8 MiB applies) and 8 MiB.
|
|
414
|
+
|
|
415
|
+
## Files a local compile touches
|
|
416
|
+
|
|
417
|
+
- **Reads** the files a free intent names under the working directory, as a
|
|
418
|
+
bounded observation of their keys and short repeated values, never their
|
|
419
|
+
rows. An edit's base travels through a 0600 scratch file in a 0700 temporary
|
|
420
|
+
directory, removed on every path.
|
|
421
|
+
- **Writes** the plan record `.nika/compile/<intent sha256>.plan.json` and the
|
|
422
|
+
verdicts `.nika/compile/<intent sha256>.declined.json` (the directory ignores
|
|
423
|
+
itself for Git), and with `output` the ready candidate. Nothing that is not
|
|
424
|
+
ready is ever written to `output`.
|
|
425
|
+
- An HTTP compile writes nothing, anywhere. Its generation-2 requests spawn
|
|
426
|
+
the local engine with `compile --observe-only` (read-only, same bounds as
|
|
427
|
+
above) unless `observe: false`.
|
|
428
|
+
|
|
429
|
+
## Engine versions
|
|
430
|
+
|
|
431
|
+
By the engine source at its release tags: 0.120.3 speaks generation 1 only,
|
|
432
|
+
without `requested_trigger` or `choice` questions, and its CLI has none of the
|
|
433
|
+
seat flags. 0.121.0 adds the seat flags, `requested_trigger`, `choice`
|
|
434
|
+
questions and Serve generation 2, without `limits.max_calls`, while still
|
|
435
|
+
announcing machine protocol 1. 0.122.0 adds `limits.max_calls` and
|
|
436
|
+
`--authoring-max-calls`. 0.123.0 announces machine protocol 2 and adds the
|
|
437
|
+
judged answer round with its capability, `nika compile --observe-only`,
|
|
438
|
+
`observed_world` with its `compileObservedWorld` capability, `trial_inputs`
|
|
439
|
+
with `compileTrialInputs`, and `nika serve --decision-model` with
|
|
440
|
+
`compileDecisionSeat`. 0.123.1 is a maintenance release: the same machine
|
|
441
|
+
protocol, and a default served document that differs from 0.123.0's only by
|
|
442
|
+
its version. 0.123.2 keeps machine protocol 2; its served document adds the
|
|
443
|
+
two artifact routes and declares answers 0.123.1 already sent, and its compile
|
|
444
|
+
door is unchanged. 0.124.0 keeps machine protocol 2 and the compile door of
|
|
445
|
+
0.123.2: its compile code is unchanged, and its served document differs from
|
|
446
|
+
0.123.2's only by its version and the artifacts route's description. 0.124.1
|
|
447
|
+
is a maintenance release of that line: the same machine protocol and compile
|
|
448
|
+
code, and a served document that differs from 0.124.0's only by its version.
|
|
449
|
+
0.124.2 keeps both again, and its served document differs from 0.124.1's
|
|
450
|
+
only by its version: the service tier it adds is a field of the workflow
|
|
451
|
+
file, never of a request, and its health answer lists one more capability,
|
|
452
|
+
`accessServiceTier`. 0.124.3 keeps the machine protocol and the compile code
|
|
453
|
+
once more. Its served document adds one route,
|
|
454
|
+
`GET /v1/access-offers/{name}`, with the schemas of its answer, and its
|
|
455
|
+
health answer lists `accessSessionOffer`. 0.124.4 keeps both again, and its
|
|
456
|
+
default served document differs from 0.124.3's only by its version: the
|
|
457
|
+
standing cost policy it adds is a flag the operator gives at startup
|
|
458
|
+
(`nika serve --cost-policy`), never a field of a request. Only a server
|
|
459
|
+
started with that flag lists one more capability, `costStandingPolicyV1`,
|
|
460
|
+
and describes the `cost_admission` of a job's settlement in the document it
|
|
461
|
+
serves. 0.124.5, the engine this package version bundles, is the first
|
|
462
|
+
release published from `nika-open/nika` and keeps both once more: its
|
|
463
|
+
default served document differs from 0.124.4's only by its version, and its
|
|
464
|
+
health answer lists the same capabilities. This package refuses an engine
|
|
465
|
+
on protocol 1 at its identity. An engine without a flag answers with a usage
|
|
466
|
+
error; a server without a field answers `422 malformed_compile_request`.
|
|
467
|
+
Point `NIKA_BIN` (or `bin`) at the engine you mean to use.
|
|
468
|
+
|
|
469
|
+
The pinned `openapi.json` and `src/generated/openapi.d.ts` are the default
|
|
470
|
+
document of the released engine 0.124.5 resident, regenerated from the
|
|
471
|
+
released `nika serve`. The generation-2 types are written by hand from the
|
|
472
|
+
engine source at tag `v0.123.0`: `crates/nika-serve/src/server/compile/v2.rs`,
|
|
473
|
+
`author.rs` and `openapi-native.json` (the rounds, the judged answer round
|
|
474
|
+
included), `crates/nika-serve/src/server/model.rs` (its capabilities),
|
|
475
|
+
`crates/nika-compile/src/wire.rs` and `crates/nika-cli-host/src/compile.rs`
|
|
476
|
+
with `compile/render.rs`.
|
|
477
|
+
|
|
478
|
+
## Example
|
|
479
|
+
|
|
480
|
+
[`examples/compile-then-run.ts`](https://github.com/nika-open/nika-client/blob/main/examples/compile-then-run.ts)
|
|
481
|
+
compiles an intention, answers its questions from a JSON file (over HTTP by
|
|
482
|
+
the judged answer round), writes the ready candidate and runs it through
|
|
483
|
+
`run()`, on either door. It reads the server URL and token or the engine
|
|
484
|
+
binary from the environment and embeds no key. On engine 0.123.0 without a
|
|
485
|
+
seat, `classify-and-route` asks `const.request`, the file answers it, the
|
|
486
|
+
next round is `ready`, and the run settles `succeeded`.
|