pdacek 0.1.0__py3-none-any.whl

pdacek/__init__.py

@@ -0,0 +1,116 @@
+"""pdacek - a plain, notebook-friendly NLP lab toolkit.
+
+Five self-contained experiments, each available three ways:
+
+* run it inline  ->  ``pdacek.p3()``
+* read the code   ->  ``print(pdacek.source(3))``
+* write it to disk -> ``pdacek.save(3)``
+
+The functions are also importable individually, e.g.
+``from pdacek import min_edit_distance``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .programs import PROGRAMS, numbers, run, source, titles
+from .programs.pl01_preprocessing import (
+    filtration,
+    preprocess,
+    stopword_removal,
+    stemming,
+    tokenization,
+    validation,
+)
+from .programs.pl02_ngrams import build_corpus, ngram_counts, ngram_probabilities
+from .programs.pl03_edit_distance import edit_table, med, min_edit_distance, trace_operations
+from .programs.pl04_parsing import Parser
+from .programs.pl05_naive_bayes import NaiveBayes
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "programs",
+    "run",
+    "source",
+    "save",
+    "p1",
+    "p2",
+    "p3",
+    "p4",
+    "p5",
+    # helpers
+    "tokenization",
+    "filtration",
+    "validation",
+    "stopword_removal",
+    "stemming",
+    "preprocess",
+    "build_corpus",
+    "ngram_counts",
+    "ngram_probabilities",
+    "edit_table",
+    "med",
+    "min_edit_distance",
+    "trace_operations",
+    "Parser",
+    "NaiveBayes",
+]
+
+
+def programs() -> Dict[int, str]:
+    """Return ``{number: title}`` for every bundled experiment."""
+    return titles()
+
+
+def save(number: int, directory: "str | Path" = ".") -> Path:
+    """Write a program listing to ``directory`` and return its path."""
+    program = PROGRAMS[int(number)]
+    target = Path(directory) / program.script_name
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(source(number), encoding="utf-8")
+    return target
+
+
+def _run_all() -> List[int]:
+    for number in numbers():
+        run(number)
+        print()
+    return numbers()
+
+
+def p1() -> None:
+    """Program 1 - text preprocessing pipeline."""
+    run(1)
+
+
+def p2() -> None:
+    """Program 2 - unigram, bigram, trigram probabilities."""
+    run(2)
+
+
+def p3() -> None:
+    """Program 3 - minimum edit distance."""
+    run(3)
+
+
+def p4() -> None:
+    """Program 4 - top-down and bottom-up parsing."""
+    run(4)
+
+
+def p5() -> None:
+    """Program 5 - add-one smoothed Naive Bayes."""
+    run(5)
+
+
+def __getattr__(name: str) -> Optional[object]:  # pragma: no cover - tiny shim
+    """Allow ``pdacek.p6`` style access to fail with a clear message."""
+    if name.startswith("p") and name[1:].isdigit():
+        raise AttributeError(
+            f"no program {name[1:]} in this release; available: {numbers()}"
+        )
+    raise AttributeError(f"module 'pdacek' has no attribute {name!r}")

pdacek/__main__.py

@@ -0,0 +1,6 @@
+"""Support ``python -m pdacek``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdacek/cli.py

