Rule Engine

Overview

The Shield360 SDKs provide a function to evaluate rules against the Rule Engine from your application code. At runtime, send trace attributes (model, provider, service name, etc.) and get back matching rules and their linked entities - contexts, prompts, or evaluation configurations.

This enables dynamic, condition-driven retrieval of AI resources without hardcoding logic in your application.

Contexts

Retrieve system prompts and knowledge based on model, user tier, or any attribute

Prompts

Fetch compiled prompts with variable substitution from the Prompt Hub

Evaluation Configs

Determine which evaluation types apply to a given trace

Prerequisites

Set up Shield360

Ensure you have a Shield360 instance running. See Installation for setup instructions.

Create an API Key

Navigate to Settings > API Keys in Shield360. Click Create API Key and save the key securely.

Create Rules

Set up rules with conditions and linked entities in the Rule Engine UI.

Configuration

All SDKs resolve the Shield360 URL and API key in the same order:

Parameter	Environment Variable	Description	Default
`url` / `URL`	`SHIELD360_URL`	Base URL of your Shield360 dashboard	`http://127.0.0.1:3000`
`api_key` / `apiKey` / `APIKey`	`SHIELD360_API_KEY`	API key for Bearer token authentication	required

export SHIELD360_URL="https://your-shield360-instance.com"
export SHIELD360_API_KEY="your-api-key"

Usage

Retrieve Contexts

Fetch context entities (system prompts, knowledge) that match the given trace attributes.

import shield360

result = shield360.evaluate_rule(
    entity_type="context",
    fields={
        "gen_ai.system": "openai",
        "gen_ai.request.model": "gpt-4",
        "service.name": "my-app",
    },
    include_entity_data=True,
)

if result:
    print("Matching rules:", result["matchingRuleIds"])
    for entity in result.get("entities", []):
        entity_key = f"{entity['entity_type']}:{entity['entity_id']}"
        data = result.get("entity_data", {}).get(entity_key, {})
        print(f"Context: {data.get('name')} - {data.get('content')}")

import Shield360 from 'shield360';

const result = await Shield360.evaluateRule({
  entityType: 'context',
  fields: {
    'gen_ai.system': 'openai',
    'gen_ai.request.model': 'gpt-4',
    'service.name': 'my-app',
  },
  includeEntityData: true,
});

if (!('err' in result)) {
  console.log('Matching rules:', result.matchingRuleIds);
  for (const entity of result.entities) {
    const key = `${entity.entity_type}:${entity.entity_id}`;
    const data = result.entity_data?.[key];
    console.log(`Context: ${data?.name} - ${data?.content}`);
  }
}

import (
    "context"
    "fmt"
    shield360 "github.com/ThinkfleetAI/shield360-go"
)

