nexustrade 3.2.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>
@@ -328,7 +323,6 @@ ones the run cannot leave on its own, so the caller is the approver.
328
323
  ```ts
329
324
  const run = await client.createAgent("Find momentum names in the S&P 500", {
330
325
  idempotencyKey: "momentum-scan-v1",
331
- costCeilingUsd: 20,
332
326
  });
333
327
 
334
328
  for await (const event of run) {
@@ -354,7 +348,7 @@ All failures throw `NexusTradeApiError` with a stable `.status`, `.code`, and
354
348
  | Code | What to do |
355
349
  | --- | --- |
356
350
  | `invalid_token` | Key missing/expired, or an OAuth JWT was used. Only `sk-` keys work here. |
357
- | `insufficient_scope` | The key lacks `read` / `write` / `lake`. Do not retry. |
351
+ | `insufficient_scope` | The key lacks the required scope. Do not retry. |
358
352
  | `invalid_portfolio` | The book is malformed — fix the builders, do not retry as-is. |
359
353
  | `idempotency_conflict` | Same key, different payload. Version the key. |
360
354
  | `idempotency_in_progress` | Same key, first call still running. Wait and re-read; never resubmit. |
@@ -383,17 +377,6 @@ you did not create in this session as possibly live.
383
377
 
384
378
  Not in this SDK. Do not attempt to reach them through it:
385
379
 
386
- - ~~**Screener** — MCP only.~~ **The screener is here now:**
387
- `client.createNlScreen("...")` + `waitForNlScreen(id)` turns a plain-language
388
- question into validated `lake.*` SQL, runs it, and returns the rows *and the
389
- statement*. Prefer it over hand-writing SQL for stock selection — the server
390
- picks tables from the same catalog the validator enforces, so it cannot name
391
- a column that does not exist. Fall back to `createLakeQuery` only when
392
- `outcome === "GENERATION_FAILED"`, or when the question is not a stock
393
- screen. `EMPTY` is an answer, not a fallback trigger, and `CLARIFICATION`
394
- means the question was ambiguous — answer it rather than guessing SQL. Always
395
- report `result.sql`: it is model-generated, so it is the only way anyone can
396
- check the numbers. Spends LLM credits; the lake API does not.
397
380
  - **Submitting a live order** — impossible from anywhere, not just here. Live
398
381
  orders are staged `PENDING_USER_APPROVAL` and a human approves them in the
399
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.
@@ -721,7 +716,6 @@ sequenceDiagram
721
716
  ```ts
722
717
  const run = await client.createAgent("Find momentum names in the S&P 500", {
723
718
  idempotencyKey: "momentum-scan-v1",
724
- costCeilingUsd: 20,
725
719
  });
