Skip to content
Factflow

factflow-knowledge

Concept detection, consolidation, and knowledge-diff adapters. Turns segmented/embedded content into a structured concept map, detects change over time, and exports to downstream systems (Avalon).

Tier and role

Section titled “Tier and role”

Consumed by pipelines that need structured knowledge rather than raw segments. Often the final stage before export.

Context

Section titled “Context”

Three subpackages, each owning a stage of the knowledge lifecycle:

concept_detection

Section titled “concept_detection”

Identify concepts in segmented content (LLM-extracted). Maintains a per-origin concept map in storage.

  • adapter.py — pipeline adapter that runs detection
  • concept_map_writer.py — persists the map
  • repository.py — read/write access to detected concepts
  • models.py — typed concept + relationship records

consolidation

Section titled “consolidation”

Merge concepts from multiple sources; write to Avalon (DNB’s knowledge platform).

  • concept_map_updater.py — merges new detections into an existing map
  • concept_source_loader.py — reads source documents referenced by concepts
  • avalon_writer.py — persists the consolidated map to Avalon
  • models.py

knowledge_diff

Section titled “knowledge_diff”

Compare two snapshots of a knowledge map; emit a diff with storage-writeable output.

  • adapter.py
  • storage_enumerator.py
  • diff_storage_writer.py

export

Section titled “export”

Render concept maps to shareable formats (tree / report / taxonomy).

  • exporter.py
  • renderer.py
  • taxonomy_resolver.py
  • stats.py

Public API

Section titled “Public API”

Top-level factflow_knowledge/__init__.py is intentionally empty. Consumers:

  • Configure adapters via YAML (pipeline config references them by their type: string — each adapter registers itself via discovery)
  • Use python -m factflow_knowledge.export to run export CLI

Importing individual classes is rare; when needed, import from the subpackage (e.g. from factflow_knowledge.concept_detection.adapter import ConceptDetectionAdapter).

Dependencies

Section titled “Dependencies”
  • Workspace: factflow-protocols, factflow-foundation, factflow-engine, factflow-llm (for concept extraction)
  • External services: storage provider, LLM provider, Avalon credentials (for the avalon_writer)

Testing

Section titled “Testing”

Tests at backend/packages/workflows/factflow-knowledge/tests/. Testing concept detection is LLM-heavy — see .claude/skills/backend/llm-unit-testing/ for the mocking pattern. See .claude/skills/epistemic-evaluation/ for assessing extraction quality.

Section titled “Related”