nativeprompt 0.1.0__py3-none-any.whl

nativeprompt/__init__.py

@@ -0,0 +1,30 @@
+"""nativeprompt — перепиши промпт на РОДНОЙ диалект той модели/CLI, которой ты
+реально пользуешься (Claude Code / Codex), строго по ОФИЦИАЛЬНЫМ правилам вендора,
+и объясни почему.
+
+Zero-deps, stdlib-only, детерминированное ядро. См. README.md.
+"""
+
+__version__ = "0.1.0"
+
+from .catalog import load_family, available_families, RulesError
+from .detect import detect_model
+from .analyze import analyze, task_shape
+from .harness import recommend_harness
+from .rewrite import rewrite, build_metaprompt
+from .explain import build_report, render_report
+
+__all__ = [
+    "__version__",
+    "load_family",
+    "available_families",
+    "RulesError",
+    "detect_model",
+    "analyze",
+    "task_shape",
+    "recommend_harness",
+    "rewrite",
+    "build_metaprompt",
+    "build_report",
+    "render_report",
+]

nativeprompt/__main__.py

@@ -0,0 +1,162 @@
+"""CLI: nativeprompt <команда>.
+
+  improve "<промпт>" [--model M] [--json] [--no-metaprompt]   переписать + объяснить
+  detect [--model M]                                          какая модель определилась
+  rules [claude|codex]                                        показать правила + источники
+  update [--write] [--timeout N]                              сверить свежесть офиц. доков
+"""
+
+import argparse
+import json
+import sys
+
+from . import __version__, catalog, detect as _detect
+from .explain import build_report, render_report
+from . import update as _update
+
+
+def _read_prompt(arg):
+    if arg:
+        return arg
+    if not sys.stdin.isatty():
+        data = sys.stdin.read().strip()
+        if data:
+            return data
+    return None
+
+
+def cmd_improve(args):
+    prompt = _read_prompt(args.prompt)
+    if not prompt:
+        print("Дайте промпт: nativeprompt improve \"<текст>\"  (или через stdin).", file=sys.stderr)
+        return 2
+    report = build_report(prompt, model=args.model)
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return 0 if not report.get("error") else 1
+    print(render_report(report, show_metaprompt=not args.no_metaprompt))
+    return 0 if not report.get("error") else 1
+
+
+def cmd_detect(args):
+    res = _detect.resolve(args.model)
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+        return 0
+    if not res.get("family"):
+        print("Модель не определена. Задайте --model claude-opus-5 / gpt-5.6 / codex.")
+        print("Сигналы: env ANTHROPIC_MODEL/OPENAI_MODEL, ~/.claude/settings.json, ~/.codex/config.toml.")
+        return 1
+    gen = (" · " + res["generation"]) if res.get("generation") else ""
+    print("Модель: %s%s" % (res.get("model_id") or res["family"], gen))
+    print("Семейство/CLI: %s (%s)" % (res["family"], res.get("cli", "")))
+    print("Определено: %s" % res.get("source", "—"))
+    return 0
+
+
+def cmd_rules(args):
+    fam = args.family
+    if fam:
+        fam = catalog.family_for(fam) or fam
+        families = [fam]
+    else:
+        families = catalog.available_families()
+    for family in families:
+        try:
+            data = catalog.load_family(family)
+        except catalog.RulesError as e:
+            print(str(e), file=sys.stderr)
+            return 1
+        print("=" * 66)
+        print("%s — %s  (версия правил: %s)" % (data.get("display", family), data.get("vendor", ""), data.get("rules_version", "?")))
+        print(data.get("surface", ""))
+        print("=" * 66)
+
+        gens = data.get("generations", {})
+        if gens:
+            print("\nМОДЕЛИ, КОТОРЫЕ ИНСТРУМЕНТ ЗНАЕТ (%d):" % len(gens))
+            own = [g for g, v in gens.items() if v.get("doc")]
+            for gid, g in gens.items():
+                if g.get("doc"):
+                    mark, tail = "★", "своя страница правил у вендора"
+                elif g.get("rules_of"):
+                    mark, tail = "↳", "правила от %s (так решил вендор)" % g["rules_of"]
+                else:
+                    mark, tail = "·", "своей страницы нет — правила семейства"
+                print("  %s %-12s %-22s %s" % (mark, gid, g.get("label", ""), tail))
+            print("  ─ ★ %d из %d моделей имеют собственные правила; остальные работают"
+                  % (len(own), len(gens)))
+            print("    на правилах семейства — они НЕ выдуманы, их просто не публиковал вендор.")
+            print("    Незнакомая новая модель тоже получит правила семейства, а не откажет.")
+
+        print("\nПРАВИЛА:")
+        for r in data.get("rules", []):
+            scope = "" if r.get("scope") == "family" else ("  [%s]" % r["scope"])
+            print("• %s%s" % (r["title"], scope))
+            print("  %s" % r["source"])
+        h = data.get("harness")
+        if h:
+            print("\nХАРНЕСС (%s): когда какая команда" % h.get("cli", ""))
+            for c in h.get("commands", []):
+                print("  [%s] %s → %s" % (c.get("when"), c.get("title"), c.get("command")))
+                print("      %s" % c.get("source"))
+        print("")
+    return 0
+
+
+def cmd_update(args):
+    res = _update.update(write=args.write, timeout=args.timeout)
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+    else:
+        print(_update.render_update(res, show_diff=args.diff))
+    # ненулевой код, если нужны действия (для CI)
+    return 1 if res["summary"]["action_needed"] and not args.write else 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="nativeprompt",
+        description="Перепиши промпт под родной диалект твоей модели (Claude Code / Codex) по офиц. правилам вендора — и объясни почему.",
+    )
+    p.add_argument("--version", action="version", version="nativeprompt " + __version__)
+    sub = p.add_subparsers(dest="command")
+
+    pi = sub.add_parser("improve", help="переписать промпт под текущую модель + объяснить")
+    pi.add_argument("prompt", nargs="?", help="текст промпта (или из stdin)")
+    pi.add_argument("--model", help="целевая модель: claude-opus-5 / gpt-5.6 / codex …")
+    pi.add_argument("--json", action="store_true", help="выдать отчёт как JSON")
+    pi.add_argument("--no-metaprompt", action="store_true", help="без блока мета-промпта")
+    pi.set_defaults(func=cmd_improve)
+
+    pd = sub.add_parser("detect", help="показать, какая модель определилась")
+    pd.add_argument("--model", help="переопределить явно")
+    pd.add_argument("--json", action="store_true")
+    pd.set_defaults(func=cmd_detect)
+
+    pr = sub.add_parser("rules", help="показать правила + источники")
+    pr.add_argument("family", nargs="?", help="claude | codex (по умолчанию — все)")
+    pr.set_defaults(func=cmd_rules)
+
+    pu = sub.add_parser("update", help="сверить свежесть офиц. доков (self-update)")
+    pu.add_argument("--write", action="store_true", help="записать снимки (после ревью правил)")
+    pu.add_argument("--diff", action="store_true",
+                    help="показать, ЧТО именно изменилось в доке вендора (было → стало)")
+    pu.add_argument("--timeout", type=int, default=20)
+    pu.add_argument("--json", action="store_true")
+    pu.set_defaults(func=cmd_update)
+
+    return p
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nativeprompt/analyze.py

