Kiploks Open Engine

https://kiploks.com/open-engine
Admin
Kiploks Open Engine is a deterministic, open-source analytics platform for strategy robustness and...
Tokens:16,833
Snippets:223
Trust Score:4.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Get Help for Kiploks CLI

Source: https://kiploks.com/open-engine/cli

Install the CLI globally using npm. Use the --help flag to view available commands and options.

```bash
npm install -g @kiploks/engine-cli
kiploks --help
```

--------------------------------

### Create Project Directory and Initialize npm

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Set up a new project directory and initialize npm for a minimal install of Kiploks engine packages.

```bash
mkdir my-kiploks-run && cd my-kiploks-run
npm init -y
```

--------------------------------

### Install Engine Packages

Source: https://kiploks.com/open-engine/getting-started

Install the core engine and contracts packages using npm. Ensure Node.js 20+ is installed.

```bash
npm install @kiploks/engine-core @kiploks/engine-contracts
```

--------------------------------

### Install Kiploks Engine Packages from npm

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Install the CLI, core, and contracts packages from the npm registry. Ensure all packages are pinned to the same semver line.

```bash
npm install @kiploks/engine-cli@^0.2.0 @kiploks/engine-core@^0.2.0 @kiploks/engine-contracts@^0.2.0
```

--------------------------------

### Install Dependencies

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Install project dependencies from the repository root using npm ci for reproducible builds.

```bash
npm ci
```

--------------------------------

### Run Professional WFA with TypeScript

Source: https://kiploks.com/open-engine/docs/WFA_PROFESSIONAL

Demonstrates the minimal TypeScript setup to run the professional Walk-Forward Analysis (WFA) engine. Ensure the engine core is imported and the input periods are correctly structured. Handles potential errors if insufficient input is provided.

```typescript
import { runProfessionalWfa } from "@kiploks/engine-core";


const professionalOut = runProfessionalWfa({
  periods: [
    { optimizationReturn: 0.1, validationReturn: 0.05, parameters: { p: 1 } },
    { optimizationReturn: 0.12, validationReturn: 0.07, parameters: { p: 2 } },
  ],
  // performanceTransfer is optional
});


if (!professionalOut) {
  throw new Error("Professional WFA: insufficient input");
}


console.log(professionalOut.professional.institutionalGrade?.grade);
```

--------------------------------

### Analyze From Windows Input Example

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Demonstrates the minimal JSON shape for the `analyzeFromWindows()` entrypoint, requiring two windows with period, in-sample, and out-of-sample return data. The `period` uses ISO date strings.

```json
{
  "wfaInputMode": "precomputed",
  "windows": [
    {
      "period": { "start": "2019-01-01", "end": "2019-04-01" },
      "inSample": { "return": 0.12 },
      "outOfSample": { "return": 0.09 }
    },
    {
      "period": { "start": "2019-04-01", "end": "2019-07-01" },
      "inSample": { "return": 0.08 },
      "outOfSample": { "return": 0.06 }
    }
  ]
}
```

--------------------------------

### Quick Start: Analyze Trades

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Quickly run the analyze function with sample trade data. This is useful for a first successful call to the engine.

```bash
mkdir my-kiploks-run && cd my-kiploks-run
npm init -y
npm install @kiploks/engine-core @kiploks/engine-contracts
node -e "const { analyze } = require('@kiploks/engine-core'); console.log(analyze({strategyId:'demo',trades:[{profit:1.2},{profit:-0.4}]},{seed:42,decimals:8}).summary)"
```

--------------------------------

### Analyze Input Example

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Provides a minimal JSON structure for the `analyze()` entrypoint, requiring at least one trade with a profit value.

```json
{
  "trades": [{ "profit": 0.05 }, { "profit": -0.02 }, { "profit": 0.08 }]
}
```

--------------------------------

### Clone Kiploks Engine Repository

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Clone the engine repository to get the full source code. This is recommended for development and running the full test suite.

```bash
git clone https://github.com/kiploks/engine.git
cd engine
```

--------------------------------

### analyzeFromWindows()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Analyzes precomputed In-Sample (IS) and Out-of-Sample (OOS) windows. Suitable for WFA when windows are already generated.

