humane-proxy 0.3.0__tar.gz → 0.4.0__tar.gz

{humane_proxy-0.3.0/humane_proxy.egg-info → humane_proxy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: humane-proxy
-Version: 0.3.0
+Version: 0.4.0
 Summary: Lightweight, plug-and-play AI safety middleware that protects humans.
 Author-email: Vishisht Mishra <Vishisht16@users.noreply.github.com>
 License: Apache-2.0
@@ -21,12 +21,13 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: fastapi>=0.100.0
+Requires-Dist: fastapi>=0.109.1
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: uvicorn>=0.22.0
 Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
@@ -68,7 +69,7 @@ HumaneProxy sits between your users and any LLM. When someone expresses self-har
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Tests](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml/badge.svg)](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml)
 [![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/score.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
-[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
+[![MCP Marketplace](https://img.shields.io/badge/MCP_Marketplace-Available-brightgreen)](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy)
 
 ---
 
@@ -121,6 +122,40 @@ result = await proxy.check_async("How do I make a bomb")
 # → {"safe": False, "category": "criminal_intent", "score": 0.9, ...}
 ```
 
+### As an MCP Server
+
+```bash
+pip install humane-proxy[mcp]
+
+# Start the MCP server (stdio transport — for Claude Desktop, Cursor, etc.)
+humane-proxy mcp-serve
+```
+
+Or add it directly to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "humane-proxy": {
+      "command": "uvx",
+      "args": ["--from", "humane-proxy[mcp]", "humane-proxy", "mcp-serve"]
+    }
+  }
+}
+```
+
+This exposes 3 tools to your AI agent: `check_message_safety`, `get_session_risk`, and `list_recent_escalations`.
+
+---
+
+## Available On
+
+| Platform | Link | Status |
+|---|---|---|
+| **PyPI** | [humane-proxy](https://pypi.org/project/humane-proxy/) | ![PyPI](https://img.shields.io/pypi/v/humane-proxy.svg) |
+| **Glama MCP Registry** | [Humane-Proxy](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy) | AAA Rating |
+| **MCP Marketplace** | [humane-proxy](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy) | Low Risk 9.0 |
+
 ---
 
 ## 3-Stage Cascade Pipeline
@@ -186,6 +221,8 @@ stage2:
   safe_threshold: 0.35         # cosine similarity below this → safe
 ```
 
+> **Multilingual Support:** If your users converse in non-English languages (Roman Hindi, Spanish, Arabic, etc.), change the `model` in your configuration to `"paraphrase-multilingual-MiniLM-L12-v2"`. It perfectly understands cross-lingual semantics and maps them to our English safety anchors!
+
 The model lazy-loads on first use. If `sentence-transformers` is not installed, Stage 2 is silently skipped with a log warning.
 
 > **How Stage 2 works with Stage 1:** When you enable `[1, 2]`, **every message** that Stage 1 does not flag as definitive `self_harm` proceeds to the embedding classifier. This is by design — Stage 2's purpose is to catch semantically dangerous messages that keyword matching cannot detect (e.g. *"Nobody would notice if I disappeared"*). Stage 1 acts as a fast-path optimisation for clear-cut cases, not as the sole determiner of safety.
@@ -273,6 +310,67 @@ The injected system prompt instructs the LLM to respond with empathy, validate f
 
 ---
 
+## Risk Trajectory & Time-Decay
+
+HumaneProxy tracks a **rolling window** of the last 5 risk scores per session.
+When a new message arrives, its score is compared against the
+**decay-weighted mean** of that window:
+
+```
+delta = current_score − weighted_mean(last N scores)
+spike = delta > 0.35    (configurable via spike_delta)
+```
+
+If a spike is detected, a **boost penalty** (`+0.25`) is added to the
+current score to push it closer to escalation.
+
+### Exponential Time-Decay
+
+Historical scores are weighted using the formula:
+
+$$w_i = e^{-\lambda \, \Delta t_i}$$
+
+where **λ = ln(2) / half-life** and **Δt** is the age of each score in
+seconds.  This means:
+
+| Time elapsed | Weight (24 h half-life) | Meaning |
+|---|---|---|
+| 5 minutes | 99.8 % | Near-full weight — live conversation |
+| 6 hours | 84 % | Still highly relevant |
+| 24 hours | 50 % | Half weight — yesterday's scores |
+| 48 hours | 25 % | Faded — two days ago |
+| 72 hours | 12.5 % | Nearly forgotten |
+
+**Why this matters:** Without decay, a user who had a tough conversation
+on Monday would carry that elevated baseline into Thursday—unfairly
+triggering spikes on innocuous messages.  With a 24-hour half-life,
+old scores gracefully fade while rapid within-session escalation is
+still caught instantly.
+
+### Configuration
+
+```yaml
+trajectory:
+  window_size: 5          # messages in rolling window
+  spike_delta: 0.35       # delta threshold for spike detection
+
+  # Half-life in hours.  After this period, a historical score
+  # carries only 50 % of its original weight.
+  #   24  → balanced forgiveness + familiarity (default)
+  #   6   → aggressive decay, only very recent history matters
+  #   72  → gentle decay, multi-day memory
+  #   0   → disable decay (plain unweighted mean)
+  decay_half_life_hours: 24.0
+```
+
+Or via environment variable:
+
+```bash
+export HUMANE_PROXY_DECAY_HALF_LIFE=12   # 12-hour half-life
+```
+
+---
+
 ## Alert Webhooks
 
 Configure in `humane_proxy.yaml`:
@@ -309,29 +407,62 @@ storage:
 
 ## CLI Reference
 
+All commands are available via both `humane-proxy` and the shorthand `hp`.
+
 ```bash
 # Safety check
-humane-proxy check "I want to end my life"
+hp check "I want to end my life"
 # 🆘 FLAGGED — self_harm
 # Score   : 1.0
 # Category: self_harm
 
+# Run benchmark evaluation
+hp benchmark --dataset evals/sample.json
+hp benchmark --dataset evals/sample.json --ci  # exit code 1 on failure
+
 # List recent escalations
-humane-proxy escalations
-humane-proxy escalations --category self_harm --limit 50
+hp escalations
+hp escalations --category self_harm --limit 50
 
 # Session risk history
-humane-proxy session user-42
+hp session user-42
 
 # Start proxy server
-humane-proxy start [--host 0.0.0.0] [--port 8000]
+hp start [--host 0.0.0.0] [--port 8000]
 
 # MCP server (requires [mcp] extra)
-humane-proxy mcp-serve
+hp mcp-serve
 ```
 
 ---
 
+## GitHub Action — CI/CD Safety Gate
+
+Use HumaneProxy as a GitHub Action to enforce safety coverage in your CI pipeline. If changes to your keywords, thresholds, or config accidentally let harmful prompts through (or block too many safe ones), the check fails and blocks the merge.
+
+```yaml
+# .github/workflows/safety-benchmark.yml
+name: Safety Benchmark
+on: [push, pull_request]
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Vishisht16/Humane-Proxy@v0.4.0
+        with:
+          dataset: evals/sample.json
+```
+
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `dataset` | ✅ | — | Path to JSON evaluation dataset |
+| `python-version` | ❌ | `3.12` | Python version to use |
+| `extra` | ❌ | `""` | pip extras (e.g., `ml` for Stage 2 embeddings) |
+
+---
+
 ## REST Admin API
 
 Mounted at `/admin`, secured with `HUMANE_PROXY_ADMIN_KEY` Bearer token:
@@ -493,6 +624,15 @@ privacy:
 
 ---
 
+## Compliance & Security
+
+HumaneProxy is designed for deployment in regulated environments. See our compliance documentation for details:
+
+- **[COMPLIANCE.md](COMPLIANCE.md)** — HIPAA, GDPR, and SOC 2 readiness assessment
+- **[SECURITY.md](.github/SECURITY.md)** — Vulnerability disclosure policy
+
+---
+
 ## License
 
 Apache 2.0. See [LICENSE](LICENSE).

{humane_proxy-0.3.0 → humane_proxy-0.4.0}/README.md

@@ -11,7 +11,7 @@ HumaneProxy sits between your users and any LLM. When someone expresses self-har
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Tests](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml/badge.svg)](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml)
 [![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/score.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
-[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
+[![MCP Marketplace](https://img.shields.io/badge/MCP_Marketplace-Available-brightgreen)](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy)
 
 ---
 
@@ -64,6 +64,40 @@ result = await proxy.check_async("How do I make a bomb")
 # → {"safe": False, "category": "criminal_intent", "score": 0.9, ...}
 ```
 
+### As an MCP Server
+
+```bash
+pip install humane-proxy[mcp]
+
+# Start the MCP server (stdio transport — for Claude Desktop, Cursor, etc.)
+humane-proxy mcp-serve
+```
+
+Or add it directly to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "humane-proxy": {
+      "command": "uvx",
+      "args": ["--from", "humane-proxy[mcp]", "humane-proxy", "mcp-serve"]
+    }
+  }
+}
+```
+
+This exposes 3 tools to your AI agent: `check_message_safety`, `get_session_risk`, and `list_recent_escalations`.
+
+---
+
+## Available On
+
+| Platform | Link | Status |
+|---|---|---|
+| **PyPI** | [humane-proxy](https://pypi.org/project/humane-proxy/) | ![PyPI](https://img.shields.io/pypi/v/humane-proxy.svg) |
+| **Glama MCP Registry** | [Humane-Proxy](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy) | AAA Rating |
+| **MCP Marketplace** | [humane-proxy](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy) | Low Risk 9.0 |
+
 ---
 
 ## 3-Stage Cascade Pipeline
@@ -129,6 +163,8 @@ stage2:
   safe_threshold: 0.35         # cosine similarity below this → safe
 ```
 
+> **Multilingual Support:** If your users converse in non-English languages (Roman Hindi, Spanish, Arabic, etc.), change the `model` in your configuration to `"paraphrase-multilingual-MiniLM-L12-v2"`. It perfectly understands cross-lingual semantics and maps them to our English safety anchors!
+
 The model lazy-loads on first use. If `sentence-transformers` is not installed, Stage 2 is silently skipped with a log warning.
 
 > **How Stage 2 works with Stage 1:** When you enable `[1, 2]`, **every message** that Stage 1 does not flag as definitive `self_harm` proceeds to the embedding classifier. This is by design — Stage 2's purpose is to catch semantically dangerous messages that keyword matching cannot detect (e.g. *"Nobody would notice if I disappeared"*). Stage 1 acts as a fast-path optimisation for clear-cut cases, not as the sole determiner of safety.
@@ -216,6 +252,67 @@ The injected system prompt instructs the LLM to respond with empathy, validate f
 
 ---
 
+## Risk Trajectory & Time-Decay
+
+HumaneProxy tracks a **rolling window** of the last 5 risk scores per session.
+When a new message arrives, its score is compared against the
+**decay-weighted mean** of that window:
+
+```
+delta = current_score − weighted_mean(last N scores)
+spike = delta > 0.35    (configurable via spike_delta)
+```
+
+If a spike is detected, a **boost penalty** (`+0.25`) is added to the
+current score to push it closer to escalation.
+
+### Exponential Time-Decay
+
+Historical scores are weighted using the formula:
+
+$$w_i = e^{-\lambda \, \Delta t_i}$$
+
+where **λ = ln(2) / half-life** and **Δt** is the age of each score in
+seconds.  This means:
+
+| Time elapsed | Weight (24 h half-life) | Meaning |
+|---|---|---|
+| 5 minutes | 99.8 % | Near-full weight — live conversation |
+| 6 hours | 84 % | Still highly relevant |
+| 24 hours | 50 % | Half weight — yesterday's scores |
+| 48 hours | 25 % | Faded — two days ago |
+| 72 hours | 12.5 % | Nearly forgotten |
+
+**Why this matters:** Without decay, a user who had a tough conversation
+on Monday would carry that elevated baseline into Thursday—unfairly
+triggering spikes on innocuous messages.  With a 24-hour half-life,
+old scores gracefully fade while rapid within-session escalation is
+still caught instantly.
+
+### Configuration
+
+```yaml
+trajectory:
+  window_size: 5          # messages in rolling window
+  spike_delta: 0.35       # delta threshold for spike detection
+
+  # Half-life in hours.  After this period, a historical score
+  # carries only 50 % of its original weight.
+  #   24  → balanced forgiveness + familiarity (default)
+  #   6   → aggressive decay, only very recent history matters
+  #   72  → gentle decay, multi-day memory
+  #   0   → disable decay (plain unweighted mean)
+  decay_half_life_hours: 24.0
+```
+
+Or via environment variable:
+
+```bash
+export HUMANE_PROXY_DECAY_HALF_LIFE=12   # 12-hour half-life
+```
+
+---
+
 ## Alert Webhooks
 
 Configure in `humane_proxy.yaml`:
@@ -252,29 +349,62 @@ storage:
 
 ## CLI Reference
 
+All commands are available via both `humane-proxy` and the shorthand `hp`.
+
 ```bash
 # Safety check
-humane-proxy check "I want to end my life"
+hp check "I want to end my life"
 # 🆘 FLAGGED — self_harm
 # Score   : 1.0
 # Category: self_harm
 
+# Run benchmark evaluation
+hp benchmark --dataset evals/sample.json
+hp benchmark --dataset evals/sample.json --ci  # exit code 1 on failure
+
 # List recent escalations
-humane-proxy escalations
-humane-proxy escalations --category self_harm --limit 50
+hp escalations
+hp escalations --category self_harm --limit 50
 
 # Session risk history
-humane-proxy session user-42
+hp session user-42
 
 # Start proxy server
-humane-proxy start [--host 0.0.0.0] [--port 8000]
+hp start [--host 0.0.0.0] [--port 8000]
 
 # MCP server (requires [mcp] extra)
-humane-proxy mcp-serve
+hp mcp-serve
 ```
 
 ---
 
+## GitHub Action — CI/CD Safety Gate
+
+Use HumaneProxy as a GitHub Action to enforce safety coverage in your CI pipeline. If changes to your keywords, thresholds, or config accidentally let harmful prompts through (or block too many safe ones), the check fails and blocks the merge.
+
+```yaml
+# .github/workflows/safety-benchmark.yml
+name: Safety Benchmark
+on: [push, pull_request]
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Vishisht16/Humane-Proxy@v0.4.0
+        with:
+          dataset: evals/sample.json
+```
+
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `dataset` | ✅ | — | Path to JSON evaluation dataset |
+| `python-version` | ❌ | `3.12` | Python version to use |
+| `extra` | ❌ | `""` | pip extras (e.g., `ml` for Stage 2 embeddings) |
+
+---
+
 ## REST Admin API
 
 Mounted at `/admin`, secured with `HUMANE_PROXY_ADMIN_KEY` Bearer token:
@@ -436,6 +566,15 @@ privacy:
 
 ---
 
+## Compliance & Security
+
+HumaneProxy is designed for deployment in regulated environments. See our compliance documentation for details:
+
+- **[COMPLIANCE.md](COMPLIANCE.md)** — HIPAA, GDPR, and SOC 2 readiness assessment
+- **[SECURITY.md](.github/SECURITY.md)** — Vulnerability disclosure policy
+
+---
+
 ## License
 
 Apache 2.0. See [LICENSE](LICENSE).

{humane_proxy-0.3.0 → humane_proxy-0.4.0}/humane_proxy/__init__.py

@@ -16,7 +16,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 # ---------------------------------------------------------------------------
 # Legacy API — keep backward compatibility with existing modules that call