Servilia for Datahub

Servilia turns DataHub metadata into AI access decisions—allow, approve, or deny—while auditing quality for safer, explainable governance and continuous improvement.

Comment

Servilia for DataHub

Servilia is a metadata-aware governance gateway that turns DataHub context into real-time access decisions for AI agents.

Before a proposed agent tool call executes, Servilia resolves dataset metadata and returns an explainable decision:

  • ALLOW — the action may proceed.
  • REQUIRE_APPROVAL — the action requires human review.
  • DENY — the action is blocked.

Servilia also audits metadata quality, helping governance teams identify catalog gaps before they become runtime risks.

Inspiration

DataHub gives enterprises a powerful foundation for discovering, describing, and governing data through metadata such as classifications, glossary terms, ownership, and lineage. However, metadata is often treated as documentation rather than an active control at the moment an AI agent attempts to access a dataset.

We were inspired by a simple question:

What if DataHub metadata could make the access decision—not just describe the data?

As AI agents increasingly query enterprise datasets and call tools autonomously, static permissions are not enough. An agent needs a decision for each proposed action, based on the current governance context.

Servilia connects DataHub's metadata intelligence to runtime enforcement, creating a bridge between the catalog and the agent execution layer.

What It Does

Servilia sits between AI agents and DataHub-managed datasets.

For every routed gate request, Servilia:

  1. Resolves the requested dataset metadata.
  2. Evaluates the configured governance policy.
  3. Returns ALLOW, REQUIRE_APPROVAL, or DENY.
  4. Explains the decision using the relevant metadata and policy.
  5. Records the gate result for later recovery and audit.

The current MVP uses classification and glossary terms as primary policy signals:

Dataset context Servilia decision
Public analytics ALLOW
Clean internal events ALLOW
Internal dataset with PII REQUIRE_APPROVAL
Confidential salary report REQUIRE_APPROVAL
Restricted security credentials DENY

Servilia applies the most restrictive outcome when a request contains multiple datasets.

Metadata Quality Audit

Servilia includes a deterministic, read-only Metadata Audit Agent that scans the configured catalog for governance gaps, including:

  • Sensitive datasets with missing owners.
  • Underclassified datasets.
  • Empty glossary terms.
  • Sensitive dataset names without matching glossary terms.
  • Classification and glossary inconsistencies.
  • Missing policy coverage for sensitive metadata.

Each finding includes the dataset URN, rule ID, severity, issue, supporting metadata, and a suggested remediation. Suggestions are displayed for governance review and are not automatically applied.

This creates a continuous governance loop:

DataHub metadata
        ↓
Servilia runtime enforcement
        ↓
Explainable audit evidence
        ↓
Human remediation
        ↓
Improved metadata and policy

How We Built It

We built Servilia as a layered system:

  1. Metadata layer — DataHub metadata, with a shared YAML fixture for fast local execution and a live DataHub GMS mode for catalog integration.
  2. Enforcement layer — The Servilia Runtime resolves metadata, evaluates policy, handles approval contexts, applies most-restrictive-wins logic, and persists gate records.
  3. Diagnostics layer — The deterministic Metadata Audit Agent scans catalog metadata and produces structured findings and suggested policy or catalog changes.
  4. Console layer — The Governance Console provides scenario-driven gate evaluation, decision explanations, approval status, activity recovery, and metadata audit results.

The gate API accepts:

  • Agent identity.
  • Tool name.
  • Tool parameters.
  • Dataset URNs.
  • User context.

The response includes:

  • Gate ID.
  • Decision.
  • Human-readable reason.
  • Policy ID.
  • Approval ID when approval is required.
  • Resolved governance metadata.
  • Status information.

The demo supports two metadata modes:

  • YAML mode for a fast, reproducible local demonstration.
  • DataHub GMS mode for live catalog resolution.

The five curated scenarios demonstrate the central behaviour of the system: adding a glossary term such as PII can change an otherwise internal dataset from ALLOW to REQUIRE_APPROVAL.

Challenges We Ran Into

Connecting Metadata to Runtime Decisions

DataHub metadata is rich and flexible, but runtime enforcement requires clear and deterministic policy semantics. We had to define how classifications, glossary terms, and multi-dataset requests should affect a decision.

We implemented explicit MVP rules:

  • Restricted classification results in DENY.
  • Confidential classification results in REQUIRE_APPROVAL.
  • Internal classification combined with an approval glossary term such as PII results in REQUIRE_APPROVAL.
  • Clean public and internal datasets result in ALLOW.
  • Multi-dataset requests use the most restrictive outcome.