```APIDOC
## analyzeFromWindows()

### Description
Analyzes precomputed In-Sample (IS) and Out-of-Sample (OOS) windows for Walk Forward Analysis (WFA). This entrypoint is used when window data is already available.

### Method
`analyzeFromWindows`

### Parameters
- **windows** (object) - Object containing precomputed IS and OOS windows.
- **windowConfig** (object) - Configuration for WFA windows.

### Request Example
```javascript
import { analyzeFromWindows } from "@kiploks/engine-core";

const precomputedWindows = { is: [...], oos: [...] }; // Structure depends on contracts
const windowConfig = { lookahead: 30, walkforward: 90 };

const result = analyzeFromWindows(precomputedWindows, windowConfig);
```

### Response
#### Success Response (200)
- **summary** (object) - High-level analysis results.
- **metadata** (object) - Contains hashes and versions.
- **wfe** (object) - Walk Forward Efficiency results.
- **consistency** (object) - Analysis of consistency.
- **warnings** (array) - Any warnings generated during analysis.
- **BlockResult** (object) - Detailed results for each block.
```

--------------------------------

### Run Conformance Tests via CLI

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Run conformance tests using the CLI helper. Ensure this is run from the engine repository root.

```bash
npm run engine:test-conformance
```

--------------------------------

### analyzeFromWindows()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Analyzes precomputed windows to compute WFA results. Requires at least two windows with specified properties.

```APIDOC
## analyzeFromWindows()

### Description
Analyzes precomputed windows to compute Weighted Fair Analysis (WFA) results. Requires at least two windows with specified properties.

### Parameters
#### Request Body
- **wfaInputMode** (string) - Required - Must be set to "precomputed".
- **windows** (array) - Required - An array of window objects, each requiring 'period' (with 'start' and 'end' ISO date strings), 'inSample' (with 'return'), and 'outOfSample' (with 'return').
- **equityCurve** (object) - Optional - Can help unlock benchmark-related paths.
- **parameters** (object) - Optional - Per window parameters to feed parameter stability.

### Request Example
```json
{
  "wfaInputMode": "precomputed",
  "windows": [
    {
      "period": { "start": "2019-01-01", "end": "2019-04-01" },
      "inSample": { "return": 0.12 },
      "outOfSample": { "return": 0.09 }
    },
    {
      "period": { "start": "2019-04-01", "end": "2019-07-01" },
      "inSample": { "return": 0.08 },
      "outOfSample": { "return": 0.06 }
    }
  ]
}
```
```

--------------------------------

### Analyze precomputed IS/OOS windows

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Use analyzeFromWindows when you have precomputed In-Sample (IS) and Out-of-Sample (OOS) windows. This entrypoint requires window configuration.

```typescript
analyzeFromWindows()
```

--------------------------------

### Analyze WFA from Precomputed Windows in TypeScript

Source: https://kiploks.com/open-engine/docs/examples/03-wfa-from-windows

Use this snippet when you have precomputed trading windows and want to run WFA. Ensure `PrecomputedWFAInput.wfaInputMode` is set to 'precomputed' and provide at least two windows. The `benchmark` block is only available if `equityCurve` is provided.

```typescript
import { analyzeFromWindows } from "@kiploks/engine-core";
import type { PrecomputedWFAInput } from "@kiploks/engine-contracts";


const input: PrecomputedWFAInput = {
  wfaInputMode: "precomputed",
  equityCurve: [
    { timestamp: 1577836800000, value: 10000 },
    { timestamp: 1580515200000, value: 10300 },
    { timestamp: 1583020800000, value: 10150 },
  ],
  windows: [
    {
      period: { start: "2020-01-01T00:00:00.000Z", end: "2020-03-01T00:00:00.000Z" },
      inSample: { return: 0.02 },
      outOfSample: { return: -0.01 },
    },
    {
      period: { start: "2020-02-01T00:00:00.000Z", end: "2020-04-01T00:00:00.000Z" },
      inSample: { return: 0.01 },
      outOfSample: { return: 0.015 },
    },
  ],
};


const result = analyzeFromWindows(input, { seed: 42, decimals: 8, permutationN: 1000 });


console.log("robustnessScore:", result.robustnessScore);
console.log("consistencyVerdict:", result.consistency.verdict);
console.log("wfe rankWfe:", result.wfe.rankWfe, "p:", result.wfe.permutationPValue, "n:", result.wfe.permutationN);


if (!result.benchmark.available) {
  console.log("benchmark unavailable:", result.benchmark.reason);
}

```

