Skip to main content


Sinapsis
Sinapsis Bertopic

Train and apply BERTopic topic models within Agent graphs.

Overview

sinapsis-bertopic — Package for topic modeling using BERTopic, including templates for fitting models and making predictions.

Topic modelling helps explore large collections of messages or documents without a predefined taxonomy. The package separates fitting, inference and downstream result handling for repeatable topic analysis.

Where it fits

Quality depends on embedding models, preprocessing and clustering choices. A trained topic model should be applied to data prepared consistently with the training corpus.

Installation

Requires Python 3.13 or later, as declared in this package’s manifest. Install the base distribution using your preferred package manager:

uv pip install sinapsis-bertopic
# or
pip install sinapsis-bertopic

Optional features and dependencies

The base installation includes the dependencies required by the package. The following extras are declared in this package’s pyproject.toml; install only those needed by your workflow. They are standard Python optional dependencies, not separate execution profiles.

Extra Adds / when to select it
wikipedia-reader Wikipedia reader support. Dependencies: sinapsis-langchain-readers[langchain-wikipedia-readers]
sinapsis-data-writers Save the resulting DataContainer content to files. Dependencies: sinapsis-data-writers[opencv]
all Bundle declared by this package; its manifest includes sinapsis-data-readers, sinapsis-data-writers, wikipedia-reader.
sinapsis-data-readers Load external media or datasets into DataContainers. Dependencies: sinapsis-data-readers

For example:

uv pip install "sinapsis-bertopic[wikipedia-reader]"

The manifest also defines development-only dependency groups: dev (pre-commit, ty). These support source development and testing and are not runtime extras.

🚀 Features

Templates Supported

This package includes a publisher Template and a Worker agent

  • BERTopicFitModel: A template class for fitting BERTopic models and saving them to disk.
  • BERTopicFitModelFromDataFrame: A template class for fitting BERTopic models using data from a DataFrame and saving the model to disk.
  • BERTopicPredict: Template for topic prediction using BERTopic models.

For example, for BERTopicPredict use sinx templates example-config BERTopicPredict to produce an example config like:

agent:
  name: my_sinapsis_bertopic_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: BERTopicPredict
  class_name: BERTopicPredict
  template_input: InputTemplate
  attributes:
    root_dir: /root/.cache/sinapsis
    export_visualization_to_image: true
    image_export_params:
      format: png
      width: null
      height: null
      scale: null
      validate_figure: true
    sentence_model_name: sentence-transformers/all-MiniLM-L6-v2
    model_path: '`replace_me:<class ''str''>`'
    visualize_predictions: true
    visualize_topics: true
    historical_data_path: null
    prediction_viz_path: prediction_viz.html
    visualize_topics_params:
      topics: null
      top_n_topics: null
      use_ctfidf: false
      custom_labels: false
      title: <b>Intertopic Distance Map</b>
      figure_width: 650
      figure_height: 650
    save_topic_visualization_path: topics_visualization.html

Example Agent

The following is adapted directly from the package’s shipped bertopic_predict.yml configuration. Save it as my_bertopic_agent.yaml. The example may require model checkpoints, input files, additional Template packages, or provider credentials as described in its configuration.

agent:
  name: my_bertopic_agent
  description: Topic inference agent for mapping text to pretrained BERTopic models.
  long_description: >
    This agent performs semantic inference by mapping new text data onto a pretrained BERTopic model.
    It leverages high-dimensional embeddings to categorize unstructured content—such as data on
    Autonomous Vehicles—into established thematic clusters, ensuring consistent classification without
    the need for additional training.

templates:
  - template_name: InputTemplate
    class_name: InputTemplate
    attributes: {}

  - template_name: PyPDFLoaderWrapper_70780
    class_name: WikipediaLoaderWrapper
    template_input: InputTemplate
    attributes:
      add_document_as_text_packet: true
      wikipedialoader_init:
        query: foreign exchange mechanics and currency markets
        lang: en
        load_max_docs: 1
        load_all_available_meta: false
        doc_content_chars_max: 4000

  - template_name: PyPDFLoaderWrapper_70781
    class_name: WikipediaLoaderWrapper
    template_input: PyPDFLoaderWrapper_70780
    attributes:
      add_document_as_text_packet: true
      wikipedialoader_init:
        query: trading strategies & market dynamics
        lang: en
        load_max_docs: 1
        load_all_available_meta: false
        doc_content_chars_max: 4000

  - template_name: PyPDFLoaderWrapper_70782
    class_name: WikipediaLoaderWrapper
    template_input: PyPDFLoaderWrapper_70781
    attributes:
      add_document_as_text_packet: true
      wikipedialoader_init:
        query: fintech trends and innovations
        lang: en
        load_max_docs: 1
        load_all_available_meta: false
        doc_content_chars_max: 4000


  - template_name: BERTopic
    template_input: PyPDFLoaderWrapper_70782
    class_name: BERTopicPredict
    attributes:
      root_dir: "artifacts"
      prediction_viz_path: "bertopic_prediction_visualization.html"
      bertopic_model_params:
        calculates_probabilities: true
      visualize_predictions: true
      historical_data_path: "artifacts/training_data.pkl" # Path to historical data used for visualization
      #model_path: "MaartenGr/BERTopic_Wikipedia" # Points to model stored in HF Hub
      model_path: "artifacts/bert_model_finance-5" # Points to local saved model
sinx jobs run my_bertopic_agent.yaml

More configurations: bertopic_fit_model_worker.yml, bertopic_fit_model_from_dataframe.yml, bertopic_predict.yml, bertopic_fit_model.yml.

Documentation

License

Sinapsis open-source components are available under your choice of the MIT License or the Apache License 2.0, unless otherwise noted.

Metadata

Release files for sinapsis-bertopic 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sinapsis-bertopic 1.0.0
File Size Uploaded Provenance Actions
sinapsis_bertopic-1.0.0.tar.gz 224.0 kB Without provenance Details for sinapsis_bertopic-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sinapsis-bertopic 1.0.0
File Interpreter ABI Platform Actions
sinapsis_bertopic-1.0.0-py3-none-any.whl Python 3 none any Details for sinapsis_bertopic-1.0.0-py3-none-any.whl

Total release size: 256.1 kB

Release files / sinapsis_bertopic-1.0.0.tar.gz

Download URL sinapsis_bertopic-1.0.0.tar.gz
Size 224.0 kB
Tags Source
SHA-256 checksum
How to use checksums
4000875e5b90dff08179f6f3f22605f94ac38021de585664308a62000c971184
BLAKE2b-256 checksum
How to use checksums
8d3691529cff662e3b391ae5ecf39a818df11c3fcc2e59dd00ede425147dc114
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.17

Release files / sinapsis_bertopic-1.0.0-py3-none-any.whl

Download URL sinapsis_bertopic-1.0.0-py3-none-any.whl
Size 32.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c2f24e53703047bd5f3794e050ee353c3036a51fa2a639ad9e83fc5bc1fd53b2
BLAKE2b-256 checksum
How to use checksums
60bb0f94b9bfe5016f9dc45bb349b0835c9fed9f210afac6c985183df5ae919d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.17

Security for sinapsis-bertopic 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page