Biblicus

Make your documents usable by your assistant, then decide later how you will search and retrieve them.

Topic trends

Topic trends combine exploratory topic modeling with corpus publication dates. They answer a different question from the topic classifier:

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:

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

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.