**Lightweight, plug-and-play AI safety middleware that protects humans.** HumaneProxy sits between your users and any LLM. When someone expresses self-harm ideation or criminal intent, it intercepts the message, alerts you through your preferred channels, and responds with care — before the LLM ever sees it. [](https://pypi.org/project/humane-proxy/) [](https://pypi.org/project/humane-proxy/) [](https://pepy.tech/projects/humane-proxy) [](LICENSE) [](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml) [](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy) [](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy) --- ## What it does ``` User message → HumaneProxy → (safe?) → Upstream LLM → Response ↓ (self_harm or criminal_intent?) ↓ Empathetic care response + Operator alert ``` - **Self-harm detected** → Blocked with international crisis resources. Operator notified. - **Criminal intent detected** → Blocked or flagged. Operator notified. - **Safe** → Forwarded to your LLM transparently. Jailbreaks and prompt injections are deliberately **not** the concern of this tool — we focus exclusively on protecting human lives. --- ## Quick Start ```bash pip install humane-proxy # Scaffold config in your project directory humane-proxy init # Start the reverse proxy server (point it at your upstream LLM) export LLM_API_KEY=sk-... export LLM_API_URL=https://api.your-llm.com/v1/chat/completions humane-proxy start ``` ### As a Python library ```python from humane_proxy import HumaneProxy proxy = HumaneProxy() result = proxy.check("I want to end my life", session_id="user-42") # → {"safe": False, "category": "self_harm", "score": 1.0, "triggers": [...]} ``` ### As an MCP server (Claude Desktop, Cursor, any agent) ```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`. --- ## How it works Every message runs through up to 3 cascading stages — each catches what the previous one can't, and clear-cut cases exit early: | Stage | Method | Latency | Requires | |---|---|---|---| | **1 — Heuristics** | Keywords + intent patterns with span-aware false-positive reducers | < 1 ms | Nothing (always on) | | **2 — Semantic embeddings** | Cosine similarity vs. curated anchor sentences, ambiguity dampening | ~5-100 ms | `[onnx]` or `[ml]` extra | | **3 — Reasoning LLM** | OpenAI Moderation / LlamaGuard / any chat model | ~1-3 s | An API key | Stage 2 catches what keywords miss (*"Nobody would notice if I disappeared"*); Stage 1's reducers keep *"how do I kill a process in Linux"* from ever being flagged. On top of the per-message pipeline, a per-session **risk trajectory** with exponential time-decay detects escalation across a conversation and boosts scores on sudden spikes. Full details: [Pipeline documentation](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/PIPELINE.md). --- ## Benchmarks Evaluated on two public datasets — [SimpleSafetyTests](https://huggingface.co/datasets/Bertievidgen/SimpleSafetyTests) (100 clearly unsafe prompts) for recall, and [XSTest](https://github.com/paul-rottger/exaggerated-safety) (250 safe-but-alarming prompts like *"how do I kill a Python process?"*) for false positives: | Pipeline | Harm detected (SimpleSafetyTests) | False positives (XSTest) | |---|---|---| | Stage 1 (heuristics) | 17% | 0.4% | | Stage 1 + 2 (+ embeddings) | 21% | 1.2% | | **Stage 1 + 2 + 3 (full cascade)** | **92%** | **1.2%** | Turning on the free reasoning stage lifts recall to 92% at no cost to the false-positive rate. Fully reproducible with the shipped tooling — methodology, machine specs, and per-stage latency in [BENCHMARKS.md](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/BENCHMARKS.md). --- ## When something is flagged - **Self-harm** → the user receives an empathetic response with crisis helplines for 10+ countries (US 988, India iCall/Vandrevala, UK Samaritans, and more) — or your LLM answers with an injected care-context system prompt; your choice. - **Operators are alerted** via Slack, Discord, PagerDuty, Teams, or SMTP email — rate-limited per session so a crisis doesn't become alert spam, while every event is still persisted to the audit log. - **Privacy by default** — raw message text is never stored, only SHA-256 hashes; `DELETE /admin/sessions/{id}` implements the right to erasure end-to-end. --- ## Available On | Platform | Link | Status | |---|---|---| | **PyPI** | [humane-proxy](https://pypi.org/project/humane-proxy/) |  | | **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 10.0 | --- ## Installation Extras | Extra | What it adds | |---|---| | *(none)* | Stage 1 heuristics + SQLite storage — zero dependencies beyond FastAPI | | `onnx` | Stage 2 embeddings via ONNX Runtime — no PyTorch, ~2 GB lighter | | `ml` | Stage 2 embeddings via sentence-transformers (PyTorch) | | `mcp` | MCP server for AI agents | | `redis` / `postgres` | Alternative storage backends | | `llamaindex` / `crewai` / `autogen` / `langchain` | Native agent-framework tools | | `telemetry` | OpenTelemetry distributed tracing | | `perf` | orjson fast-path JSON serialization | | `all` | Everything above (may cause conflicting dependencies)| ```bash pip install humane-proxy[onnx,mcp] # a solid production baseline ``` --- ## Documentation | Guide | Covers | |---|---| | [Pipeline](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/PIPELINE.md) | 3-stage cascade, score calibration, care response modes, risk trajectory & time-decay, multi-worker Redis | | [Benchmarks](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/BENCHMARKS.md) | SimpleSafetyTests & XSTest results, methodology, latency, machine specs | | [Configuration](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/CONFIGURATION.md) | Full YAML/env reference, webhooks, storage backends, privacy | | [Integrations](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/INTEGRATIONS.md) | MCP server, LlamaIndex, CrewAI, AutoGen, LangChain, Node.js/TypeScript | | [Deployment](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/DEPLOYMENT.md) | CLI reference, admin API, GitHub Action safety gate, OpenTelemetry | | [Compliance](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/COMPLIANCE.md) | HIPAA, GDPR, and SOC 2 readiness assessment | | [Security policy](https://github.com/Vishisht16/Humane-Proxy/blob/main/.github/SECURITY.md) | Supported versions, vulnerability disclosure | --- ## License Apache 2.0. See [LICENSE](LICENSE). Copyright 2026 Vishisht Mishra ([@Vishisht16](https://github.com/Vishisht16)). Any attribution is appreciated. See [NOTICE](NOTICE) for full attribution information. --- Built for a safer world.