Add target word count control and AEO citation guidelines

- UI: new "Target word count" number box, threaded through generate() ->
orchestrator.run() -> writer.write_post(); output tokens scale to the target.
- Writing prompt now enforces AI-citation (AEO) best practices distilled from the
GameMaster citation best-practices doc: direct answer up top, question-style
headings, specific/verifiable claims, a comparison/feature table, an FAQ, cited
sources, stated limitations, freshness and descriptive anchors.
- docx_builder: render Markdown pipe tables as real Word tables (bold header row,
separator row dropped) so the required tables export correctly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app.py

@@ -40,7 +40,7 @@ def _preview(markdown: str, images: list) -> str:
     return re.sub(r"\[IMAGE:\s*.+?\]", repl, markdown, flags=re.DOTALL)
 
 
-def generate(topic, primary, secondary, brief, hf_token, progress=gr.Progress()):
+def generate(topic, primary, secondary, brief, target_wordcount, hf_token, progress=gr.Progress()):
     log_lines = []
     gallery, docx_file, preview = [], None, ""
 
@@ -49,7 +49,7 @@ def generate(topic, primary, secondary, brief, hf_token, progress=gr.Progress())
 
     try:
         for frac, message, result in orchestrator.run(
-            hf_token, topic, primary, secondary, brief
+            hf_token, topic, primary, secondary, brief, target_wordcount
         ):
             progress(frac, desc=message)
             log_lines.append(message)
@@ -85,6 +85,14 @@ def build_ui() -> gr.Blocks:
                     lines=5,
                     placeholder="Audience, angle, tone, must-cover points…",
                 )
