machine_learning.naive_bayes_text_classification
================================================

.. py:module:: machine_learning.naive_bayes_text_classification

.. autoapi-nested-parse::

   Naive Bayes text classification using a multinomial event model.

   The implementation in this module is intentionally educational and keeps the
   logic explicit: token counting, prior probabilities, and posterior scoring in
   log-space.

   References:
   - https://en.wikipedia.org/wiki/Naive_Bayes_classifier
   - https://scikit-learn.org/stable/modules/naive_bayes.html



Attributes
----------

.. autoapisummary::

   machine_learning.naive_bayes_text_classification.classifier


Classes
-------

.. autoapisummary::

   machine_learning.naive_bayes_text_classification.NaiveBayesTextClassifier


Functions
---------

.. autoapisummary::

   machine_learning.naive_bayes_text_classification.build_toy_dataset


Module Contents
---------------

.. py:class:: NaiveBayesTextClassifier(alpha: float = 1.0)

   Multinomial Naive Bayes classifier for short text documents.

   Args:
       alpha: Additive (Laplace) smoothing parameter. Must be greater than 0.

   >>> NaiveBayesTextClassifier(alpha=0)
   Traceback (most recent call last):
   ...
   ValueError: alpha must be greater than 0.


   .. py:method:: _tokenize(text: str) -> list[str]
      :staticmethod:


      Split text into lowercase alphanumeric tokens.

      >>> NaiveBayesTextClassifier._tokenize("Hello, NLP world!")
      ['hello', 'nlp', 'world']



   .. py:method:: fit(texts: list[str], labels: list[str]) -> None

      Fit the classifier from labeled training texts.

      >>> model = NaiveBayesTextClassifier()
      >>> model.fit(["cheap meds", "project meeting"], ["spam", "ham"])
      >>> sorted(model.classes_)
      ['ham', 'spam']

      >>> model.fit(["only one text"], ["ham", "spam"])
      Traceback (most recent call last):
      ...
      ValueError: texts and labels must have the same length.

      >>> model.fit([], [])
      Traceback (most recent call last):
      ...
      ValueError: training data must not be empty.



   .. py:method:: predict(text: str) -> str

      Predict the most likely class label for a text.

      >>> train_texts, train_labels = build_toy_dataset()
      >>> model = NaiveBayesTextClassifier(alpha=1.0)
      >>> model.fit(train_texts, train_labels)
      >>> model.predict("free cheap meds")
      'spam'
      >>> model.predict("project meeting schedule")
      'ham'



   .. py:method:: predict_proba(text: str) -> dict[str, float]

      Return posterior probabilities for every class.

      >>> train_texts, train_labels = build_toy_dataset()
      >>> model = NaiveBayesTextClassifier()
      >>> model.fit(train_texts, train_labels)
      >>> probs = model.predict_proba("cheap meds available now")
      >>> round(sum(probs.values()), 6)
      1.0
      >>> probs['spam'] > probs['ham']
      True

      An empty input text has no tokens, so predictions fall back to class priors.
      >>> empty_probs = model.predict_proba("")
      >>> round(empty_probs['spam'], 3), round(empty_probs['ham'], 3)
      (0.5, 0.5)

      >>> NaiveBayesTextClassifier().predict_proba("hello")
      Traceback (most recent call last):
      ...
      ValueError: model has not been fitted yet.



   .. py:attribute:: alpha
      :value: 1.0



   .. py:attribute:: class_document_counts_
      :type:  collections.Counter[str]


   .. py:attribute:: class_log_prior_
      :type:  dict[str, float]


   .. py:attribute:: class_token_counts_
      :type:  dict[str, collections.Counter[str]]


   .. py:attribute:: class_total_tokens_
      :type:  collections.Counter[str]


   .. py:attribute:: classes_
      :type:  list[str]
      :value: []



   .. py:attribute:: is_fitted_
      :value: False



   .. py:attribute:: vocabulary_
      :type:  set[str]


.. py:function:: build_toy_dataset() -> tuple[list[str], list[str]]

   Build a tiny text dataset for examples and quick local testing.

   >>> texts, labels = build_toy_dataset()
   >>> len(texts), len(labels)
   (6, 6)
   >>> sorted(set(labels))
   ['ham', 'spam']


.. py:data:: classifier