npm package: @governed-ai/runtime
Description: Agent-agnostic governance middleware for AI applications. Provides classification, pre/post-interaction governance, tool guarding, trace validation, telemetry, and certification.
Latest version: 1.0.0

# @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

```bash
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.

```typescript
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):
```bash
# Start the governance API server
npx tsx api-example/server.ts
```

**Client side:**
```typescript
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

```typescript
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:

```typescript
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:
```typescript
const report = await governance.certifyAgent({
  domain: "insurance",
  categories: ["safety", "privacy"],
});
```

## Telemetry

Track governance metrics across all queries:

```typescript
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