SparkGen Guardrail

Manage guardrail rules, sets, and per-agent overrides.

Dynamic Context

Before any action:

1. •Read guardrails/default_guardrails.yaml — current rules and sets
2. •Read config/ai_workflow.yaml — guardrails: section for active sets
3. •List agent overrides: ls guardrails/agents/ 2>/dev/null
4. •If server running: curl -sf http://localhost:8000/v1/guardrails -H "X-API-Key: ${API_KEY:-dev-local-key}"

Actions

Show (/sparkgen-guardrail show)

Display active guardrails:

• •Sets: list all defined sets and which are active
• •Rules per set: name, type (input/output/both), description
• •Agent overrides: which agents have custom guardrail configs
• •Features: PII redaction, jailbreak detection, credential protection status

Add Rule (/sparkgen-guardrail add-rule <set-name> <rule-name>)

Add a new rule to guardrails/default_guardrails.yaml:

- name: <rule-name>
  type: <input|output|both>
  description: "<what this rule checks>"
  action: <block|warn|redact>
  patterns:
    - "<regex pattern>"
  test_cases:
    - input: "<test input that should trigger>"
      expected: <block|warn|redact>
    - input: "<test input that should pass>"
      expected: pass

Then run: python -m app.guardrails.test_runner --defaults guardrails/default_guardrails.yaml

Add Set (/sparkgen-guardrail add-set <set-name>)

Create a new guardrail set in guardrails/default_guardrails.yaml with an initial set of rules. Optionally add it to guardrails.apply_sets in config/ai_workflow.yaml to activate globally.

Test (/sparkgen-guardrail test [input-text])

If server is running:

curl -s -X POST http://localhost:8000/v1/guardrails/test \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY:-dev-local-key}" \
  -d '{"input": "<text to test>"}'

Otherwise run the test runner:

python -m app.guardrails.test_runner --defaults guardrails/default_guardrails.yaml

Validate (/sparkgen-guardrail validate)

python -m app.guardrails.test_runner --defaults guardrails/default_guardrails.yaml

Report: total rules, test cases passed/failed, any YAML errors.

Agent Override (/sparkgen-guardrail agent-override <agent-name> <set-name>)

Update the agent's guardrails.use_sets list in config/ai_workflow.yaml:

agents:
  - name: <agent-name>
    guardrails:
      use_sets:
        - platform_defaults
        - <set-name>  # add this

Optionally create guardrails/agents/<agent-name>.md for agent-specific rule documentation. Run make validate after changes.