{"_id":"@aidex/guardrails","_rev":"2-d38ce6fc2194004d0f81b272da856121","name":"@aidex/guardrails","dist-tags":{"latest":"1.2.0"},"versions":{"1.1.0":{"name":"@aidex/guardrails","version":"1.1.0","keywords":["ai","guardrails","validation","content-safety","provider-agnostic"],"author":{"name":"Sudheer Babu","email":"isudheerbabu.dev@gmail.com"},"license":"MIT","_id":"@aidex/guardrails@1.1.0","maintainers":[{"name":"sudheerbabu","email":"isudheerbabu.dev@gmail.com"}],"homepage":"https://github.com/getaidex/aidex/tree/main/packages/guardrails#readme","bugs":{"url":"https://github.com/getaidex/aidex/issues"},"dist":{"shasum":"6e4bf15b790289b83226cd489d864325a1633eb3","tarball":"https://registry.npmjs.org/@aidex/guardrails/-/guardrails-1.1.0.tgz","fileCount":20,"integrity":"sha512-fy1yKzc1b8PjQhm38QBis8vqWY2hq3vLInwcpk8heooAuXXjlSJLMsrD39OX2IoeewcIc7gygu45xBgr69zG+A==","signatures":[{"sig":"MEYCIQC8yBz3IAF5CRtFegQFKOaRYCLer01HmM+K2Z/uHBw0YQIhAMMmzmfn9S8VTivSANeu3pxskskvwYi2/Mwsay4EuT9k","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59740},"main":"./dist/index.cjs","type":"module","_from":"file:aidex-guardrails-1.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.19.0","pnpm":">=9"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsc -b && tsup","typecheck":"tsc -b --noEmit"},"_npmUser":{"name":"sudheerbabu","email":"isudheerbabu.dev@gmail.com"},"_resolved":"/tmp/def824f9b6217521c5ff55758fde8753/aidex-guardrails-1.1.0.tgz","_integrity":"sha512-fy1yKzc1b8PjQhm38QBis8vqWY2hq3vLInwcpk8heooAuXXjlSJLMsrD39OX2IoeewcIc7gygu45xBgr69zG+A==","repository":{"url":"git+https://github.com/getaidex/aidex.git","type":"git","directory":"packages/guardrails"},"_npmVersion":"10.9.8","description":"Aidex Guardrails — composable, provider-agnostic input/output validators for Aidex Gateway 1.1, including a JSON Schema validation guardrail built on @aidex/providers' canonical validator. No execution, no routing, no credentials.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.2","dependencies":{"@aidex/core":"1.1.0","@aidex/providers":"1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/guardrails_1.1.0_1787417523196_0.5841636444148246","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@aidex/guardrails","version":"1.2.0","description":"Aidex Guardrails — composable, provider-agnostic input/output validators for Aidex Gateway 1.1, including a JSON Schema validation guardrail built on @aidex/providers' canonical validator. No execution, no routing, no credentials.","keywords":["ai","guardrails","validation","content-safety","provider-agnostic"],"license":"MIT","author":"Sudheer Babu <isudheerbabu.dev@gmail.com>","homepage":"https://github.com/getaidex/aidex/tree/main/packages/guardrails#readme","repository":{"type":"git","url":"git+https://github.com/getaidex/aidex.git","directory":"packages/guardrails"},"bugs":{"url":"https://github.com/getaidex/aidex/issues"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"sideEffects":false,"publishConfig":{"access":"public"},"dependencies":{"@aidex/core":"1.2.0","@aidex/providers":"1.2.0"},"engines":{"node":">=20.19.0","pnpm":">=9"},"scripts":{"build":"tsc -b && tsup","typecheck":"tsc -b --noEmit"},"_nodeVersion":"24.13.0","_id":"@aidex/guardrails@1.2.0","dist":{"integrity":"sha512-4dbB61PfNc0gQRyXxlk6JAWyMGWelh2Ny7P+2Bt20qWfP5y1EZyxUJ0o7W7IE6zJbuMk/ooKNDRJQJStX+jWwA==","shasum":"301acaaf11a8e794c5e1a958c61387d4a569b8b7","tarball":"https://registry.npmjs.org/@aidex/guardrails/-/guardrails-1.2.0.tgz","fileCount":20,"unpackedSize":59740,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEdiS5ieLHdNxZ1XuZn7zi81rem2Zc4BIY3EIFzouIqRAiEAhs3fX+6ef82dxY4/gEdFmubEV2KKSxnoSNdTKsm8q04="}]},"_npmUser":{"name":"sudheerbabu","email":"isudheerbabu.dev@gmail.com"},"directories":{},"maintainers":[{"name":"sudheerbabu","email":"isudheerbabu.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/guardrails_1.2.0_1787491712048_0.20856020252760255"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-22T16:52:02.981Z","modified":"2026-08-23T13:28:32.374Z","1.1.0":"2026-08-22T16:52:03.343Z","1.2.0":"2026-08-23T13:28:32.209Z"},"bugs":{"url":"https://github.com/getaidex/aidex/issues"},"author":"Sudheer Babu <isudheerbabu.dev@gmail.com>","license":"MIT","homepage":"https://github.com/getaidex/aidex/tree/main/packages/guardrails#readme","keywords":["ai","guardrails","validation","content-safety","provider-agnostic"],"repository":{"type":"git","url":"git+https://github.com/getaidex/aidex.git","directory":"packages/guardrails"},"description":"Aidex Guardrails — composable, provider-agnostic input/output validators for Aidex Gateway 1.1, including a JSON Schema validation guardrail built on @aidex/providers' canonical validator. No execution, no routing, no credentials.","maintainers":[{"name":"sudheerbabu","email":"isudheerbabu.dev@gmail.com"}],"readme":"# @aidex/guardrails\n\n## Installation\n\n```sh\npnpm add @aidex/guardrails\n```\n\n```sh\nnpm install @aidex/guardrails\n```\n\nAidex Gateway 1.1's composable, provider-agnostic input/output validators —\npart of the approved architecture `Provider capabilities -> Model Catalog\n-> Routing/selection -> Guardrails -> Gateway/execution`. This package owns\nonly the `Guardrail<T>` contract, its composition (`composeGuardrails`), and\na small set of built-in guardrails. It never selects/ranks candidates\n(`@aidex/gateway`'s routing), never executes a request or retries/falls\nback between providers (`@aidex/gateway`'s `GatewayExecutor`), and holds no\nconnections or credentials of any kind.\n\n## Usage\n\n```ts\nimport { composeGuardrails, SizeLimitGuardrail, MimeAllowlistGuardrail } from '@aidex/guardrails';\n\nconst guardrails = [\n  new SizeLimitGuardrail({ maxTotalBytes: 5_000_000 }),\n  new MimeAllowlistGuardrail({ allowedMimeTypes: ['image/png', 'image/jpeg'] }),\n];\n\nconst outcome = await composeGuardrails(guardrails, prompt.content, {\n  executionId: 'exec-1',\n  stage: 'input',\n});\n\nif (outcome.result.decision === 'deny') {\n  // outcome.result.reason / .code — see \"Composition\" below\n}\n```\n\nIn practice, guardrails are almost always configured on `@aidex/gateway`'s\n`GatewayExecutor` (`inputGuardrails`/`outputGuardrails`) rather than called\ndirectly — see that package's README, \"Guardrails.\"\n\n## Available guardrails\n\n- **`SizeLimitGuardrail`** (`{ maxTotalBytes }`) — denies content whose\n  estimated byte size exceeds the configured limit. Text is measured as\n  UTF-8 bytes; inline image/file/audio/video parts by their decoded base64\n  size; url-sourced parts count as 0 (unknowable without an I/O call this\n  package deliberately never makes). Deny code: `content_too_large`.\n- **`MimeAllowlistGuardrail`** (`{ allowedMimeTypes }`) — denies content\n  containing any image/file/audio/video part whose `mimeType` isn't in the\n  allowlist. The whole request is denied, never silently stripped of the\n  disallowed part; text parts have no `mimeType` and are never checked.\n  Deny code: `mime_type_not_allowed`.\n- **`SchemaValidatorGuardrail`** (`{ schema: JsonSchema }`) — validates a\n  provider's raw text output (JSON) against a JSON Schema. The\n  provider-neutral fallback for structured output: wired as an output\n  guardrail, it gives every provider the same guarantee — schema-conformant\n  JSON or a denial with structural diagnostics, never silently coerced or\n  repaired — regardless of whether the dispatched provider has native\n  schema-constrained generation (currently only `GeminiProvider` does).\n  Reuses `@aidex/providers`' `validateAgainstSchema` directly rather than\n  reimplementing JSON Schema validation. Deny codes: `invalid_json`,\n  `schema_validation_failed`.\n\n## Composition\n\n`composeGuardrails(guardrails, subject, context)` runs each guardrail in\norder against `subject`, short-circuiting on the first `deny`:\n\n- **`allow`** — no effect; the next guardrail runs against the same value.\n- **`warn`** — observability-only, collected into `outcome.warnings`, never\n  alters flow.\n- **`transform`** — hands the next guardrail (and the final result) a new\n  value, rather than mutating the original subject in place.\n- **`deny`** — stops composition immediately. `composeGuardrails()` itself\n  never throws — a `deny` is data (`{ decision: 'deny', reason, code? }`)\n  returned in `outcome.result`; deciding what a deny means for the rest of\n  a request (stop it? log it?) is the execution layer's job, not this\n  package's. `@aidex/gateway`'s `GatewayExecutor.executeWithGuardrails()`\n  is that consumer — it throws `GuardrailDeniedError` and emits a\n  `'guardrail'` observability event (`stage`/`code` only, never a\n  guardrail's own free-form `reason`) on deny.\n\n`GuardrailContext` (`{ executionId, stage }`) is passed to every `check()`\ncall — `stage` is `'input'` or `'output'`, matching where in a Gateway\nexecution the guardrail ran.\n\n## Writing your own guardrail\n\n```ts\nimport type { Guardrail, GuardrailResult } from '@aidex/guardrails';\n\nclass MyGuardrail implements Guardrail<Prompt['content']> {\n  readonly name = 'my-guardrail';\n  check(subject: Prompt['content']): GuardrailResult<Prompt['content']> {\n    return { decision: 'allow' };\n  }\n}\n```\n\n`check()` may return a `Promise` — synchronous built-ins don't need it, but\na guardrail doing real I/O (a PII-detection API call, say) isn't forced\nsynchronous.\n\n## Dependency direction\n\n`@aidex/guardrails` depends on `@aidex/core` (the `Guardrail<T>` contract\nis generic, `Prompt`-agnostic) and, narrowly, `@aidex/providers` — only for\n`validateAgainstSchema`/`JsonSchema` (`SchemaValidatorGuardrail`), never a\nvendor SDK or concrete `Provider` class. This is acyclic: `@aidex/providers`\nnever depends on `@aidex/guardrails`.\n","readmeFilename":""}