Update src/api/admin.py

src/api/admin.py

@@ -359,6 +359,33 @@ tr:last-child td{{border-bottom:none}}
   <div id="recentTable" style="overflow-x:auto"><div style="color:#6b7280;font-size:.84rem">Loading…</div></div>
 </div>
 
+<div class="card">
+  <h2>📊 Reports</h2>
+  <div style="display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin-bottom:10px">
+    <label style="font-size:.82rem">Period:</label>
+    <select id="repPeriod" style="padding:5px 8px;border:1px solid #d1d5db;border-radius:6px">
+      <option value="7">Last 7 days</option>
+      <option value="30" selected>Last 30 days</option>
+      <option value="90">Last 90 days</option>
+      <option value="0">All time</option>
+    </select>
+    <label style="font-size:.82rem;margin-left:8px">Report:</label>
+    <select id="repKind" style="padding:5px 8px;border:1px solid #d1d5db;border-radius:6px">
+      <option value="overview">1. Usage overview</option>
+      <option value="topics">2. What people ask about</option>
+      <option value="when">3. When people use it</option>
+      <option value="speed">4. How fast it answers</option>
+      <option value="gaps">5. Questions we could not answer well</option>
+      <option value="health">6. Service health</option>
+      <option value="all">Everything (printable summary)</option>
+    </select>
+    <button class="btn" id="repRun" style="padding:6px 12px">Show report</button>
+    <button class="btn" id="repPrint" style="padding:6px 12px">Print / PDF</button>
+    <button class="btn" id="repCsv" style="padding:6px 12px">Download CSV</button>
+  </div>
+  <div id="reportOut"><div style="color:#6b7280;font-size:.84rem">Choose a report and click "Show report".</div></div>
+</div>
+
 <div class="card">
   <h2>🔌 System Status</h2>
   <div id="sysStatus"><div style="color:#6b7280;font-size:.84rem">Loading…</div></div>
@@ -446,6 +473,262 @@ async function loadRecentQueries(){{
   }}
 }}
 
