Persuasion Detector

An MCP-based agent that analyzes text (news articles, ads, political messaging, chatbot output) for the presence of Cialdini's six principles of persuasion (Reciprocity, Commitment/Consistency, Social Proof, Authority, Liking, Scarcity). Built for journalists and media researchers who want a structured, evidence-backed read on how a piece of text is trying to persuade its reader, not just whether it is.

This project grew out of my background in social psychology (personality and social psychology were my strongest areas) combined with prior work on news trust and content provenance at SFI MediaFutures. It's deliberately built as a production-oriented tool, not a notebook demo. The file structure below mirrors the components you'd expect in a real internal AI platform (access control, guardrails, observability, retrieval), rather than an idealized, all-in-one script.

Why this exists

Most "persuasion detection" demos either hardcode a handful of keyword rules, or throw raw text at an LLM with no grounding and no guardrails. This project tries to do better on both fronts:

• Grounded, not just prompted. Scoring is backed by a small retrieval-augmented (RAG) pipeline: labeled reference examples are embedded via Voyage AI and stored in a local vector database (Chroma), so the model has concrete precedent to reason from, not just a bare list of principle names.

• Guarded, not just trusted. Input is validated for length and checked (via regex pattern-matching) for common prompt-injection attempts before it ever reaches the model. The model's own output is constrained with a Pydantic schema: Claude cannot return a persuasion score outside 0 to 1, or a principle name outside the real six.

• Observable, not a black box. Every request is logged, with deliberate care not to log raw user text, for GDPR reasons, so the system's behavior over time (rejection rates, failure rates) is actually inspectable.

Related MCP server: decompose

Architecture

``` Text input │ ▼ Guardrails (length + injection checks) │ ▼ Retrieval (Voyage embeddings + Chroma vector search) │ ▼ Prompt construction (delimited user text + principle definitions + examples) │ ▼ Claude (structured output via Pydantic schema) │ ▼ Formatted persuasion report ```

Project structure, mapped to platform components

The structure deliberately separates concerns the way a production AI platform typically would: access/model configuration, guardrails and policy, observability, and retrieval, rather than one monolithic script:

Tech stack

• Language model: Claude (Anthropic API), structured output via client.messages.parse() and a Pydantic schema

• Embeddings / retrieval: Voyage AI + ChromaDB (local, persistent vector store)

• Protocol: Model Context Protocol (MCP), via the official mcp Python SDK

• Validation: Pydantic v2

• Testing: pytest

A deliberate design choice worth naming

The six persuasion principles are defined in two places: as a Literal type constraint in guardrails.py, and as full definitions in principles.py. This is intentional, not an oversight. The Literal constraint is a strict, independent safety gate on the model's output, kept hardcoded so that a change to the content source (principles.py) can never silently loosen what's accepted as valid.

What this project doesn't do

No content moderation or topic filtering. Journalists legitimately need to write about difficult subjects. The tool's job is to identify persuasive technique, not to police topic, and conflating the two would undermine its actual purpose.

Credit

Informed by patterns from NVIDIA's NeMo Guardrails framework, though not taken as a dependency. This project's guardrail surface is narrow enough that a full general-purpose framework would have added complexity without a matching benefit.