nexustrade 0.3.0 → 1.0.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/AGENTS.md CHANGED
@@ -25,7 +25,7 @@ export NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1
25
25
 
26
26
  ```ts
27
27
  import { NexusTradeClient } from "nexustrade";
28
- const nt = new NexusTradeClient(); // reads the environment
28
+ const client = new NexusTradeClient(); // reads the environment
29
29
  ```
30
30
 
31
31
  Keys come from https://nexustrade.io/developers. Never hardcode one into a file
@@ -68,10 +68,10 @@ retry with a new key launches a second paid job.
68
68
 
69
69
  ```ts
70
70
  // Right — same logical run reuses the key across retries
71
- await nt.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
71
+ await client.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
72
72
 
73
73
  // Wrong — every retry is a new billable job
74
- await nt.createBacktest(handle, { idempotencyKey: `run-${Date.now()}` });
74
+ await client.createBacktest(handle, { idempotencyKey: `run-${Date.now()}` });
75
75
  ```
76
76
 
77
77
  Reusing a key with a *different* payload is a `409 idempotency_conflict`. Version
@@ -80,9 +80,9 @@ the key when the request changes: `momentum-2024-v2`.
80
80
  **4. `create*` does not wait. Poll.**
81
81
 
82
82
  ```ts
83
- const operation = await nt.createBacktest(handle, { idempotencyKey: "k" });
83
+ const operation = await client.createBacktest(handle, { idempotencyKey: "k" });
84
84
  // operation.result is ABSENT here — the job has not run yet.
85
- const finished = await nt.waitForBacktest(operation.id as string);
85
+ const finished = await client.waitForBacktest(operation.id as string);
86
86
  console.log(finished.result);
87
87
  ```
88
88
 
@@ -92,10 +92,10 @@ do not resubmit.
92
92
  **5. Batch when you have several.**
93
93
 
94
94
  ```ts
95
- const operations = await nt.createBacktests([h1, h2, h3], {
95
+ const operations = await client.createBacktests([h1, h2, h3], {
96
96
  idempotencyKey: "sweep-v1",
97
97
  });
98
- const results = await nt.waitForBacktests(operations);
98
+ const results = await client.waitForBacktests(operations);
99
99
  ```
100
100
 
101
101
  One request, one key, one rate-limit slot — instead of three of each.
@@ -114,6 +114,28 @@ write, and never log one. Exported values win over the file.
114
114
  narrow before use (`operation.id as string`). This is deliberate: the envelope is
115
115
  whatever the API returned, not a promise the SDK can statically make.
116
116
 
117
+ **9. Your own data belongs in ONE series.** `createCustomIndicator` mints a new
118
+ series every time it is called with a fresh idempotency key. Recurring
119
+ collection must `appendCustomIndicatorPoints` onto the id it created the first
120
+ time — a new series per run splits the history into fragments no strategy can
121
+ read. Persist the id; never re-create by name.
122
+
123
+ ```ts
124
+ // Right — one series, appended forever
125
+ await client.appendCustomIndicatorPoints(seriesId, todaysPoints, {
126
+ idempotencyKey: `mentions-${today}`,
127
+ });
128
+
129
+ // Wrong — a new, disconnected series every run
130
+ await client.createCustomIndicator(
131
+ { name: "Mentions", points: todaysPoints },
132
+ { idempotencyKey: `mentions-${today}` },
133
+ );
134
+ ```
135
+
136
+ Point batches are unlimited in size; the SDK sends them inline or uploads them.
137
+ Do not chunk by hand.
138
+
117
139
  ## Recipes
118
140
 
119
141
  <details open>
@@ -201,7 +223,7 @@ pair.
201
223
  <summary><b>Query the data lake</b></summary>
202
224
 
203
225
  ```ts
204
- const query = await nt.createLakeQuery(
226
+ const query = await client.createLakeQuery(
205
227
  {
206
228
  query: "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
207
229
  params: ["AAPL"],
@@ -209,8 +231,8 @@ const query = await nt.createLakeQuery(
209
231
  },
210
232
  { idempotencyKey: "aapl-daily-v1" },
211
233
  );
212
- const finished = await nt.waitForLakeQuery(query.id as string);
213
- const manifest = await nt.getLakeQueryManifest(finished.id as string);
234
+ const finished = await client.waitForLakeQuery(query.id as string);
235
+ const manifest = await client.getLakeQueryManifest(finished.id as string);
214
236
  ```