@@ -0,0 +1,98 @@
+"""Command line entry point: ``pdacek 3``, ``pdacek --list``, ..."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__, numbers, programs, run, save, source
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pdacek",
+        description="Run the bundled NLP lab experiments without opening an editor.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  pdacek            run every experiment\n"
+            "  pdacek 3          run experiment 3\n"
+            "  pdacek p3         same thing\n"
+            "  pdacek 3 --source print the listing instead of running it\n"
+            "  pdacek 3 --save   write the listing to the current directory\n"
+        ),
+    )
+    parser.add_argument(
+        "program",
+        nargs="?",
+        help="experiment number (1-5) or name such as p3",
+    )
+    parser.add_argument("--list", "-l", action="store_true", help="list experiments and exit")
+    parser.add_argument("--source", "-s", action="store_true", help="print the listing")
+    parser.add_argument(
+        "--save",
+        nargs="?",
+        const=".",
+        metavar="DIR",
+        help="write the listing to DIR (default: current directory)",
+    )
+    parser.add_argument("--version", "-V", action="version", version=f"pdacek {__version__}")
+    return parser
+
+
+def _parse_number(raw: Optional[str]) -> Optional[int]:
+    if raw is None:
+        return None
+    cleaned = raw.strip().lower().lstrip("p").replace("program", "").strip(" _-")
+    try:
+        return int(cleaned)
+    except ValueError:
+        return None
+
+
+def list_programs() -> None:
+    print(f"pdacek {__version__} - bundled experiments\n")
+    for number, title in programs().items():
+        print(f"  {number}.  {title}")
+    print("\nRun one with: pdacek <number>")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.list:
+        list_programs()
+        return 0
+
+    number = _parse_number(args.program)
+    if args.program is not None and number is None:
+        print(f"error: could not read a program number from {args.program!r}", file=sys.stderr)
+        print(f"available: {', '.join(str(n) for n in numbers())}", file=sys.stderr)
+        return 2
+
+    try:
+        if number is None:
+            for n in numbers():
+                run(n)
+                print()
+            return 0
+
+        if args.save is not None:
+            path = save(number, args.save)
+            print(f"wrote {path}")
+            return 0
+
+        if args.source:
+            print(source(number))
+            return 0
+
+        run(number)
+        return 0
+    except KeyError as exc:
+        print(f"error: {exc.args[0]}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

pdacek/compat.py

@@ -0,0 +1,129 @@
+"""Shared helpers: tokenisation and NLTK corpus access with safe fallbacks.
+
+The lab machines this toolkit targets are often offline, so every helper here
+degrades to a pure-``re`` implementation instead of raising when an NLTK
+resource (``punkt``, ``stopwords``) has not been downloaded yet.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+try:  # NLTK is a declared dependency, but keep the package importable without it.
+    import nltk
+except ImportError:  # pragma: no cover - defensive
+    nltk = None  # type: ignore[assignment]
+
+__all__ = ["tokenize", "stopwords_en", "stemmer", "ensure_punkt", "nltk_available"]
+
+_TOKEN_RE = re.compile(r"[A-Za-z]+(?:'[A-Za-z]+)?|\d+|[^\sA-Za-z\d]")
+
+# Small built-in list, used only when the NLTK corpus is unavailable.
+_FALLBACK_STOPWORDS = frozenset(
+    """
+    a about above after again against all am an and any are as at be because been
+    before being below between both but by can did do does doing down during each
+    few for from further had has have having he her here hers herself him himself
+    his how i if in into is it its itself just me more most my myself no nor not
+    now of off on once only or other our ours ourselves out over own same she
+    should so some such than that the their theirs them themselves then there
+    these they this those through to too under until up very was we were what
+    when where which while who whom why will with you your yours yourself
+    yourselves
+    """.split()
+)
+
+
+def nltk_available() -> bool:
+    """Return ``True`` when NLTK can be imported."""
+    return nltk is not None
+
+
+def _resource_present(resource: str, package: str) -> bool:
+    if nltk is None:
+        return False
+    try:
+        nltk.data.find(f"{package}/{resource}")
+        return True
+    except LookupError:
+        return False
+
+
+def ensure_punkt() -> bool:
+    """Make sure a sentence/word tokenizer model exists; return availability.
+
+    NLTK 3.9 renamed the tokenizer data to ``punkt_tab``; both names are tried
+    and any download failure (offline machine) is swallowed on purpose.
+    """
+    if nltk is None:
+        return False
+    for resource in ("punkt", "punkt_tab"):
+        if _resource_present(resource, "tokenizers"):
+            return True
+        try:
+            nltk.download(resource, quiet=True)
+        except Exception:  # pragma: no cover - network/permission problems
+            pass
+        if _resource_present(resource, "tokenizers"):
+            return True
+    return False
+
+
+def tokenize(text: str) -> List[str]:
+    """Split ``text`` into word and punctuation tokens.
+
+    Uses NLTK's ``word_tokenize`` when the model is available, otherwise a
+    regex tokenizer that keeps punctuation as its own token, which is what the
+    filtration and script-validation steps in Program 1 need.
+    """
+    if ensure_punkt():
+        try:
+            return nltk.word_tokenize(text)  # type: ignore[union-attr]
+        except LookupError:  # pragma: no cover - stale resource index
+            pass
+    return _TOKEN_RE.findall(text)
+
+
+def stopwords_en() -> frozenset:
+    """Return the English stop-word set (NLTK corpus when available)."""
+    if nltk is not None:
+        try:
+            return frozenset(nltk.corpus.stopwords.words("english"))  # type: ignore[union-attr]
+        except LookupError:
+            try:
+                nltk.download("stopwords", quiet=True)  # type: ignore[union-attr]
+                return frozenset(nltk.corpus.stopwords.words("english"))  # type: ignore[union-attr]
+            except Exception:
+                pass
+    return _FALLBACK_STOPWORDS
+
+
+class _SimpleStemmer:
+    """Very small suffix stripper used when NLTK is not importable."""
+
+    _SUFFIXES = (
+        "ational", "ization", "iveness", "ingly", "edly", "ments",
+        "ing", "ies", "ied", "ed", "es", "s",
+    )
+
+    def stem(self, word: str) -> str:
+        low = word.lower()
+        for suffix in self._SUFFIXES:
+            if len(low) > len(suffix) + 2 and low.endswith(suffix):
+                if suffix == "ies":
+                    return low[: -len(suffix)] + "y"
+                return low[: -len(suffix)]
+        return low
+
+
+def stemmer():
+    """Return a Porter stemmer (NLTK) or a minimal fallback stemmer."""
+    if nltk is not None:
+        try:
+            from nltk.stem import PorterStemmer
+
+            return PorterStemmer()
+        except Exception:  # pragma: no cover
+            pass
+    return _SimpleStemmer()

pdacek/programs/__init__.py