Handling Imperfect Metadata

Real catalogs are rarely complete or perfectly consistent. Datasets may be missing owners, have empty glossary terms, or contain names that suggest sensitivity without corresponding classifications.

Instead of assuming that catalog metadata is always correct, we built the Metadata Audit Agent to expose these gaps. Its output is intentionally read-only and reviewable, allowing governance teams to decide how the catalog or policy should be improved.

Supporting Local and Live DataHub Modes

A live DataHub environment is valuable for proving integration, but it introduces setup, service availability, seed-data, and connectivity challenges.

We addressed this with two metadata modes:

  • YAML mode for a fast and reliable local demo.
  • DataHub GMS mode for live catalog resolution.

Both modes use the same governance concepts and curated scenarios, allowing the core demonstration to remain reliable while still proving the integration path.

Designing Approval Without Overbuilding

Human approval is important, but a full enterprise approval inbox, identity integration, notification system, and real-time event stream would be beyond the MVP scope.

Servilia therefore creates an approval context and exposes its status and timeline. Richer approver workflows are planned for future development.

Proving Auditability Accurately

We wanted gate decisions to be recoverable and integrity-checked without overstating what the MVP provides.

Servilia persists gate records with per-action integrity information, while the console presents a compact Activity view for demonstration and recovery. This provides a practical audit path today and a foundation for future append-only or externally anchored audit trails.

Accomplishments That We're Proud Of

  • Built a working governance gateway that connects DataHub metadata to AI agent runtime decisions.
  • Implemented three clear outcomes: ALLOW, REQUIRE_APPROVAL, and DENY.
  • Demonstrated that glossary metadata such as PII can change the result for an otherwise internal dataset.
  • Implemented most-restrictive-wins behaviour for multi-dataset requests.
  • Added a human approval path for sensitive but potentially legitimate actions.
  • Created explainable decisions containing the reason, policy ID, and resolved metadata.
  • Built a recoverable Activity and status experience for gate decisions.
  • Implemented a deterministic Metadata Audit Agent with structured findings.
  • Added suggested policy and catalog remediation without automatically modifying governance configuration.
  • Supported both local YAML metadata and live DataHub GMS integration modes.
  • Kept enforcement and diagnostics separate so audit findings do not unexpectedly alter runtime decisions.
  • Created a judge-friendly console with five escalating scenarios that demonstrate the complete governance story.

What We Learned

Building Servilia taught us that metadata quality is a security dependency. A policy engine can only make reliable decisions when classifications, glossary terms, ownership, and related governance context are trustworthy.

We also learned that human approval is essential for practical governance. A binary allow-or-deny model is too rigid for many legitimate business workflows. REQUIRE_APPROVAL provides a safer middle path for sensitive actions that may still be valid.

Explainability must also be part of the decision API rather than added later as a user-interface feature. Agents, operators, developers, and auditors all need to understand why a decision was made and which metadata supported it.

Another important lesson was that diagnostics and enforcement should be separate. The audit agent can identify catalog weaknesses without unexpectedly changing the outcome of an active request. This separation makes the system safer and easier to reason about.

Finally, we learned that a strong technical demo needs visible proof. The most compelling sequence is not an architecture diagram alone; it is the contrast between:

internal           → ALLOW
internal + PII     → REQUIRE_APPROVAL
restricted         → DENY

What's Next for Servilia for DataHub

Our next steps include:

  • Richer policies combining glossary terms, tool risk, user context, and dataset lineage.
  • Policy rules such as destructive tools combined with PII resulting in stricter decisions.
  • Production identity integration with enterprise SSO and role-based approval.
  • Approver notifications and a dedicated approval inbox.
  • One-click pull requests or controlled application of suggested catalog and policy fixes.
  • More resilient DataHub GMS integration with caching, authentication, and failure handling.
  • Lineage-aware audit rules for widely used datasets and downstream dashboards.
  • Multi-tenant policy packs and organisation-specific governance models.
  • Integration with broader agent orchestration and zero-trust execution workflows.
  • Stronger audit anchoring and verification for production compliance use cases.

Servilia's goal is simple: make DataHub metadata actionable at runtime so AI agents can work with enterprise data while access remains controlled, explainable, approvable, and auditable.

Built With

Share this project:

Updates