Spaces:
Sleeping
Sleeping
Benard John
feat: implement feedback API endpoint and add new frontend views for status, legal, and documentation pages.
2a72aeb Download web/src/views/MethodologyView.vue from Benaah/MicProtocol: direct link, hf CLI and curl.
- Browser
- Download file 11 kB
-
https://huggingface.co/spaces/Benaah/MicProtocol/resolve/main/web/src/views/MethodologyView.vue
- Command line
-
hf download hf://spaces/Benaah/MicProtocol/web/src/views/MethodologyView.vue
-
curl -L -o MethodologyView.vue https://huggingface.co/spaces/Benaah/MicProtocol/resolve/main/web/src/views/MethodologyView.vue
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> | |