Skip to content
Factflow

Knowledge & Avalon synthesis

Knowledge covers the lifecycle of a concept map across three stages, each a set of pipeline adapters:

  • Detection — extract concepts from segmented content
  • Consolidation — merge concepts across sources and write to Avalon (DNB's knowledge platform)
  • Diff — compare snapshots and emit a structured diff

Detection

Section titled “Detection”

concept_detection extracts taxonomy-guided concepts via LLM structured output; concept_map_writer persists the map. Both taxonomy_path and llm_profile are required.

- type: "concept_detection"
  config:
    taxonomy_path: "config/scribe/taxonomy.yaml"
    llm_profile: "openrouter-gemini-flash-chat"
    reasoning_effort: "medium"
    content_cutoff: 50000

Consolidation

Section titled “Consolidation”

Consolidation is a multi-adapter route, not a single adapter. The shipped scribe/avalon-consolidation.yaml chains:

concept_fanout → concept_source_loader → batch_synthesizer → structural_validator → avalon_writer → concept_map_updater

batch_synthesizer does the LLM synthesis (llm_profile, batch_size); structural_validator runs citation / length / source-diversity checks; avalon_writer posts the result to Avalon. See the shipped config for the full wiring.

Diff

Section titled “Diff”

knowledge_diff compares the current concepts against a stored reference and emits a structured diff; scribe_diff_writer persists it.

- type: "knowledge_diff"
  config:
    llm_profile: "openrouter-gemini-flash-chat"
    source_identity_field: "object_key"
    reference_prefix: "scribe/diff-state"
    diff_sample_length: 5000
    reasoning_effort: "low"

Avalon integration

Section titled “Avalon integration”

avalon_writer posts the consolidated map to Avalon over HTTP. Its endpoint and credentials come from application config / environment, not adapter YAML.

Export

Section titled “Export”

The dnb-avalon export (factflow_knowledge.export) projects the stored concept map into a self-contained git repo — Avalon pages plus a stats/ tree and a taxonomy.yaml schema. It is a pure projection of the database, fully regenerated each run:

Terminal window
cd backend
uv run python -m factflow_knowledge.export --help

Source-level findings

Section titled “Source-level findings”

The export carries the hygiene and conflict findings forward so they can be audited from the exported repo alone, without dropping into the database. Alongside the Avalon pages, stats/ holds one record per source:

FilePer-source record
stats/pii.jsonPII detections by source (origin, source_ref, finding type)
stats/sensitivity.jsonsensitivity label with confidence, rationale, and model profile
stats/anti_bac.jsonbroken-access-control verdicts (party + offending fact)
stats/conflicts.jsonper conflict: which sources contributed and which one won precedence (is_winner)
stats/pages.jsonpage-level rollup

Every finding ties back to its upstream (origin, source_ref) document — which SharePoint URL was classified confidential, which spreadsheet held a kontonummer, which source won a contradiction. That traceability is the credibility floor: a synthesized claim a reviewer cannot trace is one they will not trust. The PII, sensitivity, and anti-BAC rows are written upstream by Hygiene.

Testing epistemic quality

Section titled “Testing epistemic quality”

The epistemic-evaluation skill in .claude/skills/ captures patterns for assessing extraction quality (precision, recall, coherence) against reference datasets.

Section titled “Related”