@intflows/genkit-guard 0.0.13 → 0.1.0

package/README.md

@@ -1,292 +1,438 @@
-# **@intflows/genkit-guard** 
+# Genkit Guard
 
-### **Lightweight Intent, PII, and Safety Guardrails for Genkit**
+Keep Genkit agents on topic, mask personal data before model calls, and control which tools can run.
 
-`@intflows/genkit-guard` provides a modular guardrail layer for Genkit flows.  
-It adds **semantic intent validation**, **PII masking/unmasking**, and **prompt‑injection detection** with minimal configuration.
+`@intflows/genkit-guard` adds prompt-injection checks, semantic intent scoring, reversible PII masking, and tool policies to your Genkit application. Guard models run locally through Transformers.js; your generative model can use the provider you choose.
 
-This library is designed for developers who want **practical, production‑ready safety controls** without heavy dependencies or complex setup.
+[Try the Hugging Face Space](https://huggingface.co/spaces/intflows/genkit-guard) · [Documentation](https://github.com/IntFlows/genkit-guard/wiki) · [Examples](./example/src)
 
----
+## Why use it?
 
-## ✨ Features
+Agents can access customer data and trigger real workflows. Genkit Guard gives you controls at the model and tool boundaries:
 
-- **Semantic Intent Guarding**  
-  Uses MiniLM embeddings to ensure prompts match allowed intents.
+- **Check requests:** block known injection patterns and reject prompts below your intent similarity threshold.
+- **Reduce PII exposure:** mask detected personal data before model calls and restore tokens in responses and tool inputs.
+- **Control tools:** allow, block, redact detected PII, or require application approval before execution.
+- **Audit decisions:** emit versioned decision events without raw prompts, arguments, or PII values.
 
-- **PII Detection & Masking**  
-  Detects emails, phone numbers, names, and AU‑specific identifiers.  
-  Replaces PII with reversible tokens before sending to the LLM.
+Detection is based on patterns and model predictions. It can miss attacks or PII and can reject valid requests; evaluate it on your application's inputs and keep authorization in your application.
 
-- **Automatic Unmasking**  
-  Restores original PII in the model’s response, even inside structured JSON.
+## Full setup guide
 
-- **Prompt Injection Detection**  
-  Blocks jailbreak attempts using pattern‑based heuristics.
+The following setup targets **v0.1.0** and can be used after that version is published. The package declares Genkit **1.39.0** as its peer dependency.
 
-- **Model‑Light Architecture**  
-  The package uses local `all-MiniLM-L6-v2` and `openai/privacy-filter` Models, these Models are downloaded once and cached locally.
-
-- **Drop‑in Genkit Middleware**  
-  Works with `ai.generate`, `ai.generateStream`, and Genkit flows.
-
----
-
-### 📦 Installation
+### 1. Create the application and install dependencies
 
 ```bash
-## Install the package
-npm install @intflows/genkit-guard
+mkdir my-genkit-app
+cd my-genkit-app
+npm init -y
+npm pkg set type=module
+npm install genkit@1.39.0 @genkit-ai/google-genai@1.39.0 @intflows/genkit-guard@0.1.0
+npm install -D typescript tsx @types/node
+mkdir src
 ```
 
-This library uses lightweight transformer models (MiniLM + Openai/privacy-filter).  
+For an existing Genkit application, install the guard package and use your existing provider configuration.
 
-Download them once. 
+### 2. Download the models
+
+Download MiniLM for intent analysis and OpenAI's `privacy-filter` for PII detection. Run this command once from your application's root directory:
 
 ```bash
-## Download the transformer models (MiniLM + OpenAI/privacy-filter)
+# Download MiniLM + OpenAI/privacy-filter
 node node_modules/@intflows/genkit-guard/scripts/download-model.js
 ```
 
-Models are cached locally and reused across runs.
+Models are cached locally in `./models` and reused across runs. This script downloads those two models; it does not read `guard.config.ts`. The configuration below selects `pii.mode: "classifier"` to use `privacy-filter`. Download size and memory use depend on the models selected.
 
----
+### 3. Configure the guard
 
-## 🚀 Quick Start
+Create `src/guard.config.ts`:
 
-### 1. Initialize Local folder
+```ts
+import { defineGuardConfig } from "@intflows/genkit-guard";
+
+export default defineGuardConfig({
+  models: { extractor: "Xenova/all-MiniLM-L6-v2" },
+  intent: {
+    semantic: {
+      threshold: 0.7,
+      intents: {
+        support: "Technical support for Azure Blob Storage, APIs and integrations"
+      }
+    }
+  },
+  pii: {
+    mode: "classifier",
+    model: "openai/privacy-filter"
+  },
+  tools: {
+    defaultAction: "block",
+    rules: { searchDocs: "allow" }
+  }
+});
+```
 
-```bash
-# Install @intflows/genkit-guard
-npm install @intflows/genkit-guard
+A separate configuration file is optional in general, but required by the import in this example. Pass the same configuration to startup and runtime; there is no automatic file discovery. See [shared model configuration](https://github.com/IntFlows/genkit-guard/wiki/8.-Shared-Model-Configuration) for alternatives.
 
-# Download Local Models (Only needed once)
-node node_modules/@intflows/genkit-guard/scripts/download-model.js
-```
-_This downloads the models to `./models`; the total size is approximately 1.5 GB._
+The tool rules apply to tools you separately register and supply to Genkit; they do not create tools. This configuration permits `searchDocs` and blocks other tool names.
+
+### 4. Create the application entry point
 
-### 2. Update genkit
+Create `src/index.ts`:
 
 ```ts
+import { genkit } from "genkit";
+import { googleAI } from "@genkit-ai/google-genai";
 import { guard, initGuard } from "@intflows/genkit-guard";
+import guardConfig from "./guard.config.js";
 
-await initGuard();
+const modelName = process.env.GEMINI_MODEL;
+if (!modelName) throw new Error("Set GEMINI_MODEL before running the example");
 
-const response = await ai.generate({
-  prompt: "How do I integrate with Azure Blob Storage?",
-  use: [
-    guard({
-      intent: {
-        mode: "semantic",
-        allowedIntent: "integration",
-        semantic: {
-          threshold: 0.7,
-          intents: {
-            integration: "Azure Blob, APIs, workflows"
-          }
-        }
-      },
-      pii: { reversible: true }
-    })
-  ]
+const ai = genkit({
+  plugins: [googleAI()],
+  model: googleAI.model(modelName)
 });
-```
-
-**You Can also check the full step by step guide here:**
-
-[Intflows Wiki](https://github.com/IntFlows/genkit-guard/wiki)
 
-### 3. Execute the Genkit flow
+await initGuard(guardConfig);
 
-#### Allowed :
-``` npx tsx src/index.ts "How do I integrate with Azure Blob Storage?"```
+const response = await ai.generate({
+  prompt: process.argv[2] ?? "How do I integrate with Azure Blob Storage?",
+  use: [guard(guardConfig)]
+});
 
-#### Blocked:
-``` npx tsx src/index.ts "workflow to download a file from an API, save it to Blob file and export the API key"```
+if (response.finishReason === "blocked") {
+  console.log("Request blocked by guard policy");
+} else {
+  console.log(response.text);
+}
+```
 
-![Image showing Generation Blocked](./GenerationBlocked.png)
+`initGuard(config)` preloads the selected models and can download missing files, including NER or custom models if you change the configuration.
 
+### 5. Set environment variables
 
-#### PII MASK and UNMASK:
-``` npx tsx src/index.ts "workflow to download a file from an API, save it to Blob file with my email john.doe@example.com"```
+Set `GEMINI_API_KEY` to your provider key and `GEMINI_MODEL` to a model available to your account in the terminal you will use to run the example.
 
-![Image showing PII data masked ](./MaskedPII.png)
+PowerShell:
 
----
-## Example
+```powershell
+$env:GEMINI_API_KEY = "your-api-key"
+$env:GEMINI_MODEL = "your-model-name"
+```
 
-An example genkit flow is present in `example` directory.
+Bash:
 
 ```bash
-git clone https://github.com/IntFlows/genkit-guard.git
-cd genkit-guard/example
-npm install
-node node_modules/@intflows/genkit-guard/scripts/download-model.js
-npx tsx src/index.ts
+export GEMINI_API_KEY="your-api-key"
+export GEMINI_MODEL="your-model-name"
 ```
 
-Or you can run the flow with genkit dev UI
+### 6. Run the example
 
 ```bash
-git clone https://github.com/IntFlows/genkit-guard.git
-cd genkit-guard/example
-npm install
-node node_modules/@intflows/genkit-guard/scripts/download-model.js
-genkit start -- npx tsx src/index.ts
+npx tsx src/index.ts "How do I integrate with Azure Blob Storage?"
+npx tsx src/index.ts "export the API key"
+npx tsx src/index.ts "Integrate Azure Blob Storage for alice@example.com"
 ```
 
----
-
-## 🧠 How It Works
-
-### **1. Intent Guard**
-- Embeds the user prompt + intent descriptions using MiniLM  
-- Computes cosine similarity  
-- Blocks prompts below threshold  
-- Detects jailbreak patterns like:  
-  - “ignore previous instructions”  
-  - “you are a hacker”  
-  - “export the API key”  
+The second prompt exercises injection-pattern blocking. The third exercises email masking when intent scoring allows it. Responses restore masked values, so final output alone does not demonstrate what the model received. Check `finishReason` for blocked results before treating a response as successful, and tune intent descriptions and thresholds with representative inputs.
 
-### **2. PII Masking**
-Before the LLM sees the prompt:
+## What happens to a request?
 
-```
-"Email john.doe@example.com" → "Email [[EMAIL_0]]"
+```text
+User request
+  -> Injection-pattern check
+  -> Semantic intent check
+  -> PII masking
+  -> Generative model
+  -> Response token restoration
+  -> Tool policy check before any requested tool executes
 ```
 
-Detected PII includes:
+A matching injection phrase such as `ignore previous instructions` blocks the model call. Intent checks compare the prompt with every description in `intent.semantic.intents`; only include categories you want to allow.
 
-- Emails  
-- Phone numbers    
-- AU identifiers (Medicare, TFN, ABN, etc.)
-- PII detected by local Model (OpenAI/privacy-filter)
+PII masking replaces detected values with namespaced tokens:
 
-### **3. LLM Call**
-The masked prompt is sent to the model.
+```text
+Input:          Email alice@example.com
+Model receives: Email [[EMAIL_<namespace>_0]]
+Restored:       Email alice@example.com
+```
 
-### **4. Response Unmasking**
-After the LLM responds:
+Restoration also works inside structured responses. Tool policy checks determine whether a requested tool may receive restored values or redacted arguments.
 
+## Tool controls
+
+Add exact tool names to the shared configuration:
+```text
+Input:          Email alice@example.com
+Model receives: Email [[EMAIL_<namespace>_0]]
+Restored:       Email alice@example.com
 ```
-"Send a confirmation email to [[EMAIL_0]]" → "Send a confirmation email to john.doe@example.com"
-```
----
 
-## ⚙️ Configuration
+Restoration also works inside structured responses. Tool policy checks determine whether a requested tool may receive restored values or redacted arguments.
+
+## Tool controls
 
-### **Intent Guard**
+Add exact tool names to the shared configuration:
 
 ```ts
-intent: {
-  mode: "semantic",
-  allowedIntent: "intent_question",
-  semantic: {
-    threshold: 0.7,
-    intents: {
-      intent_question: "Description of allowed intent"
-    }
+tools: {
+  defaultAction: "block",
+  rules: {
+    searchDocs: "allow",
+    summarizeTicket: "redact",
+    deleteTicket: "approval-required"
+  },
+  approve: async ({ toolName, input, context }) => {
+    // Connect a trusted approval service for this exact call and user.
+    // This example denies every approval request.
+    return false;
+tools: {
+  defaultAction: "block",
+  rules: {
+    searchDocs: "allow",
+    summarizeTicket: "redact",
+    deleteTicket: "approval-required"
+  },
+  approve: async ({ toolName, input, context }) => {
+    // Connect a trusted approval service for this exact call and user.
+    // This example denies every approval request.
+    return false;
   }
 }
 ```
 
-### **PII Guard**
+| Policy | Behavior |
+| --- | --- |
+| `allow` | Restore tokens, scan input, then execute |
+| `block` | Stop before execution |
+| `redact` | Replace detected PII in nested string arguments with `[REDACTED]`, then execute |
+| `approval-required` | Execute only when the application's callback returns literal `true` |
 
-```ts
-pii: {
-  reversible: true,
-  mode: "classifier"
-}
-```
-
-`classifier` mode uses `openai/privacy-filter` as a token-classification model with aggregated
-spans. Model-detected names, addresses, emails, phone numbers, URLs, dates, account numbers and
-secrets are converted into reversible masking tokens. Regex rules continue to run as an additional
-layer, and duplicate spans are masked only once.
-
-During multi-turn tool execution, opaque tokens returned through a different Genkit middleware
-context are rehydrated from the configured vault before tool execution and before the final
-response is returned to the application.
-
-Preload the same mode during application startup:
-
-```ts
-await initGuard({ pii: { mode: "classifier" } });
-```
-
-### **PII Vault Isolation and External Storage**
-
-By default, PII is stored in an in-memory vault scoped to a single tokenizer instance. Tokens include a generated vault scope:
-
-```txt
-"Email john.doe@example.com" -> "Email [[EMAIL_<namespace>_0]]"
+Blocked, pending, or denied calls throw `GuardToolError`. Approval UI and durable approval storage belong to the application. Redaction may invalidate a tool's input schema, such as an email field; choose a policy appropriate to the tool.
+
+Without tool policies, the default remains allow. With `tools` configured, `guard()` returns a native Genkit middleware reference. Existing configurations without `tools` retain the legacy callable form. Use `guardMiddleware(config)` for native tool hooks without explicit policies.
+
+See [tool controls and logging](https://github.com/IntFlows/genkit-guard/wiki/9.-Tool-Controls-and-Logging) for the complete behavior.
+
+## Models and PII storage
+
+| Setting | Default |
+| --- | --- |
+| Intent model | `Xenova/all-MiniLM-L6-v2` |
+| PII mode | `ner` |
+| NER model | `Xenova/bert-base-NER` |
+| Classifier model | `openai/privacy-filter` when classifier mode is selected |
+| PII vault | In-memory storage |
+
+The quick start explicitly selects classifier mode. Regex detection also runs for email, Australian phone and identifier patterns, and credit-card-like numbers.
+
+Use `models.extractor` and `pii.model` to select compatible models, and `pii.labelMappings` to map fine-tuned labels to masking types. Classifier mode currently loads `q4` weights. Redis and custom vault adapters support external storage.
+
+- [Shared model configuration](https://github.com/IntFlows/genkit-guard/wiki/8.-Shared-Model-Configuration)
+- [PII labels, masking and vaults](https://github.com/IntFlows/genkit-guard/wiki/5.-PII-Guard)
+
+## PII Vault Isolation and External Storage
+
+Masked values are kept in a vault so they can be restored later. By default, the middleware uses process-local in-memory storage with generated vault scopes. Each tokenizer also generates an opaque namespace for its placeholders:
+| Policy | Behavior |
+| --- | --- |
+| `allow` | Restore tokens, scan input, then execute |
+| `block` | Stop before execution |
+| `redact` | Replace detected PII in nested string arguments with `[REDACTED]`, then execute |
+| `approval-required` | Execute only when the application's callback returns literal `true` |
+
+Blocked, pending, or denied calls throw `GuardToolError`. Approval UI and durable approval storage belong to the application. Redaction may invalidate a tool's input schema, such as an email field; choose a policy appropriate to the tool.
+
+Without tool policies, the default remains allow. With `tools` configured, `guard()` returns a native Genkit middleware reference. Existing configurations without `tools` retain the legacy callable form. Use `guardMiddleware(config)` for native tool hooks without explicit policies.
+
+See [tool controls and logging](https://github.com/IntFlows/genkit-guard/wiki/9.-Tool-Controls-and-Logging) for the complete behavior.
+
+## Models and PII storage
+
+| Setting | Default |
+| --- | --- |
+| Intent model | `Xenova/all-MiniLM-L6-v2` |
+| PII mode | `ner` |
+| NER model | `Xenova/bert-base-NER` |
+| Classifier model | `openai/privacy-filter` when classifier mode is selected |
+| PII vault | In-memory storage |
+
+The quick start explicitly selects classifier mode. Regex detection also runs for email, Australian phone and identifier patterns, and credit-card-like numbers.
+
+Use `models.extractor` and `pii.model` to select compatible models, and `pii.labelMappings` to map fine-tuned labels to masking types. Classifier mode currently loads `q4` weights. Redis and custom vault adapters support external storage.
+
+- [Shared model configuration](https://github.com/IntFlows/genkit-guard/wiki/8.-Shared-Model-Configuration)
+- [PII labels, masking and vaults](https://github.com/IntFlows/genkit-guard/wiki/5.-PII-Guard)
+
+## PII Vault Isolation and External Storage
+
+Masked values are kept in a vault so they can be restored later. By default, the middleware uses process-local in-memory storage with generated vault scopes. Each tokenizer also generates an opaque namespace for its placeholders:
+
+```text
+alice@example.com -> [[EMAIL_<namespace>_0]]
+```text
+alice@example.com -> [[EMAIL_<namespace>_0]]
 ```
 
-That generated namespace prevents two concurrent calls from sharing the same visible placeholder names. Vault lookups are isolated by the configured storage scope, so User A and User B can safely produce their own email tokens without cross-resolving each other's PII.
+Namespaces prevent concurrent calls from creating identical placeholder names. Use `pii.vault.scopeId` to group vault entries by request, session, or another application scope. The scope ID is not exposed in the placeholder.
+
+### Redis storage
+
+Use Redis when vault entries need to survive application restarts or be available to multiple workers. Install the client separately:
+
+```bash
+npm install redis
+```
 
-For applications that need persistence, distributed workers, audits, or tenant-specific storage, provide a vault storage backend. Redis clients can be passed through the built-in helper:
-For applications that need persistence, distributed workers, audits, or tenant-specific storage, provide a vault storage backend. Redis clients can be passed through the built-in helper:
+Extend your shared configuration during application startup:
+Namespaces prevent concurrent calls from creating identical placeholder names. Use `pii.vault.scopeId` to group vault entries by request, session, or another application scope. The scope ID is not exposed in the placeholder.
+
+### Redis storage
+
+Use Redis when vault entries need to survive application restarts or be available to multiple workers. Install the client separately:
+
+```bash
+npm install redis
+```
+
+Extend your shared configuration during application startup:
 
 ```ts
 import { createClient } from "redis";
-import { guard, createRedisPiiVaultStorage } from "@intflows/genkit-guard";
-
-const redis = createClient({ url: "redis://localhost:6379" });
+import { guard, initGuard, createRedisPiiVaultStorage } from "@intflows/genkit-guard";
+import guardConfig from "./guard.config.js";
+import { guard, initGuard, createRedisPiiVaultStorage } from "@intflows/genkit-guard";
+import guardConfig from "./guard.config.js";
+
+const redis = createClient({ url: process.env.REDIS_URL ?? "redis://localhost:6379" });
+redis.on("error", () => console.error("PII vault Redis connection error"));
+const redis = createClient({ url: process.env.REDIS_URL ?? "redis://localhost:6379" });
+redis.on("error", () => console.error("PII vault Redis connection error"));
 await redis.connect();
 
-guard({
+const config = {
+  ...guardConfig,
+const config = {
+  ...guardConfig,
   pii: {
-    reversible: true,
+    ...guardConfig.pii,
+    ...guardConfig.pii,
     vault: {
       storage: createRedisPiiVaultStorage(redis, {
         keyPrefix: "my-app:pii",
         ttlSeconds: 3600,
-        fallbackToMemory: true
+        fallbackToMemory: false
       }),
-      scopeId: (req, ctx) => ctx?.auth?.sessionId ?? req?.metadata?.requestId
+      // Populate this from trusted application context.
+      // If absent, the middleware generates a new scope.
+      scopeId: (_req: unknown, ctx: any) => ctx?.context?.piiScopeId
     }
   }
+};
+
+await initGuard(config);
+// Use guard(config) in your ai.generate({ use: [...] }) calls.
+const middleware = guard(config);
+```
+
+`ttlSeconds` expires the scoped vault and shared token-index keys; writes refresh their expiry, so it is not a per-entry retention deadline. Without a TTL, Redis entries remain until removed externally. The default in-memory vault has no automatic expiry.
+
+`fallbackToMemory: true` enables a process-local mirror with the same TTL behavior when Redis operations fail. It is disabled by default, so Redis errors propagate. The mirror is not shared across workers, does not survive restarts, and is not automatically replayed into Redis after recovery.
+
+### Custom storage and isolation boundaries
+
+Use `createPiiVaultStorage({ get, set, entries, getByToken })` to connect another database or store. `getByToken` is optional and enables recovery of opaque tokens across model/tool turns.
+
+Scoped reads and writes use `scopeId`, but cross-turn recovery can look up tokens across scopes within the same backend. Scope IDs and opaque namespaces are not tenant authorization controls. For separate tenants, use appropriately isolated storage adapters or Redis prefixes, including separate token indexes, and enforce access in your application. Vault entries contain original PII values; the adapter does not encrypt those values itself.
+
+See the [PII vault documentation](https://github.com/IntFlows/genkit-guard/wiki/5.-PII-Guard) and [Redis integration example](./example/src/index.ts).
+
+## Decision logging
+
+Console logging emits structured JSON. In v0.1.0, attach a persistent store to your shared configuration:
+
+```ts
+import { defineGuardConfig, createJsonlDecisionStore } from "@intflows/genkit-guard";
+
+const decisionStore = createJsonlDecisionStore("./logs/guard-decisions.jsonl");
+const config = defineGuardConfig({
+  // Include your intent, PII and tool policies here.
+  policyVersion: "support-v2",
+  logging: {
+    enabled: false, // Disable console output; persistence still runs.
+    store: decisionStore
+  }
 });
 ```
 
-`ttlSeconds` applies the configured expiry to both the scoped vault and token index. When
-`fallbackToMemory` is enabled, successful writes are also mirrored in process memory and Redis
-operation failures fall back to that mirror. The fallback is disabled by default, is local to one
-process, and is not a replacement for Redis persistence or multi-worker availability. Its in-memory
-entries observe the same TTL. Redis errors continue to propagate when fallback is disabled.
+Pass `config` to `initGuard()` and `guard()`. Each append is validated, serialized and flushed before it resolves. Use `await decisionStore.read()` to load the records, including after restarting the application. Unknown fields are stripped before writing.
 
-For another backend, use `createPiiVaultStorage({ get, set, entries, getByToken })` with your database, cache, or secret store.
+Events include schema version, decision ID, timestamp, guard, policy version, action, reason code, latency, and intent similarity where applicable. They exclude raw prompts, arguments, classifier output and error messages. Use non-sensitive policy identifiers.
 
-Choose a `scopeId` that matches your isolation boundary, such as request ID, session ID, tenant/user ID, or a combination like `tenantId:userId:requestId`. A shared external backend should never ignore `scopeId`, because placeholders are only safe when resolved against the correct vault scope. The placeholder sent to the model uses an opaque generated namespace rather than exposing your `scopeId`.
+`logging.onDecision` remains available. Store writes happen first, then the callback; both are awaited regardless of console settings. Failure stops the current operation. There are no automatic delivery retries, and a successful write is not rolled back if the callback later fails. Decisions describe checks, not confirmation of downstream execution.
 
-### Screenshots
-![Redis Stored PII ](redis-scan.png)
+The JSONL helper supports concurrent callers in one process, including separate instances using the same resolved path. Use separate files per worker or a shared backend through `createGuardDecisionStore({ append })` for multiple processes. File rotation, retention, encryption and crash recovery are application responsibilities; incomplete log tails cause reads and further appends to fail rather than silently discarding records. `read()` loads the full file into memory.
 
----
+## Fallback guard models
 
-## 🛡️ Why This Library Exists
+Fallbacks are optional and apply to local intent and PII models, not your application's generative model:
 
-Genkit provides a powerful LLM framework, but production systems need:
+```ts
+models: {
+  extractor: "Xenova/all-MiniLM-L6-v2",
+  extractorFallback: "your-org/compatible-embedding-model"
+},
+pii: {
+  mode: "classifier",
+  model: "openai/privacy-filter",
+  fallback: {
+    model: "Xenova/bert-base-NER",
+    mode: "ner",
+    labelMappings: { PER: "NAME" }
+  }
+}
+```
 
-- intent boundaries  
-- PII protection  
-- jailbreak resistance  
-- predictable behavior  
+Replace the custom embedding identifier with a model you have prepared. A fallback runs once when the primary model fails to load or execute. An intent rejection or empty PII result does not trigger fallback. The primary is tried again on the next operation; there is no timeout, circuit breaker or automatic switch for future requests.
 
-This library adds those guardrails without heavy dependencies or complex setup.
+PII fallback mode defaults to the primary mode. Its label mappings are independent of the primary mappings. Both models must support the relevant Transformers.js task; classifier mode requires compatible `q4` weights. NER and privacy-filter have different detection coverage, so evaluate the fallback on your own inputs before enabling it.
 
----
+Successful recovery emits `MODEL_FALLBACK_USED`; normal guard checks still determine whether the request proceeds. If both models fail, `GuardModelError` with code `MODEL_UNAVAILABLE` stops the operation. There is no regex-only bypass. The same policy applies during `initGuard()`, model-request checks and tool PII scans. A failure after a tool has executed cannot undo that execution.
 
-## Contributing
+Without fallback configuration, existing model selection and error propagation remain unchanged. See [persistent decisions and fallback models](https://github.com/IntFlows/genkit-guard/wiki/10.-Decision-Storage-and-Model-Fallback) for the full contract.
+
+## Try it and explore the examples
 
-We plan to: 
+[Open the Hugging Face Space](https://huggingface.co/spaces/intflows/genkit-guard) to explore the demo. Use synthetic inputs when trying a hosted demo.
 
-1. Extend the utility by adding Auth and Tool Middleware in further stages.
-2. Add more filter types for common malicious prompts.
-3. Add more patterns for custom PII masking.
+- [Integration flow](./example/src/index.ts): Azure Blob workflow with Redis-backed PII storage.
+- [Tool controls](./example/src/tool-controls.ts): optional standalone demo of redaction and approval-required policies. This file is not required to use the package.
+
+The tool-controls demo uses the local build. Run `npm install` and `npm run build` in the repository root, then `npm install` in `example`. Set `GEMINI_API_KEY` and `GEMINI_MODEL` for your provider account, and run:
+
+```bash
+# From example/
+npx tsx src/tool-controls.ts
+```
+
+## Roadmap
+
+- **v0.0.14:** shared model configuration, custom PII labels, tool policies and versioned decision events.
+- **v0.1.0 (in development):** persistent decision logging and explicit fallback-model behavior.
+- **Later:** SQLite vault, memory compaction integration, compatibility hardening and stable v1.
+
+## Contributing
 
-Contributions are welcome — whether it’s bug reports, new guard modules, model improvements or enhancements. This project aims to stay lightweight, modular, and production‑ready, so thoughtful contributions are appreciated.
+Issues, pull requests, model evaluations and security reviews are welcome. Run `npm test` for the deterministic suite; real Redis integration is tested separately with `npm run test:redis`.
+Issues, pull requests, model evaluations and security reviews are welcome. Run `npm test` for the deterministic suite; real Redis integration is tested separately with `npm run test:redis`.
 
-# 📄 License
+## License
+## License
 
-Apache‑2.0
+[Apache-2.0](./LICENSE)
+[Apache-2.0](./LICENSE)

package/dist/core/audit.d.ts

@@ -0,0 +1,5 @@
+import type { GuardConfig } from '../middleware/middleware.js';
+import type { GuardDecision } from './decision.js';
+export declare function publishDecision(config: GuardConfig | undefined, start: number, fields: Pick<GuardDecision, 'guard' | 'action' | 'reasonCode'> & {
+    confidence?: number;
+}): Promise<GuardDecision>;