faultline-pro

# Faultline — AI Claim Forensics
# https://github.com/nxtg-ai/faultline-pro
# npm: @nxtg/faultline | @nxtg/faultline-api
# Last updated: 2026-04-04 (N-213)

> **The only AI safety CLI not owned by an AI lab.** Forensic verification for AI-generated text. Decomposes AI output into atomic claims, verifies each against live evidence, and maps findings to EU AI Act risk tiers. Provider-agnostic: Gemini, OpenAI, Claude, Perplexity — runtime switching, no code changes.

## What Faultline Does

Faultline answers the question: **"Did the AI lie, and does that violate regulation?"**

It operates as a 4-phase pipeline:
1. **Extract** — Decompose AI output into atomic claims (fact / opinion / interpretation) with importance scoring and sentence-level guarantees (one claim per verifiable sentence)
2. **Verify** — Per-claim verdict (supported / contradicted / mixed / unverified) with confidence score and source citations, grounded against live web evidence
3. **Synthesize** — Risk scorecard: overallRisk (Low / Medium / High / Critical), weakest-link detection, EU AI Act risk tier mapping (Unacceptable / High / Limited / Minimal), triggered articles, required mitigations
4. **Gate** — CI enforcement via `--fail-on high` (exit code 1) + SARIF output for GitHub Code Scanning + EU AI Act compliance gate with configurable threshold/strict mode

## Install

```bash
npm install -g @nxtg/faultline
faultline scan --input document.txt --provider mock
```

No API key required for the `mock` provider. Real verification uses:
- Gemini (`GEMINI_API_KEY`) — live web grounding
- Perplexity (`PERPLEXITY_API_KEY`) — search-native, real-time
- OpenAI (`OPENAI_API_KEY`) — training-data verification
- Claude / Anthropic (`ANTHROPIC_API_KEY`) — reasoning-heavy documents

## Key Differentiators

- **Claim-level, not prompt-level** — Faultline forensics output; Promptfoo tests input prompts (note: Promptfoo acquired by OpenAI, March 2026 — Faultline remains independent)
- **EU AI Act compliance engine** — Article 5/6/9/10/11/12/13/14/15/50/52/53 evidence mapping; per-article evidence strength scoring (evidenceCount, sourceCount, strengthScore); evidence-weighted compliance score (0-100); per-article remediations; Annex III conformity checklist (8 items, Art. 6 trigger + high-risk gate); `art6ConformityRequired` CI gate flag; pass/fail gate with configurable threshold and strict mode; trend tracking and history; badge SVG for READMEs
- **5 compliance report formats** — JSON, PDF (EU-branded), Markdown (GFM for PR comments), SARIF 2.1.0 (GitHub Code Scanning), HTML (standalone viewable)
- **Weakest-link detection** — Finds the single claim that most undermines the argument's credibility
- **Provider-agnostic** — 5 providers; runtime switching with `--provider`; auto-failover with circuit breaker
- **SARIF output** — Native GitHub Code Scanning integration; both scan findings and compliance violations appear as code annotations
- **Enterprise API** — REST + GraphQL; API key management; multi-tenant; GDPR Article 15/17; audit trail; webhooks
- **GitHub Actions** — `faultline-scan` composite action with compliance gate, SARIF upload, threshold/strict configuration
- **Mutation-tested** — CRUCIBLE Protocol Gate 6: claim forensics 81.97%; compliance-report 80.81%; eu_ai_act fn 100%; GDPR stores 80.94%–96.81%
- **4,492 tests** across CLI, API, Python SDK, GDPR, mutation hardening, property-based, contract, integration
- **npm adoption metrics** — npmjs.org download tracking, Prometheus export, weekly trend analysis

## Use Cases

1. **Compliance gating in CI/CD** — Block deployments when AI output contains High/Critical risk claims; SARIF annotations in GitHub
2. **EU AI Act auditing** — Generate article-mapped compliance reports for conformity assessments
3. **LLM output QA** — Spot-check AI-generated documentation, support responses, or marketing copy for factual accuracy
4. **Red-team support** — Find which specific claim in a document is most likely to be challenged
5. **Multi-tenant platforms** — Per-tenant scan history, cost tracking, GDPR data export/erasure
6. **Enterprise monitoring** — Scheduled scans, webhook alerts on verdict changes, HTML mission control dashboard

## CLI Reference

