Preface

In DSH workflows, Agents often extract numerical arrays from CSV / JSON and then need to calculate mean, quantiles, frequency, and correlation. Single expression evaluation is insufficient for quantiles and correlation, and model mental calculation is not convenient for reproducibility. dsh-tool-stat registers a stat tool that accepts explicitly passed finite numerical arrays or paired observations and returns structured output.

What is this

omdsh-dev/dsh-tool-stat is a DSH statistics tool plugin, licensed under MIT. It provides descriptive statistics, percentiles, frequency distributions, and correlation calculations for a set of finite values.

Here, “zero dependencies” means no third-party numerical libraries; package.json still declares peerDependencies and devDependencies. The plugin executes in a pure functional, deterministic manner: it does not read files, access networks, create processes, or save state.

Core Features

describe: Descriptive Statistics

Calculates the following fields for an explicitly passed values array:

  • count
  • sum
  • min
  • max
  • mean
  • median
  • variance
  • standardDeviation
  • q1
  • q3
  • iqr

When sample=true, the sample variance is used with a denominator of n-1; by default, sample=false, and the denominator is n.

percentile: Percentiles

percentiles is an array of values from 0..100, with up to 100 items. Calculation uses linear interpolation:

h = (n - 1) * p

Output is returned in the order requested, with duplicate percentiles preserved.

frequency: Frequency Distribution

Groups by strictly equal values and outputs value / count / ratio, sorted by value in ascending order. The denominator for ratio is the original count.

When the number of distinct outputs exceeds 10,000, the plugin truncates according to deterministic rules and annotates the output.

correlation: Correlation

Calculates Pearson or Spearman correlation coefficients. method is optional:

  • pearson, default
  • spearman, using midrank average ranks

other is a paired observation array of the same length as values. If a pair has zero variance, it returns:

defined: false
reason: zero-variance

It does not return NaN or ±Infinity.

Numerical Constraints and Safety

  • The number of observations ranges from 1..100,000. Exceeding the limit results in an error.
  • Percentile requests do not exceed 100.
  • NaN / Infinity is rejected.
  • -0 is normalized to 0 in both input and output.
  • A finite number check is performed before returning intermediate or final results.
  • timeoutMs is set to 2000.
  • Tool parameters are logged in the session; do not pass sensitive data.

Installation and Enabling

Installing to the Web Profile

dsh plugin --profile web add github:omdsh-dev/dsh-tool-stat

web and headless are different profiles. Installing to the web profile does not automatically overwrite the headless profile; dsh run uses the headless profile by default. To use a specific profile, ensure the plugin is installed in that profile.

Starting the Web Profile

npx -p @deepseek-ai/dsh@next dsh web

It is recommended not to use install -g for global installation.

Verifying Installation

dsh --profile web --dump-config | grep tool-stat

Running Verification

dsh run "Use the stat tool to calculate descriptive statistics for [1,2,3,4,5]"

Typical Usage

Below are the key points for each action.

action=describe

You can use the above dsh run example to calculate descriptive statistics for [1,2,3,4,5]. The output includes:

count / sum / min / max / mean / median / variance / standardDeviation / q1 / q3 / iqr

action=percentile

Requires passing:

values
percentiles

percentiles is an array of values from 0..100. Output is returned in the order requested, with duplicate percentiles preserved.

action=frequency

Requires passing:

values

Output is grouped by strictly equal values, with fields:

value / count / ratio

action=correlation

Requires passing:

values
other
method

other must be of the same length as values. method is optional, either pearson or spearman. In case of zero variance, it returns:

defined: false
reason: zero-variance

Use Cases and Notes

Suitable for the following scenarios:

  • You have obtained a set of finite values in an Agent or script and need to perform reproducible statistics in DSH.
  • You need to calculate mean, median, quartiles, IQR, frequency distribution, and correlation coefficients.
  • You need to explicitly reject non-finite numbers and avoid relying on model mental calculation.

Precautions before use:

  • The plugin runs with the permissions of the current dsh process. Check the source code and license before installation.
  • Parameters are logged in the session; do not pass sensitive data.
  • There are limits on the number of values, percentile count, and distinct outputs. Errors or annotations will be generated according to plugin rules when limits are exceeded or truncation occurs.
  • package.json declares the Node engine as:
^22.19.0 || >=24.0.0
  • package.json declares peerDependencies:
@deepseek-ai/cordis ^4.0.1
@deepseek-ai/dsh-tools >=0.0.1-rc.1 <0.2.0
@deepseek-ai/dsh-invariants >=0.0.1-rc.1 <0.2.0
  • “Zero dependencies” means no third-party numerical libraries, not the absence of peerDependencies or devDependencies.

Conclusion

The value of dsh-tool-stat lies in converting a set of finite numerical statistics into structured, verifiable, and reproducible results, rather than relying on the model’s instantaneous mental calculation.

GitHub repository: https://github.com/omdsh-dev/dsh-tool-stat