ai-trust-score 1.0.2 → 1.0.3

package/README.md

@@ -1,112 +1,149 @@
-# ai-trust-score — developer summary
+# ai-trust-score — deterministic, local validator for LLM outputs
 
-ai-trust-score performs deterministic checks on model outputs to help teams gate, audit, and monitor LLM-generated text and structured responses. The repository is source-first: the package exposes `src/` as the module entry and does not commit build artifacts.
+ai-trust-score helps teams detect and block common, deterministic problems in model-generated text and structured outputs. It's designed to run locally (no external APIs), in CI pipelines, or inside backend services that produce or relay LLM responses. The goal is to give you small, auditable reports that help automate gating, auditing, and monitoring of LLM outputs.
 
-## Install
+This README is intentionally comprehensive: quickstart, programmatic examples (CommonJS and ESM), how to apply ai-trust-score to API responses, CLI/batch usage, an illustrative report, configuration options, recommended policies, and contribution notes.
 
-```bash
-npm install ai-trust-score
-```
-
-## Exports and what they do
+Why ai-trust-score
 
-- validateLLM(input, config?)
-  - input: string | object. Runs enabled detectors over the provided model output and returns a compact report with fields `ok` (boolean), `score` (0–100), and `issues` (array).
-  - config options: `detectors` (object to enable/disable), `verbose` (boolean to include `summary`, `meta`, and `config`), and detector-specific options.
+- Deterministic and auditable — no external black-box calls.
+- Low operational cost — runs on your infrastructure.
+- Extensible — add domain-specific JSON rule packs or custom detectors.
 
-- guardHandler(handler, options)
-  - Accepts an async handler that returns model output. Runs validation on the handler's output and maps the result to HTTP responses: success yields 200 with `{ output, report }`; blocked yields 422 with `{ blocked: true, report }`.
-  - Options include `threshold` (score threshold for blocking) and `validateConfig` (overrides for validateLLM).
+What ai-trust-score checks (examples)
 
-- types
-  - Re-exported TypeScript type definitions for the public API and detector shapes.
+- Schema validation: verify JSON outputs conform to your schema.
+- Numeric consistency: flag mismatched percentages, impossible arithmetic, or inconsistent ranges.
+- Hallucination heuristics: detect claims that appear fabricated or unverifiable.
+- Overconfidence: detect absolute or sweeping claims presented without evidence.
+- Simple contradiction checks: find sentence-level contradictions within one output.
 
-## Core config fields
+Quick install
 
-- `detectors`: enable or disable detectors by name, for example `{ numeric: true, hallucination: true }`.
-- `verbose`: when true the report includes `summary`, `meta` (timestamp, inputType, packageVersion, detectors), and `config`.
-- `threshold`: numeric threshold used by `guardHandler` to decide whether to block outputs.
+```bash
+npm install ai-trust-score
+# or
+yarn add ai-trust-score
+```
 
-## Built-in detectors
+Programmatic usage — CommonJS (server-side)
 
-- `numeric` — basic numeric consistency checks (simple arithmetic and percent sanity checks).
-- `hallucination` — pattern-based heuristics that flag likely hallucinated facts.
-- `inconsistency` — detects internal contradictions in a single output.
-- `overconfidence` — flags overly certain language when claims are uncertain.
+```js
+// Import the validator and run it on a single string output
+const { validateLLM } = require('ai-trust-score');
 
-## Issue object layout
+const text = 'The product revenue grew 20% from 100 to 150.';
+const report = validateLLM(text, {
+  detectors: { numericConsistency: true, overconfidence: true, hallucination: true },
+  // customRules: { /* optional domain-specific rules */ }
+});
 
-- `type`: detector name (string)
-- `severity`: `low | medium | high`
-- `message`: short human-friendly description
-- `meta`: optional detector-specific evidence object
+console.log(report.score);   // 0..100
+console.log(report.issues);  // array of issues
+```
 
-## Examples
+Programmatic usage — ESM / TypeScript
 
-CommonJS
+```ts
+import { validateLLM } from 'ai-trust-score';
 
-```js
-const { validateLLM } = require('ai-trust-score');
 const report = validateLLM('The capital of France is Berlin.', { detectors: { hallucination: true } });
 console.log(report);
 ```
 
-ESM / TypeScript
+Applying ai-trust-score to API responses (recommended patterns)
 
-```ts
-import validateLLM from 'ai-trust-score';
-const report = validateLLM('Revenue grew 20% from 100 to 150', { detectors: { numeric: true }, verbose: true });
-console.log(report.summary);
+Inline validation (explicit)
+
+```js
+const modelOutput = await myLLM.generate(prompt);
+const report = validateLLM(modelOutput);
+if (report.score < 75) {
+  // return a safe fallback, request regeneration, or present a human review flag
+}
 ```
 