@@ -0,0 +1,107 @@
+"""Program modules and the registry that maps numbers to them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from types import ModuleType
+from typing import Dict, List
+
+from . import (
+    pl01_preprocessing,
+    pl02_ngrams,
+    pl03_edit_distance,
+    pl04_parsing,
+    pl05_naive_bayes,
+)
+
+__all__ = ["Program", "PROGRAMS", "get", "run", "source", "titles", "numbers"]
+
+
+@dataclass(frozen=True)
+class Program:
+    """Metadata for one lab program."""
+
+    number: int
+    slug: str
+    title: str
+    module: ModuleType
+
+    @property
+    def script_name(self) -> str:
+        return f"{self.slug}.py"
+
+    def script(self) -> str:
+        """Return the standalone, paste-into-a-notebook listing."""
+        return (
+            resources.files("pdacek")
+            .joinpath("scripts", self.script_name)
+            .read_text(encoding="utf-8")
+        )
+
+    def run(self, *args, **kwargs) -> None:
+        self.module.main(*args, **kwargs)
+
+
+PROGRAMS: Dict[int, Program] = {
+    1: Program(
+        1,
+        "pl01_preprocessing",
+        "Text preprocessing: tokenisation, filtration, script validation, "
+        "stop-word removal, stemming",
+        pl01_preprocessing,
+    ),
+    2: Program(
+        2,
+        "pl02_ngrams",
+        "Unigram, bigram and trigram probability estimates",
+        pl02_ngrams,
+    ),
+    3: Program(
+        3,
+        "pl03_edit_distance",
+        "Minimum edit distance with test cases and a DP table",
+        pl03_edit_distance,
+    ),
+    4: Program(
+        4,
+        "pl04_parsing",
+        "Top-down and bottom-up parsing from a context-free grammar",
+        pl04_parsing,
+    ),
+    5: Program(
+        5,
+        "pl05_naive_bayes",
+        "Add-one smoothed Naive Bayes movie-review classification",
+        pl05_naive_bayes,
+    ),
+}
+
+
+def numbers() -> List[int]:
+    """Available program numbers, ascending."""
+    return sorted(PROGRAMS)
+
+
+def titles() -> Dict[int, str]:
+    """Mapping of program number to one-line title."""
+    return {n: p.title for n, p in sorted(PROGRAMS.items())}
+
+
+def get(number: int) -> Program:
+    """Look up a program by number, with a helpful error message."""
+    try:
+        return PROGRAMS[int(number)]
+    except (KeyError, TypeError, ValueError):
+        available = ", ".join(str(n) for n in numbers())
+        raise KeyError(f"unknown program {number!r}; available: {available}") from None
+
+
+def run(number: int) -> None:
+    """Execute one program and print its output."""
+    get(number).run()
+
+
+def source(number: int) -> str:
+    """Return the standalone script for one program."""
+    return get(number).script()

pdacek/programs/pl01_preprocessing.py

@@ -0,0 +1,80 @@
+"""Program 1 - text preprocessing pipeline.
+
+Tokenisation -> filtration -> script validation -> stop-word removal ->
+stemming, exposed as small composable steps plus a one-call ``preprocess``.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List
+
+from ..compat import stemmer, stopwords_en, tokenize
+
+SAMPLE_TEXT = (
+    "Natural Language Processing is a fascinating field of AI.\n"
+    "It involves processing human languages, like English!"
+)
+
+_NON_ALPHA = re.compile(r"[^a-zA-Z]")
+_ALPHA_ONLY = re.compile(r"^[a-zA-Z]+$")
+
+
+def tokenization(text: str = SAMPLE_TEXT) -> List[str]:
+    """Step 1 - split raw text into tokens, punctuation included."""
+    return tokenize(text)
+
+
+def filtration(tokens: List[str]) -> List[str]:
+    """Step 2 - drop non-alphabetic characters, then drop empty strings."""
+    stripped = [_NON_ALPHA.sub("", w) for w in tokens]
+    return [w for w in stripped if w]
+
+
+def validation(tokens: List[str]) -> List[str]:
+    """Step 3 - keep only tokens that are pure ASCII English letters."""
+    return [w for w in tokens if _ALPHA_ONLY.match(w)]
+
+
+def stopword_removal(tokens: List[str]) -> List[str]:
+    """Step 4 - remove English stop words (case-insensitive)."""
+    stop = stopwords_en()
+    return [w for w in tokens if w.lower() not in stop]
+
+
+def stemming(tokens: List[str]) -> List[str]:
+    """Step 5 - Porter stemming."""
+    porter = stemmer()
+    return [porter.stem(w) for w in tokens]
+
+
+def preprocess(text: str = SAMPLE_TEXT) -> Dict[str, List[str]]:
+    """Run the full pipeline and return every intermediate stage."""
+    tokens = tokenization(text)
+    filtered = filtration(tokens)
+    validated = validation(filtered)
+    cleaned = stopword_removal(validated)
+    stemmed = stemming(cleaned)
+    return {
+        "tokens": tokens,
+        "filtered": filtered,
+        "validated": validated,
+        "cleaned": cleaned,
+        "stemmed": stemmed,
+    }
+
+
+def main(text: str = SAMPLE_TEXT) -> None:
+    """Reproduce the lab-sheet output."""
+    stages = preprocess(text)
+
+    print("Original Text:\n", text)
+    print("\nTokens:\n", stages["tokens"])
+    print("\nFiltered Tokens:\n", stages["filtered"])
+    print("\nValidated Tokens (English Only):\n", stages["validated"])
+    print("\nTokens after Stop Word Removal:\n", stages["cleaned"])
+    print("\nStemmed Tokens:\n", stages["stemmed"])
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pdacek/programs/pl02_ngrams.py