--------------------------------

### Run All Reproducibility Checks

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_REPRODUCIBILITY

Execute this combined command to perform all necessary CI and release checks for Open Core changes. This includes tests, conformance checks, boundary checks, and bundle validation.

```bash
npm run engine:validate
```

--------------------------------

### analyzeFromTrades()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Performs Walk Forward Analysis (WFA) using trades with open and close times. Requires window configuration and WFA input mode.

```APIDOC
## analyzeFromTrades()

### Description
Analyzes trades with `openTime` and `closeTime` (Unix ms) to perform Walk Forward Analysis (WFA). Requires `windowConfig` and `wfaInputMode`.

### Method
`analyzeFromTrades`

### Parameters
- **trades** (Trade[]) - Array of trades, each with `openTime` and `closeTime`.
- **windowConfig** (object) - Configuration for WFA windows.
- **wfaInputMode** (string) - Specifies the mode for WFA input.

### Request Example
```javascript
import { analyzeFromTrades } from "@kiploks/engine-core";

const trades = [
  { openTime: 1678886400000, closeTime: 1678886460000, profit: 100 },
  // ... more trades
];
const windowConfig = { lookahead: 30, walkforward: 90 };
const wfaInputMode = "standard";

const result = analyzeFromTrades(trades, windowConfig, wfaInputMode);
```

### Response
#### Success Response (200)
- **summary** (object) - High-level analysis results.
- **metadata** (object) - Contains hashes and versions.
- **wfe** (object) - Walk Forward Efficiency results.
- **consistency** (object) - Analysis of consistency.
- **warnings** (array) - Any warnings generated during analysis.
- **BlockResult** (object) - Detailed results for each block.
```

--------------------------------

### Analyze Trades via CLI

Source: https://kiploks.com/open-engine/docs/examples/01-minimal-analyze

Run the analyze pipeline using the command-line interface by providing a JSON input file. Configure seed and decimal precision for the analysis.

```json
{
  "trades": [{ "profit": 0.05 }, { "profit": -0.02 }, { "profit": 0.08 }]
}
```

```bash
kiploks analyze ./input.json --json --seed 42 --decimals 8
```

--------------------------------

### Run analyze CLI command

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Execute the analyze command from the command line using npx. Ensure the kiploks binary is available in your PATH.

```bash
npx kiploks analyze ./input.json --json
```

--------------------------------

### Minimal Analyze with Engine Core

Source: https://kiploks.com/open-engine/getting-started

Perform a basic analysis by importing the `analyze` function and passing trade data with profit fractions and configuration for reproducible results. Logs summary and metadata.

```typescript
import { analyze } from "@kiploks/engine-core";


const out = analyze(
  { strategyId: "demo", trades: [{ profit: 0.02 }, { profit: -0.01 }] },
  { seed: 42, decimals: 8 },
);
console.log(out.summary, out.metadata);
```

--------------------------------

### Analyze trades with timestamps and window config

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Use analyzeFromTrades when trades include openTime and closeTime in Unix milliseconds, along with window configuration and WFA input mode.

```typescript
analyzeFromTrades()
```

--------------------------------

### Advanced WFE (`wfeAdvanced`)

Source: https://kiploks.com/open-engine/docs/WFA_PROFESSIONAL

Rank-based walk-forward efficiency analysis with a permutation null for out-of-sample shuffles.

