feat: Enhance gateway security features and update documentation

- Added input firewall and output moderation options in README.md.
- Introduced `get_gateway_security_summary()` method in CostKatanaClient for fetching aggregated security stats.
- Updated __init__.py to include new gateway-related exports.

Author: abdulgeek

README.md

@@ -55,6 +55,10 @@ The Python package’s high-level **`ck.ai()`** / **`ck.chat()`** APIs talk to C
 | `Content-Type` | `application/json` |
 | `x-project-id` | Optional — same as `PROJECT_ID` for dashboard scoping |
 
+The hosted gateway enables **input firewall** (LLM security) and **output moderation** by default. To opt out for a request, add `CostKatana-LLM-Security-Enabled: false` and/or `CostKatana-Output-Moderation-Enabled: false`. In Python you can merge `cost_katana.gateway_request_headers(llm_security_enabled=False)` into your headers.
+
+To fetch dashboard aggregates (blocked prompts, moderation counts), use `CostKatanaClient.get_gateway_security_summary()` (`GET /api/gateway/security/summary`).
+
 **OpenAI-compatible** — `POST {GATEWAY}/v1/chat/completions`
 
 ```python

cost_katana/__init__.py

@@ -22,6 +22,7 @@
 from typing import Optional, List, Dict, Any
 
 from .client import CostKatanaClient, get_global_client, configure, auto_configure, from_env
+from .gateway import gateway_request_headers, GATEWAY_API_PREFIX
 from .models import ChatSession
 from .exceptions import (
     CostKatanaError,
@@ -439,4 +440,7 @@ def _infer_provider(model: str) -> str:
     "CostLimitExceededError",
     # Config
     "Config",
+    # Gateway (direct HTTP to /api/gateway)
+    "gateway_request_headers",
+    "GATEWAY_API_PREFIX",
 ]

cost_katana/client.py

@@ -18,6 +18,7 @@
 from .logging import AILogger
 from .logging.logger import logger
 from .templates import TemplateManager
+from .gateway import GATEWAY_API_PREFIX
 
 # Global client instance for the configure function
 _global_client = None
@@ -354,3 +355,18 @@ def delete_conversation(self, conversation_id: str) -> Dict[str, Any]:
             if isinstance(e, CostKatanaError):
                 raise
             raise CostKatanaError(f"Failed to delete conversation: {str(e)}")
+
+    def get_gateway_security_summary(self) -> Dict[str, Any]:
+        """
+        Fetch aggregated gateway security stats (input firewall ThreatLog + output moderation usage).
+
+        Calls ``GET /api/gateway/security/summary`` with the same auth as other dashboard APIs.
+        """
+        try:
+            response = self.client.get(f"{GATEWAY_API_PREFIX}/security/summary")
+            data = self._handle_response(response)
+            return data.get("data", data)
+        except Exception as e:
+            if isinstance(e, CostKatanaError):
+                raise
+            raise CostKatanaError(f"Failed to get gateway security summary: {str(e)}")

cost_katana/gateway.py

@@ -0,0 +1,35 @@
+"""
+AI Gateway helpers — HTTP headers and dashboard APIs aligned with Cost Katana gateway defaults.
+
+The hosted gateway enables input firewall (LLM security) and output moderation by default.
+Send explicit ``false`` headers only to opt out.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# Relative to API origin (e.g. https://api.costkatana.com)
+GATEWAY_API_PREFIX = "/api/gateway"
+
+
+def gateway_request_headers(
+    *,
+    llm_security_enabled: Optional[bool] = None,
+    output_moderation_enabled: Optional[bool] = None,
+) -> Dict[str, str]:
+    """
+    Extra HTTP headers for direct ``POST /api/gateway/v1/...`` calls (e.g. with httpx).
+
+    Server defaults: both protections ON. Pass ``False`` to opt out.
+
+    Args:
+        llm_security_enabled: If False, sets ``CostKatana-LLM-Security-Enabled: false``.
+        output_moderation_enabled: If False, sets ``CostKatana-Output-Moderation-Enabled: false``.
+    """
+    h: Dict[str, str] = {}
+    if llm_security_enabled is False:
+        h["CostKatana-LLM-Security-Enabled"] = "false"
+    if output_moderation_enabled is False:
+        h["CostKatana-Output-Moderation-Enabled"] = "false"
+    return h