@criterionx/core 0.1.2 → 0.2.0

package/README.md

@@ -1,70 +1,143 @@
-# Criterion
+<p align="center">
+  <img src="criterion.jpg" alt="Criterion" width="100%" />
+</p>
 
-Criterion is a **universal decision engine** for defining and executing business-critical decisions with:
+<p align="center">
+  <strong>A universal, deterministic, and explainable decision engine for business-critical systems.</strong>
+</p>
 
-- **Mandatory contracts** (validated inputs & outputs)
-- **Deterministic evaluation** (same inputs → same result)
-- **Explainability first-class** (every result has a reason + trace)
-- **Zero side effects** (no DB, no fetch, no IO inside decisions)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@criterionx/core"><img src="https://img.shields.io/npm/v/@criterionx/core.svg" alt="npm version"></a>
+  <a href="https://github.com/tomymaritano/criterionx/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@criterionx/core.svg" alt="license"></a>
+  <a href="https://tomymaritano.github.io/criterionx/"><img src="https://img.shields.io/badge/docs-vitepress-brightgreen.svg" alt="docs"></a>
+</p>
 
-> If it's not in Criterion, it's not a decision.
+---
 
-## What Criterion is
+## What is Criterion?
 
-Criterion is **not** a web framework and it does **not** fetch data.
-It runs decisions against a provided **Context**.
+Criterion helps you encode business decisions as **pure, testable functions** with built-in validation and explainability.
 
-A decision is a small, explicit unit of business logic:
-- inputs (schema)
-- outputs (schema)
-- rules (ordered)
-- explanations (trace)
+Instead of scattering `if/else` statements across your codebase, you define decisions declaratively:
 
-## What Criterion is not
+- **"Should this transaction be flagged as high-risk?"**
+- **"Is this user eligible for a premium tier?"**
+- **"What discount applies to this order?"**
 
-Criterion is **not**:
-- a workflow/BPMN engine
-- an enterprise rules platform
-- a plugin marketplace
-- a data pipeline
-- a forecasting system
+Every decision returns not just a result, but a complete explanation of *why* that result was reached — perfect for audits, debugging, and compliance.
 
-Criterion is a **micro engine**: small core, strict boundaries.
+## Installation
 
-## Decision Profiles (key idea)
+```bash
+npm install @criterionx/core zod
+```
 
-Criterion supports **Decision Profiles**: the same decision, different thresholds/sensitivity.
+## Quick Start
+
+```typescript
+import { Engine, defineDecision } from "@criterionx/core";
+import { z } from "zod";
+
+const riskDecision = defineDecision({
+  id: "transaction-risk",
+  version: "1.0.0",
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.object({ risk: z.enum(["HIGH", "MEDIUM", "LOW"]) }),
+  profileSchema: z.object({ threshold: z.number() }),
+  rules: [
+    {
+      id: "high-risk",
+      when: (input, profile) => input.amount > profile.threshold,
+      emit: () => ({ risk: "HIGH" }),
+      explain: (input, profile) => `Amount ${input.amount} > ${profile.threshold}`,
+    },
+    {
+      id: "low-risk",
+      when: () => true,
+      emit: () => ({ risk: "LOW" }),
+      explain: () => "Amount within acceptable range",
+    },
+  ],
+});
+
+const engine = new Engine();
+const result = engine.run(
+  riskDecision,
+  { amount: 15000 },
+  { profile: { threshold: 10000 } }
+);
+
+console.log(result.data);  // { risk: "HIGH" }
+console.log(engine.explain(result));
+// Decision: transaction-risk v1.0.0
+// Status: OK
+// Matched: high-risk
+// Reason: Amount 15000 > 10000
+```
 
-Profiles are injected explicitly at runtime:
+## Features
 
-```ts
-engine.run(decision, context, { profile: "high-inflation" })
-```
+- **Pure & Deterministic** — Same input always produces the same output
+- **Fully Explainable** — Every decision includes a complete audit trail
+- **Contract-First** — Zod schemas validate inputs, outputs, and profiles
+- **Profile-Driven** — Parameterize decisions by region, tier, or environment
+- **Zero Side Effects** — No I/O, no database, no external calls
+- **Testable by Design** — Pure functions are trivial to test
+
+## Documentation
+
+Full documentation available at **[tomymaritano.github.io/criterion](https://tomymaritano.github.io/criterionx/)**
+
+- [Getting Started](https://tomymaritano.github.io/criterionx/guide/getting-started)
+- [Core Concepts](https://tomymaritano.github.io/criterionx/guide/core-concepts)
+- [API Reference](https://tomymaritano.github.io/criterionx/api/engine)
+- [Examples](https://tomymaritano.github.io/criterionx/examples/currency-risk)
+
+## Core Concepts
 
-Profiles are not data. They are interpretation settings.
+### Decisions
 
-## Repository structure
+A decision is a unit of business logic with:
+- **Input schema** — What data is required
+- **Output schema** — What the decision returns
+- **Profile schema** — What can be parameterized
+- **Rules** — The evaluation logic
 
-- `docs/` — foundational documentation
-- `examples/` — decision specs in declarative formats (no code required)
-- `diagrams/` — Mermaid diagrams for architecture (optional early)
-- `src/` — future minimal TS implementation (later)
+### Rules
 
-## Examples (domain-agnostic)
+Rules are evaluated in order. First match wins:
 
-Finance:
-- `examples/finance/currency-exposure-risk/` — generic currency risk using profiles
+```typescript
+rules: [
+  { id: "rule-1", when: (i) => i.x > 100, emit: ..., explain: ... },
+  { id: "rule-2", when: (i) => i.x > 50, emit: ..., explain: ... },
+  { id: "default", when: () => true, emit: ..., explain: ... },
+]
+```
+
+### Profiles
+
+Profiles parameterize decisions without changing logic:
+
+```typescript
+// Same decision, different thresholds
+engine.run(decision, input, { profile: usProfile });
+engine.run(decision, input, { profile: euProfile });
+```
 
-Non-financial:
-- `examples/eligibility/user-tier-eligibility/` — user tier eligibility decision
+## What Criterion Is NOT
 
-## Start here
+- A workflow/BPMN engine
+- A machine learning framework
+- A data pipeline
+- A plugin marketplace
 
-- `docs/00-manifesto.md`
-- `docs/04-decision-profiles.md`
-- `examples/finance/currency-exposure-risk/decision.xml`
-- `examples/eligibility/user-tier-eligibility/decision.xml`
+Criterion is a **micro engine**: small core, strict boundaries.
 
 ## License
 
-MIT
+[MIT](LICENSE)
+
+## Author
+
+**Tomas Maritano** — [@tomymaritano](https://github.com/tomymaritano)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@criterionx/core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Universal decision engine for business-critical decisions",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,11 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "benchmark": "tsx benchmarks/run.ts",
+    "prepublishOnly": "npm run build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "decision-engine",
@@ -42,16 +46,18 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tomymaritano/criterion.git"
+    "url": "https://github.com/tomymaritano/criterionx.git"
   },
   "bugs": {
-    "url": "https://github.com/tomymaritano/criterion/issues"
+    "url": "https://github.com/tomymaritano/criterionx/issues"
   },
-  "homepage": "https://github.com/tomymaritano/criterion#readme",
+  "homepage": "https://github.com/tomymaritano/criterionx#readme",
   "devDependencies": {
     "@vitest/coverage-v8": "^2.0.0",
     "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
     "typescript": "^5.3.0",
+    "vitepress": "^1.6.4",
     "vitest": "^2.0.0",
     "zod": "^3.22.0"
   },