```APIDOC
### 2) Advanced WFE (`wfeAdvanced`)

Rank-based walk-forward efficiency plus a one-sided permutation null for OOS shuffles (WFE v2; same shape as public `WFAAnalysisOutput.wfe`).
Key fields:
  * `rankWfe: number` - mean over windows of (OOS average rank / IS average rank), each window using independent 1-based tie-aware ranks on IS and OOS series.
  * `permutationPValue: number` - one-sided p: fraction of `permutationN` random OOS shuffles with `rankWfe` >= observed (seeded RNG per iteration).
  * `permutationN: number` - permutation count used (typically from `AnalyzeConfig.permutationN`, default 1000, bounds 100..10000).
  * `windowCount: number`
  * `seed: number` - seed wired into permutation draws for reproducibility.
  * `compositeScore: number` - heuristic 0..100 from `rankWfe`, with an extra cap when mean IS > 0 and mean OOS < 0.
  * `verdict: "ROBUST" | "ACCEPTABLE" | "WEAK" | "FAIL"` - heuristic from `rankWfe` and the mean IS / mean OOS guard above.

`buildProfessionalWfa` / `runProfessionalWfa` accept optional `permutationN` in the options object alongside `seed`.
```

--------------------------------

### Analyze Strategy and Log Metadata

Source: https://kiploks.com/open-engine/docs/examples/07-metadata-and-reproducibility

Demonstrates how to call the analyze function and log key metadata for reproducibility. Ensure the @kiploks/engine-core library is imported.

```typescript
import { analyze } from "@kiploks/engine-core";


const { summary, metadata } = analyze(
  { strategyId: "demo", trades: [{ profit: 0.01 }, { profit: -0.005 }] },
  { seed: 42, decimals: 8 },
);


console.log({
  engineVersion: metadata.engineVersion,
  formulaVersion: metadata.formulaVersion,
  riskAnalysisVersion: metadata.riskAnalysisVersion,
  contractVersion: metadata.contractVersion,
  inputHash: metadata.inputHash,
  configHash: metadata.configHash,
  seed: metadata.seed,
  decimals: metadata.decimals,
});
```

--------------------------------

### Upload Results to Cloud

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Upload analysis results to the Kiploks cloud using the CLI. Set environment variables for API base and key. Use --dry-run for testing.

```bash
export KIPLOKS_API_BASE=https://kiploks.com
export KIPLOKS_API_KEY=your_integration_key
npx tsx cli/src/index.ts upload ./result.json --cloud --dry-run
```

--------------------------------

### TypeScript: Compute WFA from synthetic trades

Source: https://kiploks.com/open-engine/docs/examples/02-wfa-from-trades

Use `analyzeFromTrades` with `tradeSlicedPseudoWfa` input mode. Each trade must include `openTime` and `closeTime` in unix ms. `parameterStability` and `benchmark` availability are explicitly represented in the output.

```typescript
import { analyzeFromTrades } from "@kiploks/engine-core";
import type { TradeBasedWFAInput } from "@kiploks/engine-contracts";


const DAY_MS = 24 * 60 * 60 * 1000;
const base = Date.UTC(2020, 0, 1);


const trades = [
  { profit: 0.01, openTime: base + 5 * DAY_MS, closeTime: base + 20 * DAY_MS },
  { profit: -0.02, openTime: base + 35 * DAY_MS, closeTime: base + 55 * DAY_MS },
  { profit: 0.03, openTime: base + 80 * DAY_MS, closeTime: base + 105 * DAY_MS },
  { profit: 0.02, openTime: base + 140 * DAY_MS, closeTime: base + 165 * DAY_MS },
  { profit: -0.01, openTime: base + 210 * DAY_MS, closeTime: base + 235 * DAY_MS },
  { profit: 0.015, openTime: base + 270 * DAY_MS, closeTime: base + 295 * DAY_MS },
];


const input: TradeBasedWFAInput = {
  trades,
  windowConfig: {
    inSampleMonths: 2,
    outOfSampleMonths: 1,
    stepMode: "rolling",
  },
  wfaInputMode: "tradeSlicedPseudoWfa",
};


const result = analyzeFromTrades(input, { seed: 42, decimals: 8, permutationN: 1000 });


console.log("robustnessScore:", result.robustnessScore);
console.log("consistencyVerdict:", result.consistency.verdict);
console.log("wfe rankWfe:", result.wfe.rankWfe, "p:", result.wfe.permutationPValue, "n:", result.wfe.permutationN);


if (!result.parameterStability.available) {
  console.log("parameterStability unavailable:", result.parameterStability.reason);
}
if (!result.benchmark.available) {
  console.log("benchmark unavailable:", result.benchmark.reason);
}

```

