Introduction

In the DeepSeek Harness (DSH) plugin ecosystem, injecting domain-specific capabilities into agents is a common requirement. In the chemical computation domain, large language models (LLMs) have predictable arithmetic errors, such as omitting water of crystallization when calculating molar mass, confusing element capitalization (e.g., “Co” and “CO”), making dilution formula calculation errors, or making back-calculation errors for pH.

dsh-chem is maintained by TYEclipse and aims to replace these unstable LLM mental calculations with pure arithmetic. It does not depend on any runtime libraries and performs deterministic calculations based only on IUPAC data, making it suitable for scenarios that require precise chemical stoichiometry.

Core Features

The plugin provides the following six deterministic tools:

1. Chemical Formula Parsing and Molar Mass Calculation

Supports nested parentheses, water of crystallization (dot or asterisk), ionic charges, and leading coefficients. It uses IUPAC standard atomic weights; for elements without stable isotopes, it uses the mass number of the most stable isotope.

2. Mass/Mole/Particle Conversion

Provides six conversion modes (mass to moles, moles to mass, mass to particles, etc.), supports directly specifying molar mass or calculating it from a formula, and uses Avogadro’s constant for precise conversion.

3. Solution Concentration Calculations

Supports four operations: molarity calculation, solution preparation (calculating solute mass based on volume and concentration), dilution calculations (C1V1=C2V2), and percentage concentration (mass/volume or volume ratio) calculations.

4. pH/pOH/Buffer Calculations

Based on the standard 25°C environment with Kw=1e-14, it supports back-calculating other parameters from hydrogen ion concentration, hydroxide concentration, pH, or pOH, and calculating buffer pH values using the Henderson-Hasselbalch equation.

5. Chemical Equation Balancing

Solves exact integer coefficients using rational arithmetic and enforces charge conservation. Supports complex equations containing ions, water of crystallization, and multiple reactants/products.

6. Ideal Gas Law Arithmetic

Provides PV=nRT-related calculations, including molar volume, gas density, and back-calculating molar mass from density. All units are fixed to avoid unit-guessing errors.

Installation and Enablement

Before installing, ensure that pnpm is installed on the system and Node.js version is 20 or higher.

dsh plugin --profile <profile> add github:TYEclipse/dsh-chem

After installation, you can verify the plugin status with the following commands:

dsh plugin --profile <profile> list
dsh --dump-config --profile <profile>

Typical Usage Examples

The following are invocation examples for some core features:

Calculate Molar Mass

{ "formula": "H2SO4" }

The returned result includes elemental composition and mass fractions.

Convert Mass to Moles

{ "mode": "mass_to_moles", "value": 98, "formula": "H2SO4" }

Prepare a Solution

{ "operation": "prepare", "molarity": 0.1, "volumeMl": 500, "formula": "NaOH" }

Calculate pH

{ "operation": "from_h", "hConc": 0.001 }

Balance a Chemical Equation

{ "equation": "C3H8 + O2 -> CO2 + H2O" }

Ideal Gas Law

{ "operation": "ideal", "moles": 1, "temperatureK": 273.15, "volumeL": 22.4 }

Applicable Scenarios and Caveats

  • Deterministic failure: The plugin behaves honestly. For equations that cannot be balanced (such as H2 + O2 -> H2O + N2), it returns valid: false and explains the reason, rather than silently discarding data.
  • Charge ambiguity rules: The plugin has explicit charge ambiguity handling rules. For example, NH4+ is treated as a positively charged combination of N and H4, while NO3- is treated as a negatively charged combination of N and O3. Standard notation must be used to avoid parsing errors.
  • Runtime environment: The plugin runs with the privileges of the current dsh process. It is recommended to review the source code and license (MIT) before installation.

Summary

dsh-chem is a lightweight, zero-dependency chemical calculation tool. By providing precise arithmetic interfaces, it resolves common calculation errors made by agents in chemical domains. For DSH agent developers who need high-precision chemical data, it is a reliable supplementary tool.

View Directory | GitHub Repository