726
720
  for await (const event of run) {
727
721
  console.log(event.text);
@@ -730,39 +724,10 @@ for await (const event of run) {
730
724
  }
731
725
  ```
732
726
 
733
- ## Lake SQL
734
-
735
- Read-only SQL over the NexusTrade market-data lake, against the server-resolved
736
- `lake.*` catalog. Results are durable Parquet parts rather than an implicitly
737
- materialized in-memory array.
738
-
739
- ```mermaid
740
- flowchart LR
741
- A[createLakeQuery] --> B[waitForLakeQuery]
742
- B --> C[getLakeQueryManifest]
743
- C --> D[downloadLakeQueryPart]
744
- D --> E[Stream Parquet within your memory budget]
745
- ```
746
-
747
- ```ts
748
- const query = await client.createLakeQuery(
749
- {
750
- query:
751
- "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
752
- params: ["AAPL"],
753
- limits: { maxRows: 10_000 },
754
- },
755
- { idempotencyKey: "aapl-daily-v1" }
756
- );
757
- const finished = await client.waitForLakeQuery(query.id as string);
758
- const manifest = await client.getLakeQueryManifest(finished.id as string);
759
- ```
760
-
761
- ## Natural language
727
+ ## Natural-language screener
762
728
 
763
- Describe the screen instead of writing the SQL. The server generates it,
764
- validates it against the same `lake.*` catalog the engine reads, executes it,
765
- 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.
766
731
 
767
732
  ```ts
768
733
  const screen = await client.createNlScreen(
@@ -772,13 +737,8 @@ const done = await client.waitForNlScreen(screen.id as string);
772
737
 
773
738
  const result = done.result as Record<string, unknown>;
774
739
  console.log(result.rows);
775
- console.log(result.sql); // always check the SQL — it is model-generated
776
740
  ```
777
741
 
778
- `returnQuery` defaults to `true` because the SQL is the audit trail: without it
779
- the rows are a number you cannot re-derive. It is returned on failure whatever
780
- you pass, since a rejected query is the most useful thing to read.
781
-
782
742
  Branch on `result.outcome`, not on status alone:
783
743
 
784
744
  | `outcome` | Meaning |
@@ -788,14 +748,7 @@ Branch on `result.outcome`, not on status alone:
788
748
  | `CLARIFICATION` | The question was ambiguous; `result.clarification` asks |
789
749
  | `GENERATION_FAILED` | The retry budget was spent — the only case worth retrying |
790
750
 
791
- This method spends LLM credits. The structured `lake` API below does not.
792
-
793
- Use the manifest plus `downloadLakeQueryPart` to stream results within your own
794
- memory budget. NexusTrade picks a compatible backing engine for the referenced
795
- tables; your SQL does not change when it does.
796
-
797
- > The Python SDK additionally ships `nt.lake.sql(...)`, a DuckDB/pandas
798
- > convenience layer over these same endpoints.
751
+ This method spends LLM credits.
799
752
 
800
753
  ## Managed watchlist universes
801
754
 
@@ -851,8 +804,7 @@ between refreshes. Missing facts remain unknown. `screenAny` composes OR rules;
851
804
  `screenBarVolume` and `screenBarDollarVolume` require a completed historical
852
805
  bar; live quotes do not supply those metrics in this release. Price and disclosure
853
806
  metrics support live screens. Failed coverage or publication blocks new allocation
854
- while consumers retain their exit behavior. Screen execution uses in-memory DuckDB;
855
- no local database volume or LLM call is required for refreshes.
807
+ while consumers retain their exit behavior. Refreshes make no LLM call.
856
808
 
857
809
  ## Complete method reference
858
810
 
@@ -930,31 +882,14 @@ is missing here, so this list cannot drift from the code.
930
882
  | `getAgent(agentId)` | Read its status |
931
883
  | `attachAgent(agentId, { cursor })` | Reattach to a run already in flight |
932
884
 
933
- **Lake SQL**
934
-
935
- | Method | Purpose |
936
- | ----------------------------------------------- | ------------------------------------ |
937
- | `createLakeQuery(request, { idempotencyKey })` | Submit read-only SQL |
938
- | `getLakeQuery(queryId)` | Read the operation |
939
- | `waitForLakeQuery(queryId, options)` | Block until terminal |
940
- | `cancelLakeQuery(queryId)` | Cancel an owned query |
941
- | `createLakeAsk(question)` | Ask the lake in plain language |
942
- | `getLakeAsk(askId)` | Read the operation |
943
- | `waitForLakeAsk(askId, options)` | Block until terminal |
944
- | `cancelLakeAsk(askId)` | Cancel an owned ask |
945
- | `getLakeQueryManifest(queryId)` | Schema, checksums, and part metadata |
946
- | `downloadLakeQueryPart(queryId, part, options)` | Download one Parquet part |
947
- | `getLakeCatalog()` | List queryable tables |
948
- | `describeLakeTable(table)` | Columns and types for one table |
949
-
950
885
  **Natural language**
951
886
 
952
- | Method | Purpose |
953
- | ------------------------------------------- | ------------------------------------------- |
954
- | `createNlScreen(question, { returnQuery })` | Screen stocks from a plain-language question |
955
- | `getNlScreen(screenId)` | Read the operation |
956
- | `waitForNlScreen(screenId, options)` | Block until terminal |
957
- | `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 |
958
893
 
959
894
  **Client construction**
960
895
 
@@ -1030,9 +965,8 @@ written back to `process.env`. Opt out with `NEXUSTRADE_DISABLE_DOTENV=1`.
1030
965
 
1031
966
  | Scope | Grants |
1032
967
  | ------- | --------------------------------------------------------------------------------- |
1033
- | `read` | Portfolio, backtest, genetic, sweep, and walk-forward reads |
968
+ | `read` | Portfolio, backtest, genetic, sweep, and walk-forward reads; NL screens |
1034
969
  | `write` | Portfolio create/edit/fork, backtests, genetic/sweep, and walk-forward launches |
1035
- | `lake` | Lake catalog, query lifecycle, manifests, result parts |
1036
970
 
1037
971
  A key missing the scope gets `403 insufficient_scope`.
1038
972
 
@@ -1077,7 +1011,7 @@ try {
1077
1011
  | Status | Code | Meaning |
1078
1012
  | ------ | -------------------------------------- | ------------------------------------------------------------ |
1079
1013
  | 401 | `invalid_token` | Missing, malformed, or expired key (or an OAuth JWT) |
1080
- | 403 | `insufficient_scope` | Key lacks `read`, `write`, or `lake` |
1014
+ | 403 | `insufficient_scope` | Key lacks the required scope |
1081
1015
  | 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
1082
1016
  | 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
1083
1017
  | 409 | `idempotency_conflict` | Key reused with a different payload |
@@ -1097,11 +1031,12 @@ _job_ takes.
1097
1031
 
1098
1032
  ## Scope
1099
1033
 
1100
- Portfolio drafting, backtesting, optimization, walk-forward studies, and
1101
- 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.
1102
1037
  The full surface requires a registered API key; anonymous workspaces are limited
1103
1038
  to portfolio authoring/forking, backtests, and programmatic agent/chat calls.
1104
- The screener and creating a live deployment remain outside this surface.
1039
+ Creating a live deployment remains outside this surface.
1105
1040
  Orders are reachable, but a live order is only ever staged for human approval —
1106
1041
  never submitted. `deploy` and `undeploy` act on whatever an existing id already
1107
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
  }
@@ -1351,9 +1347,6 @@ class NexusTradeClient {
1351
1347
  if (options.maxIterations !== undefined) {
1352
1348
  body.maxIterations = options.maxIterations;
1353
1349
  }
1354
- if (options.costCeilingUsd !== undefined) {
1355
- body.costCeilingUsd = options.costCeilingUsd;
1356
- }
1357
1350
  const response = await this.transport.request("POST", "agents", {
1358
1351
  body,
1359
1352
  idempotencyKey: options.idempotencyKey,
@@ -1416,33 +1409,10 @@ class NexusTradeClient {
1416
1409
  const response = await this.transport.request("GET", `walk-forward-studies/${encodePathSegment(studyId)}`);
1417
1410
  return operationOf(response);
1418
1411
  }
1419
- async createLakeQuery(request, options) {
1420
- const response = await this.transport.request("POST", "lake/queries", {
1421
- body: request,
1422
- idempotencyKey: options.idempotencyKey,
1423
- });
1424
- return operationOf(response);
1425
- }
1426
- async getLakeQuery(queryId) {
1427
- return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}`));
1428
- }
1429
- async cancelLakeQuery(queryId) {
1430
- return operationOf(await this.transport.request("POST", `lake/queries/${encodePathSegment(queryId)}/cancel`));
1431
- }
1432
- /**
1433
- * Submit a natural-language stock screen. Returns immediately; poll it.
1434
- *
1435
- * `returnQuery` keeps the generated SQL, engine and catalog version on the
1436
- * result. It defaults on: the SQL is the audit trail, and without it the rows
1437
- * are a number nobody can re-derive. It is returned on failure regardless,
1438
- * because a rejected query is the most useful thing to read.
1439
- */
1440
- async createNlScreen(question, options = {}) {
1412
+ /** Submit a natural-language stock screen. Returns immediately; poll it. */
1413
+ async createNlScreen(question) {
1441
1414
  return operationOf(await this.transport.request("POST", "nl/screens", {
1442
- body: {
1443
- question,
1444
- returnQuery: options.returnQuery ?? true,
1445
- },
1415
+ body: { question },
1446
1416
  }));
1447
1417
  }
1448
1418
  async getNlScreen(screenId) {
@@ -1455,55 +1425,6 @@ class NexusTradeClient {
1455
1425
  async waitForNlScreen(screenId, options = {}) {
1456
1426
  return waitForOperation((id) => this.getNlScreen(id), screenId, options);
1457
1427
  }
1458
- /**
1459
- * Submit a natural-language lake ask. Returns immediately; poll it.
1460
- */
1461
- async createLakeAsk(question) {
1462
- return operationOf(await this.transport.request("POST", "lake/ask", {
1463
- body: { question },
1464
- }));
1465
- }
1466
- async getLakeAsk(askId) {
1467
- return operationOf(await this.transport.request("GET", `lake/ask/${encodePathSegment(askId)}`));
1468
- }
1469
- async cancelLakeAsk(askId) {
1470
- return operationOf(await this.transport.request("POST", `lake/ask/${encodePathSegment(askId)}/cancel`));
1471
- }
1472
- /** Block until a lake ask is terminal. See `waitForOperation`. */
1473
- async waitForLakeAsk(askId, options = {}) {
1474
- return waitForOperation((id) => this.getLakeAsk(id), askId, options);
1475
- }
1476
- async getLakeQueryManifest(queryId) {
1477
- return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}/manifest`));
1478
- }
1479
- async getLakeCatalog() {
1480
- const response = await this.transport.request("GET", "lake/catalog");
1481
- const tables = response.tables;
1482
- if (!Array.isArray(tables) || !tables.every((t) => isJsonObject(t))) {
1483
- throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "invalid_response", "Lake catalog response is missing tables.");
1484
- }
1485
- return tables;
1486
- }
1487
- async describeLakeTable(table) {
1488
- const name = table.startsWith("lake.") ? table.slice(5) : table;
1489
- const response = await this.transport.request("GET", `lake/catalog/lake/${encodePathSegment(name)}`);
1490
- const described = response.table;
1491
- if (!isJsonObject(described)) {
1492
- throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "invalid_response", "Lake describe response is missing table.");
1493
- }
1494
- return described;
1495
- }
1496
- /** Download one Parquet part, optionally a byte range of it. */
1497
- async downloadLakeQueryPart(queryId, part, options = {}) {
1498
- if (!supportsBinary(this.transport)) {
1499
- throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "unsupported_transport", "Lake part download requires a transport implementing requestBytes.");
1500
- }
1501
- return this.transport.requestBytes("GET", `lake/queries/${encodePathSegment(queryId)}/parts/${Math.trunc(part)}`, options);
1502
- }
1503
- /** Resolve once a lake query is terminal. See `waitForOperation`. */
1504
- async waitForLakeQuery(queryId, options = {}) {
1505
- return waitForOperation((id) => this.getLakeQuery(id), queryId, { ...options, timeoutSeconds: options.timeoutSeconds ?? 1200 });
1506
- }
1507
1428
  /** Resolve once a backtest is terminal. See `waitForOperation`. */
