Node.js Content Gates: A Cheap LLM Token-Cost Estimate for User Text, Images, and JSON Schema

#moderation #node #llm #jsonschema

Short answer: for cheap LLM moderation in Node.js, estimate token cost before classifying user text or images, cap the request, and return a small JSON Schema verdict. Count the system prompt, normalized text, image payload estimate, and response ceiling; reject or route anything over budget. The estimate is useful only when you compare it with a labeled eval set and a real traffic sample.

The constraint changes the design. A moderation request is a control-plane decision, not a chat session, so an open-ended answer wastes tokens and creates another parser to maintain. I ship RAG and agent features in Python, and the same rule keeps showing up in production: a notebook prototype that logs token counts is more valuable than a clever prompt that cannot explain its own bill.

What should a Node.js moderation preflight count before classification?

Treat each request as a budget ledger. Input includes the policy prompt, role or message wrappers added by the API, and the user's text. An image has its own representation cost, which depends on the provider's vision encoding and requested detail. Output is a separate ceiling. Do not pretend that a character count is a token count.

For an early estimate, use the tokenizer for the exact model family you intend to call. Keep a second, provider-side count in an offline sampling job when that option exists; the two numbers are a calibration pair, not interchangeable truth. Your ledger should record prompt_tokens, input_image_units (or the provider's equivalent), max_output_tokens, policy revision, and the final usage returned by the call. I've found that this record is also the fastest way to explain a surprising invoice during an incident review, because it ties a request to a policy revision instead of relying on a vague average.

Here is a deliberately boring estimator. It gives the request path a hard stop and leaves the actual billing record to the response metadata.

from dataclasses import dataclass


@dataclass(frozen=True)
class Budget:
    system_tokens: int
    text_tokens: int
    image_units: int
    output_tokens: int

    @property
    def input_tokens(self) -> int:
        return self.system_tokens + self.text_tokens


def admit(budget: Budget, *, max_input_tokens: int, max_image_units: int) -> bool:
    return (
        budget.input_tokens <= max_input_tokens
        and budget.image_units <= max_image_units
        and budget.output_tokens <= 64
    )

That last limit is intentional.

A verdict with a reason can fit in a few dozen output tokens; asking for a paragraph makes cost and latency less predictable. I don't assume the same ceiling works for every language or policy, so I would test it against multilingual and adversarial fixtures before tightening it. If the fixture shows that explanations are not used by reviewers, remove them entirely and keep the schema to the decision fields.

How can text, images, and JSON schema share one moderation decision?

Normalize first, classify second. Strip invisible control characters, normalize Unicode, and enforce a byte limit before tokenization. If text is still too long, keep a documented excerpting policy or send it to a human queue. Silent truncation is dangerous because an abusive phrase can be removed while the harmless introduction remains.

Images need a different gate. Compute a perceptual hash and reuse a prior verdict for an unchanged upload; for a new image, select a fixed resolution and detail level, then log the resulting image-unit estimate. A text-only model should never receive a URL and be assumed to have inspected the pixels. The safe states are explicit: allow, review, or block, with review as the fallback when the image cannot be evaluated.

Make the response a contract. JSON Schema's enum keeps downstream policy finite, while additionalProperties: false prevents an unexpected field from becoming an unreviewed feature.

VERDICT_SCHEMA = {
    "type": "object",
    "additionalProperties": False,
    "required": ["decision", "category"],
    "properties": {
        "decision": {"type": "string", "enum": ["allow", "review", "block"]},
        "category": {
            "type": "string",
            "enum": ["harassment", "sexual", "doxxing", "spam", "none"],
        },
    },
}


def validate_verdict(value: dict) -> dict:
    decision = value.get("decision")
    category = value.get("category")
    if decision not in {"allow", "review", "block"}:
        raise ValueError("invalid decision")
    if category not in {"harassment", "sexual", "doxxing", "spam", "none"}:
        raise ValueError("invalid category")
    if set(value) != {"decision", "category"}:
        raise ValueError("unexpected fields")
    return value

In a Node.js service, the equivalent request uses the provider's JSON-schema response mode and an ordinary HTTP client. Keep that adapter behind an interface so switching model families does not change the policy, cache key, or audit record.

Which failure modes make a “cheap” moderation pass expensive?

The obvious one is a long-tail paste. A mean token count hides it, so size your budget from percentiles and inspect the largest examples. For each large sample, keep the original length, the excerpt that would be sent, and the reason it was routed away; otherwise you cannot tell whether a cheap gate protected the budget by making a useful decision or by deleting the evidence. The next is retry duplication: if a timeout causes the worker to classify and enqueue twice, the second call is a cost with no new information. Derive an idempotency key from content plus policy revision, upsert the verdict, and retry only the network operation.

Prompt injection is another budget risk. User text can ask the classifier to ignore its policy or print an essay. The system instruction should say that content is data, the output ceiling should be small, and schema validation should happen before any side effect. Log rejected responses without storing sensitive raw text in an unrestricted log sink.

Measure four things before copying the pattern: token estimate error against returned usage, false-positive and false-negative rates on a labeled set, p95 decision latency, and the percentage of requests routed to review. A cost dashboard without quality metrics is just a meter on the wrong pipe.

Where does this design stop being a good fit?

The catch is policy ownership. A general chat classifier can express a custom taxonomy, but it does not give you a regulator-ready, versioned safety standard by itself. Stick with a dedicated content-safety service when legal reporting, age assurance, or an auditable severity taxonomy is a requirement. Its fixed categories may be less flexible, yet that constraint is often the feature.

Do not build a model-based gate for tiny traffic just because the per-call estimate looks attractive. A maintained rule set, manual review, or an established moderation endpoint can be the better engineering choice when you cannot fund an eval set and an on-call path. Conversely, a local model may suit sensitive text, but then GPU capacity, model updates, and language coverage become your responsibility.

Images are the sharpest boundary. If your policy is mostly textual and uploads are rare, hash-and-report may be sufficient. If images dominate, test a vision-specific pipeline separately; text token arithmetic will not predict its cost or recall. Your mileage will vary.

A practical rollout sequence

Start in shadow mode: count and classify without changing user-visible outcomes. Compare the proposed verdict with human labels, then tune the excerpt rule and schema while the policy revision is still cheap to change. Promote only after the tail cases are understood.

Next, make review a first-class queue with an expiry and an appeal path. Store the model identifier, policy revision, token estimate, returned usage, and decision, but minimize retained user content. This gives an eval harness something reproducible to replay when a model changes.

Finally, set a per-request and per-tenant budget. When either is exhausted, fail closed to review rather than silently skipping moderation. That behavior is less convenient, and it is much easier to explain to a user than an undocumented hole in the policy.