Topic trends
Topic trends combine exploratory topic modeling with corpus publication dates. They answer a different question from the topic classifier:
- topic classifiers describe stable, reviewed knowledge-base categories;
- topic trends describe time-sensitive publication momentum inside discovered clusters.
Date metadata
Trend analysis uses one canonical field:
dates:
published_at: "2025-08-01"
Optional related fields can be stored beside it:
dates:
published_at: "2025-08-01"
updated_at: "2025-08-14"
retrieved_at: "2026-05-15T20:30:00Z"
date_provenance:
published_at: source-metadata
Do not use ingest created_at, retrieval time, or legacy top-level published metadata for trends.
Run a trend report
Run topic modeling first, then analyze trends from that snapshot:
biblicus analyze topic-trends \
--corpus corpora/AI-ML-research \
--topic-modeling-snapshot <snapshot_id> \
--classifier ai-ml-research \
--windows 30d,90d,1y,all \
--format markdown
The report writes immutable artifacts under:
analysis/topic-governance/<snapshot_id>/
The directory contains:
manifest.json: reproducibility inputs for the report;output.json: ranked canonical and discovered topic summaries;proposals.json: unified steering proposal records;report.md: Markdown rendering of the report.
Markdown tables show the human-readable topic label beside the BERTopic topic identifier. When the topic modeling snapshot used a BERTopic representation model, the label is the representation-model label rather than only the first keyword fragment.
Weekly bins
Add --bin weekly to report, for every topic, a series of integer counts binned by ISO week. This is the series a front end needs for an 8-week sparkline or a 26-week trend chart.
biblicus analyze topic-trends \
--corpus corpora/AI-ML-research \
--topic-modeling-snapshot <snapshot_id> \
--bin weekly --weeks 26 \
--as-of 2026-10-21
--weeks Nsets the number of bins and defaults to 8. It requires--bin; passing it alone is an error. The maximum is 520.- Weeks are ISO weeks that start on Monday. The final bin is the ISO week that contains
--as-of. With--bin weeklythe default--as-ofis today in UTC, not the latest published date. Pass an explicit--as-offor a deterministic result. - Each topic reports exactly
Ninteger counts ordered oldest to newest. Items published before the first bin or after the final week are not counted in any bin. - Items with no valid
dates.published_atare excluded from every bin and counted once inweekly_bins.undated_items. - Without
--binthe output is identical to the trailing-window output: theweekly_binskey is absent, not null.
The output gains one block, weekly_bins, in analysis/topic-governance/<snapshot_id>/output.json:
{
"weekly_bins": {
"bin": "weekly",
"weeks": 8,
"as_of": "2026-03-11",
"iso_weeks": ["2026-W04", "...", "2026-W11"],
"week_starts": ["2026-01-19", "...", "2026-03-09"],
"undated_items": 2,
"discovered_topics": [
{"topic_id": 0, "topic_uid": null, "label": "agent", "counts": [1, 1, 2, 0, 1, 0, 0, 2]}
],
"canonical_topics": []
}
}
discovered_topics entries carry topic_id (the BERTopic topic identifier, including -1 for outliers) and canonical_topics entries carry topic_uid when a --classifier is given. The published schema is docs/api-schemas/analyze-topic-trends.response.schema.json. The behavior specifications are in features/topic_trend_weekly_bins.feature.
Entity-level series are not computed here. Consumers count those over their own confirmed entity links.
Momentum ranking
Momentum compares a topic's recent publication-window share to its all-time share in the trend-eligible corpus. The default ranking window is 90d.
Undated items are not included in these counts. The report lists them in warnings so curators can decide whether metadata cleanup is needed.
Propose-only governance
Governance proposals use the unified steering proposal contract. They can recommend new topics, relabeling, merging, splitting, or archiving. The first implementation emits new-topic recommendations for discovered clusters with enough evidence. A proposal payload includes a topic identity, label, description, evidence item identifiers, suggested seeds, and suggested holdouts. When a discovered topic has a BERTopic representation-model label, that label becomes the proposed display name.
The proposal does not change the accepted classifier manifest. If a curator accepts it, they draft a new reviewed manifest and train a new model version.