igel-qe-core 1.0.0

package/knowledge_base/generation/prompts.py

@@ -0,0 +1,755 @@
+"""
+Prompt templates for IGEL test case generation.
+
+Provides:
+  build_system_prompt()          → static IGEL expert system prompt
+  assemble_context_window()      → fit KB chunks into token budget
+  build_markdown_user_prompt()   → prompt for detailed markdown test doc
+  build_python_user_prompt()     → prompt for pytest Python file
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from knowledge_base.config import cfg
+
+logger = logging.getLogger(__name__)
+
+MAX_CONTEXT_TOKENS = int(getattr(cfg, "CONTEXT_TOKEN_BUDGET", 8000))
+_CHARS_PER_TOKEN = 3.8   # conservative estimate, avoids importing tiktoken here
+
+# Exact import block generated tests must use — injected verbatim into Python prompt
+_REQUIRED_IMPORTS = """\
+import time, allure
+import pytest
+from core.api.UMS import UMS
+from core.api.ums_wums_api import UMSWUMSApi
+from core.api.auth_token import UMSAuthTokenService
+from core.ssh.ssh import SSHClient
+from core.ui.ui_automation_text import OcrUiInteractor
+from bussiness.page_login import ums_login
+from config.read_config import ums_cred, device_cred, otp_secrets_cred, root_path
+from core.ssh.my_logger import logger
+from bussiness.onepassword_otp import OTPGenerator"""
+
+
+# ── Data Model ────────────────────────────────────────────────────────────────
+
+@dataclass
+class PromptContext:
+    topic: str
+    test_id: str
+    feature_area: str
+    product: str | None
+    context_chunks: list        # list[SearchResult] — avoid circular import
+    token_budget: int = MAX_CONTEXT_TOKENS
+    kg_context_block: str = ""
+    image_context_block: str = ""
+    web_context_block: str = ""
+    mcp_context_block: str = ""
+    memory_context_block: str = ""
+    temporal_context_block: str = ""
+    skip_assemble_window: bool = False
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def build_system_prompt() -> str:
+    return _SYSTEM_PROMPT
+
+
+def assemble_context_window(
+    results: list,
+    token_budget: int = MAX_CONTEXT_TOKENS,
+) -> tuple[list, int]:
+    """
+    Fit retrieved parent_content chunks into the token budget.
+    Prioritises higher rrf_score results. Truncates last chunk at word boundary if needed.
+    Returns (selected_results, estimated_tokens_used).
+    """
+    reserve = 800   # headroom for prompt template text
+    available = token_budget - reserve
+
+    def _rank_key(r) -> tuple[float, float]:
+        rr = getattr(r, "rerank_score", None)
+        if rr is not None:
+            return (-float(rr), -float(getattr(r, "rrf_score", 0.0)))
+        return (-float(getattr(r, "rrf_score", 0.0)), 0.0)
+
+    ordered = sorted(results, key=_rank_key)
+
+    selected = []
+    used = 0
+
+    for result in ordered:
+        chunk_tokens = _estimate_tokens(result.parent_content)
+        if used + chunk_tokens <= available:
+            selected.append(result)
+            used += chunk_tokens
+        elif available - used > 200:
+            # Truncate at word boundary to fill remaining space
+            remaining_chars = int((available - used) * _CHARS_PER_TOKEN)
+            truncated_content = _truncate_at_word(result.parent_content, remaining_chars)
+            # Create a shallow copy with truncated content
+            import copy
+            r = copy.copy(result)
+            r.parent_content = truncated_content + "\n[...truncated]"
+            selected.append(r)
+            used += _estimate_tokens(truncated_content)
+            break
+        else:
+            break
+
+    logger.debug("Context window: %d chunks, ~%d tokens", len(selected), used)
+    return selected, used
+
+
+def build_markdown_user_prompt(ctx: PromptContext) -> str:
+    if ctx.skip_assemble_window:
+        selected = list(ctx.context_chunks)
+        tokens_used = sum(_estimate_tokens(r.parent_content) for r in selected)
+    else:
+        selected, tokens_used = assemble_context_window(ctx.context_chunks, ctx.token_budget)
+
+    prefix_parts: list[str] = []
+    if getattr(ctx, "kg_context_block", "") and ctx.kg_context_block.strip():
+        prefix_parts.append(ctx.kg_context_block.strip())
+    if getattr(ctx, "image_context_block", "") and ctx.image_context_block.strip():
+        prefix_parts.append(ctx.image_context_block.strip())
+    if getattr(ctx, "web_context_block", "") and ctx.web_context_block.strip():
+        prefix_parts.append(ctx.web_context_block.strip())
+    if getattr(ctx, "mcp_context_block", "") and ctx.mcp_context_block.strip():
+        prefix_parts.append(ctx.mcp_context_block.strip())
+    if getattr(ctx, "memory_context_block", "") and ctx.memory_context_block.strip():
+        prefix_parts.append(ctx.memory_context_block.strip())
+    if getattr(ctx, "temporal_context_block", "") and ctx.temporal_context_block.strip():
+        prefix_parts.append(ctx.temporal_context_block.strip())
+
+    context_block = _format_context_block(selected)
+    if prefix_parts:
+        context_block = "\n\n".join(prefix_parts) + "\n\n" + context_block
+
+    sources = kb_sources_for_prompt(selected)
+    sources_short = ", ".join(dict.fromkeys(r.file_name for r in selected)) or "IGEL documentation"
+
+    return f"""Generate a JIRA-level detailed IGEL test case document using the knowledge base context below.
+
+TEST REQUEST
+============
+Test ID      : {ctx.test_id}
+Topic        : {ctx.topic}
+Feature Area : {ctx.feature_area}
+Product      : {ctx.product or "IGEL OS 12"}
+KB Sources   : {sources_short}
+KB traceability (IDs; same as SOURCE n / KB_REF in context): {sources}
+
+KNOWLEDGE BASE CONTEXT
+======================
+{context_block}
+
+INSTRUCTIONS
+============
+Using the context above, generate a complete JIRA-style test case. Match the exact level of
+detail shown in IGEL JIRA tickets — specific TC Setup navigation paths, exact CLI commands,
+precise expected results with exact UI element names.
+
+The user's ask may be short (e.g. "SSO test steps"); ALWAYS produce the FULL detailed document
+below — never a summary-only or bullet sketch. Depth must reflect what the KB passages support.
+
+EXECUTABLE STEP QUALITY (NON-NEGOTIABLE)
+----------------------------------------
+- Each TEST DATA sub-step must state WHO does WHAT WHERE: product surface (UMS Web, device session,
+  SSH shell, browser), exact control names, literal values to set or type.
+- Every EXPECTED RESULT must name a concrete check (exact strings, exit code, journal line,
+  screenshot-level detail). If the KB gives an exact log pattern or UI label, reproduce it verbatim.
+- Do NOT use filler phrases alone as expected results (e.g. "Pass", "OK", "Works as expected").
+- Copy navigation paths, CLI, registry-style keys, file paths, and URLs from SOURCE/KB_REF blocks
+  when present; do not substitute generic equivalents.
+- If the KB does not contain enough detail for a safe step, omit that step and note in
+  Additional Information that the KB did not specify it — do not guess.
+
+OUTPUT FORMAT
+=============
+
+# {ctx.test_id}: {ctx.topic}
+
+## Key Details
+| Field | Value |
+|-------|-------|
+| JIRA ID | {ctx.test_id} |
+| Category | (infer from feature area and context) |
+| Priority | High |
+| Type | (Integration / Functional / Hardware-dependent — infer from context) |
+| Feature Area | {ctx.feature_area} |
+| Product | {ctx.product or "IGEL OS 12"} |
+| Source Documents | {sources_short} |
+
+## Description
+(2-3 sentences: what feature is tested, what this test validates, why it matters)
+
+## Additional Information
+(Key technical notes as bullet points — include:
+- default values and what they mean
+- important config file paths like /etc/chromium-browser/... or /var/log/...
+- policy names and parameter names from context
+- any warnings or platform-specific notes from context)
+
+## Requirements
+- IGEL OS version: (from context)
+- UMS version: (from context)
+- (any app version requirements from context)
+
+## Preconditions
+(Bullet list — be specific. Example: "IGEL OS 12 device registered in UMS with online status confirmed in UMS console")
+
+## TC Setup — Configuration Navigation Paths
+(List all UMS/device configuration steps using the exact path format:
+`TC Setup > [Section] > [SubSection] > [Setting] = [value]`
+Example: `TC Setup: Apps > Zoom > Zoom Sessions > Session Name = "Test_Session"`)
+
+## Test Details
+
+### Test Step Table
+Three columns: **STEP** | **TEST DATA** | **EXPECTED RESULT**
+
+| # | STEP | TEST DATA | EXPECTED RESULT |
+|---|------|-----------|-----------------|
+
+For each step:
+- STEP: Brief title of what is being verified (e.g., "Check Hardware Video Acceleration")
+- TEST DATA: Numbered sub-steps with exact actions. Include:
+  * TC Setup navigation paths: `TC Setup: Apps > [App] > [Setting] = true/false`
+  * Exact CLI commands with full syntax: `ps ax | grep process-name`
+  * Exact file paths: `/var/log/user/app.log`
+  * Specific URLs for verification: `chrome://media-internals`
+  * Policy/config values: `HardwareAccelerationModeEnabled`
+- EXPECTED RESULT: Specific verifiable outcomes. Include:
+  * Exact UI elements visible (e.g., "Home, Chat, Meetings, Contacts tabs visible")
+  * Exact log output expected (e.g., "journalctl shows no errors for process X")
+  * Specific commands and their expected output
+  * Pass/fail criterion with exact wording
+
+Generate as many test steps as the KB context and KG entities justify — do not pad with
+vague or invented steps. Each step must have at least 2 concrete sub-steps in TEST DATA.
+If no manual TC is provided, derive all steps from the Knowledge Base passages and KG nodes
+retrieved above; use the exact registry keys, UI paths, and CLI commands found there.
+
+## Cleanup
+| Step | Action | Command/Navigation | Verification |
+|------|--------|--------------------|-------------|
+(Specific cleanup steps — detach profiles, reboot, verify clean state)
+
+## Troubleshooting
+| # | Issue | Symptoms | Root Cause | Fix |
+|---|-------|----------|------------|-----|
+(Minimum 3 specific issues from context — include exact diagnostic commands)
+
+Generate the complete document now. Use specific IGEL terminology, exact navigation paths,
+real CLI commands, and concrete expected values. Never write "TBD" or "[add here]"."""
+
+
+def format_kb_context_excerpt_for_python(results: list, max_chars: int = 7500) -> str:
+    """Ground pytest generation in the same KB text as markdown (truncated for token limits)."""
+    if not results:
+        return "(No KB chunks — do not invent product steps.)"
+    body = _format_context_block(results)
+    if len(body) <= max_chars:
+        return body
+    truncated = _truncate_at_word(body, max_chars)
+    return (
+        truncated
+        + "\n\n[...KB excerpt truncated for token budget; strings and paths above remain "
+        "authoritative for implementation.]\n"
+    )
+
+
+def build_python_user_prompt(ctx: PromptContext, markdown_content: str) -> str:
+    test_id_upper = ctx.test_id.upper()
+    slug = _slugify(ctx.topic)
+    filename = f"test_{ctx.test_id}_{slug}.py"
+    # Extract step count hint from markdown — use actual count, no artificial floor
+    step_count = markdown_content.lower().count("#### step") or markdown_content.lower().count("| # |") or 0
+
+    kb_excerpt = format_kb_context_excerpt_for_python(ctx.context_chunks)
+    extra_context = []
+    if getattr(ctx, "kg_context_block", "") and ctx.kg_context_block.strip():
+        extra_context.append(ctx.kg_context_block.strip())
+    if getattr(ctx, "web_context_block", "") and ctx.web_context_block.strip():
+        extra_context.append(ctx.web_context_block.strip())
+    if getattr(ctx, "mcp_context_block", "") and ctx.mcp_context_block.strip():
+        extra_context.append(ctx.mcp_context_block.strip())
+    extra_block = "\n\n".join(extra_context)
+
+    return f"""Generate a Python pytest file for the following IGEL test case.
+
+KNOWLEDGE BASE CONTEXT (PostgreSQL RAG — ground truth; implement only behavior supported here)
+================================================================================
+{extra_block + chr(10) + chr(10) if extra_block else ""}{kb_excerpt}
+
+SPECIFICATION (from markdown test case or topic summary)
+=========================================================
+{markdown_content[:4000]}
+
+Implement step logic that matches BOTH the specification table AND the KB context above: use the
+same navigation strings, shell commands, file paths, policy names, and on-screen text the KB shows.
+Do not add product-specific steps absent from the KB. Steps must be executable with this project's
+fixtures (UMS, WUMS, SSH, OCR) — no vague asserts.
+
+STRICT REQUIREMENTS — follow exactly, no deviations
+=====================================================
+
+1. FILE NAME: {filename}
+
+2. MODULE DOCSTRING (copy this template exactly):
+\"\"\"
+Test ID    : {ctx.test_id}
+Title      : {ctx.topic}
+Feature    : {ctx.feature_area}
+Product    : {ctx.product or "IGEL OS 12"}
+Description: [1-sentence description from specification above]
+Author     : IGEL QA Automation (AI-Generated)
+\"\"\"
+
+3. IMPORTS — copy these verbatim, do not add or remove any:
+{_REQUIRED_IMPORTS}
+
+4. MODULE-LEVEL (after imports):
+click = OcrUiInteractor()
+
+5. HELPER FUNCTIONS:
+def get_ssh():
+    return SSHClient(host=device_cred["host"], user=device_cred["user"],
+                     pwd=device_cred["pwd"], port=device_cred["port"])
+
+def _assign(ums, wums, device, profile_key, default_name, api_config):
+    profile = ums.get_profile_details(api_config.get(profile_key, default_name))
+    wums.assign_object(device["id"], profile["id"], "profile")
+    return profile
+
+def _detach(ums, wums, device, profile_key, default_name, api_config):
+    profile = ums.get_profile_details(api_config.get(profile_key, default_name))
+    wums.detach_profile(device["id"], profile["id"])
+
+6. STEP FUNCTIONS — generate {step_count if step_count > 0 else "one step per test scenario found in"} the specification above + 1 cleanup:
+   - Decorator: @allure.step("{test_id_upper} SN: [short description]")
+   - Signature: def {test_id_upper}_stepN(api_config, browser): -> bool
+   - Body pattern:
+     try:
+         ums  = UMS(ums_cred["base_url"], ums_cred["username"], ums_cred["password"])
+         wums = UMSWUMSApi(ums_cred["weburl"], ums_cred["username"], ums_cred["password"])
+         dev  = ums.get_vm_details(device_cred["hostname"])
+         [step implementation from specification]
+         return True / return result_bool
+     except Exception as e:
+         logger.error(f"{test_id_upper}_stepN: {{e}}"); return False
+
+   - Cleanup: @allure.step("{test_id_upper} Cleanup: [description]")
+     def {test_id_upper}_cleanup(api_config): -> bool
+
+7. TEST FUNCTIONS — one per step, SINGLE LINE each:
+   @allure.feature("{ctx.feature_area}")
+   @allure.severity(allure.severity_level.CRITICAL)
+   def test_{ctx.test_id}_step1(api_config, browser_instance): assert {test_id_upper}_step1(api_config, browser_instance)
+
+   @allure.feature("{ctx.feature_area}")
+   @allure.severity(allure.severity_level.CRITICAL)
+   def test_{ctx.test_id}_step2(api_config, browser_instance): assert {test_id_upper}_step2(api_config, browser_instance)
+
+   [continue for each step, then:]
+
+   @allure.feature("{ctx.feature_area}")
+   @allure.severity(allure.severity_level.MINOR)
+   def test_{ctx.test_id}_cleanup(api_config): assert {test_id_upper}_cleanup(api_config)
+
+8. RULES:
+   - ALL configurable values from api_config dict — NEVER hardcode IPs, passwords, or secrets
+   - Use ums_cred["base_url"], ums_cred["weburl"], device_cred — for hosts/URLs not in those dicts,
+     use string literals ONLY when they appear verbatim in the KB context (e.g. chrome:// URLs,
+     fixed IGEL paths). Never use example.com or guessed tenant URLs.
+   - Use click.is_text_present_on_screen() and click.click_text_on_screen() for OCR checks — pass
+     the exact visible strings from KB/spec, not paraphrases
+   - Use ssh.exec("command") with the exact commands from KB/spec (full flags/paths)
+   - Every step function returns bool; each step must encode a concrete observable check
+   - No TODO comments, no placeholder text, no "verify success" without a named check
+   - No additional imports beyond the verbatim block above
+
+Generate the complete Python file now. Output raw Python only — no markdown fences."""
+
+
+# ── Internal Helpers ──────────────────────────────────────────────────────────
+
+def _estimate_tokens(text: str) -> int:
+    return int(len(text) / _CHARS_PER_TOKEN)
+
+
+def _truncate_at_word(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    truncated = text[:max_chars]
+    last_space = truncated.rfind(" ")
+    return truncated[:last_space] if last_space > 0 else truncated
+
+
+def kb_trace_lines(results: list) -> list[str]:
+    """One trace string per retrieved parent context (same order as SOURCE n / KB_REF)."""
+    lines: list[str] = []
+    for i, r in enumerate(results, start=1):
+        doc = getattr(r, "document_id", "") or "—"
+        parent = getattr(r, "parent_chunk_id", "") or "—"
+        child = getattr(r, "child_chunk_id", "") or "—"
+        sec = getattr(r, "section_title", "") or "—"
+        fn = getattr(r, "file_name", "") or "—"
+        lines.append(
+            f"[KB_REF {i}] file={fn} | section={sec} | document_id={doc} | "
+            f"parent_chunk_id={parent} | child_chunk_id={child}"
+        )
+    return lines
+
+
+def kb_sources_for_prompt(results: list) -> str:
+    """Compact ID list for the prompt header (same KB_REF order as context blocks)."""
+    if not results:
+        return "IGEL documentation"
+    return "; ".join(kb_trace_lines(results))
+
+
+def format_kb_retrieval_references_markdown(results: list) -> str:
+    """Appendix for generated markdown: exact chunk traceability for cross-checking the KB."""
+    if not results:
+        return ""
+    rows = [
+        "| KB_REF | File | Section | document_id | parent_chunk_id | child_chunk_id | RRF | Rerank |",
+        "|--------|------|---------|-------------|-----------------|----------------|-----|--------|",
+    ]
+    for i, r in enumerate(results, start=1):
+        rr = getattr(r, "rerank_score", None)
+        rr_s = f"{rr:.4f}" if rr is not None else "—"
+        sec = (getattr(r, "section_title", None) or "").replace("|", "\\|")
+        fn = (getattr(r, "file_name", None) or "").replace("|", "\\|")
+        rows.append(
+            f"| {i} | {fn} | {sec} | `{getattr(r, 'document_id', '')}` | "
+            f"`{getattr(r, 'parent_chunk_id', '')}` | `{getattr(r, 'child_chunk_id', '')}` | "
+            f"{getattr(r, 'rrf_score', 0.0):.4f} | {rr_s} |"
+        )
+    note = (
+        "\n*These rows match the `SOURCE n` / `KB_REF` blocks in the knowledge base context "
+        "sent to the model. Use `parent_chunk_id` / `document_id` to locate rows in PostgreSQL "
+        "(`kb_parent_chunks`, `kb_documents`).*\n"
+    )
+    return "## KB retrieval traceability\n\n" + "\n".join(rows) + note
+
+
+def format_kb_retrieval_references_python_comment(results: list) -> str:
+    """Trailing comment block for generated pytest files (traceability)."""
+    if not results:
+        return ""
+    lines = ["# --- KB retrieval references (cross-check in DB / ingest logs) ---"]
+    for i, r in enumerate(results, start=1):
+        lines.append(
+            f"# [KB_REF {i}] file={getattr(r, 'file_name', '')!r} "
+            f"section={getattr(r, 'section_title', '')!r} "
+            f"document_id={getattr(r, 'document_id', '')!r} "
+            f"parent_chunk_id={getattr(r, 'parent_chunk_id', '')!r} "
+            f"child_chunk_id={getattr(r, 'child_chunk_id', '')!r}"
+        )
+    return "\n\n" + "\n".join(lines) + "\n"
+
+
+def _format_context_block(results: list) -> str:
+    if not results:
+        return "(No relevant KB content found)"
+    parts = []
+    for i, r in enumerate(results, start=1):
+        rr_tail = (
+            f" | Rerank: {r.rerank_score:.4f}"
+            if getattr(r, "rerank_score", None) is not None
+            else ""
+        )
+        parts.append(
+            f"=== SOURCE {i} (KB_REF={i}) | {r.section_title or r.file_name} ===\n"
+            f"document_id={r.document_id}\n"
+            f"parent_chunk_id={r.parent_chunk_id}\n"
+            f"child_chunk_id={r.child_chunk_id}\n"
+            f"Product: {r.product} | File: {r.file_name} | Section: {r.section_title or '—'} | "
+            f"Type: {r.chunk_type} | Relevance_RRF: {r.rrf_score:.4f}{rr_tail}\n\n"
+            f"{r.parent_content.strip()}"
+        )
+    return "\n\n" + "\n\n---\n\n".join(parts) + "\n"
+
+
+def _slugify(text: str) -> str:
+    import re
+    slug = text.lower()
+    slug = re.sub(r"[^a-z0-9\s]", "", slug)
+    slug = re.sub(r"\s+", "_", slug.strip())
+    return slug[:50]
+
+
+# ── Gold / partial TC modes (fidelity-first) ─────────────────────────────────
+
+TRANSFORM_SYSTEM_ADDON = """
+
+MODE: MANUAL TEST CASE TRANSFORMATION (not authoring)
+======================================================
+The user supplied an official IGEL manual test. Your job is to REPACKAGE it into the template format
+and (when asked) pytest structure — NOT to invent new scenarios, edge cases, or extra steps.
+Preserve step count and order. Use supplementary KB text only to clarify terms already present.
+"""
+
+EXPAND_SYSTEM_ADDON = """
+
+MODE: PARTIAL TEST CASE EXPANSION
+=================================
+The user supplied an incomplete JIRA/manual TC. Keep every original step and phrase intact in the output.
+Add ONLY missing expected results, preconditions, or clarifying sub-steps where the description implies them.
+Use KB context to ground new text. Do not replace or remove original steps.
+"""
+
+
+def load_pytest_exemplar(max_chars: int = 6000) -> str:
+    """Few-shot excerpt from a known-good generated/hand-written pytest file."""
+    from pathlib import Path
+    p = Path(__file__).resolve().parent / "exemplars" / "pytest_reference_snippet.py"
+    if not p.exists():
+        return ""
+    text = p.read_text(encoding="utf-8", errors="replace")
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + "\n# [...truncated exemplar]\n"
+
+
+def format_parsed_steps_table(steps: list) -> str:
+    """Markdown table from ParsedStep list."""
+    if not steps:
+        return "(no parsed steps)"
+    rows = [
+        "| # | Step | Test Data | Expected Result |",
+        "|---|------|-----------|-----------------|",
+    ]
+    for s in steps:
+        def _cell(x: str, lim: int) -> str:
+            t = (x or "").replace("\n", " ").replace("|", "\\|").strip()
+            return t[:lim] + ("…" if len(t) > lim else "")
+
+        rows.append(
+            f"| {_cell(s.step_id, 12)} | {_cell(s.step_title, 80)} | "
+            f"{_cell(s.test_data, 220)} | {_cell(s.expected_result, 120)} |"
+        )
+    return "\n".join(rows)
+
+
+def build_transform_markdown_user_prompt(
+    *,
+    test_id: str,
+    feature_area: str,
+    product: str | None,
+    source_tc_full: str,
+    supplementary_context: str,
+    detail_note: str,
+) -> str:
+    return f"""Convert the OFFICIAL IGEL manual test case below into the project's JIRA-style Markdown template.
+
+CRITICAL — FIDELITY FIRST
+=========================
+- The ORIGINAL MANUAL TEST CASE section is the SOURCE OF TRUTH.
+- Preserve EVERY step's intent, order, and scope. Do NOT add scenarios, negative tests, or steps not in the source.
+- Do NOT remove steps. Do NOT merge unless the source explicitly combines them in one line.
+- Refine wording only for readability; keep TC Setup paths, CLI, URLs, registry keys, and expected outcomes aligned with the source.
+- The final Test Step Table must allow 1:1 traceability to the original step list.
+
+Detail target: {detail_note}
+
+ORIGINAL MANUAL TEST CASE
+=========================
+{source_tc_full.strip()}
+
+SUPPLEMENTARY KB CONTEXT (use only to clarify terms present in the source; never add unrelated test ideas)
+==================================================================================
+{supplementary_context.strip() if supplementary_context.strip() else "(none)"}
+
+OUTPUT METADATA (use in Key Details)
+====================================
+Test ID      : {test_id}
+Feature Area : {feature_area}
+Product      : {product or "IGEL OS 12"}
+
+Produce: Key Details, Description, Preconditions, TC Setup, Test Step Table (STEP | TEST DATA | EXPECTED RESULT),
+Additional Information, Requirements, Cleanup, Troubleshooting — following the same section expectations as standard generation.
+"""
+
+def build_expand_markdown_user_prompt(
+    *,
+    test_id: str,
+    topic: str,
+    feature_area: str,
+    product: str | None,
+    source_tc_full: str,
+    parsed_steps_table: str,
+    kb_context_block: str,
+    kg_image_prefix: str,
+    detail_note: str,
+) -> str:
+    prefix = kg_image_prefix.strip()
+    body = kb_context_block.strip()
+    context = f"{prefix}\n\n{body}".strip() if prefix else body
+    return f"""Expand this PARTIAL IGEL test case into a complete JIRA-style Markdown document.
+
+RULES
+=====
+- Reproduce EVERY original line/step from the partial TC; keep titles and actions verbatim where possible.
+- Fill gaps: missing Expected Results, Preconditions, or TC Setup paths using ONLY the knowledge context below.
+- If KB does not support a detail, write "Not specified in KB — manual confirmation required" instead of inventing.
+- Do not add unrelated scenarios.
+
+Detail target: {detail_note}
+
+PARTIAL TEST CASE (raw)
+=======================
+{source_tc_full.strip()}
+
+PARSED STEPS (reference)
+========================
+{parsed_steps_table}
+
+TOPIC / SUMMARY
+===============
+{topic}
+
+KNOWLEDGE CONTEXT (RAG + KG + images)
+=====================================
+{context if context else "(no retrieval — expand from source only)"}
+
+OUTPUT METADATA
+===============
+Test ID      : {test_id}
+Feature Area : {feature_area}
+Product      : {product or "IGEL OS 12"}
+
+Generate the full Markdown document with the standard sections and a complete Test Step Table.
+"""
+
+def build_transform_python_user_prompt(
+    *,
+    test_id: str,
+    topic: str,
+    feature_area: str,
+    product: str | None,
+    markdown_spec: str,
+    exemplar_py: str,
+) -> str:
+    """Python generation after transform markdown — reuses structure from build_python_user_prompt."""
+    slug = _slugify(topic)
+    filename = f"test_{test_id}_{slug}.py"
+    test_id_upper = test_id.upper()
+    step_count = max(markdown_spec.lower().count("#### step"), markdown_spec.count("|") // 3, 3)
+
+    exemplar_block = exemplar_py.strip() if exemplar_py.strip() else "(see standard import pattern in instructions)"
+
+    return f"""Generate a Python pytest file that implements EXACTLY the manual flow in the specification below.
+
+FIDELITY
+========
+- Implement one step function per logical step in the Markdown spec (same order). Do not add exploratory or negative tests.
+- Each step should reflect the Test Data and Expected Result from the spec.
+- Use api_config / ums_cred / device_cred — never hardcode secrets.
+
+REFERENCE EXAMPLE (shape and style only — do not copy unrelated scenarios)
+==========================================================================
+```python
+{exemplar_block[:5500]}
+```
+
+SPECIFICATION
+=============
+{markdown_spec[:6500]}
+
+STRICT REQUIREMENTS
+===================
+1. FILE NAME: {filename}
+
+2. MODULE DOCSTRING:
+\"\"\"
+Test ID    : {test_id}
+Title      : {topic}
+Feature    : {feature_area}
+Product    : {product or "IGEL OS 12"}
+Description: Mapped from official IGEL manual TC (fidelity mode)
+Author     : IGEL QA Automation (AI-Generated)
+\"\"\"
+
+3. IMPORTS — copy verbatim:
+{_REQUIRED_IMPORTS}
+
+4. After imports: click = OcrUiInteractor()
+
+5. Helpers: get_ssh(), _assign(...), _detach(...) as in standard generator.
+
+6. Generate approximately {step_count} step functions + 1 cleanup. Each step returns bool.
+
+7. TEST FUNCTIONS: single-line assert per step; @allure.feature("{feature_area}")
+
+Output raw Python only — no markdown fences.
+"""
+
+
+# ── System Prompt ─────────────────────────────────────────────────────────────
+
+_SYSTEM_PROMPT = """\
+You are a senior IGEL QA automation engineer with deep expertise in testing IGEL products.
+Your job is to generate precise, complete, and executable test cases based ONLY on the
+documentation context provided. Never invent steps, settings, or expected values not
+explicitly present in the context.
+
+IGEL PRODUCT KNOWLEDGE
+======================
+- UMS (Universal Management Suite): Central device management server. REST API on HTTPS port 8443.
+  URL pattern: https://<ums-ip>:8443/umsapi/v3/. Used to manage profiles, assign them to devices,
+  and issue commands (reboot, factory reset). Web UI at https://<ums-ip>:8443/webapp/.
+- IGEL OS 12: Linux-based thin client operating system. SSH accessible as root on port 22.
+  Device can be controlled via UMS API (profiles) and directly via SSH commands.
+- COSMOS: Cloud-based management platform for IGEL devices (cloud alternative to on-prem UMS).
+- ICG (IGEL Cloud Gateway): Secure reverse proxy allowing UMS to communicate with devices
+  outside the corporate network without VPN.
+- IMI (IGEL Management Interface): REST API for programmatic UMS control (token-based auth).
+- SSO Providers: Entra ID (Microsoft Azure AD), Okta, PingOne, Omnissa Horizon.
+
+TEST AUTOMATION FRAMEWORK
+=========================
+- Python + pytest with Allure reporting
+- UMS class: core.api.UMS — manages device/profile assignments via REST
+- UMSWUMSApi class: core.api.ums_wums_api — assign/detach profiles, device operations
+- SSHClient: core.ssh.ssh — execute shell commands on IGEL device via SSH
+- OcrUiInteractor (click): core.ui.ui_automation_text — OCR-based screen validation and interaction
+- ums_login: bussiness.page_login — Playwright browser automation for UMS Web UI
+- OTPGenerator: bussiness.onepassword_otp — TOTP generation for MFA flows
+- Configuration: config.read_config — ums_cred, device_cred, otp_secrets_cred, root_path
+- api_config: loaded from testdata/sso/api_config.yaml["igel"] — profile names, usernames, etc.
+
+GENERATION RULES
+================
+1. Use ONLY the provided KB context passages. If a step is not in the context, do not include it.
+2. ALL configurable values (profile names, URLs, usernames) come from api_config["key"] or
+   ums_cred/device_cred dicts. NEVER hardcode actual IPs, passwords, or credentials.
+3. For markdown: follow the template structure exactly with all required sections and tables.
+4. For Python: step functions MUST return bool; test functions MUST be single-line assert calls.
+5. Be specific: use actual IGEL terminology, SSH commands, and OCR check patterns from context.
+6. Cleanup steps are mandatory — always detach profiles and reboot the device.
+
+DETAILED & EXECUTABLE STEPS (MANDATORY)
+=======================================
+- Answer the user's topic with the MOST DETAILED test flow the KB allows — whether they asked for
+  "high-level steps", "test steps", or "detailed steps", always expand into full executable steps.
+- Every step MUST be something a tester can run without interpretation: exact menu paths, exact CLI
+  with full syntax, exact file paths, exact policy/parameter names, exact UI strings to look for.
+- FORBIDDEN vague wording: "verify it works", "ensure proper behavior", "check configuration",
+  "validate the setup", "confirm success", "test the feature" without naming WHAT is observed WHERE.
+- REQUIRED: each EXPECTED RESULT ties to an observable (visible label, log line, command output,
+  HTTP status, file content snippet, API field) copied from or clearly implied by the KB context.
+- URLs and URI schemes: ONLY use URLs, deep links, and browser/chrome internal URLs that appear in
+  the KB context (or standard patterns documented there, e.g. UMS port 8443 paths). NEVER invent
+  placeholder URLs (no example.com, no made-up tenant hostnames). For tenant-specific endpoints,
+  express hosts via ums_cred / api_config in generated code; in markdown describe the pattern.
+- General platform knowledge may clarify HOW to run a command already in context, but must not add
+  new product-specific claims or paths not supported by the retrieved passages.
+"""