@euclid-tools/euclid 0.2.0

package/skills/math/EXPRESSIONS.md

@@ -0,0 +1,103 @@
+# Expression Reference — `calculate` tool
+
+## Operators
+
+| Operator | Meaning        | Example           |
+| -------- | -------------- | ----------------- |
+| `+`      | Addition       | `2 + 3` → `5`     |
+| `-`      | Subtraction    | `10 - 4` → `6`    |
+| `*`      | Multiplication | `7 * 8` → `56`    |
+| `/`      | Division       | `15 / 4` → `3.75` |
+| `^`      | Exponentiation | `2^10` → `1024`   |
+| `!`      | Factorial      | `5!` → `120`      |
+
+Standard order of operations applies. Use parentheses to control grouping.
+
+## Functions
+
+| Function       | Description          | Example                 |
+| -------------- | -------------------- | ----------------------- |
+| `sqrt(x)`      | Square root          | `sqrt(144)` → `12`      |
+| `abs(x)`       | Absolute value       | `abs(-5)` → `5`         |
+| `ceil(x)`      | Round up             | `ceil(4.2)` → `5`       |
+| `floor(x)`     | Round down           | `floor(4.8)` → `4`      |
+| `round(x)`     | Round to nearest     | `round(4.5)` → `5`      |
+| `exp(x)`       | e^x                  | `exp(1)` → `2.71828...` |
+| `log(x, base)` | Logarithm            | `log(100, 10)` → `2`    |
+| `ln(x)`        | Natural log (base e) | `ln(e)` → `1`           |
+| `sin(x)`       | Sine (radians)       | `sin(pi / 2)` → `1`     |
+| `cos(x)`       | Cosine (radians)     | `cos(0)` → `1`          |
+| `tan(x)`       | Tangent (radians)    | `tan(pi / 4)` → `1`     |
+| `asin(x)`      | Inverse sine         | `asin(1)` → `1.5707...` |
+| `acos(x)`      | Inverse cosine       | `acos(1)` → `0`         |
+| `atan(x)`      | Inverse tangent      | `atan(1)` → `0.7853...` |
+
+### Trigonometry with degrees
+
+Trig functions use **radians** by default. Append `deg` for degree input:
+
+```
+sin(30 deg)     → 0.5
+cos(45 deg)     → 0.7071...
+sin(pi / 6)     → 0.5  (radians, same result)
+```
+
+## Constants
+
+| Constant | Value               | Usage        |
+| -------- | ------------------- | ------------ |
+| `pi`     | 3.14159265358979... | `2 * pi * r` |
+| `e`      | 2.71828182845904... | `e^2`        |
+| `phi`    | 1.61803398874989... | Golden ratio |
+
+## Unicode Support
+
+These symbols are normalized automatically — you can use them directly:
+
+| Input               | Converted to | Example                                    |
+| ------------------- | ------------ | ------------------------------------------ |
+| `×`                 | `*`          | `2 × 3` → `2 * 3`                          |
+| `÷`                 | `/`          | `10 ÷ 2` → `10 / 2`                        |
+| `²`                 | `^2`         | `5²` → `5^2`                               |
+| `³`                 | `^3`         | `2³` → `2^3`                               |
+| `√`                 | `sqrt(...)`  | `√16` → `sqrt(16)`, `√(2+3)` → `sqrt(2+3)` |
+| `π`                 | `pi`         | `2π` → `2pi`                               |
+| `−` (Unicode minus) | `-`          | `5 − 3` → `5 - 3`                          |
+
+## Thousands Separators
+
+Commas in numbers are stripped automatically:
+
+```
+3,456 * 7,891       → 3456 * 7891
+1,000,000 + 500     → 1000000 + 500
+```
+
+Function argument commas are preserved: `log(100, 10)` stays as-is.
+
+## Precision
+
+The `precision` parameter controls significant digits in the result (default: 14):
+
+```
+calculate({ expression: "pi", precision: 6 })  → "3.14159"
+calculate({ expression: "1/3" })                → "0.33333333333333"
+```
+
+## Edge Cases
+
+| Expression         | Result              | Note             |
+| ------------------ | ------------------- | ---------------- |
+| `1 / 0`            | `Infinity`          | Not an error     |
+| `-1 / 0`           | `-Infinity`         | Not an error     |
+| `0 / 0`            | `NaN`               | Not an error     |
+| `sqrt(-1)`         | `i`                 | Complex number   |
+| `e^(i * pi) + 1`   | `≈ 0`               | Euler's identity |
+| Very large numbers | Scientific notation | e.g., `1e+30`    |
+
+## Limits
+
+- **Max expression length:** 1000 characters
+- **Execution timeout:** 5 seconds
+- **Disabled functions:** `import`, `createUnit`, `evaluate`, `parse`, `simplify`,
+  `derivative`, `resolve`, `reviver` (blocked for security)

