Skip to content
Back to search

epistemic-guard

Open-source provenance auditing & two-sided listening engine. Checks Where, When, and Primary Media/Named Outlets before sharing viral claims.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Sandeep-Hipparagi/epistemic-guard with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Sandeep-Hipparagi/epistemic-guard'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sandeep-hipparagi--epistemic-guard/badge.svg)](/listings/sandeep-hipparagi--epistemic-guard)

HTML

<a href="/listings/sandeep-hipparagi--epistemic-guard"><img src="/api/listings/sandeep-hipparagi--epistemic-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Installation

Install via `pip` or modern Python package manager `uv`:

# Clone the repository
git clone https://github.com/Sandeep-Hipparagi/epistemic-guard.git
cd epistemic-guard

# Option A: Fast installation with uv
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
uv pip install -e ".[dev]"

# Option B: Standard pip
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

2. Zero-API-Key Configuration (Ollama + DuckDuckGo)

`epistemic-guard` runs 100% open-source without any paid cloud API keys:

cp .env.example .env

Configure `.env` for your local [Ollama](https://ollama.ai) instance:

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL_NAME=qwen2.5:7b
SEARCH_PROVIDER=duckduckgo

*(Also compatible with `vLLM`, `llama.cpp`, OpenAI `gpt-4o`, or any OpenAI-compatible API endpoint).*

3. Run Your First CLI Audit

Audit a domain or viral post right from your terminal:

# Audit a domain's accountability tier
epistemic-guard audit-url "https://theonion.com/article/123"

# Audit a viral claim and check provenance
epistemic-guard analyze "Official Envoy: Trade accord ratified https://www.reuters.com/markets/trade-accord-2026"

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 357 lines
  1. <div align="center">
  2. # 🛡️ Epistemic Guard
  3. **Open-Source, Model-Agnostic Provenance Auditing & Two-Sided Listening Engine**
  4. [![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](pyproject.toml)
  5. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  6. [![Pydantic v2](https://img.shields.io/badge/pydantic-v2.7+-green.svg)](https://docs.pydantic.dev/)
  7. [![Tests Passing](https://img.shields.io/badge/tests-89%20passed-brightgreen.svg)](tests/)
  8. [![CI Status](https://github.com/Sandeep-Hipparagi/epistemic-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/Sandeep-Hipparagi/epistemic-guard/actions/workflows/ci.yml)
  9. [![Benchmark Accuracy](https://img.shields.io/badge/benchmark-100%25%20accuracy-success.svg)](benchmarks/)
  10. [![MCP Ready](https://img.shields.io/badge/MCP-Ready-8A2BE2.svg)](src/epistemic_guard/interfaces/mcp_server.py)
  11. [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  12. *A deterministic, zero-hallucination verification foundation to halt viral misinformation before emotional contagion spreads.*
  13. [Quickstart](#-60-second-quickstart) • [The Philosophy](#-the-problem--epistemic-philosophy) • [Architecture](#-system-architecture) • [Use Cases](#-public-use-cases--integration-recipes) • [Benchmarks](#-benchmark-scorecard) • [Documentation](docs/)
  14. </div>
  15. ---
  16. ## 📖 The Problem & Epistemic Philosophy
  17. In modern digital ecosystems, viral claims, outrage quotes, and video snippets propagate during moments of peak emotional volatility. Fact-checking systems often fail in these moments because:
  18. 1. **Subjective Truth Arbitration:** LLMs tasked with arbitrating "truth" hallucinate, exhibit political bias, or struggle with fast-moving breaking news.
  19. 2. **Context Stripping & Recycling:** Historical footage or past speeches are repackaged as "breaking news," evading text-only fact-checkers.
  20. 3. **Quote Mutation & Deceptive Domains:** Subtle single-word alterations to real speeches and typosquatted domains (e.g., `reuters-breaking.com`) bypass naive filters.
  21. 4. **Echo Chambers & Asymmetry:** Discourse degenerates into tribal camps where one side cites primary documentation while the other relies on anonymous viral outrage.
  22. ### The Epistemic Philosophy: Provenance Over Arbitration
  23. Rather than asking an LLM *"Is this claim true?"*, `epistemic-guard` asks three deterministic, empirical questions:
  24. 1. **WHERE was it said?** (Platform, podium, legislative floor, or canonical root URL)
  25. 2. **WHEN was it said?** (Exact datetime to catch recycled historical media or out-of-context quotes)
  26. 3. **IS THERE EVIDENCE / A NAMED OUTLET?** (Primary video/audio, government registry, or Tier 1/2 accountable journalism—filtering out single unverified UGC posts)
  27. If these criteria are unmet—or if the sole source is an unverified social media post, lookalike domain, or mutated quote—the system applies a strict invariant: **`DO_NOT_SHARE_UNCONFIRMED`**.
  28. When evaluating two opposing factions, `epistemic-guard` pairs provenance verification with **Two-Sided Listening**: mathematically exposing narrative asymmetry while producing steel-manned summaries and calm, non-preachy de-escalation guidance.
  29. ---
  30. ## 🏛️ System Architecture
  31. `epistemic-guard` decouples empirical verification from language generation:
  32. ```mermaid
  33. flowchart TD
  34. subgraph Ingestion ["1. Multi-Format Ingestion"]
  35. Raw["Raw Social Posts / Threads / Articles"]
  36. Single["Viral Claim or Direct URL"]
  37. end
  38. subgraph Extraction ["2. Claim & Emotional Extraction"]
  39. Ext["ClaimExtractor (LLM at temperature=0.0)"]
  40. Claims["Extracted Claims & Quotes"]
  41. Arousal["Emotional Framing & Manipulation Cues"]
  42. end
  43. subgraph Verification ["3. Deterministic 3-Criteria Provenance Engine"]
  44. Where["1. WHERE: DomainAuditor & Lookalike Interceptor"]
  45. When["2. WHEN: Temporal Drift Engine (|Δt| > 30 days)"]
  46. Quote["3. EVIDENCE: Quote-Mutation (< 0.55 similarity) & Circular Reporting Defense"]
  47. end
  48. subgraph StateGraph ["4. LangGraph Multi-Perspective Synthesis"]
  49. State["EpistemicGraphState"]
  50. Asymm["Provenance Asymmetry Calculator"]
  51. Syn["Steel-Manned Synthesis & De-escalation Note"]
  52. end
  53. subgraph Delivery ["5. Developer & User Delivery Channels"]
  54. CLI["Rich Terminal CLI"]
  55. API["FastAPI REST Service (/v1/analyze)"]
  56. MCP["Model Context Protocol Server (epistemic-guard-mcp)"]
  57. WebUI["Pre-Share Friction Studio & Bookmarklet (GET /)"]
  58. end
  59. Raw --> Ext
  60. Single --> Where
  61. Ext --> Claims
  62. Ext --> Arousal
  63. Claims --> Where
  64. Where --> When --> Quote
  65. Quote --> State
  66. Arousal --> State
  67. State --> Asymm --> Syn
  68. Syn --> CLI
  69. Syn --> API
  70. Syn --> MCP
  71. Syn --> WebUI
  72. ```
  73. Detailed technical specifications are available in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  74. ---
  75. ## ⚡ 60-Second Quickstart
  76. ### 1. Installation
  77. Install via `pip` or modern Python package manager `uv`:
  78. ```bash
  79. # Clone the repository
  80. git clone https://github.com/Sandeep-Hipparagi/epistemic-guard.git
  81. cd epistemic-guard
  82. # Option A: Fast installation with uv
  83. uv venv
  84. source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
  85. uv pip install -e ".[dev]"
  86. # Option B: Standard pip
  87. python -m venv .venv
  88. source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
  89. pip install -e ".[dev]"
  90. ```
  91. ### 2. Zero-API-Key Configuration (Ollama + DuckDuckGo)
  92. `epistemic-guard` runs 100% open-source without any paid cloud API keys:
  93. ```bash
  94. cp .env.example .env
  95. ```
  96. Configure `.env` for your local [Ollama](https://ollama.ai) instance:
  97. ```ini
  98. LLM_BASE_URL=http://localhost:11434/v1
  99. LLM_API_KEY=ollama
  100. LLM_MODEL_NAME=qwen2.5:7b
  101. SEARCH_PROVIDER=duckduckgo
  102. ```
  103. *(Also compatible with `vLLM`, `llama.cpp`, OpenAI `gpt-4o`, or any OpenAI-compatible API endpoint).*
  104. ### 3. Run Your First CLI Audit
  105. Audit a domain or viral post right from your terminal:
  106. ```bash
  107. # Audit a domain's accountability tier
  108. epistemic-guard audit-url "https://theonion.com/article/123"
  109. # Audit a viral claim and check provenance
  110. epistemic-guard analyze "Official Envoy: Trade accord ratified https://www.reuters.com/markets/trade-accord-2026"
  111. ```
  112. ---
  113. ## 🎯 Public Use Cases & Integration Recipes
  114. ### Use Case 1: Pre-Share Friction Gate for Journalists & Readers (Web UI & Bookmarklet)
  115. Launch the self-contained, zero-build web friction studio:
  116. ```bash
  117. uvicorn epistemic_guard.interfaces.api:app --host 0.0.0.0 --port 8000
  118. ```
  119. Open `http://localhost:8000` in your browser.
  120. - **Interactive Pre-Share Friction:** Instant **Stop / Caution / Verified** visual friction banners, the 3 Provenance Checkboxes (*Where*, *When*, *Evidence*), and an emotional arousal meter.
  121. - **1-Click Browser Bookmarklet:** Drag the **🛡️ Epistemic Guard** bookmarklet to your browser's toolbar. Highlight any text on X, Reddit, or news articles, and click the bookmarklet to audit before sharing.
  122. ---
  123. ### Use Case 2: MCP Server for AI Coding & Research Agents
  124. Autonomous agents (in Claude Desktop, Cursor, OpenCode, or LangChain) can prevent hallucinated citations and verify web sources via the **Model Context Protocol (MCP)**.
  125. Add to your `claude_desktop_config.json`:
  126. ```json
  127. {
  128. "mcpServers": {
  129. "epistemic-guard": {
  130. "command": "epistemic-guard-mcp",
  131. "env": {
  132. "LLM_BASE_URL": "http://localhost:11434/v1",
  133. "LLM_API_KEY": "ollama",
  134. "LLM_MODEL_NAME": "qwen2.5:7b",
  135. "SEARCH_PROVIDER": "duckduckgo"
  136. }
  137. }
  138. }
  139. }
  140. ```
  141. **Exposed MCP Agent Tools:**
  142. - `audit_source_url(url: str)`: Deterministically classifies domains into Tiers 1–5 before citations.
  143. - `check_viral_claim(claim_text: str)`: Audits single claims against the 3 provenance criteria.
  144. - `listen_two_sides(texts: list[str])`: Synthesizes multi-perspective discourse and exposes epistemic asymmetry.
  145. ---
  146. ### Use Case 3: REST Microservice for Social Feeds & Moderation Pipelines
  147. Run `epistemic-guard` as a production microservice:
  148. ```bash
  149. # Start containerized service on port 8000
  150. docker compose up -d
  151. ```
  152. **Query End-to-End Discourse Analysis:**
  153. ```bash
  154. curl -X POST http://localhost:8000/v1/analyze \
  155. -H "Content-Type: application/json" \
  156. -d '{
  157. "texts": [
  158. "Official Envoy: Trade accord ratified with tariff cuts across 14 sectors https://www.reuters.com/markets/trade-accord-2026",
  159. "OUTRAGE! Secret surrender leaked on Telegram! https://t.me/patriot_leaks/889"
  160. ]
  161. }'
  162. ```
  163. **Response Payload (Truncated):**
  164. ```json
  165. {
  166. "topic": "Trade Accord Ratification",
  167. "provenance_asymmetry_detected": true,
  168. "asymmetry_rationale": "Side A is corroborated by Tier 1 wire services (Reuters), while Side B relies on unverified social media posts lacking primary media backing.",
  169. "perspectives": [
  170. {
  171. "side_label": "Side A",
  172. "verified_shareable_count": 1,
  173. "unconfirmed_blocked_count": 0,
  174. "average_emotional_arousal": 0.22,
  175. "steelmanned_summary": "Proponents emphasize the documented economic provisions of the ratified agreement."
  176. },
  177. {
  178. "side_label": "Side B",
  179. "verified_shareable_count": 0,
  180. "unconfirmed_blocked_count": 1,
  181. "average_emotional_arousal": 0.91,
  182. "steelmanned_summary": "Critics raise sovereignty concerns, though without primary documentary evidence."
  183. }
  184. ],
  185. "deescalation_guidance": "Primary documentary evidence exists for the ratified terms, while allegations of secret concessions remain uncorroborated. Pause before sharing."
  186. }
  187. ```
  188. ---
  189. ### Use Case 4: Evaluating Two-Sided Discourse Asymmetry in Python
  190. Integrate the compiled LangGraph pipeline directly into your Python research scripts:
  191. ```python
  192. from epistemic_guard.graph.workflow import EpistemicGuardPipeline
  193. pipeline = EpistemicGuardPipeline()
  194. report = pipeline.analyze([
  195. "Official Press Office: New regulatory framework approved https://www.reuters.com/business/regs-2026",
  196. "THEY SOLD US OUT! Anonymous whistleblower claims total corruption: https://x.com/outrage/status/123"
  197. ])
  198. print(f"Topic: {report.topic}")
  199. print(f"Asymmetry Detected: {report.provenance_asymmetry_detected}")
  200. print(f"De-escalation Guidance: {report.deescalation_guidance}")
  201. for perspective in report.perspectives:
  202. print(f"[{perspective.side_label}] Verified: {perspective.verified_shareable_count} | Blocked: {perspective.unconfirmed_blocked_count} | Arousal: {perspective.average_emotional_arousal:.2f}")
  203. ```
  204. More walkthroughs and recipes can be found in [docs/USE_CASES.md](docs/USE_CASES.md).
  205. ---
  206. ## 🏛️ Deterministic Source Tiering & Adversarial Defense
  207. Domain credibility is resolved via [`config/source_tiers.yaml`](config/source_tiers.yaml) using strict suffix-tree registered domain matching:
  208. | Tier | Name | Trust Level | Description & Rules | Default Verdict |
  209. | :--- | :--- | :---: | :--- | :--- |
  210. | **Tier 1** | `TIER_1_PRIMARY` | `HIGH` | Global wire services (Reuters, AP), primary academic journals (`Nature`, `Science`), government/judicial portals (`.gov`, `.mil`), supranational bodies (UN, WHO), and IFCN-certified fact-checkers. | **Eligible for Primary Verification** |
  211. | **Tier 2** | `TIER_2_ESTABLISHED_EDITORIAL` | `MEDIUM_HIGH` | Major newsrooms with published corrections policies, named reporter bylines, and legal accountability (NYT, BBC, WSJ, The Guardian). | **Eligible for Corroboration** |
  212. | **Tier 3** | `TIER_3_SECONDARY_ANALYSIS` | `MEDIUM` | Trade press, tech publications, opinion commentary, and curated analytical platforms (TechCrunch, Wired, Axios, Substack). | **Requires Secondary Corroboration** |
  213. | **Tier 4** | `TIER_4_USER_GENERATED` | `LOW_UNVERIFIED` | Social media platforms (X/Twitter, TikTok, Reddit, Telegram, YouTube) and lookalike domains. | **`DO_NOT_SHARE_UNCONFIRMED` if sole source** |
  214. | **Tier 5** | `TIER_5_SATIRE_PARODY` | `SATIRE` | Humorous or satirical outlets (The Onion, Babylon Bee) frequently misconstrued as real news. | **Immediate Satire Parody Alert** |
  215. | **Unknown** | `TIER_UNKNOWN` | `UNKNOWN` | Unlisted domains or personal blogs. | **Conservative Hold** |
  216. ### Adversarial Defenses
  217. - **Lookalike & Typosquatting Interceptor (`detect_lookalike_domain`):** Intercepts deceptive domain permutations targeting 22+ protected brands (e.g., `reuters-breaking.com`, `bbc-news-alert.co`). Forcefully demotes them to Tier 4 with flag `LOOKALIKE_DOMAIN_IMPERSONATION`.
  218. - **Quote-Mutation & Misattribution Auditor (`verify_quote_integrity`):** Detects doctored quotes using token Jaccard and sliding-window character matching. If wire reporting covers the event but quote similarity is $< 0.55$, the engine triggers `QUOTE_MUTATION_DISTORTION` and blocks sharing.
  219. For governance rules and proposal instructions, see [docs/SOURCE_TIERING_POLICY.md](docs/SOURCE_TIERING_POLICY.md).
  220. ---
  221. ## 📊 Benchmark Scorecard
  222. `epistemic-guard` includes a 100% offline, reproducible evaluation harness testing 16 diverse viral scenarios across 8 epistemic categories in [`benchmarks/dataset.jsonl`](benchmarks/dataset.jsonl):
  223. ```bash
  224. # Run the evaluation suite (executes in ~1.7s, zero API keys required)
  225. python benchmarks/evaluate.py
  226. ```
  227. ### Measured Benchmark Performance
  228. | Epistemic Evaluation Metric | Measured Score | Design Target | Status |
  229. | :--- | :---: | :---: | :---: |
  230. | **Overall Scenario Accuracy** | **100.0%** (16/16) | $\ge 95.0\%$ | ✅ PASSED |
  231. | **Misinformation Block Recall** | **100.0%** (13/13) | $100.0\%$ | ✅ PASSED |
  232. | **Verified Share Precision** | **100.0%** (3/3) | $100.0\%$ | ✅ PASSED |
  233. | **Temporal Drift (Recycled) Recall** | **100.0%** | $100.0\%$ | ✅ PASSED |
  234. | **Provenance Asymmetry Accuracy** | **100.0%** | $100.0\%$ | ✅ PASSED |
  235. | **Total Evaluation Latency** | **1752.3ms** | $< 3000\text{ms}$ | ✅ PASSED |
  236. ### Benchmark Archetypes Tested
  237. 1. **Fake Attributed Viral Quotes:** Fabricated executive resignations & political admissions $\to$ `DO_NOT_SHARE_UNCONFIRMED`.
  238. 2. **Recycled Historical Media:** Winter storm power grid failures from 2021 resold as current $\to$ `TEMPORAL_DRIFT_RECYCLED_CONTENT`.
  239. 3. **Circular Social Media Echoes:** Rumors repeating across unverified accounts $\to$ `NO_PRIMARY_MEDIA_OR_NAMED_OUTLET`.
  240. 4. **Satire Misattribution:** Fictional satire headlines circulated literally $\to$ `SATIRE_PARODY_ALERT`.
  241. 5. **Verified Primary Records:** C-SPAN hearings, Federal Reserve releases, NASA mission telemetry $\to$ `VERIFIED_PRIMARY`.
  242. 6. **Asymmetric Discourse:** Heated debates contrasting evidence-backed facts against emotional hearsay $\to$ `provenance_asymmetry_detected: true`.
  243. 7. **Quote Mutation & Distortion:** Subtle single-word tampering of authentic press briefings $\to$ `QUOTE_MUTATION_DISTORTION`.
  244. 8. **Lookalike Domain Impersonation:** Typosquatted news domains $\to$ `LOOKALIKE_DOMAIN_IMPERSONATION`.
  245. ---
  246. ## 🗺️ Roadmap
  247. - [x] **v0.1.0 — Core Foundation & Retrieval Engine:** Zero-hallucination data contracts, deterministic source tiering, temporal drift detection, and LangGraph multi-perspective state topology.
  248. - [x] **v0.2.0 — Pre-Share Friction & Adversarial Defense:** Zero-build Pre-Share Web Friction UI, 1-click browser bookmarklet, quote-mutation integrity auditor, lookalike domain interceptor, and 16-case offline benchmark suite.
  249. - [ ] **v0.3.0 — Browser Extension (Chrome/Firefox/Brave):** Native Manifest v3 pre-share modal injecting cognitive friction before posting on social media feeds.
  250. - [ ] **v0.4.0 — Multilingual Provenance:** Cross-lingual quote matching and domain tiering for Spanish, French, German, and Hindi media ecosystems.
  251. - [ ] **v0.5.0 — Audio/Video Telemetry Ingestion:** Automated Whisper-based audio transcription and timestamped video keyframe alignment.
  252. ---
  253. ## 📚 Citation
  254. If you use `epistemic-guard` in your academic research or applications, please cite:
  255. ```bibtex
  256. @software{hipparagi2026epistemicguard,
  257. author = {Hipparagi, Sandeep and Contributors},
  258. title = {Epistemic Guard: Model-Agnostic Provenance Auditing and Two-Sided Listening Engine},
  259. year = {2026},
  260. publisher = {GitHub},
  261. journal = {GitHub repository},
  262. howpublished = {\url{https://github.com/Sandeep-Hipparagi/epistemic-guard}},
  263. version = {0.2.0}
  264. }
  265. ```
  266. ---
  267. ## 📄 License & Governance
  268. - **License:** Apache License 2.0. See [LICENSE](LICENSE) for terms.
  269. - **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md).
  270. - **Security:** See [SECURITY.md](SECURITY.md).
  271. - **Code of Conduct:** See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.