safestar 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safestar",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Snapshot, version, and diff AI behavior over time.",
   "main": "dist/index.js",
   "bin": {

package/readme.md

@@ -0,0 +1,165 @@
+<p align="center">
+  <h1 align="center">SafeStar</h1>
+  <p align="center"><strong>The "Git" for AI Behavior.</strong></p>
+  <p align="center">Snapshot, version, and diff AI model outputs. Detect drift before your users do.</p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/safestar"><img src="https://img.shields.io/npm/v/safestar.svg" alt="npm version"></a>
+  <a href="https://github.com/your-username/safestar/actions"><img src="https://github.com/your-username/safestar/workflows/AI%20Guardrails/badge.svg" alt="Build Status"></a>
+  <a href="https://opensource.org/licenses/ISC"><img src="https://img.shields.io/badge/License-ISC-blue.svg" alt="License: ISC"></a>
+</p>
+
+---
+
+## Why SafeStar?
+<img src="https://github.com/user-attachments/assets/62a87419-ddaa-4fc0-bb50-90e2c5bf2dfd">
+
+
+You updated a prompt. Tests pass. You deploy. Three days later, users complain the bot is "acting weird."
+
+**The problem:** Traditional tests don't catch AI behavior drift—subtle changes in tone, verbosity, or consistency that emerge over time or after model updates.
+
+**SafeStar fixes this** by treating AI outputs like code:
+- 📸 **Snapshot** a known-good baseline
+- 🔍 **Diff** against it in CI/CD
+- 🚨 **Fail the build** if behavior drifts beyond tolerance
+
+No SaaS. No external dependencies. Works with any CLI command.
+<img src="https://github.com/user-attachments/assets/f3a14fec-93f6-42c3-b8e2-35af6b701b5f">
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev safestar
+```
+
+---
+
+## Quick Start
+
+### 1. Define a Scenario
+
+Create `scenarios/refund.yaml`:
+
+```yaml
+name: refund_bot_test
+description: Ensure the refund bot doesn't hallucinate or get rude.
+
+prompt: "I want a refund immediately."
+
+# Run your AI however you want—Python, Node, curl, anything
+exec: "python3 scripts/my_agent.py"
+
+# Test multiple times to catch variance
+runs: 5
+
+# Heuristic guardrails
+checks:
+  max_length: 200
+  must_contain:
+    - "refund"
+  must_not_contain:
+    - "I am just an AI"
+```
+
+> **Note:** SafeStar passes the prompt via `process.env.PROMPT` (or equivalent in your language).
+<img src="https://github.com/user-attachments/assets/8ccd918e-4331-4f2c-981e-c7c9535865f0">
+
+### 2. Run & Baseline
+
+Run your scenario:
+```bash
+npx safestar run scenarios/refund.yaml
+```
+
+Happy with the output? Lock it as your gold standard:
+```bash
+npx safestar baseline refund_bot_test
+```
+<img src="https://github.com/user-attachments/assets/2021ff79-e094-470e-be19-8490d8d3ae6b">
+
+### 3. Diff in CI/CD
+
+```bash
+npx safestar diff scenarios/refund.yaml
+```
+
+**Example output:**
+```
+--- SAFESTAR REPORT ---
+Status: FAIL
+
+Metrics:
+  Avg Length: 45 chars
+  Drift:      +210% vs baseline (WARNING)
+  Variance:   9.8 (High instability)
+
+Violations:
+  - must_not_contain "sorry sorry": failed in 2 runs
+```
+
+---
+<img src="https://github.com/user-attachments/assets/c2c6bbe6-0971-43d3-9845-0a5f0bdd0092">
+
+## Checks Reference
+
+| Check | Description |
+|-------|-------------|
+| `max_length` | Fail if output exceeds N characters |
+| `must_contain` | Fail if any string is missing from output |
+| `must_not_contain` | Fail if any string is found in output |
+
+---
+
+## `exec` Examples
+
+SafeStar works with anything that prints to stdout:
+
+```yaml
+# Python
+exec: "python3 bot.py"
+
+# Node.js
+exec: "node agent.js"
+
+# cURL (test an API directly)
+exec: "curl -s https://api.openai.com/v1/chat/completions -H 'Authorization: Bearer $OPENAI_KEY' -d '{\"model\":\"gpt-4\",\"messages\":[{\"role\":\"user\",\"content\":\"$PROMPT\"}]}'"
+
+# Any CLI
+exec: "./my-binary --prompt \"$PROMPT\""
+```
+
+---
+
+## GitHub Actions
+
+```yaml
+name: AI Guardrails
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npx safestar diff scenarios/refund.yaml
+```
+
+---
+
+## Philosophy
+
+- **Zero dependencies** – Runs anywhere Node runs
+- **No SaaS** – Your data stays on your machine
+- **Language agnostic** – If it prints to stdout, SafeStar can test it
+- **Git-native** – Baselines are `.json` files you commit
+
+---
+
+## License
+
+ISC