Skip to main content
The Hipocap Shield protects your AI applications by analyzing function calls before execution. This guide shows you how to set it up.

​
Prerequisites

  • Hipocap account and project
  • Python application with function calls you want to protect
  • API key from your Hipocap project
  • Hipocap server running (self-hosted or cloud)

​
Installation

Install the Hipocap Python client: 
pip install hipocap

​
Basic Setup

​
1. Initialize Hipocap

Hipocap integrates with Laminar for observability. Initialize both together: 
from hipocap import Hipocap

# Initialize Hipocap with Laminar
observ_client = Hipocap.initialize(
    project_api_key="your-laminar-project-api-key",
    base_url="http://localhost",  # Laminar base URL
    http_port=8000,  # Laminar HTTP port
    grpc_port=8001,  # Laminar gRPC port
    hipocap_base_url="http://localhost:8006",  # Hipocap server URL
    hipocap_api_key="your-hipocap-api-key",
    hipocap_user_id="your-user-id"
)

​
2. Analyze Function Calls

Call analyze() on the observability client returned from initialize(): 
from hipocap import Hipocap

# Initialize and get the observability client
observ_client = Hipocap.initialize(
    project_api_key="your-hipocap-api-key",
    # ... other config ...
)

# Analyze function result after execution
result = observ_client.analyze(
    function_name="send_email",
    function_result=email_content,  # Actual function result
    function_args={"to": to, "subject": subject},
    user_query=user_query,
    user_role="user",
    input_analysis=True,
    llm_analysis=True,
    quarantine_analysis=False
)

if result.get("safe_to_use"):
    # Safe to use - return the result
    return email_content
else:
    # Blocked or requires review
    raise SecurityError(f"Blocked: {result.get('reason')}")

​
Analysis Modes

​
Quick Analysis Mode

For low-latency requirements, use quick analysis: 
# Use the observability client from initialization
result = observ_client.analyze(
    function_name="send_email",
    function_result=email_content,
    quick_analysis=True  # Faster, simplified analysis
)

​
Full Analysis Mode

For maximum security, enable all stages: 
# Use the observability client from initialization
result = observ_client.analyze(
    function_name="send_email",
    function_result=email_content,
    input_analysis=True,      # Stage 1: Input analysis
    llm_analysis=True,         # Stage 2: LLM analysis
    quarantine_analysis=True,  # Stage 3: Quarantine analysis
    quick_analysis=False        # Full detailed analysis
)

​
Handling Decisions

The analyze() method returns a dictionary with analysis results: 
# Use the observability client from initialization
result = observ_client.analyze(
    function_name="send_email",
    function_result=email_content,
    function_args={"to": to, "subject": subject}
)

if result.get("safe_to_use"):
    # Safe to use - return the result
    return email_content
else:
    # Blocked - raise security error
    raise SecurityError(f"Blocked: {result.get('reason')}")

​
Configuration Options

​
Analysis Stages

  • input_analysis (default: True) - Enable Stage 1 input analysis
  • llm_analysis (default: False) - Enable Stage 2 LLM analysis
  • quarantine_analysis (default: False) - Enable Stage 3 quarantine analysis
  • quick_analysis (default: False) - Use quick mode for faster analysis

​
Keyword Detection

# Use the observability client from initialization
result = observ_client.analyze(
    function_name="send_email",
    function_result=email_content,
    enable_keyword_detection=True,
    keywords=["confidential", "classified", "password reset"]
)

​
Policy Selection

# Use the observability client from initialization
result = observ_client.analyze(
    function_name="send_email",
    function_result=email_content,
    policy_key="production-policy"  # Use specific policy
)

​
Integration with Observability

All Shield decisions are automatically traced in Hipocap’s observability platform (powered by Laminar). Analysis results are sent as OpenTelemetry spans, so you can:
  • View blocked attempts in the traces view
  • Analyze security patterns across all function calls
  • Review audit logs for compliance
The analysis creates a span named hipocap.security.analysis with all analysis results as span attributes.

​
Next Steps