PyGuard

Features

A reference for every feature PyGuard ships in the beta release. Where a feature involves a flow, the workflows page has the matching diagram.

Generate a fraud intelligence report

The primary feature. PyGuard reads the flagged transaction dataset already loaded into the backend, coordinates the fraud sub-agents, and produces a formatted PDF report with:

  • A cover page with headline metrics.
  • A Key Metrics table.
  • An Executive Summary in three to five bullets.
  • A pattern analysis grouped by risk tier (Critical, High, Moderate).
  • A Risk Assessment.
  • A prioritised Recommended Actions section (IMMEDIATE, SHORT-TERM, MEDIUM-TERM).
  • A Data Appendix with the numbers supporting the analysis.

The PDF, the LaTeX source, the chart PNGs, and a metadata.json are written to backend/reports/fraud_report_<timestamp>/. A fraud_reports row is inserted keyed by the Slack thread.

Ask questions about a report in the thread

Reply inside the thread where the PDF was uploaded. The Phase 0 router detects the matching fraud_reports row, runs a lightweight classifier, and delegates to ReportQAAgent when the message is a question.

The Q&A agent has four read-only tools:

  • read_report_sections — the narrative sections captured at generation.
  • read_report_tex — the full LaTeX source, optionally section-scoped.
  • read_data_snapshot — the fraud summary frozen at generation time.
  • read_report_metadata — bundle name, version, available sections.

It also re-binds the eight FraudDataAnalyst function tools so it can answer questions that need fresh numbers (get_fraud_summary, get_flagged_transactions, get_pattern_analysis, etc.). The answer is posted as plain text in the thread. No new PDF is uploaded.

Request targeted LaTeX edits

If the follow-up is an edit ("rewrite the executive summary", "add a section on mobile fraud", "tighten recommendation three"), ReportFollowupAgent routes to ReportEditorAgent. The agent is constrained to four structured edit operations:

  • replace_section_body — rewrite a whole section between anchor comments.
  • insert_section_after — add a brand-new anchored section.
  • delete_section — remove an anchored section.
  • replace_text — in-place swap of an unambiguous substring.

The composite apply_edits_and_recompile tool wraps all four with validation, atomic writes, and a backup to history/v{n}/ before anything is written. Tectonic is then invoked (120-second timeout). On failure, the previous tex and PDF are restored before PyGuard replies.

Version history and rollback

Every successful edit leaves the prior bundle intact in history/v{n}/. That means:

  • Every prior version of the PDF is still retrievable on disk.
  • A compile failure automatically restores the previous version without your intervention.
  • If the wording drift on v5 turns out to be worse than v2, you can manually copy v2 back into the bundle root and regenerate the row.

Slack integration

PyGuard uses Slack's Socket Mode client, so the backend never needs to expose a public webhook. The integration supports:

  • Direct messages and channel mentions. Policies are configurable through SLACK_GROUP_POLICY and SLACK_DM_POLICY.
  • Reply threading. When SLACK_REPLY_IN_THREAD=true, every reply lands in a thread under the user's message.
  • PDF uploads via files_upload_v2. Initial reports and edited versions both land in the same thread.
  • Emoji reactions on the user's incoming message so they know PyGuard has started working.

See the setup guide for the bot scopes PyGuard needs.

WhatsApp bridge (optional)

PyGuard/bridge/ is a small Node service that connects to WhatsApp over Baileys and exposes a local WebSocket (port 3001 by default). It is an opt-in surface — you do not need it to use Slack. The bridge is useful if you want to forward alerts to an on-call WhatsApp number or let a non-Slack user trigger a report.

Conversational fallback

If you greet PyGuard or ask a question that is not a rule, action, user management, or fraud query, the Memory Agent routes you to a small conversational responder. The response is one to three plain sentences that describe what PyGuard can do, so you never see a blank or nonsensical reply.

What is deliberately out of scope

  • Detection. PyGuard does not invent fraud signals. It sits on top of the detection you already have.
  • Automated freeze or block. We surface prioritised actions; a human is always the one who executes them.
  • Multi-report-per-thread. One thread maps to one active report. The unique index on slack_thread_ts enforces this.
  • Chart refresh on edit. Edits change the tex content only. Regenerating charts with the latest data is a new-report request.