[agentic] Port pi loop hooks + LLM-drafted editable (Word) documents

Audited /tmp/pi and ported its agentic control architecture into Refuge's
Python loop, then used it to make the assessment and documents genuinely agentic
(the hackathon point: small-LLM agentic AI).

Agent framework (agent/loop.py) — Python port of pi's AgentLoopConfig hooks:
- LoopHooks: transform_context, before_tool_call, after_tool_call,
should_stop_after_turn, prepare_next_turn; plus tool `terminate` handling.

Assessment now uses the hooks:
- should_stop_after_turn ends the run once the @@ASSESSMENT block is produced
(no rambling); before_tool_call blocks web_search queries containing the
person's private narrative (privacy, ARCHITECTURE §Security).

Documents are now agentic + editable:
- agent/drafting.py: the LLM drafts an in-depth, first-person personal statement
from the person's own answers, in their language, with [placeholders] to
complete (deterministic fallback if the model is down; nothing fabricated).
- doc_generator: exports every document as editable Word (.docx) AND PDF;
placeholders highlighted; "Download all" zips all 8 files.
- documents.py: populate() awaits the LLM draft; shows Word + PDF.

Fixes: recognition rate shown as % and relabelled honestly; assessment facts
panel shows the free-text "What happened"; checkbox label leak fixed.

Deps: python-docx==1.1.2 (one before latest). Tests updated (58 fast pass).

Co-authored-by: Codex <noreply@openai.com>

agent/drafting.py

@@ -0,0 +1,84 @@
+"""agent/drafting.py — LLM-drafted asylum documents (the agentic document step).
+
+Uses the agent loop to draft an in-depth, first-person personal statement from
+the person's own answers, in their language, inserting clearly-marked
+``[placeholders]`` for specifics not collected (name, dates, names of people/
+places) so they can complete and edit it. Facts are never invented (CLAUDE.md
+Rule 4) — the model expands respectfully only on what the person said.
+"""
+
+from __future__ import annotations
+
+from agent.events import ErrorEvent, TextDeltaEvent
+from agent.loop import create_loop
+
+_SYSTEM = """You are Refuge, helping a person draft a first-person PERSONAL STATEMENT
+to support an asylum / refugee claim. Write with dignity, in plain, clear language,
+in {language}.
+
+Rules:
+- Use ONLY the facts provided. Do not invent events, dates, names, or details.
+- Where a specific fact is missing (full name, date of birth, exact dates, names
+  of people or places, document numbers), insert a clearly marked placeholder in
+  square brackets, e.g. [your full name], [date], [town], so the person can fill it in.
+- Expand respectfully on what the person told you about why they left — do not
+  exaggerate or add claims they did not make.
+- Structure: 4–6 short paragraphs covering, in the first person ("I"):
+  1) who I am and where I am from; 2) where I am now; 3) what happened that forced
+  me to leave; 4) why I fear returning; 5) the protection I am asking for.
+- End with two lines: "Signed: [your full name]" and "Date: [date]".
+- Output ONLY the statement text. No headings, no commentary, no markdown."""
+
+
+def _facts(session) -> str:
+    iv = session.interview
+    rows = [
+        ("Country of origin", iv.origin_country),
+        ("Current country", iv.current_country),
+        ("What happened (their words)", iv.free_text_history
+         or (", ".join(iv.persecution_types) if iv.persecution_types else None)),
+        ("In immediate danger", None if iv.immediate_danger is None else ("yes" if iv.immediate_danger else "no")),
+        ("Time since leaving", iv.displacement_duration),
+        ("Travelling with", iv.family_situation),
+        ("Languages", ", ".join(iv.languages_spoken) if iv.languages_spoken else None),
+        ("Seeking protection in", session.selected_country),
+    ]
+    return "\n".join(f"- {k}: {v}" for k, v in rows if v)
+
+
+async def draft_personal_statement(session, loop=None) -> str:
+    """Draft the statement via the LLM. Returns plain text with [placeholders]."""
+    loop = loop or create_loop()
+    language = getattr(session, "language", None) or "English"
+    system_prompt = _SYSTEM.format(language=language)
+    prompt = (
+        "Draft my personal statement now using these facts:\n\n" + _facts(session)
+        + "\n\nWrite it in " + language + "."
+    )
+    acc = ""
+    async for ev in loop.run(prompt, session=None, system_prompt=system_prompt, thinking_level="off"):
+        if isinstance(ev, TextDeltaEvent):
+            acc += ev.delta
+        elif isinstance(ev, ErrorEvent):
+            acc += ""  # fall back to template below if the model failed
+    return acc.strip()
+
+
+def fallback_statement(session) -> str:
+    """Deterministic statement if the model is unavailable (no fabrication)."""
+    iv = session.interview
+    origin = iv.origin_country or "[country of origin]"
+    current = iv.current_country or "[current country]"
+    reason = iv.free_text_history or "[describe what happened that made you leave]"
+    return (
+        f"My name is [your full name]. I am a national of {origin}, born in [town] on [date of birth].\n\n"
+        f"I am currently in {current}.\n\n"
+        f"I had to leave {origin} because: {reason}\n\n"
+        "I fear that if I am returned I will be at serious risk of harm for the reasons described above.\n\n"
+        "I am asking for protection and the right not to be returned to a place where my life or freedom "
+        "would be threatened.\n\n"
+        "Signed: [your full name]\nDate: [date]"
+    )
+
+
+__all__ = ["draft_personal_statement", "fallback_statement"]

agent/loop.py

@@ -23,9 +23,11 @@ Guarantees:
 from __future__ import annotations
 
 import asyncio
+import inspect
 import json
 import os
