How Tawa works

This page explains what happens when you submit text and what you get back.

Scans, not jobs

Every SDK call — analyze, scanContext, scanChunk, scanToolCall, scanToolOutput, scanResponse — is a single, synchronous scan: you send text, you get a decision back in the same call. There's no queue to poll and nothing to wait on; each method just tells the pipeline where the text came from (a plain prompt, a RAG chunk, a tool call, ...) so the decision can account for that provenance.

The decision

A decision is a recommendation — Tawa returns its assessment and you decide how to act on it. The result is a ScanResult:

• action: what to enforce: allow or block. The engine can be uncertain, so the gateway turns an engine review into allow or block using your app's setting for that content type before the response is sent (see The review flag). The action you receive is final.
• engineAction: the engine's own label before that step, in ascending severity (production emits allow, review, block, hard_block):
  • allow — looks safe.
  • review: the engine was uncertain.
  • soft_block / block / hard_block: blocking, with increasing certainty.
  • sandbox — consider handling in an isolated or reduced-capability context.
  • ambiguous — inconclusive; use suggestion for a coarse allow/block hint.
  • ood — out-of-distribution; the input didn't resemble anything in either the safe or malicious training data.
• needsReview: true when the engine's action was review, whichever way action was collapsed. Use it to tune your settings or to route the item to a second model. ood does not set it.
• risk: how likely the input is malicious, from 0 to 1, regardless of the verdict. Higher means more likely malicious. null when the response comes from an older service version, or when the input is out of distribution.
• confidence: how sure the engine is of action, from 0 to 1. It equals risk for any flagging action, and 1 - risk for allow, so a confident allow has high confidence and low risk.
• rationale — a human-readable explanation.
• policy — directives from your app's policy rules, if any matched (see below).
• language — language identification detail, null while disabled for your app.
• scoreBreakdown — diagnostic detail behind the decision. Shape varies by which internal decision path fired, so treat it as opaque debug detail rather than a stable schema.

const result = await tawa.analyze(userInput);
const { action, confidence, rationale } = result;

Policy rules

Your app can define rules — evaluated on every scan, additive to (never a replacement for) the built-in detection — that contribute directives to the verdict (e.g. "always block tool X for this app", "flag anything touching sensitive data"). A matched rule's directives land on the result's policy field; enforcing them (e.g. actually withholding a tool call) is your application's responsibility, the same way acting on action is.

Provenance-specific protection

Different content deserves different handling, so each scan method exists for a reason rather than all funneling through one generic call:

• analyze — a plain prompt, before it reaches your LLM.
• scanContext — the fully assembled prompt (system + retrieved context + user turn), immediately before the LLM call.
• scanChunk / scanRetrieval — RAG-retrieved content, before it's assembled into a prompt at all.
• scanToolCall / scanToolOutput — an agent's proposed tool call, and a tool's returned output before it re-enters the agent loop.
• scanResponse — the model's own reply, 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).

See Scanning (or the Python equivalent) for the full reference.

Where it runs

Scans run on Tawa's hosted infrastructure, region-resolved automatically per organization — see Configuration for pointing the SDK at a different base URL (local development, or a private deployment).