Audit Agent
The backend agent that parses a document, runs deterministic brand-compliance rules plus an AI review against your own guidelines, and produces a reviewable, annotatable findings report. It currently powers PPTX Auditor and PDF Auditor, and is built to add new document/media formats as auditors without touching the shared pipeline.
What Is the Audit Agent?
The Audit Agent is one of TotalApp's Core Agents. Its single responsibility is taking an uploaded file — a document, spreadsheet, image, or design asset — and checking it against a set of brand/compliance guidelines, combining two complementary review passes: a fast deterministic rule pass, and a slower AI semantic review pass.
PPTX Auditor and PDF Auditor are the two auditors live today, and both are thin screens built on top of the exact same agent — the parsing/rule/review pipeline, the job queue, and the tenant-scoped report storage are all shared. Only the file parser differs per format (PPTX uses the file's own XML via a ZIP reader; PDF uses text extraction), since each format needs different code to turn "a file" into the same normalized internal shape the rest of the agent understands. This parser-only boundary is deliberate — see Format Roadmap below for the auditors planned to follow the same pattern.
In one sentence
Upload a file and your brand guidelines — the Audit Agent returns a per-page/per-slide/per-item list of findings (draft markers, missing confidentiality statements, tone/terminology issues, style violations) that a human reviews, accepts, dismisses, and annotates before saving a report.
How It Works — Parse, Deterministic Rules, AI Review
Every Audit Agent analysis runs the same three-phase pipeline, regardless of which format triggered it:
| Phase | What happens |
|---|---|
| 1. Parse | The uploaded file is normalized into a common internal shape — a list of slides/pages, each with a title and one or more text shapes. PPTX parsing reads the presentation's own XML (shape names, placeholder types, font sizes, colors, and position, all extracted from the file's ZIP structure). PDF parsing extracts each page's text via a text-extraction library — PDFs don't expose the same per-run styling metadata a PPTX file does, so PDF findings are text-based only (see the limitations note below). |
| 2. Deterministic Rules | A fixed set of regex/heuristic checks runs against every slide or page — no AI call involved, instant and free. Checks include: a "DRAFT" marker, banned abbreviations, non-standard fonts/colors (PPTX only), title punctuation/casing/length, a missing confidentiality statement, bullet-line punctuation, and empty slides/pages. See the full rule table below. |
| 3. AI Semantic Review | The parsed content plus your guidelines (pasted or uploaded as a `.md` file) are sent to the configured AI provider (Anthropic API or Claude CLI, depending on the tenant's Writer Engine setting) with a strict instruction to return only structured JSON violations — tone, terminology, and guideline-specific issues the regex rules can't catch. |
Why run both passes?
Deterministic rules are instant, free, and 100% reliable for the mechanical checks they cover (no AI hallucination risk), but they can't judge tone, terminology, or guideline-specific nuance. The AI pass fills that gap. Running both means the fast, cheap checks never wait on a network round-trip, while the qualitative checks still get done.
One Engine, Many Auditors
PPTX Auditor and PDF Auditor are not two separate implementations that happen to look alike — they are two thin front-ends over one shared server module, and the agent is deliberately structured so that a brand-new auditor (a new format, a new category of asset) plugs into the same pipeline instead of forking it. The upload/job-polling/persistence infrastructure, the deterministic-rule runner, and the AI review call are all written once and reused by every auditor; only the file parser and its rule set are format-specific.
| Component | Shared across auditors? | Notes |
|---|---|---|
| File parser | No — format-specific | Each format gets its own parser (PPTX reads the file's own XML; PDF uses text extraction) that produces the same normalized internal shape — a list of pages/slides/items with content and, where available, style metadata. Adding a new auditor means writing one new parser, not a new pipeline. |
| Deterministic rule set | Partially — format-aware | Text-based rules (banned words, missing statements, punctuation, casing) run identically across every format. Rules that depend on metadata a format doesn't expose (font/color for PDF, cell formulas for images, etc.) simply don't apply to that format — an expected limitation, not a bug, and the same pattern that already applies today between PPTX and PDF. |
| AI review call | Yes | Same prompt-building logic, same provider routing, same response parsing, for every auditor — only the guidelines and the parsed content passed into the prompt change. |
| Upload / job-status / persistence handlers | Yes | One generic handler set, parameterized by a small per-format config object (file extension, storage filename) — never duplicated per auditor. |
| Review UI (3-panel workstation) | Pattern shared, code duplicated | Every auditor screen uses the same 3-panel layout (item list, content view, findings panel) with Accept/Dismiss and per-finding notes — built as parallel screens rather than one shared component, so each can evolve its own format-specific terminology (e.g. "slide" vs "page" vs "cell"). |
What "adding a new auditor" actually means
Because the job queue, AI call, and persistence layer are already generic, shipping a new auditor is scoped to: (1) a new file parser that normalizes the format into the shared internal shape, (2) any format-specific deterministic rules that make sense for that format, and (3) a new review screen following the existing 3-panel pattern. Nothing in the shared engine needs to change.
Format Roadmap
PPTX Auditor and PDF Auditor are live today. The same agent is designed to extend to the following auditors as they ship — each one reuses the shared pipeline above and only adds its own parser and rule set:
| Auditor | Input Format | What It Reviews | Status |
|---|---|---|---|
| PPTX Auditor | .pptx |
Brand fonts/colors, title formatting, confidentiality statements, terminology, tone. | Live |
| PDF Auditor | .pdf |
Terminology, confidentiality statements, title formatting, tone (text-based rules only). | Live |
| DOCX / Word Auditor | .docx |
Corporate style rules, font styles, banned words, heading hierarchy, table and structure compliance. | Planned |
| XLSX / Spreadsheet Auditor | .xlsx, .csv |
Financial reporting rules, broken formulas, cells that must not be left blank, brand-consistent table formatting. | Planned |
| Brand & Image Auditor | .png, .jpg |
Correct logo usage, contrast ratios, whether an image looks AI-generated (text-to-image), watermark checks. | Planned |
| Social Media / Ad Banner Auditor | Figma link, .psd, .png |
Text density on ad creative (e.g. the classic "20% text" rule), presence of a clear call-to-action button. | Planned |
| Accessibility (a11y) Auditor | .pdf, .html |
Screen-reader compatibility, missing alt-text, correct heading hierarchy (H1, H2, …). |
Planned |
| Legal & Compliance Auditor | Any text-bearing format | NDA/privacy-agreement compliance, banned terminology, presence of required up-to-date regulatory clauses. | Planned |
Roadmap, not a commitment date
The auditors marked "Planned" describe the direction the Audit Agent's format coverage is heading, not a scheduled release. Each one becomes a straightforward addition once prioritized, precisely because the shared pipeline (job queue, AI review, persistence, review UI pattern) already exists and doesn't need to be rebuilt per format.
Deterministic Rule Set (PPTX & PDF)
These checks run instantly, with no AI call, on every slide or page for the two auditors live today. Future auditors (see the roadmap above) will each define their own rule set suited to their format — a spreadsheet auditor needs formula/blank-cell checks, an image auditor needs contrast/logo checks, and so on — reusing the same rule-runner mechanism, not this specific rule list.
| Rule | Severity | What it catches | PDF-compatible? |
|---|---|---|---|
| Draft marker | High | The literal word "DRAFT" anywhere in the content. | Yes |
| Banned abbreviation | High | Disallowed shorthand that should be spelled out in full. | Yes |
| Non-standard font | Medium | A font outside the approved brand list. | No — PDF text extraction has no per-run font metadata |
| Color palette | Medium | A color hex value outside the approved brand palette. | No — same limitation as fonts |
| Title font size | Medium | Title text not set to the required point size. | No |
| Title position | Medium | Title box displaced from its expected position, suggesting the wrong layout was used. | No — PDF has no shape-position data |
| Title punctuation | Medium | Title ending in a period, exclamation, or question mark. | Yes |
| Title ALL CAPS | Medium | A title written entirely in uppercase. | Yes |
| Title too long | Low | Title length likely to wrap past the expected line count. | Yes |
| Missing confidentiality statement | Low | No confidentiality/proprietary notice found anywhere on the slide/page. | Yes |
| Bullet punctuation | Low | A body bullet line ending in terminal punctuation. | Yes |
| "Percentile" vs "%ile" | Low | The word "Percentile" used where the house style requires the "%ile" abbreviation. | Yes |
| Empty slide/page | Medium | No extractable text content at all on that slide/page. | Yes |
PDF input has fewer applicable rules than PPTX
PDF text extraction does not expose the per-run styling metadata (font name, font size, color, shape position) that a PPTX file's own XML structure provides. As a result, the four style/position rules above simply never fire on PDF input — this is an expected limitation of the format, not a bug. Every text-based rule (the other nine) applies identically to both formats.
Human Review — Accept, Dismiss, Annotate
No finding is applied automatically. Every deterministic and AI-sourced finding is presented to the reviewer in a 3-panel workstation (item list on the left, document content in the center, findings panel on the right) where each one can be:
Accepted
Marked as a confirmed, real issue that needs fixing in the source document.
Dismissed
Marked as a false positive or an intentional exception, and excluded from the final report's active findings.
Annotated
A free-text note can be attached to any individual finding — context for why it was accepted/dismissed, or instructions for whoever fixes the source document. Notes travel with the finding into every export (JSON, PDF report, saved server report).
Once review is complete, the findings (with their Accept/Dismiss state and any notes) can be downloaded as a JSON file, exported as a formatted PDF report (summary of accepted issues only, or the full report including pending items), or saved to tenant-scoped server storage for later reference.
Where the Audit Agent Is Used Today
| Screen | Input format | Category |
|---|---|---|
| PPTX Auditor | PowerPoint (.pptx) |
Audit |
| PDF Auditor | PDF (.pdf) |
Audit |
See the Format Roadmap above for the auditors planned to join this table.
PPTX Auditor
Upload a PowerPoint deck and your brand guidelines to check fonts, colors, title formatting, confidentiality statements, and terminology across every slide. See PPTX Auditor.
PDF Auditor
Upload a PDF document and your brand guidelines to check the same terminology, title, and confidentiality rules across every page — style/position rules that need font or layout metadata are not applicable to this format. See PDF Auditor.
Frequently Asked Questions
.md) file — this is passed to the AI review pass alongside the document content, and you can keep multiple named guideline sets side by side.