"""Text hygiene primitives — markdown, HTML, sanitization, entity candidates.

This package is the single source of truth for "text → clean content"
transformations used across AgntSpace. It exists so that every subsystem
(memory/graph extraction, KB ingest, web scraping, entity registration,
future NER/tokenization work) shares one well-tested implementation
instead of maintaining its own ad-hoc regex.

Design principles:

- **Syntactic, not lexical.** Rules operate on markdown/HTML syntax, not
  on vocabulary. There are no hardcoded phrase blocklists — a Swedish
  ``## Användarjournal`` is stripped by the same rules as an English
  ``## User Journal`` because both use the same ``##`` marker.
- **Language-agnostic.** Everything in this package is safe for any
  Unicode script. Case checks use Python's Unicode case methods.
  Punctuation checks use ``\\w`` (Unicode word characters). CJK, Arabic,
  Hebrew, and other non-cased scripts flow through unchanged.
- **Idempotent where possible.** ``strip_markdown_structure`` applied
  twice is equivalent to applying it once, which makes it safe to call
  defensively at multiple layers.
- **Composable.** Small pure functions with no hidden state. Every
  function takes and returns a string (or list of strings), so they
  chain cleanly and are trivial to unit-test.

Modules:

- ``markdown``  — strip markdown structure (headers, bullets, fences,
                  blockquotes, YAML frontmatter, HTML tags)
- ``html``      — strip web-clipper noise, extract readable text from HTML
- ``sanitize``  — normalize and validate entity names (chokepoint for
                  registry writes)
- ``candidates``— Unicode-aware Title Case entity candidate extractor
"""

from __future__ import annotations

from agntspace.text.candidates import extract_entity_candidates
from agntspace.text.html import extract_readable_text, strip_web_clipper_noise
from agntspace.text.markdown import strip_markdown_structure
from agntspace.text.sanitize import sanitize_name, strip_comma_descriptor

__all__ = [
    "extract_entity_candidates",
    "extract_readable_text",
    "sanitize_name",
    "strip_comma_descriptor",
    "strip_markdown_structure",
    "strip_web_clipper_noise",
]
