admin / Apex

# Module Blueprint — Answer Library (Tender Q&A Repository)

**Status:** Proposed design (not yet built)
**Working name:** **Answer Library** (alternatives: *Tender Answer Bank*, *Q&A Repository*, *Knowledge Bank*)
**Left-nav entry:** "Answer Library"

---

## 1. Purpose & the "win more tenders" rationale

Every bid the organisation writes produces reusable intellectual capital: a question the
market asked, and the best answer the team could give. Today that value is trapped inside
individual bids. The Answer Library **captures every tender question and its response into
one searchable, curated catalogue**, so the team stops re-writing from scratch and starts
compounding its best work.

**How this directly increases win rate:**

| Lever | Mechanism | Win impact |
|---|---|---|
| **Reuse proven winners** | Answers from **won** bids are flagged and surfaced first | Reuse what evaluators already rewarded, not untested prose |
| **Speed → more bids, more polish** | Draft in minutes by adapting an existing answer | Bid more opportunities; spend saved time on tailoring & win themes |
| **Consistency & quality floor** | One "master" answer per topic, curated and improved over time | No weak/off-message answers slipping through under deadline pressure |
| **Learn from losses** | Answers from **lost** bids are labelled as caution | Stop repeating answers that didn't land; evolve them |
| **Institutional memory** | Knowledge survives staff turnover | New team members produce senior-quality answers on day one |
| **Compliance coverage** | Answers tagged to frameworks (ISO 27001, etc.) | Faster, complete responses to compliance-heavy tenders |
| **Continuous improvement** | Reuse count + win rate per answer guide investment | Double down on the answers that win |

The Library is the connective tissue between **Module 1 (capabilities)** and **Module 2
(response generation)** — it turns one-off responses into a growing, self-improving asset.

---

## 2. What it catalogues (sources)

The Library is populated from data the application already holds:

1. **Tender requirements + responses** — `bid_requirements.question_text` paired with the
   winning/approved `bid_responses.final_text` (or `draft_text`).
2. **Capability responses** — the framework-aligned "win" paragraphs from Module 1.
3. **Manual entries** — a bid writer can add a Q&A directly (e.g. a great answer written
   outside the tool, or a canonical corporate statement).

Each catalogued entry carries **provenance and outcome** so users can trust and rank it.

---

## 3. Data model

Recommended approach: a **curated snapshot** table, not a live view. Snapshotting means
later edits to a bid don't silently mutate the Library, lost-bid answers are retained (with
a caution flag), and entries can be independently improved. A "refresh from source" action
keeps a link when wanted.

