Skip to main content

​
Rules Management Guide

Rules let you shape how Simba Intelligence’s AI agents behave—both the Data Source Agent (when creating new data sources) and the Query Agent (when interpreting and answering user questions). A rule is a short, plain‑English instruction that adds governance, tone, context, constraints, or business logic beyond what is inferred from schemas and data source configuration.

​
Overview

​
What Are Rules?

Think of rules as lightweight guardrails or behavioral hints you layer on top of your existing semantic model. They do not replace data source optimization (see the Data Source Optimization Guide), but they help:
  • Emphasize important business definitions
  • Enforce preferred terminology
  • Prevent disallowed insights or perspectives
  • Guide tone, style, or emphasis for generated explanations
  • Remind the AI of contextual constraints (“Never expose raw cost fields unless explicitly asked”)

​
Rule Targets

A rule can apply to:
  • None (Global for Query) – Applies to all user queries across every data source unless overridden by explicit user instruction
  • Specific Data Source – Applies only when querying that data source
  • Data Source Agent – Applies when the AI is creating new data sources via the Data Agent (useful for structural / naming / compliance guidance)
💡 If you choose None, the rule does not constrain creation logic directly—it’s interpreted during natural language querying across any data source. To influence creation, target the Data Source Agent explicitly or define both types of rules.

​
When to Use Rules

Use Rules when you need:
  • Consistent phrasing (e.g., “Use ‘Customer’ instead of ‘Client’ in explanations”)
  • Guardrails (“Do not include speculative forecasting unless user asks for a prediction”)
  • Compliance reinforcement (“Do not surface personally identifiable information (PII) in summaries”)
  • Analytical posture (“Prioritize variance explanations over raw totals when comparing periods”)
  • Data Source creation standards (“Prefer concise, business-readable field labels; expand abbreviations”)

​
Key Concepts

AttributeDescription
NameHuman-readable identifier shown in the Rules list
ContentThe actual instruction (plain English) – required
Data SourceOptional selection; empty = global (query) scope; specific = scoped; agent = creation context (if UI supports explicit agent targeting)
Created AtTimestamp (UTC) when the rule was created
🧩 The UI currently exposes: Name, Content, and Data Source selector with a None option. Selecting none yields a global query rule. Selecting a data source scopes it. (If/when an explicit “Data Source Agent” target option is added, include one rule per structural policy.)

​
How the AI Uses Rule Names

The Rule Name is not just cosmetic. The AI performs lightweight semantic relevance matching using rule names as signals to decide which optional rules to load for a given task context (especially when many global rules exist). A weak or vague name can cause the system to overlook an otherwise useful rule. Implications:
  • Names should summarize intent + domain (“Privacy: Suppress PII” vs “PII Stuff”)
  • Avoid generic labels (“General”, “Style”, “Rule 1”)
  • Prefer consistent prefixes so related rules cluster during relevance scoring
  • If two rules have overlapping names, disambiguate with scope or outcome wording (e.g., “Terminology: Gross vs Net” vs “Terminology: Acronym Expansion”)
Name Structure Template: CATEGORY: Focus – Qualifier Examples:
  • PRIVACY: Suppress PII Fields
  • TERMINOLOGY: Use “Gross Revenue” Label
  • TONE: Executive Summary First
  • STRUCTURE (Creation): Expand Abbreviations
  • COMPARISON: Highlight Drivers Before Totals
Anti‑Patterns:
  • Revenue (too vague)
  • Tone Rule (uninformative)
  • DSAgent (unclear function)
  • AOV (acronym with no context)
🎯 Goal: A reviewer (or the AI) should infer the rule’s purpose without reading its content.

​
Multi-Tenancy and Rule Scope

​
Tenant-Wide Rules vs User Rules

In multi-tenant deployments, rules can have two scopes: User Rules (Personal):
  • Created by individual users for their own use
  • Visible and editable only by the user who created them
  • Applied automatically during queries alongside tenant-wide rules
  • All users can create, edit, and delete their own user rules
Tenant-Wide Rules (Organizational):
  • Created by tenant administrators
  • Automatically applied to all users within the tenant
  • Visible to all users but only editable by tenant administrators
  • Useful for enforcing organization-wide policies, compliance requirements, and consistent business logic

​
Rule Display and Organization

The Rules interface displays rules in two separate sections: For Tenant Administrators:
  • Tenant Rules table at the top - shows all tenant-wide rules with full edit/delete controls
  • User Rules table below - shows your personal rules with full edit/delete controls
For Standard Users:
  • Tenant Rules table at the top - shows tenant-wide rules (read-only, no action buttons)
  • User Rules table below - shows your personal rules with full edit/delete controls
