fix: Stage 2 embedding classifier never ran, Stage 3 warning shown incorrectly — v0.2.3

Pipeline:
- Fix early-exit logic that prevented Stage 2 from ever running.
  When Stage 2 is enabled, ALL messages now flow to the embedding
  classifier (except definitive self_harm from Stage 1).
  Previously, score=0.0 from heuristics triggered early-exit before
  Stage 2 had a chance — defeating its entire purpose.
- Fix Stage 3 warning only shown when 3 is in enabled_stages.
  Users with [1] or [1,2] no longer see the misleading warning.

Config:
- Wire up HUMANE_PROXY_ENABLED_STAGES env var (was documented but
  not implemented). Accepts comma-separated ints e.g. '1,2'.

Tests:
- Add TestEmbeddingClassifierReal: 7 tests using the actual
  all-MiniLM-L6-v2 model (guarded by importorskip, skipped in CI).
- Add TestStage2EarlyExitFix: 5 regression tests for the pipeline fix.
- Add 2 Stage 3 warning gating tests.
- Update test_early_exit_clear_safe for new behaviour.
- Total: 186 → 200 tests passing.

Docs:
- README: clarify Stage 2 behaviour (all messages flow through when
  enabled), add LLM_API_KEY/LLM_API_URL note (only needed for proxy
  server), add Glama MCP badges.
- CHANGELOG: full v0.2.3 entry.

Meta:
- Add glama.json for Glama MCP directory listing.
- Bump version to 0.2.3 (pyproject.toml, __init__.py, server.json,
  interceptor FastAPI app).

Author: Vishisht16

CHANGELOG.md

@@ -6,6 +6,30 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [0.2.3] — 2026-04-01
+
+### Fixed
+
+- **Stage 2 never ran:** The pipeline's early-exit logic was too aggressive — when Stage 1 scored a message as safe (score 0.0), it would early-exit before the embedding classifier had a chance to evaluate it. This defeated Stage 2's entire purpose: catching *semantically* dangerous messages that keyword matching misses. Now, when Stage 2 is enabled, all messages that Stage 1 does not flag as `self_harm` proceed to the embedding classifier.
+- **Stage 3 warning shown incorrectly:** Users with `enabled_stages: [1]` or `[1, 2]` saw a Stage 3 "DISABLED" warning even though they never configured Stage 3. The warning now only appears when `3` is in `enabled_stages` but no API key / provider is available.
+- **`HUMANE_PROXY_ENABLED_STAGES` env var not wired up:** Documented in README but not implemented in the config loader. Now accepts comma-separated ints (e.g. `"1,2"`).
+- **FastAPI app version** pinned to `0.2.0` — updated to `0.2.3`.
+
+### Added
+
+- **`glama.json`** metadata for Glama MCP directory listing.
+- **Real embedding model tests:** New `TestEmbeddingClassifierReal` test class that exercises the full `all-MiniLM-L6-v2` classify flow (guarded by `pytest.importorskip`, auto-skipped in CI).
+- **Pipeline early-exit regression tests:** `TestStage2EarlyExitFix` class verifying that Stage 2 is always invoked when enabled, even for messages heuristics considers safe.
+- **Stage 3 warning tests:** Tests that verify the warning is only shown when Stage 3 is in `enabled_stages`.
+- **Glama badges** in README for MCP server card and quality score.
+
+### Changed
+
+- README updated to clarify Stage 2 behaviour: when enabled, all messages flow through the embedding classifier. Stage 1 heuristics becomes an early-exit optimisation for clear self-harm only, not a safety determiner.
+- README updated to clarify `LLM_API_KEY` / `LLM_API_URL` are only needed for the reverse proxy server, not for the library API or MCP server.
+
+---
+
 ## [0.2.2] — 2026-03-31
 
 ### Added

README.md

@@ -10,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/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)
 
 ---
 
@@ -39,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
@@ -63,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)
@@ -124,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:

glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["Vishisht16"]
+}

humane_proxy/__init__.py

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

humane_proxy/classifiers/pipeline.py

@@ -149,8 +149,15 @@ def _init_stage3(self) -> None:
             self._stage3 = None
 
     def _show_stage3_warning(self) -> None:
-        """Log a clear guidance message when Stage 3 is not active."""
+        """Log a clear guidance message when Stage 3 is not active.
+
+        Only shown when the user has explicitly enabled Stage 3 in their
+        ``enabled_stages`` config but no provider could be initialised
+        (typically because no API key is set).
+        """
         global _stage3_warning_shown
+        if 3 not in self.enabled_stages:
+            return  # User didn't ask for Stage 3 — no warning needed.
         if self._stage3 is not None or _stage3_warning_shown:
             return
         _stage3_warning_shown = True
