compliance-flag 0.2.0

AI-assisted Python CLI for drafting SEC Marketing Rule review reports with Anthropic's Opus model.

Compliance Flag

Compliance Flag is an AI-assisted Python CLI that prepares reviewer-ready reports on URLs and local content files a team is authorized to review. It captures the source material, sends the review request to Anthropic's Opus model through the user's Anthropic API key, compares Registered Investment Adviser (RIA) marketing content against bundled SEC regulatory sources, and produces structured findings for qualified compliance, legal, or supervisory review.

The analysis is performed by Anthropic's Opus model, so each report is structured review support, not a substitute for professional judgment. See Intended Use and DISCLAIMER.md.

---

Project Links: Website · Documentation · Usage · Rule Boundaries · Regulatory Sources · Roadmap · Changelog · Contributing · Security · Support

Table of Contents

• Compliance Flag
  • Table of Contents
  • Website
  • Status
  • How It Works
  • Requirements
  • Install
  • Quick Start
  • Usage
  • Output
  • Reading a Report
  • Configuration
  • Exit Codes
  • Intended Use
  • Regulatory Scope
  • Development
  • Contributing
  • Security
  • Maintainer
  • License
  • Disclaimer

Website

The project website is complianceflag.com. It provides a plain-language overview for compliance reviewers and technical operators, website-hosted docs, and a sample report:

• Website documentation
• Sample report
• Project status

Status

Compliance Flag is moving from alpha to beta. The current package includes:

• compliance-flag scan --file for local .html, .htm, .md, and .txt files
• experimental compliance-flag scan --url support that captures page content before analysis
• structured JSON reports validated against a bundled schema
• HTML report rendering
• saved raw source files and source metadata alongside each report
• bundled prompt, schema, and regulatory source assets migrated from the alpha scanner
• default analysis with Anthropic's Opus model through the user's Anthropic API key

See ROADMAP.md for what is planned next.

How It Works

A scan runs four stages:

1. Input capture — --file reads a supported local file; --url fetches a page with httpx, applies a Content-Type allowlist, and saves the raw bytes.
2. Analysis — the captured document and bundled SEC regulatory sources are sent to Anthropic's Opus model with a versioned prompt and JSON schema.
3. Validation — the model response is parsed and validated against the bundled report schema; invalid output fails the scan.
4. Rendering — the validated report is written as JSON, rendered to HTML, and accompanied by the raw source and source metadata.

The source material is always preserved alongside the report so a reviewer can verify findings against exactly what was analyzed.

Requirements

• Python 3.10+ (CPython 3.10, 3.11, 3.12, 3.13, 3.14 are tested)
• An Anthropic API key for Opus model calls
• Network access for --url scans and for model calls

Install

From PyPI:

pip install compliance-flag

From source (latest main):

pip install git+https://github.com/quillmark-open-source/compliance-flag.git

Set your Anthropic API key:

export ANTHROPIC_API_KEY="..."

Quick Start

export ANTHROPIC_API_KEY="..."
compliance-flag scan --file tests/fixtures/example-blog-post.html

A sample report generated from that fixture is committed under examples/reports/ so you can inspect the output format without running a scan.

The API key is a credential from Anthropic, not from Compliance Flag. Create one in the Anthropic Console API keys page after setting up an Anthropic API account. When a scan runs, the CLI sends the captured source content and bundled regulatory context to Anthropic's Opus model through this key so the model can draft the report findings. Anthropic API usage may be billed through the account that owns the key.

Usage

compliance-flag scan (--file PATH | --url URL) [--out DIR] [--model NAME]

Scan a local file:

compliance-flag scan --file page.html

Scan a URL you are authorized to review:

compliance-flag scan --url https://example.com

Authorized URL scans can include intranet, localhost, or firewall-restricted resources when the scanner is run in an environment allowed to reach them.

Write output to a specific directory:

compliance-flag scan --file page.html --out reports/example

Override the Opus model only when you have a specific reason to test another Anthropic model. The package default is claude-opus-4-8, and non-default models may produce reports that fail schema validation:

compliance-flag scan --file page.html --model claude-sonnet-4-6

Print version or help:

compliance-flag --version
compliance-flag scan --help

More detail in docs/usage.md.

Output

Each scan writes four artifacts to the output directory (default reports/):