@@ -0,0 +1,66 @@
+"""Program 2 - unigram, bigram and trigram probability estimates.
+
+Unigram probabilities use maximum likelihood over the whole corpus; higher
+orders use the conditional estimate ``C(w1..wn) / C(w1..wn-1)``.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Dict, Iterable, List, Sequence, Tuple
+
+from ..compat import tokenize
+
+SENTENCES: List[str] = [
+    "The quick brown fox jumps over the lazy dog",
+    "The dog barks at the fox",
+    "The fox is quick and the dog is lazy",
+    "The quick dog jumps over the lazy fox",
+]
+
+
+def _ngrams(sequence: Sequence[str], n: int) -> Iterable[Tuple[str, ...]]:
+    if n <= 0:
+        raise ValueError("n must be >= 1")
+    for i in range(len(sequence) - n + 1):
+        yield tuple(sequence[i : i + n])
+
+
+def build_corpus(sentences: Sequence[str] = SENTENCES) -> List[List[str]]:
+    """Lower-case and tokenise every sentence."""
+    return [tokenize(s.lower()) for s in sentences]
+
+
+def ngram_counts(corpus: Sequence[Sequence[str]], n: int) -> Counter:
+    """Count every n-gram in the corpus."""
+    return Counter(g for sentence in corpus for g in _ngrams(sentence, n))
+
+
+def ngram_probabilities(corpus: Sequence[Sequence[str]], n: int) -> Dict[Tuple[str, ...], float]:
+    """Return ``{ngram: probability}`` for the requested order ``n``."""
+    counts = ngram_counts(corpus, n)
+    if n == 1:
+        total = sum(counts.values())
+        return {gram: count / total for gram, count in counts.items()}
+
+    previous = ngram_counts(corpus, n - 1)
+    probabilities: Dict[Tuple[str, ...], float] = {}
+    for gram, count in counts.items():
+        denominator = previous.get(gram[:-1], 0)
+        if denominator:
+            probabilities[gram] = count / denominator
+    return probabilities
+
+
+def main(sentences: Sequence[str] = SENTENCES) -> None:
+    """Reproduce the lab-sheet output for n = 1, 2, 3."""
+    corpus = build_corpus(sentences)
+    for n in (1, 2, 3):
+        probabilities = ngram_probabilities(corpus, n)
+        print(f"\n{n}-Gram Probabilities:")
+        for gram, probability in probabilities.items():
+            print(f"{' '.join(gram)}: {probability:.4f}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pdacek/programs/pl03_edit_distance.py

@@ -0,0 +1,89 @@
+"""Program 3 - minimum edit distance (Levenshtein, unit cost).
+
+The dynamic-programming table is kept so it can be printed like the lab sheet.
+"""
+
+from __future__ import annotations
+
+from typing import List, Sequence, Tuple
+
+TESTS: List[Tuple[str, str]] = [
+    ("kitten", "sitting"),
+    ("flaw", "lawn"),
+    ("intention", "execution"),
+    ("apple", "aple"),
+    ("", "hello"),
+    ("hello", ""),
+]
+
+
+def edit_table(a: str, b: str) -> List[List[int]]:
+    """Return the full ``(len(a)+1) x (len(b)+1)`` distance matrix."""
+    m, n = len(a), len(b)
+    dp = [[0] * (n + 1) for _ in range(m + 1)]
+
+    for i in range(m + 1):
+        dp[i][0] = i
+    for j in range(n + 1):
+        dp[0][j] = j
+
+    for i in range(1, m + 1):
+        for j in range(1, n + 1):
+            if a[i - 1] == b[j - 1]:
+                dp[i][j] = dp[i - 1][j - 1]
+            else:
+                dp[i][j] = 1 + min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    return dp
+
+
+def min_edit_distance(a: str, b: str) -> int:
+    """Levenshtein distance between ``a`` and ``b``."""
+    return edit_table(a, b)[len(a)][len(b)]
+
+
+def med(a: str, b: str) -> Tuple[int, List[List[int]]]:
+    """Lab-compatible wrapper returning ``(distance, table)``."""
+    dp = edit_table(a, b)
+    return dp[len(a)][len(b)], dp
+
+
+def display(dp: Sequence[Sequence[int]], a: str, b: str) -> None:
+    """Print the matrix with source/target letters as headers."""
+    print("\nEdit Distance Table:")
+    print(" " + " ".join("#" + c for c in " " + b))
+    for i, row in enumerate(dp):
+        print(("#" if i == 0 else a[i - 1]), *row)
+
+
+def trace_operations(a: str, b: str) -> List[str]:
+    """Backtrace the table into edit operations (useful for the viva)."""
+    dp = edit_table(a, b)
+    i, j = len(a), len(b)
+    operations: List[str] = []
+    while i > 0 or j > 0:
+        if i > 0 and j > 0 and a[i - 1] == b[j - 1] and dp[i][j] == dp[i - 1][j - 1]:
+            operations.append(f"keep '{a[i - 1]}'")
+            i, j = i - 1, j - 1
+        elif i > 0 and j > 0 and dp[i][j] == dp[i - 1][j - 1] + 1:
+            operations.append(f"substitute '{a[i - 1]}' -> '{b[j - 1]}'")
+            i, j = i - 1, j - 1
+        elif i > 0 and dp[i][j] == dp[i - 1][j] + 1:
+            operations.append(f"delete '{a[i - 1]}'")
+            i -= 1
+        else:
+            operations.append(f"insert '{b[j - 1]}'")
+            j -= 1
+    return list(reversed(operations))
+
+
+def main(tests: Sequence[Tuple[str, str]] = TESTS) -> None:
+    """Reproduce the lab-sheet output."""
+    for a, b in tests:
+        distance, dp = med(a, b)
+        print(f"\nComparing: '{a}' -> '{b}'")
+        print("Minimum Edit Distance:", distance)
+        display(dp, a, b)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pdacek/programs/pl04_parsing.py

@@ -0,0 +1,150 @@
+"""Program 4 - top-down and bottom-up parsing from a context-free grammar.
+
+``Parser`` takes the grammar as ``(lhs, rhs)`` pairs where ``rhs`` is a list of
+symbols; symbols that never appear on a left-hand side are terminals.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Sequence, Tuple
+
+Grammar = Sequence[Tuple[str, Sequence[str]]]
+
+GRAMMAR: List[Tuple[str, List[str]]] = [
+    ("S", ["NP", "VP"]),
+    ("NP", ["Det", "N"]),
+    ("VP", ["V", "NP"]),
+    ("VP", ["V"]),
+    ("Det", ["a"]),
+    ("Det", ["the"]),
+    ("N", ["cat"]),
+    ("N", ["dog"]),
+    ("V", ["chases"]),
+    ("V", ["eats"]),
+]
+
+SENTENCE: List[str] = ["the", "cat", "chases", "a", "dog"]
+
+
+class Parser:
+    """A tiny CFG parser with both search directions."""
+
+    def __init__(self, grammar: Grammar, start: str = "S") -> None:
+        self.rules: Dict[str, List[List[str]]] = {}
+        for lhs, rhs in grammar:
+            self.rules.setdefault(lhs, []).append(list(rhs))
+        self.start = start
+
+    # ------------------------------------------------------------------ top-down
+    def top_down_parse(self, sentence: Sequence[str]) -> Optional[List[str]]:
+        """Leftmost recursive-descent expansion with backtracking.
+
+        Returns the resulting stack (``[start]``) on success, ``None`` on
+        failure - same contract as the lab sheet, but actually implemented.
+        """
+        self._tokens = list(sentence)
+        self._pos = 0
+        if not self._expand(self.start):
+            return None
+        if self._pos != len(self._tokens):
+            return None
+        return [self.start]
+
+    def _expand(self, symbol: str) -> bool:
+        if symbol not in self.rules:  # terminal
+            if self._pos < len(self._tokens) and self._tokens[self._pos] == symbol:
+                self._pos += 1
+                return True
+            return False
+
+        for rhs in self.rules[symbol]:
+            mark = self._pos
+            matched = True
+            for child in rhs:
+                if not self._expand(child):
+                    matched = False
+                    break
+            if matched:
+                return True
+            self._pos = mark
+        return False
+
+    # ------------------------------------------------------------------ bottom-up
+    def _rule_kinds(self):
+        """Split the grammar into lexical, unary and binary rules (CNF view)."""
+        lexical: Dict[str, List[str]] = {}
+        unary: List[Tuple[str, str]] = []
+        binary: List[Tuple[str, str, str]] = []
+        for lhs, rhs_list in self.rules.items():
+            for rhs in rhs_list:
+                if len(rhs) == 1 and rhs[0] not in self.rules:
+                    lexical.setdefault(rhs[0], []).append(lhs)
+                elif len(rhs) == 1:
+                    unary.append((lhs, rhs[0]))
+                elif len(rhs) == 2:
+                    binary.append((lhs, rhs[0], rhs[1]))
+                else:
+                    raise ValueError(
+                        f"rule {lhs} -> {' '.join(rhs)} is not supported by the "
+                        "chart parser; split it into binary rules"
+                    )
+        return lexical, unary, binary
+
+    def bottom_up_parse(self, sentence: Sequence[str]) -> List[str]:
+        """Bottom-up chart (CYK-style) parse over spans of the sentence.
+
+        Terminals are lifted to their preterminals first, then spans of growing
+        length are combined - the standard bottom-up direction. Returns
+        ``['S']`` when the whole sentence reduces to the start symbol,
+        otherwise the symbols left at the top of the chart.
+        """
+        tokens = list(sentence)
+        if not tokens:
+            return []
+
+        lexical, unary, binary = self._rule_kinds()
+
+        def close(cell: set) -> set:
+            changed = True
+            while changed:
+                changed = False
+                for parent, child in unary:
+                    if child in cell and parent not in cell:
+                        cell.add(parent)
+                        changed = True
+            return cell
+
+        chart: Dict[Tuple[int, int], set] = {}
+        for index, token in enumerate(tokens):
+            chart[(index, index + 1)] = close(set(lexical.get(token, ())))
+
+        for length in range(2, len(tokens) + 1):
+            for start in range(0, len(tokens) - length + 1):
+                end = start + length
+                cell: set = set()
+                for split in range(start + 1, end):
+                    left = chart[(start, split)]
+                    right = chart[(split, end)]
+                    for parent, first, second in binary:
+                        if first in left and second in right:
+                            cell.add(parent)
+                chart[(start, end)] = close(cell)
+
+        top = chart.get((0, len(tokens)), set())
+        if self.start in top:
+            return [self.start]
+        return sorted(top) if top else tokens
+
+
+def main(
+    grammar: Grammar = GRAMMAR,
+    sentence: Sequence[str] = SENTENCE,
+) -> None:
+    """Reproduce the lab-sheet output."""
+    parser = Parser(grammar)
+    print("Top-Down Parse Result:", parser.top_down_parse(sentence))
+    print("Bottom-Up Parse Result:", parser.bottom_up_parse(sentence))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pdacek/programs/pl05_naive_bayes.py