+// ── Plain-language reporting ────────────────────────────────────────────────
+// Internal routing codes are meaningless to a reader, so every code is mapped
+// to a phrase a librarian or director would recognise. Unknown codes degrade to
+// a title-cased version of the code rather than disappearing.
+const INTENT_LABELS = {{
+  'library_info:rag_hybrid_search':'Library information (from our guides)',
+  'library_info:libcal_live_hours':'Opening hours',
+  'library_info:hours_hardcoded':'Opening hours',
+  'library_info:libcal_live_events':'Library events & workshops',
+  'library_info:fulltext_chain':'How to get the full text of an article',
+  'library_info:database_recommendation':'Which database should I use',
+  'library_info:staff_name_match':'Contacting a named staff member',
+  'library_info:staff_role_match':'Who to contact for help',
+  'library_info:theses_guide':'Finding theses & dissertations',
+  'library_info:campus_hardcoded':'Campus & location',
+  'library_info':'General library information',
+  'search_academic:primo_inline':'Finding articles & books',
+  'search_academic:primo_browser_link':'Finding articles & books (opened in catalogue)',
+  'search_academic:research_snapshot':'Research starting points',
+  'search_academic:follow_up_resolution, both_resources':'Refining an earlier search',
+  'search_academic':'Finding articles & books',
+  'search_medical:primo_inline':'Medical & health literature',
+  'search_medical:primo_browser_link':'Medical & health literature (opened in catalogue)',
+  'search_medical':'Medical & health literature',
+  'general:web_search':'General questions (answered from the web)',
+  'general_recent:web_search':'Current events & news',
+  'general_topic':'General topic questions','general_recent':'Current events & news',
+  'general':'General questions',
+  'social_greeting:libbee_casual':'Greetings & small talk',
+  'social_greeting:':'Greetings & small talk','social_greeting':'Greetings & small talk',
+  'sensitive_blocked:sensitive_intent_guard':'Sensitive topics (safely redirected)',
+  'blocked:injection_guard':'Blocked misuse attempts',
+  'not_in_kb':'No information available in our guides',
+  'unknown':'Could not be categorised','error':'Errors',
+  'faq':'Frequently asked questions (older system)',
+  'rag':'Library information (older system)',
+  'search':'Catalogue search (older system)',
+  'database':'Database recommendation (older system)',
+  'agent':'Assistant reply (older system)',
+  'clarify':'Clarifying question (older system)',
+  'search_recovery':'Search retry (older system)',
+  'llm_general':'General questions (older system)',
+  'llm_general_confirmed':'General questions (older system)',
+  'llm_library':'Library questions (older system)'
+}};
+const MODEL_LABELS={{gpt:'ChatGPT (GPT-4o-mini)',claude:'Claude','n/a':'Not applicable'}};
+const WEEKDAYS=['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday'];
+
+function labelFor(code){{
+  if(INTENT_LABELS[code]) return INTENT_LABELS[code];
+  const base=String(code||'').split(':')[0];
+  if(INTENT_LABELS[base]) return INTENT_LABELS[base];
+  return base?base.replace(/_/g,' ').replace(/\\b\\w/g,c=>c.toUpperCase()):'Other';
+}}
+function speedBand(sec){{
+  if(!sec||sec<0.5) return 'Instant';
+  if(sec<3) return 'Fast';
+  if(sec<8) return 'Moderate';
+  return 'Slower (searches external databases)';
+}}
+function fmtDate(s){{ return (s||'').substring(0,10) || '—'; }}
+function pct(n,total){{ return total?Math.round(n*1000/total)/10:0; }}
+function bar(p){{
+  return '<div style="background:#e5e7eb;border-radius:4px;height:8px;width:110px;display:inline-block;vertical-align:middle">'
+       +'<div style="background:#003366;height:8px;border-radius:4px;width:'+Math.max(2,Math.round(p))+'%"></div></div>';
+}}
+
+let REPORT_DATA=null;
+
+async function fetchReport(){{
+  const days=document.getElementById('repPeriod').value;
+  const res=await cfFetch('/analytics/report?days='+days);
+  REPORT_DATA=res.data;
+  return REPORT_DATA;
+}}
+
+function reportOverview(d){{
+  const t=d.totals||{{}};
+  const prev=t.previous_period_queries||0;
+  const change=prev?Math.round(((t.queries-prev)/prev)*100):null;
+  const perDay=t.active_days?Math.round(t.queries/t.active_days*10)/10:0;
+  const trend=change===null?'<em>no comparable earlier period</em>'
+    :(change>=0?'<span style="color:#047857">up '+change+'%</span>':'<span style="color:#b45309">down '+Math.abs(change)+'%</span>')
+     +' compared with the previous period';
+  return `<h3 style="margin:6px 0">1. Usage overview</h3>
+  <p style="font-size:.9rem;line-height:1.7">
+    LibBee answered <strong>${{t.queries||0}} questions</strong> during this period,
+    across <strong>${{t.active_days||0}} days</strong> when it was used
+    (about <strong>${{perDay}} questions per day</strong> on those days). Usage was ${{trend}}.<br>
+    First question in this period: <strong>${{fmtDate(t.first_query)}}</strong> ·
+    most recent: <strong>${{fmtDate(t.last_query)}}</strong>.
+    ${{t.busiest_day?'Busiest single day: <strong>'+t.busiest_day.day+'</strong> with '+t.busiest_day.count+' questions.':''}}<br>
+    Of these, <strong>${{t.unanswered||0}}</strong> could not be answered from the library guides
+    (${{pct(t.unanswered||0,t.queries||1)}}% — see report 5), and
+    <strong>${{t.blocked||0}}</strong> were misuse attempts the assistant safely refused.
+  </p>`;
+}}
+
+function reportTopics(d){{
+  const total=(d.totals||{{}}).queries||0;
+  const grouped={{}};
+  (d.by_intent||[]).forEach(r=>{{
+    const l=labelFor(r.k);
+    if(!grouped[l]) grouped[l]={{c:0,t:0,n:0}};
+    grouped[l].c+=r.c;
+    if(r.avg_time){{ grouped[l].t+=r.avg_time*r.c; grouped[l].n+=r.c; }}
+  }});
+  const rows=Object.entries(grouped).sort((a,b)=>b[1].c-a[1].c).map(([l,v])=>{{
+    const p=pct(v.c,total); const avg=v.n?v.t/v.n:0;
+    return `<tr><td>${{l}}</td><td style="white-space:nowrap">${{v.c}}</td>
+      <td style="white-space:nowrap">${{bar(p)}} ${{p}}%</td>
+      <td>${{speedBand(avg)}}</td></tr>`;
+  }}).join('');
+  return `<h3 style="margin:6px 0">2. What people ask about</h3>
+  <p style="font-size:.86rem;color:#4b5563">Every question is sorted into a category automatically. This is what people came for.</p>
+  <div style="overflow-x:auto"><table><thead><tr><th>Type of question</th><th>Questions</th><th>Share</th><th>Typical speed</th></tr></thead><tbody>${{rows||'<tr><td colspan="4">No data.</td></tr>'}}</tbody></table></div>`;
+}}
+
+function reportWhen(d){{
+  const hours=d.hourly||[]; const maxH=Math.max(1,...hours.map(h=>h.c));
+  const hourRows=hours.map(h=>{{
+    const hr=parseInt(h.h,10);
+    const uae=(hr+4)%24;
+    const ampm=(uae%12===0?12:uae%12)+(uae<12?' AM':' PM');
+    return `<tr><td style="white-space:nowrap">${{ampm}}</td><td>${{bar(h.c/maxH*100)}} ${{h.c}}</td></tr>`;
+  }}).join('');
+  const wd=d.weekday||[]; const maxW=Math.max(1,...wd.map(w=>w.c));
+  const busiestW=wd.slice().sort((a,b)=>b.c-a.c)[0];
+  const wdRows=wd.map(w=>`<tr><td>${{WEEKDAYS[parseInt(w.d,10)]||w.d}}</td><td>${{bar(w.c/maxW*100)}} ${{w.c}}</td></tr>`).join('');
+  return `<h3 style="margin:6px 0">3. When people use it</h3>
+  <p style="font-size:.86rem;color:#4b5563">Times shown in UAE local time. Useful for deciding when human help should be available.
+  ${{busiestW?'Busiest day of the week: <strong>'+(WEEKDAYS[parseInt(busiestW.d,10)]||'')+'</strong>.':''}}</p>
+  <div style="display:flex;gap:24px;flex-wrap:wrap">
+    <div><h4 style="font-size:.85rem;margin:4px 0">By hour of day</h4><table><tbody>${{hourRows||'<tr><td>No data.</td></tr>'}}</tbody></table></div>
+    <div><h4 style="font-size:.85rem;margin:4px 0">By day of week</h4><table><tbody>${{wdRows||'<tr><td>No data.</td></tr>'}}</tbody></table></div>
+  </div>`;
+}}
+
+function reportSpeed(d){{
+  const t=d.totals||{{}};
+  const bands={{}};
+  (d.by_intent||[]).forEach(r=>{{
+    if(!r.avg_time) return;
+    const b=speedBand(r.avg_time);
+    bands[b]=(bands[b]||0)+r.c;
+  }});
+  const totalTimed=Object.values(bands).reduce((a,b)=>a+b,0);
+  const rows=Object.entries(bands).sort((a,b)=>b[1]-a[1]).map(([b,c])=>
+    `<tr><td>${{b}}</td><td>${{c}}</td><td>${{bar(pct(c,totalTimed))}} ${{pct(c,totalTimed)}}%</td></tr>`).join('');
+  const slowest=(d.by_intent||[]).filter(r=>r.avg_time).sort((a,b)=>b.avg_time-a.avg_time).slice(0,5)
+    .map(r=>`<tr><td>${{labelFor(r.k)}}</td><td>${{r.avg_time.toFixed(1)}} seconds</td></tr>`).join('');
+  return `<h3 style="margin:6px 0">4. How fast it answers</h3>
+  <p style="font-size:.9rem;line-height:1.7">Average answer time across all questions:
+    <strong>${{(t.avg_response_time||0).toFixed(1)}} seconds</strong>.
+    Questions answered from our own guides are near-instant; questions that search
+    outside databases take longer because they wait for those services.</p>
+  <div style="display:flex;gap:24px;flex-wrap:wrap">
+   <div><h4 style="font-size:.85rem;margin:4px 0">Answer speed</h4>
+    <table><thead><tr><th>Speed</th><th>Questions</th><th>Share</th></tr></thead><tbody>${{rows||'<tr><td colspan="3">No timing data.</td></tr>'}}</tbody></table></div>
+   <div><h4 style="font-size:.85rem;margin:4px 0">Slowest categories</h4>
+    <table><thead><tr><th>Type of question</th><th>Average</th></tr></thead><tbody>${{slowest||'<tr><td colspan="2">No data.</td></tr>'}}</tbody></table></div>
+  </div>`;
+}}
+
+function reportGaps(d){{
+  const t=d.totals||{{}};
+  const reps=d.daily_reports||[];
+  const clusters=[]; const lows=[];
+  reps.forEach(r=>{{
+    (r.kb_gap_clusters||[]).forEach(c=>clusters.push({{...c,date:r.report_date}}));
+    (r.low_relevance_samples||[]).forEach(x=>lows.push({{...x,date:r.report_date}}));
+  }});
+  const cRows=clusters.sort((a,b)=>(b.count||0)-(a.count||0)).slice(0,15).map(c=>
+    `<tr><td>${{c.label||'(unlabelled)'}}</td><td>${{c.count||0}}</td>
+     <td style="color:#6b7280;font-size:.78rem">${{(c.sample_questions||[]).slice(0,2).join(' | ')}}</td></tr>`).join('');
+  const lRows=lows.slice(0,15).map(x=>
+    `<tr><td>${{(x.question||'').substring(0,90)}}</td><td>${{x.score}}</td>
+     <td style="color:#6b7280;font-size:.78rem">${{x.reason||''}}</td></tr>`).join('');
+  return `<h3 style="margin:6px 0">5. Questions we could not answer well</h3>
+  <p style="font-size:.9rem;line-height:1.7">
+    <strong>${{t.unanswered||0}}</strong> questions in this period had no matching information in the
+    library guides. Each theme below is a suggestion for content worth adding.
+    ${{reps.length?'':'<em>The nightly review has not produced results yet; themes appear once it has run.</em>'}}</p>
+  <h4 style="font-size:.85rem;margin:8px 0 4px">Themes with missing information</h4>
+  <div style="overflow-x:auto"><table><thead><tr><th>Theme</th><th>Times asked</th><th>Examples</th></tr></thead><tbody>${{cRows||'<tr><td colspan="3">Nothing flagged.</td></tr>'}}</tbody></table></div>
+  <h4 style="font-size:.85rem;margin:12px 0 4px">Answers judged weak on review</h4>
+  <div style="overflow-x:auto"><table><thead><tr><th>Question</th><th>Score (0–1)</th><th>Reason</th></tr></thead><tbody>${{lRows||'<tr><td colspan="3">Nothing flagged.</td></tr>'}}</tbody></table></div>`;
+}}
+
+function reportHealth(d){{
+  const runs=d.canary||[];
+  const ok=runs.filter(r=>r.ok).length;
+  const rows=runs.map(r=>`<tr><td style="white-space:nowrap">${{(r.run_at||'').substring(0,16)}}</td>
+    <td>${{r.ok?'<span style="color:#047857;font-weight:700">Working</span>':'<span style="color:#dc2626;font-weight:700">Failed</span>'}}</td>
+    <td style="max-width:260px">${{(r.question||'').substring(0,80)}}</td>
+    <td>${{r.latency_ms!=null?(r.latency_ms/1000).toFixed(1)+'s':''}}</td></tr>`).join('');
+  return `<h3 style="margin:6px 0">6. Service health</h3>
+  <p style="font-size:.9rem;line-height:1.7">Each night the system asks itself a real question and checks it gets a
+    sensible answer. These checks are not counted in the usage figures above.<br>
+    <strong>${{ok}} of the last ${{runs.length||0}} daily checks passed.</strong></p>
+  <div style="overflow-x:auto"><table><thead><tr><th>Check</th><th>Result</th><th>Question asked</th><th>Time taken</th></tr></thead><tbody>${{rows||'<tr><td colspan="4">No checks recorded yet.</td></tr>'}}</tbody></table></div>`;
+}}
+
+const REPORTS={{overview:reportOverview,topics:reportTopics,when:reportWhen,
+                speed:reportSpeed,gaps:reportGaps,health:reportHealth}};
+
+async function runReport(){{
+  const out=document.getElementById('reportOut');
+  out.innerHTML='<div style="color:#6b7280;font-size:.84rem">Preparing report…</div>';
+  try{{
+    const d=await fetchReport();
+    const kind=document.getElementById('repKind').value;
+    const periodTxt=document.getElementById('repPeriod').selectedOptions[0].text;
+    let body;
+    if(kind==='all') body=Object.values(REPORTS).map(f=>f(d)).join('<hr style="margin:16px 0;border:none;border-top:1px solid #e5e7eb">');
+    else body=REPORTS[kind](d);
+    out.innerHTML='<div id="reportBody"><div style="font-size:.78rem;color:#6b7280;margin-bottom:8px">'
+      +'KU Library — LibBee report · '+periodTxt+' · generated '+new Date().toLocaleString()+'</div>'+body+'</div>';
+  }}catch(e){{
+    out.innerHTML='<span style="color:#dc2626">Could not load report: '+e.message+'</span>';
+  }}
+}}
+
+function printReport(){{
+  const el=document.getElementById('reportBody');
+  if(!el){{ alert('Show a report first.'); return; }}
+  const w=window.open('','_blank');
+  w.document.write('<html><head><title>LibBee report</title><style>'
+    +'body{{font-family:Segoe UI,system-ui,sans-serif;padding:24px;color:#111}}'
+    +'table{{border-collapse:collapse;width:100%;margin:8px 0}}'
+    +'th,td{{border:1px solid #ddd;padding:6px 8px;text-align:left;font-size:.85rem}}'
+    +'th{{background:#f3f4f6}}h3{{color:#003366}}</style></head><body>'
+    +el.innerHTML+'</body></html>');
+  w.document.close(); w.focus(); w.print();
+}}
+
+function downloadCsv(){{
+  if(!REPORT_DATA){{ alert('Show a report first.'); return; }}
+  const rows=[['Type of question','Questions','Share %','Average seconds']];
+  const total=(REPORT_DATA.totals||{{}}).queries||0;
+  const grouped={{}};
+  (REPORT_DATA.by_intent||[]).forEach(r=>{{
+    const l=labelFor(r.k);
+    if(!grouped[l]) grouped[l]={{c:0,t:0,n:0}};
+    grouped[l].c+=r.c;
+    if(r.avg_time){{ grouped[l].t+=r.avg_time*r.c; grouped[l].n+=r.c; }}
+  }});
+  Object.entries(grouped).sort((a,b)=>b[1].c-a[1].c).forEach(([l,v])=>
+    rows.push([l,v.c,pct(v.c,total),v.n?(v.t/v.n).toFixed(2):'']));
+  const csv=rows.map(r=>r.map(x=>'"'+String(x).replace(/"/g,'""')+'"').join(',')).join('\\n');
+  const a=document.createElement('a');
+  a.href=URL.createObjectURL(new Blob([csv],{{type:'text/csv'}}));
+  a.download='libbee-report-'+new Date().toISOString().substring(0,10)+'.csv';
+  a.click();
+}}
+
 async function loadMetrics(){{
   try{{
     const r=await fetch('/admin/metrics');
@@ -516,6 +799,10 @@ async function loadStatus(){{
 loadStats();
 loadCFAnalytics();
 loadRecentQueries();
+document.getElementById('repRun').onclick=runReport;
+document.getElementById('repPrint').onclick=printReport;
+document.getElementById('repCsv').onclick=downloadCsv;
+runReport();
 loadMetrics();
 loadRAGInfo();
 loadStatus();
@@ -888,16 +1175,16 @@ async def admin_log_status(request: Request):
     if not data["recent_attempts"]:
         data["hint"] = ("No write attempts recorded since the last restart. "
                         "Send a query through LibBee, then reload this page.")
-    return data
-
-@router.get("/canary-status")
-async def admin_canary_status(request: Request):
-    """Last 14 daily canary runs (the Worker's scheduled health probe).
-
-    Each run is one real question through the full pipeline, chosen from a
-    fixed 14-question pool rotating by day-of-year. Canary traffic is excluded
-    from analytics, so these runs never appear in the D1 usage data.
-    """
-    _require_session(request)
-    return await _worker_get("/canary/status")
-
+    return data
+
+@router.get("/canary-status")
+async def admin_canary_status(request: Request):
+    """Last 14 daily canary runs (the Worker's scheduled health probe).
+
+    Each run is one real question through the full pipeline, chosen from a
+    fixed 14-question pool rotating by day-of-year. Canary traffic is excluded
+    from analytics, so these runs never appear in the D1 usage data.
+    """
+    _require_session(request)
+    return await _worker_get("/canary/status")
+