result, err := shield360.EvaluateRule(context.Background(), shield360.EvaluateRuleOptions{
    EntityType: shield360.RuleEntityContext,
    Fields: map[string]interface{}{
        "gen_ai.system":        "openai",
        "gen_ai.request.model": "gpt-4",
        "service.name":         "my-app",
    },
    IncludeEntityData: true,
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("Matching rules:", result.MatchingRuleIDs)
for _, entity := range result.Entities {
    key := fmt.Sprintf("%s:%s", entity.EntityType, entity.EntityID)
    if data, ok := result.EntityData[key]; ok {
        fmt.Printf("Context: %v\n", data)
    }
}

Retrieve Prompts

Fetch compiled prompts from the Prompt Hub with variable substitution.

import shield360

result = shield360.evaluate_rule(
    entity_type="prompt",
    fields={
        "gen_ai.system": "openai",
        "gen_ai.request.model": "gpt-4",
    },
    include_entity_data=True,
    entity_inputs={
        "variables": {"user_name": "Alice", "product": "Shield360"},
        "shouldCompile": True,
    },
)

if result:
    for entity in result.get("entities", []):
        key = f"prompt:{entity['entity_id']}"
        prompt_data = result.get("entity_data", {}).get(key, {})
        print("Compiled prompt:", prompt_data.get("compiledPrompt"))

import Shield360 from 'shield360';

const result = await Shield360.evaluateRule({
  entityType: 'prompt',
  fields: {
    'gen_ai.system': 'openai',
    'gen_ai.request.model': 'gpt-4',
  },
  includeEntityData: true,
  entityInputs: {
    variables: { user_name: 'Alice', product: 'Shield360' },
    shouldCompile: true,
  },
});

if (!('err' in result)) {
  for (const entity of result.entities) {
    const key = `prompt:${entity.entity_id}`;
    const promptData = result.entity_data?.[key];
    console.log('Compiled prompt:', promptData?.compiledPrompt);
  }
}

result, err := shield360.EvaluateRule(ctx, shield360.EvaluateRuleOptions{
    EntityType: shield360.RuleEntityPrompt,
    Fields: map[string]interface{}{
        "gen_ai.system":        "openai",
        "gen_ai.request.model": "gpt-4",
    },
    IncludeEntityData: true,
    EntityInputs: map[string]interface{}{
        "variables":     map[string]string{"user_name": "Alice", "product": "Shield360"},
        "shouldCompile": true,
    },
})
if err != nil {
    log.Fatal(err)
}

for _, entity := range result.Entities {
    key := fmt.Sprintf("prompt:%s", entity.EntityID)
    if data, ok := result.EntityData[key]; ok {
        fmt.Printf("Prompt data: %v\n", data)
    }
}

Check Evaluation Rules

Determine which evaluation types (hallucination, bias, etc.) are linked to rules matching the current trace. This works with both the 11 built-in evaluation types and any custom evaluation types you have created.

import shield360

result = shield360.evaluate_rule(
    entity_type="evaluation",
    fields={
        "gen_ai.system": "openai",
        "gen_ai.request.model": "gpt-4",
        "service.name": "production-api",
    },
)

if result and result["matchingRuleIds"]:
    print("Evaluation rules matched:", result["matchingRuleIds"])
    for entity in result.get("entities", []):
        print(f"  Evaluation type: {entity['entity_id']}")
else:
    print("No evaluation rules matched")

import Shield360 from 'shield360';

const result = await Shield360.evaluateRule({
  entityType: 'evaluation',
  fields: {
    'gen_ai.system': 'openai',
    'gen_ai.request.model': 'gpt-4',
    'service.name': 'production-api',
  },
});

if (!('err' in result) && result.matchingRuleIds.length > 0) {
  console.log('Evaluation rules matched:', result.matchingRuleIds);
  result.entities.forEach(e => console.log('  Evaluation type:', e.entity_id));
}

result, err := shield360.EvaluateRule(ctx, shield360.EvaluateRuleOptions{
    EntityType: shield360.RuleEntityEvaluation,
    Fields: map[string]interface{}{
        "gen_ai.system":        "openai",
        "gen_ai.request.model": "gpt-4",
        "service.name":         "production-api",
    },
})
if err != nil {
    log.Fatal(err)
}

if len(result.MatchingRuleIDs) > 0 {
    fmt.Println("Evaluation rules matched:", result.MatchingRuleIDs)
    for _, entity := range result.Entities {
        fmt.Printf("  Evaluation type: %s\n", entity.EntityID)
    }
}

Parameters

Python - `shield360.evaluate_rule()`

Parameter	Type	Required	Description
`url`	`str`	No	Shield360 dashboard URL
`api_key`	`str`	No	API key for authentication
`entity_type`	`str`	Yes	`"context"`, `"prompt"`, or `"evaluation"`
`fields`	`dict`	Yes	Trace attributes to match against rules
`include_entity_data`	`bool`	No	Include full entity data in response. Default: `False`
`entity_inputs`	`dict`	No	Inputs for entity resolution (e.g. prompt variables)

TypeScript - `Shield360.evaluateRule()`

Parameter	Type	Required	Description
`url`	`string`	No	Shield360 dashboard URL
`apiKey`	`string`	No	API key for authentication
`entityType`	`'context'`, `'prompt'`, or `'evaluation'`	Yes	Entity type to match
`fields`	Object of string/number/boolean values	Yes	Trace attributes to match
`includeEntityData`	`boolean`	No	Include full entity data. Default: `false`
`entityInputs`	Object	No	Inputs for entity resolution

Go - `shield360.EvaluateRule()`

Field	Type	Required	Description
`URL`	`string`	No	Shield360 dashboard URL
`APIKey`	`string`	No	API key for authentication
`EntityType`	`RuleEntityType`	Yes	`RuleEntityContext`, `RuleEntityPrompt`, or `RuleEntityEvaluation`
`Fields`	`map[string]interface`	Yes	Trace attributes to match
`IncludeEntityData`	`bool`	No	Include full entity data. Default: `false`
`EntityInputs`	`map[string]interface`	No	Inputs for entity resolution
`Timeout`	`time.Duration`	No	HTTP timeout. Default: `30s`

Response Format

All SDKs return the same response structure:

{
  "matchingRuleIds": ["rule-uuid-1", "rule-uuid-2"],
  "entities": [
    {
      "rule_id": "rule-uuid-1",
      "entity_type": "context",
      "entity_id": "ctx-uuid-1"
    }
  ],
  "entity_data": {
    "context:ctx-uuid-1": {
      "id": "ctx-uuid-1",
      "name": "Premium System Prompt",
      "content": "You are a helpful AI assistant..."
    }
  }
}

Field	Description
`matchingRuleIds`	Array of rule IDs whose conditions matched the input fields
`entities`	Array of linked entities from matching rules, filtered by `entity_type`
`entity_data`	Full entity records, keyed as `type:id`. Only present when `include_entity_data` is `true`

Error Handling

Returns None on any error (network, auth, server). Check for None before using the result.

result = shield360.evaluate_rule(entity_type="context", fields={"key": "val"})
if result is None:
    print("Rule evaluation failed - check logs for details")

Returns { err: string } on error. Use a type guard to check.

const result = await Shield360.evaluateRule({ entityType: 'context', fields: {} });
if ('err' in result) {
  console.error('Rule evaluation failed:', result.err);
}

Returns error as the second value (idiomatic Go).

result, err := shield360.EvaluateRule(ctx, opts)
if err != nil {
    log.Printf("Rule evaluation failed: %v", err)
}

Rule Engine Guide

Learn how to create rules, add conditions, and link entities in the Shield360 UI

API Reference

Full OpenAPI reference for the evaluate endpoint