humane-proxy 0.2.3__tar.gz → 0.3.1__tar.gz

{humane_proxy-0.2.3/humane_proxy.egg-info → humane_proxy-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: humane-proxy
-Version: 0.2.3
+Version: 0.3.1
 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,8 +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/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 [![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)
 
 ---
 
@@ -175,6 +186,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.
@@ -234,6 +247,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
@@ -258,6 +275,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`:
@@ -284,6 +362,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"
 ```
 
 ---
@@ -333,10 +415,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 |
 
 ---
@@ -361,10 +446,38 @@ Available on the [Official MCP Registry](https://registry.modelcontextprotocol.i
 
 ---
 
-## LangChain Integration
+## AI Agent Integrations
 
-Plug HumaneProxy safety tools into any LangChain or LangGraph agent:
+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
+```
+
+### 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]
 ```
@@ -390,15 +503,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"` |
 
 ---
@@ -428,11 +543,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.3 → humane_proxy-0.3.1}/README.md

@@ -10,8 +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/card.svg)](https://glama.ai/mcp/servers/Vishisht16/Humane-Proxy)
 [![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)
 
 ---
 
@@ -129,6 +129,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.
@@ -188,6 +190,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
@@ -212,6 +218,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`:
@@ -238,6 +305,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"
 ```
 
 ---
@@ -287,10 +358,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 |
 
 ---
@@ -315,10 +389,38 @@ Available on the [Official MCP Registry](https://registry.modelcontextprotocol.i
 
 ---
 
-## LangChain Integration
+## AI Agent Integrations
 
-Plug HumaneProxy safety tools into any LangChain or LangGraph agent:
+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
+```
+
+### 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]
 ```
@@ -344,15 +446,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"` |
 
 ---
@@ -382,11 +486,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.3 → humane_proxy-0.3.1}/humane_proxy/__init__.py

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