### `answer_entries`
| Field | Type | Notes |
|---|---|---|
| `id` | pk | |
| `question` | text | The tender question / topic |
| `answer` | text | The response text |
| `summary` | text | Short one-line gist (AI-generated) for list views |
| `category` | string | Taxonomy (Security, Service Desk, Transition, Social Value, …) — reuses Module 1 categories |
| `tags` | json[] | Free tags (e.g. "24x7", "SOC", "MTTR") |
| `frameworks` | json[] | Framework ids this answer aligns to |
| `source_type` | string | `bid_response` \| `capability` \| `manual` |
| `source_bid_id` | fk? | Provenance |
| `source_response_id` | fk? | Provenance / for "refresh from source" |
| `client` | string | Client the answer was written for (denormalised) |
| `outcome` | string | `won` \| `lost` \| `in_progress` \| `n/a` (from the source bid's state) |
| `status` | string | `draft` \| `curated` \| `master` \| `archived` |
| `group_id` | fk (self) | Groups variants/versions of the same topic; one is `is_master` |
| `is_master` | bool | The recommended canonical answer for its group |
| `quality_score` | int? | Optional AI/human rating (1–5) |
| `reuse_count` | int | Incremented when inserted into a live response |
| `word_count` | int | For quick fit-to-limit checks |
| `search_vector` | tsvector | Postgres full-text index (generated) |
| `embedding` | vector? | Phase 2: pgvector for semantic search |
| `created_by` / `created_at` / `updated_at` | | Audit |

### `answer_reuse_log` (analytics)
`{id, answer_id, bid_id, response_id, user_id, action: inserted|adapted|copied, ts}` —
powers reuse and win-rate analytics, and closes the loop back to outcomes.

---

## 4. Ingestion & curation

**Auto-harvest (the key to a Library that fills itself):**
- On **response approval** and on **package approval**, enqueue a Celery job that upserts
  an `answer_entries` row from each approved requirement+response.
- On **bid outcome change** (`won`/`lost`), propagate `outcome` to the entries harvested
  from that bid, so ranking reflects reality.
- Capability responses are harvested when a capability is approved (Module 1).

**Curation controls:**
- **De-duplication:** on ingest, find near-duplicates (trigram similarity ≥ threshold, or
  embedding cosine in Phase 2). Group them under one `group_id`; don't create noise.
- **Master answers:** a curator marks the best variant `is_master`. Master answers rank
  first and are the default for reuse.
- **Versioning:** editing a master keeps prior variants in the group for history.
- **Provenance & trust:** every entry shows where it came from, the client, and whether the
  parent bid was won or lost. A "won" badge is a strong reuse signal; "lost" is a caution.

---

## 5. Search & retrieval

**MVP (no new infrastructure): Postgres full-text + trigram.**
- `search_vector` (tsvector) for keyword search with ranking (`ts_rank`).
- `pg_trgm` for fuzzy/typo-tolerant matching and similarity dedup.
- **Filters:** category, framework, client, outcome (won/lost), status, tags, date, word
  limit (≤ N words). Free-text + filters combine.
- **Ranking:** relevance × recency × `reuse_count` × outcome weight (won > neutral > lost)
  × `is_master` boost.

**Phase 2 — semantic search.** Add `pgvector` and embeddings so "describe your incident
response" also matches answers about "SOC / MTTR / breach handling" even without shared
keywords. Note: Anthropic does not provide an embeddings API, so this needs either a local
embedding model (e.g. a sentence-transformer running in the worker) or a third-party
embeddings provider — a deliberate dependency decision for Phase 2.

**AI-assisted retrieval that fits the current stack (no embeddings needed):** a **hybrid
retrieve-then-rerank** flow — Postgres returns the top ~20 candidates by keyword/trigram,
then **Claude re-ranks** them for true relevance to the new question and can **compose a
tailored answer** from the best 2–3 (grounded, self-checked for hallucinations exactly like
the existing Assistant). This reuses the Anthropic integration already in place.

---

## 6. AI leverage (where this multiplies value)

1. **Retrieval-augmented response generation (biggest win).** Extend Module 2: when
   generating a response, retrieve the top Library answers for that requirement and pass
   them into the prompt as *proven-answer* grounding — alongside the existing capability
   grounding. The engine adapts a winner instead of inventing from scratch.
2. **Assistant integration (thought cloud).** When a user drafts/enhances a response, the
   Assistant surfaces *"3 proven answers from won bids for this question — reuse or adapt?"*
   with the same guard-rail (hallucination self-check) and human-approval flow.
3. **Auto-tagging & categorisation** on ingest (Claude assigns category, tags, frameworks,
   and a one-line summary) so the Library is organised without manual effort.
4. **Quality scoring & gap analysis.** Claude rates answers and flags topics with only
   weak/lost-bid coverage — a prioritised list of answers worth improving *before* the next
   tender needs them.
5. **De-duplication & merge suggestions** — propose which near-duplicates to merge and which
   variant should be master.

---

## 7. UI / UX

**Left-nav: "Answer Library"** (visible to all roles). Views:

- **Browse / Search:** a prominent search bar + filter rail (category, framework, client,
  outcome, status, tags). Results as **Q&A cards**: question, answer summary, badges
  (won/lost, master, framework chips), reuse count, and quick actions **Copy**, **Insert
  into a response**, **View detail**.
- **Entry detail:** full question + answer, provenance (source bid/client/date), outcome,
  variants in the group, reuse history, tags/category editing, "mark as master", rating,
  and **"refresh from source"**.
- **Insert-into-response:** from a bid's Responses tab, a **"Find in Answer Library"** action
  opens a search scoped to that requirement; selecting an answer inserts/adapts it into the
  response and logs the reuse.
- **Analytics tab (Phase 2):** most-reused answers, win rate of reused answers, coverage by
  category/framework, and "gaps" (topics with weak or lost-only coverage).

---

## 8. Integration points

- **Module 1 (Capabilities):** approved capability responses feed the Library; the Library
  can promote a capability answer to a master.
- **Module 2 (Responses):** two-way — harvests approved responses in; feeds proven answers
  back into generation and manual authoring; logs reuse.
- **Assistant:** a new suggestion kind, `library_reuse`, surfacing proven answers with the
  existing approve-to-apply + audit + guard-rail pattern.
- **Package assembly:** unchanged, but responses are now stronger and more consistent.
- **Audit:** ingestion, curation (master/merge/edit), and reuse are all audited.

---

## 9. RBAC

| Action | Roles |
|---|---|
| Search / view / copy | All authenticated roles |
| Insert into a response | Bid Manager, Contributor |
| Add / edit / tag entries, mark master, merge | Bid Manager, Contributor (curators) |
| Manage taxonomy (categories), archive, bulk ops | Administrator |
| View analytics | Bid Manager, Finance, Administrator, Approver |

---

## 10. KPIs (prove it wins more)

- **Reuse rate** — % of live responses that reused a Library answer.
- **Win rate of reused answers** vs from-scratch answers (the headline metric).
- **Time-to-draft** reduction per bid (via reuse log timestamps).
- **Coverage** — % of common tender topics with a curated/master answer.
- **Library growth & freshness** — entries added, % from won bids, % stale.

---

## 11. Phased delivery

**MVP (Phase 1) — the catalogue + search + reuse.** Highest value, no new infra.
- `answer_entries` + `answer_reuse_log` tables; Postgres FTS + `pg_trgm`.
- Auto-harvest on response/package approval + outcome propagation; manual add.
- Left-nav Answer Library: search + filters + Q&A cards + copy/insert; entry detail;
  mark-as-master; basic dedup grouping.
- Reuse logging; audit.

**Phase 2 — AI multipliers.**
- Retrieval-augmented generation in Module 2 + Assistant `library_reuse` suggestions.
- Claude auto-tagging/summaries on ingest; hybrid retrieve-then-rerank; quality scoring.

**Phase 3 — intelligence & analytics.**
- Semantic search (pgvector + embeddings — dependency decision), analytics dashboard,
  gap analysis, win-rate-by-answer, merge/curation assistant.

---

## 12. API sketch (MVP)

```
GET    /api/library                 ?q=&category=&framework=&client=&outcome=&status=&tags=&limit=&offset=
GET    /api/library/{id}
POST   /api/library                 (manual add)
PATCH  /api/library/{id}            (edit / tag / category / status / mark master)
POST   /api/library/{id}/master     (promote to master within its group)
DELETE /api/library/{id}            (archive)
POST   /api/library/harvest         (admin: backfill from existing approved responses)
POST   /api/library/{id}/reuse      {bid_id, response_id, action}  -> logs reuse (+ optional insert)
GET    /api/library/analytics       (Phase 2)
```

Frontend: `pages/AnswerLibrary.tsx` (browse/search) + `AnswerDetail`, a left-nav link in
`components/Layout.tsx`, and a "Find in Answer Library" action on the Responses tab.

---

## 13. Key design decisions

- **Snapshot, not live view** — retains lost-bid answers, prevents silent mutation, enables
  independent curation. Provide "refresh from source".
- **Keyword/trigram first, semantic later** — ships value immediately with zero new
  dependencies; embeddings are a deliberate Phase-2 choice (Anthropic has no embeddings API).
- **Won/lost outcome as a first-class ranking signal** — the whole point is to reuse winners.
- **Human-in-the-loop curation** — master answers and reuse are curated/approved, never
  auto-applied, consistent with the app's guard-rail philosophy.
```