Feature: KB Research & Synthesis Agent

Last updated: 2026-06-24 (docs-gap backfill for #1336; feature shipped in #1279, closes #1225)

The KB Research & Synthesis agent bootstraps a new client's Knowledge Base during onboarding. After an Account Manager (AM) seeds a handful of inputs (files, URLs, free-form prompts), the agent reads them, sleuths a few public sources, and synthesizes four first-draft KB markdown documents the Specialist can eventually retrieve. Every synthesized document is written pending_review and is hidden from Specialist retrieval until an AM or SuperAdmin approves it — that is the retrieval safety gate, and it is the highest-risk part of the feature.

Default-off / hidden-by-default. Unapproved synthesis can never influence a Specialist's drafted reply. The retrieval gate (below) is enforced in HaystackRetrievalService — serving only approved (or legacy NULL) documents. Do not weaken it. (See Retrieval safety gate for the four hidden-status cases and the current test coverage.)

This feature sits between two surfaces:

AM seed inputs (#1224 / #1277) — what the AM uploads before research runs.
KB retrieval (ADR-008) — how approved documents reach the Specialist at chat time.

End-to-end flow

AM seeds inputs              Research agent (Python)            Review gate (NestJS)            Specialist
─────────────────            ───────────────────────           ────────────────────           ──────────
POST /admin/orgs/:orgId      POST /v1/kb/research               4 docs written                 KB retrieval
  /seed-kb                     ├─ render AM inputs                status = pending_review         (search)
  files / urls / prompts       ├─ fetch public context     ──►   source_tag = agent_synthesis  ──►  gate filters
       │                       │   (X profile, homepage,         synthesis_run_id = <uuid>       status != approved
       ▼                       │    DuckDuckGo searches)              │                              │
  source_tag =                 ├─ Haiku 4.5 synthesis               AM/SuperAdmin reviews:         only approved
   am_file/am_url/am_prompt    └─ validate (4 docs +                 Approve / Edit / Reject        docs served
       │                           citations footer)                     │
       └───────────── am_inputs ────────────►                            ▼
                                                                  status = approved ──────────────►

Seed. The AM submits an input bundle for the org (see AM-input bundle). Each input is stored on org_documents tagged am_file, am_url, or am_prompt.
Run. The research run is invoked with the org's am_inputs. The agent gathers public context, calls the LLM, and returns exactly four documents.
Persist. The four documents are written to the org KB with status = 'pending_review', source_tag = 'agent_synthesis', and a shared synthesis_run_id.
Review. An AM (assigned to the org) or a SuperAdmin previews each draft and Approves, Edits & Approves, or Rejects it.
Serve. Only approved documents pass the retrieval gate and become visible to the Specialist.

The research agent (Python / FastAPI)

Item	Value
Endpoint	`POST /v1/kb/research` (auth: `verify_agent_secret`) — the router defines `/kb/research` and `agent/main.py` mounts it under the `/v1` prefix
Router	`agent/routers/kb_research.py`
Pipeline	`agent/research_synthesis.py` — `synthesize_research_docs()`
Models	`agent/models/research.py` — `KbResearchRequest` / `KbResearchResponse`
Default model	`claude-haiku-4-5` (override with env `KB_RESEARCH_MODEL` or `request.model`)

Request / response shape

// KbResearchRequest
{
  "orgId": "…",                 // client org UUID (alias: org_id)
  "clientName": "Acme Financial",
  "am_inputs": [                // the AM-seeded bundle (see below)
    { "docId": "…", "source": "am_url", "title": "Acme homepage",
      "snippet": "https://acme.example … about us …" }
  ],
  "budget_cap_tokens": 200000,  // default 200K
  "model": null                 // optional override
}

// KbResearchResponse
{
  "synthesis_run_id": "…",      // groups the four output docs
  "budget_exceeded": false,
  "documents": [ { "filename": "…", "title": "…", "content": "…" }, … ],
  "consumed_tokens": 41200
}

Public-source sleuthing

gather_public_context() augments the AM corpus with a bounded set of public fetches:

The client's X/Twitter profile (https://x.com/<handle>, handle derived from clientName).
The homepage, extracted from the first URL found in the AM inputs (homepage_from_inputs).
Two DuckDuckGo HTML searches: "<client>" tone OR voice OR brand and "<client>" compliance OR regulatory.

All outbound fetches are SSRF-guarded by _hostname_is_safe(), which rejects cloud metadata/IMDS endpoints (169.254.169.254, metadata.google.internal, Alibaba 100.100.100.200, AWS IMDSv2 IPv6, …) and any non-global IP. The final host is re-validated after redirects, so an attacker-controlled 302 to an IMDS endpoint cannot leak instance metadata into a synthesized document.

The four output documents

validate_documents() enforces that the LLM returns exactly these four filenames, each ending with a ---\n## Citations footer:

Filename	Contents
`brand-voice-playbook.md`	Tone guide. Golden examples + anti-examples — every example must carry a citation id (`[doc:…]`, `[url:…]`, or `[search:…]`).
`product-context.md`	Products, audience, status.
`compliance-notes.md`	Flagged risk topics — only echoed from the corpus, never invented.
`key-contacts-extracted.md`	Names, roles, escalation paths.

If the LLM returns the wrong number of documents, a wrong filename, a missing citations footer, or an uncited brand-voice example, synthesis raises rather than persisting a malformed draft.

Cost discipline (atomic budget stop)

FetchBudget enforces two hard caps per run:

30 external fetches (max_fetches).
A token budget (budget_cap_tokens, default 200,000). Tokens are charged for the AM corpus, every public-context block, the synthesis prompt, and the LLM response.

The moment the budget is exceeded, mark_exceeded() emits the kb_research_budget_exceeded Prometheus counter (labelled by org) and the run returns budget_exceeded: true with an empty documents array — an atomic stop with no partial writes. The NestJS side persists nothing for a budget-exceeded run.

Retrieval safety gate (NestJS)

This is the critical invariant of the feature. Unapproved synthesis must never reach the Specialist. The gate lives in api/src/haystack/haystack-retrieval.service.ts.

Specialist retrieval flows through two methods, both status-gated:

search() — production retrieval. Candidate chunks are filtered through allowedDocumentIds(), whose WHERE only admits documents with status = 'approved' or status IS NULL (legacy rows that predate the review states). pending_review, rejected, and superseded are excluded. The same predicate also enforces effective_date <= today, audience, and parse_status IN ('ingested','parsed').
listDocumentChunks() — fetches the chunks, then re-reads the document's status and returns [] whenever it is set to anything other than approved.

status        Specialist retrieval
───────────   ────────────────────
approved      ✅ served
NULL          ✅ served (legacy, pre-review rows)
pending_review ❌ hidden
rejected      ❌ hidden
superseded    ❌ hidden

The gate's contract is its code: allowedDocumentIds() (for search()) and the status re-check in listDocumentChunks(). The review-state transitions that feed it (approve / reject / and the refusal to act on a superseded doc) are covered by api/src/kb/kb-documents.controller.spec.ts. A dedicated retrieval-gate spec asserting the four hidden-status cases against HaystackRetrievalService is not currently present in dev (it was named ragflow-retrieval-status-gating.spec.ts in #1279 but did not survive the RAGFlow → Haystack port — see Implementation status). Re-adding it before any change that touches the gate is the safest guard.

Admin-inspection bypass

AMs need to preview and edit a pending_review draft, which the Specialist gate would otherwise return empty. KbService.getDocument() therefore routes HP review roles (superadmin, account_manager, expert) to listDocumentChunksForReview(), which bypasses the status gate for human inspection only. This bypass never touches search() — the Specialist's retrieval path is unaffected.

Known scope note. expert is included in that review-role set, so an org expert can read pending synthesis chunks via the document-detail endpoint. This is human read-only access; it does not affect the Specialist AI gate. Tracked as a P2 observation on #1279.

Review workflow & document states

Synthesized documents reuse the org_documents.status column as their review state (OrgDocumentReviewStatus):

Status	Meaning	Specialist sees it?
`pending_review`	Freshly synthesized draft, awaiting review	No
`approved`	AM/SuperAdmin approved (or edited & approved)	Yes
`rejected`	AM/SuperAdmin rejected; excluded from Specialist context	No
`superseded`	Replaced by a newer document/run	No

Review endpoints

Exposed by KbAdminController under admin/kb, restricted to superadmin and account_manager:

Endpoint	Action
`POST /admin/kb/documents/:id/approve`	`status → approved`; stamps `approved_by` / `approved_at`.
`POST /admin/kb/documents/:id/reject`	`status → rejected`; stamps `rejected_by` / `rejected_at`.
`POST /admin/kb/documents/:id/edit`	Replaces the document content (body `{ content }`, validated non-empty), re-ingests, then `status → approved`; stamps `edited_by`.

Authorization is enforced in KbService.findDocumentForReview():

Caller must be superadmin or account_manager.
An account_manager must be the org's assigned AM (organizations.assigned_am_id).
The transition is gated on the document still being pending_review — a concurrent approve/reject returns HTTP 409 (ConflictException) rather than double-applying, per the platform's idempotent state-machine contract.

Every transition writes an audit-log entry (kb.document.approved / kb.document.rejected / kb.document.edited_approved) carrying the synthesisRunId and sourceTag.

Review surface (Ops)

The Ops client-detail page (/ops/clients/[id]) renders a "Pending agent-drafted KB documents" panel (PendingAgentKbPanel) for AMs and SuperAdmins, with a preview modal, Approve / Edit / Reject actions, and a button to trigger a new research run.

The panel — and its "Run research" button — is hidden on a fresh org. PendingAgentKbPanel returns null when the org has no pending_review and no rejected agent-synthesis documents, so it only appears once a run has already produced drafts. Combined with the orchestration seam noted in Implementation status, the first run for a brand-new org is not currently launchable from this panel.

AM-input bundle (#1224 / #1277)

Research runs over inputs the AM seeds before synthesis. The bundle is submitted to KbSeedingController:

POST /admin/orgs/:orgId/seed-kb        (superadmin | account_manager)
  multipart: files[]  (≤ 20 files, ≤ 25 MB each)
  payload:   { urls: string[], prompts: string[] }
GET  /admin/orgs/:orgId/seed-kb/inputs  → list seeded inputs

Each accepted input becomes an org_documents row tagged with its source, and is passed to the agent as an AmResearchInput:

`source` tag	Origin	How the agent uses it
`am_file`	Uploaded file	Rendered into the `# AM inputs` corpus, cited as `[doc:<docId>]`.
`am_url`	URL provided by the AM	Same; the first URL also seeds the homepage fetch.
`am_prompt`	Free-form AM instruction	Same; steers tone/compliance emphasis.

render_am_inputs() formats the bundle into the corpus the synthesizer reads, and homepage_from_inputs() extracts the first http(s) URL as the homepage to fetch. AM inputs are themselves readable by reviewers via the unchecked admin-inspection path (listAmInputChunks), independent of the Specialist gate.

Schema

Added by migration 1780291000000-OrgDocumentResearchReviewFields.ts:

Column	Notes
`org_documents.status`	Default changed to `approved`. Review state: `pending_review \| approved \| rejected \| superseded`.
`org_documents.synthesis_run_id` (uuid, nullable)	Groups the four `agent_synthesis` drafts from one run.
`org_documents.source_tag` (text, nullable)	`am_file \| am_url \| am_prompt \| agent_synthesis`.

Indexes: idx_org_documents_approved_audience (partial, status='approved' — the retrieval hot path), idx_org_documents_pending_review (the AM review queue), and idx_org_documents_synthesis_run.

The migration remaps legacy statuses forward (active → approved, draft → pending_review, deprecated → superseded; unknown values fall back to approved). Risk: any pre-existing document not in active becomes non-approved and therefore excluded from retrieval after the migration — by design, since the gate now serves approved/NULL only.

Relevant config

Variable	Service	Default	Purpose
`KB_RESEARCH_MODEL`	agent	`claude-haiku-4-5`	Synthesis model.
`budget_cap_tokens` (request field)	agent	`200000`	Per-run token budget.

Implementation status (as of 2026-06-24, `dev`)

The feature spans two services joined by an orchestration seam. Current state on dev:

Agent service — the synthesis pipeline (POST /kb/research, research_synthesis.py, the four-document + citation validators, the budget and SSRF guards) is present.
API service — the review/retrieval gate (the status enum + migration, the HaystackRetrievalService gate, the approve/reject/edit endpoints, the AM seed-input intake) is present.
Orchestration seam — #1279 landed the NestJS trigger as a RAGFlow-named BullMQ worker + POST /admin/clients/:orgId/research:run hook. That worker was not carried through the RAGFlow → Haystack migration (ADR-024); the Ops "Run research" button (runClientKbResearch) still posts to …/research:run, which is the integration point a Haystack-side processor needs to re-expose to wire the two halves together end-to-end.

This is worth knowing before assuming a single button click drives the whole pipeline today: the agent pipeline and the review gate are independently shipped and tested; the on-demand trigger that bridges them is the remaining seam.

ADR-008 — Knowledge Base architecture (K1 + K2) — KB scope/ACL primitive the synthesized docs live under.
ADR-024 — Haystack migration — current retrieval backend (RAGflow → Haystack/Hayhooks).
Onboarding — where AM seeding fits in the client setup flow.
Agentic Tasks — the Specialist-side agent runtime that consumes approved KB context.
Expert Queue (HITL) — the human-in-the-loop review model this gate mirrors.

End-to-end flow​

The research agent (Python / FastAPI)​

Request / response shape​

Public-source sleuthing​

The four output documents​

Cost discipline (atomic budget stop)​

Retrieval safety gate (NestJS)​

Admin-inspection bypass​

Review workflow & document states​

Review endpoints​

Review surface (Ops)​

AM-input bundle (#1224 / #1277)​

Schema​

Relevant config​

Implementation status (as of 2026-06-24, dev)​

Related docs​