feat: add fastapi-ai-guardrails extension (fixes #82)

extensions/fastapi-ai-guardrails/README.md

@@ -0,0 +1,78 @@
+# fastapi-ai-guardrails
+
+A FastAPI extension providing typed guardrail hooks for input and output validation in AI applications.
+
+## Overview
+
+This extension adds guardrail mechanisms to ensure that AI-generated or user-provided inputs and outputs meet certain quality and safety standards. It provides:
+
+- **Input validation**: Checks for required fields, maximum length limits, and blocked patterns.
+- **Output validation**: Ensures generated responses adhere to safety and formatting rules.
+- **Extensible design**: Easy to customize guardrail rules for specific use cases.
+
+## Installation
+
+```bash
+pip install fastapi-ai-guardrails
+```
+
+## Usage
+
+Add the extension to your FastAPI application:
+
+```python
+from fastapi import FastAPI
+from fastapi_ai_guardrails import apply_input_guardrails, apply_output_guardrails
+
+app = FastAPI()
+
+@app.post("/chat")
+async def chat_endpoint(
+    user_message: str,
+    model_response: dict,
+):
+    # Validate input
+    validated_input = apply_input_guardrails(user_message)
+
+    # Process the model
+    processed = model.process(validated_input)
+
+    # Validate output
+    validated_output = apply_output_guardrails(processed)
+
+    return {"response": validated_output}
+```
+
+## Guardrail Rules
+
+### Input Validation
+
+- **Required fields**: Ensure critical fields are present
+- **Max length**: Limit string lengths to prevent excessive processing
+- **Blocked patterns**: Prevent dangerous or inappropriate content
+
+### Output Validation
+
+- **Max length**: Cap response size
+- **Blocked patterns**: Sanitize output for safety
+- **Structured response checks**: Enforce expected schema
+
+## Configuration
+
+The extension accepts configurable parameters for each guardrail:
+
+- `max_length`: Maximum allowed length for strings
+- `blocked_patterns`: List of substrings to reject
+- `required_fields`: Fields that must be present
+
+## Testing
+
+Run the test suite:
+
+```bash
+pytest extensions/fastapi-ai-guardrails/tests/test_guardrails.py -v
+```
+
+## License
+
+MIT

extensions/fastapi-ai-guardrails/README.md.append

@@ -0,0 +1,85 @@
+# fastapi-ai-guardrails Extension
+
+## Overview
+
+This extension provides comprehensive input and output guardrail validation for FastAPI AI applications, ensuring safety and quality standards are maintained throughout the AI pipeline.
+
+## Features
+
+- **Input Validation**: Required fields, max length limits, blocked patterns
+- **Output Validation**: Structured response checks, safety filters
+- **Configurable Rules**: Easy customization for specific use cases
+- **Error Handling**: Clear GuardrailError exceptions with descriptive messages
+
+## Integration
+
+Add to your `extension-addons` in `cpa.config.json`:
+
+```json
+{
+  "extension-addons": ["fastapi-ai-guardrails"]
+}
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from app.core.guardrails import apply_input_guardrails, apply_output_guardrails
+
+# Validate user input
+validated_input = apply_input_guardrails(
+    user_query,
+    max_length=1000,
+    blocked_patterns=["ignore previous instructions", "delete everything"],
+    required_fields=["user_id", "query_type"]
+)
+
+# Validate model output
+validated_output = apply_output_guardrails(
+    model_response,
+    max_length=500,
+    blocked_patterns=["@", "mailto:"],
+    required_fields=["answer", "confidence"]
+)
+```
+
+### Configuration for Your App
+
+Create `app/config/guardrails.yaml`:
+
+```yaml
+input:
+  max_length: 1000
+  blocked_patterns:
+    - "ignore"
+    - "bypass"
+    - "override"
+  required_fields:
+    - "user_id"
+    - "session_id"
+
+output:
+  max_length: 500
+  blocked_patterns:
+    - "@"
+    - "mailto:"
+    - "tel:"
+  required_fields:
+    - "response"
+    - "confidence"
+```
+
+## Testing
+
+Run extension tests:
+
+```bash
+cd extensions/fastapi-ai-guardrails
+pytest tests/ -v
+```
+
+## License
+
+MIT

extensions/fastapi-ai-guardrails/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "fastapi-ai-guardrails"
+version = "0.1.0"
+description = "FastAPI AI extension with guardrails for input/output validation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[build-system]
+requires = ["setuptools>=65.0"]
+build-backend = "setuptools.build_meta"

extensions/fastapi-ai-guardrails/template/.env.example.append

@@ -0,0 +1,26 @@
+# FastAPI AI Guardrails Configuration
+
+# Input guardrail settings
+GUARDRAILS_INPUT_MAX_LENGTH=1000
+GUARDRAILS_INPUT_BLOCKED_PATTERNS=ignore previous instructions,bypass security,delete everything,override
+GUARDRAILS_INPUT_REQUIRED_FIELDS=user_id,session_id
+
+# Output guardrail settings
+GUARDRAILS_OUTPUT_MAX_LENGTH=500
+GUARDRAILS_OUTPUT_BLOCKED_PATTERNS=@,mailto:,tel:,password,secret
+GUARDRAILS_OUTPUT_REQUIRED_FIELDS=answer,confidence
+
+# Debug mode
+DEBUG_GUARDRAILS=0
+
+# Logging
+LOG_LEVEL=INFO
+GUARDRAILS_LOG_INVALID_INPUTS=true
+GUARDRAILS_LOG_INVALID_OUTPUTS=true
+
+# Rate limiting (requests per minute)
+GUARDRAILS_RATE_LIMIT_PER_MINUTE=100
+
+# Cache settings
+GUARDRAILS_CACHE_ENABLED=true
+GUARDRAILS_CACHE_TTL=3600

extensions/fastapi-ai-guardrails/template/.gitignore

@@ -0,0 +1,65 @@
+# FastAPI AI Guardrails Extension
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.example
+
+# Distribution
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Documentation
+*.log
+*.log.*
+
+# Data
+*.csv
+*.json
+*.yaml
+*.yml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+
+# Extension-specific
+/app/core/__pycache__/
+/tests/__pycache__/
+/cache/
+/temp/

extensions/fastapi-ai-guardrails/template/app/core/guardrails.py

@@ -0,0 +1,102 @@
+"""
+FastAPI AI guardrails extension.
+Provides typed guardrail hooks for input and output validation.
+"""
+
+from typing import Any, Callable, List, Optional, Union
+
+
+class GuardrailError(Exception):
+    """Raised when input or output violates guardrail rules."""
+
+
+def apply_input_guardrails(
+    input_data: Any,
+    *,
+    max_length: int = 1000,
+    blocked_patterns: Optional[List[str]] = None,
+    required_fields: Optional[List[str]] = None,
+) -> Any:
+    """
+    Validate input data against guardrail rules.
+
+    Args:
+        input_data: The input data to validate.
+        max_length: Maximum allowed length for string fields.
+        blocked_patterns: List of regex-like patterns that should not appear.
+        required_fields: List of field names that must be present.
+
+    Returns:
+        The validated input data (possibly modified).
+
+    Raises:
+        GuardrailError: If input violates any guardrail rule.
+    """
+    # Check required fields
+    if required_fields:
+        for field in required_fields:
+            if field not in input_data:
+                raise GuardrailError(f"Missing required field: {field}")
+
+    # Check max length for strings
+    if isinstance(input_data, str):
+        if len(input_data) > max_length:
+            raise GuardrailError(
+                f"Input string exceeds maximum length of {max_length}: {len(input_data)}"
+            )
+
+    # Check blocked patterns
+    if blocked_patterns:
+        for pattern in blocked_patterns:
+            if pattern in str(input_data):
+                raise GuardrailError(
+                    f"Input contains blocked pattern: {pattern}"
+                )
+
+    return input_data
+
+
+def apply_output_guardrails(
+    output_data: Any,
+    *,
+    max_length: int = 1000,
+    blocked_patterns: Optional[List[str]] = None,
+    required_fields: Optional[List[str]] = None,
+) -> Any:
+    """
+    Validate output data against guardrail rules.
+
+    Args:
+        output_data: The output data to validate.
+        max_length: Maximum allowed length for string fields.
+        blocked_patterns: List of regex-like patterns that should not appear.
+        required_fields: List of field names that must be present.
+
+    Returns:
+        The validated output data (possibly modified).
+
+    Raises:
+        GuardrailError: If output violates any guardrail rule.
+    """
+    # Check required fields
+    if required_fields:
+        for field in required_fields:
+            if field not in output_data:
+                raise GuardrailError(f"Missing required field: {field}")
+
+    # Check max length for strings
+    if isinstance(output_data, str):
+        if len(output_data) > max_length:
+            raise GuardrailError(
+                f"Output string exceeds maximum length of {max_length}: {len(output_data)}"
+            )
+
+    # Check blocked patterns
+    if blocked_patterns:
+        for pattern in blocked_patterns:
+            if pattern in str(output_data):
+                raise GuardrailError(
+                    f"Output contains blocked pattern: {pattern}"
+                )
+
+    return output_data