limatus 0.2.0__py3-none-any.whl

limatus/__init__.py

@@ -0,0 +1,3 @@
+"""Limatus: a diagnose-and-steer quality loop for AI-generated content."""
+
+__version__ = "0.2.0"

limatus/_util.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def hash_stable(value: Any) -> str:
+    if isinstance(value, str):
+        payload = value
+    else:
+        payload = json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def hash_short(value: Any) -> str:
+    return hash_stable(value)[:16]
+
+
+# Default model for constrained rewrite-option generation.
+DEFAULT_EDITORIAL_REWRITE_MODEL = "gpt-5.4-mini"

limatus/cli.py

@@ -0,0 +1,43 @@
+"""Limatus CLI entry point.
+
+    limatus diagnose --draft <file> --profile <style-profile.yml> [...]
+    limatus options  --draft <file> --profile <style-profile.yml> \\
+                      --diagnosis <diagnosis.json> --decisions <decisions.json> \\
+                      --skill <editorial-rewrite-skill.yml> [...]
+
+See editorial_commands.py for each subcommand's full flag set.
+"""
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+from .editorial_commands import editorial_diagnose, editorial_options
+
+COMMANDS = {
+    "diagnose": editorial_diagnose,
+    "options": editorial_options,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help"}:
+        print(__doc__)
+        return 0
+    if args[0] in {"-V", "--version"}:
+        print(f"limatus {__version__}")
+        return 0
+
+    command, flags = args[0], args[1:]
+    handler = COMMANDS.get(command)
+    if handler is None:
+        print(f"limatus: unknown command '{command}'. Try one of: {', '.join(sorted(COMMANDS))}")
+        return 1
+
+    handler(flags)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

limatus/editorial_commands.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .editorial_diagnosis import diagnose_draft
+from .editorial_diagnosis_schema import validate_diagnosis
+from .editorial_markup import render_annotated_markus, render_annotated_xml
+from .editorial_options_schema import validate_decisions
+from .editorial_rewrite_options import generate_rewrite_options
+from .editorial_style import load_style_profile
+from ._util import DEFAULT_EDITORIAL_REWRITE_MODEL
+
+
+def editorial_diagnose(flags: list[str]) -> None:
+    parser = argparse.ArgumentParser(prog="limatus diagnose")
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument("--draft", help="Path to the draft file (read-only).")
+    input_group.add_argument("--text", help="Draft text to diagnose without reading a file.")
+    parser.add_argument("--profile", required=True, help="Path to the style profile YAML.")
+    parser.add_argument("--output", default="", help="Optional path to write diagnostic JSON.")
+    parser.add_argument(
+        "--markup-out",
+        default="",
+        help="Optional path to write Markus-annotated Markdown (editorial-finding directives).",
+    )
+    parser.add_argument(
+        "--xml-out",
+        default="",
+        help="Optional path to write editorial annotation XML.",
+    )
+    args = parser.parse_args(flags)
+
+    profile_path = Path(args.profile).resolve()
+    if args.draft:
+        draft_path = Path(args.draft).resolve()
+        if not draft_path.is_file():
+            raise ValueError(f"Draft file not found: {draft_path}")
+        draft_text = draft_path.read_text(encoding="utf-8")
+    else:
+        draft_text = args.text
+
+    style_profile = load_style_profile(profile_path)
+    diagnosis = diagnose_draft(draft_text, style_profile=style_profile)
+    rendered = json.dumps(diagnosis, indent=2) + "\n"
+
+    if args.markup_out:
+        markup_path = Path(args.markup_out).resolve()
+        markup_path.write_text(render_annotated_markus(draft_text, diagnosis), encoding="utf-8")
+
+    if args.xml_out:
+        xml_path = Path(args.xml_out).resolve()
+        xml_path.write_text(render_annotated_xml(draft_text, diagnosis), encoding="utf-8")
+
+    if args.output:
+        output_path = Path(args.output).resolve()
+        output_path.write_text(rendered, encoding="utf-8")
+        return
+
+    sys.stdout.write(rendered)
+
+
+def editorial_options(flags: list[str]) -> None:
+    parser = argparse.ArgumentParser(prog="limatus options")
+    parser.add_argument("--draft", required=True, help="Path to the draft file (read-only).")
+    parser.add_argument("--profile", required=True, help="Path to the style profile YAML.")
+    parser.add_argument("--diagnosis", required=True, help="Path to validated diagnostic JSON.")
+    parser.add_argument("--decisions", required=True, help="Path to steering decisions JSON.")
+    parser.add_argument("--output", default="", help="Optional path to write options JSON.")
+    parser.add_argument("--model", default=DEFAULT_EDITORIAL_REWRITE_MODEL, help="OpenAI model id.")
+    parser.add_argument(
+        "--skill",
+        required=True,
+        help="Path to editorial rewrite skill YAML.",
+    )
+    args = parser.parse_args(flags)
+
+    draft_path = Path(args.draft).resolve()
+    if not draft_path.is_file():
+        raise ValueError(f"Draft file not found: {draft_path}")
+    draft_text = draft_path.read_text(encoding="utf-8")
+
+    diagnosis_path = Path(args.diagnosis).resolve()
+    decisions_path = Path(args.decisions).resolve()
+    diagnosis_payload = json.loads(diagnosis_path.read_text(encoding="utf-8"))
+    decisions_payload = json.loads(decisions_path.read_text(encoding="utf-8"))
+    if not isinstance(decisions_payload, list):
+        raise ValueError("Decisions JSON must be a list.")
+
+    style_profile = load_style_profile(Path(args.profile).resolve())
+    validate_diagnosis(diagnosis_payload)
+    validate_decisions(decisions_payload)
+
+    options = generate_rewrite_options(
+        draft_text,
+        style_profile=style_profile,
+        diagnosis=diagnosis_payload,
+        decisions=decisions_payload,
+        model=args.model,
+        skill_path=args.skill,
+    )
+    rendered = json.dumps(options, indent=2) + "\n"
+
+    if args.output:
+        output_path = Path(args.output).resolve()
+        output_path.write_text(rendered, encoding="utf-8")
+        return
+
+    sys.stdout.write(rendered)

limatus/editorial_corpus.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .editorial_style import StyleProfileValidationError
+
+
+def load_editorial_corpus_manifest(path: str | Path) -> dict[str, list[dict[str, Any]]]:
+    manifest_path = Path(path).resolve()
+    raw = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise StyleProfileValidationError(f"Editorial corpus manifest must be a mapping: {manifest_path}")
+
+    manifest: dict[str, list[dict[str, Any]]] = {"mustFail": [], "mustPass": []}
+    for section in ("mustFail", "mustPass"):
+        entries = raw.get(section)
+        if entries is None:
+            continue
+        if not isinstance(entries, list):
+            raise StyleProfileValidationError(f"{section} must be a list in {manifest_path}")
+        normalized: list[dict[str, Any]] = []
+        for index, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                raise StyleProfileValidationError(f"{section}[{index}] must be a mapping in {manifest_path}")
+            entry_id = str(entry.get("id", "")).strip()
+            rel_path = str(entry.get("path", "")).strip()
+            if not entry_id or not rel_path:
+                raise StyleProfileValidationError(
+                    f"{section}[{index}] requires id and path in {manifest_path}"
+                )
+            draft_path = (manifest_path.parent / rel_path).resolve()
+            if not draft_path.is_file():
+                raise StyleProfileValidationError(f"Corpus draft not found: {draft_path}")
+            normalized_entry = {"id": entry_id, "path": rel_path, "draftPath": str(draft_path)}
+            if section == "mustFail":
+                expect_terms = entry.get("expectTerms")
+                if not isinstance(expect_terms, list) or not expect_terms:
+                    raise StyleProfileValidationError(
+                        f"{section}[{index}].expectTerms must be a non-empty list in {manifest_path}"
+                    )
+                normalized_entry["expectTerms"] = [str(term).strip() for term in expect_terms if str(term).strip()]
+            else:
+                source_sample = entry.get("sourceSample")
+                if isinstance(source_sample, str) and source_sample.strip():
+                    normalized_entry["sourceSample"] = source_sample.strip()
+            normalized.append(normalized_entry)
+        manifest[section] = normalized
+    return manifest

limatus/editorial_density.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import gzip
+from dataclasses import dataclass
+from typing import Any
+
+from .editorial_diagnosis_schema import stable_finding_id
+from .editorial_text import sentence_spans, tokenize, word_count
+
+# Function-word inventory aligned with Ure (1971) / Halliday lexical-density practice.
+FUNCTION_WORDS: frozenset[str] = frozenset(
+    {
+        "a",
+        "about",
+        "above",
+        "after",
+        "again",
+        "against",
+        "all",
+        "am",
+        "an",
+        "and",
+        "any",
+        "are",
+        "as",
+        "at",
+        "be",
+        "because",
+        "been",
+        "before",
+        "being",
+        "below",
+        "between",
+        "both",
+        "but",
+        "by",
+        "can",
+        "could",
+        "did",
+        "do",
+        "does",
+        "doing",
+        "down",
+        "during",
+        "each",
+        "few",
+        "for",
+        "from",
+        "further",
+        "had",
+        "has",
+        "have",
+        "having",
+        "he",
+        "her",
+        "here",
+        "hers",
+        "herself",
+        "him",
+        "himself",
+        "his",
+        "how",
+        "i",
+        "if",
+        "in",
+        "into",
+        "is",
+        "it",
+        "its",
+        "itself",
+        "just",
+        "me",
+        "more",
+        "most",
+        "my",
+        "myself",
+        "no",
+        "nor",
+        "not",
+        "now",
+        "of",
+        "off",
+        "on",
+        "once",
+        "only",
+        "or",
+        "other",
+        "our",
+        "ours",
+        "ourselves",
+        "out",
+        "over",
+        "own",
+        "same",
+        "she",
+        "should",
+        "so",
+        "some",
+        "such",
+        "than",
+        "that",
+        "the",
+        "their",
+        "theirs",
+        "them",
+        "themselves",
+        "then",
+        "there",
+        "these",
+        "they",
+        "this",
+        "those",
+        "through",
+        "to",
+        "too",
+        "under",
+        "until",
+        "up",
+        "very",
+        "was",
+        "we",
+        "were",
+        "what",
+        "when",
+        "where",
+        "which",
+        "while",
+        "who",
+        "whom",
+        "why",
+        "will",
+        "with",
+        "would",
+        "you",
+        "your",
+        "yours",
+        "yourself",
+        "yourselves",
+    }
+)
+
+
+@dataclass(frozen=True)
+class DensityThresholds:
+    min_words: int
+    min_lexical_density: float
+    max_gzip_ratio: float
+
+
+@dataclass(frozen=True)
+class DensitySummary:
+    word_count: int
+    sentence_count: int
+    lexical_density: float
+    gzip_ratio: float
+
+
+@dataclass(frozen=True)
+class DensityAnalysis:
+    summary: DensitySummary
+    findings: tuple[dict[str, Any], ...]
+
+
+def lexical_density(tokens: list[str]) -> float:
+    if not tokens:
+        return 0.0
+    content_words = sum(1 for token in tokens if token not in FUNCTION_WORDS)
+    return content_words / len(tokens)
+
+
+def gzip_ratio(text: str) -> float:
+    encoded = text.encode("utf-8")
+    if not encoded:
+        return 1.0
+    compressed = gzip.compress(encoded)
+    return len(compressed) / len(encoded)
+
+
+def analyze_density(text: str, thresholds: DensityThresholds) -> DensityAnalysis:
+    normalized = text.replace("\r\n", "\n")
+    tokens = tokenize(normalized)
+    total_words = len(tokens)
+    total_sentences = len(sentence_spans(normalized))
+    density_value = lexical_density(tokens)
+    compression_value = gzip_ratio(normalized)
+
+    summary = DensitySummary(
+        word_count=total_words,
+        sentence_count=total_sentences,
+        lexical_density=round(density_value, 4),
+        gzip_ratio=round(compression_value, 4),
+    )
+
+    if total_words < thresholds.min_words:
+        return DensityAnalysis(summary=summary, findings=())
+
+    findings: list[dict[str, Any]] = []
+    if density_value < thresholds.min_lexical_density:
+        findings.append(
+            _document_finding(
+                "low_lexical_density",
+                normalized,
+                (
+                    "Document lexical density is below the profile threshold "
+                    f"({density_value:.3f} < {thresholds.min_lexical_density:.3f})."
+                ),
+            )
+        )
+    if compression_value <= thresholds.max_gzip_ratio:
+        findings.append(
+            _document_finding(
+                "high_compressibility",
+                normalized,
+                (
+                    "Document compresses unusually well for its length "
+                    f"(gzip ratio {compression_value:.3f} <= {thresholds.max_gzip_ratio:.3f})."
+                ),
+            )
+        )
+
+    return DensityAnalysis(summary=summary, findings=tuple(findings))
+
+
+def density_summary_as_dict(summary: DensitySummary) -> dict[str, Any]:
+    return {
+        "wordCount": summary.word_count,
+        "sentenceCount": summary.sentence_count,
+        "lexicalDensity": summary.lexical_density,
+        "gzipRatio": summary.gzip_ratio,
+    }
+
+
+def _document_finding(kind: str, text: str, rationale: str) -> dict[str, Any]:
+    start = 0
+    end = len(text)
+    return {
+        "id": stable_finding_id(kind, text, start, end),
+        "kind": kind,
+        "excerpt": text[start:end],
+        "span": {"start": start, "end": end},
+        "rationale": rationale,
+    }