igel-qe-core 1.0.0

package/knowledge_base/api/server.py

@@ -0,0 +1,778 @@
+"""
+IGEL Test Case Generation — Always-Running REST API
+=====================================================
+Start:
+    uvicorn knowledge_base.api.server:app --host 0.0.0.0 --port 8000
+
+Endpoints:
+    POST /query      — Ask any test-case-related question; returns detailed KB-grounded steps
+    POST /generate   — Full test case generation (markdown + python) from a topic and/or pasted manual TC
+    POST /convert    — Convert a gold/partial manual TC to pytest (faithful transform/expand pipeline)
+    POST /feedback   — Submit feedback on generated output for curation
+    POST /generate/v2 — Agentic generation (LangGraph multi-agent pipeline)
+    POST /rca        — Root cause analysis for test failures (Phase 7)
+    POST /heal       — Script healing for flaky tests (Phase 7)
+    POST /impact-analysis — Regression impact from change set (Phase 7)
+    GET  /health     — DB, KG, and embedding readiness check
+    GET  /stats      — Current KB statistics (docs, chunks, KG nodes/edges)
+"""
+from __future__ import annotations
+
+import logging
+import tempfile
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from uuid import uuid4
+
+import anyio
+from fastapi import FastAPI, HTTPException, Depends, Header, Request
+from pydantic import BaseModel, Field, model_validator, field_validator
+
+from knowledge_base.config import cfg
+from knowledge_base.db.client import init_pool, test_connection, close_pool, get_conn
+from knowledge_base.db.schema import create_schema, get_stats, ensure_knowledge_graph_tables
+from knowledge_base.db.feedback_schema import ensure_feedback_tables
+from knowledge_base.feedback.handler import capture_feedback
+from knowledge_base.retrieval.unified_query import unified_query
+from knowledge_base.core.logging_setup import configure_logging
+from knowledge_base.core.metrics import metrics, Timer
+from knowledge_base.core.request_context import (
+    api_key_scope_var,
+    get_request_id,
+    hash_api_key,
+    resolve_scope,
+)
+from knowledge_base.api.middleware import RequestTracingMiddleware, RateLimitMiddleware
+from knowledge_base.generation.prompts import (
+    PromptContext,
+    build_system_prompt,
+    build_markdown_user_prompt,
+    format_kb_retrieval_references_markdown,
+    kb_trace_lines,
+)
+from knowledge_base.generation.test_generator import (
+    generate_test_cases,
+    _infer_feature_area,
+    _call_gpt,
+)
+
+logging.basicConfig(level=getattr(logging, cfg.LOG_LEVEL, "INFO"), format="%(levelname)s %(message)s")
+configure_logging(level=cfg.LOG_LEVEL, json_logs=cfg.JSON_LOGS)
+logger = logging.getLogger(__name__)
+_THREAD_LIMITER = anyio.CapacityLimiter(max(2, int(getattr(cfg, "ASYNC_THREAD_LIMIT", 16))))
+
+
+async def _run_blocking(fn):
+    """Run blocking call in bounded worker pool and abandon await on cancellation."""
+    try:
+        return await anyio.to_thread.run_sync(fn, abandon_on_cancel=True, limiter=_THREAD_LIMITER)
+    except TypeError:
+        # Backward compatibility with older AnyIO versions.
+        return await anyio.to_thread.run_sync(fn, limiter=_THREAD_LIMITER)
+
+
+# ── Lifespan: DB pool + schema verification on startup ────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("Starting IGEL Test Generation Server...")
+    logger.info("  DB: %s:%s/%s", cfg.DB_HOST, cfg.DB_PORT, cfg.DB_NAME)
+    logger.info("  LLM: %s @ %s", cfg.AZURE_DEPLOYMENT, cfg.AZURE_ENDPOINT[:40])
+    logger.info("  KG enabled: %s", cfg.KG_ENABLED)
+
+    init_pool()
+    try:
+        if not test_connection():
+            raise RuntimeError("Cannot connect to PostgreSQL — check knowledge_base/.env")
+
+        create_schema()
+        ensure_knowledge_graph_tables()
+        ensure_feedback_tables()
+
+        stats = get_stats()
+        logger.info(
+            "  KB ready: %d docs, %d parent chunks, %d child chunks, %d KG nodes, %d KG edges",
+            stats["documents"], stats["parent_chunks"], stats["chunks"],
+            stats.get("kg_nodes", 0), stats.get("kg_edges", 0),
+        )
+        if stats["documents"] == 0:
+            logger.warning("  KB is EMPTY — run: python -m knowledge_base.ingestion.ingest")
+        orphans = stats.get("kg_orphan_parents (no KG entity)", 0)
+        if orphans > 0:
+            logger.warning("  %d parent chunks have no KG entity — run: python -m knowledge_base.ingestion.ingest --enrich-orphans", orphans)
+
+        if cfg.RERANKER_BACKEND == "local":
+            try:
+                from knowledge_base.retrieval.reranker import warm_start_reranker
+                warm_start_reranker()
+                logger.info("  Reranker model pre-loaded")
+            except Exception as exc:
+                logger.warning("  Reranker warm start failed: %s", exc)
+
+        yield
+    finally:
+        close_pool()
+        logger.info("Server shut down.")
+
+
+app = FastAPI(
+    title="IGEL Test Case Generation API",
+    description="Always-running service: RAG + Knowledge Graph in sync. "
+                "Ask test-case questions or generate full executable test cases from the IGEL KB.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+app.add_middleware(RateLimitMiddleware)
+app.add_middleware(RequestTracingMiddleware)
+
+
+# ── Request/Response Models ───────────────────────────────────────────────────
+
+class QueryRequest(BaseModel):
+    question: str = Field(..., max_length=2000, description="Natural language question about IGEL test cases")
+    product: Optional[str] = Field(None, description="Filter by product: UMS, IGEL OS, COSMOS, ICG, IMI")
+    top_k: int = Field(8, ge=1, le=20, description="Number of KB chunks to retrieve")
+
+class QueryResponse(BaseModel):
+    answer: str
+    kb_sources: List[str]
+    kg_entities_used: int
+    retrieval_chunks: int
+    web_hits: int = 0
+    mcp_hits: int = 0
+    sources_queried: List[str] = Field(default_factory=list)
+    tokens_used: int
+    generation_time_sec: float
+
+class GenerateRequest(BaseModel):
+    topic: str = Field(
+        "",
+        description="Test case topic or short label. May be omitted if source_tc is provided.",
+    )
+    product: Optional[str] = Field(None, description="Filter by product")
+    top_k: int = Field(8, ge=1, le=20)
+    output_format: str = Field("both", description="md, py, or both")
+    test_id: Optional[str] = Field(None, description="Custom test ID like TC015")
+    feature_area: Optional[str] = Field(None, description="Allure feature group")
+    source_tc: Optional[str] = Field(
+        None,
+        description="Optional pasted official manual TC (CSV / JIRA export). Enables transform or expand mode.",
+    )
+    detail_level: Optional[str] = Field(
+        None,
+        description="concise | detailed | auto — overrides default detail / classification hints.",
+    )
+    generation_mode: Optional[str] = Field(
+        None,
+        description="pipeline | agentic — A/B generation path (default from config).",
+    )
+
+    @model_validator(mode="after")
+    def _require_topic_or_source(self):
+        if not (self.topic or "").strip() and not (self.source_tc or "").strip():
+            raise ValueError("Provide a non-empty `topic` and/or `source_tc`.")
+        return self
+
+    @field_validator("source_tc")
+    @classmethod
+    def _limit_source_tc(cls, v: Optional[str]) -> Optional[str]:
+        if v and len(v) > 50_000:
+            raise ValueError("source_tc exceeds 50KB limit")
+        return v
+
+
+class ConvertRequest(BaseModel):
+    """Dedicated body for gold / partial manual TC → pytest (no topic-only synthesis)."""
+
+    source_tc: str = Field(..., max_length=50000, description="Full manual test case text (structured steps).")
+    topic: str = Field(
+        "",
+        description="Short label or JIRA key for naming (defaults from first line of source_tc).",
+    )
+    product: Optional[str] = Field(None)
+    top_k: int = Field(8, ge=1, le=20)
+    output_format: str = Field("both", description="md, py, or both")
+    test_id: Optional[str] = Field(None)
+    feature_area: Optional[str] = Field(None)
+    detail_level: Optional[str] = Field(None, description="concise | detailed | auto")
+
+class GenerateResponse(BaseModel):
+    test_id: str
+    topic: str
+    feature_area: str
+    markdown_content: Optional[str]
+    python_content: Optional[str]
+    kb_sources: List[str]
+    kb_chunk_count: int
+    tokens_used: int
+    generation_time_sec: float
+    syntax_valid: bool
+    warnings: List[str]
+    traceability_table: str
+    confidence: Optional[dict] = None
+    precedence_conflicts: List[dict] = Field(default_factory=list)
+
+
+class FeedbackRequest(BaseModel):
+    query: str = Field(..., max_length=2000, description="Original query or topic used for generation")
+    generated_output: dict = Field(..., description="Full generation payload (markdown, python, etc.)")
+    feedback_type: str = Field(..., description="rating | correction | edit | rejection | execution_failure")
+    feedback_data: dict = Field(default_factory=dict, description="Structured feedback payload")
+    user_id: Optional[str] = None
+    session_id: Optional[str] = None
+    generation_metadata: Optional[dict] = None
+    source_context: Optional[dict] = None
+
+
+class FeedbackResponse(BaseModel):
+    feedback_id: str
+    status: str = "pending"
+    message: str = "Feedback captured for curation"
+
+class HealthResponse(BaseModel):
+    status: str
+    db_connected: bool
+    documents: int
+    chunks: int
+    kg_nodes: int
+    kg_edges: int
+    kg_orphan_parents: int
+    kg_backend: str = "postgres"
+    neo4j: Optional[dict] = None
+    cognee: Optional[dict] = None
+    graphiti: Optional[dict] = None
+    phase: str = "phase1"
+
+
+class AgenticGenerateRequest(BaseModel):
+    query: str = Field(..., description="Test case topic or scenario")
+    product: Optional[str] = None
+    top_k: int = Field(8, ge=1, le=20)
+    output_format: str = Field("both", description="md, py, or both")
+    test_id: Optional[str] = None
+
+
+class AgenticGenerateResponse(BaseModel):
+    test_id: str
+    query: str
+    feature_area: str
+    markdown_content: Optional[str]
+    python_content: Optional[str]
+    confidence: Optional[dict] = None
+    sources_used: List[str] = Field(default_factory=list)
+    agent_trace: List[dict] = Field(default_factory=list)
+    validation_errors: List[str] = Field(default_factory=list)
+    validation_warnings: List[str] = Field(default_factory=list)
+    warnings: List[str] = Field(default_factory=list)
+
+
+class RCARequest(BaseModel):
+    test_id: str
+    failure_log: str = ""
+
+
+class HealRequest(BaseModel):
+    test_id: str
+    flaky_history: List[dict] = Field(default_factory=list)
+
+
+class ImpactAnalysisRequest(BaseModel):
+    changed_files: List[str] = Field(..., min_length=1)
+
+
+# ── Auth middleware (Phase 9) ─────────────────────────────────────────────────
+
+async def verify_api_key(x_api_key: Optional[str] = Header(default=None, alias="X-API-Key")):
+    if not cfg.API_KEY_REQUIRED:
+        api_key_scope_var.set("admin")
+        return
+    scope = resolve_scope(x_api_key, cfg.api_key_map, cfg.API_KEY)
+    if scope == "invalid":
+        metrics.inc("auth_failures_total")
+        raise HTTPException(status_code=401, detail="Invalid or missing API key")
+    api_key_scope_var.set(scope)
+
+
+def require_scope(*allowed: str):
+    async def _check(_: None = Depends(verify_api_key)):
+        scope = api_key_scope_var.get()
+        if scope == "admin" or scope in allowed:
+            return
+        raise HTTPException(status_code=403, detail=f"Insufficient scope: need one of {allowed}")
+    return _check
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@app.get("/metrics")
+async def prometheus_metrics():
+    from fastapi.responses import PlainTextResponse
+    return PlainTextResponse(metrics.render_prometheus(), media_type="text/plain; version=0.0.4")
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health():
+    """Check system readiness: DB, KB population, KG health."""
+    try:
+        ok = test_connection()
+    except Exception:
+        ok = False
+    if not ok:
+        raise HTTPException(503, detail="Database not reachable")
+
+    stats = get_stats()
+    orphans = stats.get("kg_orphan_parents (no KG entity)", 0)
+    status = "healthy"
+    if stats["documents"] == 0:
+        status = "empty_kb"
+    elif stats.get("kg_nodes", 0) == 0:
+        status = "kg_empty"
+
+    reranker_ok = True
+    try:
+        from knowledge_base.retrieval.reranker import is_reranker_loaded
+        reranker_ok = is_reranker_loaded()
+    except Exception:
+        reranker_ok = False
+    if not reranker_ok and cfg.RERANKER_BACKEND == "local":
+        status = "degraded" if status == "healthy" else status
+
+    redis_ok = None
+    try:
+        from knowledge_base.core.cache import _redis
+        r = _redis()
+        redis_ok = r is not None and r.ping()
+    except Exception:
+        redis_ok = False
+
+    return HealthResponse(
+        status=status,
+        db_connected=True,
+        documents=stats["documents"],
+        chunks=stats["chunks"],
+        kg_nodes=stats.get("kg_nodes", 0),
+        kg_edges=stats.get("kg_edges", 0),
+        kg_orphan_parents=orphans,
+        kg_backend=cfg.KG_BACKEND,
+        neo4j=_component_health("neo4j"),
+        cognee=_component_health("cognee"),
+        graphiti=_component_health("graphiti"),
+        phase=_current_phase(),
+    )
+
+
+@app.get("/stats")
+async def stats():
+    """Full KB statistics."""
+    return get_stats()
+
+
+@app.post("/query", response_model=QueryResponse, dependencies=[Depends(require_scope("read", "write", "admin"))])
+async def query_test_steps(req: QueryRequest):
+    """
+    Ask any question related to IGEL test cases.
+    Returns detailed, executable test steps grounded in the Knowledge Base.
+    The response uses real registry keys, TC Setup paths, CLI commands from the DB.
+    """
+    if not req.question.strip():
+        raise HTTPException(400, detail="question cannot be empty")
+
+    t0 = time.time()
+
+    retrieval_timeout = max(1.0, float(getattr(cfg, "QUERY_TIMEOUT_SECONDS", 60)))
+    try:
+        with anyio.fail_after(retrieval_timeout):
+            uq = await _run_blocking(
+                lambda: unified_query(query=req.question, top_k=req.top_k, product=req.product)
+            )
+    except TimeoutError as exc:
+        raise HTTPException(
+            status_code=504,
+            detail=f"Retrieval timed out after {retrieval_timeout:.0f}s",
+        ) from exc
+    if not uq.results and not uq.web_hits and not uq.mcp.hits:
+        raise HTTPException(
+            404,
+            detail=f"No KB content found for '{req.question}'. "
+                   "Ensure documents are ingested and topic is specific enough.",
+        )
+
+    feature = _infer_feature_area(req.question)
+    ctx = PromptContext(
+        topic=req.question,
+        test_id="QUERY",
+        feature_area=feature,
+        product=req.product,
+        context_chunks=uq.results,
+        token_budget=int(cfg.CONTEXT_TOKEN_BUDGET),
+        kg_context_block=uq.kg_context.text_block,
+        image_context_block=uq.rag.image_block,
+        web_context_block=uq.web_block,
+        mcp_context_block=uq.mcp.block,
+        skip_assemble_window=True,
+    )
+
+    system_prompt = build_system_prompt() + _QUERY_ADDENDUM
+    user_prompt = build_markdown_user_prompt(ctx)
+
+    generation_timeout = max(1.0, float(getattr(cfg, "QUERY_GENERATION_TIMEOUT_SECONDS", 90)))
+    try:
+        with anyio.fail_after(generation_timeout):
+            answer = await _run_blocking(
+                lambda: _call_gpt(system_prompt, user_prompt, max_tokens=4096, temperature=0.2)
+            )
+    except TimeoutError as exc:
+        raise HTTPException(
+            status_code=504,
+            detail=f"Generation timed out after {generation_timeout:.0f}s",
+        ) from exc
+    elapsed = round(time.time() - t0, 1)
+
+    source_lines = kb_trace_lines(uq.results)
+    for i, hit in enumerate(uq.web_hits, start=1):
+        backend = hit.metadata.get("web_source", hit.source_type) if getattr(hit, "metadata", None) else hit.source_type
+        source_lines.append(f"[WEB_REF {i}] source={backend} | title={hit.title} | url={hit.url}")
+    for i, hit in enumerate(uq.mcp.hits, start=1):
+        source_lines.append(f"[MCP_REF {i}] source={hit.source} | title={hit.title} | url={hit.url}")
+
+    return QueryResponse(
+        answer=answer,
+        kb_sources=source_lines,
+        kg_entities_used=uq.kg_context.node_count,
+        retrieval_chunks=len(uq.results),
+        web_hits=len(uq.web_hits),
+        mcp_hits=len(uq.mcp.hits),
+        sources_queried=uq.mcp.sources_queried,
+        tokens_used=uq.debug.total_tokens_used,
+        generation_time_sec=elapsed,
+    )
+
+
+def _effective_topic(topic: str, source_tc: Optional[str]) -> str:
+    t = (topic or "").strip()
+    if t:
+        return t
+    blob = (source_tc or "").strip()
+    if not blob:
+        return "Manual test case"
+    first = blob.split("\n", 1)[0].strip()
+    return (first[:120] if first else "Manual test case")
+
+
+@app.post("/generate", response_model=GenerateResponse, dependencies=[Depends(require_scope("write", "admin"))])
+async def generate_full_test(req: GenerateRequest):
+    """
+    Generate a complete test case (Markdown spec + Python pytest file).
+    Uses the same pipeline as the CLI: classifies input (synthesize vs transform vs expand),
+    then returns content as strings (artifacts are written to a temporary directory server-side).
+    """
+    effective_topic = _effective_topic(req.topic, req.source_tc)
+    mode = (req.generation_mode or cfg.DEFAULT_GENERATION_MODE or "pipeline").lower()
+
+    if mode == "agentic" and cfg.AGENTIC_ENABLED:
+        from knowledge_base.agents.graph import generate_agentic
+        result = generate_agentic(
+            effective_topic,
+            product=req.product,
+            top_k=req.top_k,
+            output_format=req.output_format,
+            test_id=req.test_id,
+        )
+        warnings = list(result.get("validation_warnings") or [])
+        confidence = result.get("confidence")
+        _apply_confidence_gate(confidence, warnings)
+        return GenerateResponse(
+            test_id=result.get("test_id") or req.test_id or "TC_AGENT",
+            topic=effective_topic,
+            feature_area=result.get("feature_area", "Unknown"),
+            markdown_content=result.get("markdown_output"),
+            python_content=result.get("python_output"),
+            kb_sources=result.get("sources_used") or [],
+            kb_chunk_count=len(result.get("rag_chunks") or []),
+            tokens_used=0,
+            generation_time_sec=0.0,
+            syntax_valid=not bool(result.get("validation_errors")),
+            warnings=warnings,
+            traceability_table="",
+            confidence=confidence,
+            precedence_conflicts=[],
+        )
+
+    try:
+        with tempfile.TemporaryDirectory() as td:
+            out = await _run_blocking(
+                lambda: generate_test_cases(
+                    topic=effective_topic,
+                    output_format=req.output_format,
+                    product=req.product,
+                    test_id=req.test_id or _next_test_id(),
+                    feature_area=req.feature_area,
+                    top_k=req.top_k,
+                    output_dir=Path(td),
+                    debug_retrieval=False,
+                    source_tc=req.source_tc,
+                    detail_level=req.detail_level,
+                )
+            )
+            response = _build_generate_response(out, effective_topic)
+    except ValueError as e:
+        raise HTTPException(404, detail=str(e))
+
+    return response
+
+
+@app.post("/convert", response_model=GenerateResponse, dependencies=[Depends(require_scope("write", "admin"))])
+async def convert_manual_test_case(req: ConvertRequest):
+    """
+    Convert pasted manual TC (gold or partial) to Markdown + pytest with fidelity constraints.
+    `source_tc` is required; retrieval is light (supplementary) for transform, full for expand.
+    """
+    if not req.source_tc.strip():
+        raise HTTPException(400, detail="source_tc cannot be empty")
+
+    effective_topic = _effective_topic(req.topic, req.source_tc)
+
+    try:
+        with tempfile.TemporaryDirectory() as td:
+            out = await _run_blocking(
+                lambda: generate_test_cases(
+                    topic=effective_topic,
+                    output_format=req.output_format,
+                    product=req.product,
+                    test_id=req.test_id or _next_test_id(),
+                    feature_area=req.feature_area,
+                    top_k=req.top_k,
+                    output_dir=Path(td),
+                    debug_retrieval=False,
+                    source_tc=req.source_tc,
+                    detail_level=req.detail_level,
+                )
+            )
+            response = _build_generate_response(out, effective_topic)
+    except ValueError as e:
+        raise HTTPException(404, detail=str(e))
+
+    return response
+
+
+@app.post("/feedback", response_model=FeedbackResponse, dependencies=[Depends(require_scope("admin"))])
+async def submit_feedback(req: FeedbackRequest):
+    """Capture user feedback for later curation (Phase 1 feedback loop)."""
+    try:
+        feedback_id = capture_feedback(
+            query=req.query,
+            generated_output=req.generated_output,
+            feedback_type=req.feedback_type,
+            feedback_data=req.feedback_data,
+            generation_metadata=req.generation_metadata,
+            user_id=req.user_id,
+            session_id=req.session_id,
+            source_context=req.source_context,
+        )
+    except ValueError as e:
+        raise HTTPException(400, detail=str(e))
+    except Exception as e:
+        logger.exception("Failed to capture feedback")
+        raise HTTPException(500, detail=f"Failed to store feedback: {e}")
+
+    return FeedbackResponse(feedback_id=feedback_id)
+
+
+@app.post("/generate/v2", response_model=AgenticGenerateResponse, dependencies=[Depends(require_scope("write", "admin"))])
+async def generate_agentic(req: AgenticGenerateRequest):
+    """Agentic generation using LangGraph multi-agent pipeline (Phase 5)."""
+    if not cfg.AGENTIC_ENABLED:
+        raise HTTPException(503, detail="Agentic pipeline disabled (AGENTIC_ENABLED=false)")
+
+    from knowledge_base.agents.graph import generate_agentic
+
+    try:
+        result = generate_agentic(
+            req.query,
+            product=req.product,
+            top_k=req.top_k,
+            output_format=req.output_format,
+            test_id=req.test_id,
+        )
+    except Exception as e:
+        logger.exception("Agentic generation failed")
+        raise HTTPException(500, detail=str(e))
+
+    warnings: List[str] = list(result.get("validation_warnings") or [])
+    confidence = result.get("confidence")
+    _apply_confidence_gate(confidence, warnings)
+
+    return AgenticGenerateResponse(
+        test_id=result.get("test_id") or req.test_id or "TC_AGENT",
+        query=req.query,
+        feature_area=result.get("feature_area", "Unknown"),
+        markdown_content=result.get("markdown_output"),
+        python_content=result.get("python_output"),
+        confidence=confidence,
+        sources_used=result.get("sources_used") or [],
+        agent_trace=result.get("agent_trace") or [],
+        validation_errors=result.get("validation_errors") or [],
+        validation_warnings=result.get("validation_warnings") or [],
+        warnings=warnings,
+    )
+
+
+@app.post("/rca", dependencies=[Depends(require_scope("admin"))])
+async def run_rca(req: RCARequest):
+    """Root cause analysis for test failures (Phase 7)."""
+    from knowledge_base.agents.rca_agent import analyze_failure
+    return analyze_failure(req.test_id, req.failure_log)
+
+
+@app.post("/heal", dependencies=[Depends(require_scope("admin"))])
+async def heal_test(req: HealRequest):
+    """Propose script fix for flaky test (Phase 7)."""
+    from knowledge_base.agents.healing_agent import propose_fix
+    return propose_fix(req.test_id, req.flaky_history)
+
+
+@app.post("/impact-analysis", dependencies=[Depends(require_scope("admin"))])
+async def analyze_impact(req: ImpactAnalysisRequest):
+    """Regression impact analysis from changed files (Phase 7)."""
+    from knowledge_base.agents.regression_agent import impact_analysis
+    return impact_analysis(req.changed_files)
+
+
+@app.get("/feedback/report", dependencies=[Depends(require_scope("admin"))])
+async def feedback_report(days: int = 7):
+    """Weekly feedback analytics report (Phase 2)."""
+    from knowledge_base.feedback.analytics import generate_weekly_report
+    return generate_weekly_report(days=days)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+_QUERY_ADDENDUM = """
+
+ADDITIONAL INSTRUCTION FOR QUERY MODE
+======================================
+The user is asking a question (not necessarily requesting a full JIRA test case).
+Respond with the most detailed and accurate answer the KB context supports:
+- If they ask for test steps, give FULL executable steps (navigation paths, exact CLI, expected results).
+- If they ask about a feature, explain it with exact registry keys and settings from context.
+- If they ask how to configure something, provide the exact TC Setup path and values.
+- Always cite which SOURCE/KB_REF the information comes from.
+- Never invent steps, paths, or URLs not present in the context.
+- If the KB does not contain enough info, say so explicitly — do not guess.
+"""
+
+
+def _read_output_files(out) -> Tuple[Optional[str], Optional[str]]:
+    md_content: Optional[str] = None
+    py_content: Optional[str] = None
+    if out.markdown_path and out.markdown_path.exists():
+        md_content = out.markdown_path.read_text(encoding="utf-8")
+    if out.python_path and out.python_path.exists():
+        py_content = out.python_path.read_text(encoding="utf-8")
+    return md_content, py_content
+
+
+def _apply_confidence_gate(confidence: Optional[dict], warnings: List[str]) -> None:
+    """Reject or warn based on publish confidence score (Phase 1)."""
+    if not confidence:
+        return
+
+    publish_score = float(confidence.get("publish", 0.0))
+    route = confidence.get("route")
+
+    if route == "reject" or publish_score < cfg.CONFIDENCE_REJECT_THRESHOLD:
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "message": "Generation confidence too low to publish output.",
+                "publish_score": publish_score,
+                "threshold": cfg.CONFIDENCE_REJECT_THRESHOLD,
+                "confidence": confidence,
+                "recommendation": confidence.get("publish_recommendation", ""),
+            },
+        )
+
+    if route == "human_review" or publish_score < cfg.CONFIDENCE_WARN_THRESHOLD:
+        warnings.append(
+            f"⚠️ LOW CONFIDENCE: publish score {publish_score:.2f} — human review recommended."
+        )
+
+
+def _build_generate_response(out, effective_topic: str) -> GenerateResponse:
+    md_content, py_content = _read_output_files(out)
+    warnings = list(out.warnings)
+    _apply_confidence_gate(out.confidence, warnings)
+
+    if out.precedence_conflicts:
+        warnings.append(
+            f"⚠️ SOURCE CONFLICTS: {len(out.precedence_conflicts)} precedence conflict(s) detected — reviewer should verify."
+        )
+
+    return GenerateResponse(
+        test_id=out.test_id,
+        topic=effective_topic,
+        feature_area=out.feature_area,
+        markdown_content=md_content,
+        python_content=py_content,
+        kb_sources=out.kb_sources,
+        kb_chunk_count=out.kb_chunk_count,
+        tokens_used=out.tokens_used,
+        generation_time_sec=out.generation_time_sec,
+        syntax_valid=out.syntax_valid,
+        warnings=warnings,
+        traceability_table=out.traceability_table or "",
+        confidence=out.confidence,
+        precedence_conflicts=out.precedence_conflicts,
+    )
+
+
+def _next_test_id() -> str:
+    """Generate next TC id from the database (not file-system based)."""
+    try:
+        with get_conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute("""
+                    SELECT metadata->>'test_id' FROM kb_documents
+                    WHERE metadata->>'test_id' IS NOT NULL
+                    ORDER BY ingested_at DESC LIMIT 1
+                """)
+                row = cur.fetchone()
+    except Exception:
+        row = None
+    import re
+    suffix = uuid4().hex[:4].upper()
+    if row and row[0]:
+        m = re.search(r"\d+", row[0])
+        if m:
+            return f"TC{int(m.group()) + 1:03d}_{suffix}"
+    return f"TC{int(time.time() * 1000) % 1000000:06d}_{suffix}"
+
+
+def _component_health(component: str) -> Optional[dict]:
+    try:
+        if component == "neo4j":
+            from knowledge_base.graph_db.neo4j_client import get_neo4j_client
+            return get_neo4j_client().health_check()
+        if component == "cognee":
+            from knowledge_base.memory.cognee_client import get_cognee_client
+            return get_cognee_client().health_check()
+        if component == "graphiti":
+            from knowledge_base.graph_db.graphiti_client import get_graphiti_client
+            return get_graphiti_client().health_check()
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+    return None
+
+
+def _current_phase() -> str:
+    if cfg.AGENTIC_ENABLED:
+        return "phase5+"
+    if cfg.GRAPHITI_ENABLED:
+        return "phase6"
+    if cfg.COGNEE_ENABLED:
+        return "phase4"
+    if cfg.KG_SHADOW_MODE or cfg.KG_BACKEND == "neo4j":
+        return "phase3"
+    return "phase1"