-Express minimal handler
+Middleware pattern (convenience)
 
 ```js
-const express = require('express');
-const { guardHandler } = require('ai-trust-score');
+import express from 'express';
+import { llmGuardMiddleware } from 'ai-trust-score';
+
 const app = express();
 app.use(express.json());
 
-app.post('/generate', guardHandler(async (req) => {
-  // return model output (string or object)
-  return await myLLM.generate(req.body.prompt);
-}, { threshold: 80 }));
+app.post('/generate', llmGuardMiddleware({ threshold: 80 }), (req, res) => {
+  const { allowed, report, output } = res.locals;
+  if (!allowed) return res.status(422).json({ error: 'Blocked by ai-trust-score', report });
+  res.json({ reply: output, report });
+});
+```
+
+Policy notes
+
+- Thresholds are organizational: 80 is a sensible starting point. Use higher thresholds in high-risk domains.
+- Instead of outright blocking, consider fallback behaviors: regenerate, lower-risk response, or human review.
+
+CLI & batch usage
+
+The package exposes a small CLI for ad-hoc checks and a batch mode for audits. Use the published package via `npx ai-trust-score` or install it locally.
+
+```bash
+# Human-friendly table
+npx ai-trust-score check --file path/to/output.txt
+
+# Machine-readable JSON
+npx ai-trust-score check --file path/to/output.txt --json
 
-app.listen(3001);
+# Batch audit (JSONL -> results + HTML summary)
+npx ai-trust-score batch --file samples.jsonl --out results.jsonl --parallel 8 --html report.html
 ```
 
-## Sample verbose report
+Illustration — sample GuardReport
+
+Calling `validateLLM(text, config)` returns a `GuardReport` object. Example:
 
 ```json
 {
-  "ok": false,
   "score": 92,
   "issues": [
-    { "type": "numeric", "severity": "medium", "message": "Percent change inconsistent: 100 -> 150 is 50% not 20%", "meta": { "expected": "50%", "actual": "20%" } }
+    {
+      "detector": "numeric-consistency",
+      "severity": "medium",
+      "message": "20% inconsistent with increase from 100 to 150 (~50%).",
+      "meta": { "found": "20%", "expectedApprox": "50%", "evidence": "increase from 100 to 150" }
+    }
   ],
-  "summary": "Detected 1 issue(s). Trust score 92/100.",
-  "meta": { "timestamp": "2026-02-18T00:48:32.716Z", "inputType": "string", "packageVersion": "1.0.1", "detectors": ["numeric","hallucination"] },
-  "config": { "detectors": { "numeric": true }, "verbose": true }
+  "summary": "Detected 1 issue(s). Trust score 92/100."
 }
 ```
 
-## Run CLI/demo locally (source-first)
+Fields explained
 
-```bash
-# run CLI (uses src/)
-npm run cli
+- `score`: integer 0–100. Starts at 100 and subtracts penalties according to issue severities.
+- `issues`: array of objects { detector, severity, message, meta }.
+- `summary`: short, human-friendly summary.
 
-# run demo script
-npm run demo
-```
+Configuration and extension points
+
+- `GuardConfig` (second parameter to `validateLLM`) accepts:
+  - `detectors`: enable/disable detector groups (e.g., `numericConsistency`, `hallucination`).
+  - `customRules`: JSON rule packs to add or override existing patterns.
+  - `threshold`: an app-level policy useful for middleware.
 
-## Notes and tips
+Custom rules example
 
-- The project is intentionally source-first. If you prefer built artifacts, set `prepare` to run the build and point `main`/`bin` at `dist/`.
-- Use `verbose: true` for debugging detector evidence.
+```js
+const custom = {
+  hallucination: [
+    { id: 'hall-001', pattern: "\\bthe capital of mars\\b", severity: 'high', message: 'Fictional location' }
+  ]
+};
+const r = validateLLM('The capital of Mars is Olympus City.', { customRules: custom });
+```
 
-## License
 
-See the `LICENSE` file in this repository.
+License, support, and ethos
 
-Made with love by ahmadraza100
+- License: see `LICENSE`.
+- Made with ❤️ by ahmadraza100. Open to expand — if you need help with curated rule packs or secure deployment, open an issue or reach out via the repository.

package/package.json

@@ -1,17 +1,16 @@
 {
     "name": "ai-trust-score",
-        "version": "1.0.2",
+    "version": "1.0.3",
     "description": "ai-trust-score — deterministic validator for LLM outputs (schema, heuristics, consistency checks)",
     "main": "src/index.js",
     "types": "src/index.d.ts",
     "scripts": {
-            "build": "if [ -d src ]; then tsc -p tsconfig.json; else echo 'no src, skip build'; fi",
+        "build": "if [ -d src ]; then tsc -p tsconfig.json; else echo 'no src, skip build'; fi",
         "test": "vitest",
         "prepare": "echo 'skip build on pack'",
         "cli": "node ./src/cli.js",
         "demo": "node ./src/demo.js",
         "publish:github": "node ./scripts/publish-github.js"
-            ,"release": "npm version patch && npm publish"
     },
     "keywords": [
         "llm",