package/skills/math/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: math
+description: >
+  Guidance for using Euclid's deterministic MCP math tools (calculate, convert,
+  statistics). Use when the user's request requires numerical computation, unit
+  conversion, or statistical analysis instead of mental math.
+---
+
+# Euclid Math Tools
+
+## The Rule
+
+If a user's request requires a numerical result, unit conversion, or statistical
+computation, use the Euclid MCP tools. **Never predict, estimate, or mentally
+compute when a deterministic tool is available.**
+
+This applies to all math: arithmetic, percentages, exponents, roots, trigonometry,
+logarithms, factorials, combinatorics, unit conversions, and dataset statistics.
+
+Even for "simple" math like `247 * 38`, use the `calculate` tool. Mental math
+is a prediction — the tool is deterministic.
+
+## Which Tool to Use
+
+| The user needs...                         | Use          | Example                                                 |
+| ----------------------------------------- | ------------ | ------------------------------------------------------- |
+| A numerical result from a math expression | `calculate`  | "What is 15% of 847?" → `0.15 * 847`                    |
+| To convert between units of measurement   | `convert`    | "Convert 5 km to miles" → `convert(5, "km", "mile")`    |
+| A statistic computed on a dataset         | `statistics` | "Average of these scores" → `statistics("mean", [...])` |
+| A conceptual explanation                  | None         | "Explain what a derivative is"                          |
+| A rough estimate or guess                 | None         | "About how many people fit in a stadium"                |
+| Symbolic algebra (no numeric answer)      | None         | "Simplify x^2 + 2x"                                     |
+
+## Key Behaviors
+
+**Always use the tool, never fall back to mental math.** If a calculation errors,
+read the `hint` and `examples` fields in the error response. Fix the input and
+retry. Do not fall back to predicting the answer.
+
+**Chain tools when needed.** Calculate a value, then convert its units. Compute
+individual values, then run statistics on them. Each tool does one thing well.
+
+**Present full precision.** Do not round or truncate Euclid results unless the
+user explicitly asks for rounding. The tool returns precise results — preserve them.
+
+**Unicode and natural language work.** Expressions with `×`, `÷`, `√`, `π`, `²`,
+`³` are normalized automatically. Unit names like `"celsius"`, `"fahrenheit"`,
+`"miles per hour"` are also normalized. No need to manually convert these.
+
+**Use `calculate` broadly.** Percentages, compound interest, combinatorics,
+trigonometry, logarithms, factorials — anything with a single correct numerical
+answer belongs in `calculate`.
+
+## Tool Quick Reference
+
+### calculate
+
+Takes `expression` (string) and optional `precision` (number, default 14).
+
+```
+calculate({ expression: "0.15 * 847" })
+calculate({ expression: "sin(30 deg)", precision: 6 })
+calculate({ expression: "12! / (4! * 8!)" })
+```
+
+For expression syntax, available functions, and edge cases, see
+[EXPRESSIONS.md](EXPRESSIONS.md).
+
+### convert
+
+Takes `value` (number), `from` (string), `to` (string).
+
+```
+convert({ value: 100, from: "fahrenheit", to: "celsius" })
+convert({ value: 60, from: "mph", to: "kph" })
+convert({ value: 1024, from: "bytes", to: "kB" })
+```
+
+For supported units, aliases, and categories, see [UNITS.md](UNITS.md).
+
+### statistics
+
+Takes `operation` (enum), `data` (number[]), optional `percentile` (0-100).
+
+```
+statistics({ operation: "mean", data: [85, 92, 78, 95, 88] })
+statistics({ operation: "percentile", data: [120, 340, 200, 150, 180], percentile: 90 })
+```
+
+Operations: `mean`, `median`, `mode`, `std`, `variance`, `min`, `max`, `sum`,
+`percentile`.
+
+For details on each operation and data format, see [STATISTICS.md](STATISTICS.md).

