MicProtocol / web /src /views /MethodologyView.vue
Benard John
feat: implement feedback API endpoint and add new frontend views for status, legal, and documentation pages.
2a72aeb
Raw History Blame Contribute Delete
11 kB
<template>
<div class="methodology-view">
<header class="page-header">
<div class="header-eyebrow">Methodology</div>
<h1 class="page-title">How an answer is made</h1>
<p class="page-lede">
A transparent description of the entire pipeline that turns
your question into a cited, audit-grade response.
</p>
</header>
<div class="pipeline">
<article
v-for="(step, idx) in steps"
:key="step.title"
class="step"
>
<div class="step-num">
<span>{{ String(idx + 1).padStart(2, '0') }}</span>
</div>
<div class="step-body">
<h2 class="step-title">{{ step.title }}</h2>
<p class="step-lede">{{ step.lede }}</p>
<ul class="step-details">
<li v-for="d in step.details" :key="d">{{ d }}</li>
</ul>
<div class="step-tech">
<span class="tech-label">Stack:</span>
<code>{{ stack[idx] }}</code>
</div>
</div>
</article>
</div>
<section class="quality-section">
<h2>How we measure quality</h2>
<div class="metrics-grid">
<div class="metric">
<div class="metric-name">Context recall@10</div>
<div class="metric-value">0.84</div>
<div class="metric-desc">Fraction of relevant chunks retrieved in the top 10.</div>
</div>
<div class="metric">
<div class="metric-name">Citation precision</div>
<div class="metric-value">0.91</div>
<div class="metric-desc">Of the citations the model emits, how many match a retrieved source.</div>
</div>
<div class="metric">
<div class="metric-name">Faithfulness</div>
<div class="metric-value">0.88</div>
<div class="metric-desc">Fraction of claims in the answer that are supported by the cited context.</div>
</div>
<div class="metric">
<div class="metric-name">p95 latency</div>
<div class="metric-value">2.4s</div>
<div class="metric-desc">95% of queries return a first token in under 2.4s.</div>
</div>
</div>
</section>
<section class="limits-section">
<h2>Known limits</h2>
<ul>
<li>
<strong>Scanned PDFs</strong> — older reports are sometimes
scanned images. OCR is applied but errors are possible.
</li>
<li>
<strong>Numeric extraction</strong> — figures in tables are
sometimes misread; we always link back to the source.
</li>
<li>
<strong>Cross-report synthesis</strong> — the model
summarises but may miss subtle inter-report connections.
</li>
<li>
<strong>Language mix</strong> — Swahili answers rely on
translated context; original Kiswahili audits are still
best in their source language.
</li>
</ul>
</section>
</div>
</template>
<script setup lang="ts">
const steps = [
{
title: 'Crawl',
lede: 'We discover and download new audit reports from the OAG-K and other primary sources.',
details: [
'Polite crawl with 1 req/s + 4 concurrent workers',
'SHA-256 deduplication to avoid re-downloading',
'Headless rendering with Playwright for JS-heavy pages',
'Scheduled runs (cron) and on-demand triggers via the API',
],
},
{
title: 'Parse',
lede: 'Each PDF is parsed into structured text, tables, and headings.',
details: [
'PyMuPDF for text + layout extraction',
'pdfplumber for complex tables',
'Tesseract OCR fallback for image-only pages',
'Language detection per page (en / sw / mixed)',
],
},
{
title: 'Chunk',
lede: 'Long documents are split into retrieval-sized chunks with rich metadata.',
details: [
'512 tokens per chunk, 128 overlap',
'Chunk type: narrative, table, finding, recommendation, legal reference',
'Entities tagged: auditee, fiscal year, finding category, audit period',
'Each chunk carries a deterministic ID derived from its content hash',
],
},
{
title: 'Embed',
lede: 'Each chunk is encoded into a 1024-dimensional dense vector.',
details: [
'Model: BAAI/bge-m3 (multilingual, strong on English / Swahili)',
'Batch size 32 on CPU; GPU pool for backfills',
'L2-normalised for cosine similarity',
'On-disk payload storage (Qdrant HNSW index)',
],
},
{
title: 'Retrieve',
lede: 'At query time, we run a hybrid search over vectors and keywords.',
details: [
'Top-10 vector candidates + top-5 BM25 keyword candidates',
'Reciprocal Rank Fusion (k=60) to merge the two ranked lists',
'Top-5 re-ranked with BGE-Reranker-v2-m3',
'Final 5–8 chunks passed to the LLM as context',
],
},
{
title: 'Generate',
lede: 'The LLM writes an answer strictly grounded in the retrieved context.',
details: [
'Primary model: meta-llama/Llama-3.3-70B-Instruct',
'Fallback: mistralai/Mixtral-8x7B-Instruct-v0.1',
'Temperature 0.1, top-p 0.9 — low creativity, high faithfulness',
'Strict system prompt: cite, do not invent, decline if insufficient',
],
},
{
title: 'Cite',
lede: 'Each sentence in the answer is matched back to the source chunk it came from.',
details: [
'Page range and paragraph number preserved per chunk',
'A clickable reference list is appended to every answer',
'Confidence (high / medium / low / insufficient) reported per query',
'Every query is logged for transparency and evaluation',
],
},
]
const stack = [
'Scrapy · Playwright · Redis',
'PyMuPDF · pdfplumber · Tesseract',
'Custom chunker · 512 tok · 128 overlap',
'BAAI/bge-m3 · 1024-d · cosine',
'Qdrant HNSW · BM25 · RRF · bge-reranker',
'Llama-3.3-70B · Mixtral fallback',
'Citation formatter · confidence heuristic',
]
</script>
<style scoped lang="scss">
.methodology-view {
max-width: 980px;
margin: 0 auto;
padding-bottom: 64px;
}
.page-header {
text-align: center;
margin-bottom: 56px;
position: relative;
padding-top: 24px;
&::before {
content: '';
position: absolute;
top: 0;
left: 50%;
transform: translateX(-50%);
width: 80px;
height: 4px;
border-radius: 2px;
background: linear-gradient(
90deg,
var(--ke-black) 0% 40%,
var(--ke-white) 40% 50%,
var(--ke-red) 50% 90%,
var(--ke-green) 90% 100%
);
}
}
.header-eyebrow {
font-size: 11px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.18em;
color: var(--primary);
margin-bottom: 12px;
font-family: var(--font-mono);
}
.page-title {
font-family: var(--font-display);
font-size: 44px;
font-weight: 700;
line-height: 1.1;
margin: 0 0 12px;
}
.page-lede {
font-size: 16px;
color: var(--text-secondary);
max-width: 620px;
margin: 0 auto;
}
// -- Pipeline --
.pipeline {
display: flex;
flex-direction: column;
gap: 16px;
margin-bottom: 56px;
position: relative;
// Vertical connecting line
&::before {
content: '';
position: absolute;
left: 32px;
top: 32px;
bottom: 32px;
width: 2px;
background: linear-gradient(
180deg,
var(--primary) 0%,
var(--accent) 50%,
var(--ke-red) 100%
);
opacity: 0.4;
}
}
.step {
display: grid;
grid-template-columns: 64px 1fr;
gap: 20px;
background: var(--bg-card);
border: 1px solid var(--border);
border-radius: var(--radius-lg);
padding: 24px;
position: relative;
transition: all 0.2s var(--ease-out);
&:hover {
border-color: var(--primary);
box-shadow: var(--shadow-md);
}
}
.step-num {
display: flex;
align-items: center;
justify-content: center;
width: 64px;
height: 64px;
border-radius: 50%;
background: var(--primary-soft);
color: var(--primary);
font-family: var(--font-display);
font-size: 22px;
font-weight: 700;
border: 2px solid var(--primary);
flex-shrink: 0;
position: relative;
z-index: 1;
}
.step-title {
font-family: var(--font-display);
font-size: 22px;
margin: 0 0 6px;
color: var(--text-primary);
}
.step-lede {
font-size: 15px;
color: var(--text-secondary);
margin: 0 0 12px;
line-height: 1.5;
}
.step-details {
list-style: none;
padding: 0;
margin: 0 0 12px;
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 6px 16px;
li {
position: relative;
padding-left: 16px;
font-size: 13px;
color: var(--text-secondary);
line-height: 1.5;
&::before {
content: '';
position: absolute;
left: 0;
top: 9px;
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--primary);
}
}
}
.step-tech {
display: flex;
align-items: center;
gap: 8px;
font-size: 12px;
color: var(--text-muted);
padding-top: 8px;
border-top: 1px dashed var(--border);
code {
font-family: var(--font-mono);
background: var(--bg-elevated);
padding: 3px 8px;
border-radius: 4px;
color: var(--text-secondary);
font-size: 12px;
}
}
.tech-label {
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.08em;
font-size: 10px;
}
// -- Quality metrics --
.quality-section, .limits-section {
margin-bottom: 40px;
h2 {
font-family: var(--font-display);
font-size: 24px;
margin: 0 0 16px;
padding-bottom: 8px;
border-bottom: 1px solid var(--border);
}
}
.metrics-grid {
display: grid;
grid-template-columns: repeat(4, 1fr);
gap: 12px;
}
.metric {
background: var(--bg-card);
border: 1px solid var(--border);
border-radius: var(--radius-md);
padding: 16px;
text-align: center;
.metric-name {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--text-muted);
font-weight: 700;
margin-bottom: 8px;
}
.metric-value {
font-family: var(--font-display);
font-size: 32px;
font-weight: 700;
color: var(--primary);
line-height: 1;
margin-bottom: 6px;
}
.metric-desc {
font-size: 11px;
color: var(--text-muted);
line-height: 1.4;
}
}
.limits-section ul {
list-style: none;
padding: 0;
display: flex;
flex-direction: column;
gap: 8px;
li {
background: var(--bg-elevated);
border-left: 3px solid var(--accent);
border-radius: var(--radius-sm);
padding: 12px 16px;
font-size: 14px;
color: var(--text-secondary);
line-height: 1.6;
strong { color: var(--text-primary); margin-right: 4px; }
}
}
@media (max-width: 768px) {
.page-title { font-size: 32px; }
.step { grid-template-columns: 1fr; }
.step-num { width: 48px; height: 48px; font-size: 18px; }
.step-details { grid-template-columns: 1fr; }
.metrics-grid { grid-template-columns: repeat(2, 1fr); }
}
</style>