--------------------------------

### Conceptual Mapping of Engine JSON to Product UI

Source: https://kiploks.com/open-engine/docs/examples/08-result-shape-and-kiploks-ui

This flowchart illustrates the conceptual mapping between fields in the engine's JSON output and the corresponding sections in the product's user interface. It helps understand how raw analysis data is transformed into user-friendly visualizations.

```mermaid
flowchart LR
  subgraph Engine JSON
    S[summary]
    M[metadata]
    W[wfe + consistency]
    R[robustnessScore]
    B[parameterStability / benchmark / dqg / ...]
    Warn[warnings]
  end
  subgraph Product UI
    T[Trade / summary strip]
    V[Versions and hashes footer]
    WF[Walk-Forward / WFE section]
    RB[Robustness block]
    OB[Optional analytics blocks]
    AL[Alerts / warnings]
  end
  S --> T
  M --> V
  W --> WF
  R --> RB
  B --> OB
  Warn --> AL
```

--------------------------------

### Regenerate Engine Sample Outputs

Source: https://kiploks.com/open-engine/docs/examples/sample-output/README

Run this command from the engine repository root after building the engine to regenerate sample JSON outputs. Ensure you update embedded samples if formulas or hashing change.

```bash
npm run engine:examples:generate-samples
```

--------------------------------

### Sync Versions Command

Source: https://kiploks.com/open-engine/docs/OSS_PUBLIC_REPO_SYNC

Run this command from the repository root to synchronize the version number across all workspace package.json files and internal dependencies. This ensures a consistent semver for all `@kiploks/engine-*` packages.

```bash
npm run sync-versions

```

--------------------------------

### Run Analyzer with JSON Input

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Analyze a JSON input file using the CLI. This provides machine-readable output of the analysis.

```json
{
  "strategyId": "demo",
  "trades": [{ "profit": 10.5 }, { "profit": -2.2 }]
}
```

```bash
npx tsx cli/src/index.ts analyze ./input.json --json
```

--------------------------------

### Build Engine Libraries

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Build the compiled 'dist/' artifacts for engine contracts and core libraries, which are typically expected by consumers and local scripts.

```bash
npm run build
```

--------------------------------

### CLI: Analyze trades from array

Source: https://kiploks.com/open-engine/docs/examples/02-wfa-from-trades

Run the `kiploks analyze-trades` command with a raw trades array, specifying output format, JSON, and window configuration parameters.

```bash
kiploks analyze-trades trades-array.json --format raw --json \
  --in-sample-months 2 --out-of-sample-months 1 --step rolling

```

--------------------------------

### Methodology Page Flow

Source: https://kiploks.com/open-engine/docs/examples/10-methodology-flow-and-engine

Illustrates the fixed order of analysis blocks as shown on the product UI, which mirrors the assembly of a full report from payload data.

```text
Data Quality Guard
  → Walk-Forward
  → Benchmark Metrics
  → Benchmark Comparison
  → Parameter Sensitivity
  → Cost Drag
  → Action Plan
  → Risk Metrics
  → Robustness Score
  → Final Verdict
```

--------------------------------

### Upload Standalone Result with Parity

Source: https://kiploks.com/open-engine/docs/examples/06-cloud-upload-parity

Upload a standalone analysis result to the cloud while enabling parity checks against local analysis. Set the API base URL and API key using environment variables. Use `--dry-run` to preview the upload.

```bash
export KIPLOKS_API_BASE=https://kiploks.com
export KIPLOKS_API_KEY=your_integration_key

kiploks upload ./standalone-result.json --cloud --local-analyze ./local-analyze.json
```

--------------------------------

### Public Entrypoints

Source: https://kiploks.com/open-engine/docs/WFA_PROFESSIONAL

The wfaProfessional module exposes three public functions for building and validating Professional WFA artifacts.

