WIP checkpoint: Text filtering service + profanity config

2026-08-18 15:17:08 +00:00
9 changed files with 343 additions and 358 deletions
@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import create_async_engine
 from app.config import settings
 from app.database import Base
-from app.models import user, session, world, asset, friendship, follow, block  # noqa: F401
+from app.models import user, session, world, asset  # noqa: F401
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
@@ -1,136 +0,0 @@
 """social graph: friendships, follows, blocks
 Revision ID: 0002_social_graph
 Revises: 0001_initial
 Create Date: 2026-08-18 00:00:00.000000
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 # revision identifiers, used by Alembic.
 revision: str = "0002_social_graph"
 down_revision: Union[str, None] = "0001_initial"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    """Create friendships, follows, and blocks tables."""
    op.create_table(
        "friendships",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("requester_id", sa.Integer(), nullable=False),
        sa.Column("addressee_id", sa.Integer(), nullable=False),
        sa.Column("status", sa.String(length=20), server_default="pending", nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
        sa.CheckConstraint(
            "status IN ('pending', 'accepted')",
            name="ck_friendships_status",
        ),
        sa.CheckConstraint(
            "requester_id <> addressee_id",
            name="ck_friendships_no_self",
        ),
        sa.ForeignKeyConstraint(
            ["addressee_id"],
            ["users.id"],
            ondelete="CASCADE",
        ),
        sa.ForeignKeyConstraint(
            ["requester_id"],
            ["users.id"],
            ondelete="CASCADE",
        ),
        sa.PrimaryKeyConstraint("id"),
        sa.UniqueConstraint(
            "requester_id",
            "addressee_id",
            name="uq_friendships_requester_addressee",
        ),
    )
    op.create_index(op.f("ix_friendships_id"), "friendships", ["id"], unique=False)
    op.create_index(op.f("ix_friendships_addressee_id"), "friendships", ["addressee_id"], unique=False)
    op.create_index(op.f("ix_friendships_requester_id"), "friendships", ["requester_id"], unique=False)
    op.create_table(
        "follows",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("follower_id", sa.Integer(), nullable=False),
        sa.Column("followed_id", sa.Integer(), nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
        sa.CheckConstraint(
            "follower_id <> followed_id",
            name="ck_follows_no_self",
        ),
        sa.ForeignKeyConstraint(
            ["followed_id"],
            ["users.id"],
            ondelete="CASCADE",
        ),
        sa.ForeignKeyConstraint(
            ["follower_id"],
            ["users.id"],
            ondelete="CASCADE",
        ),
        sa.PrimaryKeyConstraint("id"),
        sa.UniqueConstraint(
            "follower_id",
            "followed_id",
            name="uq_follows_follower_followed",
        ),
    )
    op.create_index(op.f("ix_follows_id"), "follows", ["id"], unique=False)
    op.create_index(op.f("ix_follows_followed_id"), "follows", ["followed_id"], unique=False)
    op.create_index(op.f("ix_follows_follower_id"), "follows", ["follower_id"], unique=False)
    op.create_table(
        "blocks",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("blocker_id", sa.Integer(), nullable=False),
        sa.Column("blocked_id", sa.Integer(), nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
        sa.CheckConstraint(
            "blocker_id <> blocked_id",
            name="ck_blocks_no_self",
        ),
        sa.ForeignKeyConstraint(
            ["blocked_id"],
            ["users.id"],
            ondelete="CASCADE",
        ),
        sa.ForeignKeyConstraint(
            ["blocker_id"],
            ["users.id"],
            ondelete="CASCADE",
        ),
        sa.PrimaryKeyConstraint("id"),
        sa.UniqueConstraint(
            "blocker_id",
            "blocked_id",
            name="uq_blocks_blocker_blocked",
        ),
    )
    op.create_index(op.f("ix_blocks_id"), "blocks", ["id"], unique=False)
    op.create_index(op.f("ix_blocks_blocked_id"), "blocks", ["blocked_id"], unique=False)
    op.create_index(op.f("ix_blocks_blocker_id"), "blocks", ["blocker_id"], unique=False)
 def downgrade() -> None:
    """Drop friendships, follows, and blocks tables."""
    op.drop_index(op.f("ix_blocks_blocker_id"), table_name="blocks")
    op.drop_index(op.f("ix_blocks_blocked_id"), table_name="blocks")
    op.drop_index(op.f("ix_blocks_id"), table_name="blocks")
    op.drop_table("blocks")
    op.drop_index(op.f("ix_follows_follower_id"), table_name="follows")
    op.drop_index(op.f("ix_follows_followed_id"), table_name="follows")
    op.drop_index(op.f("ix_follows_id"), table_name="follows")
    op.drop_table("follows")
    op.drop_index(op.f("ix_friendships_requester_id"), table_name="friendships")
    op.drop_index(op.f("ix_friendships_addressee_id"), table_name="friendships")
    op.drop_index(op.f("ix_friendships_id"), table_name="friendships")
    op.drop_table("friendships")
@@ -2,17 +2,5 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
 from app.models.friendship import Friendship, FriendshipStatus
 from app.models.follow import Follow
 from app.models.block import Block
-__all__ = [
+__all__ = ["User", "Session", "World", "Asset"]
    "User",
    "Session",
    "World",
    "Asset",
    "Friendship",
    "FriendshipStatus",
    "Follow",
    "Block",
 ]
@@ -1,48 +0,0 @@
 """Block model: a hard deny that also hides content and prevents DMs."""
 from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class Block(Base):
    __tablename__ = "blocks"
    __table_args__ = (
        UniqueConstraint(
            "blocker_id",
            "blocked_id",
            name="uq_blocks_pair",
        ),
        CheckConstraint(
            "blocker_id <> blocked_id",
            name="ck_blocks_no_self",
        ),
    )
    id = Column(Integer, primary_key=True, index=True)
    blocker_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    blocked_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    blocker = relationship(
        "User",
        foreign_keys=[blocker_id],
        back_populates="blocks_issued",
    )
    blocked = relationship(
        "User",
        foreign_keys=[blocked_id],
        back_populates="blocks_received",
    )
@@ -1,48 +0,0 @@
 """Follow model: a one-way relationship requiring no approval."""
 from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class Follow(Base):
    __tablename__ = "follows"
    __table_args__ = (
        UniqueConstraint(
            "follower_id",
            "followed_id",
            name="uq_follows_pair",
        ),
        CheckConstraint(
            "follower_id <> followed_id",
            name="ck_follows_no_self",
        ),
    )
    id = Column(Integer, primary_key=True, index=True)
    follower_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    followed_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    follower = relationship(
        "User",
        foreign_keys=[follower_id],
        back_populates="following",
    )
    followed = relationship(
        "User",
        foreign_keys=[followed_id],
        back_populates="followers",
    )
@@ -1,74 +0,0 @@
 """Friendship model: a one-directional request that becomes mutual on accept."""
 from sqlalchemy import (
    CheckConstraint,
    Column,
    DateTime,
    ForeignKey,
    Integer,
    String,
    UniqueConstraint,
 )
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class FriendshipStatus:
    """String values for the friendship.status column."""
    PENDING = "pending"
    ACCEPTED = "accepted"
 class Friendship(Base):
    __tablename__ = "friendships"
    __table_args__ = (
        UniqueConstraint(
            "requester_id",
            "addressee_id",
            name="uq_friendships_pair",
        ),
        CheckConstraint(
            "requester_id <> addressee_id",
            name="ck_friendships_no_self",
        ),
        CheckConstraint(
            "status IN ('pending', 'accepted')",
            name="ck_friendships_status",
        ),
    )
    id = Column(Integer, primary_key=True, index=True)
    requester_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    addressee_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    status = Column(
        String(20),
        nullable=False,
        default=FriendshipStatus.PENDING,
        server_default=FriendshipStatus.PENDING,
    )
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
    requester = relationship(
        "User",
        foreign_keys=[requester_id],
        back_populates="sent_friend_requests",
    )
    addressee = relationship(
        "User",
        foreign_keys=[addressee_id],
        back_populates="received_friend_requests",
    )
@@ -19,41 +19,3 @@ class User(Base):
    sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
    worlds = relationship("World", back_populates="owner")
    assets = relationship("Asset", back_populates="owner")
    # Social graph
    sent_friend_requests = relationship(
        "Friendship",
        foreign_keys="Friendship.requester_id",
        back_populates="requester",
        cascade="all, delete-orphan",
    )
    received_friend_requests = relationship(
        "Friendship",
        foreign_keys="Friendship.addressee_id",
        back_populates="addressee",
        cascade="all, delete-orphan",
    )
    following = relationship(
        "Follow",
        foreign_keys="Follow.follower_id",
        back_populates="follower",
        cascade="all, delete-orphan",
    )
    followers = relationship(
        "Follow",
        foreign_keys="Follow.followed_id",
        back_populates="followed",
        cascade="all, delete-orphan",
    )
    blocks_issued = relationship(
        "Block",
        foreign_keys="Block.blocker_id",
        back_populates="blocker",
        cascade="all, delete-orphan",
    )
    blocks_received = relationship(
        "Block",
        foreign_keys="Block.blocked_id",
        back_populates="blocked",
        cascade="all, delete-orphan",
    )
@@ -0,0 +1 @@
 """Application services."""
@@ -0,0 +1,340 @@
 """Pluggable server-side text filtering service.
 Provides a ``TextFilter`` protocol with a deterministic default
 implementation (profanity/term list with normalization) and a hook
 for third-party providers.
 Usage::
    from app.services.text_filter import TextFilter, FilterResult, \
        ProfanityTextFilter, get_text_filter
    # Default factory reads config from the path below
    filt = get_text_filter()
    result = filt.check("Hello wor1d!")
    # result.action == FilterAction.ALLOW
 """
 from __future__ import annotations
 import json
 import os
 import re
 import unicodedata
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 from typing import Any
 # ---------------------------------------------------------------------------
 # Enums / Data classes
 # ---------------------------------------------------------------------------
 class FilterAction(str, Enum):
    """Action the filter wants the caller to take."""
    ALLOW = "allow"
    REDACT = "redact"
    REJECT = "reject"
@dataclass(frozen=True)
 class FilterResult:
    """Immutable result of a single ``TextFilter.check()`` call.
    Attributes:
        action: What to do with the message.
        filtered_text: The text after redaction (may equal *text* if
            action is ``ALLOW``).
        matched_terms: Sorted list of terms that triggered the filter.
    """
    action: FilterAction
    filtered_text: str
    matched_terms: list[str] = field(default_factory=list)
    @property
    def is_allowed(self) -> bool:
        return self.action == FilterAction.ALLOW
    @property
    def is_rejected(self) -> bool:
        return self.action == FilterAction.REJECT
    @property
    def is_redacted(self) -> bool:
        return self.action == FilterAction.REDACT
 # ---------------------------------------------------------------------------
 # Protocol / abstract base
 # ---------------------------------------------------------------------------
 class TextFilter(ABC):
    """Protocol for server-side text filters.
    Every concrete filter must implement ``check()``.  The default
    implementation (``ProfanityTextFilter``) is deterministic and
    requires no external service.  A third-party provider can be
    plugged in by subclassing ``TextFilter`` and overriding ``check``.
    """
    @abstractmethod
    def check(self, text: str) -> FilterResult:
        """Analyse *text* and return a ``FilterResult``.
        Args:
            text: Raw message text to filter.
        Returns:
            A ``FilterResult`` with the decision and any redacted text.
        """
 # ---------------------------------------------------------------------------
 # Normalisation helpers
 # ---------------------------------------------------------------------------
 # Common leetspeak substitutions (char -> set of possible originals)
 _LEETSPEAK: dict[str, str] = {
    "0": "o",
    "1": "i",
    "3": "e",
    "4": "a",
    "5": "s",
    "7": "t",
    "8": "b",
    "9": "g",
    "@": "a",
 }
 # Normalise separators that are often used to obfuscate words
 _SEPARATORS = re.compile(r"[\s_\-\.]+")
 def _normalize(text: str) -> str:
    """Case-fold, strip diacritics, and replace leetspeak / separators.
    This produces a canonical form for matching against the term list.
    """
    # Case-fold
    text = text.casefold()
    # Strip diacritics (e.g. é -> e)
    text = unicodedata.normalize("NFKD", text)
    text = "".join(c for c in text if not unicodedata.combining(c))
    # Replace leetspeak
    normalized = ""
    for ch in text:
        normalized += _LEETSPEAK.get(ch, ch)
    # Collapse separators
    normalized = _SEPARATORS.sub("", normalized)
    return normalized
 # ---------------------------------------------------------------------------
 # Default implementation
 # ---------------------------------------------------------------------------
 # Default config path (relative to project root)
 _DEFAULT_CONFIG_PATH = Path(__file__).resolve().parent.parent.parent / "data" / "text_filter_config.json"
@dataclass
 class _FilterPolicy:
    """Filtering policy loaded from config."""
    mode: str  # "redact" or "reject"
    redaction_char: str = "*"
    # Minimum term length to consider (avoids matching single chars)
    min_term_length: int = 3
    # If True, match terms case-insensitively after normalisation
    case_insensitive: bool = True
    # If True, match whole words only (after normalisation)
    whole_word: bool = True
 class ProfanityTextFilter(TextFilter):
    """Deterministic text filter backed by a JSON term list.
    The config file is a JSON object with:
    .. code-block:: json
        {
            "mode": "redact",
            "redaction_char": "*",
            "min_term_length": 3,
            "case_insensitive": true,
            "whole_word": true,
            "terms": ["badword", "another", ...]
        }
    Terms are matched after normalisation (case-fold, leetspeak
    substitution, separator removal, diacritic stripping).
    """
    def __init__(
        self,
        config_path: str | Path | None = None,
        terms: list[str] | None = None,
        policy: _FilterPolicy | None = None,
    ) -> None:
        """
        Args:
            config_path: Path to a JSON config file.  Ignored if *terms*
                is provided.
            terms: Inline list of terms (overrides config file).
            policy: Filter policy.  Defaults to a redact policy.
        """
        if terms is not None:
            self._terms: list[str] = [t.lower() for t in terms]
        elif config_path is not None:
            self._terms = self._load_terms(Path(config_path))
        else:
            # Try default path
            if _DEFAULT_CONFIG_PATH.exists():
                self._terms = self._load_terms(_DEFAULT_CONFIG_PATH)
            else:
                self._terms = []
        self._policy = policy or _FilterPolicy(mode="redact")
        # Pre-compile patterns for each term
        self._patterns: list[tuple[re.Pattern[str], str]] = []
        for term in self._terms:
            if len(term) < self._policy.min_term_length:
                continue
            if self._policy.whole_word:
                pattern = re.compile(
                    r"(?<!\w)" + re.escape(term) + r"(?!\w)",
                    re.IGNORECASE if self._policy.case_insensitive else 0,
                )
            else:
                pattern = re.compile(
                    re.escape(term),
                    re.IGNORECASE if self._policy.case_insensitive else 0,
                )
            self._patterns.append((pattern, term))
    # -- config loading --------------------------------------------------
    @staticmethod
    def _load_terms(config_path: Path) -> list[str]:
        """Load terms from a JSON config file."""
        with open(config_path, "r", encoding="utf-8") as f:
            data: dict[str, Any] = json.load(f)
        terms: list[str] = []
        for raw in data.get("terms", []):
            term = str(raw).strip()
            if term:
                terms.append(term.casefold())
        return terms
    # -- public API ------------------------------------------------------
    def check(self, text: str) -> FilterResult:
        """Check *text* against the loaded term list.
        Returns a ``FilterResult`` with the appropriate action,
        filtered text, and matched terms.
        """
        if not text:
            return FilterResult(
                action=FilterAction.ALLOW,
                filtered_text=text,
                matched_terms=[],
            )
        normalized = _normalize(text)
        matched_terms: list[str] = []
        # Collect all matches
        for pattern, term in self._patterns:
            if pattern.search(normalized):
                if term not in matched_terms:
                    matched_terms.append(term)
        if not matched_terms:
            return FilterResult(
                action=FilterAction.ALLOW,
                filtered_text=text,
                matched_terms=[],
            )
        matched_terms.sort()
        # Build filtered text by replacing matched terms
        filtered = text
        for term in matched_terms:
            norm_term = _normalize(term)
            # Find all occurrences in the normalised text and replace in original
            # We need to map positions from normalised text back to original
            filtered = self._replace_terms(filtered, term, norm_term)
        action = FilterAction.REJECT if self._policy.mode == "reject" else FilterAction.REDACT
        return FilterResult(
            action=action,
            filtered_text=filtered,
            matched_terms=matched_terms,
        )
    def _replace_terms(
        self, text: str, term: str, norm_term: str
    ) -> str:
        """Replace occurrences of *term* in *text* with redaction chars.
        Uses normalised text for matching but preserves original casing
        in the output.
        """
        norm_text = _normalize(text)
        norm_term_len = len(norm_term)
        result_chars = list(text)
        start = 0
        while start < len(norm_text):
            idx = norm_text.find(norm_term, start)
            if idx == -1:
                break
            # Replace characters in original text
            for i in range(idx, min(idx + norm_term_len, len(result_chars))):
                result_chars[i] = self._policy.redaction_char
            start = idx + norm_term_len
        return "".join(result_chars)
    @property
    def terms(self) -> list[str]:
        """Read-only access to the loaded term list."""
        return list(self._terms)
    @property
    def policy(self) -> _FilterPolicy:
        """Read-only access to the filter policy."""
        return self._policy
 # ---------------------------------------------------------------------------
 # Factory
 # ---------------------------------------------------------------------------
 def get_text_filter(
    config_path: str | Path | None = None,
    terms: list[str] | None = None,
    policy: _FilterPolicy | None = None,
 ) -> TextFilter:
    """Return a ``TextFilter`` instance.
    By default this creates a ``ProfanityTextFilter``.  To use a
    third-party provider, subclass ``TextFilter`` and pass an
    instance here instead.
    """
    return ProfanityTextFilter(
        config_path=config_path,
        terms=terms,
        policy=policy,
    )