Quickstart

Prerequisites

  • Python 3.12+ (developed on 3.13)
  • uv package manager

Installation

git clone https://github.com/lemur47/si-protocols.git
cd si-protocols
uv sync --all-extras
uv pip install en_core_web_sm@https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl

Analyse a Text

Run the threat filter against any local text file:

uv run si-threat-filter examples/synthetic_suspicious.txt

Output

The filter produces a 0–100 threat score with a breakdown:

  • Tech score — NLP-based detection of vagueness, authority claims, urgency patterns, emotional manipulation, logical contradictions, source attribution analysis, and commitment escalation
  • Heuristic score — probabilistic dissonance scanner
  • Hybrid score — weighted composite: 60% tech + 40% heuristic

Higher scores indicate more markers of disinformation were detected.

Topology Analysis

Run the topology analyser to extract claims, classify them, and produce a structural graph:

uv run si-topology examples/synthetic_topology_suspicious.txt

This generates an SVG file (<input>.topology.svg) visualising the claim graph. Options:

  • --format json — output JSON instead of SVG
  • --engine anthropic — use the Claude API engine (requires anthropic extra and ANTHROPIC_API_KEY)
  • --lang ja — analyse Japanese text
  • -o OUTPUT — specify output file path

Running Tests

uv run pytest                    # All tests
uv run pytest -m "not slow"     # Skip spaCy-dependent tests
uv run pytest tests/test_topology_types.py     # Topology types only
uv run pytest -k "topology"     # All topology tests

What Next?

  • Python Library Reference — use hybrid_score(), tech_analysis(), and the topology functions in your own code
  • REST API Reference — analyse text over HTTP with POST /analyse
  • Check markers.py to see which patterns are detected
  • File issues or contribute on GitHub