💡 Tip: If you only see one table, there are no tenant-wide rules in your organization. This is normal for non-multi-tenant deployments or tenants without organizational rules.

​
Creating Tenant-Wide Rules (Administrators Only)

Tenant administrators have an additional option when creating rules:
  1. Navigate to Rules and click Create Rule
  2. Fill in Name, Content, and optional Data Source as usual
  3. Check the “Apply across tenant” checkbox
  4. Click Create Rule
The rule immediately becomes visible and active for all users in your tenant. Use cases for tenant-wide rules:
  • Governance: “Do not surface personally identifiable information (PII) in summaries unless explicitly asked”
  • Compliance: “All financial figures must include currency clarification (USD)”
  • Terminology: “Use ‘Customer’ instead of ‘Client’ in all explanations”
  • Data quality: “When comparing periods, prioritize variance drivers before totals”

​
Interaction Between Tenant and User Rules

  • Both tenant-wide rules and user rules are applied during queries
  • Tenant-wide rules cannot be overridden or disabled by standard users
  • User rules work alongside tenant rules to add personal preferences
  • If rules conflict, more specific guidance typically takes precedence
  • Data source-scoped rules (whether tenant-wide or personal) apply when querying that specific source
Example:
  • Tenant-wide rule: “Always clarify currency as USD”
  • User rule: “Begin summaries with top 3 drivers”
  • Result: Both apply - currency is clarified AND summaries prioritize drivers

​
Accessing Rules Management

  1. Navigate to Rules from the user menu in the top-right corner
  2. The Rules interface displays existing rules organized by scope (Tenant Rules and User Rules)
  3. Use the Search box to filter by rule name across both sections
  4. Click Create Rule to add a new rule (user rule by default; tenant administrators can check “Apply across tenant”)

​
Creating a Rule

​
Steps

  1. Click Create Rule
  2. Enter a Rule Name (concise, descriptive)
  3. (Optional) Choose a Data Source from the dropdown:
    • Leave blank = global query rule
    • Select a data source = scoped rule for that source only
  4. Enter Rule Content – write a direct instruction (avoid fluff)
  5. Click Create Rule

​
Content Writing Guidelines

✅ Do:
  • Be explicit: “Always describe currency values in USD unless user specifies another currency.”
  • Use imperative tone: “Prioritize…” “Avoid…” “Never…” “When comparing…”
  • Keep one intent per rule; create multiple rules instead of a long paragraph
  • Reference business terminology exactly as labeled in the data source
❌ Avoid:
  • Vague phrasing: “Be smart about revenue stuff.”
  • Overloaded instructions mixing tone, filtering, formatting in one rule
  • Duplicating what the data source schema already makes obvious

​
Example Rules

NameScopeContent
Revenue TerminologyGlobalUse the term “Gross Revenue” instead of generic “Revenue” when summarizing totals.
Cost VisibilityGlobalDo not include cost or margin fields unless the user explicitly asks for cost, margin, or profitability.
Sales Source ToneSales Performance SourceSummaries should emphasize drivers of change (top 3 product categories and regions) before totals.
Naming StandardsData Source AgentWhen creating data sources, expand abbreviations in labels (e.g., rev_gross_amt → Gross Revenue).
Currency ClarificationSales Performance SourceIf user asks for revenue without specifying currency, clarify that figures are in USD.

​
Editing a Rule

  1. In the Rules table, click the Edit (pencil) icon
  2. Adjust Name, Content, or Data Source
  3. (Tenant administrators only) Toggle the “Apply across tenant” checkbox to change rule scope
  4. Click Save Changes
  5. Confirm success via toast message
✏️ Editing scope (changing from global to specific, or from user to tenant-wide) changes where the rule applies immediately.
Note: Standard users can only edit their own user rules. Tenant-wide rules have no edit buttons for standard users.

​
Deleting a Rule

  1. Click the Delete (trash) icon next to a rule
  2. Confirm in the deletion modal
  3. Rule is permanently removed; behavior reverts accordingly
🛑 This cannot be undone—capture critical governance rules elsewhere (internal documentation / version control).
Note: Standard users can only delete their own user rules. Tenant-wide rules have no delete buttons for standard users. Only tenant administrators can delete tenant-wide rules.

​
Searching and Filtering

Use the search input at the top of the page to filter by Rule Name. (Search currently does not inspect rule content.) For large catalogs of rules, adopt consistent naming prefixes (e.g., GOV:, TONE:, CALC:). Naming Pattern Suggestions:
  • GOV: Data Privacy
  • FORMAT: Currency
  • TONE: Executive Summaries
  • MODEL: Abbreviation Expansion