```APIDOC
## Public entrypoints

The engine-core exports the following functions from `wfaProfessional`:

* `validateAndNormalizeWfaInput(wfa)` - normalizes input into numeric periods and optionally extracts/sorts curve points.
* `buildProfessionalWfa(validationResult)` - builds the 7 blocks from normalized periods.
* `runProfessionalWfa(wfa)` - combines validation + build; returns `null` when input cannot produce a professional report.

If `runProfessionalWfa(...)` (or `buildProfessionalWfa(...)`) cannot validate the input (for example, not enough periods), it returns `null`.
```

--------------------------------

### CLI: Prepare raw trades array

Source: https://kiploks.com/open-engine/docs/examples/02-wfa-from-trades

Define a raw trades array in `trades-array.json` for the `analyze-trades` command. This format is accepted by `analyze-trades --format auto`.

```json
[
  { "profit": 0.01, "openTime": 1578182400000, "closeTime": 1578528000000 },
  { "profit": -0.02, "openTime": 1578969600000, "closeTime": 1579442400000 },
  { "profit": 0.03, "openTime": 1580342400000, "closeTime": 1580815200000 }
]

```

--------------------------------

### CLI: Prepare canonical engine input shape

Source: https://kiploks.com/open-engine/docs/examples/02-wfa-from-trades

Define the canonical engine input shape in `trade-based-wfa.json` for validation. This file specifies trades, window configuration, and the WFA input mode.

```json
{
  "trades": [
    { "profit": 0.01, "openTime": 1578182400000, "closeTime": 1578528000000 },
    { "profit": -0.02, "openTime": 1578969600000, "closeTime": 1579442400000 },
    { "profit": 0.03, "openTime": 1580342400000, "closeTime": 1580815200000 }
  ],
  "windowConfig": {
    "inSampleMonths": 2,
    "outOfSampleMonths": 1,
    "stepMode": "rolling"
  },
  "wfaInputMode": "tradeSlicedPseudoWfa"
}

```

--------------------------------

### Add analyze command to package.json scripts

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_LOCAL_USER_GUIDE

Define an npm script in your package.json to easily run the analyze command. This is an alternative to using npx directly.

```json
{
  "scripts": {
    "analyze": "kiploks analyze ./input.json --json"
  }
}
```

--------------------------------

### analyzeFromTrades()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Analyzes trades to compute Weighted Fair Analysis (WFA) results. Requires sufficient trades and calendar span to form at least two full windows.

```APIDOC
## analyzeFromTrades()

### Description
Analyzes trades to compute Weighted Fair Analysis (WFA) results. Requires sufficient trades and calendar span to form at least two full windows.

### Parameters
#### Request Body
- **trades** (array) - Required - An array of trade objects, each requiring 'profit', 'openTime' (Unix ms), 'closeTime' (Unix ms), 'windowConfig', and 'wfaInputMode' set to "tradeSlicedPseudoWfa".
- **wfaInputMode** (string) - Required - Must be set to "tradeSlicedPseudoWfa".

### Notes
Ensure there is enough calendar span and trades for the slicer to form at least two full windows. Refer to `docs/examples/01-minimal-analyze.md` and WFA examples for more details.
```

--------------------------------

### Parameter stability (`parameterStability`)

Source: https://kiploks.com/open-engine/docs/WFA_PROFESSIONAL

Analysis of parameter drift and stability across different walk-forward periods.

```APIDOC
### 3) Parameter stability (`parameterStability`)

Drift-based parameter stability across periods.
Key fields:
  * `available: boolean`
  * `parameterDrift?: Record<string, { mean: number; std: number; driftPct: number; stability: "STABLE" | "ADAPTIVE" | "FRAGILE" }> `
  * `fragileParameters?: string[]`
  * `overallStability?: "ROBUST" | "ACCEPTABLE" | "FRAGILE"`
  * `stabilityScore?: number | null`

If there are no numeric parameters across the input periods, `parameterStability` becomes unavailable (`parameterStability.available` is `false` and the block is omitted by `runProfessionalWfa`).
```

--------------------------------

