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

{humane_proxy-0.2.2 → humane_proxy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: humane-proxy
-Version: 0.2.2
+Version: 0.3.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
@@ -40,8 +40,19 @@ 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: all
-Requires-Dist: humane-proxy[langchain,mcp,ml]; extra == "all"
+Requires-Dist: humane-proxy[autogen,crewai,langchain,llamaindex,mcp,ml,postgres,redis]; extra == "all"
 Dynamic: license-file
 
 # 🛡️ HumaneProxy
@@ -56,6 +67,8 @@ HumaneProxy sits between your users and any LLM. When someone expresses self-har
 [![Python](https://img.shields.io/pypi/pyversions/humane-proxy.svg)](https://pypi.org/project/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)
+[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 
 ---
 
@@ -85,10 +98,13 @@ pip install humane-proxy
 # Scaffold config in your project directory
 humane-proxy init
 
-# Start the proxy (set LLM_API_KEY and LLM_API_URL in .env first)
+# Start the reverse proxy server
+# (requires LLM_API_KEY and LLM_API_URL in .env — these point to your upstream LLM)
 humane-proxy start
 ```
 
+> **Note:** `LLM_API_KEY` and `LLM_API_URL` are only needed for the reverse proxy server (`humane-proxy start`). They tell HumaneProxy where to forward safe messages. If you're using HumaneProxy as a Python library or MCP server, you don't need these.
+
 ### As a Python library
 
 ```python
@@ -109,19 +125,21 @@ result = await proxy.check_async("How do I make a bomb")
 
 ## 3-Stage Cascade Pipeline
 
-HumaneProxy classifies every message through up to **3 stages**, each progressively more capable but also more expensive. Stages exit early when confident.
+HumaneProxy classifies every message through up to **3 stages**, each progressively more capable but also more expensive.
 
 ```
 ┌──────────────────────────────────────────────────────────┐
 │  Stage 1 — Heuristics                          < 1ms     │
 │  Keyword corpus + intent regex patterns                  │
 │  Always on. Catches clear cases instantly.               │
+│  Early-exit: definitive self_harm → block immediately.   │
 └──────────────────────────────────────────────────────────┘
-             ↓ (ambiguous or medium-score)
+             ↓ (all other messages when Stage 2 enabled)
 ┌──────────────────────────────────────────────────────────┐
 │  Stage 2 — Semantic Embeddings               ~100ms      │
 │  sentence-transformers cosine similarity                 │
 │  vs. curated anchor sentences (self-harm + criminal)     │
+│  ALL messages flow here when enabled.                    │
 │  Optional: pip install humane-proxy[ml]                  │
 └──────────────────────────────────────────────────────────┘
              ↓ (still ambiguous)
@@ -170,6 +188,8 @@ stage2:
 
 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.
+
 ### Stage 3 — Reasoning LLM
 
 Set your API key and optionally configure the provider:
@@ -225,6 +245,10 @@ HumaneProxy returns an empathetic message with crisis resources for 10+ countrie
 safety:
   categories:
     self_harm:
+      # Self-harm escalation threshold (0.0 to 1.0).
+      # Scores below this are downgraded to safe.
+      escalate_threshold: 0.5
+
       response_mode: "block"     # default
 
       # Optional: override the built-in message
@@ -275,6 +299,10 @@ escalation:
       to:
         - "safety-team@yourorg.com"
         - "oncall@yourorg.com"
+
+# Swappable Storage Backend (sqlite config default, redis/postgres optional)
+storage:
+  backend: "sqlite"  # or "redis", "postgres"
 ```
 
 ---
@@ -324,10 +352,13 @@ curl -X DELETE http://localhost:8000/admin/sessions/user-42 \
 
 | Endpoint | Description |
 |---|---|
-| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id` |
+| `GET /admin/health` | Health check (no auth required) |
+| `GET /admin/config` | Active config view (secrets redacted) |
+| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id`, `date`, sortable |
+| `GET /admin/escalations/export` | CSV export of escalations |
 | `GET /admin/escalations/{id}` | Single escalation detail |
 | `GET /admin/sessions/{id}/risk` | Session history + trajectory |
-| `GET /admin/stats` | Aggregate counts by category and day |
+| `GET /admin/stats` | Aggregate counts, top sessions, hourly breakdown |
 | `DELETE /admin/sessions/{id}` | Delete all session records |
 
 ---
@@ -352,10 +383,38 @@ Available on the [Official MCP Registry](https://registry.modelcontextprotocol.i
 
 ---
 
-## LangChain Integration
+## AI Agent Integrations
+
+HumaneProxy tools can be natively plugged into standard agentic frameworks:
+
+### LlamaIndex
+```bash
+pip install humane-proxy[llamaindex]
+```
+```python
+from humane_proxy.integrations.llamaindex import get_safety_tools
+tools = get_safety_tools() # Native FunctionTool instances
+```
 
-Plug HumaneProxy safety tools into any LangChain or LangGraph agent:
+### CrewAI
+```bash
+pip install humane-proxy[crewai]
+```
+```python
+from humane_proxy.integrations.crewai import get_safety_tools
+tools = get_safety_tools() # Native BaseTool subclass instances
+```
+
+### AutoGen (AG2)
+```bash
+pip install humane-proxy[autogen]
+```
+```python
+from humane_proxy.integrations.autogen import register_safety_tools
+register_safety_tools(assistant, user_proxy)
+```
 
+### LangChain
 ```bash
 pip install humane-proxy[langchain]
 ```
@@ -381,15 +440,17 @@ All values can be set in `humane_proxy.yaml` (project root) or via `HUMANE_PROXY
 | YAML key | Env var | Default | Description |
 |---|---|---|---|
 | `safety.risk_threshold` | `HUMANE_PROXY_RISK_THRESHOLD` | `0.7` | Score threshold for criminal_intent escalation |
-| `safety.spike_boost` | — | `0.25` | Score boost on trajectory spike |
+| `safety.categories.self_harm.escalate_threshold` | `HUMANE_PROXY_SELF_HARM_THRESHOLD` | `0.5` | Score threshold for self_harm escalation |
+| `safety.spike_boost` | `HUMANE_PROXY_SPIKE_BOOST` | `0.25` | Score boost on trajectory spike |
 | `server.port` | `HUMANE_PROXY_PORT` | `8000` | Proxy port |
-| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages |
+| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages (e.g. `1,2,3`) |
 | `pipeline.stage1_ceiling` | `HUMANE_PROXY_STAGE1_CEILING` | `0.3` | Early exit after Stage 1 |
 | `pipeline.stage2_ceiling` | `HUMANE_PROXY_STAGE2_CEILING` | `0.4` | Early exit after Stage 2 |
 | `stage3.provider` | `HUMANE_PROXY_STAGE3_PROVIDER` | `"auto"` | Stage 3 provider |
 | `stage3.timeout` | `HUMANE_PROXY_STAGE3_TIMEOUT` | `10` | Stage 3 timeout (s) |
 | `privacy.store_message_text` | — | `false` | Store raw text (vs SHA-256 hash) |
-| `escalation.rate_limit_max` | — | `3` | Max alerts per session/window |
+| `escalation.rate_limit_max` | `HUMANE_PROXY_RATE_LIMIT_MAX` | `3` | Max alerts per session/window |
+| `storage.backend` | `HUMANE_PROXY_STORAGE_BACKEND` | `"sqlite"` | `"sqlite"`, `"redis"`, `"postgres"` |
 | `safety.categories.self_harm.response_mode` | — | `"block"` | `"block"` or `"forward"` |
 
 ---
@@ -419,11 +480,16 @@ privacy:
 
 | Extra | Command | What it adds |
 |---|---|---|
-| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + full API + CLI |
+| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + default SQLite storage |
 | `ml` | `pip install humane-proxy[ml]` | Stage 2 semantic embeddings (`sentence-transformers`) |
 | `mcp` | `pip install humane-proxy[mcp]` | MCP server for AI agent integration (`fastmcp`) |
+| `redis` | `pip install humane-proxy[redis]` | Redis storage backend (`redis`) |
+| `postgres` | `pip install humane-proxy[postgres]` | PostgreSQL storage backend (`psycopg`, `psycopg_pool`) |
+| `llamaindex` | `pip install humane-proxy[llamaindex]` | LlamaIndex native integration (`llama-index-core`) |
+| `crewai` | `pip install humane-proxy[crewai]` | CrewAI native integration (`crewai[tools]`) |
+| `autogen` | `pip install humane-proxy[autogen]` | AutoGen native integration (`autogen-agentchat`) |
 | `langchain` | `pip install humane-proxy[langchain]` | LangChain adapter (MCP + `langchain-mcp-adapters`) |
-| `all` | `pip install humane-proxy[all]` | Everything above |
+| `all` | `pip install humane-proxy[all]` | Includes ALL optional dependencies above |
 
 ---
 

humane_proxy-0.2.2/humane_proxy.egg-info/PKG-INFO → humane_proxy-0.3.0/README.md

@@ -1,49 +1,3 @@
-Metadata-Version: 2.4
-Name: humane-proxy
-Version: 0.2.2
-Summary: Lightweight, plug-and-play AI safety middleware that protects humans.
-Author-email: Vishisht Mishra <Vishisht16@users.noreply.github.com>
-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.100.0
-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
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
-Requires-Dist: httpx; extra == "dev"
-Provides-Extra: ml
-Requires-Dist: sentence-transformers>=2.2.0; extra == "ml"
-Provides-Extra: mcp
-Requires-Dist: fastmcp>=0.4.0; 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: all
-Requires-Dist: humane-proxy[langchain,mcp,ml]; extra == "all"
-Dynamic: license-file
-
 # 🛡️ HumaneProxy
 
 <!-- mcp-name: io.github.Vishisht16/humane-proxy -->
@@ -56,6 +10,8 @@ HumaneProxy sits between your users and any LLM. When someone expresses self-har
 [![Python](https://img.shields.io/pypi/pyversions/humane-proxy.svg)](https://pypi.org/project/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)
+[![Humane-Proxy MCP server](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy/badges/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 
 ---
 
@@ -85,10 +41,13 @@ pip install humane-proxy
 # Scaffold config in your project directory
 humane-proxy init
 
-# Start the proxy (set LLM_API_KEY and LLM_API_URL in .env first)
+# Start the reverse proxy server
+# (requires LLM_API_KEY and LLM_API_URL in .env — these point to your upstream LLM)
 humane-proxy start
 ```
 
+> **Note:** `LLM_API_KEY` and `LLM_API_URL` are only needed for the reverse proxy server (`humane-proxy start`). They tell HumaneProxy where to forward safe messages. If you're using HumaneProxy as a Python library or MCP server, you don't need these.
+
 ### As a Python library
 
 ```python
@@ -109,19 +68,21 @@ result = await proxy.check_async("How do I make a bomb")
 
 ## 3-Stage Cascade Pipeline
 
-HumaneProxy classifies every message through up to **3 stages**, each progressively more capable but also more expensive. Stages exit early when confident.
+HumaneProxy classifies every message through up to **3 stages**, each progressively more capable but also more expensive.
 
 ```
 ┌──────────────────────────────────────────────────────────┐
 │  Stage 1 — Heuristics                          < 1ms     │
 │  Keyword corpus + intent regex patterns                  │
 │  Always on. Catches clear cases instantly.               │
+│  Early-exit: definitive self_harm → block immediately.   │
 └──────────────────────────────────────────────────────────┘
-             ↓ (ambiguous or medium-score)
+             ↓ (all other messages when Stage 2 enabled)
 ┌──────────────────────────────────────────────────────────┐
 │  Stage 2 — Semantic Embeddings               ~100ms      │
 │  sentence-transformers cosine similarity                 │
 │  vs. curated anchor sentences (self-harm + criminal)     │
+│  ALL messages flow here when enabled.                    │
 │  Optional: pip install humane-proxy[ml]                  │
 └──────────────────────────────────────────────────────────┘
              ↓ (still ambiguous)
@@ -170,6 +131,8 @@ stage2:
 
 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.
+
 ### Stage 3 — Reasoning LLM
 
 Set your API key and optionally configure the provider:
@@ -225,6 +188,10 @@ HumaneProxy returns an empathetic message with crisis resources for 10+ countrie
 safety:
   categories:
     self_harm:
+      # Self-harm escalation threshold (0.0 to 1.0).
+      # Scores below this are downgraded to safe.
+      escalate_threshold: 0.5
+
       response_mode: "block"     # default
 
       # Optional: override the built-in message
@@ -275,6 +242,10 @@ escalation:
       to:
         - "safety-team@yourorg.com"
         - "oncall@yourorg.com"
+
+# Swappable Storage Backend (sqlite config default, redis/postgres optional)
+storage:
+  backend: "sqlite"  # or "redis", "postgres"
 ```
 
 ---
@@ -324,10 +295,13 @@ curl -X DELETE http://localhost:8000/admin/sessions/user-42 \
 
 | Endpoint | Description |
 |---|---|
-| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id` |
+| `GET /admin/health` | Health check (no auth required) |
+| `GET /admin/config` | Active config view (secrets redacted) |
+| `GET /admin/escalations` | Paginated list, filterable by `category`, `session_id`, `date`, sortable |
+| `GET /admin/escalations/export` | CSV export of escalations |
 | `GET /admin/escalations/{id}` | Single escalation detail |
 | `GET /admin/sessions/{id}/risk` | Session history + trajectory |
-| `GET /admin/stats` | Aggregate counts by category and day |
+| `GET /admin/stats` | Aggregate counts, top sessions, hourly breakdown |
 | `DELETE /admin/sessions/{id}` | Delete all session records |
 
 ---
@@ -352,10 +326,38 @@ Available on the [Official MCP Registry](https://registry.modelcontextprotocol.i
 
 ---
 
-## LangChain Integration
+## AI Agent Integrations
+
+HumaneProxy tools can be natively plugged into standard agentic frameworks:
+
+### LlamaIndex
+```bash
+pip install humane-proxy[llamaindex]
+```
+```python
+from humane_proxy.integrations.llamaindex import get_safety_tools
+tools = get_safety_tools() # Native FunctionTool instances
+```
+
+### CrewAI
+```bash
+pip install humane-proxy[crewai]
+```
+```python
+from humane_proxy.integrations.crewai import get_safety_tools
+tools = get_safety_tools() # Native BaseTool subclass instances
+```
 
-Plug HumaneProxy safety tools into any LangChain or LangGraph agent:
+### AutoGen (AG2)
+```bash
+pip install humane-proxy[autogen]
+```
+```python
+from humane_proxy.integrations.autogen import register_safety_tools
+register_safety_tools(assistant, user_proxy)
+```
 
+### LangChain
 ```bash
 pip install humane-proxy[langchain]
 ```
@@ -381,15 +383,17 @@ All values can be set in `humane_proxy.yaml` (project root) or via `HUMANE_PROXY
 | YAML key | Env var | Default | Description |
 |---|---|---|---|
 | `safety.risk_threshold` | `HUMANE_PROXY_RISK_THRESHOLD` | `0.7` | Score threshold for criminal_intent escalation |
-| `safety.spike_boost` | — | `0.25` | Score boost on trajectory spike |
+| `safety.categories.self_harm.escalate_threshold` | `HUMANE_PROXY_SELF_HARM_THRESHOLD` | `0.5` | Score threshold for self_harm escalation |
+| `safety.spike_boost` | `HUMANE_PROXY_SPIKE_BOOST` | `0.25` | Score boost on trajectory spike |
 | `server.port` | `HUMANE_PROXY_PORT` | `8000` | Proxy port |
-| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages |
+| `pipeline.enabled_stages` | `HUMANE_PROXY_ENABLED_STAGES` | `[1]` | Active stages (e.g. `1,2,3`) |
 | `pipeline.stage1_ceiling` | `HUMANE_PROXY_STAGE1_CEILING` | `0.3` | Early exit after Stage 1 |
 | `pipeline.stage2_ceiling` | `HUMANE_PROXY_STAGE2_CEILING` | `0.4` | Early exit after Stage 2 |
 | `stage3.provider` | `HUMANE_PROXY_STAGE3_PROVIDER` | `"auto"` | Stage 3 provider |
 | `stage3.timeout` | `HUMANE_PROXY_STAGE3_TIMEOUT` | `10` | Stage 3 timeout (s) |
 | `privacy.store_message_text` | — | `false` | Store raw text (vs SHA-256 hash) |
-| `escalation.rate_limit_max` | — | `3` | Max alerts per session/window |
+| `escalation.rate_limit_max` | `HUMANE_PROXY_RATE_LIMIT_MAX` | `3` | Max alerts per session/window |
+| `storage.backend` | `HUMANE_PROXY_STORAGE_BACKEND` | `"sqlite"` | `"sqlite"`, `"redis"`, `"postgres"` |
 | `safety.categories.self_harm.response_mode` | — | `"block"` | `"block"` or `"forward"` |
 
 ---
@@ -419,11 +423,16 @@ privacy:
 
 | Extra | Command | What it adds |
 |---|---|---|
-| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + full API + CLI |
+| *(none)* | `pip install humane-proxy` | Stage 1 heuristics + default SQLite storage |
 | `ml` | `pip install humane-proxy[ml]` | Stage 2 semantic embeddings (`sentence-transformers`) |
 | `mcp` | `pip install humane-proxy[mcp]` | MCP server for AI agent integration (`fastmcp`) |
+| `redis` | `pip install humane-proxy[redis]` | Redis storage backend (`redis`) |
+| `postgres` | `pip install humane-proxy[postgres]` | PostgreSQL storage backend (`psycopg`, `psycopg_pool`) |
+| `llamaindex` | `pip install humane-proxy[llamaindex]` | LlamaIndex native integration (`llama-index-core`) |
+| `crewai` | `pip install humane-proxy[crewai]` | CrewAI native integration (`crewai[tools]`) |
+| `autogen` | `pip install humane-proxy[autogen]` | AutoGen native integration (`autogen-agentchat`) |
 | `langchain` | `pip install humane-proxy[langchain]` | LangChain adapter (MCP + `langchain-mcp-adapters`) |
-| `all` | `pip install humane-proxy[all]` | Everything above |
+| `all` | `pip install humane-proxy[all]` | Includes ALL optional dependencies above |
 
 ---
 

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

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