Metadata-Version: 2.4
Name: humane-proxy
Version: 0.6.0
Summary: Lightweight, plug-and-play AI safety middleware that protects humans.
Author-email: Vishisht Mishra <mishra@vishisht.tech>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Vishisht16/Humane-Proxy
Project-URL: Repository, https://github.com/Vishisht16/Humane-Proxy
Project-URL: Issues, https://github.com/Vishisht16/Humane-Proxy/issues
Keywords: ai-safety,llm,middleware,guardrails,human-safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
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"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: humane-proxy[perf]; extra == "dev"
Provides-Extra: ml
Requires-Dist: sentence-transformers>=2.2.0; extra == "ml"
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.17; extra == "onnx"
Requires-Dist: tokenizers>=0.15; extra == "onnx"
Requires-Dist: huggingface_hub>=0.20; extra == "onnx"
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.11; extra == "mcp"
Provides-Extra: langchain
Requires-Dist: humane-proxy[mcp]; extra == "langchain"
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == "langchain"
Provides-Extra: webhooks
Requires-Dist: httpx>=0.24.0; extra == "webhooks"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Requires-Dist: psycopg_pool>=3.1; extra == "postgres"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
Provides-Extra: crewai
Requires-Dist: crewai[tools]>=0.80; extra == "crewai"
Provides-Extra: autogen
Requires-Dist: autogen-agentchat>=0.4; extra == "autogen"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "telemetry"
Provides-Extra: perf
Requires-Dist: orjson>=3.9; extra == "perf"
Provides-Extra: all
Requires-Dist: humane-proxy[autogen,crewai,langchain,llamaindex,mcp,ml,onnx,perf,postgres,redis,telemetry]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Vishisht16/Humane-Proxy/main/docs/assets/banner.png" alt="HumaneProxy" width="100%">
</p>

<!-- mcp-name: io.github.Vishisht16/humane-proxy -->

**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.

[![PyPI](https://img.shields.io/pypi/v/humane-proxy.svg)](https://pypi.org/project/humane-proxy/)
[![Python](https://img.shields.io/pypi/pyversions/humane-proxy.svg)](https://pypi.org/project/humane-proxy/)
[![Downloads](https://static.pepy.tech/badge/humane-proxy)](https://pepy.tech/projects/humane-proxy)
[![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)
[![MCP Marketplace](https://img.shields.io/badge/MCP_Marketplace-Available-brightgreen)](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).

---

## 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/) | ![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 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, care response modes, risk trajectory & time-decay, multi-worker Redis |
| [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.
