truthguard-ai 0.1.5 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ Most "hallucinations" in tool-calling agents are **grounding failures** — the
 TruthGuard extracts factual claims from the agent's response, cross-references them against tool outputs, and reports grounding failures with standardized codes — like OBD diagnostic codes for AI.
 
 ```
-npm install truthguard
+npm install truthguard-ai
 ```
 
 **Zero LLM calls.** 30+ deterministic failure detectors. Runs in <50ms.
@@ -30,7 +30,7 @@ npm install truthguard
 ### 1. Evaluate a trace
 
 ```typescript
-import { TraceBuilder, GroundingEngine, generateReport } from 'truthguard';
+import { TraceBuilder, GroundingEngine, generateReport } from 'truthguard-ai';
 
 const trace = new TraceBuilder({ traceId: 'run-001' })
   .addUserInput('How many employees are on leave today?')
@@ -55,7 +55,7 @@ console.log(text);
 ### 2. Add a CI quality gate
 
 ```typescript
-import { loadDataset, runDataset, evaluateGate, loadGateConfig } from 'truthguard';
+import { loadDataset, runDataset, evaluateGate, loadGateConfig } from 'truthguard-ai';
 
 const entries = loadDataset('./test-cases.jsonl');
 const result = runDataset(entries);
@@ -73,7 +73,7 @@ if (!verdict.pass) {
 Works with **any language** — PHP, Python, Go, Java, Ruby, C#:
 
 ```bash
-npx truthguard observe --port 3001
+npx truthguard-ai observe --port 3001
 ```
 
 Change your AI base URL:
@@ -112,7 +112,7 @@ Every detected failure includes actionable diagnostics — root cause identifica
 Configure per-failure actions — block, warn, or observe:
 
 ```typescript
-import { wrapOpenAI, GroundingError } from 'truthguard';
+import { wrapOpenAI, GroundingError } from 'truthguard-ai';
 import OpenAI from 'openai';
 
 const openai = wrapOpenAI(new OpenAI(), {
@@ -131,7 +131,7 @@ const openai = wrapOpenAI(new OpenAI(), {
 ### Baseline Regression Detection
 
 ```typescript
-import { createSnapshot, saveBaseline, loadBaseline, compareToBaseline } from 'truthguard';
+import { createSnapshot, saveBaseline, loadBaseline, compareToBaseline } from 'truthguard-ai';
 
 // Save after a known-good run
 const snapshot = createSnapshot(result, 'v1.2-main');
@@ -158,7 +158,7 @@ Use TruthGuard directly from your IDE — no terminal needed.
     "truthguard": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "truthguard", "mcp"]
+      "args": ["-y", "truthguard-ai", "mcp"]
     }
   }
 }
@@ -178,7 +178,7 @@ Full setup guide: [docs/getting-started.md](docs/getting-started.md#ide--mcp-ser
 
 ```typescript
 import express from 'express';
-import { groundingMiddleware, FileStore } from 'truthguard';
+import { groundingMiddleware, FileStore } from 'truthguard-ai';
 
 const app = express();
 app.post('/api/chat', groundingMiddleware({
@@ -193,10 +193,10 @@ app.post('/api/chat', groundingMiddleware({
 ## CLI
 
 ```bash
-npx truthguard debug trace.json              # Evaluate one trace
-npx truthguard run dataset.jsonl             # Batch dataset evaluation
-npx truthguard run dataset.jsonl --gate gate.yml  # CI quality gate
-npx truthguard observe --port 3001           # Start observe server + proxy
+npx truthguard-ai debug trace.json              # Evaluate one trace
+npx truthguard-ai run dataset.jsonl             # Batch dataset evaluation
+npx truthguard-ai run dataset.jsonl --gate gate.yml  # CI quality gate
+npx truthguard-ai observe --port 3001           # Start observe server + proxy
 ```
 
 ---
@@ -219,7 +219,7 @@ jobs:
         with:
           node-version: '20'
       - run: npm ci
-      - run: npx truthguard run test-cases.jsonl --gate .ai-rcp-gate.yml
+      - run: npx truthguard-ai run test-cases.jsonl --gate .ai-rcp-gate.yml
 ```
 
 ### Gate config (`.ai-rcp-gate.yml`)

package/dist-npm/Claims/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Claim Extractor
+ *
+ * Extracts factual claims from free-form LLM text.
+ *
+ * V1 supports:
+ *   - numbers  (integer and decimal)
+ *   - dates    (common formats → ISO-8601)
+ *   - names    (capitalised multi-word proper nouns)
+ *   - counts   (explicit "N [items]" patterns)
+ *
+ * V1 explicitly skips vague qualitative claims ("most", "significant", "many").
+ */
+import type { Claim, TraceStepRole } from '../types';
+/**
+ * Attempt to parse a date-like string into an ISO-8601 date (YYYY-MM-DD).
+ * Returns null if parsing fails.
+ */
+export declare function tryParseDate(raw: string, _referenceDate?: Date): string | null;
+/**
+ * A date range representing a period (inclusive start, inclusive end).
+ */
+export interface PeriodBounds {
+    start: string;
+    end: string;
+    label: string;
+}
+/**
+ * Parse a period expression into start/end bounds.
+ * Supports: Q1-Q4, H1/H2, FY, YTD, MTD, "last quarter", "this quarter",
+ * "last month", "this month", "MonthName YYYY", "YYYY", rolling periods.
+ *
+ * Returns null if the expression is not a recognized period.
+ */
+export declare function parsePeriodBounds(raw: string, referenceDate?: Date): PeriodBounds | null;
+/**
+ * Strip diacritics (č→c, ć→c, š→s, ž→z, đ→d, etc.) and lowercase.
+ * Allows entity matching across diacritic and case variants.
+ */
+export declare function normalizeEntityName(name: string): string;
+/**
+ * Check if two entity names refer to the same person/thing.
+ * Handles: case, diacritics, partial name matching (first/last name subset).
+ */
+export declare function entitiesMatch(a: string, b: string): boolean;
+/**
+ * Strips combining diacritical marks for matching purposes.
+ * "Tasić" → "Tasic", "Čačak" → "Cacak", "Новосибирск" → "Новосибирск" (Cyrillic unchanged).
+ * Uses Unicode NFD decomposition + strip combining marks (U+0300–U+036F).
+ */
+export declare function normalizeDiacritics(str: string): string;
+/** Options for claim extraction. */
+export interface ExtractorOptions {
+    /** Step ID of the source (defaults to 'unknown'). */
+    sourceStepId?: string;
+    /** Role of the source step. */
+    sourceRole?: TraceStepRole;
+    /** Reference date for resolving relative dates ("yesterday", "pre 3 dana"). Defaults to now. */
+    referenceDate?: Date;
+}
+/**
+ * Extracts factual claims from a text string.
+ *
+ * Extraction order:
+ * 1. Dates  — before numbers so date digits are not re-extracted as numbers
+ * 2. Counts — before numbers so count numerals are not re-extracted as plain numbers
+ * 3. Numbers
+ * 4. Names
+ *
+ * Vague qualitative claims are skipped.
+ */
+export declare function extractClaims(text: string, options?: ExtractorOptions): Claim[];
+//# sourceMappingURL=index.d.ts.map

package/dist-npm/Claims/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Claims/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,KAAK,EAA0B,aAAa,EAAY,MAAM,UAAU,CAAC;AAyGvF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CA6J9E;AAcD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAYD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,YAAY,GAAG,IAAI,CAyLxF;AAkXD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAoB3D;AAqSD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AA4CD,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,gGAAgG;IAChG,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,KAAK,EAAE,CA4jBnF"}