### Produce Local Analyze JSON

Source: https://kiploks.com/open-engine/docs/examples/06-cloud-upload-parity

Generate a JSON file containing the results of a local analysis. This is used later for parity comparison. Ensure the input file and desired seed are specified.

```bash
kiploks analyze ./minimal-input.json --json --seed 42 --decimals 8 > local-analyze.json
```

--------------------------------

### Repository Layout

Source: https://kiploks.com/open-engine/docs/OSS_PUBLIC_REPO_SYNC

This is the directory structure of the Open Core engine's public repository. It includes configuration files, scripts, and package directories.

```plaintext
VERSION                 # single semver for all @kiploks/engine-* packages
LICENSE
README.md
CHANGELOG.md
CONTRIBUTING.md
SECURITY.md
CODE_OF_CONDUCT.md
vitest.config.ts
package.json            # private workspace root (not published)
scripts/                # prepack, version sync, boundary/bundle checks
packages/
  contracts/
  core/
  adapters/
  cli/
  test-vectors/
docs/                   # Open Core guides and examples (see docs/README.md)

```

--------------------------------

### Refresh Reproducibility Metadata

Source: https://kiploks.com/open-engine/docs/OPEN_CORE_REPRODUCIBILITY

Run this command to refresh metadata when canonicalization or hash policies are updated. This ensures that all reproducible output fields are up-to-date.

```bash
npm run engine:vectors:refresh-metadata
```

--------------------------------

### analyze()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Performs basic analysis providing summary and metadata. Use when only trade profits are available, without timestamps.

```APIDOC
## analyze()

### Description
Performs basic analysis on trade profits to generate a summary and metadata. This is the simplest entrypoint, suitable when timestamps are not available.

### Method
`analyze`

### Parameters
None explicitly documented for this basic call.

### Request Example
```javascript
import { analyze } from "@kiploks/engine-core";

const result = analyze({ profits: [100, -50, 200] }); 
// Assuming input is an object with a 'profits' array
```

### Response
#### Success Response (200)
- **summary** (object) - High-level analysis results.
- **metadata** (object) - Contains hashes and versions.
```

--------------------------------

### Analyze basic trade data

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Use the analyze function when you only have trade profits and no timestamps. This is the simplest entrypoint for analysis.

```typescript
analyze()
```

--------------------------------

### Equity curve analysis (`equityCurveAnalysis`)

Source: https://kiploks.com/open-engine/docs/WFA_PROFESSIONAL

Analysis of the out-of-sample equity curve, providing insights into its performance and trend.

```APIDOC
### 1) Equity curve analysis (`equityCurveAnalysis`)

Represents analysis of the out-of-sample equity curve (transferred curve or approximated curve when transfers are not available enough).
Key fields:
  * `available: boolean`
  * `chunkStats?: Array<{ return: number; volatility: number; maxDrawdown: number }>`
  * `trendConsistency?: "HIGH" | "MEDIUM" | "LOW"`
  * `overallTrend?: "UP" | "FLAT" | "DOWN"`
  * `volatilityProgression?: number[]`
  * `verdict?: "STRONG" | "ACCEPTABLE" | "WEAK"`

If the curve is too short for reliable chunking, `equityCurveAnalysis` becomes unavailable (`available: false`).
```

--------------------------------

### Analyze Raw Trades Array

Source: https://kiploks.com/open-engine/docs/examples/05-cli-validate-and-analyze-trades

Analyze a raw trades array from a JSON file using the `kiploks analyze-trades` command. Specify the input format, output format, and window configuration parameters.

```bash
kiploks analyze-trades trades.json --format raw --json \
  --in-sample-months 2 --out-of-sample-months 1 --step rolling
```

--------------------------------

### Analyze Trades with Auto Format Detection

Source: https://kiploks.com/open-engine/docs/examples/05-cli-validate-and-analyze-trades

Analyze trades using the `--format auto` option, which automatically detects the input format (CSV or JSON array). This command also shows the detected format and outputs results in JSON.

```bash
kiploks analyze-trades trades.json --format auto --show-detected-format --json \
  --in-sample-months 3 --out-of-sample-months 1 --step rolling
```