package/skills/math/STATISTICS.md

@@ -0,0 +1,51 @@
+# Statistics Reference — `statistics` tool
+
+## Operations
+
+| Operation    | Description               | Example                                                  |
+| ------------ | ------------------------- | -------------------------------------------------------- |
+| `mean`       | Arithmetic average        | `statistics("mean", [1, 2, 3])` → `2`                    |
+| `median`     | Middle value (sorted)     | `statistics("median", [1, 3, 5, 7])` → `4`               |
+| `mode`       | Most frequent value       | `statistics("mode", [1, 2, 2, 3])` → `2`                 |
+| `std`        | Sample standard deviation | `statistics("std", [2, 4, 6])` → `2`                     |
+| `variance`   | Sample variance           | `statistics("variance", [2, 4, 6])` → `4`                |
+| `min`        | Minimum value             | `statistics("min", [5, 1, 9])` → `1`                     |
+| `max`        | Maximum value             | `statistics("max", [5, 1, 9])` → `9`                     |
+| `sum`        | Sum of all values         | `statistics("sum", [10, 20, 30])` → `60`                 |
+| `percentile` | Value at nth percentile   | `statistics("percentile", [10, 20, 30], 90)` → see below |
+
+### Notes on specific operations
+
+**`mode`**: If multiple values share the highest frequency, returns the first one
+encountered. It does not return all modes.
+
+**`percentile`**: Requires the `percentile` parameter (0–100). This is the most
+common error — omitting it produces:
+
+```
+"Percentile value is required when operation is 'percentile'"
+```
+
+Example:
+
+```
+statistics({ operation: "percentile", data: [120, 340, 200, 150, 180], percentile: 90 })
+```
+
+**`std` and `variance`**: These compute **sample** standard deviation and variance
+(dividing by n-1), not population (dividing by n).
+
+## Data Format
+
+- Data is a plain JSON array of numbers: `[85, 92, 78, 95, 88]`
+- Array must contain at least one number (empty arrays are rejected)
+- Maximum 10,000 elements per array
+
+## Common Errors
+
+| Error                                  | Cause                      | Fix                               |
+| -------------------------------------- | -------------------------- | --------------------------------- |
+| "Data array is empty"                  | Empty `[]` passed          | Provide at least one number       |
+| "Percentile value is required..."      | `percentile` param missing | Add `percentile: N` (0–100)       |
+| "Percentile must be between 0 and 100" | Value out of range         | Use a value from 0 to 100         |
+| "Unknown operation"                    | Typo in operation name     | Use one of the 9 valid operations |

package/skills/math/UNITS.md