@@ -0,0 +1,297 @@
+"""Детерминированный разбор промпта: какие правила семейства «срабатывают»
+и какая у задачи форма (для рекомендации харнесса).
+
+Ноль обращений к модели — только регэкспы/эвристики (RU+EN). Каждый детектор
+привязан к правилу из rules/<family>.json по имени в поле "check".
+"""
+
+import re
+
+from . import catalog
+
+_CODING_VERB = re.compile(
+    r"(напиш|добав|почин|исправ|сдела|реализ|перепиш|отрефактор|рефактор|создай|"
+    r"удали|обнови|напис|implement|fix\b|add\b|write\b|refactor|create|build\b|"
+    r"update\b|remove\b|migrat|тест|debug|отлад)",
+    re.I,
+)
+_PATH = re.compile(
+    r"@|/|\b\w+\.(py|ts|tsx|js|jsx|go|rs|java|rb|php|json|md|html|css|scss|sql|yml|yaml|toml)\b"
+    r"|\bsrc\b|\bкаталог|\bпапк|\bмодул",
+    re.I,
+)
+_VERIFY_MEANS = re.compile(
+    r"(тест|test|сборк|build|pytest|jest|npm |lint|прогони|run |скрин|screenshot|"
+    r"exit code|assert|провер\w* (что|сборк|прошл)|passes|компилир)",
+    re.I,
+)
+
+
+def _coding_task(low):
+    return bool(_CODING_VERB.search(low))
+
+
+# ── детекторы (check-имена из шпаргалок) ─────────────────────────────
+def _c_always(p, low, t):
+    return True
+
+
+def _c_missing_context(p, low, t):
+    return _coding_task(low) and not _PATH.search(p)
+
+
+def _c_missing_verification(p, low, t):
+    return _coding_task(low) and not _VERIFY_MEANS.search(low)
+
+
+def _c_describe_location(p, low, t):
+    return bool(
+        re.search(r"(файл[,]?\s+(где|в котором|котор)|там,?\s+где|где-то в|"
+                  r"in the file (that|where)|the file that)", low)
+    ) and "@" not in p
+
+
+def _c_fix_symptom(p, low, t):
+    fix = re.search(r"(почин|исправ|fix)\b", low) and re.search(
+        r"(баг|ошибк|не работает|падает|failing|broken|\bbug\b|crash|сломал)", low
+    )
+    detail = re.search(r"(причин|root cause|симптом|потому что|because|@|/|src)", low)
+    return bool(fix) and not detail
+
+
+def _c_missing_output_contract(p, low, t):
+    produce = re.search(
+        r"(напиш|сдела|сгенер|состав|выведи|подготов|summar|\blist\b|generate|"
+        r"\bwrite\b|отчёт|report|объясн|explain)",
+        low,
+    )
+    fmt = re.search(
+        r"(формат|в виде|верни|возврат|структур|json|таблиц|список|markdown|bullet|"
+        r"ответь\s|\bformat\b|\boutput\b|критери\w* готов|что считается|counts as done|"
+        r"exit 0|ok или fail|ok/fail)",
+        low,
+    )
+    return bool(produce) and not fmt
+
+
+def _c_vague_ask(p, low, t):
+    return bool(
+        re.search(
+            r"(не мог(ли)? бы (ты|вы)|мог бы ты|можешь ли ты|\bможешь\b|could you|"
+            r"can you|would you|пожалуйста,?\s+(предлож|подумай|посмотр)|давай(те)? попроб)",
+            low,
+        )
+    )
+
+
+def _c_pushy_caps(p, low, t):
+    if re.search(r"!!!", p):
+        return True
+    if re.search(r"\b(КРИТИЧНО|ОБЯЗАТЕЛЬНО|ВАЖНО|СРОЧНО|CRITICAL|MUST|ALWAYS|NEVER|IMPORTANT)\b", p):
+        return True
+    if re.search(r"\b(ты|вы|you)\s+(ДОЛЖЕН|ДОЛЖНЫ|ОБЯЗАН|MUST)\b", p):
+        return True
+    return False
+
+
+def _c_missing_xml(p, low, t):
+    if t.get("family") != "claude":
+        return False
+    multi = len(p) > 500 or bool(
+        re.search(r"(пример:|example:|данные:|контекст:|вот текст|```|<<<|инструкци\w*:)", low)
+    )
+    has_xml = re.search(r"<[a-zA-Z_][a-zA-Z0-9_]*>", p)
+    return multi and not has_xml
+
+
+def _c_verification_demand(p, low, t):
+    return bool(
+        re.search(
+            r"(перепровер|убедись,?\s+что|дважды провер|double.?check|re-?verify|"
+            r"verify your|проверь себя|make sure you|тщательно проверь)",
+            low,
+        )
+    )
+
+
+def _c_report_only_high(p, low, t):
+    return bool(
+        re.search(
+            r"(только\s+(важн|критич|серьёзн|high|severe|major|значим)|report only|"
+            r"только самое важное|only (high|critical|major|the most))",
+            low,
+        )
+    )
+
+
+def _c_forced_cot(p, low, t):
+    return bool(
+        re.search(
+            r"(думай пошагово|шаг за шагом|по шагам|пошагово|think step by step|"
+            r"step[- ]by[- ]step|let'?s think|chain of thought|рассуждай вслух|"
+            r"распиши (свои )?рассуждени|покажи ход мыслей)",
+            low,
+        )
+    )
+
+
+def _c_repetition(p, low, t):
+    sents = [s.strip() for s in re.split(r"[.!?\n]+", low) if len(s.strip()) > 12]
+    seen = {}
+    for s in sents:
+        seen[s] = seen.get(s, 0) + 1
+        if seen[s] >= 2:
+            return True
+    for key in ("обязательно", "сначала спроси", "не забудь", "напоминаю"):
+        if low.count(key) >= 2:
+            return True
+    return False
+
+
+def _c_contradiction_hint(p, low, t):
+    pairs = [
+        ("кратко", "подробно"),
+        ("кратко", "детальн"),
+        ("коротко", "развернут"),
+        ("markdown", "без форматирован"),
+        ("без форматирован", "в формате"),
+        ("быстро", "тщательно"),
+        ("brief", "detailed"),
+    ]
+    return any(a in low and b in low for a, b in pairs)
+
+
+def _c_needs_agents_md(p, low, t):
+    if t.get("family") != "openai":
+        return False
+    return bool(
+        re.search(
+            r"(всегда|каждый раз|во всех задачах|в целом по проекту|стиль кода|"
+            r"code style|always use|every time|по всему проекту)",
+            low,
+        )
+    )
+
+
+_CHECKS = {
+    "always": _c_always,
+    "missing_context": _c_missing_context,
+    "missing_verification": _c_missing_verification,
+    "describe_location": _c_describe_location,
+    "fix_symptom": _c_fix_symptom,
+    "missing_output_contract": _c_missing_output_contract,
+    "vague_ask": _c_vague_ask,
+    "pushy_caps": _c_pushy_caps,
+    "missing_xml": _c_missing_xml,
+    "verification_demand": _c_verification_demand,
+    "report_only_high": _c_report_only_high,
+    "forced_cot": _c_forced_cot,
+    "repetition": _c_repetition,
+    "contradiction_hint": _c_contradiction_hint,
+    "needs_agents_md": _c_needs_agents_md,
+}
+
+
+def analyze(prompt, target):
+    """Вернуть список сработавших правил (findings) для данной модели.
+
+    target: {family, generation}. Правила scope='family' проверяются всегда;
+    scope=<generation-id> — только если target.generation совпадает.
+    Правила с action='add'/check='always' не включаем в findings как «проблему»,
+    их подхватывает rewrite/harness (кроме явных — они попадают в 'additions').
+    """
+    family = target.get("family")
+    if not family:
+        return []
+    data = catalog.load_family(family)
+    low = prompt.lower()
+    shape = None
+    findings = []
+    # поколение + те, чьи правила вендор объявил применимыми к нему (rules_of):
+    # Mythos 5 ключуется на страницу Fable 5, Opus 4.7 — на guidance Opus 4.8
+    scopes = catalog.scopes_for(family, target.get("generation"))
+    for rule in data.get("rules", []):
+        scope = rule.get("scope", "family")
+        if scope != "family" and scope not in scopes:
+            continue
+        allowed_shapes = rule.get("when_shapes")
+        if allowed_shapes:
+            if shape is None:
+                shape = task_shape(prompt)
+            if shape not in allowed_shapes:
+                continue
+        check = rule.get("check", "always")
+        fn = _CHECKS.get(check)
+        if fn is None:
+            continue
+        if check == "always":
+            # 'always'-правила — это добавления по умолчанию для поколения,
+            # их показываем как рекомендации, но помечаем отдельно
+            findings.append(_as_finding(rule, always=True))
+            continue
+        if fn(prompt, low, target):
+            findings.append(_as_finding(rule, always=False))
+    return findings
+
+
+def _as_finding(rule, always):
+    return {
+        "id": rule["id"],
+        "title": rule["title"],
+        "action": rule.get("action", "warn"),
+        "why": rule.get("why", ""),
+        "source": rule.get("source", ""),
+        "check": rule.get("check", ""),
+        "scope": rule.get("scope", "family"),
+        "always": always,
+    }
+
+
+# ── форма задачи (для харнесса) ──────────────────────────────────────
+_SHAPE_WORKFLOW = re.compile(
+    r"(по всем файлам|во всех файлах|(все|всех|каждый|каждого)\s+файл\w*|по всему проекту|"
+    r"across (all|every)|every file|codebase[- ]wide|весь проект целиком|тысяч\w* файл|"
+    r"аудит безопасност|security audit|миграци\w* тысяч|(entire|whole) codebase)",
+    re.I,
+)
+_SHAPE_LOOP = re.compile(
+    r"(кажд(ый|ое|ую)\s+(день|утро|ночь|неделю|час)|ежедневн|ежечас|nightly|"
+    r"по расписани|periodic|every (night|morning|day|hour|week)|раз в день|раз в час)",
+    re.I,
+)
+_SHAPE_GOAL = re.compile(
+    r"((пока|until|до тех пор)\b[^.\n]{0,60}"
+    r"(пройд|прошл|проход|зелён|готов|заверш|compil|pass|hold|green|empty|исчез|пуст|clean|чист)"
+    r"|до зелён|all tests pass|acceptance criteria|критери\w* приёмк|до готовн|backlog|"
+    r"очередь задач|доведи до|доведи задачу)",
+    re.I,
+)
+_SHAPE_PLANNING = re.compile(
+    r"(как лучше|какой подход|с чего начать|спроектир|design (a|the)|архитектур|"
+    r"architecture|отрефактор|\brefactor\b|не уверен|несколько файлов|multiple files|"
+    r"how (should|do) (i|we)|продумай план|состав\w* план|нужно продумать)",
+    re.I,
+)
+_SHAPE_TRIVIAL = re.compile(
+    r"(переименуй|опечат|\btypo\b|\brename\b|добавь лог|add a log|подправь|"
+    r"поправь мелк|один символ|измени строк)",
+    re.I,
+)
+
+
+def task_shape(prompt):
+    """Классифицировать задачу: workflow | loop | goal | planning | trivial | normal."""
+    low = prompt.lower()
+    if _SHAPE_WORKFLOW.search(low):
+        return "workflow"
+    if _SHAPE_LOOP.search(low):
+        return "loop"
+    if _SHAPE_GOAL.search(low):
+        return "goal"
+    if _SHAPE_PLANNING.search(low):
+        return "planning"
+    if len(prompt.strip()) <= 120 and _SHAPE_TRIVIAL.search(low):
+        return "trivial"
+    if len(prompt.strip()) <= 90 and _coding_task(low):
+        return "trivial"
+    return "normal"