--------------------------------

### analyze()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Analyzes provided trades to compute results. Requires at least one trade with a 'profit' field.

```APIDOC
## analyze()

### Description
Analyzes provided trades to compute results. Requires at least one trade with a 'profit' field.

### Parameters
#### Request Body
- **trades** (array) - Required - An array of trade objects, each requiring a 'profit' field (decimal fraction of capital).

### Request Example
```json
{
  "trades": [{ "profit": 0.05 }, { "profit": -0.02 }, { "profit": 0.08 }]
}
```
```

--------------------------------

### CLI: Validate canonical engine input

Source: https://kiploks.com/open-engine/docs/examples/02-wfa-from-trades

Validate the canonical engine input contract using the `kiploks validate` command with the `--schema trade-based-wfa` flag.

```bash
kiploks validate trade-based-wfa.json --schema trade-based-wfa --explain

```

--------------------------------

### mapPayloadToUnified()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Normalizes raw integration JSON payloads into a unified format. This is a data shaping step, not an analysis function.

```APIDOC
## mapPayloadToUnified()

### Description
This function normalizes raw integration JSON payloads by copying and rewriting known subtrees to align keys and decimal returns with downstream expectations. It is a pure normalization step and does not perform any analysis.

### Method
`mapPayloadToUnified`

### Parameters
- **payload** (object) - The raw integration JSON payload.

### Request Example
```javascript
import { mapPayloadToUnified } from "@kiploks/engine-core";

const rawPayload = { backtestResult: { ... }, walkForwardAnalysis: { ... } }; // Example structure
const unifiedPayload = mapPayloadToUnified(rawPayload);
```

### Response
#### Success Response (200)
- **UnifiedIntegrationPayload** (object) - The normalized payload with aligned keys and decimal returns.
```

--------------------------------

### Import analyze function from engine-core

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Import the analyze function for use in TypeScript projects. This is the basic import statement for the core engine functionality.

```typescript
import { analyze } from "@kiploks/engine-core";
```

--------------------------------

### TypeScript: Map Raw Payload to Unified Format

Source: https://kiploks.com/open-engine/docs/examples-map-payload-to-unified

Use `mapPayloadToUnified` to normalize raw integration payloads with legacy or mixed keys into a consistent format. This function applies decimal conversion and key alignment for known subtrees. It does not perform analysis.

```typescript
import { mapPayloadToUnified } from "@kiploks/engine-core";


const raw = {
  walkForwardAnalysis: {
    periods: [
      {
        optimization_return: 0.12,
        validation_return: 0.09,
      },
    ],
  },
} as Record<string, unknown>;


const unified = mapPayloadToUnified(raw);
// Normalized periods include optimizationReturn / validationReturn as decimals per implementation.

```

--------------------------------

### csvToTrades() and csvToTradesFromStream()

Source: https://kiploks.com/open-engine/docs/ENTRYPOINTS

Converts UTF-8 CSV data with a header row into an array of trades. `csvToTradesFromStream` is suitable for large files.

```APIDOC
## csvToTrades() and csvToTradesFromStream()

### Description
These functions parse UTF-8 CSV files with a header row and convert the data into a `Trade[]` format, suitable for downstream analysis. `csvToTradesFromStream` is optimized for handling large CSV files by processing them as a stream.

### Method
`csvToTrades` or `csvToTradesFromStream`

### Parameters
- **csvData** (string or stream) - The CSV data as a string or a readable stream.

### Request Example
```javascript
import { csvToTrades, csvToTradesFromStream } from "@kiploks/engine-core";

// For csvToTrades
const csvString = "openTime,closeTime,profit\n1678886400000,1678886460000,100\n...";
const trades = csvToTrades(csvString);

// For csvToTradesFromStream (example using Node.js streams)
// const fs = require('fs');
// const tradeStream = fs.createReadStream('trades.csv');
// const trades = await csvToTradesFromStream(tradeStream);
```

### Response
#### Success Response (200)
- **Trade[]** - An array of trade objects, each containing at least `openTime`, `closeTime`, and `profit`.
```
Tokens:
Raw