Quick Start

pip install 'hipocap[all]'

export HIPOCAP_API_KEY=your-api-key-here
export HIPOCAP_USER_ID=your-user-id-here
export HIPOCAP_SERVER_URL=http://localhost:8006  # Optional, for self-hosted

from hipocap import Hipocap
import os

client = Hipocap.initialize(
    project_api_key=os.environ.get("HIPOCAP_API_KEY"),
    base_url="http://localhost",      # Observability server
    http_port=8000,
    grpc_port=8001,
    hipocap_base_url="http://localhost:8006",  # Security server
    hipocap_user_id=os.environ.get("HIPOCAP_USER_ID")
)

from hipocap import Hipocap, observe
import os

# Initialize (from Step 3)
client = Hipocap.initialize(
    project_api_key=os.environ.get("HIPOCAP_API_KEY"),
    base_url="http://localhost",
    http_port=8000,
    grpc_port=8001,
    hipocap_base_url="http://localhost:8006",
    hipocap_user_id=os.environ.get("HIPOCAP_USER_ID")
)

@observe()
def get_user_data(user_id: str):
    """Retrieve user data - automatically traced."""
    return {"user_id": user_id, "email": f"user{user_id}@example.com"}

@observe()
def process_user_request():
    user_query = "What's my email?"
    user_id = "123"
    
    # Execute function
    user_data = get_user_data(user_id)
    
    # Analyze for security threats
    result = client.analyze(
        function_name="get_user_data",
        function_result=user_data,
        function_args={"user_id": user_id},
        user_query=user_query,
        user_role="user",
        input_analysis=True,   # Stage 1: Fast detection
        llm_analysis=True,     # Stage 2: Deep analysis
        policy_key="default"
    )
    
    # Check if safe to use
    if not result.get("safe_to_use"):
        return {
            "error": "Blocked by security policy",
            "reason": result.get("reason")
        }
    
    return user_data

{
    "safe_to_use": bool,           # True if content is safe
    "final_decision": str,         # "ALLOWED", "BLOCKED", or "REVIEW_REQUIRED"
    "reason": str,                 # Explanation of decision
    "input_score": float,          # Stage 1 score (0.0-1.0)
    "llm_score": float,            # Stage 2 score (0.0-1.0)
    "quarantine_score": float,     # Stage 3 score (0.0-1.0)
    "threat_indicators": [str],    # List of threat categories (S1-S14)
    "severity": str,               # "safe", "low", "medium", "high", "critical"
    "blocked_at": str              # Stage where content was blocked (if blocked)
}