File	Purpose
scan-*.json	Structured report, validated against the bundled schema
scan-*.html	Human-readable rendering of the same report
scan-*.source.<ext>	Raw captured source exactly as analyzed
scan-*.source-meta.json	Capture metadata (source URL, content type, status code, saved filename)

Local file scans preserve the input file extension. URL scans choose the source extension from a conservative Content-Type allowlist (text/plain → .txt, text/markdown → .md, JSON/XML media types → .json/.xml). HTML captures and unknown types are saved as .html.txt so the untrusted page is not opened directly as HTML by a double-click.

Reading a Report

A report is meant to be triaged top-down. The JSON structure mirrors the HTML rendering:

• executive_summary — a plain-language overview of what was reviewed and the headline conclusions.
• summary.by_severity — counts at critical, high, medium, low. Start with the highest severity present.
• summary.by_category — counts grouped by regulatory category (e.g. general_prohibitions, recordkeeping, form_adv).
• findings[] — one entry per potential issue. Each finding includes:
  • rule — the primary SEC citation, rule name, and a short description.
  • related_rules — adjacent provisions a reviewer should consider.
  • source — where in the captured material the finding came from.
  • content.excerpt + content.context — the quoted text and the surrounding rationale.
  • violation.explanation — why the model flagged it.
  • violation.remediation — a summary, ordered steps, and optional suggested_language to consider.
• disclaimer — the standing notice that findings are not legal conclusions.

A reviewer is expected to:

1. Open the HTML report (or the JSON if integrating with another system).
2. Confirm each excerpt against scan-*.source.<ext> to verify the model quoted the document accurately.
3. Apply professional judgment to accept, modify, or reject each finding. The CLI does not decide compliance.

For an annotated end-to-end example, see examples/reports/example-blog-post-report.json and its HTML companion.

Configuration

Variable	Purpose
ANTHROPIC_API_KEY	Required. Authenticates calls to the Anthropic API for Opus model analysis.

Flag	Default	Purpose
--file	—	Local file path (.html, .htm, .md, .txt). Mutually exclusive with --url.
--url	—	Authorized URL to fetch and scan. Mutually exclusive with --file.
--out	reports	Output directory for the four scan artifacts.
--model	claude-opus-4-8	Override the Opus model used for analysis. Experimental — the override must support adaptive thinking and structured outputs (Opus 4.6+, Sonnet 4.6, Fable 5); older models are rejected by the API, and non-default models may produce output that fails schema validation.

Exit Codes

Code	Meaning
0	Scan completed and the report validated against the schema
1	Scan failed (input, network, API, or schema-validation error; details on stderr)
130	Cancelled by the user (Ctrl-C)

A non-zero exit does not indicate a compliance finding — findings are reported inside the JSON/HTML output regardless of severity.

Intended Use

Compliance Flag is a review-support tool. It is not a compliance approval system, legal reviewer, or substitute for qualified professional judgment.

Only use Compliance Flag on websites, files, pages, or other content that you own, control, administer, or have explicit permission to assess. Do not run URL scans against third-party websites without authorization. See docs/rule-boundaries.md.

Regulatory Scope

The initial focus is SEC Rule 275.206(4)-1, Investment Adviser Marketing. Related SEC sources (e.g. § 275.204-2 books-and-records, Part 279 Form ADV) are used as supporting context where appropriate.

Bundled regulatory source provenance, retrieval dates, and "current-as-of" notes are tracked in docs/regulatory-sources.md. Treat bundled sources as point-in-time copies — verify against the authoritative source (eCFR, SEC.gov) for any consequential review.

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Common tasks:

pytest              # run the test suite
ruff check .        # lint
python -m build     # build sdist + wheel into dist/

The package layout is src/compliance_flag/:

• cli.py — argument parsing and the scan entry point
• input/ — file and URL capture
• scanner.py — model orchestration
• prompts.py, resources.py, rules.py — bundled prompt, schema, and regulatory assets
• reports/ — JSON storage and HTML rendering
• providers/ — Anthropic API integration

See AGENTS.md for guidance specific to AI-assisted contributions.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening an issue or pull request. Bug reports, regulatory-source corrections, and additional test fixtures are particularly valuable at this stage.

Security

Do not file security issues in the issue tracker. Report vulnerabilities per SECURITY.md.

Maintainer

Compliance Flag is a Quillmark Open Source project maintained by Quillmark LLC. General support channels are listed in SUPPORT.md.

License

Apache-2.0. See LICENSE and NOTICE.

Disclaimer

See DISCLAIMER.md.