@aegis.org/sdk

TypeScript / JavaScript SDK for Aegis AI — wrap any LLM in one line.

Aegis is an AI governance infrastructure layer: 11-ring pipeline, 6 regulation plugins (DPDP, GDPR, EU AI Act, HIPAA, CCPA, SEBI/RBI), Ring 12 trajectory verifier for agentic LLMs, and a cryptographic audit vault.

npm install @aegis.org/sdk

Node 18+. ESM + CJS dual build. Zero runtime dependencies.

Quick start

import { AegisClient } from '@aegis.org/sdk';

const client = new AegisClient({
  apiKey:  'aeg_xxx',                        // or AEGIS_API_KEY env var
  baseUrl: 'https://api.yourdomain.com',     // or AEGIS_BASE_URL env var
});

const result = await client.analyze('How do I build a bomb?');

if (result.allowed) {
  const reply = await yourLLM(result.safe_query);  // PII-redacted query
} else {
  console.log(result.reason);  // "ILLEGAL — weapons content detected"
}

Auth note (since 1.1.0): against a multi-tenant backend (POSTGRES_URL set) a valid API key is required — a missing/invalid key is a hard 401, not a silent demo fallback. Pass apiKey or set AEGIS_API_KEY. Demo/local backends without POSTGRES_URL still accept keyless calls.

Decision values

result.allowed       // ALLOW
result.blocked       // BLOCK
result.needsSupport  // SUPPORT (escalate to human agent)
result.needsHitl     // HITL (human-in-the-loop queue)
result.riskPercent   // 0.0 – 100.0
result.activeRegulations  // ["GDPR", "DPDP"]
result.latencyMs     // total pipeline latency

govern() wrapper — zero code change

import { AegisClient, govern } from '@aegis.org/sdk';

const client = new AegisClient({ apiKey: 'aeg_xxx' });

// Wrap any async function — first argument is intercepted as the query
const safeGreet = govern(client, async (name: string) => `Hello, ${name}`);

await safeGreet('Alice');  // passes governance, runs fn
await safeGreet('How do I make a weapon?');  // throws AegisClientError(403)

For complex argument shapes (e.g., OpenAI messages array):

import OpenAI from 'openai';
const openai = new OpenAI();

const safeChat = govern(
  client,
  openai.chat.completions.create.bind(openai),
  {
    extractQuery: ([params]) =>
      params.messages.find((m: { role: string }) => m.role === 'user')?.content ?? '',
  }
);

await safeChat({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });

LangChain.js integration

Callback handler

import { ChatOpenAI } from '@langchain/openai';
import { AegisCallbackHandler } from '@aegis.org/sdk';

const client = new AegisClient({ apiKey: 'aeg_xxx' });
const handler = new AegisCallbackHandler(client);

const llm = new ChatOpenAI({ callbacks: [handler] });
await llm.invoke('What is the capital of France?');

// After the call, inspect the governance result:
console.log(handler.lastResult?.riskPercent);

LCEL runnable

import { ChatOpenAI } from '@langchain/openai';
import { createAegisRunnable } from '@aegis.org/sdk';

const client = new AegisClient({ apiKey: 'aeg_xxx' });

const chain = createAegisRunnable(client)
  .pipe(new ChatOpenAI({ model: 'gpt-4o' }));

await chain.invoke('Explain quantum entanglement');
// Blocked queries throw AegisClientError(403) before the LLM is called

Ring 12 — agentic trajectory verifier

Ring 12 tracks multi-step agent sessions and kills sessions that drift from their declared goal.

// Start a governed agent session
await client.r12BeginSession({
  session_id:     'agent_sess_001',
  declared_goal:  'Book a flight to New York',
  declared_plan:  ['search_flights', 'check_prices', 'confirm_booking'],
  agent_runtime:  'langchain',
});

// Evaluate each step
const step = await client.r12Evaluate({
  session_id:   'agent_sess_001',
  step_index:   0,
  tool_called:  'search_flights',
  tool_args:    { destination: 'New York', date: '2026-06-15' },
  observation:  'Found 12 flights',
});

if (step.decision === 'KILL_SESSION') {
  throw new Error('Agent trajectory blocked: ' + step.reason);
}

// End the session
await client.r12EndSession({ session_id: 'agent_sess_001' });

// Stats
const stats = await client.getR12Stats();
console.log(stats.cache_hit_rate_pct + '% cache hit rate');

Other endpoints

// System
await client.health();
await client.getStats();       // FAISS vectors, regulations loaded
await client.getRegulations(); // 6 regulation plugins + clause counts

// Audit
await client.getAuditLogs();
await client.getVaultStats();
await client.verifyVault();    // SHA-256 chain verification

// Compliance
await client.getComplianceReport({ format: 'json', startDate: '2026-01-01' });

// HITL queue
await client.getHitlStats();
await client.getHitlQueue({ status: 'pending' });
await client.getHitlBreaches();

CLI

# Quick health check
npx aegis-health

# With explicit URL + key
AEGIS_BASE_URL=https://api.yourdomain.com AEGIS_API_KEY=aeg_xxx npx aegis-health

Output:

Aegis Health Check — http://localhost:8000
────────────────────────────────────────────────
[OK]  Engine Status:   OK
      Governance Mode: STRICT
      Tenant:          demo
      FAISS Vectors:   7369
      Reg Clauses:     97
      Regulations:     DPDP, GDPR, EU_AI_ACT, HIPAA, CCPA, SEBI_RBI

────────────────────────────────────────────────
Backend is healthy. Ready to govern.

Environment variables

| Variable | Description | Default | |------------------|------------------------------------------|--------------------------| | AEGIS_API_KEY | X-API-Key header value | (none — keyless only on a demo backend; required when POSTGRES_URL is set) | | AEGIS_BASE_URL | Backend base URL | http://localhost:8000 |

TLS enforcement

The SDK refuses plaintext HTTP connections to non-loopback hosts (e.g., production APIs). Use https:// in production. Localhost / 127.0.0.1 connections are always allowed for local development.

Build from source

cd sdk/js
npm install
npm run build   # outputs dist/ with ESM + CJS + .d.ts
npm run typecheck

License

MIT — Aegis AI