@pecta/core

In-process quality gates and reputation telemetry for AI agents.

Run a configurable set of gates over every agent output before it reaches the user. Gates are parallel, fail-fast, and bounded by a timeout budget (default 50ms). Telemetry ships to Pecta cloud asynchronously, never on the hot path.

Install

npm install @pecta/core

Quickstart — gate an agent's output

import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.latency({ maxMs: 100 }),
    gates.filesystem(),
    gates.pii(),
  ],
  timeout: 50,
});

const result = await engine.evaluate({
  agent_id: "research-bot-v2",
  tool: "shell.run",
  output: { stdout: "ls -la /tmp" },
  latency_ms: 18,
});

if (!result.passed) {
  // result.gates contains every gate's verdict + reason
  console.error("blocked:", result.gates.filter((g) => !g.passed));
}

RTB / OpenRTB

import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.rtb.tmaxGuard({ bufferMs: 15 }),
    gates.rtb.impidMatch(),
    gates.rtb.adomainVerify(),
    gates.rtb.bidSanity({ maxFloorMultiple: 50 }),
    gates.rtb.audienceSafety(),
    gates.rtb.bcatCompliance(),
  ],
  timeout: 15,
});

const result = await engine.evaluate({
  agent_id: "dsp-bidder-prod",
  input: openRtbRequest,
  output: openRtbResponse,
  tmaxMs: openRtbRequest.tmax,
  startedAt: requestStartMs,
});

Telemetry

import { PectaTelemetry } from "@pecta/core/telemetry";

const telemetry = new PectaTelemetry({
  publishableKey: process.env.PECTA_PUBLISHABLE_KEY!,
  secretKey: process.env.PECTA_SECRET_KEY,
  hmac: true,            // signs every batch with sha256(secretKey, body)
  sampleRate: 0.1,       // ship 10% of evaluations to cloud
});

telemetry.track(result); // never blocks, never throws

process.on("SIGTERM", () => telemetry.shutdown());

Built-in gates

General

• gates.latency({ maxMs }) — fail if ctx.latency_ms exceeds threshold.
• gates.schema(zodSchema) — validate ctx.output against a Zod schema.
• gates.filesystem() — detect rm -rf, path traversal, sensitive directories.
• gates.pii() — flag emails, SSN-shaped strings, phone numbers in output.
• gates.content() — reject empty output and AI refusal phrases.

RTB (under gates.rtb)

• tmaxGuard() — skip downstream gates when the OpenRTB deadline is exhausted.
• impidMatch() — every bid.impid must match a request imp.id.
• adomainVerify() — reject placeholder / malformed adomains.
• bidSanity({ maxFloorMultiple }) — fail bids unrealistically far above the floor.
• audienceSafety() — child-directed inventory must not serve unsafe categories.
• bcatCompliance() — response creative must not appear in request bcat.

Custom gates

const myGate = {
  name: "my.custom",
  run: async (ctx, signal) => {
    if (signal.aborted) return { passed: false, reason: "aborted" };
    // ...your check...
    return { passed: true };
  },
};
const engine = createEngine({ gates: [myGate] });

A gate's run returns { passed: boolean, reason?: string, skipped?: boolean, details?: unknown }. The engine fills in name and latency_ms automatically.

License

Apache-2.0