nexustrade 4.0.0 → 5.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 +12 -28
- package/README.md +18 -82
- package/dist/cjs/client.js +6 -82
- package/dist/esm/client.d.ts +2 -48
- package/dist/esm/client.js +6 -82
- package/dist/esm/generated/ntSdk.generated.d.ts +1 -1
- package/package.json +4 -3
package/AGENTS.md
CHANGED
|
@@ -143,10 +143,6 @@ retain same-day UTC availability on both inline and large-upload paths. Use
|
|
|
143
143
|
`period_aggregate` plus `aggregatePeriod` for closed periods, or `disclosed`
|
|
144
144
|
with per-row publication times.
|
|
145
145
|
|
|
146
|
-
For daily market prices, prefer `lake.query("sec_daily_ohlc", ...)` or the
|
|
147
|
-
canonical OHLC helper. `daily_ohlc` is a legacy/vendor table and may lag the
|
|
148
|
-
canonical daily series.
|
|
149
|
-
|
|
150
146
|
`client.listOrders({ portfolioId, statuses, page, limit })` lists owned orders with a read key. `client.cancelOrders(orderIds, { idempotencyKey, portfolioId })` cancels explicit IDs with a trade key. Inspect both `canceled` and `rejected`, and reuse the same key/payload for retries. Defaults and status gates are documented in README.
|
|
151
147
|
|
|
152
148
|
## Recipes
|
|
@@ -299,23 +295,22 @@ pair.
|
|
|
299
295
|
</details>
|
|
300
296
|
|
|
301
297
|
<details>
|
|
302
|
-
<summary><b>
|
|
298
|
+
<summary><b>Screen stocks in plain language</b></summary>
|
|
299
|
+
|
|
300
|
+
Market data is available only through the natural-language screener.
|
|
303
301
|
|
|
304
302
|
```ts
|
|
305
|
-
const
|
|
306
|
-
|
|
307
|
-
query: "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
|
|
308
|
-
params: ["AAPL"],
|
|
309
|
-
limits: { maxRows: 10_000 },
|
|
310
|
-
},
|
|
311
|
-
{ idempotencyKey: "aapl-daily-v1" },
|
|
303
|
+
const screen = await client.createNlScreen(
|
|
304
|
+
"technology stocks with a market cap over 100 billion and a PE under 30",
|
|
312
305
|
);
|
|
313
|
-
const
|
|
314
|
-
const
|
|
306
|
+
const done = await client.waitForNlScreen(screen.id as string);
|
|
307
|
+
const result = done.result as Record<string, unknown>;
|
|
308
|
+
console.log(result.outcome, result.rows);
|
|
315
309
|
```
|
|
316
310
|
|
|
317
|
-
|
|
318
|
-
|
|
311
|
+
Branch on `result.outcome`. `EMPTY` is an answer, `CLARIFICATION` means the
|
|
312
|
+
question was ambiguous (answer it rather than guessing), and only
|
|
313
|
+
`GENERATION_FAILED` is worth retrying. Spends LLM credits.
|
|
319
314
|
</details>
|
|
320
315
|
|
|
321
316
|
<details>
|
|
@@ -353,7 +348,7 @@ All failures throw `NexusTradeApiError` with a stable `.status`, `.code`, and
|
|
|
353
348
|
| Code | What to do |
|
|
354
349
|
| --- | --- |
|
|
355
350
|
| `invalid_token` | Key missing/expired, or an OAuth JWT was used. Only `sk-` keys work here. |
|
|
356
|
-
| `insufficient_scope` | The key lacks
|
|
351
|
+
| `insufficient_scope` | The key lacks the required scope. Do not retry. |
|
|
357
352
|
| `invalid_portfolio` | The book is malformed — fix the builders, do not retry as-is. |
|
|
358
353
|
| `idempotency_conflict` | Same key, different payload. Version the key. |
|
|
359
354
|
| `idempotency_in_progress` | Same key, first call still running. Wait and re-read; never resubmit. |
|
|
@@ -382,17 +377,6 @@ you did not create in this session as possibly live.
|
|
|
382
377
|
|
|
383
378
|
Not in this SDK. Do not attempt to reach them through it:
|
|
384
379
|
|
|
385
|
-
- ~~**Screener** — MCP only.~~ **The screener is here now:**
|
|
386
|
-
`client.createNlScreen("...")` + `waitForNlScreen(id)` turns a plain-language
|
|
387
|
-
question into validated `lake.*` SQL, runs it, and returns the rows *and the
|
|
388
|
-
statement*. Prefer it over hand-writing SQL for stock selection — the server
|
|
389
|
-
picks tables from the same catalog the validator enforces, so it cannot name
|
|
390
|
-
a column that does not exist. Fall back to `createLakeQuery` only when
|
|
391
|
-
`outcome === "GENERATION_FAILED"`, or when the question is not a stock
|
|
392
|
-
screen. `EMPTY` is an answer, not a fallback trigger, and `CLARIFICATION`
|
|
393
|
-
means the question was ambiguous — answer it rather than guessing SQL. Always
|
|
394
|
-
report `result.sql`: it is model-generated, so it is the only way anyone can
|
|
395
|
-
check the numbers. Spends LLM credits; the lake API does not.
|
|
396
380
|
- **Submitting a live order** — impossible from anywhere, not just here. Live
|
|
397
381
|
orders are staged `PENDING_USER_APPROVAL` and a human approves them in the
|
|
398
382
|
UI; the brokerage boundary refuses an unapproved live order regardless of
|
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
[](LICENSE)
|
|
12
12
|
[](package.json)
|
|
13
13
|
|
|
14
|
-
[Quickstart](#quickstart) · [Authoring](#authoring-strategies) · [Polling](#jobs-run-on-the-engine--you-poll) · [Agents](#agent-runs) · [
|
|
14
|
+
[Quickstart](#quickstart) · [Authoring](#authoring-strategies) · [Polling](#jobs-run-on-the-engine--you-poll) · [Agents](#agent-runs) · [Screener](#natural-language-screener) · [Auth](#authentication) · [Errors](#errors)
|
|
15
15
|
|
|
16
16
|
</div>
|
|
17
17
|
|
|
@@ -345,11 +345,6 @@ Transient network and HTTP 408/429/5xx polling failures retry the same operation
|
|
|
345
345
|
at most twice consecutively, within the wait deadline. Persistent failures keep
|
|
346
346
|
their original error code and operation ID; no new job is submitted.
|
|
347
347
|
|
|
348
|
-
Durable lake exports use a 900-second server budget by default (registered API
|
|
349
|
-
keys may request up to 1800 seconds). `waitForLakeQuery` defaults to 1200 seconds
|
|
350
|
-
to include queue time. Compute token budgets remain 90 seconds by default and
|
|
351
|
-
180 seconds maximum. A client wait timeout does not extend the server budget.
|
|
352
|
-
|
|
353
348
|
**Batches.** `createBacktests` submits many in one request and returns one
|
|
354
349
|
operation each; `waitForBacktests(operations)` waits on all of them. Prefer it
|
|
355
350
|
over a loop: one request, one idempotency key, one rate-limit slot.
|
|
@@ -729,39 +724,10 @@ for await (const event of run) {
|
|
|
729
724
|
}
|
|
730
725
|
```
|
|
731
726
|
|
|
732
|
-
##
|
|
733
|
-
|
|
734
|
-
Read-only SQL over the NexusTrade market-data lake, against the server-resolved
|
|
735
|
-
`lake.*` catalog. Results are durable Parquet parts rather than an implicitly
|
|
736
|
-
materialized in-memory array.
|
|
737
|
-
|
|
738
|
-
```mermaid
|
|
739
|
-
flowchart LR
|
|
740
|
-
A[createLakeQuery] --> B[waitForLakeQuery]
|
|
741
|
-
B --> C[getLakeQueryManifest]
|
|
742
|
-
C --> D[downloadLakeQueryPart]
|
|
743
|
-
D --> E[Stream Parquet within your memory budget]
|
|
744
|
-
```
|
|
745
|
-
|
|
746
|
-
```ts
|
|
747
|
-
const query = await client.createLakeQuery(
|
|
748
|
-
{
|
|
749
|
-
query:
|
|
750
|
-
"SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
|
|
751
|
-
params: ["AAPL"],
|
|
752
|
-
limits: { maxRows: 10_000 },
|
|
753
|
-
},
|
|
754
|
-
{ idempotencyKey: "aapl-daily-v1" }
|
|
755
|
-
);
|
|
756
|
-
const finished = await client.waitForLakeQuery(query.id as string);
|
|
757
|
-
const manifest = await client.getLakeQueryManifest(finished.id as string);
|
|
758
|
-
```
|
|
759
|
-
|
|
760
|
-
## Natural language
|
|
727
|
+
## Natural-language screener
|
|
761
728
|
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
and hands back both the rows and the statement.
|
|
729
|
+
Market data is available through the natural-language screener. Describe the
|
|
730
|
+
screen in plain language; the server runs it and returns the matching rows.
|
|
765
731
|
|
|
766
732
|
```ts
|
|
767
733
|
const screen = await client.createNlScreen(
|
|
@@ -771,13 +737,8 @@ const done = await client.waitForNlScreen(screen.id as string);
|
|
|
771
737
|
|
|
772
738
|
const result = done.result as Record<string, unknown>;
|
|
773
739
|
console.log(result.rows);
|
|
774
|
-
console.log(result.sql); // always check the SQL — it is model-generated
|
|
775
740
|
```
|
|
776
741
|
|
|
777
|
-
`returnQuery` defaults to `true` because the SQL is the audit trail: without it
|
|
778
|
-
the rows are a number you cannot re-derive. It is returned on failure whatever
|
|
779
|
-
you pass, since a rejected query is the most useful thing to read.
|
|
780
|
-
|
|
781
742
|
Branch on `result.outcome`, not on status alone:
|
|
782
743
|
|
|
783
744
|
| `outcome` | Meaning |
|
|
@@ -787,14 +748,7 @@ Branch on `result.outcome`, not on status alone:
|
|
|
787
748
|
| `CLARIFICATION` | The question was ambiguous; `result.clarification` asks |
|
|
788
749
|
| `GENERATION_FAILED` | The retry budget was spent — the only case worth retrying |
|
|
789
750
|
|
|
790
|
-
This method spends LLM credits.
|
|
791
|
-
|
|
792
|
-
Use the manifest plus `downloadLakeQueryPart` to stream results within your own
|
|
793
|
-
memory budget. NexusTrade picks a compatible backing engine for the referenced
|
|
794
|
-
tables; your SQL does not change when it does.
|
|
795
|
-
|
|
796
|
-
> The Python SDK additionally ships `nt.lake.sql(...)`, a DuckDB/pandas
|
|
797
|
-
> convenience layer over these same endpoints.
|
|
751
|
+
This method spends LLM credits.
|
|
798
752
|
|
|
799
753
|
## Managed watchlist universes
|
|
800
754
|
|
|
@@ -850,8 +804,7 @@ between refreshes. Missing facts remain unknown. `screenAny` composes OR rules;
|
|
|
850
804
|
`screenBarVolume` and `screenBarDollarVolume` require a completed historical
|
|
851
805
|
bar; live quotes do not supply those metrics in this release. Price and disclosure
|
|
852
806
|
metrics support live screens. Failed coverage or publication blocks new allocation
|
|
853
|
-
while consumers retain their exit behavior.
|
|
854
|
-
no local database volume or LLM call is required for refreshes.
|
|
807
|
+
while consumers retain their exit behavior. Refreshes make no LLM call.
|
|
855
808
|
|
|
856
809
|
## Complete method reference
|
|
857
810
|
|
|
@@ -929,31 +882,14 @@ is missing here, so this list cannot drift from the code.
|
|
|
929
882
|
| `getAgent(agentId)` | Read its status |
|
|
930
883
|
| `attachAgent(agentId, { cursor })` | Reattach to a run already in flight |
|
|
931
884
|
|
|
932
|
-
**Lake SQL**
|
|
933
|
-
|
|
934
|
-
| Method | Purpose |
|
|
935
|
-
| ----------------------------------------------- | ------------------------------------ |
|
|
936
|
-
| `createLakeQuery(request, { idempotencyKey })` | Submit read-only SQL |
|
|
937
|
-
| `getLakeQuery(queryId)` | Read the operation |
|
|
938
|
-
| `waitForLakeQuery(queryId, options)` | Block until terminal |
|
|
939
|
-
| `cancelLakeQuery(queryId)` | Cancel an owned query |
|
|
940
|
-
| `createLakeAsk(question)` | Ask the lake in plain language |
|
|
941
|
-
| `getLakeAsk(askId)` | Read the operation |
|
|
942
|
-
| `waitForLakeAsk(askId, options)` | Block until terminal |
|
|
943
|
-
| `cancelLakeAsk(askId)` | Cancel an owned ask |
|
|
944
|
-
| `getLakeQueryManifest(queryId)` | Schema, checksums, and part metadata |
|
|
945
|
-
| `downloadLakeQueryPart(queryId, part, options)` | Download one Parquet part |
|
|
946
|
-
| `getLakeCatalog()` | List queryable tables |
|
|
947
|
-
| `describeLakeTable(table)` | Columns and types for one table |
|
|
948
|
-
|
|
949
885
|
**Natural language**
|
|
950
886
|
|
|
951
|
-
| Method
|
|
952
|
-
|
|
|
953
|
-
| `createNlScreen(question
|
|
954
|
-
| `getNlScreen(screenId)`
|
|
955
|
-
| `waitForNlScreen(screenId, options)`
|
|
956
|
-
| `cancelNlScreen(screenId)`
|
|
887
|
+
| Method | Purpose |
|
|
888
|
+
| ------------------------------------ | -------------------------------------------- |
|
|
889
|
+
| `createNlScreen(question)` | Screen stocks from a plain-language question |
|
|
890
|
+
| `getNlScreen(screenId)` | Read the operation |
|
|
891
|
+
| `waitForNlScreen(screenId, options)` | Block until terminal |
|
|
892
|
+
| `cancelNlScreen(screenId)` | Cancel an owned screen |
|
|
957
893
|
|
|
958
894
|
**Client construction**
|
|
959
895
|
|
|
@@ -1029,9 +965,8 @@ written back to `process.env`. Opt out with `NEXUSTRADE_DISABLE_DOTENV=1`.
|
|
|
1029
965
|
|
|
1030
966
|
| Scope | Grants |
|
|
1031
967
|
| ------- | --------------------------------------------------------------------------------- |
|
|
1032
|
-
| `read` | Portfolio, backtest, genetic, sweep, and walk-forward reads
|
|
968
|
+
| `read` | Portfolio, backtest, genetic, sweep, and walk-forward reads; NL screens |
|
|
1033
969
|
| `write` | Portfolio create/edit/fork, backtests, genetic/sweep, and walk-forward launches |
|
|
1034
|
-
| `lake` | Lake catalog, query lifecycle, manifests, result parts |
|
|
1035
970
|
|
|
1036
971
|
A key missing the scope gets `403 insufficient_scope`.
|
|
1037
972
|
|
|
@@ -1076,7 +1011,7 @@ try {
|
|
|
1076
1011
|
| Status | Code | Meaning |
|
|
1077
1012
|
| ------ | -------------------------------------- | ------------------------------------------------------------ |
|
|
1078
1013
|
| 401 | `invalid_token` | Missing, malformed, or expired key (or an OAuth JWT) |
|
|
1079
|
-
| 403 | `insufficient_scope` | Key lacks
|
|
1014
|
+
| 403 | `insufficient_scope` | Key lacks the required scope |
|
|
1080
1015
|
| 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
|
|
1081
1016
|
| 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
|
|
1082
1017
|
| 409 | `idempotency_conflict` | Key reused with a different payload |
|
|
@@ -1096,11 +1031,12 @@ _job_ takes.
|
|
|
1096
1031
|
|
|
1097
1032
|
## Scope
|
|
1098
1033
|
|
|
1099
|
-
Portfolio drafting, backtesting, optimization, walk-forward studies, and
|
|
1100
|
-
|
|
1034
|
+
Portfolio drafting, backtesting, optimization, walk-forward studies, and the
|
|
1035
|
+
natural-language screener, versioned under `/api/v1/nexustrade`. Market data is
|
|
1036
|
+
available only through the natural-language screener.
|
|
1101
1037
|
The full surface requires a registered API key; anonymous workspaces are limited
|
|
1102
1038
|
to portfolio authoring/forking, backtests, and programmatic agent/chat calls.
|
|
1103
|
-
|
|
1039
|
+
Creating a live deployment remains outside this surface.
|
|
1104
1040
|
Orders are reachable, but a live order is only ever staged for human approval —
|
|
1105
1041
|
never submitted. `deploy` and `undeploy` act on whatever an existing id already
|
|
1106
1042
|
is, live included.
|
package/dist/cjs/client.js
CHANGED
|
@@ -44,8 +44,7 @@ function encodeQuery(params) {
|
|
|
44
44
|
}
|
|
45
45
|
const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
|
|
46
46
|
const MAX_ERROR_BYTES = 64 * 1024;
|
|
47
|
-
// Keep in lockstep with _MAX_REDIRECTS in sdk/python/nexustrade/client.py
|
|
48
|
-
// checkSdkClientParity.ts asserts the two numbers match.
|
|
47
|
+
// Keep in lockstep with _MAX_REDIRECTS in sdk/python/nexustrade/client.py.
|
|
49
48
|
const MAX_REDIRECTS = 5;
|
|
50
49
|
// `status` for errors no HTTP status describes: the request never reached the
|
|
51
50
|
// API, or it returned 2xx with an envelope the client could not use. Reporting
|
|
@@ -56,7 +55,7 @@ exports.WORKSPACE_SESSION_HEADER = "X-NexusTrade-Session";
|
|
|
56
55
|
// Polling defaults. Every NexusTrade job — backtest, optimization,
|
|
57
56
|
// walk-forward, and any future operation kind — reports through the same
|
|
58
57
|
// envelope, so one poller serves all of them. Kept in lockstep with the Python
|
|
59
|
-
// SDK
|
|
58
|
+
// SDK; the backoff is deterministic (no jitter) so
|
|
60
59
|
// both languages issue the identical request sequence.
|
|
61
60
|
exports.DEFAULT_POLL_TIMEOUT_SECONDS = 900;
|
|
62
61
|
exports.DEFAULT_POLL_INTERVAL_SECONDS = 2;
|
|
@@ -85,7 +84,7 @@ const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
|
|
|
85
84
|
// A presigned PUT crosses the open internet with no API-side retry behind it, so
|
|
86
85
|
// the client owns transient recovery. Jittered (unlike the poll backoff) because
|
|
87
86
|
// every client retrying a storage blip on the same schedule is the blip.
|
|
88
|
-
//
|
|
87
|
+
// Kept in lockstep with the Python SDK.
|
|
89
88
|
exports.MAX_UPLOAD_PUT_ATTEMPTS = 5;
|
|
90
89
|
exports.UPLOAD_PUT_INITIAL_BACKOFF_SECONDS = 0.5;
|
|
91
90
|
exports.UPLOAD_PUT_MAX_BACKOFF_SECONDS = 8.0;
|
|
@@ -160,9 +159,6 @@ function sameOrigin(left, right) {
|
|
|
160
159
|
const b = origin(right);
|
|
161
160
|
return a.scheme === b.scheme && a.host === b.host && a.port === b.port;
|
|
162
161
|
}
|
|
163
|
-
function supportsBinary(transport) {
|
|
164
|
-
return typeof transport.requestBytes === "function";
|
|
165
|
-
}
|
|
166
162
|
function supportsUpload(transport) {
|
|
167
163
|
return typeof transport.putBytes === "function";
|
|
168
164
|
}
|
|
@@ -1413,33 +1409,10 @@ class NexusTradeClient {
|
|
|
1413
1409
|
const response = await this.transport.request("GET", `walk-forward-studies/${encodePathSegment(studyId)}`);
|
|
1414
1410
|
return operationOf(response);
|
|
1415
1411
|
}
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
body: request,
|
|
1419
|
-
idempotencyKey: options.idempotencyKey,
|
|
1420
|
-
});
|
|
1421
|
-
return operationOf(response);
|
|
1422
|
-
}
|
|
1423
|
-
async getLakeQuery(queryId) {
|
|
1424
|
-
return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}`));
|
|
1425
|
-
}
|
|
1426
|
-
async cancelLakeQuery(queryId) {
|
|
1427
|
-
return operationOf(await this.transport.request("POST", `lake/queries/${encodePathSegment(queryId)}/cancel`));
|
|
1428
|
-
}
|
|
1429
|
-
/**
|
|
1430
|
-
* Submit a natural-language stock screen. Returns immediately; poll it.
|
|
1431
|
-
*
|
|
1432
|
-
* `returnQuery` keeps the generated SQL, engine and catalog version on the
|
|
1433
|
-
* result. It defaults on: the SQL is the audit trail, and without it the rows
|
|
1434
|
-
* are a number nobody can re-derive. It is returned on failure regardless,
|
|
1435
|
-
* because a rejected query is the most useful thing to read.
|
|
1436
|
-
*/
|
|
1437
|
-
async createNlScreen(question, options = {}) {
|
|
1412
|
+
/** Submit a natural-language stock screen. Returns immediately; poll it. */
|
|
1413
|
+
async createNlScreen(question) {
|
|
1438
1414
|
return operationOf(await this.transport.request("POST", "nl/screens", {
|
|
1439
|
-
body: {
|
|
1440
|
-
question,
|
|
1441
|
-
returnQuery: options.returnQuery ?? true,
|
|
1442
|
-
},
|
|
1415
|
+
body: { question },
|
|
1443
1416
|
}));
|
|
1444
1417
|
}
|
|
1445
1418
|
async getNlScreen(screenId) {
|
|
@@ -1452,55 +1425,6 @@ class NexusTradeClient {
|
|
|
1452
1425
|
async waitForNlScreen(screenId, options = {}) {
|
|
1453
1426
|
return waitForOperation((id) => this.getNlScreen(id), screenId, options);
|
|
1454
1427
|
}
|
|
1455
|
-
/**
|
|
1456
|
-
* Submit a natural-language lake ask. Returns immediately; poll it.
|
|
1457
|
-
*/
|
|
1458
|
-
async createLakeAsk(question) {
|
|
1459
|
-
return operationOf(await this.transport.request("POST", "lake/ask", {
|
|
1460
|
-
body: { question },
|
|
1461
|
-
}));
|
|
1462
|
-
}
|
|
1463
|
-
async getLakeAsk(askId) {
|
|
1464
|
-
return operationOf(await this.transport.request("GET", `lake/ask/${encodePathSegment(askId)}`));
|
|
1465
|
-
}
|
|
1466
|
-
async cancelLakeAsk(askId) {
|
|
1467
|
-
return operationOf(await this.transport.request("POST", `lake/ask/${encodePathSegment(askId)}/cancel`));
|
|
1468
|
-
}
|
|
1469
|
-
/** Block until a lake ask is terminal. See `waitForOperation`. */
|
|
1470
|
-
async waitForLakeAsk(askId, options = {}) {
|
|
1471
|
-
return waitForOperation((id) => this.getLakeAsk(id), askId, options);
|
|
1472
|
-
}
|
|
1473
|
-
async getLakeQueryManifest(queryId) {
|
|
1474
|
-
return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}/manifest`));
|
|
1475
|
-
}
|
|
1476
|
-
async getLakeCatalog() {
|
|
1477
|
-
const response = await this.transport.request("GET", "lake/catalog");
|
|
1478
|
-
const tables = response.tables;
|
|
1479
|
-
if (!Array.isArray(tables) || !tables.every((t) => isJsonObject(t))) {
|
|
1480
|
-
throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "invalid_response", "Lake catalog response is missing tables.");
|
|
1481
|
-
}
|
|
1482
|
-
return tables;
|
|
1483
|
-
}
|
|
1484
|
-
async describeLakeTable(table) {
|
|
1485
|
-
const name = table.startsWith("lake.") ? table.slice(5) : table;
|
|
1486
|
-
const response = await this.transport.request("GET", `lake/catalog/lake/${encodePathSegment(name)}`);
|
|
1487
|
-
const described = response.table;
|
|
1488
|
-
if (!isJsonObject(described)) {
|
|
1489
|
-
throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "invalid_response", "Lake describe response is missing table.");
|
|
1490
|
-
}
|
|
1491
|
-
return described;
|
|
1492
|
-
}
|
|
1493
|
-
/** Download one Parquet part, optionally a byte range of it. */
|
|
1494
|
-
async downloadLakeQueryPart(queryId, part, options = {}) {
|
|
1495
|
-
if (!supportsBinary(this.transport)) {
|
|
1496
|
-
throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "unsupported_transport", "Lake part download requires a transport implementing requestBytes.");
|
|
1497
|
-
}
|
|
1498
|
-
return this.transport.requestBytes("GET", `lake/queries/${encodePathSegment(queryId)}/parts/${Math.trunc(part)}`, options);
|
|
1499
|
-
}
|
|
1500
|
-
/** Resolve once a lake query is terminal. See `waitForOperation`. */
|
|
1501
|
-
async waitForLakeQuery(queryId, options = {}) {
|
|
1502
|
-
return waitForOperation((id) => this.getLakeQuery(id), queryId, { ...options, timeoutSeconds: options.timeoutSeconds ?? 1200 });
|
|
1503
|
-
}
|
|
1504
1428
|
/** Resolve once a backtest is terminal. See `waitForOperation`. */
|
|
1505
1429
|
async waitForBacktest(backtestId, options = {}) {
|
|
1506
1430
|
return waitForOperation((id) => this.getBacktest(id), backtestId, options);
|
package/dist/esm/client.d.ts
CHANGED
|
@@ -139,20 +139,6 @@ export interface RequestOptions {
|
|
|
139
139
|
export interface Transport {
|
|
140
140
|
request(method: string, path: string, options?: RequestOptions): Promise<JsonObject>;
|
|
141
141
|
}
|
|
142
|
-
/**
|
|
143
|
-
* Transports that can also return raw bytes.
|
|
144
|
-
*
|
|
145
|
-
* Lake result parts are Parquet, so they do not fit `Transport`, which is a
|
|
146
|
-
* JSON contract. Declaring the capability keeps custom and test transports able
|
|
147
|
-
* to implement downloads through a typed interface instead of a duck-typed
|
|
148
|
-
* check.
|
|
149
|
-
*/
|
|
150
|
-
export interface BinaryTransport extends Transport {
|
|
151
|
-
requestBytes(method: string, path: string, options?: {
|
|
152
|
-
byteRange?: [number, number];
|
|
153
|
-
maxBytes?: number;
|
|
154
|
-
}): Promise<Uint8Array>;
|
|
155
|
-
}
|
|
156
142
|
/**
|
|
157
143
|
* Transports that can PUT bytes to a presigned storage URL.
|
|
158
144
|
*
|
|
@@ -482,44 +468,12 @@ export declare class NexusTradeClient {
|
|
|
482
468
|
idempotencyKey: string;
|
|
483
469
|
}): Promise<JsonObject>;
|
|
484
470
|
getWalkForward(studyId: string): Promise<JsonObject>;
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
}): Promise<JsonObject>;
|
|
488
|
-
getLakeQuery(queryId: string): Promise<JsonObject>;
|
|
489
|
-
cancelLakeQuery(queryId: string): Promise<JsonObject>;
|
|
490
|
-
/**
|
|
491
|
-
* Submit a natural-language stock screen. Returns immediately; poll it.
|
|
492
|
-
*
|
|
493
|
-
* `returnQuery` keeps the generated SQL, engine and catalog version on the
|
|
494
|
-
* result. It defaults on: the SQL is the audit trail, and without it the rows
|
|
495
|
-
* are a number nobody can re-derive. It is returned on failure regardless,
|
|
496
|
-
* because a rejected query is the most useful thing to read.
|
|
497
|
-
*/
|
|
498
|
-
createNlScreen(question: string, options?: {
|
|
499
|
-
returnQuery?: boolean;
|
|
500
|
-
}): Promise<JsonObject>;
|
|
471
|
+
/** Submit a natural-language stock screen. Returns immediately; poll it. */
|
|
472
|
+
createNlScreen(question: string): Promise<JsonObject>;
|
|
501
473
|
getNlScreen(screenId: string): Promise<JsonObject>;
|
|
502
474
|
cancelNlScreen(screenId: string): Promise<JsonObject>;
|
|
503
475
|
/** Block until a screen is terminal. See `waitForOperation`. */
|
|
504
476
|
waitForNlScreen(screenId: string, options?: WaitOptions): Promise<JsonObject>;
|
|
505
|
-
/**
|
|
506
|
-
* Submit a natural-language lake ask. Returns immediately; poll it.
|
|
507
|
-
*/
|
|
508
|
-
createLakeAsk(question: string): Promise<JsonObject>;
|
|
509
|
-
getLakeAsk(askId: string): Promise<JsonObject>;
|
|
510
|
-
cancelLakeAsk(askId: string): Promise<JsonObject>;
|
|
511
|
-
/** Block until a lake ask is terminal. See `waitForOperation`. */
|
|
512
|
-
waitForLakeAsk(askId: string, options?: WaitOptions): Promise<JsonObject>;
|
|
513
|
-
getLakeQueryManifest(queryId: string): Promise<JsonObject>;
|
|
514
|
-
getLakeCatalog(): Promise<JsonObject[]>;
|
|
515
|
-
describeLakeTable(table: string): Promise<JsonObject>;
|
|
516
|
-
/** Download one Parquet part, optionally a byte range of it. */
|
|
517
|
-
downloadLakeQueryPart(queryId: string, part: number, options?: {
|
|
518
|
-
byteRange?: [number, number];
|
|
519
|
-
maxBytes?: number;
|
|
520
|
-
}): Promise<Uint8Array>;
|
|
521
|
-
/** Resolve once a lake query is terminal. See `waitForOperation`. */
|
|
522
|
-
waitForLakeQuery(queryId: string, options?: WaitOptions): Promise<JsonObject>;
|
|
523
477
|
/** Resolve once a backtest is terminal. See `waitForOperation`. */
|
|
524
478
|
waitForBacktest(backtestId: string, options?: WaitOptions): Promise<JsonObject>;
|
|
525
479
|
/** Resolve once an optimization is terminal. See `waitForOperation`. */
|
package/dist/esm/client.js
CHANGED
|
@@ -37,8 +37,7 @@ function encodeQuery(params) {
|
|
|
37
37
|
}
|
|
38
38
|
const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
|
|
39
39
|
const MAX_ERROR_BYTES = 64 * 1024;
|
|
40
|
-
// Keep in lockstep with _MAX_REDIRECTS in sdk/python/nexustrade/client.py
|
|
41
|
-
// checkSdkClientParity.ts asserts the two numbers match.
|
|
40
|
+
// Keep in lockstep with _MAX_REDIRECTS in sdk/python/nexustrade/client.py.
|
|
42
41
|
const MAX_REDIRECTS = 5;
|
|
43
42
|
// `status` for errors no HTTP status describes: the request never reached the
|
|
44
43
|
// API, or it returned 2xx with an envelope the client could not use. Reporting
|
|
@@ -49,7 +48,7 @@ export const WORKSPACE_SESSION_HEADER = "X-NexusTrade-Session";
|
|
|
49
48
|
// Polling defaults. Every NexusTrade job — backtest, optimization,
|
|
50
49
|
// walk-forward, and any future operation kind — reports through the same
|
|
51
50
|
// envelope, so one poller serves all of them. Kept in lockstep with the Python
|
|
52
|
-
// SDK
|
|
51
|
+
// SDK; the backoff is deterministic (no jitter) so
|
|
53
52
|
// both languages issue the identical request sequence.
|
|
54
53
|
export const DEFAULT_POLL_TIMEOUT_SECONDS = 900;
|
|
55
54
|
export const DEFAULT_POLL_INTERVAL_SECONDS = 2;
|
|
@@ -78,7 +77,7 @@ const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
|
|
|
78
77
|
// A presigned PUT crosses the open internet with no API-side retry behind it, so
|
|
79
78
|
// the client owns transient recovery. Jittered (unlike the poll backoff) because
|
|
80
79
|
// every client retrying a storage blip on the same schedule is the blip.
|
|
81
|
-
//
|
|
80
|
+
// Kept in lockstep with the Python SDK.
|
|
82
81
|
export const MAX_UPLOAD_PUT_ATTEMPTS = 5;
|
|
83
82
|
export const UPLOAD_PUT_INITIAL_BACKOFF_SECONDS = 0.5;
|
|
84
83
|
export const UPLOAD_PUT_MAX_BACKOFF_SECONDS = 8.0;
|
|
@@ -151,9 +150,6 @@ function sameOrigin(left, right) {
|
|
|
151
150
|
const b = origin(right);
|
|
152
151
|
return a.scheme === b.scheme && a.host === b.host && a.port === b.port;
|
|
153
152
|
}
|
|
154
|
-
function supportsBinary(transport) {
|
|
155
|
-
return typeof transport.requestBytes === "function";
|
|
156
|
-
}
|
|
157
153
|
function supportsUpload(transport) {
|
|
158
154
|
return typeof transport.putBytes === "function";
|
|
159
155
|
}
|
|
@@ -1403,33 +1399,10 @@ export class NexusTradeClient {
|
|
|
1403
1399
|
const response = await this.transport.request("GET", `walk-forward-studies/${encodePathSegment(studyId)}`);
|
|
1404
1400
|
return operationOf(response);
|
|
1405
1401
|
}
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
body: request,
|
|
1409
|
-
idempotencyKey: options.idempotencyKey,
|
|
1410
|
-
});
|
|
1411
|
-
return operationOf(response);
|
|
1412
|
-
}
|
|
1413
|
-
async getLakeQuery(queryId) {
|
|
1414
|
-
return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}`));
|
|
1415
|
-
}
|
|
1416
|
-
async cancelLakeQuery(queryId) {
|
|
1417
|
-
return operationOf(await this.transport.request("POST", `lake/queries/${encodePathSegment(queryId)}/cancel`));
|
|
1418
|
-
}
|
|
1419
|
-
/**
|
|
1420
|
-
* Submit a natural-language stock screen. Returns immediately; poll it.
|
|
1421
|
-
*
|
|
1422
|
-
* `returnQuery` keeps the generated SQL, engine and catalog version on the
|
|
1423
|
-
* result. It defaults on: the SQL is the audit trail, and without it the rows
|
|
1424
|
-
* are a number nobody can re-derive. It is returned on failure regardless,
|
|
1425
|
-
* because a rejected query is the most useful thing to read.
|
|
1426
|
-
*/
|
|
1427
|
-
async createNlScreen(question, options = {}) {
|
|
1402
|
+
/** Submit a natural-language stock screen. Returns immediately; poll it. */
|
|
1403
|
+
async createNlScreen(question) {
|
|
1428
1404
|
return operationOf(await this.transport.request("POST", "nl/screens", {
|
|
1429
|
-
body: {
|
|
1430
|
-
question,
|
|
1431
|
-
returnQuery: options.returnQuery ?? true,
|
|
1432
|
-
},
|
|
1405
|
+
body: { question },
|
|
1433
1406
|
}));
|
|
1434
1407
|
}
|
|
1435
1408
|
async getNlScreen(screenId) {
|
|
@@ -1442,55 +1415,6 @@ export class NexusTradeClient {
|
|
|
1442
1415
|
async waitForNlScreen(screenId, options = {}) {
|
|
1443
1416
|
return waitForOperation((id) => this.getNlScreen(id), screenId, options);
|
|
1444
1417
|
}
|
|
1445
|
-
/**
|
|
1446
|
-
* Submit a natural-language lake ask. Returns immediately; poll it.
|
|
1447
|
-
*/
|
|
1448
|
-
async createLakeAsk(question) {
|
|
1449
|
-
return operationOf(await this.transport.request("POST", "lake/ask", {
|
|
1450
|
-
body: { question },
|
|
1451
|
-
}));
|
|
1452
|
-
}
|
|
1453
|
-
async getLakeAsk(askId) {
|
|
1454
|
-
return operationOf(await this.transport.request("GET", `lake/ask/${encodePathSegment(askId)}`));
|
|
1455
|
-
}
|
|
1456
|
-
async cancelLakeAsk(askId) {
|
|
1457
|
-
return operationOf(await this.transport.request("POST", `lake/ask/${encodePathSegment(askId)}/cancel`));
|
|
1458
|
-
}
|
|
1459
|
-
/** Block until a lake ask is terminal. See `waitForOperation`. */
|
|
1460
|
-
async waitForLakeAsk(askId, options = {}) {
|
|
1461
|
-
return waitForOperation((id) => this.getLakeAsk(id), askId, options);
|
|
1462
|
-
}
|
|
1463
|
-
async getLakeQueryManifest(queryId) {
|
|
1464
|
-
return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}/manifest`));
|
|
1465
|
-
}
|
|
1466
|
-
async getLakeCatalog() {
|
|
1467
|
-
const response = await this.transport.request("GET", "lake/catalog");
|
|
1468
|
-
const tables = response.tables;
|
|
1469
|
-
if (!Array.isArray(tables) || !tables.every((t) => isJsonObject(t))) {
|
|
1470
|
-
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Lake catalog response is missing tables.");
|
|
1471
|
-
}
|
|
1472
|
-
return tables;
|
|
1473
|
-
}
|
|
1474
|
-
async describeLakeTable(table) {
|
|
1475
|
-
const name = table.startsWith("lake.") ? table.slice(5) : table;
|
|
1476
|
-
const response = await this.transport.request("GET", `lake/catalog/lake/${encodePathSegment(name)}`);
|
|
1477
|
-
const described = response.table;
|
|
1478
|
-
if (!isJsonObject(described)) {
|
|
1479
|
-
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Lake describe response is missing table.");
|
|
1480
|
-
}
|
|
1481
|
-
return described;
|
|
1482
|
-
}
|
|
1483
|
-
/** Download one Parquet part, optionally a byte range of it. */
|
|
1484
|
-
async downloadLakeQueryPart(queryId, part, options = {}) {
|
|
1485
|
-
if (!supportsBinary(this.transport)) {
|
|
1486
|
-
throw new NexusTradeApiError(NO_HTTP_STATUS, "unsupported_transport", "Lake part download requires a transport implementing requestBytes.");
|
|
1487
|
-
}
|
|
1488
|
-
return this.transport.requestBytes("GET", `lake/queries/${encodePathSegment(queryId)}/parts/${Math.trunc(part)}`, options);
|
|
1489
|
-
}
|
|
1490
|
-
/** Resolve once a lake query is terminal. See `waitForOperation`. */
|
|
1491
|
-
async waitForLakeQuery(queryId, options = {}) {
|
|
1492
|
-
return waitForOperation((id) => this.getLakeQuery(id), queryId, { ...options, timeoutSeconds: options.timeoutSeconds ?? 1200 });
|
|
1493
|
-
}
|
|
1494
1418
|
/** Resolve once a backtest is terminal. See `waitForOperation`. */
|
|
1495
1419
|
async waitForBacktest(backtestId, options = {}) {
|
|
1496
1420
|
return waitForOperation((id) => this.getBacktest(id), backtestId, options);
|
|
@@ -1901,7 +1901,7 @@ export interface BacktestConfig {
|
|
|
1901
1901
|
interval?: "Day" | "Minute";
|
|
1902
1902
|
/** Starting portfolio value (default 10000) Range 1..inf. */
|
|
1903
1903
|
initialValue?: number;
|
|
1904
|
-
/** Generate detailed event data (signals, orders, audits) during backtest. Costs 5x research tokens. Events are
|
|
1904
|
+
/** Generate detailed event data (signals, orders, audits) during backtest. Costs 5x research tokens. Events are retained for 3 days. Use query_backtest_events to explore them while retained. */
|
|
1905
1905
|
generateEvents?: boolean;
|
|
1906
1906
|
/** Create and execute a fresh backtest instead of reusing a prior identical result. Defaults to false. Requires portfolio_id. Use for an explicitly requested rerun or warm-cache timing; this reruns the simulation and incurs the normal backtest cost. */
|
|
1907
1907
|
forceNewRun?: boolean;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nexustrade",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and
|
|
3
|
+
"version": "5.0.0",
|
|
4
|
+
"description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, optimization, and natural-language stock screening",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Starks Technology",
|
|
7
7
|
"repository": {
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
"trading",
|
|
15
15
|
"backtesting",
|
|
16
16
|
"algorithmic-trading",
|
|
17
|
-
"portfolio"
|
|
17
|
+
"portfolio",
|
|
18
|
+
"stock-screener"
|
|
18
19
|
],
|
|
19
20
|
"type": "module",
|
|
20
21
|
"main": "./dist/cjs/index.js",
|