@governed-ai/runtime

Agent-agnostic governance middleware for AI applications. Provides classification, pre/post-interaction governance, tool guarding, trace validation, telemetry, and certification — embeddable in any AI agent across any domain (health, finance, insurance, etc.).

Installation

npm install @governed-ai/runtime

Usage

There are two ways to use the governance runtime:

Option A: In-Process (Library Mode)

Import the orchestrator directly and run governance within your application process. You supply your own LLM callback — governance never imports an LLM provider.

import {
  runGovernance,
  DomainRegistry,
  QueryClassifier,
  PreInteractionGovernance,
  PostInteractionGovernance,
  ResponseNormalizer,
  GovernanceLogger,
  InteractionStateManager,
  ToolGuard,
  TraceValidator,
  type GovernancePipelineConfig,
  type GovernanceLLMCall,
} from "@governed-ai/runtime";

// 1. Set up the domain registry (built-in: health, finance, insurance)
const domainRegistry = new DomainRegistry("insurance");
const domainConfig = domainRegistry.getDomain("insurance");

// 2. Wire up the pipeline components
const pipelineConfig: GovernancePipelineConfig = {
  queryClassifier: new QueryClassifier(),
  preInteractionGovernance: new PreInteractionGovernance(
    new QueryClassifier(),
    yourEntityRepository,    // your domain's entity lookup
    yourEntityResolver,      // your domain's entity resolver
    domainConfig.policyEngine,
    domainConfig.entityRules,
  ),
  postInteractionGovernance: new PostInteractionGovernance(),
  responseNormalizer: new ResponseNormalizer(),
  governanceLogger: new GovernanceLogger(),
  stateManager: new InteractionStateManager(),
  toolGuard: new ToolGuard(),
  traceValidator: new TraceValidator(),
};

// 3. Define your LLM callback
const myLLMCall: GovernanceLLMCall = async (query, context) => {
  const result = await yourLLMProvider.generate(query, context);
  return {
    response: result.text,
    confidence: result.confidence,
    reasoning: result.reasoning,
    evidence: result.sources,
    missingData: result.gaps,
    confidenceLabel: result.confidenceLabel,
  };
};

// 4. Run governance
const result = await runGovernance(
  "What is my claim status?",
  { sessionPatientId: "policyholder-123" },
  myLLMCall,
  pipelineConfig,
  "insurance",
  "session-abc",
);

if (result.blocked) {
  console.log("Blocked:", result.blockedReason);
} else {
  console.log("Response:", result.finalResponse);
}

Option B: HTTP Service (SDK Mode)

Deploy the governance runtime as a standalone API service, then use the lightweight SDK from any application.

Server side (see api-example/server.ts for a full reference implementation):

# Start the governance API server
npx tsx api-example/server.ts

Client side:

import { createGovernance } from "@governed-ai/runtime/sdk";

const governance = createGovernance({
  baseUrl: "https://your-governance-service.example.com",
});

const result = await governance.run(
  "What is my deductible?",
  { sessionPatientId: "policyholder-456" },
  "insurance",
  "session-xyz",
);

if (result.status === "blocked") {
  console.log("Blocked:", result.blockedReason);
} else {
  console.log("Response:", result.answer);
}

Built-in Domains

The package ships with policy definitions for three domains:

| Domain | Policy File | Entity Type | |--------|------------|-------------| | health | domains/health/policy.yaml | Patient | | finance | domains/finance/policy.yaml | Client | | insurance | domains/insurance/policy.yaml | Policyholder |

Each domain defines blocked query types, privacy rules, and safety rules in its YAML policy file.

Registering Custom Domains

import {
  DomainRegistry,
  PolicyEngine,
  type DomainEntityRules,
} from "@governed-ai/runtime";

const registry = new DomainRegistry("health");

// Register a custom domain with a policy definition object
registry.registerDomain("legal", {
  policyEngine: new PolicyEngine({
    domain: "legal",
    version: "1.0",
    blocked_query_types: {
      legal_advice: {
        action: "block",
        response: "I cannot provide legal advice.",
      },
    },
    privacy_rules: [
      { id: "client_privilege", description: "Protect attorney-client privilege", severity: "critical" },
    ],
    safety_rules: [
      { id: "no_legal_opinion", description: "Do not issue legal opinions", severity: "critical" },
    ],
  }),
  entityRules: {
    domain: "legal",
    entityLabel: "client",
    entityLabelPlural: "clients",
    // ... other entity rules
  } as DomainEntityRules,
});

Certification

Run the built-in UAT certification suite to validate your agent's governance compliance:

import { CertificationTestRunner } from "@governed-ai/runtime";

const runner = new CertificationTestRunner();
const report = await runner.run(myLLMCall, pipelineConfig, {
  domain: "insurance",
  categories: ["safety", "privacy", "tool_governance"],
});

console.log(`Pass rate: ${report.passRate * 100}%`);
console.log(`Verdict: ${report.verdict}`);
// "certified" | "conditional" | "failed"

Or via the SDK:

const report = await governance.certifyAgent({
  domain: "insurance",
  categories: ["safety", "privacy"],
});

Telemetry

Track governance metrics across all queries:

import { GovernanceMetricsAggregator, GovernanceLogger } from "@governed-ai/runtime";

const metrics = new GovernanceMetricsAggregator();
const logger = new GovernanceLogger(metrics);

// Use this logger in your pipeline config
// Later, retrieve metrics:
const stats = metrics.getMetrics();
console.log(`Total queries: ${stats.totalQueries}`);
console.log(`Blocked: ${stats.blockedQueries}`);

Pipeline Stages

Every query passes through these stages in order:

1. Session Init — Create/resume session state
2. Classify — Identify query type and intent
3. Pre-Interaction — Check against domain policy (blocked types, entity validation)
4. Tool Guard — Validate any tool calls (PII access, destructive ops, bulk limits)
5. LLM Call — Your LLM generates a response
6. Trace Validation — Check reasoning for hallucinations, overconfidence, circular logic
7. Post-Interaction — Validate response safety and accuracy
8. Normalize — Add caveats, structure evidence, format response
9. Log & Persist — Record decision and update session state

Any stage can block the query, returning a safe fallback response with the blockedStage and blockedReason fields set.

API Reference

Exports

| Export | Description | |--------|-------------| | runGovernance | Core orchestrator function | | createGovernance / governance | SDK client (HTTP mode) | | DomainRegistry | Domain policy registry | | PolicyEngine | YAML policy loader/evaluator | | QueryClassifier | Query intent classifier | | PreInteractionGovernance | Pre-interaction policy checks | | PostInteractionGovernance | Post-interaction safety checks | | ResponseNormalizer | Response formatting and caveats | | GovernanceLogger | Governance decision logger | | GovernanceMetricsAggregator | Telemetry metrics collector | | InteractionStateManager | Session state tracker | | ToolGuard | Tool call validator | | TraceValidator | Reasoning trace validator | | CertificationTestRunner | UAT certification runner |

License

MIT