215
237
 
216
238
  Always parameterize with `?` rather than interpolating into the SQL string.
@@ -225,7 +247,7 @@ Agents are the one job kind that is NOT fire-and-poll. Three states —
225
247
  ones the run cannot leave on its own, so the caller is the approver.
226
248
 
227
249
  ```ts
228
- const run = await nt.createAgent("Find momentum names in the S&P 500", {
250
+ const run = await client.createAgent("Find momentum names in the S&P 500", {
229
251
  idempotencyKey: "momentum-scan-v1",
230
252
  });
231
253
 
@@ -238,7 +260,7 @@ for await (const event of run) {
238
260
 
239
261
  Iterating waits. If you never answer a blocked run, iteration throws
240
262
  `agent_awaiting_input` rather than spinning silently — the run keeps going
241
- server-side, so reattach with `nt.attachAgent(run.id)`.
263
+ server-side, so reattach with `client.attachAgent(run.id)`.
242
264
 
243
265
  Approving can place orders, so it needs the `trade` scope; everything else
244
266
  needs `write`. Agent runs are unavailable to `run_compute` sandbox code.
@@ -255,6 +277,7 @@ All failures throw `NexusTradeApiError` with a stable `.status`, `.code`, and
255
277
  | `insufficient_scope` | The key lacks `read` / `write` / `lake`. Do not retry. |
256
278
  | `invalid_portfolio` | The book is malformed — fix the builders, do not retry as-is. |
257
279
  | `idempotency_conflict` | Same key, different payload. Version the key. |
280
+ | `idempotency_in_progress` | Same key, first call still running. Wait and re-read; never resubmit. |
258
281
  | `rate_limit_exceeded` | Back off and retry. |
259
282
  | `operation_timeout` | Job still running. Re-poll the same id; never resubmit. |
260
283
 
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
12
12
  [![Deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
13
13
 
14
- [Quickstart](#quickstart) · [Authoring](#authoring-strategies) · [Polling](#jobs-run-on-the-engine--you-poll) · [Lake SQL](#lake-sql) · [Auth](#authentication) · [Errors](#errors)
14
+ [Quickstart](#quickstart) · [Authoring](#authoring-strategies) · [Polling](#jobs-run-on-the-engine--you-poll) · [Agents](#agent-runs) · [Lake SQL](#lake-sql) · [Auth](#authentication) · [Errors](#errors)
15
15
 
16
16
  </div>
17
17
 
@@ -30,7 +30,7 @@ import {
30
30
  NexusTradeClient, always, backtest, buy, portfolio, stockAsset, strategy,
31
31
  } from "nexustrade";
32
32
 
33
- const nt = new NexusTradeClient({
33
+ const client = new NexusTradeClient({
34
34
  apiKey: "sk-...",
35
35
  baseUrl: "https://nexustrade.io/api/v1",
36
36
  });
@@ -39,11 +39,11 @@ const book = portfolio("Example", [
39
39
  strategy("Buy SPY", always(), buy(stockAsset("SPY"), 100)),
40
40
  ]);
41
41
 
42
- const operation = await nt.createBacktest(
42
+ const operation = await client.createBacktest(
43
43
  backtest(book, { startDate: "2024-01-01", endDate: "2024-12-31" }),
44
44
  { idempotencyKey: "example-v1" },
45
45
  );
46
- const result = await nt.waitForBacktest(operation.id as string);
46
+ const result = await client.waitForBacktest(operation.id as string);
47
47
  console.log(result.result);
48
48
  ```
49
49
 
