ltcai 11.2.0 → 11.4.0

package/latticeai/core/file_generation/extraction.py

@@ -0,0 +1,154 @@
+"""Recover the intended file payload from an arbitrary model reply.
+
+Step 2 of the pipeline described in the package docstring: strip reasoning
+blocks and conversational framing, pick the best fenced block, and slice known
+document boundaries. Pure string work — nothing here decides whether the result
+is *good*, only what the model most plausibly meant to hand over.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Dict, List, Optional, Tuple
+
+from latticeai.core.quiet import quiet
+
+_THINK_BLOCK_RE = re.compile(
+    r"<(think|thinking|reasoning|reflection)>.*?</\1>",
+    re.DOTALL | re.IGNORECASE,
+)
+# Unclosed think block (model hit the token limit mid-reasoning).
+_THINK_OPEN_RE = re.compile(r"<(think|thinking|reasoning)>.*\Z", re.DOTALL | re.IGNORECASE)
+
+_FENCE_RE = re.compile(r"```([\w.+-]*)[ \t]*\n(.*?)```", re.DOTALL)
+
+# Conversational lines that small models prepend/append around the payload.
+_CHAT_LINE_RE = re.compile(
+    r"^\s*("
+    r"(sure|of course|certainly|okay|ok|alright|great|absolutely)\b[^\n]*"
+    r"|here('s| is| are)\b[^\n]*"
+    r"|i('ve| have) (created|written|generated|made)\b[^\n]*"
+    r"|(below|following) is\b[^\n]*"
+    r"|let me know\b[^\n]*"
+    r"|hope (this|that) helps[^\n]*"
+    r"|feel free\b[^\n]*"
+    r"|물론(입니다|이죠|이에요)?[!., ]*[^\n]*"
+    r"|네[,!. ][^\n]*"
+    r"|알겠습니다[^\n]*"
+    r"|다음은[^\n]*(입니다|합니다)[:.]?[^\n]*"
+    r"|아래는?[^\n]*(입니다|내용)[^\n]*"
+    r"|(요청하신|원하시는)[^\n]*(입니다|만들었습니다|작성했습니다)[^\n]*"
+    r"|(파일|내용|코드)[을를]?\s*(생성|작성|만들)[^\n]*"
+    r"|도움이 (필요하|되)[^\n]*"
+    r"|추가로[^\n]*(말씀|요청)[^\n]*"
+    r")\s*$",
+    re.IGNORECASE,
+)
+
+
+# Language tags that identify a fenced block as the payload for an extension.
+_EXT_FENCE_LANGS: Dict[str, Tuple[str, ...]] = {
+    ".html": ("html", "htm", "xhtml"),
+    ".htm": ("html", "htm", "xhtml"),
+    ".css": ("css",),
+    ".js": ("js", "javascript"),
+    ".jsx": ("jsx", "javascript"),
+    ".ts": ("ts", "typescript"),
+    ".tsx": ("tsx", "typescript"),
+    ".py": ("py", "python"),
+    ".json": ("json",),
+    ".yaml": ("yaml", "yml"),
+    ".yml": ("yaml", "yml"),
+    ".toml": ("toml",),
+    ".md": ("md", "markdown"),
+    ".markdown": ("md", "markdown"),
+    ".sql": ("sql",),
+    ".sh": ("sh", "bash", "shell", "zsh"),
+    ".xml": ("xml", "svg"),
+    ".csv": ("csv",),
+    ".txt": ("txt", "text", "plaintext"),
+    ".vue": ("vue", "html"),
+    ".svelte": ("svelte", "html"),
+}
+
+
+def _ext(path: str) -> str:
+    dot = path.rfind(".")
+    return path[dot:].lower() if dot >= 0 else ""
+
+
+def _strip_chat_lines(text: str) -> str:
+    """Drop leading/trailing conversational lines around the payload."""
+    lines = text.split("\n")
+    start, end = 0, len(lines)
+    while start < end and (not lines[start].strip() or _CHAT_LINE_RE.match(lines[start])):
+        start += 1
+    while end > start and (not lines[end - 1].strip() or _CHAT_LINE_RE.match(lines[end - 1])):
+        end -= 1
+    stripped = "\n".join(lines[start:end]).strip()
+    return stripped if stripped else text.strip()
+
+
+def extract_file_content(raw: str, target_path: str) -> str:
+    """Recover the intended file payload from an arbitrary model reply."""
+    text = (raw or "").strip()
+    if not text:
+        return ""
+    text = _THINK_BLOCK_RE.sub("", text)
+    text = _THINK_OPEN_RE.sub("", text).strip()
+
+    ext = _ext(target_path)
+    fences = _FENCE_RE.findall(text + ("\n```" if text.count("```") % 2 else ""))
+    if fences:
+        wanted = _EXT_FENCE_LANGS.get(ext, ())
+        matching = [body for lang, body in fences if lang.lower() in wanted]
+        candidates = matching if matching else [body for _, body in fences]
+        # The payload is the largest block; short blocks are usually usage
+        # snippets ("run it with: python app.py").
+        content = max(candidates, key=len).strip()
+    else:
+        content = _strip_chat_lines(text)
+
+    if ext in (".html", ".htm"):
+        content = _slice_html_document(content)
+    elif ext == ".json":
+        sliced = _slice_json_document(content)
+        if sliced is not None:
+            content = sliced
+    return content.strip()
+
+
+def _slice_html_document(content: str) -> str:
+    """Cut a complete HTML document out of surrounding prose when present."""
+    lower = content.lower()
+    start = lower.find("<!doctype")
+    if start < 0:
+        start = lower.find("<html")
+    if start > 0:
+        content = content[start:]
+        lower = lower[start:]
+    end = lower.rfind("</html>")
+    if end >= 0:
+        content = content[: end + len("</html>")]
+    return content
+
+
+def _slice_json_document(content: str) -> Optional[str]:
+    """Return the largest parseable JSON value inside ``content``, if any."""
+    candidates: List[str] = [content]
+    for opener, closer in (("{", "}"), ("[", "]")):
+        start = content.find(opener)
+        end = content.rfind(closer)
+        if start >= 0 and end > start:
+            candidates.append(content[start : end + 1])
+    best: Optional[str] = None
+    for candidate in candidates:
+        try:
+            json.loads(candidate)
+        except (ValueError, TypeError):
+            quiet()
+            continue
+        if best is None or len(candidate) > len(best):
+            best = candidate
+    return best

package/latticeai/core/file_generation/inference.py

@@ -0,0 +1,235 @@
+"""What the user asked for, when they never said a filename.
+
+Two deliberately narrow, fully deterministic inferences (weak local models
+never see either decision): a single filename for "html 파일 만들어줘", and a
+multi-file project manifest for "todo 앱 html+css+js로 만들어줘". Both require
+a creation verb and an explicit type keyword, so anything less specific keeps
+flowing to the paths that handled it before.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+_CREATE_VERB_RE = re.compile(
+    r"(만들|생성|작성|써\s*줘|저장|create|make|write|generate|build|save)",
+    re.IGNORECASE,
+)
+
+
+# Explicit type keyword → default filename. Ordered: first match wins.
+_TYPE_KEYWORDS: Tuple[Tuple[str, str], ...] = (
+    (r"\bhtml\b|웹\s*페이지|웹페이지|홈페이지|landing\s*page|web\s*page", "generated_page.html"),
+    (r"\bcss\b|스타일\s*시트", "styles.css"),
+    (r"\bjavascript\b|\bjs\b\s*(파일|file)|자바스크립트", "script.js"),
+    (r"\bpython\b|파이썬", "script.py"),
+    (r"\bjson\b", "data.json"),
+    (r"\bcsv\b", "data.csv"),
+    (r"\byaml\b|\byml\b", "config.yaml"),
+    (r"\bxml\b", "data.xml"),
+    (r"\bsql\b", "query.sql"),
+    (r"마크다운|\bmarkdown\b|\bmd\b\s*(파일|file)", "notes.md"),
+    (r"텍스트\s*파일|\btext\s*file\b|\btxt\b", "notes.txt"),
+)
+
+
+def infer_file_target(message: str) -> Optional[str]:
+    """Infer a filename for creation requests that name a type but no path.
+
+    "html 파일 만들어줘" previously fell through to the agent JSON loop, which
+    small models fail at. Inference keeps such requests on the deterministic
+    direct-write path. Deliberately narrow: requires a creation verb and an
+    explicit file-type keyword — report/document prose requests keep flowing
+    to the document generator.
+    """
+    text = (message or "").strip()
+    if not text or not _CREATE_VERB_RE.search(text):
+        return None
+    lower = text.lower()
+    for pattern, filename in _TYPE_KEYWORDS:
+        if re.search(pattern, lower):
+            return filename
+    return None
+
+
+# ``\b`` fails against Korean particles ("js로") because Hangul is ``\w`` —
+# use ASCII lookarounds so type keywords match with or without a particle.
+_HTML_HINT_RE = re.compile(
+    r"(?<![a-z0-9])html(?![a-z0-9])"
+    r"|웹\s*페이지|웹페이지|홈페이지|웹\s*사이트|웹사이트|website|web\s*page|landing\s*page",
+)
+_CSS_HINT_RE = re.compile(r"(?<![a-z0-9])css(?![a-z0-9])|스타일\s*시트|stylesheet")
+_JS_HINT_RE = re.compile(
+    r"(?<![a-z0-9])js(?![a-z0-9])|javascript|자바스크립트|자바\s*스크립트"
+)
+# An explicit filename means the user is managing paths — keep the
+# deterministic single-file flow untouched.
+_EXPLICIT_FILENAME_RE = re.compile(
+    r"[\w-]+\.(?:html?|css|js|jsx|ts|tsx|py|json|md|txt|csv|vue|svelte)\b",
+    re.IGNORECASE,
+)
+_PROJECT_NAME_RE = re.compile(r"([A-Za-z][A-Za-z0-9_-]{1,30})\s*(?:앱|app\b)", re.IGNORECASE)
+# React/Vite intent: the react keyword is specific enough on its own.
+_REACT_HINT_RE = re.compile(r"(?<![a-z0-9])react(?![a-z0-9])|리액트")
+_VITE_HINT_RE = re.compile(r"(?<![a-z0-9])vite(?![a-z0-9])")
+# Python package intent: language + package word, both required.
+_PYTHON_HINT_RE = re.compile(r"(?<![a-z0-9])python(?![a-z0-9])|파이썬")
+_PACKAGE_HINT_RE = re.compile(r"패키지|(?<![a-z0-9])package(?![a-z0-9])")
+_PKG_NAME_RE = re.compile(
+    r"([A-Za-z][A-Za-z0-9_-]{1,30})\s*(?:패키지|package\b)", re.IGNORECASE
+)
+
+
+def _react_manifest(text: str) -> Dict[str, Any]:
+    """Vite + React starter manifest (review Wave 4: manifest 확장)."""
+    name_match = _PROJECT_NAME_RE.search(text)
+    name = f"{name_match.group(1).lower()}-app" if name_match else "react-app"
+    return {
+        "name": name,
+        "kind": "react",
+        "files": [
+            {
+                "path": "package.json",
+                "brief": (
+                    f'Vite React app manifest: strictly valid JSON with "name": "{name}", '
+                    '"private": true, "type": "module", "scripts" {"dev": "vite", '
+                    '"build": "vite build", "preview": "vite preview"}, "dependencies" '
+                    'with react and react-dom (^18), and "devDependencies" with vite '
+                    "and @vitejs/plugin-react."
+                ),
+            },
+            {
+                "path": "index.html",
+                "brief": (
+                    "The Vite entry HTML: <div id=\"root\"></div> in <body> and "
+                    "<script type=\"module\" src=\"/src/main.jsx\"></script> just "
+                    "before </body>. No inline styles or scripts."
+                ),
+            },
+            {
+                "path": "src/main.jsx",
+                "brief": (
+                    "React entry: createRoot from react-dom/client rendering <App /> "
+                    "into #root; imports ./App.jsx and ./App.css."
+                ),
+            },
+            {
+                "path": "src/App.jsx",
+                "brief": (
+                    "The main App component implementing the user's request as one "
+                    "self-contained React component (hooks allowed, no extra deps)."
+                ),
+            },
+            {
+                "path": "src/App.css",
+                "brief": "All visual styles for the App component.",
+            },
+        ],
+    }
+
+
+def _python_package_manifest(text: str) -> Dict[str, Any]:
+    """Multi-file Python package manifest (review Wave 4: manifest 확장)."""
+    name_match = _PKG_NAME_RE.search(text)
+    raw_name = name_match.group(1).lower() if name_match else "my_package"
+    module = re.sub(r"[^a-z0-9_]", "_", raw_name)
+    if not re.match(r"[a-z_]", module):
+        module = f"pkg_{module}"
+    return {
+        "name": module,
+        "kind": "python",
+        "files": [
+            {
+                "path": f"{module}/__init__.py",
+                "brief": (
+                    f"Package init for {module}: import and re-export the public "
+                    "API from .core with an explicit __all__."
+                ),
+            },
+            {
+                "path": f"{module}/core.py",
+                "brief": (
+                    "Implement the user's request as clean, documented functions/"
+                    "classes with type hints. Standard library only."
+                ),
+            },
+            {
+                "path": f"{module}/cli.py",
+                "brief": (
+                    "argparse CLI wrapping the core API: a main() function and an "
+                    'if __name__ == "__main__": main() guard.'
+                ),
+            },
+            {
+                "path": "README.md",
+                "brief": (
+                    f"Usage documentation for the {module} package: install, import "
+                    "example, and CLI example."
+                ),
+            },
+        ],
+    }
+
+
+def infer_project_manifest(message: str) -> Optional[Dict[str, Any]]:
+    """Infer a multi-file project manifest from a creation request.
+
+    "todo 앱 html+css+js로 만들어줘" should yield real linked files, not one
+    inlined page. Deliberately narrow and deterministic (weak local models
+    never see this decision): requires a creation verb, a recognized project
+    intent (web page + css/js, React/Vite app, or Python package), and no
+    explicit filename. Single-type requests return ``None`` so the existing
+    single-file flow is completely unchanged.
+    """
+    text = (message or "").strip()
+    if not text or not _CREATE_VERB_RE.search(text):
+        return None
+    if _EXPLICIT_FILENAME_RE.search(text):
+        return None
+    lower = text.lower()
+
+    # Most-specific first: React (its own structure), then Python package,
+    # then the classic html+css/js web bundle.
+    if _REACT_HINT_RE.search(lower) or _VITE_HINT_RE.search(lower):
+        return _react_manifest(text)
+    if _PYTHON_HINT_RE.search(lower) and _PACKAGE_HINT_RE.search(lower):
+        return _python_package_manifest(text)
+
+    wants_html = bool(_HTML_HINT_RE.search(lower))
+    wants_css = bool(_CSS_HINT_RE.search(lower))
+    wants_js = bool(_JS_HINT_RE.search(lower))
+    if not wants_html or not (wants_css or wants_js):
+        return None
+
+    name_match = _PROJECT_NAME_RE.search(text)
+    name = f"{name_match.group(1).lower()}-app" if name_match else "web-project"
+
+    files: List[Dict[str, str]] = []
+    html_refs: List[str] = []
+    if wants_css:
+        html_refs.append('<link rel="stylesheet" href="style.css"> in <head>')
+    if wants_js:
+        html_refs.append('<script src="app.js"></script> just before </body>')
+    files.append({
+        "path": "index.html",
+        "brief": (
+            "The main HTML page of the project. Reference the sibling files: "
+            + " and ".join(html_refs)
+            + ". Do not inline styles or behavior scripts."
+        ),
+    })
+    if wants_css:
+        files.append({
+            "path": "style.css",
+            "brief": "All visual styles for index.html (layout, colors, typography).",
+        })
+    if wants_js:
+        files.append({
+            "path": "app.js",
+            "brief": (
+                "All page behavior for index.html as plain browser JavaScript "
+                "(no build step, no imports of missing files)."
+            ),
+        })
+    return {"name": name, "kind": "web", "files": files}

