Check Ukrainian text for calque-prone phrases and naturalness.

Returns spans flagged as: • calque-prone — phrase appears in the antisurzhyk book corpus (Сербенська, Караванський, Антоненко-Давидович) as something to avoid; prefer gives the recommended alternative. • natural — phrase is attested as a high/medium-confidence rendering in the 29k-sense corpus.

Use this AFTER drafting Ukrainian text, BEFORE returning it to the user. Rewrite calque-prone spans before delivering your response.

Args: text: Ukrainian text (2 chars min).

Returns: { "input": str, "spans": [ {"span": str, "start": int, "end": int, "verdict": "calque-prone" | "natural", "prefer": str | None, # for calque-prone "for_en": str | None, # for natural "source": str | None, "source_url": str}, ... ], "summary": {"calque_prone": int, "natural": int, "score": float}, "citation": {...}, }

Full Ukrainian grammar + spelling + surzhyk check.

Runs LanguageTool, 1400+ hand-written rules, a fine-tuned russianism detection model, and the antisurzhyk book corpus. Returns position-indexed issues with severity and replacement suggestions.

Use this when the user asks "is my Ukrainian correct?" or you want to validate Ukrainian text comprehensively (not just naturalness).

Args: text: Ukrainian text (up to ~5000 chars).

Returns: { "issues": [ {"rule_id": str, "offset": int, "length": int, "message": str, "suggestion": str | None, "severity": "error" | "warning" | "hint", "source": str, "category": str | None}, ... ], "stats": {"word_count": int, "errors": int, "warnings": int, ...}, "engine_version": str, "citation": {...}, }

Get authentic Ukrainian renderings for an English word or sense.

Returns multiple natural UA renderings sourced from Балла EN-UA Dictionary (1996), e2u.org.ua, and modern corpora. When the English word is polysemous, each sense is returned with its own renderings.

Use this for translation or vocabulary tasks where you want idiomatic Ukrainian (not a calque or AI-guessed translation).

Args: en: English word (lemma or surface). sense: Optional sense filter (substring match on sense description).

Returns: { "en_key": str, "senses": [ {"sense": str, "explanation": str, "level": str, "renderings": [{"phrase": str, "confidence": str, "n_sources": int, ...}, ...], "permalink": str}, ... ], "citation": {...}, }

Get the citation chain for a Ukrainian phrase.

Returns independent attestations from configured primary sources — Балла 1996 (with page numbers), e2u.org.ua, r2u.org.ua (which hosts Karavansky's RU-UA dictionaries cleanly), Сербенська's Антисуржик, Антоненко-Давидович's Як ми говоримо, uk.wiktionary, slovnyk.ua, and more.

Use this when:

• You need to back up a claim about Ukrainian usage with cited evidence

• You're explaining why a particular word/phrase is correct or preferable, and want to point to authoritative sources

• You want to find historical attestation (pre-Soviet UA, etc.)

Args: phrase: Any Ukrainian phrase (single word or multi-word). sources: Optional comma-separated source IDs to limit the query (e.g., "e2u,r2u" or "balla,wiktionary"). Default: all.

Returns: { "phrase": str, "confidence": "high" | "medium" | "tentative" | "missing" | "rejected", "attestation_count": int, "attestations": [ {"source_id": str, "kind": str, "ref": str, "url": str | None, "verbatim": str | None, "context": str | None, "confidence": float}, ... ], "canonical": str, # the citable API URL for this lookup "citation": {...}, }

Search the 29k EN→UA sense index.

Returns matching entries with sense descriptions, CEFR level, and permalinks to the full sense pages. Useful for vocabulary lookups, finding related words, or grounding a translation in attested entries.

Args: query: English keyword or partial match. level: Optional CEFR filter — one of A1, A2, B1, B2, C1, C2. limit: Max results (1..100, default 20).

Returns: { "count": int, "results": [ {"en_key": str, "sense": str, "level": str, "ps": str, "permalink": str}, ... ], "citation": {...}, }