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 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>Query the data lake</b></summary>
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 query = await client.createLakeQuery(
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 finished = await client.waitForLakeQuery(query.id as string);
314
- const manifest = await client.getLakeQueryManifest(finished.id as string);
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
- Always parameterize with `?` rather than interpolating into the SQL string.
318
- Stream parts with `downloadLakeQueryPart` instead of materializing large results.
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 `read` / `write` / `lake`. Do not retry. |
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](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) · [Agents](#agent-runs) · [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) · [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
- ## Lake SQL
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
- Describe the screen instead of writing the SQL. The server generates it,
763
- validates it against the same `lake.*` catalog the engine reads, executes it,
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. The structured `lake` API below does not.
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. Screen execution uses in-memory DuckDB;
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 | Purpose |
952
- | ------------------------------------------- | ------------------------------------------- |
953
- | `createNlScreen(question, { returnQuery })` | Screen stocks from a plain-language question |
954
- | `getNlScreen(screenId)` | Read the operation |
955
- | `waitForNlScreen(screenId, options)` | Block until terminal |
956
- | `cancelNlScreen(screenId)` | Cancel an owned screen |
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 `read`, `write`, or `lake` |
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
- read-only SQL over the market-data lake, versioned under `/api/v1/nexustrade`.
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
- The screener and creating a live deployment remain outside this surface.
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.
@@ -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 by checkSdkClientParity.ts; the backoff is deterministic (no jitter) so
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
- // checkSdkClientParity.ts asserts these match the Python SDK.
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
- async createLakeQuery(request, options) {
1417
- const response = await this.transport.request("POST", "lake/queries", {
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);
@@ -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
- createLakeQuery(request: JsonObject, options: {
486
- idempotencyKey: string;
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`. */
@@ -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 by checkSdkClientParity.ts; the backoff is deterministic (no jitter) so
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
- // checkSdkClientParity.ts asserts these match the Python SDK.
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
- async createLakeQuery(request, options) {
1407
- const response = await this.transport.request("POST", "lake/queries", {
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 Mongo hot-store traces retained for 3 days. Use query_backtest_events to explore them while retained. */
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.0.0",
4
- "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
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",