@@ -0,0 +1,95 @@
+"""Program 5 - add-one smoothed Naive Bayes movie-review classifier.
+
+Posteriors are unnormalised class scores (prior x product of likelihoods),
+which is all that is needed to compare classes.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Dict, Iterable, List, Sequence, Tuple
+
+REVIEWS: List[Tuple[str, str]] = [
+    ("fun, couple, love, love", "comedy"),
+    ("fast, furious, shoot", "action"),
+    ("couple, fly, fast, fun", "comedy"),
+    ("furious, shoot, shoot, fun", "action"),
+    ("fly, fast, shoot, love", "action"),
+]
+
+DOCUMENT = "fast, couple, shoot, fly"
+SEPARATOR = ", "
+
+
+class NaiveBayes:
+    """Multinomial Naive Bayes with add-one (Laplace) smoothing."""
+
+    def __init__(self, alpha: float = 1.0) -> None:
+        self.alpha = alpha
+        self.counts: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
+        self.class_totals: Dict[str, int] = {}
+        self.priors: Dict[str, float] = {}
+        self.vocabulary: set = set()
+
+    def fit(self, rows: Iterable[Tuple[str, str]], separator: str = SEPARATOR) -> "NaiveBayes":
+        classes: Dict[str, int] = defaultdict(int)
+        for review, label in rows:
+            classes[label] += 1
+            for word in review.split(separator):
+                word = word.strip()
+                if not word:
+                    continue
+                self.counts[label][word] += 1
+                self.vocabulary.add(word)
+
+        total_documents = sum(classes.values())
+        self.priors = {label: n / total_documents for label, n in classes.items()}
+        self.class_totals = {label: sum(words.values()) for label, words in self.counts.items()}
+        return self
+
+    @property
+    def vocabulary_size(self) -> int:
+        return len(self.vocabulary)
+
+    def likelihood(self, label: str, word: str) -> float:
+        """P(word | label) with add-one smoothing."""
+        numerator = self.counts[label][word] + self.alpha
+        denominator = self.class_totals.get(label, 0) + self.alpha * self.vocabulary_size
+        return numerator / denominator
+
+    def scores(self, words: Sequence[str]) -> Dict[str, float]:
+        """Unnormalised posterior score per class."""
+        result: Dict[str, float] = {}
+        for label, prior in self.priors.items():
+            score = prior
+            for word in words:
+                score *= self.likelihood(label, word)
+            result[label] = score
+        return result
+
+    def predict(self, words: Sequence[str]) -> str:
+        scores = self.scores(words)
+        return max(scores, key=scores.get)  # type: ignore[arg-type]
+
+
+def main(rows: Sequence[Tuple[str, str]] = REVIEWS, document: str = DOCUMENT) -> None:
+    """Reproduce the lab-sheet output (including the capitalised labels)."""
+    model = NaiveBayes().fit(rows)
+    words = [w for w in document.split(SEPARATOR) if w]
+
+    comedy = model.priors.get("comedy", 0.0)
+    action = model.priors.get("action", 0.0)
+    for word in words:
+        comedy *= model.likelihood("comedy", word)
+        action *= model.likelihood("action", word)
+
+    print("Posterior for comedy:", comedy)
+    print("Posterior for action:", action)
+    print(
+        "\nThe most likely class for the document is:",
+        "Comedy" if comedy > action else "Action",
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pdacek/scripts/pl01_preprocessing.py

@@ -0,0 +1,62 @@
+"""Program 1 - text preprocessing: tokenisation, filtration, script
+validation, stop-word removal and stemming.
+
+Self-contained listing: paste it into any notebook or run it directly with
+``python pl01_preprocessing.py``. No download is attempted unless NLTK is
+already installed and the corpus files are missing.
+"""
+
+import re
+
+try:
+    import nltk
+    from nltk.corpus import stopwords
+    from nltk.stem import PorterStemmer
+    from nltk.tokenize import word_tokenize
+except ImportError:  # keep working without NLTK
+    nltk = None
+
+text = """Natural Language Processing is a fascinating field of AI.
+It involves processing human languages, like English!"""
+
+print("Original Text:\n", text)
+
+# 1. Tokenization
+if nltk is not None:
+    try:
+        tokens = word_tokenize(text)
+    except LookupError:
+        for resource in ("punkt", "punkt_tab"):
+            nltk.download(resource, quiet=True)
+        tokens = word_tokenize(text)
+else:
+    tokens = re.findall(r"[A-Za-z]+(?:'[A-Za-z]+)?|\d+|[^\sA-Za-z\d]", text)
+
+print("\nTokens:\n", tokens)
+
+# 2. Filtration
+filtered = [re.sub(r"[^a-zA-Z]", "", w) for w in tokens]
+filtered = [w for w in filtered if w]
+print("\nFiltered Tokens:\n", filtered)
+
+# 3. Script Validation
+validated = [w for w in filtered if re.match(r"^[a-zA-Z]+$", w)]
+print("\nValidated Tokens (English Only):\n", validated)
+
+# 4. Stop Word Removal
+if nltk is not None:
+    try:
+        english_stopwords = stopwords.words("english")
+    except LookupError:
+        nltk.download("stopwords", quiet=True)
+        english_stopwords = stopwords.words("english")
+else:
+    english_stopwords = ["a", "an", "the", "is", "of", "and", "it", "like", "in", "to"]
+
+cleaned = [w for w in validated if w.lower() not in english_stopwords]
+print("\nTokens after Stop Word Removal:\n", cleaned)
+
+# 5. Stemming
+stemmer = PorterStemmer() if nltk is not None else None
+stemmed = [stemmer.stem(w) if stemmer else w.lower() for w in cleaned]
+print("\nStemmed Tokens:\n", stemmed)

pdacek/scripts/pl02_ngrams.py

@@ -0,0 +1,46 @@
+"""Program 2 - unigram, bigram and trigram probability estimates.
+
+Self-contained listing: ``python pl02_ngrams.py``.
+"""
+
+import re
+from collections import Counter
+
+try:
+    from nltk.tokenize import word_tokenize
+except ImportError:  # regex fallback below
+    word_tokenize = None
+
+sentences = [
+    "The quick brown fox jumps over the lazy dog",
+    "The dog barks at the fox",
+    "The fox is quick and the dog is lazy",
+    "The quick dog jumps over the lazy fox",
+]
+
+
+def tokenize(sentence):
+    if word_tokenize is not None:
+        try:
+            return word_tokenize(sentence.lower())
+        except LookupError:
+            pass
+    return re.findall(r"[a-z]+(?:'[a-z]+)?|[^\sa-z\d]", sentence.lower())
+
+
+def ngrams(sequence, n):
+    return [tuple(sequence[i:i + n]) for i in range(len(sequence) - n + 1)]
+
+
+# Tokenization
+words = [tokenize(s) for s in sentences]
+
+# N-gram probabilities
+for n in [1, 2, 3]:
+    count = Counter(g for w in words for g in ngrams(w, n))
+    prev = Counter(g for w in words for g in ngrams(w, n - 1)) if n > 1 else None
+
+    print(f"\n{n}-Gram Probabilities:")
+    for g, c in count.items():
+        p = c / (sum(count.values()) if n == 1 else prev[g[:-1]])
+        print(f"{' '.join(g)}: {p:.4f}")

pdacek/scripts/pl03_edit_distance.py

@@ -0,0 +1,47 @@
+"""Program 3 - minimum edit distance with the dynamic-programming table.
+
+Self-contained listing: ``python pl03_edit_distance.py``.
+"""
+
+
+def med(a, b):
+    """Return (minimum edit distance, DP table)."""
+    m, n = len(a), len(b)
+    dp = [[0] * (n + 1) for _ in range(m + 1)]
+
+    for i in range(m + 1):
+        dp[i][0] = i
+    for j in range(n + 1):
+        dp[0][j] = j
+
+    for i in range(1, m + 1):
+        for j in range(1, n + 1):
+            if a[i - 1] == b[j - 1]:
+                dp[i][j] = dp[i - 1][j - 1]
+            else:
+                dp[i][j] = 1 + min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    return dp[m][n], dp
+
+
+def display(dp, a, b):
+    print("\nEdit Distance Table:")
+    print(" " + " ".join("#" + c for c in " " + b))
+    for i, row in enumerate(dp):
+        print(("#" if i == 0 else a[i - 1]), *row)
+
+
+# Test cases
+tests = [
+    ("kitten", "sitting"),
+    ("flaw", "lawn"),
+    ("intention", "execution"),
+    ("apple", "aple"),
+    ("", "hello"),
+    ("hello", ""),
+]
+
+for a, b in tests:
+    distance, dp = med(a, b)
+    print(f"\nComparing: '{a}' -> '{b}'")
+    print("Minimum Edit Distance:", distance)
+    display(dp, a, b)

pdacek/scripts/pl04_parsing.py

@@ -0,0 +1,95 @@
+"""Program 4 - top-down and bottom-up parsing from a context-free grammar.
+
+Self-contained listing: ``python pl04_parsing.py``.
+"""
+
+
+class Parser:
+    def __init__(self, grammar):
+        self.rules = {}
+        for lhs, rhs in grammar:
+            self.rules.setdefault(lhs, []).append(rhs)
+
+    # ---- top-down: recursive descent with backtracking ---------------------
+    def top_down_parse(self, sentence):
+        self.tokens = list(sentence)
+        self.pos = 0
+        if not self._expand("S"):
+            return None
+        return ["S"] if self.pos == len(self.tokens) else None
+
+    def _expand(self, symbol):
+        if symbol not in self.rules:  # terminal
+            if self.pos < len(self.tokens) and self.tokens[self.pos] == symbol:
+                self.pos += 1
+                return True
+            return False
+        for rhs in self.rules[symbol]:
+            mark = self.pos
+            if all(self._expand(child) for child in rhs):
+                return True
+            self.pos = mark
+        return False
+
+    # ---- bottom-up: chart (CYK-style) parse over spans ---------------------
+    def bottom_up_parse(self, sentence, start="S"):
+        tokens = list(sentence)
+        if not tokens:
+            return []
+
+        lexical, unary, binary = {}, [], []
+        for lhs, rhs_list in self.rules.items():
+            for rhs in rhs_list:
+                if len(rhs) == 1 and rhs[0] not in self.rules:
+                    lexical.setdefault(rhs[0], []).append(lhs)
+                elif len(rhs) == 1:
+                    unary.append((lhs, rhs[0]))
+                elif len(rhs) == 2:
+                    binary.append((lhs, rhs[0], rhs[1]))
+                else:
+                    raise ValueError(f"rule {lhs} -> {' '.join(rhs)} needs splitting")
+
+        def close(cell):
+            changed = True
+            while changed:
+                changed = False
+                for parent, child in unary:
+                    if child in cell and parent not in cell:
+                        cell.add(parent)
+                        changed = True
+            return cell
+
+        chart = {}
+        for i, token in enumerate(tokens):
+            chart[(i, i + 1)] = close(set(lexical.get(token, ())))
+
+        for length in range(2, len(tokens) + 1):
+            for s in range(0, len(tokens) - length + 1):
+                e = s + length
+                cell = set()
+                for split in range(s + 1, e):
+                    left, right = chart[(s, split)], chart[(split, e)]
+                    for parent, first, second in binary:
+                        if first in left and second in right:
+                            cell.add(parent)
+                chart[(s, e)] = close(cell)
+
+        top = chart.get((0, len(tokens)), set())
+        return [start] if start in top else (sorted(top) or tokens)
+
+
+grammar = [
+    ("S", ["NP", "VP"]),
+    ("NP", ["Det", "N"]),
+    ("VP", ["V", "NP"]),
+    ("VP", ["V"]),
+    ("Det", ["a"]), ("Det", ["the"]),
+    ("N", ["cat"]), ("N", ["dog"]),
+    ("V", ["chases"]), ("V", ["eats"]),
+]
+
+parser = Parser(grammar)
+sentence = ["the", "cat", "chases", "a", "dog"]
+
+print("Top-Down Parse Result:", parser.top_down_parse(sentence))
+print("Bottom-Up Parse Result:", parser.bottom_up_parse(sentence))

pdacek/scripts/pl05_naive_bayes.py

@@ -0,0 +1,53 @@
+"""Program 5 - add-one smoothed Naive Bayes movie-review classifier.
+
+Self-contained listing: ``python pl05_naive_bayes.py``.
+"""
+
+from collections import defaultdict
+
+reviews = [
+    ("fun, couple, love, love", "comedy"),
+    ("fast, furious, shoot", "action"),
+    ("couple, fly, fast, fun", "comedy"),
+    ("furious, shoot, shoot, fun", "action"),
+    ("fly, fast, shoot, love", "action"),
+]
+
+counts = defaultdict(lambda: defaultdict(int))
+classes = defaultdict(int)
+vocab = set()
+
+# Count words
+for review, label in reviews:
+    classes[label] += 1
+    for word in review.split(", "):
+        counts[label][word] += 1
+        vocab.add(word)
+
+V = len(vocab)
+
+# Prior probabilities
+total = sum(classes.values())
+prior = {c: classes[c] / total for c in classes}
+
+
+# Likelihood with Add-1 smoothing
+def likelihood(c, w):
+    total_words = sum(counts[c].values())
+    return (counts[c][w] + 1) / (total_words + V)
+
+
+# Classify new document
+words = "fast, couple, shoot, fly".split(", ")
+comedy = prior["comedy"]
+action = prior["action"]
+
+for w in words:
+    comedy *= likelihood("comedy", w)
+    action *= likelihood("action", w)
+
+print("Posterior for comedy:", comedy)
+print("Posterior for action:", action)
+
+print("\nThe most likely class for the document is:",
+      "Comedy" if comedy > action else "Action")

pdacek-0.1.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: pdacek
+Version: 0.1.0
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: nltk>=3.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+import pdacek
+pdacek.p1()          # preprocessing pipeline
+pdacek.p2()          # n-gram probabilities
+pdacek.p3()          # minimum edit distance
+pdacek.p4()          # top-down / bottom-up parsing
+pdacek.p5()          # Naive Bayes

pdacek-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+pdacek/__init__.py,sha256=_wbnmUGgNfrfkyUdSd4bmecd6v-Lju8zrsvpcIr4Az4,2794
+pdacek/__main__.py,sha256=YPR_b19rJwqt63H1haKe7o3Uq-xFsfBxl4jbVSOm-vQ,116
+pdacek/cli.py,sha256=ZzzNpzYGBvpPKL0iy1BQgRPqqaTcVZNY_1sjK53v2jQ,2961
+pdacek/compat.py,sha256=C7p5TDJIWD1dbFDzDmCn__KIj3nvCkg2tiHddkDzgqY,4484
+pdacek/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdacek/programs/__init__.py,sha256=SW-nyRpS1FFVnhAK00XyOq2eNYwRrd4v0HOoy1G5de8,2676
+pdacek/programs/pl01_preprocessing.py,sha256=VeZSboQRdXyUK5F2BT_jFFVMaw2KwF1yTZw1W4kyxdQ,2435
+pdacek/programs/pl02_ngrams.py,sha256=ziMDozsuZoPWS1cZS6qvPet-oY5eoUqv2n-4ql614oc,2228
+pdacek/programs/pl03_edit_distance.py,sha256=vjO9W88TjYswhC9WbGNYn93vlGjCzw1usoIGgs2hzRI,2766
+pdacek/programs/pl04_parsing.py,sha256=KNsCI2F3hdzkAp4FSrK_4Ryp4xJ4K0_oeW6h04tstU4,5338
+pdacek/programs/pl05_naive_bayes.py,sha256=amWnfqDele05HcTBktsuVlrLBWtANHnslHmlfU92T_o,3375
+pdacek/scripts/pl01_preprocessing.py,sha256=_nZAAqaCzdAOVPYBoHlnZ2dnxYoNxeGHDLQFsKOEXt0,1986
+pdacek/scripts/pl02_ngrams.py,sha256=XWURpSWHQN5DPudpknmGFIEv0jsxmUC5SPrDqlvHr0A,1242
+pdacek/scripts/pl03_edit_distance.py,sha256=6TcDtqNgO3Wvs6F1oTZS3ETlijEP_azbosjDGpfl0D0,1169
+pdacek/scripts/pl04_parsing.py,sha256=bPtmdimyIuJ2qUbcptbS0-FGQbaN-MfWNS-9eQv_EM4,3279
+pdacek/scripts/pl05_naive_bayes.py,sha256=6sv0qnQGn9PEgOiiHPiMx9GLceabakbvRleDXq4qV80,1313
+pdacek-0.1.0.dist-info/METADATA,sha256=lVYrV2xqM_aEonQJ6KZ1baOG1P28RizQYp4QApx5EjE,557
+pdacek-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pdacek-0.1.0.dist-info/entry_points.txt,sha256=iQxygOdFfe7fB9ZW3YrAP3fZzjExu0W9dOe0fu4WOl4,43
+pdacek-0.1.0.dist-info/licenses/LICENSE,sha256=IeH_S9lC7iNb5q7sKLWDAI5qviV1-urlfIcisLMXAyw,1071
+pdacek-0.1.0.dist-info/RECORD,,

pdacek-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pdacek-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdacek = pdacek.cli:main

pdacek-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sohel Havaldar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.