Scanning

Every scan method hits the same underlying detection pipeline with different provenance — a plain prompt, a retrieved document chunk, a tool call, and so on — and they all return the same ScanResult shape (RAG-family methods add a couple of extra fields; scanRetrieval returns a list plus an aggregate verdict instead).

analyze

The general-purpose entry point. Scans a plain prompt before it reaches your LLM.

const result = await tawa.analyze("Ignore all previous instructions…");

Result

if (result.action === "allow") {
  console.log(`Safe (${result.confidence.toFixed(2)} confidence)`);
} else {
  console.log(`Blocked: ${result.rationale}`);
}

if (result.needsReview) {
  // The engine was uncertain; engineAction holds its own label, e.g. "review".
  console.log(`Flagged for review (engine said ${result.engineAction})`);
}

action is allow or block: the gateway collapses the engine's review using your app's per-content-type setting before the response is sent. engineAction keeps the engine's own label and needsReview marks the uncertain results. See The review flag. Against a gateway that predates these fields, the SDK derives needsReview from action === "review" and action carries the engine's raw label, so keep handling review, soft_block, sandbox, and ambiguous if you support such a gateway.

Options

Every scan method accepts the same options object:

RAG protection

Scan retrieved content before it's assembled into a prompt.

// A single retrieved chunk, before it enters the assembled context.
const chunkResult = await tawa.scanChunk(chunkText, { chunkId: "doc-42#3" });

// The fully assembled prompt (system + retrieved chunks + user turn),
// immediately before the LLM call.
const contextResult = await tawa.scanContext(assembledPrompt);

// An entire retrieved set in one call — a per-chunk verdict plus an
// aggregate.
const { perChunk, aggregate } = await tawa.scanRetrieval(query, [
  { chunkId: "doc-42#1", text: "…" },
  { chunkId: "doc-42#2", text: "…" },
]);

aggregate.flaggedChunkIds; // chunks enforced as block
aggregate.reviewChunkIds;  // chunks the engine flagged, blocked or not

See the RAG protection cookbook for a full walkthrough combining all three.

Agent protection

Inspect a proposed tool call before it executes, and its output before it re-enters the agent loop.

const callResult = await tawa.scanToolCall("run_query", { sql: "SELECT …" });
if (callResult.action !== "allow") {
  // withhold the tool call
}

const outputResult = await tawa.scanToolOutput("run_query", queryResult);

See the Agent protection cookbook for a full walkthrough with both gates and policy directive handling.

Scanning the model's reply

scanResponse scans the model's own reply immediately before it reaches the end user — the same threat family as a tool's output (untrusted-ish content that can carry an injection aimed at the next turn).

const replyResult = await tawa.scanResponse(modelReply);