nativeprompt/catalog.py

@@ -0,0 +1,99 @@
+"""Загрузка шпаргалок правил (rules/*.json) и выбор семейства по имени модели."""
+
+import json
+import os
+
+_RULES_DIR = os.path.join(os.path.dirname(__file__), "rules")
+_CACHE = {}
+
+
+class RulesError(Exception):
+    pass
+
+
+def _rules_path(name):
+    return os.path.join(_RULES_DIR, name + ".json")
+
+
+def available_families():
+    """Список доступных семейств (по файлам rules/<family>.json, кроме служебных)."""
+    out = []
+    for fn in sorted(os.listdir(_RULES_DIR)):
+        if fn.endswith(".json") and not fn.startswith("_"):
+            out.append(fn[:-5])
+    return out
+
+
+def load_family(family):
+    """Загрузить шпаргалку семейства ('claude' | 'openai'). Кэшируется."""
+    if family in _CACHE:
+        return _CACHE[family]
+    path = _rules_path(family)
+    if not os.path.exists(path):
+        raise RulesError(
+            "Нет шпаргалки для семейства %r. Доступны: %s"
+            % (family, ", ".join(available_families()))
+        )
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    _CACHE[family] = data
+    return data
+
+
+def load_sources():
+    """Манифест самообновления (_sources.json)."""
+    path = _rules_path("_sources")
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def family_for(family_or_alias):
+    """Нормализовать вход ('claude code', 'codex', 'gpt', ...) в id семейства."""
+    key = (family_or_alias or "").strip().lower()
+    if not key:
+        return None
+    for fam in available_families():
+        data = load_family(fam)
+        if key == fam:
+            return fam
+        det = data.get("detect", {})
+        for alias in det.get("aliases", []):
+            if key == alias.lower():
+                return fam
+    return None
+
+
+def scopes_for(family, generation):
+    """Какие scope-ключи применимы к этому поколению.
+
+    Вендор иногда прямо пишет, что правила одной модели применимы к другой
+    (Mythos 5 ключуется на страницу Fable 5; guidance Opus 4.7 применим к 4.8).
+    Такие связи описаны полем "rules_of" в generations — здесь мы их
+    разворачиваем, чтобы правило с scope="fable-5" сработало и для mythos-5.
+    """
+    if not generation:
+        return set()
+    data = load_family(family)
+    gens = data.get("generations", {})
+    out, cur, guard = {generation}, generation, 0
+    while guard < 5:
+        parent = (gens.get(cur) or {}).get("rules_of")
+        if not parent or parent in out:
+            break
+        out.add(parent)
+        cur = parent
+        guard += 1
+    return out
+
+
+def generation_for(family, model_id):
+    """По id/имени модели найти поколение внутри семейства (например 'opus-5')."""
+    if not model_id:
+        return None
+    data = load_family(family)
+    m = model_id.strip().lower().replace(" ", "-")
+    for gen_id, gen in data.get("generations", {}).items():
+        for token in gen.get("match", []):
+            if token.lower() in m:
+                return gen_id
+    return None