Entity Governance

Overview

Entity governance lets you apply policies to specific people, organizations, or systems. Instead of one-size-fits-all rules, entities enable governance that adapts to individual context -- a patient's medication list, a customer's contract terms, a vendor's compliance requirements.

Each entity gets a dedicated knowledge base. Upload documents specific to that entity, and Aguardic uses them during RAG-powered evaluation to make governance decisions grounded in real context.

What Entities Represent

An entity is any person, organization, or system that your policies need to consider individually. Aguardic supports the following entity types:

Creating Entities

Via the Dashboard

1. Navigate to Entities in the sidebar.
2. Click Create Entity.
3. Fill in the details:
   • Name -- A human-readable name (e.g., "Jane Doe", "Acme Corp").
   • Type -- Select from the entity types above.
   • Description -- Optional context about the entity.
   • Metadata -- Optional structured data (key-value pairs) for additional context.
4. Click Create.

A dedicated knowledge base is automatically created for the entity. You can start uploading documents immediately.

Entity Knowledge Bases

Every entity gets its own knowledge base -- a collection of documents that are embedded and searchable via vector search. These documents provide context during semantic rule evaluation.

What to Upload

Upload any documents that define what governance rules should apply to this entity:

How It Works

When a semantic rule runs, it can query the entity's knowledge base using RAG (Retrieval-Augmented Generation). The rule's prompt is sent to the LLM along with relevant chunks retrieved from the entity's documents via vector search.

For example, if a patient entity has a medication list uploaded and a semantic rule asks "Does this recommendation conflict with the patient's current medications?", the LLM will receive the relevant medication data from the knowledge base and can give an informed answer.

Uploading Documents

1. Open the entity in the dashboard.
2. Navigate to the Knowledge Base tab.
3. Click Upload Document and select a file.
4. The document is processed, chunked, and embedded automatically.

Supported formats include PDF, plain text, Markdown, and common document formats. Large documents are split into chunks for optimal vector search retrieval.

Linking Policies to Entities

Policies can be linked directly to entities, creating entity-specific governance rules. When a policy is linked to an entity, the evaluation engine automatically loads the entity's metadata and searches its knowledge base via RAG during semantic rule evaluation.

To link a policy to an entity:

1. Open the entity in the dashboard.
2. Navigate to the Policies tab.
3. Click Link Policy and select the policy.

This is useful when different entities need different governance rules. For example:

• A high-risk customer might have stricter PII policies than a standard customer.
• A patient on blood thinners needs drug interaction checks that do not apply to other patients.
• A vendor handling PHI needs HIPAA-specific policies that do not apply to other vendors.

Automatic Policy Derivation

Aguardic can automatically generate policies from an entity's context documents. Instead of manually writing rules for each entity, the LLM reads the entity's knowledge base and infers what policies should apply.

Example: Patient Medication List

1. Upload a patient's medication list to their entity knowledge base.
2. Open the entity page and click Derive Policies.
3. Aguardic's LLM reads the medication documents and generates rules such as:
   • "Flag recommendations that conflict with current prescriptions for Warfarin, Metformin, and Lisinopril."
   • "Block dosage suggestions that exceed maximum recommended doses for the patient's current medications."
   • "Warn if the AI recommends discontinuing any current medication without explicit physician approval."

Example: Customer Contract

1. Upload a customer's service agreement to their entity knowledge base.
2. Click Derive Policies.
3. Generated rules might include:
   • "Block responses that promise features or SLAs not included in the customer's current plan."
   • "Warn if the AI shares pricing information that contradicts the customer's contracted rates."
   • "Flag any discussion of contract terms that requires legal review."

Derived policies are created as drafts so you can review and adjust them before activating. You have full control over the generated rules -- edit, remove, or add conditions as needed.

Entity-Aware Evaluation

When a policy is linked to an entity, evaluations using that policy benefit from the entity's context:

1. Knowledge base context -- Semantic rules query the entity's documents via RAG for relevant information during evaluation.
2. Entity metadata -- The entity's type, description, and metadata are available to the LLM during semantic rule evaluation.
3. Audit trail -- Violations are associated with the entity, making it easy to view all governance events for a specific person, organization, or system.

How It Works

The entity context flows through the policy, not through the session or evaluation request. When you link a policy to an entity in the dashboard, the evaluation engine automatically:

1. Loads the entity's metadata (name, type, description).
2. Searches the entity's knowledge base via vector search for content relevant to the evaluation input.
3. Provides both to the LLM alongside the semantic rule prompt.

Example: Patient Consultation

A healthcare organization links a "Drug Interaction Check" policy to a patient entity. The patient's knowledge base contains their medication list.

import Aguardic from "@aguardic/sdk";
 
const aguardic = new Aguardic(process.env.AGUARDIC_API_KEY);
 
// Create a session for the consultation
const session = await aguardic.sessions.create({
  externalSessionId: "consult-2025-03-10-001",
  metadata: { department: "cardiology" },
});
 
// Evaluate the AI assistant's response
// The "Drug Interaction Check" policy is linked to the patient entity,
// so the engine automatically loads the patient's medication list via RAG
const result = await aguardic.evaluate({
  sessionId: session.id,
  input: {
    role: "assistant",
    content: "Based on your symptoms, I recommend adding ibuprofen to your regimen.",
  },
  targetKey: "assistant-response",
});
 
if (result.enforcementAction === "BLOCK") {
  // The entity's knowledge base flags this because the patient
  // is on Warfarin, and ibuprofen increases bleeding risk
  console.log("Blocked:", result.violations);
} else {
  console.log("Response approved");
}

In this example, the evaluation would likely be blocked because the patient's medication list (in their knowledge base) includes Warfarin, and a semantic rule derived from that context would flag the ibuprofen recommendation as a dangerous drug interaction.

Best Practices

Next Steps

• Evaluation Sessions -- Group evaluations into multi-step workflows
• Your First Policy -- Create your first governance policy
• Audit Trail -- Track violations per entity
• Core Concepts -- Understand knowledge bases, policies, and evaluations