{"_id":"@aegis.org/sdk","_rev":"2-93dceb565024134a617a2229141b0d6c","name":"@aegis.org/sdk","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@aegis.org/sdk","version":"1.0.0","keywords":["ai-safety","ai-governance","llm","policy","compliance","langchain","typescript"],"author":{"name":"Aegis AI"},"license":"MIT","_id":"@aegis.org/sdk@1.0.0","maintainers":[{"name":"jash123","email":"jaswanthalkur@gmail.com"}],"homepage":"https://aegis-ai.dev","bugs":{"url":"https://github.com/aegis-ai/aegis/issues"},"bin":{"aegis-health":"bin/aegis-health.js"},"dist":{"shasum":"b71724e50b9afa60775bd89f914dc474f1229b52","tarball":"https://registry.npmjs.org/@aegis.org/sdk/-/sdk-1.0.0.tgz","fileCount":25,"integrity":"sha512-XDr+RYGcq5T8WHCGSuDOR8Yg1Q7MmdnOHp7joQ6ov+hHSi2MWx0rjGJQW1dndEAwQLosWQ5PDeGNjD7Se/st5g==","signatures":[{"sig":"MEUCIFqwD29tpn0/lin4gLv225tbF4G5RrBSSwobA72HHlR+AiEA9jjqmkwtvtkHvLhvv1WZhyqP8JsXObY13OxiSFPQ7cQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":162784},"main":"./dist/index.cjs","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.cjs"}},"./shims/openai":{"import":{"types":"./dist/shims/openai.d.mts","default":"./dist/shims/openai.mjs"},"require":{"types":"./dist/shims/openai.d.ts","default":"./dist/shims/openai.cjs"}},"./shims/anthropic":{"import":{"types":"./dist/shims/anthropic.d.mts","default":"./dist/shims/anthropic.mjs"},"require":{"types":"./dist/shims/anthropic.d.ts","default":"./dist/shims/anthropic.cjs"}}},"gitHead":"cf813dacf99f31392a30d9aa0b28af82a6374e79","scripts":{"dev":"tsup --watch","build":"tsup","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"jash123","email":"jaswanthalkur@gmail.com"},"repository":{"url":"git+https://github.com/aegis-ai/aegis.git","type":"git"},"_npmVersion":"11.9.0","description":"Aegis AI governance SDK for JavaScript / TypeScript — wrap any LLM in one line","directories":{},"_nodeVersion":"24.14.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.4.0","@types/node":"^25.9.1"},"peerDependencies":{"openai":">=4.0.0","@langchain/core":">=0.2.0","@anthropic-ai/sdk":">=0.30.0"},"peerDependenciesMeta":{"openai":{"optional":true},"@langchain/core":{"optional":true},"@anthropic-ai/sdk":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1779353198301_0.5883256148058547","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aegis.org/sdk","version":"1.1.0","description":"Aegis AI governance SDK for JavaScript / TypeScript — wrap any LLM in one line","license":"MIT","author":{"name":"Aegis AI"},"homepage":"https://aegis-ai.dev","repository":{"type":"git","url":"git+https://github.com/aegis-ai/aegis.git"},"main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.cjs"}},"./shims/anthropic":{"import":{"types":"./dist/shims/anthropic.d.mts","default":"./dist/shims/anthropic.mjs"},"require":{"types":"./dist/shims/anthropic.d.ts","default":"./dist/shims/anthropic.cjs"}},"./shims/openai":{"import":{"types":"./dist/shims/openai.d.mts","default":"./dist/shims/openai.mjs"},"require":{"types":"./dist/shims/openai.d.ts","default":"./dist/shims/openai.cjs"}}},"bin":{"aegis-health":"bin/aegis-health.js"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"devDependencies":{"@types/node":"^25.9.1","tsup":"^8.3.0","typescript":"^5.4.0"},"peerDependencies":{"@anthropic-ai/sdk":">=0.30.0","@langchain/core":">=0.2.0","openai":">=4.0.0"},"peerDependenciesMeta":{"@anthropic-ai/sdk":{"optional":true},"@langchain/core":{"optional":true},"openai":{"optional":true}},"engines":{"node":">=18"},"keywords":["ai-safety","ai-governance","llm","policy","compliance","langchain","typescript"],"dependencies":{},"gitHead":"6f25349c2795fe8f0173363223d0d5543a55a704","_id":"@aegis.org/sdk@1.1.0","bugs":{"url":"https://github.com/aegis-ai/aegis/issues"},"_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-tyqv+ZNIGSoMbhDjbBeRd0D/CJqJ/QEBKvlmPH2X9I8H1wuhGT29+Cr9ljfAS4gdnIY5Gw64c7nFSk7fSU3xWw==","shasum":"32607b6ecf72598596acdd8291070d0f2bff89fb","tarball":"https://registry.npmjs.org/@aegis.org/sdk/-/sdk-1.1.0.tgz","fileCount":25,"unpackedSize":163166,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFX119eTDyxr32d57nUUpPI+6bP9J6+gKsiB34OWzDj9AiADkBn9gQinodddqN/8GWjhuU7dne7Bw5zt3kCG1yOl5Q=="}]},"_npmUser":{"name":"jash123","email":"jaswanthalkur@gmail.com"},"directories":{},"maintainers":[{"name":"jash123","email":"jaswanthalkur@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.1.0_1780759225317_0.017313446878057803"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T08:46:38.102Z","modified":"2026-06-06T15:20:25.569Z","1.0.0":"2026-05-21T08:46:38.422Z","1.1.0":"2026-06-06T15:20:25.450Z"},"bugs":{"url":"https://github.com/aegis-ai/aegis/issues"},"author":{"name":"Aegis AI"},"license":"MIT","homepage":"https://aegis-ai.dev","keywords":["ai-safety","ai-governance","llm","policy","compliance","langchain","typescript"],"repository":{"type":"git","url":"git+https://github.com/aegis-ai/aegis.git"},"description":"Aegis AI governance SDK for JavaScript / TypeScript — wrap any LLM in one line","maintainers":[{"name":"jash123","email":"jaswanthalkur@gmail.com"}],"readme":"# @aegis.org/sdk\n\nTypeScript / JavaScript SDK for [Aegis AI](https://aegis-ai.dev) — wrap any LLM in one line.\n\nAegis 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.\n\n```\nnpm install @aegis.org/sdk\n```\n\nNode 18+. ESM + CJS dual build. Zero runtime dependencies.\n\n---\n\n## Quick start\n\n```typescript\nimport { AegisClient } from '@aegis.org/sdk';\n\nconst client = new AegisClient({\n  apiKey:  'aeg_xxx',                        // or AEGIS_API_KEY env var\n  baseUrl: 'https://api.yourdomain.com',     // or AEGIS_BASE_URL env var\n});\n\nconst result = await client.analyze('How do I build a bomb?');\n\nif (result.allowed) {\n  const reply = await yourLLM(result.safe_query);  // PII-redacted query\n} else {\n  console.log(result.reason);  // \"ILLEGAL — weapons content detected\"\n}\n```\n\n> **Auth note (since 1.1.0):** against a multi-tenant backend (`POSTGRES_URL`\n> set) a **valid API key is required** — a missing/invalid key is a hard `401`,\n> not a silent demo fallback. Pass `apiKey` or set `AEGIS_API_KEY`. Demo/local\n> backends without `POSTGRES_URL` still accept keyless calls.\n\n### Decision values\n\n```typescript\nresult.allowed       // ALLOW\nresult.blocked       // BLOCK\nresult.needsSupport  // SUPPORT (escalate to human agent)\nresult.needsHitl     // HITL (human-in-the-loop queue)\nresult.riskPercent   // 0.0 – 100.0\nresult.activeRegulations  // [\"GDPR\", \"DPDP\"]\nresult.latencyMs     // total pipeline latency\n```\n\n---\n\n## govern() wrapper — zero code change\n\n```typescript\nimport { AegisClient, govern } from '@aegis.org/sdk';\n\nconst client = new AegisClient({ apiKey: 'aeg_xxx' });\n\n// Wrap any async function — first argument is intercepted as the query\nconst safeGreet = govern(client, async (name: string) => `Hello, ${name}`);\n\nawait safeGreet('Alice');  // passes governance, runs fn\nawait safeGreet('How do I make a weapon?');  // throws AegisClientError(403)\n```\n\nFor complex argument shapes (e.g., OpenAI messages array):\n\n```typescript\nimport OpenAI from 'openai';\nconst openai = new OpenAI();\n\nconst safeChat = govern(\n  client,\n  openai.chat.completions.create.bind(openai),\n  {\n    extractQuery: ([params]) =>\n      params.messages.find((m: { role: string }) => m.role === 'user')?.content ?? '',\n  }\n);\n\nawait safeChat({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });\n```\n\n---\n\n## LangChain.js integration\n\n### Callback handler\n\n```typescript\nimport { ChatOpenAI } from '@langchain/openai';\nimport { AegisCallbackHandler } from '@aegis.org/sdk';\n\nconst client = new AegisClient({ apiKey: 'aeg_xxx' });\nconst handler = new AegisCallbackHandler(client);\n\nconst llm = new ChatOpenAI({ callbacks: [handler] });\nawait llm.invoke('What is the capital of France?');\n\n// After the call, inspect the governance result:\nconsole.log(handler.lastResult?.riskPercent);\n```\n\n### LCEL runnable\n\n```typescript\nimport { ChatOpenAI } from '@langchain/openai';\nimport { createAegisRunnable } from '@aegis.org/sdk';\n\nconst client = new AegisClient({ apiKey: 'aeg_xxx' });\n\nconst chain = createAegisRunnable(client)\n  .pipe(new ChatOpenAI({ model: 'gpt-4o' }));\n\nawait chain.invoke('Explain quantum entanglement');\n// Blocked queries throw AegisClientError(403) before the LLM is called\n```\n\n---\n\n## Ring 12 — agentic trajectory verifier\n\nRing 12 tracks multi-step agent sessions and kills sessions that drift from their declared goal.\n\n```typescript\n// Start a governed agent session\nawait client.r12BeginSession({\n  session_id:     'agent_sess_001',\n  declared_goal:  'Book a flight to New York',\n  declared_plan:  ['search_flights', 'check_prices', 'confirm_booking'],\n  agent_runtime:  'langchain',\n});\n\n// Evaluate each step\nconst step = await client.r12Evaluate({\n  session_id:   'agent_sess_001',\n  step_index:   0,\n  tool_called:  'search_flights',\n  tool_args:    { destination: 'New York', date: '2026-06-15' },\n  observation:  'Found 12 flights',\n});\n\nif (step.decision === 'KILL_SESSION') {\n  throw new Error('Agent trajectory blocked: ' + step.reason);\n}\n\n// End the session\nawait client.r12EndSession({ session_id: 'agent_sess_001' });\n\n// Stats\nconst stats = await client.getR12Stats();\nconsole.log(stats.cache_hit_rate_pct + '% cache hit rate');\n```\n\n---\n\n## Other endpoints\n\n```typescript\n// System\nawait client.health();\nawait client.getStats();       // FAISS vectors, regulations loaded\nawait client.getRegulations(); // 6 regulation plugins + clause counts\n\n// Audit\nawait client.getAuditLogs();\nawait client.getVaultStats();\nawait client.verifyVault();    // SHA-256 chain verification\n\n// Compliance\nawait client.getComplianceReport({ format: 'json', startDate: '2026-01-01' });\n\n// HITL queue\nawait client.getHitlStats();\nawait client.getHitlQueue({ status: 'pending' });\nawait client.getHitlBreaches();\n```\n\n---\n\n## CLI\n\n```bash\n# Quick health check\nnpx aegis-health\n\n# With explicit URL + key\nAEGIS_BASE_URL=https://api.yourdomain.com AEGIS_API_KEY=aeg_xxx npx aegis-health\n```\n\nOutput:\n```\nAegis Health Check — http://localhost:8000\n────────────────────────────────────────────────\n[OK]  Engine Status:   OK\n      Governance Mode: STRICT\n      Tenant:          demo\n      FAISS Vectors:   7369\n      Reg Clauses:     97\n      Regulations:     DPDP, GDPR, EU_AI_ACT, HIPAA, CCPA, SEBI_RBI\n\n────────────────────────────────────────────────\nBackend is healthy. Ready to govern.\n```\n\n---\n\n## Environment variables\n\n| Variable         | Description                              | Default                  |\n|------------------|------------------------------------------|--------------------------|\n| `AEGIS_API_KEY`  | X-API-Key header value                   | (none — keyless only on a demo backend; **required** when `POSTGRES_URL` is set) |\n| `AEGIS_BASE_URL` | Backend base URL                         | `http://localhost:8000`  |\n\n---\n\n## TLS enforcement\n\nThe 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.\n\n---\n\n## Build from source\n\n```bash\ncd sdk/js\nnpm install\nnpm run build   # outputs dist/ with ESM + CJS + .d.ts\nnpm run typecheck\n```\n\n---\n\n## License\n\nMIT — Aegis AI\n","readmeFilename":"README.md"}