Beadloom

Appearance

✅ fresh

last synced 2026-09-29T21:12:19.681221+00:00 · coverage 100% (context-builder)

Validation by Beadloom doc_sync — same source as sync-check.

Context Builder (component) ​

Internal building block of the context-oracle domain.

Source: src/beadloom/context_oracle/builder.py

Overview ​

Assembles a context bundle for a node via a bounded BFS subgraph traversal of the graph, gathering the node, its neighbors, the attributed code symbols, and the relevant docs into one structured bundle. This is the machinery behind ctx / prime — the read-only context surface AI agents consume.

Public surface ​

  • build_context(conn, ref_ids, *, depth=2, max_nodes=20, max_chunks=10, intent=None) — build a full versioned context bundle for the focus ref_ids; raises LookupError if any focus ref_id is unknown. intent is a read of the project's TO-BE space supplied by the caller: this builder takes a connection and no project root, so it cannot read that space itself and None produces intent.status = "not_checked" rather than an absence of intent.
  • bfs_subgraph(conn, focus_ref_ids, depth=2, max_nodes=20) — the bounded bidirectional BFS that expands neighbors by edge priority; returns (nodes, edges).
  • collect_chunks(conn, ref_ids, max_chunks=10) — gather doc text chunks for the subgraph, ordered by section priority.
  • suggest_ref_id(conn, ref_id) — up to 5 prefix-/Levenshtein-matched suggestions for a missing ref_id.
  • estimate_tokens(text) — the chars/4 token-count heuristic used to size bundles.
  • DEFAULT_DEPTH / DEFAULT_MAX_NODES / DEFAULT_MAX_CHUNKS — traversal defaults (2 / 20 / 10).

Collaborators ​

Reads nodes / edges / chunks / code_symbols / sync_state (populated by the graph-loader, doc-indexer, and code-indexer) plus the architecture rules. It is the engine behind the ctx / prime surfaces and feeds the cache feature; the full bundle shape and the BFS / chunk-priority tables live in the context-oracle README.

The bundle's intent section is decided by the node-intent component, which this module calls with the focus ref ids only: the traversal reaches up to twenty nodes and the question was asked about one or two of them. See node-intent.

The bundle's tests key is the focus node's extra["tests"], which the reindex rebuilt from the test binding. Since BDL-074 C2 the bundle also carries test_placements, the project's indexed test files by placement, read from the test_files table by infrastructure.repository.count_test_files_by_placement ({} for an index older than that table). A reader needs it to tell a node with no bound test from a repository whose tests are not laid out yet. Since BDL-074 G2 the builder states that share itself, as test_unplaced: test_binding.describe_unplaced() over those counts and the test layout the index recorded (infrastructure.repository.read_test_layout), or None when no file is unplaced. It is stated here because the sentence names the recorded layout's folders and the index is open here. ctx prints it under its Tests: line. Since beadloom-2mj3.15 the bundle also carries test_recognition: test_binding.describe_test_file_recognition() over the same recorded layout — the patterns and roots a test file is read under — or None when the index recorded no layout. It is stated every time, not only when a file is unplaced, because a count of bound files is a count of the files those patterns matched. ctx prints it capitalised under Tests:. See test mapping.

Component doc (BDL-051). Public surface verified against builder.py.