Steering proposals
Steering proposals separate machine-derived signals from reviewable recommendations. Biblicus owns the artifact contract; the application owns human decisions.
Layers
- Signals are computational candidates: topic ids, graph snapshot refs, evidence item ids, confidence metrics, and deterministic payloads.
- Proposals are judgments over signals:
recommend,do_not_recommend, orneeds_clarification. - Decisions are human accept, reject, edit, or defer actions. Biblicus does not write them.
Graph signals
Generate topic-informed graph signals:
biblicus steering graph-signals \
--corpus corpora/AI-ML-research \
--classifier ai-ml-research \
--graph-snapshot simple-entities:<snapshot_id> \
--steering-feedback papyrus-steering-feedback.json \
--format json
The command emits a proposal bundle with signals and an empty proposals list. A worker can pass
those signals to an agent, a language model, or a human-authored process.
Every accepted taxonomy topic can produce a signal when the graph snapshot has no known topic entity with
the deterministic node id topic:<topic_uid>. Classifier topic maps can also produce candidate
Item -> Topic membership edge signals. When an accepted taxonomy artifact exists, graph signals use every
accepted taxonomy node, including child nodes. When no accepted taxonomy artifact exists, graph signals use
the classifier seed manifest as the root-topic source.
When the steering application exports review memory with
export_kind: "papyrus-steering-feedback", pass it with --steering-feedback. Biblicus uses the normalized
suppressions list to avoid re-emitting rejected graph signals under the same classifier and root topic. This is
negative steering only; accepted taxonomy and ontology manifests remain the positive source of truth.
Suppression input shape:
{
"schema_version": 1,
"export_kind": "papyrus-steering-feedback",
"generated_at": "2026-05-16T00:00:00+00:00",
"source": {
"system": "papyrus",
"topic_set_id": "curation-topic-set-example",
"corpus_id": "curation-corpus-example",
"classifier_id": "example-classifier"
},
"topic_set": {
"topic_set_id": "curation-topic-set-example",
"corpus_id": "curation-corpus-example",
"classifier_id": "example-classifier",
"display_name": "Example Topics",
"description": "Reviewed topic set."
},
"decisions": [],
"accepted_proposals": [],
"rejected_proposals": [],
"suppressions": [
{
"suppression_id": "suppression-create-taxonomy-node-example",
"proposal_id": "create-taxonomy-node:example",
"proposal_kind": "create-taxonomy-node",
"steering_domain": "topic",
"reason": "Rejected during editor review.",
"decided_at": "2026-05-16T00:00:00+00:00",
"decided_by": "editor@example.com",
"scope": {
"topic_set_id": "curation-topic-set-example",
"corpus_id": "curation-corpus-example",
"classifier_id": "example-classifier",
"root_topic_uid": "root-topic"
},
"match": {
"topic_uid": "root-topic-child",
"display_name": "Rejected child label",
"normalized_display_name": "rejected child label",
"relationship_type": null,
"graph_entity_id": null
},
"evidence_item_ids": []
}
]
}
Taxonomy and ontology proposal kinds
Unified steering proposal bundles can now carry topic, graph, taxonomy, and ontology recommendations. Supported taxonomy and ontology proposal kinds are:
create-taxonomy-nodemove-taxonomy-nodemerge-taxonomy-nodessplit-taxonomy-nodearchive-taxonomy-nodeadd-ontology-relationshipadd-relationship-type
Accepted human decisions still live outside Biblicus. Agents can create proposal bundles with any method, then validate or record them through the steering proposal commands.
Sample export
A compact steering export with taxonomy and ontology proposals is available at
docs/examples/steering-export-taxonomy-ontology.json.
The sample shows:
- a flattened
proposalslist containing onecreate-taxonomy-nodeproposal and oneadd-ontology-relationshipproposal; - a
proposal_bundlesentry preserving the normalized steering proposal bundle; - artifact references for
taxonomy,taxonomy-discovery,ontology,steering-proposals, andgraph; - the accepted root topic set under
topic_set.
Accepted taxonomy and ontology manifests are not embedded as top-level steering export fields. The export carries artifact references to those accepted overlays. Workers can load the referenced Biblicus artifacts when they need the full accepted taxonomy or ontology assertion manifest.
Payload field guide
All proposals use the same wrapper fields:
proposal_id: stable proposal identity for idempotent imports;proposal_kind: one of the supported steering proposal kinds;domain:topicorgraph;recommendation: Biblicus or agent judgment, one ofrecommend,do_not_recommend, orneeds_clarification;status: alwaysproposedinside Biblicus artifacts;author: proposal author metadata;source_signal_ids: computational signal identifiers that support the proposal;evidence: proposal-level evidence, usually includingitem_ids;rationale: human-readable reason for the recommendation;confidence: optional proposal confidence;payload: proposal-kind-specific contract.
recommend, do_not_recommend, and needs_clarification are not human review actions. They are
proposal recommendation labels authored before human review. External applications should keep their
own human actions, such as accept, reject, edit, or defer, in application-owned decision records.
create-taxonomy-node
Use when discovery suggests a new accepted taxonomy node.
Expected payload fields:
topic_uid: proposed stable topic identity;parent_topic_uid: parent topic identity, ornullwhen proposing a root;display_name: proposed topic label;description: proposed topic description;document_ids: supporting documents from scoped discovery;keywords: representative topic keywords;topic_id: source BERTopic integer topic id, when applicable.
move-taxonomy-node
Use when a taxonomy node appears to belong under a different parent.
Expected payload fields:
topic_uid: topic identity to move;current_parent_topic_uid: current parent identity, ornull;proposed_parent_topic_uid: proposed parent identity, ornull;evidence_item_ids: evidence supporting the move.
merge-taxonomy-nodes
Use when two or more taxonomy nodes appear semantically redundant.
Expected payload fields:
source_topic_uids: topic identities proposed for merging;target_topic_uid: surviving topic identity;display_name: proposed surviving display name, when a rename is suggested;description: proposed surviving description, when a rewrite is suggested;evidence_item_ids: evidence supporting the merge.
split-taxonomy-node
Use when one taxonomy node repeatedly contains multiple stable child concepts.
Expected payload fields:
topic_uid: topic identity proposed for splitting;proposed_children: list of child topic objects, each withtopic_uid,display_name,description, and optionalseed_item_idsorholdout_item_ids;evidence_item_ids: evidence supporting the split.
archive-taxonomy-node
Use when a taxonomy node no longer has active analytical value.
Expected payload fields:
topic_uid: topic identity proposed for archiving;reason: archive rationale;evidence_item_ids: evidence supporting the archive decision.
add-ontology-relationship
Use when an accepted typed relationship assertion should be added.
Expected payload fields:
assertion_id: stable assertion identity for idempotent imports and accepted ontology manifests;source_ref: source reference, usingitem:<item_id>,topic:<topic_uid>, orgraph:<node_id>;relationship_uid: relationship type identity, such asinfluenced,historical_context_for, oruse_case_of;target_ref: target reference, using the same ref vocabulary assource_ref;direction:outboundorinbound;evidence_item_ids: evidence item identifiers;confidence: optional assertion confidence;notes: optional reviewer or agent note.
When accepted, these fields can be rendered directly into an ontology assertion manifest.
add-relationship-type
Use when a new reusable relationship predicate is needed.
Expected payload fields:
relationship_uid: stable relationship type identity;display_name: human-readable relationship name;description: relationship definition;directed: whether assertions using this relationship are directed.
Deprecated or suppressing graph structure
Use suppress-entity-or-edge for graph entities or edges that should be hidden, ignored, or
excluded from a future graph view or materialization step. This remains a proposal only; Biblicus does
not remove graph data automatically.
Proposal bundles
Validate an externally authored proposal bundle:
biblicus steering proposals validate \
--input proposal-bundle.json
Record a validated bundle as a reproducible Biblicus artifact:
biblicus steering proposals record \
--corpus corpora/AI-ML-research \
--input proposal-bundle.json
Recorded bundles are written under:
analysis/steering-proposals/<snapshot_id>/
The directory contains:
manifest.json: reproducibility metadata and artifact paths;signals.json: computational signal records;proposals.json: proposal judgments;report.md: optional human-readable rendering when available.
Proposal recommendations
Proposals must use one of:
recommenddo_not_recommendneeds_clarification
Negative recommendations are first-class. Applications should show them because they explain what the agent considered and rejected.
Human decisions
The external steering application imports proposal artifacts and records human decisions in its own schema. Biblicus proposal artifacts must not contain human decision fields or accepted/rejected review state.