{ "markdown": "

\n \"HumaneProxy\"\n

\n\n\n\n**Lightweight, plug-and-play AI safety middleware that protects humans.**\n\nHumaneProxy 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.\n\n[![PyPI](https://img.shields.io/pypi/v/humane-proxy.svg)](https://pypi.org/project/humane-proxy/)\n[![Python](https://img.shields.io/pypi/pyversions/humane-proxy.svg)](https://pypi.org/project/humane-proxy/)\n[![Downloads](https://static.pepy.tech/badge/humane-proxy)](https://pepy.tech/projects/humane-proxy)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Tests](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml/badge.svg)](https://github.com/Vishisht16/Humane-Proxy/actions/workflows/tests.yaml)\n[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/score.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)\n[![MCP Marketplace](https://img.shields.io/badge/MCP_Marketplace-Available-brightgreen)](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy)\n\n---\n\n## What it does\n\n```\nUser message → HumaneProxy → (safe?) → Upstream LLM → Response\n ↓\n (self_harm or criminal_intent?)\n ↓\n Empathetic care response + Operator alert\n```\n\n- **Self-harm detected** → Blocked with international crisis resources. Operator notified.\n- **Criminal intent detected** → Blocked or flagged. Operator notified.\n- **Safe** → Forwarded to your LLM transparently.\n\nJailbreaks and prompt injections are deliberately **not** the concern of this tool — we focus exclusively on protecting human lives.\n\n---\n\n## Quick Start\n\n```bash\npip install humane-proxy\n\n# Scaffold config in your project directory\nhumane-proxy init\n\n# Start the reverse proxy server (point it at your upstream LLM)\nexport LLM_API_KEY=sk-...\nexport LLM_API_URL=https://api.your-llm.com/v1/chat/completions\nhumane-proxy start\n```\n\n### As a Python library\n\n```python\nfrom humane_proxy import HumaneProxy\n\nproxy = HumaneProxy()\n\nresult = proxy.check(\"I want to end my life\", session_id=\"user-42\")\n# → {\"safe\": False, \"category\": \"self_harm\", \"score\": 1.0, \"triggers\": [...]}\n```\n\n### As an MCP server (Claude Desktop, Cursor, any agent)\n\n```json\n{\n \"mcpServers\": {\n \"humane-proxy\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"humane-proxy[mcp]\", \"humane-proxy\", \"mcp-serve\"]\n }\n }\n}\n```\n\nThis exposes 3 tools to your AI agent: `check_message_safety`, `get_session_risk`, and `list_recent_escalations`.\n\n---\n\n## How it works\n\nEvery message runs through up to 3 cascading stages — each catches what the previous one can't, and clear-cut cases exit early:\n\n| Stage | Method | Latency | Requires |\n|---|---|---|---|\n| **1 — Heuristics** | Keywords + intent patterns with span-aware false-positive reducers | < 1 ms | Nothing (always on) |\n| **2 — Semantic embeddings** | Cosine similarity vs. curated anchor sentences, ambiguity dampening | ~5-100 ms | `[onnx]` or `[ml]` extra |\n| **3 — Reasoning LLM** | OpenAI Moderation / LlamaGuard / any chat model | ~1-3 s | An API key |\n\nStage 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.\n\nFull details: [Pipeline documentation](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/PIPELINE.md).\n\n---\n\n## Benchmarks\n\nEvaluated 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:\n\n| Pipeline | Harm detected (SimpleSafetyTests) | False positives (XSTest) |\n|---|---|---|\n| Stage 1 (heuristics) | 17% | 0.4% |\n| Stage 1 + 2 (+ embeddings) | 21% | 1.2% |\n| **Stage 1 + 2 + 3 (full cascade)** | **92%** | **1.2%** |\n\nTurning 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).\n\n---\n\n## When something is flagged\n\n- **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.\n- **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.\n- **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.\n\n---\n\n## Available On\n\n| Platform | Link | Status |\n|---|---|---|\n| **PyPI** | [humane-proxy](https://pypi.org/project/humane-proxy/) | ![PyPI](https://img.shields.io/pypi/v/humane-proxy.svg) |\n| **Glama MCP Registry** | [Humane-Proxy](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy) | AAA Rating |\n| **MCP Marketplace** | [humane-proxy](https://mcp-marketplace.io/server/io-github-vishisht16-humane-proxy) | Low Risk 10.0 |\n\n---\n\n## Installation Extras\n\n| Extra | What it adds |\n|---|---|\n| *(none)* | Stage 1 heuristics + SQLite storage — zero dependencies beyond FastAPI |\n| `onnx` | Stage 2 embeddings via ONNX Runtime — no PyTorch, ~2 GB lighter |\n| `ml` | Stage 2 embeddings via sentence-transformers (PyTorch) |\n| `mcp` | MCP server for AI agents |\n| `redis` / `postgres` | Alternative storage backends |\n| `llamaindex` / `crewai` / `autogen` / `langchain` | Native agent-framework tools |\n| `telemetry` | OpenTelemetry distributed tracing |\n| `perf` | orjson fast-path JSON serialization |\n| `all` | Everything above (may cause conflicting dependencies)|\n\n```bash\npip install humane-proxy[onnx,mcp] # a solid production baseline\n```\n\n---\n\n## Documentation\n\n| Guide | Covers |\n|---|---|\n| [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 |\n| [Benchmarks](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/BENCHMARKS.md) | SimpleSafetyTests & XSTest results, methodology, latency, machine specs |\n| [Configuration](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/CONFIGURATION.md) | Full YAML/env reference, webhooks, storage backends, privacy |\n| [Integrations](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/INTEGRATIONS.md) | MCP server, LlamaIndex, CrewAI, AutoGen, LangChain, Node.js/TypeScript |\n| [Deployment](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/DEPLOYMENT.md) | CLI reference, admin API, GitHub Action safety gate, OpenTelemetry |\n| [Compliance](https://github.com/Vishisht16/Humane-Proxy/blob/main/docs/COMPLIANCE.md) | HIPAA, GDPR, and SOC 2 readiness assessment |\n| [Security policy](https://github.com/Vishisht16/Humane-Proxy/blob/main/.github/SECURITY.md) | Supported versions, vulnerability disclosure |\n\n---\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n\nCopyright 2026 Vishisht Mishra ([@Vishisht16](https://github.com/Vishisht16)). Any attribution is appreciated.\n\nSee [NOTICE](NOTICE) for full attribution information.\n\n---\n\nBuilt for a safer world.\n", "bytes": 7954, "sha": "770d172392b20ab9a476c74dd14cc26def6d0348343f50bca5af85e2880029f1", "repo_slug": "vishisht16/humane-proxy", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_vishisht16_humane_proxy_a877e7a9/readme" }