@@ -0,0 +1,130 @@
+# Unit Reference — `convert` tool
+
+## Supported Unit Categories
+
+### Length
+
+| Unit          | Aliases               |
+| ------------- | --------------------- |
+| Meter         | `m`, `cm`, `mm`, `km` |
+| Mile          | `mi`, `mile`, `miles` |
+| Yard          | `yd`                  |
+| Foot          | `ft`                  |
+| Inch          | `inch`, `in`          |
+| Nautical mile | `nmi`                 |
+
+### Mass
+
+| Unit     | Aliases         |
+| -------- | --------------- |
+| Kilogram | `kg`, `g`, `mg` |
+| Pound    | `lb`            |
+| Ounce    | `oz`            |
+| Ton      | `ton`           |
+| Stone    | `stone`         |
+
+### Volume
+
+| Unit        | Aliases                         |
+| ----------- | ------------------------------- |
+| Liter       | `liter`, `litre`, `litres`, `L` |
+| Milliliter  | `ml`, `mL`                      |
+| Gallon      | `gal`                           |
+| Pint        | `pint`                          |
+| Cup         | `cup`                           |
+| Fluid ounce | `floz`                          |
+
+### Temperature
+
+| Unit       | Code   | Natural language alias |
+| ---------- | ------ | ---------------------- |
+| Celsius    | `degC` | `celsius`              |
+| Fahrenheit | `degF` | `fahrenheit`           |
+| Kelvin     | `K`    | —                      |
+| Rankine    | `degR` | —                      |
+
+Temperature units in mathjs are `degC` and `degF`, but you can use `celsius` and
+`fahrenheit` — they are normalized automatically.
+
+### Speed
+
+| Unit                      | Code                        |
+| ------------------------- | --------------------------- |
+| Meters per second         | `m/s`                       |
+| Kilometers per hour       | `km/h`                      |
+| Miles per hour            | `mph`                       |
+| Kilometers per hour (alt) | `kph`, `kmh`                |
+| Knots                     | `knot`, `knots`, `kn`, `kt` |
+
+### Time
+
+| Unit   | Code   |
+| ------ | ------ |
+| Second | `s`    |
+| Minute | `min`  |
+| Hour   | `h`    |
+| Day    | `day`  |
+| Week   | `week` |
+
+### Area
+
+| Unit             | Code     | Natural language alias |
+| ---------------- | -------- | ---------------------- |
+| Square meter     | `m^2`    | `square meters`        |
+| Square foot      | `ft^2`   | `square feet`          |
+| Square kilometer | `km^2`   | `square kilometers`    |
+| Square mile      | `mile^2` | `square miles`         |
+
+### Volume (Cubic)
+
+| Unit        | Code   | Natural language alias |
+| ----------- | ------ | ---------------------- |
+| Cubic meter | `m^3`  | `cubic meters`         |
+| Cubic foot  | `ft^3` | `cubic feet`           |
+| Cubic inch  | `in^3` | `cubic inches`         |
+
+### Data
+
+| Unit     | Code            |
+| -------- | --------------- |
+| Byte     | `byte`, `bytes` |
+| Kilobyte | `kB`            |
+| Megabyte | `MB`            |
+| Gigabyte | `GB`            |
+| Terabyte | `TB`            |
+| Bit      | `b`             |
+| Kilobit  | `kb`            |
+| Megabit  | `Mb`            |
+| Gigabit  | `Gb`            |
+| Terabit  | `Tb`            |
+
+## Natural Language Aliases
+
+These are normalized automatically (case-insensitive):
+
+| You can say...        | Converted to |
+| --------------------- | ------------ |
+| `celsius`             | `degC`       |
+| `fahrenheit`          | `degF`       |
+| `kilometers per hour` | `km/hour`    |
+| `miles per hour`      | `mile/hour`  |
+| `meters per second`   | `m/s`        |
+| `feet per second`     | `ft/s`       |
+| `square meters`       | `m^2`        |
+| `square feet`         | `ft^2`       |
+| `square kilometers`   | `km^2`       |
+| `square miles`        | `mile^2`     |
+| `cubic meters`        | `m^3`        |
+| `cubic feet`          | `ft^3`       |
+| `cubic inches`        | `in^3`       |
+| `litres`              | `liter`      |
+
+## Incompatible Units
+
+Both units must measure the same quantity. Converting between different quantities
+(e.g., `kg` to `km`, or `degC` to `mph`) returns an error:
+
+```
+"Units are incompatible. Ensure both measure the same quantity
+(e.g., length to length, weight to weight)."
+```