-from typing import AsyncGenerator, Iterable, Optional
+from dataclasses import dataclass
+from typing import AsyncGenerator, Callable, Iterable, Optional
 
 from agent.events import (
     AgentEndEvent,
@@ -45,6 +47,36 @@ DEFAULT_MODEL_ID = "qwen2.5:7b"
 MAX_TURNS = 12
 
 
+@dataclass
+class LoopHooks:
+    """Agent-loop control hooks — a Python port of pi's AgentLoopConfig hooks.
+
+    Each is optional and may be sync or async. They give the harness real agency
+    over the loop without the model deciding control flow:
+
+    * ``transform_context(history)`` -> history  — shape context before the call
+    * ``before_tool_call(name, args)`` -> {"block": bool, "reason": str} | None
+    * ``after_tool_call(name, args, result)`` -> replacement result dict | None
+    * ``should_stop_after_turn(assistant_message, history)`` -> bool — graceful stop
+    * ``prepare_next_turn(assistant_message, history)`` -> {"thinking_level": ...} | None
+    """
+
+    transform_context: Optional[Callable] = None
+    before_tool_call: Optional[Callable] = None
+    after_tool_call: Optional[Callable] = None
+    should_stop_after_turn: Optional[Callable] = None
+    prepare_next_turn: Optional[Callable] = None
+
+
+async def _maybe_await(fn, *args):
+    if fn is None:
+        return None
+    result = fn(*args)
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
 class AgentLoop:
     """A stateless-per-session driver around the LLM + tools.
 
@@ -145,24 +177,25 @@ class AgentLoop:
         system_prompt: str = "",
         tools: Optional[Iterable[AgentTool]] = None,
         thinking_level: str = "low",
+        hooks: Optional[LoopHooks] = None,
     ) -> AsyncGenerator[AgentEvent, None]:
         # AgentStartEvent is yielded before any network call (SC-004).
         yield AgentStartEvent()
 
+        hooks = hooks or LoopHooks()
         active_tools = list(tools) if tools is not None else self.tools
         tool_map = self._tool_map(active_tools)
         tool_schemas = [t.to_ollama_schema() for t in active_tools] or None
+        think_level = thinking_level
 
-        # Conversation history excludes the system prompt: the system message is
-        # supplied fresh on every API call, so it must not be persisted into the
-        # history we return (otherwise it would accumulate across turns).
+        # Conversation history excludes the system prompt (supplied fresh each call).
         history: list[dict] = list(getattr(session, "messages", None) or [])
         if prompt:
             history.append({"role": "user", "content": prompt})
 
-        def api_messages() -> list[dict]:
+        def api_messages(ctx: list[dict]) -> list[dict]:
             sys = [{"role": "system", "content": system_prompt}] if system_prompt else []
-            return sys + history
+            return sys + ctx
 
         try:
             client = self._client_lazy()
@@ -173,12 +206,14 @@ class AgentLoop:
 
                 yield TurnStartEvent()
 
+                # transform_context hook (pi: transformContext) — shape context.
+                ctx = await _maybe_await(hooks.transform_context, history) or history
+
                 assistant_text = ""
                 tool_calls: list = []
+                think_arg = think_level if think_level in ("low", "medium", "high") else None
 
-                think_arg = thinking_level if thinking_level in ("low", "medium", "high") else None
-
-                async for chunk in self._iter_chat(client, api_messages(), tool_schemas, think_arg):
+                async for chunk in self._iter_chat(client, api_messages(ctx), tool_schemas, think_arg):
                     if self.abort_event.is_set():
                         break
                     msg = getattr(chunk, "message", None)
@@ -190,7 +225,6 @@ class AgentLoop:
                     if getattr(msg, "tool_calls", None):
                         tool_calls.extend(msg.tool_calls)
 
-                # Record the assistant turn in history.
                 assistant_message: dict = {"role": "assistant", "content": assistant_text}
 
                 if tool_calls:
@@ -207,33 +241,51 @@ class AgentLoop:
                     assistant_message["tool_calls"] = serialised_calls
                     history.append(assistant_message)
 
-                    # Run each requested tool and feed results back to the model.
+                    terminate_flags = []
                     for call in serialised_calls:
                         name = call["function"]["name"]
                         args = call["function"]["arguments"]
                         yield ToolStartEvent(name=name, args=args)
-                        result = await self._execute_tool(name, args, tool_map)
+
+                        # before_tool_call hook (pi: beforeToolCall) — guard/block.
+                        guard = await _maybe_await(hooks.before_tool_call, name, args)
+                        if guard and guard.get("block"):
+                            result = {"error": "blocked", "reason": guard.get("reason", "blocked")}
+                        else:
+                            result = await self._execute_tool(name, args, tool_map)
+                        # after_tool_call hook (pi: afterToolCall) — transform result.
+                        replaced = await _maybe_await(hooks.after_tool_call, name, args, result)
+                        if replaced is not None:
+                            result = replaced
+
+                        terminate_flags.append(bool(isinstance(result, dict) and result.get("terminate")))
                         yield ToolEndEvent(name=name, result=result)
-                        history.append(
-                            {
-                                "role": "tool",
-                                "name": name,
-                                "content": json.dumps(result, ensure_ascii=False),
-                            }
-                        )
-                    # Loop again so the model can use the tool results.
+                        history.append({
+                            "role": "tool", "name": name,
+                            "content": json.dumps(result, ensure_ascii=False),
+                        })
+
+                    yield TurnEndEvent(message=assistant_message)
+
+                    # tool `terminate`: stop when every tool in the batch asked to.
+                    if terminate_flags and all(terminate_flags):
+                        break
+                    if await _maybe_await(hooks.should_stop_after_turn, assistant_message, history):
+                        break
+                    upd = await _maybe_await(hooks.prepare_next_turn, assistant_message, history)
+                    if upd and upd.get("thinking_level"):
+                        think_level = upd["thinking_level"]
                     continue
 
-                # No tool calls: this turn produced the final answer.
+                # No tool calls: final answer for this turn.
                 history.append(assistant_message)
                 yield TurnEndEvent(message=assistant_message)
 
-                # Honour any steering message queued during the turn.
+                if await _maybe_await(hooks.should_stop_after_turn, assistant_message, history):
+                    break
                 if not self.steering_queue.empty():
-                    steer_msg = await self.steering_queue.get()
-                    history.append({"role": "user", "content": steer_msg})
+                    history.append({"role": "user", "content": await self.steering_queue.get()})
                     continue
-
                 break
 
             yield AgentEndEvent(messages=history)
@@ -256,4 +308,4 @@ def create_loop(
     return AgentLoop(tools=tools, model_id=model_id, host=host)
 
 
-__all__ = ["AgentLoop", "AgentTool", "DEFAULT_MODEL_ID", "create_loop"]
+__all__ = ["AgentLoop", "AgentTool", "LoopHooks", "DEFAULT_MODEL_ID", "create_loop"]

agent/tools/doc_generator.py

@@ -1,32 +1,37 @@
-"""agent/tools/doc_generator.py — Phase 5 document package generator (T049/T050).
-
-Generates four PDFs from the completed session using WeasyPrint + HTML templates
-(agent/tools/templates/). Every pre-filled value comes only from
-``session.interview`` / ``session.assessment`` / ``session.selected_country`` —
-nothing is invented (CLAUDE.md Critical Rule 4). Pre-filled fields are wrapped in
-an amber-highlight ``.fill`` span; missing fields render as a blank line (never a
-literal "PLACEHOLDER"/"[NAME]"). Every filled field is logged with its source key.
-
-Output PDFs go to an ephemeral temp directory (ARCHITECTURE.md §Security).
+"""agent/tools/doc_generator.py — Phase 5 document package (PDF + editable Word).
+
+Generates the document package from real session data. The **personal statement
+is drafted by the LLM** (see agent/drafting.py) — an in-depth, first-person
+narrative with ``[placeholders]`` the person completes — and every document is
+exported as both an **editable Word (.docx)** file and a print-ready **PDF**.
+Country facts come from the curated data via country_lookup; nothing is
+fabricated (CLAUDE.md Rule 4).
 """
 
 from __future__ import annotations
 
 import html
 import logging
+import re
 import tempfile
 import zipfile
 from dataclasses import dataclass
 from pathlib import Path
 
+from docx import Document
+from docx.shared import Pt, RGBColor
 from weasyprint import HTML
 
+from agent.drafting import fallback_statement
 from agent.tools.country_lookup import lookup_country
 
 logger = logging.getLogger("refuge.doc_generator")
 
 TEMPLATES = Path(__file__).resolve().parent / "templates"
 _HEAD = (TEMPLATES / "_head.html").read_text(encoding="utf-8")
+_PLACEHOLDER = re.compile(r"(\[[^\]]+\])")
+_AMBER = RGBColor(0xC2, 0x63, 0x29)
+_TEAL = RGBColor(0x0A, 0x50, 0x42)
 
 
 @dataclass
@@ -34,177 +39,210 @@ class GeneratedDoc:
     key: str
     title: str
     meta: str
-    path: Path
-
-
-# -- field helpers ----------------------------------------------------------
-
-def _is_empty(value) -> bool:
-    return value is None or value == "" or value == [] or value == {}
-
-
-def fill(value, source_key: str, *, fallback_blank: bool = True) -> str:
-    """Amber-highlight a pre-filled value, logging its source. Blank if missing."""
-    if _is_empty(value):
-        return '<span class="blank">&nbsp;</span>' if fallback_blank else ""
-    text = ", ".join(str(v) for v in value) if isinstance(value, list) else str(value)
-    logger.info("Filling field from session key: %s", source_key)
-    return f'<span class="fill">{html.escape(text)}</span>'
-
-
-def _render(template_name: str, tokens: dict[str, str]) -> str:
-    tpl = (TEMPLATES / template_name).read_text(encoding="utf-8")
-    tpl = tpl.replace("%%HEAD%%", _HEAD)
-    for key, value in tokens.items():
-        tpl = tpl.replace(f"%%{key}%%", value)
-    return tpl
-
+    pdf_path: Path
+    docx_path: Path
+
+
+# -- shared helpers ---------------------------------------------------------
+
+def _paras(text: str) -> list[str]:
+    return [p.strip() for p in text.split("\n") if p.strip()]
+
+
+def _html_with_placeholders(text: str) -> str:
+    """Render free text into HTML, highlighting [placeholders] in amber."""
+    out = []
+    for para in _paras(text):
+        pieces = []
+        for part in _PLACEHOLDER.split(para):
+            if not part:
+                continue
+            if _PLACEHOLDER.fullmatch(part):
+                pieces.append(f'<span class="fill">{html.escape(part)}</span>')
+            else:
+                pieces.append(html.escape(part))
+        out.append("<p>" + "".join(pieces) + "</p>")
+    return "\n".join(out)
+
+
+def _docx_add_rich(doc: Document, text: str):
+    """Add paragraphs, bolding [placeholders] so they're easy to find and edit."""
+    for para in _paras(text):
+        p = doc.add_paragraph()
+        for part in _PLACEHOLDER.split(para):
+            if not part:
+                continue
+            run = p.add_run(part)
+            if _PLACEHOLDER.fullmatch(part):
+                run.bold = True
+                run.font.color.rgb = _AMBER
+
+
+def _new_docx(title: str, subtitle: str) -> Document:
+    doc = Document()
+    h = doc.add_heading(title, level=0)
+    try:
+        h.runs[0].font.color.rgb = _TEAL
+    except Exception:
+        pass
+    sub = doc.add_paragraph(subtitle)
+    sub.runs[0].italic = True
+    sub.runs[0].font.size = Pt(9)
+    sub.runs[0].font.color.rgb = RGBColor(0x6B, 0x72, 0x80)
+    return doc
+
+
+def _pdf_from_html(body_html: str, path: Path):
+    HTML(string=f"<!DOCTYPE html><html><head>{_HEAD}</head><body>{body_html}</body></html>").write_pdf(str(path))
+
+
+# -- per-document content ---------------------------------------------------
+
+def _statement_body_html(text: str) -> str:
+    return (
+        "<h1>Personal Statement</h1>"
+        '<p class="sub">In support of an application for refugee status · Prepared with Refuge</p>'
+        f"{_html_with_placeholders(text)}"
+        '<p class="note">Fields in amber are placeholders for you to complete. You can edit any part '
+        "of this statement in the Word (.docx) version.</p>"
+    )
 
-# -- per-document HTML builders --------------------------------------------
 
-def _personal_statement_html(session) -> str:
-    iv = session.interview
-    family_clause = ""
-    if not _is_empty(iv.family_situation):
-        family_clause = f", traveling with {fill(iv.family_situation, 'interview.family_situation')}"
-    history_para = ""
-    if not _is_empty(iv.free_text_history):
-        history_para = f"<p>{fill(iv.free_text_history, 'interview.free_text_history')}</p>"
-    return _render("personal_statement.html", {
-        "full_name": fill(None, "interview.full_name"),  # not collected — blank to complete
-        "origin_country": fill(iv.origin_country, "interview.origin_country"),
-        "current_country": fill(iv.current_country, "interview.current_country"),
-        "family_clause": family_clause,
-        "persecution": fill(iv.persecution_types, "interview.persecution_types"),
-        "history_para": history_para,
-    })
+def _rec_for(session):
+    if session.selected_country:
+        rec = lookup_country(session.selected_country)
+        return None if rec.get("error") else rec
+    return None
 
 
-def _action_plan_html(session, rec: dict | None) -> str:
+def _action_plan_blocks(session, rec):
     country = session.selected_country or "your chosen country"
     months = (rec or {}).get("processingTimeMonths")
-    processing = f"about {months} months" if months else "a variable amount of time"
     office = (rec or {}).get("unhcrOffice")
-    unhcr = f"Yes — {office}" if office else ("Yes" if (rec or {}).get("unhcrPresence") else "Check locally")
-    steps_src = (rec or {}).get("steps") or [
+    steps = (rec or {}).get("steps") or [
         "Register with UNHCR or the asylum authority",
         "File your asylum claim with your personal statement",
         "Attend your refugee status interview (RSD)",
         "Receive the decision (appeal if refused)",
         "Access integration support",
     ]
-    steps_html = "".join(
-        f'<p class="step"><b>Step {i}.</b> {html.escape(str(s))}</p>'
-        for i, s in enumerate(steps_src, start=1)
-    )
-    return _render("action_plan.html", {
-        "selected_country": html.escape(str(country)),
-        "processing": processing,
-        "unhcr_office": html.escape(str(unhcr)),
-        "steps": steps_html,
-    })
+    intro = (f"This plan is for seeking protection in {country}. "
+             f"Typical processing: {('about ' + str(months) + ' months') if months else 'varies'}. "
+             f"UNHCR: {('Yes — ' + office) if office else 'check locally'}.")
+    return country, intro, steps
 
 
-def _emergency_contacts_html(session, rec: dict | None) -> str:
-    country = session.selected_country or "your chosen country"
-    office = (rec or {}).get("unhcrOffice") or "Nearest UNHCR office"
-    orgs = (rec or {}).get("legalAidOrgs") or []
-    if orgs:
-        orgs_html = "".join(
-            f'<div class="org"><b>{html.escape(str(o.get("name", "")))}</b>'
-            f'<span>{html.escape(str(o.get("url", "")))}</span></div>'
-            for o in orgs if isinstance(o, dict)
-        )
-    else:
-        orgs_html = "<p>Ask the UNHCR office for a list of registered legal-aid partners.</p>"
-    return _render("emergency_contacts.html", {
-        "selected_country": html.escape(str(country)),
-        "unhcr_office": html.escape(str(office)),
-        "orgs": orgs_html,
-    })
-
-
-def _rights_card_html(session) -> str:
-    grounds = session.assessment.convention_grounds or []
-    grounds_txt = ", ".join(grounds) if grounds else "to be confirmed in your interview"
-    return _render("rights_summary_card.html", {
-        "origin_country": fill(session.interview.origin_country, "interview.origin_country"),
-        "selected_country": html.escape(str(session.selected_country or "your chosen country")),
-        "grounds": html.escape(grounds_txt),
-    })
-
-
-# -- public API -------------------------------------------------------------
-
-_DOCS = [
-    ("personal_statement", "Personal statement (pre-filled)", "PDF · narrative for your claim"),
-    ("action_plan", "Action plan", "PDF · step-by-step roadmap with contacts"),
-    ("emergency_contacts", "Emergency contacts", "PDF · UNHCR offices & legal aid"),
-    ("rights_summary_card", "Your rights — summary card", "PDF · key protections"),
-]
-
-
-def build_html(session) -> dict[str, str]:
-    """Return {key: full_html} for all four documents (handy for tests/preview)."""
-    rec = None
-    if session.selected_country:
-        looked = lookup_country(session.selected_country)
-        rec = None if looked.get("error") else looked
-    return {
-        "personal_statement": _personal_statement_html(session),
-        "action_plan": _action_plan_html(session, rec),
-        "emergency_contacts": _emergency_contacts_html(session, rec),
-        "rights_summary_card": _rights_card_html(session),
-    }
-
-
-def preview_statement_html(session) -> str:
-    """Inline (head-less) personal-statement snippet for the on-screen preview."""
-    iv = session.interview
-    family_clause = ""
-    if not _is_empty(iv.family_situation):
-        family_clause = f", traveling with {fill(iv.family_situation, 'interview.family_situation')}"
-    history = ""
-    if not _is_empty(iv.free_text_history):
-        history = f"<p>{fill(iv.free_text_history, 'interview.free_text_history')}</p>"
-    return (
-        '<article class="doc"><h4>Personal Statement</h4>'
-        '<p class="doc__sub">In support of an application for refugee status · Prepared with Refuge</p>'
-        f"<p>My name is {fill(None, 'interview.full_name')}. I am a national of "
-        f"{fill(iv.origin_country, 'interview.origin_country')}. I am currently in "
-        f"{fill(iv.current_country, 'interview.current_country')}{family_clause}.</p>"
-        '<div class="doc__divider"></div>'
-        f"<p>I left my home because of {fill(iv.persecution_types, 'interview.persecution_types')}.</p>"
-        f"{history}"
-        "</article>"
-    )
+def _orgs(rec):
+    return [(o.get("name", ""), o.get("url", "")) for o in (rec or {}).get("legalAidOrgs", []) if isinstance(o, dict)]
+
 
+# -- generation -------------------------------------------------------------
 
-def generate(session, out_dir: Path | None = None) -> list[GeneratedDoc]:
-    """Generate the four PDFs. Returns GeneratedDoc records with file paths."""
+def generate(session, statement: str | None = None, out_dir: Path | None = None) -> list[GeneratedDoc]:
+    """Build the 4 documents as PDF + DOCX. ``statement`` is the LLM-drafted
+    personal statement; if omitted, a deterministic fallback is used."""
     out_dir = Path(out_dir) if out_dir else Path(tempfile.mkdtemp(prefix="refuge_docs_"))
     out_dir.mkdir(parents=True, exist_ok=True)
-    htmls = build_html(session)
-
+    stmt = statement or fallback_statement(session)
+    rec = _rec_for(session)
     docs: list[GeneratedDoc] = []
-    for key, title, meta in _DOCS:
-        path = out_dir / f"{key}.pdf"
-        HTML(string=htmls[key]).write_pdf(str(path))
-        docs.append(GeneratedDoc(key=key, title=title, meta=meta, path=path))
-    logger.info("Generated %d documents in %s", len(docs), out_dir)
+
+    # 1. Personal statement (LLM-drafted) — PDF + DOCX
+    ps_pdf, ps_docx = out_dir / "personal_statement.pdf", out_dir / "personal_statement.docx"
+    _pdf_from_html(_statement_body_html(stmt), ps_pdf)
+    d = _new_docx("Personal Statement", "In support of an application for refugee status · Prepared with Refuge")
+    _docx_add_rich(d, stmt)
+    d.save(str(ps_docx))
+    docs.append(GeneratedDoc("personal_statement", "Personal statement (editable)",
+                             "Word + PDF · drafted for you, with placeholders to complete", ps_pdf, ps_docx))
+
+    # 2. Action plan
+    country, intro, steps = _action_plan_blocks(session, rec)
+    ap_html = (f"<h1>Action Plan — {html.escape(country)}</h1>"
+               '<p class="sub">Step-by-step roadmap · Prepared with Refuge</p>'
+               f"<p>{html.escape(intro)}</p>" +
+               "".join(f'<p class="step"><b>Step {i}.</b> {html.escape(str(s))}</p>'
+                       for i, s in enumerate(steps, 1)))
+    ap_pdf, ap_docx = out_dir / "action_plan.pdf", out_dir / "action_plan.docx"
+    _pdf_from_html(ap_html, ap_pdf)
+    d = _new_docx(f"Action Plan — {country}", "Step-by-step roadmap · Prepared with Refuge")
+    d.add_paragraph(intro)
+    for i, s in enumerate(steps, 1):
+        d.add_paragraph(f"Step {i}. {s}", style="List Number" if "List Number" in [s.name for s in d.styles] else None)
+    d.save(str(ap_docx))
+    docs.append(GeneratedDoc("action_plan", "Action plan", "Word + PDF · roadmap with contacts", ap_pdf, ap_docx))
+
+    # 3. Emergency contacts
+    office = (rec or {}).get("unhcrOffice") or "Nearest UNHCR office"
+    orgs = _orgs(rec)
+    ec_html = ("<h1>Emergency Contacts</h1>"
+               '<p class="sub">UNHCR offices &amp; legal aid · Prepared with Refuge</p>'
+               f"<h2>{html.escape(country)}</h2><p>UNHCR office: {html.escape(office)}</p>"
+               "<h2>Legal aid &amp; support</h2>" +
+               ("".join(f'<div class="org"><b>{html.escape(n)}</b><span>{html.escape(u)}</span></div>' for n, u in orgs)
+                or "<p>Ask the UNHCR office for registered legal-aid partners.</p>"))
+    ec_pdf, ec_docx = out_dir / "emergency_contacts.pdf", out_dir / "emergency_contacts.docx"
+    _pdf_from_html(ec_html, ec_pdf)
+    d = _new_docx("Emergency Contacts", "UNHCR offices & legal aid · Prepared with Refuge")
+    d.add_paragraph(f"{country} — UNHCR office: {office}")
+    for n, u in orgs:
+        d.add_paragraph(f"{n} — {u}")
+    d.save(str(ec_docx))
+    docs.append(GeneratedDoc("emergency_contacts", "Emergency contacts", "Word + PDF · UNHCR & legal aid", ec_pdf, ec_docx))
+
+    # 4. Rights summary card
+    grounds = ", ".join(session.assessment.convention_grounds) if session.assessment.convention_grounds else "to be confirmed"
+    rc_html = ("<h1>Your Rights — Summary Card</h1>"
+               '<p class="sub">Key protections · Prepared with Refuge</p>'
+               "<h2>Non-refoulement</h2><p>You cannot be forced back to a country where your life or freedom "
+               "would be at serious risk (1951 Refugee Convention).</p>"
+               "<h2>While your claim is decided</h2><ul>"
+               "<li>The right to seek asylum and a fair hearing.</li>"
+               "<li>The right to an interpreter and free legal assistance.</li>"
+               "<li>The right not to be detained arbitrarily.</li>"
+               "<li>The right to shelter, food, and emergency healthcare.</li></ul>"
+               f"<p>Origin: {html.escape(session.interview.origin_country or '[origin]')} · "
+               f"Seeking protection in: {html.escape(country)} · Grounds: {html.escape(grounds)}</p>")
+    rc_pdf, rc_docx = out_dir / "rights_summary_card.pdf", out_dir / "rights_summary_card.docx"
+    _pdf_from_html(rc_html, rc_pdf)
+    d = _new_docx("Your Rights — Summary Card", "Key protections · Prepared with Refuge")
+    d.add_paragraph("Non-refoulement: you cannot be forced back to a country where your life or freedom "
+                    "would be at serious risk (1951 Refugee Convention).")
+    for r in ["The right to seek asylum and a fair hearing.",
+              "The right to an interpreter and free legal assistance.",
+              "The right not to be detained arbitrarily.",
+              "The right to shelter, food, and emergency healthcare."]:
+        d.add_paragraph(r, style=None)
+    d.save(str(rc_docx))
+    docs.append(GeneratedDoc("rights_summary_card", "Your rights — summary card", "Word + PDF · key protections", rc_pdf, rc_docx))
+
+    logger.info("Generated %d documents (PDF + DOCX) in %s", len(docs), out_dir)
     return docs
 
 
+def all_files(docs: list[GeneratedDoc]) -> list[str]:
+    files = []
+    for d in docs:
+        files.append(str(d.docx_path))
+        files.append(str(d.pdf_path))
+    return files
+
+
 def zip_package(docs: list[GeneratedDoc], out_dir: Path | None = None) -> Path:
-    """Bundle the generated PDFs into a single zip for "Download all"."""
-    base = Path(out_dir) if out_dir else docs[0].path.parent
+    base = Path(out_dir) if out_dir else docs[0].pdf_path.parent
     zip_path = base / "refuge_documents.zip"
     with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
-        for d in docs:
-            zf.write(d.path, arcname=d.path.name)
+        for f in all_files(docs):
+            zf.write(f, arcname=Path(f).name)
     return zip_path
 
 
-__all__ = [
-    "generate", "build_html", "preview_statement_html", "zip_package", "GeneratedDoc", "fill",
-]
+def preview_statement_html(session, statement: str | None = None) -> str:
+    """Head-less personal-statement snippet for the on-screen preview."""
+    stmt = statement or fallback_statement(session)
+    return ('<article class="doc"><h4>Personal Statement</h4>'
+            '<p class="doc__sub">In support of an application for refugee status · Prepared with Refuge</p>'
+            f"{_html_with_placeholders(stmt)}</article>")
+
+
+__all__ = ["generate", "preview_statement_html", "zip_package", "all_files", "GeneratedDoc"]

app/app.py

@@ -202,13 +202,13 @@ def build_app() -> gr.Blocks:
         # Recommendations -> Documents: generate the package for the chosen country.
         docs_outputs = [reco_ui.column, docs_ui.column, *docs_ui.render_outputs]
 
-        def show_documents(session):
+        async def show_documents(session):
             if session is None or not session.selected_country:
                 return [gr.update()] * len(docs_outputs)
             if session.state < State.DOCUMENTS:
                 from app.phases.interview import advance_to
                 advance_to(session, State.DOCUMENTS)
-            updates = docs_ui.populate(session)
+            updates = await docs_ui.populate(session)  # LLM drafts the statement
             return [gr.update(visible=False), gr.update(visible=True), *updates]
 
         reco_ui.proceed.click(show_documents, inputs=[session_st], outputs=docs_outputs)

app/phases/assessment.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass
 import gradio as gr
 
 from agent.events import ErrorEvent, TextDeltaEvent, ToolEndEvent, ToolStartEvent
+from agent.loop import LoopHooks
 from agent.tools.asylum_stats import asylum_stats_tool
 from agent.tools.country_lookup import country_lookup_tool, lookup_country
 from agent.tools.web_search import web_search_tool
@@ -31,12 +32,12 @@ ASSESSMENT_TOOLS = [web_search_tool, country_lookup_tool, asylum_stats_tool]
 FACT_FIELDS = [
     ("Country of origin", "origin_country", "text"),
     ("Current location", "current_country", "text"),
-    ("Reason for leaving", "persecution_types", "chips"),
+    ("What happened", "free_text_history", "text"),
     ("Immediate danger", "immediate_danger", "bool"),
-    ("Family situation", "family_situation", "text"),
+    ("Time displaced", "displacement_duration", "text"),
+    ("Documents", "documents_available", "list"),
     ("Languages", "languages_spoken", "list"),
     ("Destination preference", "destination_preferences", "list"),
-    ("Time displaced", "displacement_duration", "text"),
 ]
 
 ASSESSMENT_CSS = """
@@ -169,11 +170,29 @@ async def stream_assessment(session: SessionState, loop):
     pct = 5
     status = ""
     looked_up: list[str] = []  # countries the agent actually researched
+
+    # Agentic control (ported from pi's AgentLoopConfig hooks):
+    #  * stop once the structured @@ASSESSMENT block is produced (no rambling)
+    #  * privacy guard: never let the person's free-text story into a web query
+    def _stop(assistant_message, history):
+        return "@@ASSESSMENT" in (assistant_message or {}).get("content", "")
+
+    story = (session.interview.free_text_history or "").strip().lower()
+
+    def _guard(name, args):
+        if name == "web_search" and story:
+            q = str((args or {}).get("query", "")).lower()
+            if story and (story[:40] in q):
+                return {"block": True, "reason": "query contained personal narrative (privacy)"}
+        return None
+
+    hooks = LoopHooks(should_stop_after_turn=_stop, before_tool_call=_guard)
+
     yield facts_html, render_reason(acc), render_progress(pct, "")
 
     async for ev in loop.run(
         prompt, session, system_prompt=system_prompt,
-        tools=ASSESSMENT_TOOLS, thinking_level="medium",
+        tools=ASSESSMENT_TOOLS, thinking_level="medium", hooks=hooks,
     ):
         if isinstance(ev, TextDeltaEvent):
             acc += ev.delta

app/phases/documents.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 
 import gradio as gr
 
-from agent.tools.doc_generator import generate, preview_statement_html, zip_package
+from agent.tools.doc_generator import all_files, generate, preview_statement_html, zip_package
 from app.state.session import SessionState
 
 # Evidence checklist: (label, sublabel, document_available key or None).
@@ -91,12 +91,12 @@ def build(visible: bool = False, session_st: gr.State | None = None) -> Document
                     gr.HTML('<p class="pkg__lbl">Evidence to gather</p>')
                     checklist = gr.CheckboxGroup(
                         choices=[label for label, _s, _k in CHECKLIST],
-                        value=[], label="", elem_id="docs-checklist",
+                        value=[], label="", show_label=False, elem_id="docs-checklist",
                     )
-                    gr.HTML('<p class="pkg__lbl">Your files</p>')
-                    files = gr.File(label="", interactive=False, elem_id="docs-files")
+                    gr.HTML('<p class="pkg__lbl">Your files · Word (editable) + PDF</p>')
+                    files = gr.File(label="", show_label=False, interactive=False, elem_id="docs-files")
                     download_all = gr.DownloadButton(
-                        "⤓ Download all (4 files)", elem_id="docs-download", visible=False
+                        "⤓ Download all (Word + PDF)", elem_id="docs-download", visible=False
                     )
                     start_over = gr.Button(
                         "↺ Start over for a different country", elem_id="docs-startover"
@@ -104,13 +104,22 @@ def build(visible: bool = False, session_st: gr.State | None = None) -> Document
 
     render_outputs = [preview, checklist, files, download_all]
 
-    def populate(session: SessionState) -> list:
-        docs = generate(session)
+    async def populate(session: SessionState) -> list:
+        # The agent drafts the personal statement (LLM), then we render PDF + Word.
+        from agent.drafting import draft_personal_statement
+        try:
+            statement = await draft_personal_statement(session)
+        except Exception:
+            statement = None
+        if not statement:
+            from agent.drafting import fallback_statement
+            statement = fallback_statement(session)
+        docs = generate(session, statement=statement)
         zip_path = zip_package(docs)
         return [
-            gr.update(value=preview_statement_html(session)),
+            gr.update(value=preview_statement_html(session, statement)),
             gr.update(value=_checklist_values(session)),
-            gr.update(value=[str(d.path) for d in docs]),
+            gr.update(value=all_files(docs)),
             gr.update(value=str(zip_path), visible=True),
         ]
 

app/phases/recommendations.py

@@ -100,7 +100,14 @@ def _unhcr_label(rec: dict) -> str:
 
 def _acceptance_label(rec: dict) -> str:
     rate = rec.get("acceptanceRate")
-    return str(rate) if rate else "Not published"
+    if rate in (None, "", "PENDING"):
+        return "Not published"
+    try:
+        pct = float(rate)
+        pct = pct * 100 if pct <= 1 else pct  # stored as 0-1 fraction
+        return f"{round(pct)}%"
+    except (TypeError, ValueError):
+        return str(rate)
 
 
 def _language_label(rec: dict) -> str:
@@ -117,7 +124,7 @@ def card_body_html(rec: dict) -> str:
     facts = [
         ("Processing time", _processing_label(rec)),
         ("UNHCR office", _unhcr_label(rec)),
-        ("Acceptance (your profile)", _acceptance_label(rec)),
+        ("Recognition rate (recent)", _acceptance_label(rec)),
         ("Primary language", _language_label(rec)),
     ]
     facts_html = "".join(

requirements.txt

@@ -5,8 +5,9 @@
 # UI framework
 gradio==6.15.2          # latest 6.16.0
 
-# Document generation (Phase 5)
+# Document generation (Phase 5) — PDF + editable Word
 weasyprint==68.1        # latest 69.0
+python-docx==1.1.2      # latest 1.2.0 — editable .docx export
 
 # HTTP client (tool API calls; stubbed at this boundary in unit tests)
 httpx==0.28.0           # latest 0.28.1

tests/integration/test_documents.py

@@ -1,14 +1,14 @@
-"""tests/integration/test_documents.py — document package generation (T053).
+"""tests/integration/test_documents.py — document package (PDF + editable Word).
 
-Seeds a complete session (real Ethiopia/Sudan scenario) and generates the four
-PDFs with WeasyPrint. Asserts they are real, valid, non-empty, contain the
-person's real data, and contain no placeholder tokens.
+Seeds a complete session and generates the package with the deterministic
+fallback statement (no model needed). Asserts real, valid, non-empty PDF + DOCX
+files containing the person's real data and no forbidden placeholder tokens.
 """
 
 from pathlib import Path
 
 from agent.tools.country_lookup import lookup_country
-from agent.tools.doc_generator import generate, zip_package
+from agent.tools.doc_generator import all_files, generate, zip_package
 from app.state.session import SessionState, State
 
 
@@ -17,15 +17,13 @@ def _complete_session(origin="Ethiopia") -> SessionState:
     for target in (State.INTAKE, State.SITUATION, State.HISTORY, State.GOALS,
                    State.REVIEW, State.ASSESSMENT, State.RECOMMENDATIONS, State.DOCUMENTS):
         s.transition_to(target)
-    s.language = "Amharic"
+    s.language = "English"
     s.interview.origin_country = origin
     s.interview.current_country = "Sudan"
-    s.interview.persecution_types = ["Political", "Ethnic"]
+    s.interview.free_text_history = "Armed men came to our village in November."
     s.interview.immediate_danger = True
-    s.interview.family_situation = "two children"
-    s.interview.documents_available = ["passport"]
+    s.interview.documents_available = ["Passport"]
     s.interview.languages_spoken = ["Amharic", "Arabic"]
-    s.interview.free_text_history = "Armed men came to our village in November."
     s.assessment.convention_grounds = ["Political opinion"]
     s.assessment.recommended_countries = [lookup_country("Kenya")]
     s.selected_country = "Kenya"
@@ -34,37 +32,36 @@ def _complete_session(origin="Ethiopia") -> SessionState:
 
 def _pdf_text(path: Path) -> str:
     from pypdf import PdfReader
-
-    reader = PdfReader(str(path))
-    return "\n".join(page.extract_text() or "" for page in reader.pages)
+    return "\n".join(page.extract_text() or "" for page in PdfReader(str(path)).pages)
 
 
-def test_generates_four_nonempty_valid_pdfs(tmp_path):
+def test_generates_four_docs_each_pdf_and_docx(tmp_path):
     docs = generate(_complete_session(), out_dir=tmp_path)
     assert len(docs) == 4
     for d in docs:
-        assert d.path.exists()
-        data = d.path.read_bytes()
-        assert len(data) > 1000          # non-trivial
-        assert data[:5] == b"%PDF-"      # valid PDF header
+        assert d.pdf_path.exists() and d.docx_path.exists()
+        pdf = d.pdf_path.read_bytes()
+        assert pdf[:5] == b"%PDF-" and len(pdf) > 1000
+        docx = d.docx_path.read_bytes()
+        assert docx[:2] == b"PK" and len(docx) > 1000  # .docx is a zip
 
 
 def test_personal_statement_contains_real_origin(tmp_path):
     docs = generate(_complete_session(), out_dir=tmp_path)
-    statement = next(d for d in docs if d.key == "personal_statement")
-    assert "Ethiopia" in _pdf_text(statement.path)  # SC-039: real data
+    ps = next(d for d in docs if d.key == "personal_statement")
+    assert "Ethiopia" in _pdf_text(ps.pdf_path)
 
 
-def test_no_placeholder_tokens(tmp_path):
+def test_no_forbidden_placeholder_tokens(tmp_path):
     docs = generate(_complete_session(), out_dir=tmp_path)
     for d in docs:
-        text = _pdf_text(d.path)
+        text = _pdf_text(d.pdf_path)
         for forbidden in ("PLACEHOLDER", "[NAME]", "[COUNTRY]"):
-            assert forbidden not in text, f"{forbidden} found in {d.key}"
+            assert forbidden not in text, f"{forbidden} in {d.key}"
 
 
-def test_download_all_zip(tmp_path):
+def test_download_all_zip_has_eight_files(tmp_path):
     docs = generate(_complete_session(), out_dir=tmp_path)
+    assert len(all_files(docs)) == 8  # 4 docs × (pdf + docx)
     zip_path = zip_package(docs, out_dir=tmp_path)
-    assert zip_path.exists()
-    assert zip_path.stat().st_size > 1000
+    assert zip_path.exists() and zip_path.stat().st_size > 2000

tests/unit/test_doc_fields.py

@@ -1,49 +1,40 @@
-"""tests/unit/test_doc_fields.py — pre-fill field rules (T055).
+"""tests/unit/test_doc_fields.py — document drafting field rules.
 
-Pre-filled values trace to real session keys and are amber-highlighted; missing
-fields render as a blank line (never a crash, never an invented value).
+The personal statement is drafted (LLM at runtime; deterministic fallback here);
+pre-filled values trace to real session data; missing specifics become clearly
+marked [placeholders]; nothing is fabricated.
 """
 
-from agent.tools.doc_generator import build_html, fill
+from agent.drafting import fallback_statement
+from agent.tools.doc_generator import _html_with_placeholders, preview_statement_html
 from app.state.session import SessionState, State
 
 
-def test_fill_present_value_is_highlighted():
-    out = fill("Ethiopia", "interview.origin_country")
-    assert "Ethiopia" in out
-    assert 'class="fill"' in out
-
-
-def test_fill_missing_value_is_blank_not_placeholder():
-    out = fill(None, "interview.origin_country")
-    assert 'class="blank"' in out
-    assert "Ethiopia" not in out
-    assert "None" not in out  # never leak the literal None
-    assert "PLACEHOLDER" not in out and "[NAME]" not in out
-
-
-def test_fill_list_is_joined_and_escaped():
-    out = fill(["Political", "Ethnic"], "interview.persecution_types")
-    assert "Political, Ethnic" in out
-    safe = fill("<script>x</script>", "interview.free_text_history")
-    assert "<script>" not in safe  # HTML-escaped
-
-
-def _min_session() -> SessionState:
+def _session(origin="Ethiopia"):
     s = SessionState()
     for t in (State.INTAKE, State.SITUATION, State.HISTORY, State.GOALS, State.REVIEW,
               State.ASSESSMENT, State.RECOMMENDATIONS, State.DOCUMENTS):
         s.transition_to(t)
+    s.interview.origin_country = origin
+    s.interview.current_country = "Sudan"
+    s.interview.free_text_history = "Armed men came to our village."
     return s
 
 
-def test_build_html_with_no_data_does_not_crash():
-    # origin_country is None and nothing is filled — must render blanks, not crash.
-    s = _min_session()
-    htmls = build_html(s)
-    assert set(htmls) == {
-        "personal_statement", "action_plan", "emergency_contacts", "rights_summary_card"
-    }
-    statement = htmls["personal_statement"]
-    assert 'class="blank"' in statement  # origin rendered as a blank line
-    assert "None" not in statement
+def test_fallback_statement_uses_real_data_and_placeholders():
+    out = fallback_statement(_session())
+    assert "Ethiopia" in out                 # real data
+    assert "[your full name]" in out          # placeholder for the person to fill
+    assert "Armed men came to our village." in out
+
+
+def test_placeholders_highlighted_in_html():
+    html = _html_with_placeholders("My name is [your full name].")
+    assert 'class="fill"' in html and "[your full name]" in html
+
+
+def test_preview_renders_without_crash_on_empty_session():
+    s = SessionState()
+    html = preview_statement_html(s)  # no data -> placeholders, no crash
+    assert "Personal Statement" in html
+    assert "None" not in html