```bash
faultline scan --input <file>         # Full forensic scan (JSON output)
faultline scan --input <file> --output-format markdown  # Human-readable report
faultline scan --demo                 # No API key — shows full product experience
faultline scan --fail-on high         # CI gate (exit 1 on High/Critical)
faultline weakest --input <file>      # Find weakest claim only
faultline compare --before a.txt --after b.txt  # Diff two scans
faultline compliance-report --input scan.json --ci  # EU AI Act pass/fail gate
faultline compliance-report --input scan.json --format sarif --output compliance.sarif  # SARIF for Code Scanning
faultline compliance-report --input scan.json --format markdown  # GFM for PR comments
faultline compliance-report --input scan.json --format html  # Standalone HTML report
faultline compliance-report --input scan.json --ci --threshold 80 --strict  # Require score >= 80 + all articles compliant
faultline init                        # Setup wizard (auto-detects configured providers)
```

## API Reference

Full integration guide: `docs/INTEGRATION.md`

Key endpoints:
- `POST /scan` — scan text, returns claims + verdicts + risk scorecard + inline complianceScore/compliancePass
- `POST /scan/deep` — multi-provider chain with evidence linking
- `POST /scan/stream` (SSE) — progressive per-claim streaming
- `POST /scan/batch` — scan multiple texts
- `POST /scan/diff` — compare two texts
- `POST /scan/compliance-gate` — scan text + evaluate EU AI Act compliance (200=pass, 422=fail)
- `GET /scan/:id/compliance` — evaluate compliance for existing scan (supports threshold/strict)
- `POST /scan/compliance-diff` — compare compliance between two scans
- `GET /scan/:id/compliance/badge` — SVG compliance badge for README embedding
- `GET /compliance/history` — time-series compliance gate history (filter by project/since/limit)
- `GET /compliance/trend` — compliance score direction for a project (up/down/stable)
- `GET /compliance/deadlines` — EU AI Act, GDPR, NIST upcoming dates
- `GET /claims/trending` — claim frequency, emerging patterns, verdict alerts
- `GET /npm/downloads` — npm download overview across all tracked packages
- `GET /npm/downloads/:package` — daily download counts for a package
- `GET /npm/trend/:package` — weekly download trend
- `POST /npm/poll` — trigger npm download poll (admin)
- `POST /keys` — API key management (create, rotate, expire, revoke)
- `GET /tenants/:id/export` — GDPR Article 15 data export (ZIP)
- `DELETE /tenants/:id/data` — GDPR Article 17 erasure

## Packages

| Package | npm | Description |
|---------|-----|-------------|
| `@nxtg/faultline` | CLI | Command-line forensics tool |
| `@nxtg/faultline-api` | API server | Fastify REST + GraphQL |
| `@nxtg/faultline-sdk` | SDK | TypeScript library for embedding |
| `faultline-sdk` | PyPI | Python SDK |

## Competitive Position

```
                PROMPT TESTING    CLAIM VERIFICATION    EU AI ACT
Promptfoo       ████████████      ░░░░░░               ░░░░░░
DeepEval        ███████           ░░░░░░               ░░░░░░
Faultline       ███               ████████████         ████████████
```

Faultline is not a substitute for Promptfoo (red-teaming, adversarial inputs) or DeepEval (RAG metrics, retrieval quality). It is the specialist for **output forensics** — verifying what the AI said, whether it was accurate, and whether it meets regulatory requirements.

## Repository Structure

```
packages/
  cli/          — CLI tool (@nxtg/faultline), providers, scan pipeline
  api/          — Fastify REST + GraphQL API (@nxtg/faultline-api)
  sdk/          — TypeScript SDK (@nxtg/faultline-sdk)
  web/          — Kaggle origin (P-08, frozen)
docs/
  INTEGRATION.md         — Full API integration guide (763 lines)
  PROVIDERS.md           — Provider comparison + configuration
  ARCHITECTURE.md        — System design, store architecture, data flow
  GTM-PLAN.md            — Go-to-market strategy
  mutation-testing.md    — Mutation hardening patterns
  gemini-model-benchmark-results.md  — Live Gemini Flash vs Pro accuracy results
```

## Project Status

- **215 initiatives SHIPPED** (N-01 through N-215)
- **4,492 tests** (CLI + API + Python SDK + integration + property-based + contract + mutation)
- **8/8 CRUCIBLE gates PASS** (example, property, contract, integration oracles)
- **EU AI Act enforcement-deadline ready** — Full compliance reporting (Art. 5/6/9/10/11/12/13/14/15/50/52/53), evidence strength scoring, Annex III conformity checklist, gating, SARIF, 5 output formats
- **GDPR compliant** — Article 15 export + Article 17 erasure implemented
- **Mutation-tested** — claim forensics critical path above 80% threshold
- **Security hardened** — security headers (CSP, X-Frame-Options, nosniff), timing-safe auth, GraphQL query bounds, Mermaid XSS sanitization
- **Version**: 0.5.0 (published 2026-04-15)

## License

Apache-2.0 — https://www.apache.org/licenses/LICENSE-2.0