package/latticeai/core/file_generation/orchestration.py

@@ -0,0 +1,152 @@
+"""Prompt → extract → validate → retry → repair, in that order.
+
+The pipeline's driver. ``generate_file_content`` is the only place the model
+is actually called; every other module here is pure. The salvage score decides
+which rejected candidate repair gets to work from — closest to a file, not
+longest.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple
+
+from .extraction import _ext, _slice_json_document, extract_file_content
+from .prompting import build_file_generation_context
+from .repair import repair_file_content
+from .validation import (
+    _BRACED_CODE_EXTENSIONS,
+    _COMPONENT_EXTENSIONS,
+    _check_balanced_delimiters,
+    _check_component_blocks,
+    looks_like_refusal,
+    validate_file_content,
+)
+
+
+async def generate_file_content(
+    generate: Callable[[str], Awaitable[Any]],
+    *,
+    target_path: str,
+    user_request: str,
+    max_attempts: int = 2,
+    bundle_files: Optional[List[str]] = None,
+) -> Tuple[str, Dict[str, Any]]:
+    """Generate validated file content with any LLM.
+
+    ``generate`` is an async callable ``context -> raw model text``. Runs up
+    to ``max_attempts`` model calls (each retry carrying corrective feedback),
+    then falls back to deterministic repair, so the returned content is
+    always non-empty and structurally valid for the target type.
+
+    One extra call beyond ``max_attempts`` is spent — at most once per
+    request — when the model has returned a byte-identical rejected reply.
+    That is the one case where the ordinary retry is known to be dead on
+    arrival: the corrective feedback did not change the reply, so the budget
+    is better spent on a prompt that names the repetition than on a third
+    identical round trip. Small local models hit this constantly; large ones
+    never do, so the extra call is not charged to models that do not need it.
+    """
+    attempts: List[Dict[str, Any]] = []
+    feedback: Optional[str] = None
+    best_candidate = ""
+    best_score = (-1, -1)
+    seen: set[str] = set()
+    escalations_left = 1
+    attempt = 0
+    budget = max_attempts
+    while attempt < budget:
+        attempt += 1
+        context = build_file_generation_context(
+            target_path, user_request, feedback=feedback, bundle_files=bundle_files,
+        )
+        try:
+            raw = await generate(context)
+        except Exception as exc:  # model backend hiccup — repair still delivers
+            attempts.append({"attempt": attempt, "valid": False, "reason": f"generation error: {exc}"})
+            feedback = "the model call failed"
+            continue
+        candidate = extract_file_content(str(raw or ""), target_path)
+        ok, reason = validate_file_content(candidate, target_path)
+        record: Dict[str, Any] = {"attempt": attempt, "valid": ok, "reason": reason}
+        if ok:
+            attempts.append(record)
+            return candidate, {"attempts": attempts, "repaired": False}
+
+        # A small model handed the same corrective feedback often replays the
+        # same reply verbatim. Saying "you sent this before" is the only signal
+        # left that has any chance of moving it, and it makes the wasted retry
+        # visible in the trace instead of looking like two genuine tries.
+        fingerprint = candidate.strip()
+        repeated = fingerprint in seen and bool(fingerprint)
+        record["repeated"] = repeated
+        seen.add(fingerprint)
+        if repeated and escalations_left and attempt >= budget:
+            # The retry budget is exhausted and the last thing it bought was a
+            # duplicate. Buy one more, but only with a prompt that says so.
+            escalations_left -= 1
+            budget += 1
+            record["escalated"] = True
+        attempts.append(record)
+
+        # Keep the candidate that is *closest to a file*, not the longest one.
+        # Longest-wins handed repair a 900-character apology in preference to a
+        # 300-character HTML document that only needed its </html> closing —
+        # and repair can finish the document but can only bury the apology.
+        score = _salvage_score(candidate, target_path)
+        if score > best_score:
+            best_score, best_candidate = score, candidate
+
+        feedback = (
+            f"{reason}. You already sent exactly this reply and it was rejected "
+            "for the same reason — do not repeat it. Output the file itself, "
+            "starting at its first character."
+            if repeated else reason
+        )
+    repaired = repair_file_content(best_candidate, target_path, user_request)
+    return repaired, {"attempts": attempts, "repaired": True}
+
+
+def _salvage_score(candidate: str, target_path: str) -> Tuple[int, int]:
+    """How useful an invalid candidate is as raw material for repair.
+
+    ``(tier, length)`` — tier first, so a short real document always beats a
+    long non-document; length breaks ties within a tier.
+
+    Tier 2  something of the right shape that repair can finish (an HTML
+            document missing its close tag, parseable-ish JSON, Python that
+            at least tokenises).
+    Tier 1  ordinary text: no structure, but the words may be the content.
+    Tier 0  a refusal — repair should prefer literally anything else, because
+            an apology written into the file is worse than an empty stub.
+    """
+    text = candidate.strip()
+    if not text:
+        return (0, 0)
+    if looks_like_refusal(text):
+        return (0, len(text))
+
+    ext = _ext(target_path)
+    lower = text.lower()
+    if ext in (".html", ".htm"):
+        if lower.startswith("<!doctype") or lower.startswith("<html"):
+            return (2, len(text))
+    elif ext == ".json":
+        if _slice_json_document(text) is not None:
+            return (2, len(text))
+    elif ext == ".py":
+        try:
+            ast.parse(text)
+        except SyntaxError:
+            pass
+        else:
+            return (2, len(text))
+    elif ext in _BRACED_CODE_EXTENSIONS:
+        if _check_balanced_delimiters(text)[0]:
+            return (2, len(text))
+    elif ext in _COMPONENT_EXTENSIONS:
+        if _check_component_blocks(text)[0]:
+            return (2, len(text))
+    elif ext == ".css" and "{" in text and "}" in text:
+        return (2, len(text))
+    return (1, len(text))

package/latticeai/core/file_generation/prompting.py

@@ -0,0 +1,117 @@
+"""Extension-aware generation instructions — step 1 of the pipeline.
+
+Small models ignore abstract rules but reliably imitate concrete anchors, so
+the prompt pins the exact first line of the expected output and the structural
+rule for the target type. Multi-file bundles swap in the rule that links
+sibling files instead of inlining everything.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .extraction import _ext
+
+_FIRST_LINE_HINTS: Dict[str, str] = {
+    ".html": "<!DOCTYPE html>",
+    ".htm": "<!DOCTYPE html>",
+    ".py": "# (python code — imports or code on the first line)",
+    ".sh": "#!/bin/sh",
+    ".json": "{",
+    ".xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+}
+
+
+_TYPE_RULES: Dict[str, str] = {
+    ".html": (
+        "Produce ONE complete standalone HTML5 document: <!DOCTYPE html>, <html>, "
+        "<head> with <meta charset=\"utf-8\"> and a <title>, inline <style> for CSS, "
+        "and a closed </html> tag. Do not reference external files."
+    ),
+    ".htm": (
+        "Produce ONE complete standalone HTML5 document ending with </html>."
+    ),
+    ".json": "Produce strictly valid JSON (double quotes, no comments, no trailing commas).",
+    ".css": "Produce valid CSS rules only.",
+    ".md": "Produce well-structured Markdown with headings.",
+    ".markdown": "Produce well-structured Markdown with headings.",
+    ".csv": "Produce CSV with a header row; comma-separated, one record per line.",
+    ".py": "Produce complete runnable Python source code.",
+    ".js": "Produce complete valid JavaScript source code.",
+    ".jsx": "Produce one complete React component file in JSX.",
+    ".ts": "Produce complete valid TypeScript source code.",
+    ".tsx": "Produce one complete React component file in TSX (TypeScript).",
+    ".vue": "Produce ONE complete Vue single-file component with closed <template>/<script>/<style> blocks.",
+    ".svelte": "Produce ONE complete Svelte component; every <script>/<style> block must be closed.",
+}
+
+
+# Multi-file bundles override the standalone-HTML rule: the page must link
+# its sibling files instead of inlining everything.
+_BUNDLE_HTML_RULE = (
+    "Produce ONE complete HTML5 document: <!DOCTYPE html>, <html>, <head> with "
+    "<meta charset=\"utf-8\"> and a <title>, and a closed </html> tag. "
+    "This page is part of a multi-file project: link the project stylesheet(s) "
+    "with <link rel=\"stylesheet\" href=\"...\"> and load the project script(s) "
+    "with <script src=\"...\"></script> just before </body>. Reference ONLY the "
+    "project files listed below — no other external files, no inline <style> "
+    "blocks, no inline behavior scripts."
+)
+
+
+# Vite/React bundles need a module entry point, not classic script tags.
+_BUNDLE_HTML_MODULE_RULE = (
+    "Produce ONE complete HTML5 document: <!DOCTYPE html>, <html>, <head> with "
+    "<meta charset=\"utf-8\"> and a <title>, and a closed </html> tag. "
+    "This page is the Vite entry of a React project: the <body> must contain "
+    "<div id=\"root\"></div> and load the app with "
+    "<script type=\"module\" src=\"/src/main.jsx\"></script> just before "
+    "</body>. No inline <style> blocks, no other scripts, no external files."
+)
+
+
+def _bundle_html_rule(bundle_files: List[str]) -> str:
+    """Pick the HTML bundle rule that matches the bundle's technology."""
+    if any(str(path).lower().endswith((".jsx", ".tsx")) for path in bundle_files):
+        return _BUNDLE_HTML_MODULE_RULE
+    return _BUNDLE_HTML_RULE
+
+
+def build_file_generation_context(
+    target_path: str,
+    user_request: str,
+    feedback: Optional[str] = None,
+    bundle_files: Optional[List[str]] = None,
+) -> str:
+    """Strict, extension-aware generation instructions.
+
+    Small models ignore abstract rules but reliably imitate concrete anchors,
+    so the prompt pins the exact first line of the expected output.
+    """
+    ext = _ext(target_path)
+    parts = [
+        "You are a file content generator. Your entire reply is saved verbatim "
+        f"as the file `{target_path}` — it is NOT shown in a chat.",
+        "Rules:",
+        "- Output ONLY the raw file content.",
+        "- No Markdown code fences (```), no explanations, no greetings, "
+        "no text before or after the content.",
+    ]
+    type_rule = _TYPE_RULES.get(ext)
+    if bundle_files and ext in (".html", ".htm"):
+        type_rule = _bundle_html_rule(bundle_files)
+    if type_rule:
+        parts.append(f"- {type_rule}")
+    if bundle_files:
+        listed = ", ".join(bundle_files)
+        parts.append(f"- Project files in this bundle: {listed}")
+    first_line = _FIRST_LINE_HINTS.get(ext)
+    if first_line:
+        parts.append(f"- The very first line of your reply must be: {first_line}")
+    if feedback:
+        parts.append(
+            "Your previous attempt was rejected: "
+            f"{feedback}. Fix that and output only the corrected file content."
+        )
+    parts.append(f"\nUser request: {user_request}")
+    return "\n".join(parts)