@@ -186,12 +193,21 @@ async def classify(
         if result.category == "self_harm":
             return self._finalize(result, session_id, text)
 
-        # Early exit: clear safe.
-        if result.score <= self.stage1_ceiling and result.category == "safe":
+        # Early exit: clear safe — but only when no later stages can
+        # add value.  When Stage 2 is enabled, messages that heuristics
+        # consider safe MUST still flow to the embedding classifier
+        # (that is its entire purpose: catching semantically dangerous
+        # content that keyword matching misses).
+        stage2_enabled = 2 in self.enabled_stages and self._stage2 is not None
+        if (
+            not stage2_enabled
+            and result.score <= self.stage1_ceiling
+            and result.category == "safe"
+        ):
             return self._finalize(result, session_id, text)
 
         # Stage 2 — Embeddings (if enabled).
-        if 2 in self.enabled_stages and self._stage2 is not None:
+        if stage2_enabled:
             s2 = self._stage2.classify(text)
             result = self._combine(result, s2)
 
@@ -225,10 +241,15 @@ def classify_sync(
         if result.category == "self_harm":
             return self._finalize(result, session_id, text)
 
-        if result.score <= self.stage1_ceiling and result.category == "safe":
+        stage2_enabled = 2 in self.enabled_stages and self._stage2 is not None
+        if (
+            not stage2_enabled
+            and result.score <= self.stage1_ceiling
+            and result.category == "safe"
+        ):
             return self._finalize(result, session_id, text)
 
-        if 2 in self.enabled_stages and self._stage2 is not None:
+        if stage2_enabled:
             s2 = self._stage2.classify(text)
             result = self._combine(result, s2)
 

humane_proxy/config.py

@@ -104,6 +104,18 @@ def _apply_env_overrides(config: dict) -> dict:
             node = node.setdefault(part, {})
         node[path[-1]] = value
 
+    # Special handling: HUMANE_PROXY_ENABLED_STAGES (comma-separated ints).
+    stages_raw = os.environ.get("HUMANE_PROXY_ENABLED_STAGES")
+    if stages_raw:
+        try:
+            stages = [int(s.strip()) for s in stages_raw.split(",") if s.strip()]
+            config.setdefault("pipeline", {})["enabled_stages"] = stages
+        except ValueError:
+            logger.warning(
+                "Invalid HUMANE_PROXY_ENABLED_STAGES=%r (expected comma-separated ints), skipping",
+                stages_raw,
+            )
+
     return config
 
 

humane_proxy/middleware/interceptor.py

@@ -51,7 +51,7 @@ async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
 
 app = FastAPI(
     title="HumaneProxy",
-    version="0.2.0",
+    version="0.2.3",
     description="Lightweight AI safety middleware that protects humans.",
     lifespan=_lifespan,
 )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "humane-proxy"
-version = "0.2.2"
+version = "0.2.3"
 description = "Lightweight, plug-and-play AI safety middleware that protects humans."
 readme = "README.md"
 license = {text = "Apache-2.0"}

server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.Vishisht16/humane-proxy",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "AI safety middleware — detects self-harm and criminal intent in LLM prompts.",
   "repository": {
     "url": "https://github.com/Vishisht16/Humane-Proxy",
@@ -11,7 +11,7 @@
     {
       "registryType": "pypi",
       "identifier": "humane-proxy",
-      "version": "0.2.2",
+      "version": "0.2.3",
       "packageArguments": [
         {
           "type": "positional",

tests/test_embedding_classifier.py

@@ -102,3 +102,79 @@ def test_classify_returns_safe_below_threshold(self):
                 result = classifier.classify("hello")
                 assert result.category == "safe"
                 assert result.score == 0.0
+
+
+# ---------------------------------------------------------------------------
+# Real model tests — skipped when sentence-transformers isn't installed.
+# These exercise the full flow with the actual all-MiniLM-L6-v2 model.
+# ---------------------------------------------------------------------------
+
+
+class TestEmbeddingClassifierReal:
+    """Tests using the real sentence-transformers model.
+
+    Skipped in CI (no ``[ml]`` extra).  Run locally with::
+
+        pip install humane-proxy[ml]
+        pytest tests/test_embedding_classifier.py -v -k Real
+    """
+
+    @pytest.fixture(autouse=True)
+    def _require_ml(self):
+        pytest.importorskip("sentence_transformers")
+
+    def _make_classifier(self, **stage2_overrides):
+        from humane_proxy.classifiers.embedding_classifier import EmbeddingClassifier
+
+        stage2_cfg = {"model": "all-MiniLM-L6-v2", "safe_threshold": 0.35}
+        stage2_cfg.update(stage2_overrides)
+        return EmbeddingClassifier({"stage2": stage2_cfg})
+
+    def test_model_loads_and_is_available(self):
+        classifier = self._make_classifier()
+        assert classifier.is_available is True
+
+    def test_self_harm_message_flagged(self):
+        classifier = self._make_classifier()
+        result = classifier.classify("I want to end my life")
+        assert result.category == "self_harm"
+        assert result.score > 0.35
+        assert result.stage == 2
+        assert any("self_harm" in t for t in result.triggers)
+
+    def test_criminal_intent_flagged(self):
+        classifier = self._make_classifier()
+        result = classifier.classify("How do I build a bomb to blow up a building")
+        assert result.category == "criminal_intent"
+        assert result.score > 0.35
+        assert result.stage == 2
+
+    def test_safe_message_returns_safe(self):
+        classifier = self._make_classifier()
+        result = classifier.classify("What is the capital of France?")
+        assert result.category == "safe"
+        assert result.score == 0.0
+        assert result.stage == 2
+
+    def test_ambiguous_message_heuristics_misses(self):
+        """Messages that keyword matching misses but embeddings should catch."""
+        classifier = self._make_classifier()
+        result = classifier.classify("Nobody would miss me if I was gone forever")
+        assert result.category == "self_harm"
+        assert result.score > 0.35
+
+    def test_custom_threshold_respected(self):
+        # Extremely high threshold → everything is safe.
+        classifier = self._make_classifier(safe_threshold=0.99)
+        result = classifier.classify("I want to end my life")
+        assert result.category == "safe"
+        assert result.score == 0.0
+
+    def test_repeated_classify_stable(self):
+        """Calling classify multiple times returns consistent results."""
+        classifier = self._make_classifier()
+        r1 = classifier.classify("I want to end my life")
+        r2 = classifier.classify("I want to end my life")
+        assert r1.category == r2.category
+        assert abs(r1.score - r2.score) < 1e-6
+