​
Best Practices

​
Keep Rules Atomic

One rule = one behavioral constraint. Easier to maintain, disable, or refine.

​
Use Hierarchical Intent

  • Rely on data source configuration for structural clarity
  • Use rules for behavioral overlays (tone, selective suppression, explanation priorities)

​
Avoid Rule Overlap

Too many similar or conflicting rules can cause diluted adherence.

​
Optimize Names for AI Selection

Because the AI scores rule names for contextual relevance:
  • Front‑load the category so related rules cluster (PRIVACY:, TONE:, FORMAT:)
  • Use strong action verbs (“Suppress”, “Highlight”, “Use”, “Avoid”, “Explain”)
  • Disambiguate variants (e.g., TERMINOLOGY: Margin vs Markup distinct from TERMINOLOGY: Acronym Expansion)
  • Flag creation-specific rules with a suffix or parenthetical (Creation) or (Data Source Agent) until dedicated targeting UI exists
  • Refactor legacy names that are overly short—rename rather than layering new rules on top
Before / After Examples:
BeforeAfter
Cost RulePRIVACY: Suppress Cost & Margin Unless Asked
Naming StandardsSTRUCTURE (Creation): Expand Abbreviations in Labels
AOVTERMINOLOGY: Use “Average Order Value” (Not AOV)
StyleTONE: Executive Summary Before Detail
Removal Checklist for Weak Names: Delete or rename if the name is: single-word generic, ambiguous acronym, or duplicates another rule with only minor differences.

​
Review Regularly

Quarterly or after major schema/label changes, audit rules for redundancy or obsolescence.

​
Traceability

Maintain a simple changelog externally (date, rule added/retired, rationale). This supports governance and auditability.

​
Common Use Case Patterns

ScenarioExample Rule
Suppress sensitive fieldsDo not surface user email addresses in summaries unless explicitly asked.
Force explanation structureBegin summaries with a variance explanation before totals if a comparison is implied.
Enforce naming conventionsReplace internal acronym “AOV” with “Average Order Value” in all user-facing wording.
Clarify assumptionsIf timeframe not specified, clarify the default time range before answering.
Guide creation styleWhen creating data sources, prefer descriptive business names over system codes.
Limit speculationDo not generate forward-looking forecasts unless user explicitly asks for predictions.

​
Troubleshooting

IssuePossible CauseResolution
Rule appears ignoredToo vague; conflicts with stronger schema signalsRewrite using specific verbs and domain terms
Conflicting behaviorsMultiple rules say opposite thingsConsolidate; keep the clearer one
Hard to locate ruleInconsistent namingAdopt prefixes / naming taxonomy
Overly verbose summariesTone or structure rules encourage narrationTighten rules to focus on insight hierarchy
Sensitive data surfacedNo rule suppressing it; field visibleHide field OR add suppression rule
Can’t edit tenant-wide ruleYou’re a standard user; only admins can editContact your tenant administrator to modify the rule
Can’t see “Apply across tenant” optionYou don’t have tenant administrator permissionsThis feature is only available to tenant administrators

​
Governance Recommendations

  1. Baseline Set: Create a minimal core pack (Privacy, Tone, Terminology, Structural Guidance).
  2. Expansion Policy: Require justification for each new rule (what problem does it solve?).
  3. Sunset Review: Mark candidate rules for removal if unused or superseded.
  4. Change Communication: Notify analysts when global rules change—they may observe shifts in summarization style.

​
FAQ

Q: Do rules change underlying query logic?
A: They influence interpretation and summarization, not raw database access—underlying permissions and schema still govern data availability. Q: Can a scoped rule override a global rule?
A: Yes—scoped rules provide additional, more specific context when that data source is queried. Q: How many rules is too many?
A: If you need more than ~25 active rules, consider consolidation or moving structural guidance into data source configuration. Q: Should I duplicate a global rule inside every data source?
A: No. Use a single global rule unless a source needs a tailored variation. Q: What if users explicitly request something a rule discourages?
A: Well‑written rules typically allow explicit user intent to override (e.g., “unless the user explicitly asks”). Phrase accordingly.

​
Summary & Next Steps

Rules complement (not replace) strong data modeling. Start with a focused set that enforces privacy, terminology, and analytical framing. Expand carefully, review regularly, and retire obsolete rules. Suggested follow-up actions:
  • Draft a core governance ruleset (4–6 rules)
  • Audit for redundant or unclear existing rules
  • Add a naming taxonomy prefix if absent
  • Pair this with the Data Source Optimization checklist for holistic quality control
Ready to add or refine rules? Open the Rules interface and apply these patterns—each clear rule compounds overall AI reliability and user trust.