+                target_wc = gr.Number(
+                    label="Target word count",
+                    value=config.DEFAULT_WORD_COUNT,
+                    minimum=300,
+                    maximum=5000,
+                    step=100,
+                    precision=0,
+                )
                 hf_token = gr.Textbox(
                     label="Hugging Face token (billed to you)",
                     type="password",
@@ -99,7 +107,7 @@ def build_ui() -> gr.Blocks:
 
         run_btn.click(
             fn=generate,
-            inputs=[topic, primary, secondary, brief, hf_token],
+            inputs=[topic, primary, secondary, brief, target_wc, hf_token],
             outputs=[status_box, preview, gallery, docx_out],
         )
         gr.Markdown(

pipeline/aeo_guidelines.py

@@ -0,0 +1,42 @@
+"""AEO / AI-chatbot-citation writing guidelines injected into the blog-writing prompt.
+
+Distilled from the writing-relevant parts of
+"Best Practices for Being Listed and Cited in AI Chatbot Queries"
+(V:\\GameMaster\\Marketing\\AEO\\ai_chatbot_citation_best_practices_gamemaster.docx).
+
+Only the guidance that applies to authoring a single article is included here — site-wide
+technical items (robots.txt, sitemaps, schema/JSON-LD, llms.txt) are out of scope for a
+generated blog post and are intentionally omitted.
+"""
+
+# Kept as a single prompt-ready block. Referenced by writer.write_post().
+AEO_GUIDELINES = """\
+Write the article to be easily discovered, quoted and CITED by AI answer engines
+(ChatGPT, Claude, Gemini, Perplexity, Google AI Overviews). Follow these rules:
+
+Core formula: be specific + be useful + show original proof + be quotable.
+
+1. Direct answer first: open with a one-sentence, self-contained definition/answer to the
+   article's core question, then a short direct-answer paragraph — all within the first
+   ~100 words. A reader (or model) should get the answer without scrolling.
+2. Answer-friendly structure: use clear, descriptive H2/H3 headings; where natural, phrase
+   headings as the questions users actually ask. Each section should directly answer its
+   heading. Keep paragraphs short (2-4 sentences) and use bullet lists so points are easy
+   to extract and quote.
+3. Be specific, not generic: prefer concrete, verifiable, extractable statements over vague
+   marketing claims. (Weak: "the best tool for everyone." Strong: name the exact features,
+   numbers, versions, steps or limitations.) Every claim should be something a model could
+   quote and attribute.
+4. Include at least one comparison or feature table (Markdown table syntax) when the topic
+   supports it — comparisons, feature/module matrices, specs, pros/cons or step summaries.
+5. Include a short FAQ section near the end: 3-6 real questions a user might ask an AI,
+   each with a concise, direct 1-3 sentence answer (great for citation).
+6. Trust / E-E-A-T: cite reliable primary sources by name inline where you make factual
+   claims, and add a brief "Sources" list at the end referencing them. Show experience and
+   state limitations or caveats honestly (what does NOT work, what needs manual review).
+7. Freshness: include a "Last updated" line (use the current month/year) near the top or end.
+8. Descriptive link text: when you reference a concept, use strong descriptive anchor
+   phrasing — never "click here", "read more", "this article" or "learn more".
+9. Self-contained: put the important details in plain text prose; do not defer key facts to
+   the images. Images illustrate; the text must stand alone.
+"""

pipeline/config.py

@@ -36,6 +36,7 @@ N_SEARCH_TERMS = int(os.environ.get("N_SEARCH_TERMS", "5"))   # queries generate
 TOP_N = int(os.environ.get("TOP_N", "25"))                    # results ranked by OpenPageRank
 TOP_K = int(os.environ.get("TOP_K", "5"))                     # top pages used as source material
 N_IMAGES = int(os.environ.get("N_IMAGES", "3"))              # illustrations per post
+DEFAULT_WORD_COUNT = int(os.environ.get("DEFAULT_WORD_COUNT", "1200"))  # target post length
 SOURCE_CHAR_CAP = int(os.environ.get("SOURCE_CHAR_CAP", "4000"))  # chars kept per source page
 HTTP_TIMEOUT = int(os.environ.get("HTTP_TIMEOUT", "20"))     # seconds for outbound HTTP
 

pipeline/docx_builder.py

@@ -11,6 +11,7 @@ from docx.shared import Inches, Pt, RGBColor
 
 _IMAGE_MARKER = re.compile(r"\[IMAGE:\s*.+?\]", re.DOTALL)
 _INLINE = re.compile(r"(\*\*.+?\*\*|\*.+?\*|`.+?`)")
+_SEP_CELL = re.compile(r"^:?-{2,}:?$")
 _MAX_IMG_WIDTH = Inches(6.0)
 
 
@@ -19,9 +20,25 @@ def build_docx(markdown: str, images: List[dict], out_path: Path) -> Path:
     doc = Document()
     img_iter = iter([im for im in images if im.get("path")])
 
-    for block in _split_blocks(markdown):
+    blocks = _split_blocks(markdown)
+    i, n = 0, len(blocks)
+    while i < n:
+        block = blocks[i]
+
+        # Markdown pipe table: a header row followed by a separator row (| --- | --- |).
+        if _is_table_row(block) and i + 1 < n and _is_separator_row(blocks[i + 1]):
+            j = i + 2
+            rows = [block]
+            while j < n and _is_table_row(blocks[j]):
+                rows.append(blocks[j])
+                j += 1
+            _add_table(doc, rows)
+            i = j
+            continue
+
         if _IMAGE_MARKER.fullmatch(block.strip()):
             _insert_next_image(doc, img_iter)
+            i += 1
             continue
         # a block may still contain an inline marker mixed with text
         if _IMAGE_MARKER.search(block):
@@ -29,8 +46,11 @@ def build_docx(markdown: str, images: List[dict], out_path: Path) -> Path:
                 if piece.strip():
                     _render_line(doc, piece.strip())
             _insert_next_image(doc, img_iter)
+            i += 1
             continue
+
         _render_line(doc, block)
+        i += 1
 
     # any leftover images that never got placed → append at the end
     for im in img_iter:
@@ -41,6 +61,47 @@ def build_docx(markdown: str, images: List[dict], out_path: Path) -> Path:
     return out_path
 
 
+def _is_table_row(line: str) -> bool:
+    s = line.strip()
+    return "|" in s and s.count("|") >= 2
+
+
+def _is_separator_row(line: str) -> bool:
+    cells = _parse_row(line)
+    return bool(cells) and all(_SEP_CELL.match(c.replace(" ", "")) for c in cells)
+
+
+def _parse_row(line: str) -> List[str]:
+    s = line.strip()
+    if s.startswith("|"):
+        s = s[1:]
+    if s.endswith("|"):
+        s = s[:-1]
+    return [c.strip() for c in s.split("|")]
+
+
+def _add_table(doc: Document, rows: List[str]) -> None:
+    header = _parse_row(rows[0])
+    body = [_parse_row(r) for r in rows[1:]]
+    ncols = max([len(header)] + [len(r) for r in body]) if (header or body) else 0
+    if ncols == 0:
+        return
+    table = doc.add_table(rows=1, cols=ncols)
+    try:
+        table.style = "Table Grid"
+    except Exception:
+        pass
+    # header (cells start empty, so add_run yields runs[0])
+    for c in range(ncols):
+        run = table.rows[0].cells[c].paragraphs[0].add_run(header[c] if c < len(header) else "")
+        run.bold = True
+    # body
+    for r in body:
+        cells = table.add_row().cells
+        for c in range(ncols):
+            _add_runs(cells[c].paragraphs[0], r[c] if c < len(r) else "")
+
+
 def _split_blocks(md: str) -> List[str]:
     """Split into logical blocks (headings/paragraphs/markers), preserving order."""
     blocks: List[str] = []

pipeline/orchestrator.py

@@ -29,12 +29,19 @@ def run(
     primary_keyword: str,
     secondary_keyword: str,
     brief: str,
+    target_wordcount: int = config.DEFAULT_WORD_COUNT,
 ) -> Iterator[Tuple[float, str, dict]]:
     if not topic.strip():
         raise ValueError("Please enter a topic.")
     client = llm.make_client(hf_token)  # raises if token missing → billed to user
 
-    key = cache.run_key(topic, primary_keyword, secondary_keyword, brief)
+    try:
+        target_wordcount = int(target_wordcount)
+    except (TypeError, ValueError):
+        target_wordcount = config.DEFAULT_WORD_COUNT
+    target_wordcount = max(300, min(target_wordcount, 5000))
+
+    key = cache.run_key(topic, primary_keyword, secondary_keyword, brief, str(target_wordcount))
     run_dir = config.OUT_DIR / key
     run_dir.mkdir(parents=True, exist_ok=True)
     result: dict = {"key": key}
@@ -72,9 +79,10 @@ def run(
     result["sources"] = [{k: v for k, v in s.items() if k != "text"} for s in sources]
 
     # 5) write the post
-    yield 0.55, "Writing the blog post…", result
+    yield 0.55, f"Writing the ~{target_wordcount}-word blog post…", result
     markdown = writer.write_post(
-        client, topic, primary_keyword, secondary_keyword, brief, sources
+        client, topic, primary_keyword, secondary_keyword, brief, sources,
+        target_wordcount=target_wordcount,
     )
     (run_dir / "post.md").write_text(markdown, encoding="utf-8")
     result["markdown"] = markdown

pipeline/writer.py

@@ -12,23 +12,30 @@ from typing import List
 from huggingface_hub import InferenceClient
 
 from . import config, llm
+from .aeo_guidelines import AEO_GUIDELINES
 
-_SYSTEM = (
-    "You are an expert blog writer and SEO editor. Using ONLY the supplied source "
-    "material as factual grounding, write an original, engaging, well-structured blog "
-    "post. Do not copy sentences verbatim from the sources; synthesize in your own voice.\n\n"
-    "Requirements:\n"
-    "- Start with a single '# ' H1 title that includes the primary keyword.\n"
-    "- Use the primary keyword naturally in the first 100 words and in at least one '## ' heading.\n"
-    "- Weave the secondary keyword in naturally 1-3 times.\n"
-    "- Use '## ' subheadings to organize sections; write substantive paragraphs.\n"
-    "- Honor the brief's angle, audience, and tone.\n"
-    f"- Insert exactly {config.N_IMAGES} image markers of the form "
-    "'[IMAGE: a vivid visual scene to illustrate this section]' at natural points "
-    "(never two in a row, not in the title).\n"
-    "- End with a short conclusion.\n"
-    "Return Markdown only — no preamble, no code fences."
-)
+
+def _build_system(target_wordcount: int) -> str:
+    return (
+        "You are an expert blog writer and SEO/AEO editor. Using ONLY the supplied source "
+        "material as factual grounding, write an original, engaging, well-structured blog "
+        "post. Do not copy sentences verbatim from the sources; synthesize in your own voice.\n\n"
+        "Structural requirements:\n"
+        "- Start with a single '# ' H1 title that includes the primary keyword.\n"
+        "- Use the primary keyword naturally in the first 100 words and in at least one '## ' heading.\n"
+        "- Weave the secondary keyword in naturally 1-3 times.\n"
+        "- Use '## ' subheadings to organize sections; write substantive paragraphs.\n"
+        "- Honor the brief's angle, audience, and tone.\n"
+        f"- Target length: about {target_wordcount} words (stay within roughly ±10%).\n"
+        f"- Insert exactly {config.N_IMAGES} image markers of the form "
+        "'[IMAGE: a vivid visual scene to illustrate this section]' at natural points "
+        "(never two in a row, not in the title).\n"
+        "- End with a short conclusion.\n\n"
+        "AI-citation (AEO) requirements:\n"
+        f"{AEO_GUIDELINES}\n"
+        "Return Markdown only — no preamble, no code fences. Use Markdown pipe tables for "
+        "any tables."
+    )
 
 
 def write_post(
@@ -38,22 +45,28 @@ def write_post(
     secondary_keyword: str,
     brief: str,
     sources: List[dict],
+    target_wordcount: int = config.DEFAULT_WORD_COUNT,
 ) -> str:
     source_block = _format_sources(sources)
     user = (
         f"Topic: {topic}\n"
         f"Primary keyword: {primary_keyword}\n"
         f"Secondary keyword: {secondary_keyword}\n"
+        f"Target word count: {target_wordcount}\n"
         f"Brief: {brief}\n\n"
         f"SOURCE MATERIAL (ranked by domain authority):\n{source_block}\n\n"
-        "Write the full blog post in Markdown now."
+        f"Write the full ~{target_wordcount}-word blog post in Markdown now, following the "
+        "AI-citation guidelines (direct answer up top, question-style headings, a comparison/"
+        "feature table, an FAQ, cited sources, stated limitations)."
     )
+    # Allow enough output tokens for the requested length (~1.6 tokens/word + overhead).
+    max_tokens = max(1500, min(int(target_wordcount * 2) + 600, 8000))
     md = llm.chat(
         client,
         config.MODEL_WRITER,
-        _SYSTEM,
+        _build_system(target_wordcount),
         user,
-        max_tokens=3500,
+        max_tokens=max_tokens,
         temperature=0.7,
         fallback_model=config.MODEL_WRITER_FALLBACK,
     )