1508
1429
  async waitForBacktest(backtestId, options = {}) {
1509
1430
  return waitForOperation((id) => this.getBacktest(id), backtestId, options);
@@ -39,7 +39,6 @@ exports.DaysSinceLastRebalanceOptionOrder = DaysSinceLastRebalanceOptionOrder;
39
39
  exports.DaysSinceOptionOrder = DaysSinceOptionOrder;
40
40
  exports.DaysSinceOrder = DaysSinceOrder;
41
41
  exports.DaysSinceStrategyFired = DaysSinceStrategyFired;
42
- exports.DaysSinceTransaction = DaysSinceTransaction;
43
42
  exports.DaysUntilEarnings = DaysUntilEarnings;
44
43
  exports.Divide = Divide;
45
44
  exports.DonchianChannel = DonchianChannel;
@@ -692,7 +691,7 @@ function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
692
691
  /**
693
692
  * ChartBar indicator.
694
693
  * @param asset Ticker name (ex. SPY, BTC)
695
- * @param barMinutes Completed candles aligned to 9:30 ET for stocks. Must divide the 390-minute regular session.
694
+ * @param barMinutes Completed candles: stocks divide the 390-minute regular session from 9:30 ET. Crypto divides the 1440-minute UTC day or uses 10080 for a Monday UTC week; legacy intraday sizes remain valid. Observation cadence must be Minute even for daily/weekly candles.
696
695
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
697
696
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
698
697
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
@@ -801,7 +800,7 @@ function CountTrue(condition, length = 1, interval = "Day", countInterval) {
801
800
  return d;
802
801
  }
803
802
  /**
804
- * CrossAbove indicator.
803
+ * CrossAbove and CrossBelow are numeric Indicators, not Conditions: with available operands they return 1 when a crossing is detected and 0 otherwise; an unavailable operand produces no value. Comparing the result with Value(0), for example gt(CrossAbove(left, right), Value(0)), is valid; passing the indicator directly to and/or is not. They compare consecutive market observations, not consecutive strategy decisions or completed chart candles. Stateful operands continue observing behind time and position gates, so a crossing before a scheduled decision can be 0 by the decision. Zero at that decision does not prove the underlying series never crossed. For an ordinary daily moving-average crossover strategy without a more specific observation clock, compare the two most recently completed trading sessions and disclose that execution follows confirmation at a later scheduled decision. Define latestLeft=IndicatorWindowAgo(left,1,'TradingDay'), latestRight=IndicatorWindowAgo(right,1,'TradingDay'), priorLeft=IndicatorWindowAgo(left,2,'TradingDay'), and priorRight=IndicatorWindowAgo(right,2,'TradingDay'). An upward completed-session crossing is gt(latestLeft,latestRight) AND lte(priorLeft,priorRight); reverse the comparisons for a downward crossing. Comparing the forming/current average against lag 1 can miss a crossing that occurs at the close after the scheduled decision: by the next decision the lag-1 relationship has already changed. A bare CrossAbove/CrossBelow impulse has a similar observation-versus-decision limitation. Preserve an explicitly requested partial-session/current-versus-prior comparison or observation-level impulse, and explain its sampling limitations rather than silently changing its clock. TradingDay references a confirmed session closing value; Day is elapsed calendar time, including for the underlying average window. ChartBar already excludes the forming candle, so preserve its intended candle identity and offset instead of blindly adding another lag. For other bar/session/decision references choose operands and lag lengths from the requested observation clock. Before diagnosing a crossover mismatch, inspect saved operand windows, observation/decision cadence, current and referenced values, and retained evaluation evidence. An outer comparison audit without inner operands cannot establish why the crossing was absent. Do not propose removing a valid numeric comparison as a repair.
805
804
  */
806
805
  function CrossAbove(left, right) {
807
806
  const d = { type: "CrossAbove" };
@@ -809,7 +808,7 @@ function CrossAbove(left, right) {
809
808
  return d;
810
809
  }
811
810
  /**
812
- * CrossBelow indicator.
811
+ * CrossAbove and CrossBelow are numeric Indicators, not Conditions: with available operands they return 1 when a crossing is detected and 0 otherwise; an unavailable operand produces no value. Comparing the result with Value(0), for example gt(CrossAbove(left, right), Value(0)), is valid; passing the indicator directly to and/or is not. They compare consecutive market observations, not consecutive strategy decisions or completed chart candles. Stateful operands continue observing behind time and position gates, so a crossing before a scheduled decision can be 0 by the decision. Zero at that decision does not prove the underlying series never crossed. For an ordinary daily moving-average crossover strategy without a more specific observation clock, compare the two most recently completed trading sessions and disclose that execution follows confirmation at a later scheduled decision. Define latestLeft=IndicatorWindowAgo(left,1,'TradingDay'), latestRight=IndicatorWindowAgo(right,1,'TradingDay'), priorLeft=IndicatorWindowAgo(left,2,'TradingDay'), and priorRight=IndicatorWindowAgo(right,2,'TradingDay'). An upward completed-session crossing is gt(latestLeft,latestRight) AND lte(priorLeft,priorRight); reverse the comparisons for a downward crossing. Comparing the forming/current average against lag 1 can miss a crossing that occurs at the close after the scheduled decision: by the next decision the lag-1 relationship has already changed. A bare CrossAbove/CrossBelow impulse has a similar observation-versus-decision limitation. Preserve an explicitly requested partial-session/current-versus-prior comparison or observation-level impulse, and explain its sampling limitations rather than silently changing its clock. TradingDay references a confirmed session closing value; Day is elapsed calendar time, including for the underlying average window. ChartBar already excludes the forming candle, so preserve its intended candle identity and offset instead of blindly adding another lag. For other bar/session/decision references choose operands and lag lengths from the requested observation clock. Before diagnosing a crossover mismatch, inspect saved operand windows, observation/decision cadence, current and referenced values, and retained evaluation evidence. An outer comparison audit without inner operands cannot establish why the crossing was absent. Do not propose removing a valid numeric comparison as a repair.
813
812
  */
814
813
  function CrossBelow(left, right) {
815
814
  const d = { type: "CrossBelow" };
@@ -951,17 +950,6 @@ function DaysSinceStrategyFired() {
951
950
  const d = { type: "DaysSinceStrategyFired" };
952
951
  return d;
953
952
  }
954
- /**
955
- * DaysSinceTransaction indicator.
956
- * @param transactionType Matches transaction events with this type (deposit or withdraw)
957
- * @param transactionStatus Matches transaction events with this status
958
- */
959
- function DaysSinceTransaction(transactionType, transactionStatus = "Completed") {
960
- const d = { type: "DaysSinceTransaction" };
961
- d["transactionType"] = transactionType;
962
- d["transactionStatus"] = transactionStatus;
963
- return d;
964
- }
965
953
  /**
966
954
  * DaysUntilEarnings indicator.
967
955
  * @param asset Ticker name (ex. SPY, BTC)
@@ -1003,7 +991,7 @@ function Economic(metric) {
1003
991
  return d;
1004
992
  }
1005
993
  /**
1006
- * ExponentialMovingAverage indicator.
994
+ * SMA/EMA window interval Day means elapsed calendar time, including closed exchange dates. TradingDay uses the exchange-session clock for exchange-traded assets and skips closed dates while preserving within-session time. For a conventional N-day stock moving average, author interval TradingDay unless the request explicitly specifies elapsed calendar days. An outer TradingDay lag does not change an inner Day average into an N-session average. Preserve an explicit calendar-day request as Day. Continuous-market daily windows use 24-hour Day intervals. A TradingDay window can still have a forming current reading: choose completed-session references separately when the signal requires confirmed closes. ChartBar periods and offsets already identify completed candles; preserve that clock instead of substituting a time-window average.
1007
995
  * @param asset Ticker name (ex. SPY, BTC)
1008
996
  * @param length Length of time
1009
997
  * @param interval Unit of time
@@ -2160,7 +2148,7 @@ function RelativeVolume(asset, length = 14, interval = "Day") {
2160
2148
  return d;
2161
2149
  }
2162
2150
  /**
2163
- * SimpleMovingAverage indicator.
2151
+ * SMA/EMA window interval Day means elapsed calendar time, including closed exchange dates. TradingDay uses the exchange-session clock for exchange-traded assets and skips closed dates while preserving within-session time. For a conventional N-day stock moving average, author interval TradingDay unless the request explicitly specifies elapsed calendar days. An outer TradingDay lag does not change an inner Day average into an N-session average. Preserve an explicit calendar-day request as Day. Continuous-market daily windows use 24-hour Day intervals. A TradingDay window can still have a forming current reading: choose completed-session references separately when the signal requires confirmed closes. ChartBar periods and offsets already identify completed candles; preserve that clock instead of substituting a time-window average.
2164
2152
  * @param asset Ticker name (ex. SPY, BTC)
2165
2153
  * @param length Length of time
2166
2154
  * @param interval Unit of time
@@ -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
  *
@@ -452,7 +438,6 @@ export declare class NexusTradeClient {
452
438
  createAgent(prompt: string, options: {
453
439
  idempotencyKey: string;
454
440
  maxIterations?: number;
455
- costCeilingUsd?: number;
456
441
  }): Promise<AgentRun>;
457
442
  /**
458
443
  * Reattach to a run already in flight.
@@ -483,44 +468,12 @@ export declare class NexusTradeClient {
483
468
  idempotencyKey: string;
484
469
  }): Promise<JsonObject>;
485
470
  getWalkForward(studyId: string): Promise<JsonObject>;
486
- createLakeQuery(request: JsonObject, options: {
487
- idempotencyKey: string;
488
- }): Promise<JsonObject>;
489
- getLakeQuery(queryId: string): Promise<JsonObject>;
490
- cancelLakeQuery(queryId: string): Promise<JsonObject>;
491
- /**
492
- * Submit a natural-language stock screen. Returns immediately; poll it.
493
- *
494
- * `returnQuery` keeps the generated SQL, engine and catalog version on the
495
- * result. It defaults on: the SQL is the audit trail, and without it the rows
496
- * are a number nobody can re-derive. It is returned on failure regardless,
497
- * because a rejected query is the most useful thing to read.
498
- */
499
- createNlScreen(question: string, options?: {
500
- returnQuery?: boolean;
501
- }): Promise<JsonObject>;
471
+ /** Submit a natural-language stock screen. Returns immediately; poll it. */
472
+ createNlScreen(question: string): Promise<JsonObject>;
502
473
  getNlScreen(screenId: string): Promise<JsonObject>;
503
474
  cancelNlScreen(screenId: string): Promise<JsonObject>;
504
475
  /** Block until a screen is terminal. See `waitForOperation`. */
505
476
  waitForNlScreen(screenId: string, options?: WaitOptions): Promise<JsonObject>;
506
- /**
507
- * Submit a natural-language lake ask. Returns immediately; poll it.
508
- */
509
- createLakeAsk(question: string): Promise<JsonObject>;
510
- getLakeAsk(askId: string): Promise<JsonObject>;
511
- cancelLakeAsk(askId: string): Promise<JsonObject>;
512
- /** Block until a lake ask is terminal. See `waitForOperation`. */
513
- waitForLakeAsk(askId: string, options?: WaitOptions): Promise<JsonObject>;
514
- getLakeQueryManifest(queryId: string): Promise<JsonObject>;
515
- getLakeCatalog(): Promise<JsonObject[]>;
516
- describeLakeTable(table: string): Promise<JsonObject>;
517
- /** Download one Parquet part, optionally a byte range of it. */
518
- downloadLakeQueryPart(queryId: string, part: number, options?: {
519
- byteRange?: [number, number];
520
- maxBytes?: number;
521
- }): Promise<Uint8Array>;
522
- /** Resolve once a lake query is terminal. See `waitForOperation`. */
523
- waitForLakeQuery(queryId: string, options?: WaitOptions): Promise<JsonObject>;
524
477
  /** Resolve once a backtest is terminal. See `waitForOperation`. */
525
478
  waitForBacktest(backtestId: string, options?: WaitOptions): Promise<JsonObject>;
526
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
  }
@@ -1341,9 +1337,6 @@ export class NexusTradeClient {
1341
1337
  if (options.maxIterations !== undefined) {
1342
1338
  body.maxIterations = options.maxIterations;
1343
1339
  }
1344
- if (options.costCeilingUsd !== undefined) {
1345
- body.costCeilingUsd = options.costCeilingUsd;
1346
- }
1347
1340
  const response = await this.transport.request("POST", "agents", {
1348
1341
  body,
1349
1342
  idempotencyKey: options.idempotencyKey,
@@ -1406,33 +1399,10 @@ export class NexusTradeClient {
1406
1399
  const response = await this.transport.request("GET", `walk-forward-studies/${encodePathSegment(studyId)}`);
1407
1400
  return operationOf(response);
1408
1401
  }
1409
- async createLakeQuery(request, options) {
1410
- const response = await this.transport.request("POST", "lake/queries", {
1411
- body: request,
1412
- idempotencyKey: options.idempotencyKey,
1413
- });
1414
- return operationOf(response);
1415
- }
1416
- async getLakeQuery(queryId) {
1417
- return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}`));
1418
- }
1419
- async cancelLakeQuery(queryId) {
1420
- return operationOf(await this.transport.request("POST", `lake/queries/${encodePathSegment(queryId)}/cancel`));
1421
- }
1422
- /**
1423
- * Submit a natural-language stock screen. Returns immediately; poll it.
1424
- *
1425
- * `returnQuery` keeps the generated SQL, engine and catalog version on the
1426
- * result. It defaults on: the SQL is the audit trail, and without it the rows
1427
- * are a number nobody can re-derive. It is returned on failure regardless,
1428
- * because a rejected query is the most useful thing to read.
1429
- */
1430
- async createNlScreen(question, options = {}) {
1402
+ /** Submit a natural-language stock screen. Returns immediately; poll it. */
1403
+ async createNlScreen(question) {
1431
1404
  return operationOf(await this.transport.request("POST", "nl/screens", {
1432
- body: {
1433
- question,
1434
- returnQuery: options.returnQuery ?? true,
1435
- },
1405
+ body: { question },
1436
1406
  }));
1437
1407
  }
1438
1408
  async getNlScreen(screenId) {
@@ -1445,55 +1415,6 @@ export class NexusTradeClient {
1445
1415
  async waitForNlScreen(screenId, options = {}) {
1446
1416
  return waitForOperation((id) => this.getNlScreen(id), screenId, options);
1447
1417
  }
1448
- /**
1449
- * Submit a natural-language lake ask. Returns immediately; poll it.
1450
- */
1451
- async createLakeAsk(question) {
1452
- return operationOf(await this.transport.request("POST", "lake/ask", {
1453
- body: { question },
1454
- }));
1455
- }
1456
- async getLakeAsk(askId) {
1457
- return operationOf(await this.transport.request("GET", `lake/ask/${encodePathSegment(askId)}`));
1458
- }
1459
- async cancelLakeAsk(askId) {
1460
- return operationOf(await this.transport.request("POST", `lake/ask/${encodePathSegment(askId)}/cancel`));
1461
- }
1462
- /** Block until a lake ask is terminal. See `waitForOperation`. */
1463
- async waitForLakeAsk(askId, options = {}) {
1464
- return waitForOperation((id) => this.getLakeAsk(id), askId, options);
1465
- }
1466
- async getLakeQueryManifest(queryId) {
1467
- return operationOf(await this.transport.request("GET", `lake/queries/${encodePathSegment(queryId)}/manifest`));
1468
- }
1469
- async getLakeCatalog() {
1470
- const response = await this.transport.request("GET", "lake/catalog");
1471
- const tables = response.tables;
1472
- if (!Array.isArray(tables) || !tables.every((t) => isJsonObject(t))) {
1473
- throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Lake catalog response is missing tables.");
1474
- }
1475
- return tables;
1476
- }
1477
- async describeLakeTable(table) {
1478
- const name = table.startsWith("lake.") ? table.slice(5) : table;
1479
- const response = await this.transport.request("GET", `lake/catalog/lake/${encodePathSegment(name)}`);
1480
- const described = response.table;
1481
- if (!isJsonObject(described)) {
1482
- throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Lake describe response is missing table.");
1483
- }
1484
- return described;
1485
- }
1486
- /** Download one Parquet part, optionally a byte range of it. */
1487
- async downloadLakeQueryPart(queryId, part, options = {}) {
1488
- if (!supportsBinary(this.transport)) {
1489
- throw new NexusTradeApiError(NO_HTTP_STATUS, "unsupported_transport", "Lake part download requires a transport implementing requestBytes.");
1490
- }
1491
- return this.transport.requestBytes("GET", `lake/queries/${encodePathSegment(queryId)}/parts/${Math.trunc(part)}`, options);
1492
- }
1493
- /** Resolve once a lake query is terminal. See `waitForOperation`. */
1494
- async waitForLakeQuery(queryId, options = {}) {
1495
- return waitForOperation((id) => this.getLakeQuery(id), queryId, { ...options, timeoutSeconds: options.timeoutSeconds ?? 1200 });
1496
- }
1497
1418
  /** Resolve once a backtest is terminal. See `waitForOperation`. */
1498
1419
  async waitForBacktest(backtestId, options = {}) {
1499
1420
  return waitForOperation((id) => this.getBacktest(id), backtestId, options);
@@ -101,10 +101,6 @@ export interface Allocation {
101
101
  type: AllocationType;
102
102
  amount: number;
103
103
  }
104
- export interface DepositWithdrawAllocation {
105
- type: DepositWithdrawAllocationType;
106
- amount: number;
107
- }
108
104
  export interface OptionAllocation {
109
105
  type: OptionAllocationType;
110
106
  amount: number;
@@ -291,10 +287,6 @@ export interface BuyOrSellAction {
291
287
  funding?: PurchaseFunding;
292
288
  holdingCondition?: Condition;
293
289
  }
294
- export interface DepositOrWithdrawAction {
295
- type: "Deposit" | "Withdraw";
296
- amount: DepositWithdrawAllocation;
297
- }
298
290
  export interface AlertAction {
299
291
  type: "Alert";
300
292
  message: string;
@@ -518,7 +510,7 @@ export interface CloseOptionAction {
518
510
  triggers?: CloseOptionTrigger[];
519
511
  quantity?: CloseQuantity;
520
512
  }
521
- export type Action = BuyOrSellAction | DepositOrWithdrawAction | AlertAction | LaunchAgentAction | DynamicRebalanceAction | RebalanceOptionAction | OpenOptionAction | CloseOptionAction | UpdateWatchlistAction;
513
+ export type Action = BuyOrSellAction | AlertAction | LaunchAgentAction | DynamicRebalanceAction | RebalanceOptionAction | OpenOptionAction | CloseOptionAction | UpdateWatchlistAction;
522
514
  export type StrategyLimitWorkingTime = {
523
515
  type: "Day";
524
516
  } | {
@@ -613,7 +605,6 @@ export type Comparator = "lessThan" | "greaterThan" | "lessThanOrEqual" | "great
613
605
  export type SelectDirection = "Highest" | "Lowest";
614
606
  export type UniverseSource = "ALL_US_STOCKS" | "SP500" | "NASDAQ100" | "DJIA" | "CRYPTO" | "SPECIFIC_ASSETS" | "WATCHLIST";
615
607
  export type AllocationType = "percent of portfolio" | "percent of buying power" | "percent of current positions" | "dollars" | "number of assets";
616
- export type DepositWithdrawAllocationType = "percent of portfolio" | "percent of buying power" | "dollars";
617
608
  export type OptionAllocationType = "dollars" | "percent of portfolio" | "percent of buying power" | "contracts" | "percent of realized premium";
618
609
  export type DeploymentBudgetType = "dollars" | "percent of portfolio";
619
610
  export type ExpirationPreference = "nearest" | "middle" | "furthest";
@@ -971,7 +962,7 @@ export declare function ChaikinMoneyFlow(asset: AssetArg, length?: number, inter
971
962
  /**
972
963
  * ChartBar indicator.
973
964
  * @param asset Ticker name (ex. SPY, BTC)
974
- * @param barMinutes Completed candles aligned to 9:30 ET for stocks. Must divide the 390-minute regular session.
965
+ * @param barMinutes Completed candles: stocks divide the 390-minute regular session from 9:30 ET. Crypto divides the 1440-minute UTC day or uses 10080 for a Monday UTC week; legacy intraday sizes remain valid. Observation cadence must be Minute even for daily/weekly candles.
975
966
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
976
967
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
977
968
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
@@ -1033,11 +1024,11 @@ export declare function CountTrue(condition: Condition, length?: number, interva
1033
1024
  interval: Interval;
1034
1025
  }): Indicator;
1035
1026
  /**
1036
- * CrossAbove indicator.
1027
+ * CrossAbove and CrossBelow are numeric Indicators, not Conditions: with available operands they return 1 when a crossing is detected and 0 otherwise; an unavailable operand produces no value. Comparing the result with Value(0), for example gt(CrossAbove(left, right), Value(0)), is valid; passing the indicator directly to and/or is not. They compare consecutive market observations, not consecutive strategy decisions or completed chart candles. Stateful operands continue observing behind time and position gates, so a crossing before a scheduled decision can be 0 by the decision. Zero at that decision does not prove the underlying series never crossed. For an ordinary daily moving-average crossover strategy without a more specific observation clock, compare the two most recently completed trading sessions and disclose that execution follows confirmation at a later scheduled decision. Define latestLeft=IndicatorWindowAgo(left,1,'TradingDay'), latestRight=IndicatorWindowAgo(right,1,'TradingDay'), priorLeft=IndicatorWindowAgo(left,2,'TradingDay'), and priorRight=IndicatorWindowAgo(right,2,'TradingDay'). An upward completed-session crossing is gt(latestLeft,latestRight) AND lte(priorLeft,priorRight); reverse the comparisons for a downward crossing. Comparing the forming/current average against lag 1 can miss a crossing that occurs at the close after the scheduled decision: by the next decision the lag-1 relationship has already changed. A bare CrossAbove/CrossBelow impulse has a similar observation-versus-decision limitation. Preserve an explicitly requested partial-session/current-versus-prior comparison or observation-level impulse, and explain its sampling limitations rather than silently changing its clock. TradingDay references a confirmed session closing value; Day is elapsed calendar time, including for the underlying average window. ChartBar already excludes the forming candle, so preserve its intended candle identity and offset instead of blindly adding another lag. For other bar/session/decision references choose operands and lag lengths from the requested observation clock. Before diagnosing a crossover mismatch, inspect saved operand windows, observation/decision cadence, current and referenced values, and retained evaluation evidence. An outer comparison audit without inner operands cannot establish why the crossing was absent. Do not propose removing a valid numeric comparison as a repair.
1037
1028
  */
1038
1029
  export declare function CrossAbove(left: Indicator, right: Indicator): Indicator;
1039
1030
  /**
1040
- * CrossBelow indicator.
1031
+ * CrossAbove and CrossBelow are numeric Indicators, not Conditions: with available operands they return 1 when a crossing is detected and 0 otherwise; an unavailable operand produces no value. Comparing the result with Value(0), for example gt(CrossAbove(left, right), Value(0)), is valid; passing the indicator directly to and/or is not. They compare consecutive market observations, not consecutive strategy decisions or completed chart candles. Stateful operands continue observing behind time and position gates, so a crossing before a scheduled decision can be 0 by the decision. Zero at that decision does not prove the underlying series never crossed. For an ordinary daily moving-average crossover strategy without a more specific observation clock, compare the two most recently completed trading sessions and disclose that execution follows confirmation at a later scheduled decision. Define latestLeft=IndicatorWindowAgo(left,1,'TradingDay'), latestRight=IndicatorWindowAgo(right,1,'TradingDay'), priorLeft=IndicatorWindowAgo(left,2,'TradingDay'), and priorRight=IndicatorWindowAgo(right,2,'TradingDay'). An upward completed-session crossing is gt(latestLeft,latestRight) AND lte(priorLeft,priorRight); reverse the comparisons for a downward crossing. Comparing the forming/current average against lag 1 can miss a crossing that occurs at the close after the scheduled decision: by the next decision the lag-1 relationship has already changed. A bare CrossAbove/CrossBelow impulse has a similar observation-versus-decision limitation. Preserve an explicitly requested partial-session/current-versus-prior comparison or observation-level impulse, and explain its sampling limitations rather than silently changing its clock. TradingDay references a confirmed session closing value; Day is elapsed calendar time, including for the underlying average window. ChartBar already excludes the forming candle, so preserve its intended candle identity and offset instead of blindly adding another lag. For other bar/session/decision references choose operands and lag lengths from the requested observation clock. Before diagnosing a crossover mismatch, inspect saved operand windows, observation/decision cadence, current and referenced values, and retained evaluation evidence. An outer comparison audit without inner operands cannot establish why the crossing was absent. Do not propose removing a valid numeric comparison as a repair.
1041
1032
  */
1042
1033
  export declare function CrossBelow(left: Indicator, right: Indicator): Indicator;
1043
1034
  /**
@@ -1114,12 +1105,6 @@ export declare function DaysSinceOrder(assets: AssetArg | AssetArg[], side: Side
1114
1105
  * DaysSinceStrategyFired indicator.
1115
1106
  */
1116
1107
  export declare function DaysSinceStrategyFired(): Indicator;
1117
- /**
1118
- * DaysSinceTransaction indicator.
1119
- * @param transactionType Matches transaction events with this type (deposit or withdraw)
1120
- * @param transactionStatus Matches transaction events with this status
1121
- */
1122
- export declare function DaysSinceTransaction(transactionType: "Deposit" | "Withdraw", transactionStatus?: "Pending" | "Canceled" | "Completed"): Indicator;
1123
1108
  /**
1124
1109
  * DaysUntilEarnings indicator.
1125
1110
  * @param asset Ticker name (ex. SPY, BTC)
@@ -1143,7 +1128,7 @@ export declare function DonchianChannel(asset: AssetArg, length?: number, interv
1143
1128
  */
1144
1129
  export declare function Economic(metric: "NonfarmPayrolls" | "UnemploymentRate" | "MoneySupply" | "TreasuryYield3Month" | "CPI"): Indicator;
1145
1130
  /**
1146
- * ExponentialMovingAverage indicator.
1131
+ * SMA/EMA window interval Day means elapsed calendar time, including closed exchange dates. TradingDay uses the exchange-session clock for exchange-traded assets and skips closed dates while preserving within-session time. For a conventional N-day stock moving average, author interval TradingDay unless the request explicitly specifies elapsed calendar days. An outer TradingDay lag does not change an inner Day average into an N-session average. Preserve an explicit calendar-day request as Day. Continuous-market daily windows use 24-hour Day intervals. A TradingDay window can still have a forming current reading: choose completed-session references separately when the signal requires confirmed closes. ChartBar periods and offsets already identify completed candles; preserve that clock instead of substituting a time-window average.
1147
1132
  * @param asset Ticker name (ex. SPY, BTC)
1148
1133
  * @param length Length of time
1149
1134
  * @param interval Unit of time
@@ -1764,7 +1749,7 @@ export declare const RSI: typeof RelativeStrengthIndex;
1764
1749
  */
1765
1750
  export declare function RelativeVolume(asset: AssetArg, length?: number, interval?: Interval): Indicator;
1766
1751
  /**
1767
- * SimpleMovingAverage indicator.
1752
+ * SMA/EMA window interval Day means elapsed calendar time, including closed exchange dates. TradingDay uses the exchange-session clock for exchange-traded assets and skips closed dates while preserving within-session time. For a conventional N-day stock moving average, author interval TradingDay unless the request explicitly specifies elapsed calendar days. An outer TradingDay lag does not change an inner Day average into an N-session average. Preserve an explicit calendar-day request as Day. Continuous-market daily windows use 24-hour Day intervals. A TradingDay window can still have a forming current reading: choose completed-session references separately when the signal requires confirmed closes. ChartBar periods and offsets already identify completed candles; preserve that clock instead of substituting a time-window average.
1768
1753
  * @param asset Ticker name (ex. SPY, BTC)
1769
1754
  * @param length Length of time
1770
1755
  * @param interval Unit of time
@@ -1908,7 +1893,7 @@ export interface BacktestConfig {
1908
1893
  startDate: string;
1909
1894
  /** Backtest end date (ISO format, e.g. 2024-12-31). Minute allows up to 730 days of minute data from start_date, counting minute-indicator warmup; never split a longer span into yearly Minute jobs. */
1910
1895
  endDate: string;
1911
- /** Legacy Stock benchmark shorthand for comparisonValue. Use baseline_asset with explicit Cryptocurrency type for crypto pairs; never provide both fields. When both fields are omitted, the single traded stock/option underlying is inferred, otherwise SPY. For single-name options use that underlying; compare multi-name books against a deliberately chosen benchmark. */
1896
+ /** Deprecated Stock benchmark shorthand for comparisonValue. Use baseline_asset with an explicit Stock or Cryptocurrency type; never provide both fields. When both fields are omitted, the single traded stock/option underlying is inferred, otherwise SPY. For single-name options use that underlying; compare multi-name books against a deliberately chosen benchmark. */
1912
1897
  baselineSymbol?: string;
1913
1898
  /** Typed buy-and-hold benchmark for comparisonValue. Use {type:'Cryptocurrency',symbol:'BTC-USD',name:'BTC-USD'} for BTC or {type:'Stock',symbol:'SPY',name:'SPY'} for a stock/ETF. Symbol text never determines asset type. Omit baseline_symbol when using this field. */
1914
1899
  baselineAsset?: Record<string, unknown>;
@@ -1916,7 +1901,7 @@ export interface BacktestConfig {
1916
1901
  interval?: "Day" | "Minute";
1917
1902
  /** Starting portfolio value (default 10000) Range 1..inf. */
1918
1903
  initialValue?: number;
1919
- /** 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. */
1920
1905
  generateEvents?: boolean;
1921
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. */
1922
1907
  forceNewRun?: boolean;
@@ -459,7 +459,7 @@ export function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
459
459
  /**
460
460
  * ChartBar indicator.
461
461
  * @param asset Ticker name (ex. SPY, BTC)
462
- * @param barMinutes Completed candles aligned to 9:30 ET for stocks. Must divide the 390-minute regular session.
462
+ * @param barMinutes Completed candles: stocks divide the 390-minute regular session from 9:30 ET. Crypto divides the 1440-minute UTC day or uses 10080 for a Monday UTC week; legacy intraday sizes remain valid. Observation cadence must be Minute even for daily/weekly candles.
463
463
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
464
464
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
465
465
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
@@ -568,7 +568,7 @@ export function CountTrue(condition, length = 1, interval = "Day", countInterval
568
568
  return d;
569
569
  }
570
570
  /**
571
- * CrossAbove indicator.
571
+ * CrossAbove and CrossBelow are numeric Indicators, not Conditions: with available operands they return 1 when a crossing is detected and 0 otherwise; an unavailable operand produces no value. Comparing the result with Value(0), for example gt(CrossAbove(left, right), Value(0)), is valid; passing the indicator directly to and/or is not. They compare consecutive market observations, not consecutive strategy decisions or completed chart candles. Stateful operands continue observing behind time and position gates, so a crossing before a scheduled decision can be 0 by the decision. Zero at that decision does not prove the underlying series never crossed. For an ordinary daily moving-average crossover strategy without a more specific observation clock, compare the two most recently completed trading sessions and disclose that execution follows confirmation at a later scheduled decision. Define latestLeft=IndicatorWindowAgo(left,1,'TradingDay'), latestRight=IndicatorWindowAgo(right,1,'TradingDay'), priorLeft=IndicatorWindowAgo(left,2,'TradingDay'), and priorRight=IndicatorWindowAgo(right,2,'TradingDay'). An upward completed-session crossing is gt(latestLeft,latestRight) AND lte(priorLeft,priorRight); reverse the comparisons for a downward crossing. Comparing the forming/current average against lag 1 can miss a crossing that occurs at the close after the scheduled decision: by the next decision the lag-1 relationship has already changed. A bare CrossAbove/CrossBelow impulse has a similar observation-versus-decision limitation. Preserve an explicitly requested partial-session/current-versus-prior comparison or observation-level impulse, and explain its sampling limitations rather than silently changing its clock. TradingDay references a confirmed session closing value; Day is elapsed calendar time, including for the underlying average window. ChartBar already excludes the forming candle, so preserve its intended candle identity and offset instead of blindly adding another lag. For other bar/session/decision references choose operands and lag lengths from the requested observation clock. Before diagnosing a crossover mismatch, inspect saved operand windows, observation/decision cadence, current and referenced values, and retained evaluation evidence. An outer comparison audit without inner operands cannot establish why the crossing was absent. Do not propose removing a valid numeric comparison as a repair.
572
572
  */
573
573
  export function CrossAbove(left, right) {
574
574
  const d = { type: "CrossAbove" };
@@ -576,7 +576,7 @@ export function CrossAbove(left, right) {
576
576
  return d;
577
577
  }
578
578
  /**
579
- * CrossBelow indicator.
579
+ * CrossAbove and CrossBelow are numeric Indicators, not Conditions: with available operands they return 1 when a crossing is detected and 0 otherwise; an unavailable operand produces no value. Comparing the result with Value(0), for example gt(CrossAbove(left, right), Value(0)), is valid; passing the indicator directly to and/or is not. They compare consecutive market observations, not consecutive strategy decisions or completed chart candles. Stateful operands continue observing behind time and position gates, so a crossing before a scheduled decision can be 0 by the decision. Zero at that decision does not prove the underlying series never crossed. For an ordinary daily moving-average crossover strategy without a more specific observation clock, compare the two most recently completed trading sessions and disclose that execution follows confirmation at a later scheduled decision. Define latestLeft=IndicatorWindowAgo(left,1,'TradingDay'), latestRight=IndicatorWindowAgo(right,1,'TradingDay'), priorLeft=IndicatorWindowAgo(left,2,'TradingDay'), and priorRight=IndicatorWindowAgo(right,2,'TradingDay'). An upward completed-session crossing is gt(latestLeft,latestRight) AND lte(priorLeft,priorRight); reverse the comparisons for a downward crossing. Comparing the forming/current average against lag 1 can miss a crossing that occurs at the close after the scheduled decision: by the next decision the lag-1 relationship has already changed. A bare CrossAbove/CrossBelow impulse has a similar observation-versus-decision limitation. Preserve an explicitly requested partial-session/current-versus-prior comparison or observation-level impulse, and explain its sampling limitations rather than silently changing its clock. TradingDay references a confirmed session closing value; Day is elapsed calendar time, including for the underlying average window. ChartBar already excludes the forming candle, so preserve its intended candle identity and offset instead of blindly adding another lag. For other bar/session/decision references choose operands and lag lengths from the requested observation clock. Before diagnosing a crossover mismatch, inspect saved operand windows, observation/decision cadence, current and referenced values, and retained evaluation evidence. An outer comparison audit without inner operands cannot establish why the crossing was absent. Do not propose removing a valid numeric comparison as a repair.
580
580
  */
581
581
  export function CrossBelow(left, right) {
582
582
  const d = { type: "CrossBelow" };
@@ -718,17 +718,6 @@ export function DaysSinceStrategyFired() {
718
718
  const d = { type: "DaysSinceStrategyFired" };
719
719
  return d;
720
720
  }
721
- /**
722
- * DaysSinceTransaction indicator.
723
- * @param transactionType Matches transaction events with this type (deposit or withdraw)
724
- * @param transactionStatus Matches transaction events with this status
725
- */
726
- export function DaysSinceTransaction(transactionType, transactionStatus = "Completed") {
727
- const d = { type: "DaysSinceTransaction" };
728
- d["transactionType"] = transactionType;
729
- d["transactionStatus"] = transactionStatus;
730
- return d;
731
- }
732
721
  /**
733
722
  * DaysUntilEarnings indicator.
734
723
  * @param asset Ticker name (ex. SPY, BTC)
@@ -770,7 +759,7 @@ export function Economic(metric) {
770
759
  return d;
771
760
  }
772
761
  /**
773
- * ExponentialMovingAverage indicator.
762
+ * SMA/EMA window interval Day means elapsed calendar time, including closed exchange dates. TradingDay uses the exchange-session clock for exchange-traded assets and skips closed dates while preserving within-session time. For a conventional N-day stock moving average, author interval TradingDay unless the request explicitly specifies elapsed calendar days. An outer TradingDay lag does not change an inner Day average into an N-session average. Preserve an explicit calendar-day request as Day. Continuous-market daily windows use 24-hour Day intervals. A TradingDay window can still have a forming current reading: choose completed-session references separately when the signal requires confirmed closes. ChartBar periods and offsets already identify completed candles; preserve that clock instead of substituting a time-window average.
774
763
  * @param asset Ticker name (ex. SPY, BTC)
775
764
  * @param length Length of time
776
765
  * @param interval Unit of time
@@ -1927,7 +1916,7 @@ export function RelativeVolume(asset, length = 14, interval = "Day") {
1927
1916
  return d;
1928
1917
  }
1929
1918
  /**
1930
- * SimpleMovingAverage indicator.
1919
+ * SMA/EMA window interval Day means elapsed calendar time, including closed exchange dates. TradingDay uses the exchange-session clock for exchange-traded assets and skips closed dates while preserving within-session time. For a conventional N-day stock moving average, author interval TradingDay unless the request explicitly specifies elapsed calendar days. An outer TradingDay lag does not change an inner Day average into an N-session average. Preserve an explicit calendar-day request as Day. Continuous-market daily windows use 24-hour Day intervals. A TradingDay window can still have a forming current reading: choose completed-session references separately when the signal requires confirmed closes. ChartBar periods and offsets already identify completed candles; preserve that clock instead of substituting a time-window average.
1931
1920
  * @param asset Ticker name (ex. SPY, BTC)
1932
1921
  * @param length Length of time
1933
1922
  * @param interval Unit of time
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "3.2.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",