@@ -87,7 +87,7 @@ const book = nt.portfolio("Momentum", [
87
87
  | **Portfolio state** | `PortfolioValue` `BuyingPower` `MaxDrawdown` `InitialValue` |
88
88
  | **Fundamentals** | `Fundamental` `Economic` `DaysUntilEarnings` `IsIndexMember` `IsIndustry` |
89
89
  | **Options** | `OptionDaysToExpiration` `OptionCollateral` `OptionUnrealizedPnL` `openOption` `closeOption` |
90
- | **Actions** | `buy` `sell` `deposit` `withdraw` `alert` `dynamicRebalance` `rebalanceOption` |
90
+ | **Actions** | `buy` `sell` `alert` `dynamicRebalance` `rebalanceOption` |
91
91
  | **Selection** | `filter` `selectTop` `selectPercentile` `universe` |
92
92
  | **Logic** | `always` `atLeast` `atMost` `exactly` `fewerThan` `multi` `and` `or` |
93
93
 
@@ -100,6 +100,27 @@ Every builder is fully typed — your editor completes the whole surface.
100
100
  `create*` enqueues work and returns immediately. It does **not** resolve when
101
101
  results exist. There are no webhooks today.
102
102
 
103
+ ```mermaid
104
+ sequenceDiagram
105
+ participant You
106
+ participant SDK
107
+ participant Engine
108
+
109
+ You->>SDK: createBacktest(book)
110
+ SDK->>Engine: POST (enqueue)
111
+ Engine-->>SDK: id, status=queued
112
+ SDK-->>You: operation (returns immediately)
113
+
114
+ loop waitForBacktest — backoff 2s→15s
115
+ SDK->>Engine: GET /operations/{id}
116
+ Engine-->>SDK: status update
117
+ end
118
+
119
+ SDK-->>You: result (when completed)
120
+
121
+ Note over You,Engine: Poll timeout throws operation_timeout.<br/>The job keeps running — call wait again with the same id.
122
+ ```
123
+
103
124
  Every job kind reports the same envelope, so one poller serves all of them:
104
125
 
105
126
  ```ts
@@ -113,7 +134,7 @@ Every job kind reports the same envelope, so one poller serves all of them:
113
134
  ```
114
135
 
115
136
  ```ts
116
- const finished = await nt.waitForBacktest(operation.id as string);
137
+ const finished = await client.waitForBacktest(operation.id as string);
117
138
  ```
118
139
 
119
140
  | Option | Default | Meaning |
@@ -133,7 +154,7 @@ over a loop: one request, one idempotency key, one rate-limit slot.
133
154
  **Optimization and walk-forward** follow the identical shape:
134
155
 
135
156
  ```ts
136
- const study = await nt.createWalkForward(
157
+ const study = await client.createWalkForward(
137
158
  nt.walkForward(book, {
138
159
  globalStartDate: "2022-01-01",
139
160
  globalEndDate: "2024-12-31",
@@ -141,7 +162,124 @@ const study = await nt.createWalkForward(
141
162
  }),
142
163
  { idempotencyKey: "wf-v1" },
143
164
  );
144
- await nt.waitForWalkForward(study.id as string);
165
+ await client.waitForWalkForward(study.id as string);
166
+ ```
167
+
168
+ ## Your own data
169
+
170
+ A custom data source is a time series you own — sentiment counts, a proprietary
171
+ factor, anything the platform does not already carry. Create one, then reference
172
+ it from a strategy with `CustomIndicator`.
173
+
174
+ ```ts
175
+ const series = await client.createCustomIndicator(
176
+ {
177
+ name: "WSB NVDA Mentions",
178
+ scope: "asset",
179
+ description: "Daily r/wallstreetbets mentions",
180
+ points: [
181
+ { timestamp: "2024-04-01", value: 152, ticker: "NVDA" },
182
+ { timestamp: "2024-04-02", value: 90, ticker: "NVDA" },
183
+ ],
184
+ },
185
+ { idempotencyKey: "wsb-mentions-v1" },
186
+ );
187
+
188
+ const busy = nt.gt(
189
+ nt.CustomIndicator(nt.stockAsset("NVDA"), String(series.customIndicatorId)),
190
+ 100,
191
+ );
192
+ const book = nt.portfolio("Attention", [
193
+ nt.strategy("Buy the buzz", busy, nt.buy(nt.stockAsset("NVDA"), 25)),
194
+ ]);
195
+ ```
196
+
197
+ `scope` is `"global"` (one series) or `"asset"` (one series per ticker, so every
198
+ point needs a `ticker`). It cannot be changed after creation.
199
+
200
+ **Size is not a constraint.** `points` is unlimited. A batch that fits the
201
+ request goes with it; a larger one is uploaded to storage and validated before
202
+ the call resolves. Either way the returned indicator reflects what actually
203
+ landed, and an upload that fails validation rejects rather than reporting
204
+ success.
205
+
206
+ **Growing a series.** Append to the same id every run:
207
+
208
+ ```ts
209
+ await client.appendCustomIndicatorPoints(
210
+ String(series.customIndicatorId),
211
+ [{ timestamp: "2024-04-03", value: 118, ticker: "NVDA" }],
212
+ { idempotencyKey: "wsb-mentions-2024-04-03" },
213
+ );
214
+ ```
215
+
216
+ Creating a fresh series per run splits the history into fragments no strategy
217
+ can read. Re-sending an identical batch is safe — the duplicate is not written
218
+ twice.
219
+
220
+ | Call | Purpose |
221
+ | --- | --- |
222
+ | `createCustomIndicator(spec, { idempotencyKey })` | Create, optionally seeded |
223
+ | `appendCustomIndicatorPoints(id, points, { idempotencyKey })` | Add points |
224
+ | `listCustomIndicators()` / `getCustomIndicator(id)` | Discover ids and coverage |
225
+
226
+ Points accept `timestamp`, `value`, `ticker`, `assetType`, and `availableAt`
227
+ — camelCase or snake_case, with `Date` objects allowed. Set `availableAt` when a
228
+ value became knowable later than it is dated: an earnings figure stamped to
229
+ quarter-end but published weeks after. An unrecognized field throws rather than
230
+ being silently dropped.
231
+
232
+ To hand over a file you already have on disk, `createCustomIndicatorUpload` /
233
+ `completeCustomIndicatorUpload` / `waitForCustomIndicatorUpload` expose the
234
+ three steps directly. CSV, JSON, and JSONL up to 100 MB.
235
+
236
+ ## Agent runs
237
+
238
+ Every other job is fire-and-poll. **Agents are not** — three states
239
+ (`pending_plan_approval`, `pending_action_approval`, `awaiting_user_input`)
240
+ cannot advance without you. Iterate the run and answer when it blocks:
241
+
242
+ ```mermaid
243
+ sequenceDiagram
244
+ participant You
245
+ participant Run as AgentRun
246
+ participant Engine
247
+
248
+ You->>Run: createAgent(prompt)
249
+ Run->>Engine: POST /agents
250
+ Engine-->>Run: run id
251
+
252
+ loop for await (const event of run)
253
+ Run->>Engine: GET events (cursor)
254
+ Engine-->>Run: new events
255
+
256
+ alt event.needsApproval
257
+ Run-->>You: plan or action awaiting approval
258
+ You->>Run: approve() or reject()
259
+ Run->>Engine: POST approval
260
+ else event.needsInput
261
+ Run-->>You: awaiting user input
262
+ You->>Run: say("...")
263
+ Run->>Engine: POST message
264
+ else
265
+ Run-->>You: event.text
266
+ end
267
+ end
268
+
269
+ Run-->>You: terminal
270
+
271
+ Note over You,Engine: Without approve/say, the run stalls and bills.<br/>Reattach later with attachAgent(run.id).
272
+ ```
273
+
274
+ ```ts
275
+ const run = await client.createAgent("Find momentum names in the S&P 500", {
276
+ idempotencyKey: "momentum-scan-v1",
277
+ });
278
+ for await (const event of run) {
279
+ console.log(event.text);
280
+ if (event.needsApproval) await run.approve();
281
+ if (event.needsInput) await run.say("Focus on tech");
282
+ }
145
283
  ```
146
284
 
147
285
  ## Lake SQL
@@ -150,8 +288,16 @@ Read-only SQL over the NexusTrade market-data lake, against the server-resolved
150
288
  `lake.*` catalog. Results are durable Parquet parts rather than an implicitly
151
289
  materialized in-memory array.
152
290
 
291
+ ```mermaid
292
+ flowchart LR
293
+ A[createLakeQuery] --> B[waitForLakeQuery]
294
+ B --> C[getLakeQueryManifest]
295
+ C --> D[downloadLakeQueryPart]
296
+ D --> E[Stream Parquet within your memory budget]
297
+ ```
298
+
153
299
  ```ts
154
- const query = await nt.createLakeQuery(
300
+ const query = await client.createLakeQuery(
155
301
  {
156
302
  query: "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
157
303
  params: ["AAPL"],
@@ -159,8 +305,8 @@ const query = await nt.createLakeQuery(
159
305
  },
160
306
  { idempotencyKey: "aapl-daily-v1" },
161
307
  );
162
- const finished = await nt.waitForLakeQuery(query.id as string);
163
- const manifest = await nt.getLakeQueryManifest(finished.id as string);
308
+ const finished = await client.waitForLakeQuery(query.id as string);
309
+ const manifest = await client.getLakeQueryManifest(finished.id as string);
164
310
  ```
165
311
 
166
312
  Use the manifest plus `downloadLakeQueryPart` to stream results within your own
@@ -176,7 +322,7 @@ Create a key at **[nexustrade.io/developers](https://nexustrade.io/developers)**
176
322
  (Profile → API Keys). Keys start with `sk-` and are shown once.
177
323
 
178
324
  ```ts
179
- const nt = new NexusTradeClient({
325
+ const client = new NexusTradeClient({
180
326
  apiKey: "sk-...",
181
327
  baseUrl: "https://nexustrade.io/api/v1",
182
328
  });
@@ -223,7 +369,7 @@ the original resource instead of launching a second paid job — so a retry afte
223
369
  a network failure is free.
224
370
 
225
371
  ```ts
226
- await nt.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
372
+ await client.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
227
373
  ```
228
374
 
229
375
  ## Errors
@@ -232,7 +378,7 @@ await nt.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
232
378
  import { NexusTradeApiError } from "nexustrade";
233
379
 
234
380
  try {
235
- await nt.createBacktest(handle, { idempotencyKey: "run-1" });
381
+ await client.createBacktest(handle, { idempotencyKey: "run-1" });
236
382
  } catch (error) {
237
383
  if (error instanceof NexusTradeApiError && error.code === "rate_limit_exceeded") {
238
384
  // back off
@@ -248,6 +394,7 @@ try {
248
394
  | 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
249
395
  | 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
250
396
  | 409 | `idempotency_conflict` | Key reused with a different payload |
397
+ | 409 | `idempotency_in_progress` | Same key, first call still running. Re-poll, do not resubmit |
251
398
  | 404 | `not_found`, `operation_not_found` | Unknown or not yours |
252
399
  | 429 | `rate_limit_exceeded` | Back off and retry |
253
400
 
package/dist/cjs/agent.js CHANGED
@@ -20,8 +20,6 @@
20
20
  * if (event.needsApproval) await run.approve();
21
21
  * }
22
22
  * ```
23
- *
24
- * Mirrors `agent.py`. See designs/2026-07-26-sdk-agent-runs.md.
25
23
  */
26
24
  Object.defineProperty(exports, "__esModule", { value: true });
27
25
  exports.AgentRun = void 0;
@@ -38,9 +36,8 @@ class AgentRun {
38
36
  /** Every event yielded so far, in order. */
39
37
  events = [];
40
38
  /**
41
- * Pacing, public and mutable to mirror the Python dataclass fields. Tests
42
- * collapse the backoff through these; callers can widen the timeout on a run
43
- * they expect to sit blocked for a while.
39
+ * Polling pacing. Mutable so callers can widen the timeout on a run they
40
+ * expect to sit blocked for a while.
44
41
  */
45
42
  timeoutSeconds;
46
43
  pollIntervalSeconds;
@@ -49,6 +46,14 @@ class AgentRun {
49
46
  #transport;
50
47
  #cursor = null;
51
48
  #seen = new Map();
49
+ /**
50
+ * Advances only after a POST is acknowledged, so a retry of a call that
51
+ * failed reuses its key and is deduped, while two different calls never
52
+ * collide. Keying on `events.length` did the latter wrong: two messages sent
53
+ * without iterating between them shared a key and the second was rejected as
54
+ * an idempotency conflict.
55
+ */
56
+ #actionSeq = 0;
52
57
  constructor(id, transport, status = "initializing", options = {}) {
53
58
  this.id = id;
54
59
  this.status = status;
@@ -209,8 +214,9 @@ class AgentRun {
209
214
  async #post(action, body = {}) {
210
215
  const response = await this.#transport.request("POST", `agents/${encodeURIComponent(this.id)}/${action}`, {
211
216
  body,
212
- idempotencyKey: `${this.id}:${action}:${this.events.length}`,
217
+ idempotencyKey: `${this.id}:${action}:${this.#actionSeq}`,
213
218
  });
219
+ this.#actionSeq += 1;
214
220
  const agent = response.agent;
215
221
  if (agent && typeof agent === "object" && !Array.isArray(agent)) {
216
222
  const status = agent.status;