pybox-nlp 0.1.0__py3-none-any.whl

pybox/__init__.py

@@ -0,0 +1,57 @@
+"""
+pybox: Bundles 11 Python programs into one installable package with source inspection and export capabilities.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+from .core import Program
+
+__version__ = "0.1.0"
+
+PROGRAM_NAMES: Tuple[str, ...] = (
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+    "eleven",
+)
+
+PROGRAMS: Dict[str, Program] = {name: Program(name) for name in PROGRAM_NAMES}
+
+one: Program = PROGRAMS["one"]
+two: Program = PROGRAMS["two"]
+three: Program = PROGRAMS["three"]
+four: Program = PROGRAMS["four"]
+five: Program = PROGRAMS["five"]
+six: Program = PROGRAMS["six"]
+seven: Program = PROGRAMS["seven"]
+eight: Program = PROGRAMS["eight"]
+nine: Program = PROGRAMS["nine"]
+ten: Program = PROGRAMS["ten"]
+eleven: Program = PROGRAMS["eleven"]
+
+__all__ = [
+    "Program",
+    "PROGRAM_NAMES",
+    "PROGRAMS",
+    "__version__",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+    "eleven",
+]

pybox/core.py

@@ -0,0 +1,163 @@
+"""
+Core implementation of the PyBox Program abstraction.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import tempfile
+from typing import Union
+
+
+class Program:
+    """
+    Represents an individual bundled Python program within pybox.
+
+    Provides safe inspection of original source code without executing it,
+    as well as export functionality to save standalone .py files.
+    """
+
+    def __init__(self, identifier: str) -> None:
+        if not identifier or not isinstance(identifier, str):
+            raise ValueError(f"Program identifier must be a non-empty string, got: {identifier!r}")
+        self._identifier: str = identifier
+        self._filename: str = f"{identifier}.py"
+
+    @property
+    def identifier(self) -> str:
+        """The identifier of this program (e.g., 'one', 'two')."""
+        return self._identifier
+
+    @property
+    def filename(self) -> str:
+        """The default filename for this program (e.g., 'one.py')."""
+        return self._filename
+
+    def _read_source(self) -> str:
+        """
+        Locate and read the packaged source file using UTF-8 encoding.
+
+        Raises:
+            FileNotFoundError: If the source file cannot be found in the package.
+            OSError: If an error occurs while reading the file.
+        """
+        # Try importlib.resources (Python 3.9+)
+        try:
+            from importlib import resources
+            traversable = resources.files("pybox.programs").joinpath(self._filename)
+            # traversable.is_file() might raise AttributeError on older backports, so check safely
+            try:
+                is_file = traversable.is_file()
+            except AttributeError:
+                is_file = True
+            
+            if is_file:
+                return traversable.read_text(encoding="utf-8")
+        except Exception:
+            pass
+
+        # Fallback to direct filesystem resolution relative to this file
+        fallback_path = Path(__file__).resolve().parent / "programs" / self._filename
+        if fallback_path.is_file():
+            return fallback_path.read_text(encoding="utf-8")
+
+        raise FileNotFoundError(
+            f"Packaged source file for program '{self._identifier}' "
+            f"('{self._filename}') was not found in pybox.programs."
+        )
+
+    @property
+    def code(self) -> str:
+        """The complete original source code of the program as a string."""
+        return self._read_source()
+
+    def __str__(self) -> str:
+        """Return the complete source code when the program is converted to str or printed."""
+        return self.code
+
+    def __repr__(self) -> str:
+        """Return a helpful developer representation."""
+        return f"Program({self._identifier!r})"
+
+    def save(
+        self,
+        destination: Union[str, Path, None] = None,
+        *,
+        overwrite: bool = False,
+    ) -> Path:
+        """
+        Export the program's source code into a standalone Python file.
+
+        Args:
+            destination: Optional file path or directory. Defaults to '<identifier>.py'
+                         in the current working directory.
+            overwrite: If False (default), raises FileExistsError if the destination exists.
+                       If True, safely replaces the destination file.
+
+        Returns:
+            The resolved Path to the saved Python file.
+
+        Raises:
+            FileExistsError: If destination exists and overwrite is False.
+            IsADirectoryError: If destination is an existing directory and no filename is given.
+            OSError: If an error occurs creating directories or writing the file.
+        """
+        source_code = self.code
+
+        if destination is None:
+            dest_path = Path.cwd() / self._filename
+        else:
+            dest_path = Path(destination)
+            dest_str = str(destination)
+            if dest_str.endswith(("/", "\\")) or (dest_path.is_dir() and not dest_path.suffix):
+                dest_path = dest_path / self._filename
+
+        # Refuse to overwrite directory
+        if dest_path.is_dir():
+            raise IsADirectoryError(
+                f"Destination path '{dest_path}' is an existing directory. "
+                "Cannot overwrite a directory with a file."
+            )
+
+        # Strict overwrite check
+        if dest_path.exists() and not overwrite:
+            raise FileExistsError(
+                f"Destination file '{dest_path}' already exists. "
+                "Pass 'overwrite=True' to allow overwriting."
+            )
+
+        parent_dir = dest_path.parent
+        try:
+            parent_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            raise OSError(f"Failed to create directory '{parent_dir}': {e}") from e
+
+        # Safe atomic write via temporary file in the same target directory
+        temp_file_path: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                dir=parent_dir,
+                delete=False,
+                prefix=f".tmp_{dest_path.stem}_",
+                suffix=".tmp",
+            ) as tmp:
+                temp_file_path = Path(tmp.name)
+                tmp.write(source_code)
+                tmp.flush()
+                os.fsync(tmp.fileno())
+
+            # Atomic replace
+            os.replace(temp_file_path, dest_path)
+            temp_file_path = None
+        except Exception as e:
+            if temp_file_path is not None and temp_file_path.exists():
+                try:
+                    temp_file_path.unlink()
+                except OSError:
+                    pass
+            raise OSError(f"Failed to export source code to '{dest_path}': {e}") from e
+
+        return dest_path.resolve()

pybox/programs/__init__.py

@@ -0,0 +1,6 @@
+"""
+Bundled Python program assets for pybox.
+
+These modules are packaged source code resources.
+They are read as text and are never imported or executed directly by pybox.
+"""

pybox/programs/eight.py

@@ -0,0 +1,27 @@
+import nltk
+from nltk.corpus import wordnet as wn
+from nltk.wsd import lesk
+# Download necessary resources
+nltk.download('wordnet')
+nltk.download('punkt')
+nltk.download('omw-1.4')
+def perform_wsd(sentences):
+    for sentence in sentences:
+        tokens = nltk.word_tokenize(sentence)
+        print(f"\nSentence: '{sentence}'")
+        for word in tokens:
+            synset = lesk(sentence, word)
+            if synset:
+                print(f"Word: {word}")
+                print(f"Sense: {synset.name()}")
+                print(f"Definition: {synset.definition()}")
+            else:
+                print(f"Word: {word}")
+                print("Sense: No disambiguation found")
+# Example usage with three sentences
+sentences = [
+    "The bank can guarantee deposits will eventually cover future tuition costs.",
+    "He went to the bank to deposit his money.",
+    "The river bank was full of blooming flowers."
+]
+perform_wsd(sentences)

pybox/programs/eleven.py

@@ -0,0 +1,36 @@
+import nltk
+from nltk.featstruct import FeatStruct
+# Define selectional restrictions for a predicate
+selectional_restrictions = {
+    'eat': {'AGENT': {'ANIMATED': '+', 'HUMAN': '+'}, 'THEME': {'EDIBLE': '+'}},
+    'sleep': {'SUBJECT': {'ANIMATED': '+', 'HUMAN': '+'}}
+}
+# Define a feature structure for an entity
+entity_feature_structure = FeatStruct(
+    ANIMATED='+',
+    HUMAN='+'
+)
+# Define a feature structure for a food item
+food_feature_structure = FeatStruct(
+    EDIBLE='+'
+)
+# Function to check if a feature structure satisfies selectional restrictions for a predicate
+def satisfies_selectional_restrictions(predicate, argument_feature_structure):
+    if predicate in selectional_restrictions:
+        for arg_name, restrictions in selectional_restrictions[predicate].items():
+            for feature, value in restrictions.items():
+                if value == '+':
+                    if feature not in argument_feature_structure or argument_feature_structure[feature] != '+':
+                        return False
+                elif value == '-':
+                    if feature in argument_feature_structure and argument_feature_structure[feature] == '+':
+                        return False
+    return True
+# Example usage
+predicate = 'eat'
+agent = entity_feature_structure
+theme = food_feature_structure
+if satisfies_selectional_restrictions(predicate, agent) and satisfies_selectional_restrictions(predicate, theme):
+    print(f"The feature structures satisfy selectional restrictions for the predicate '{predicate}'.")
+else:
+    print(f"The feature structures do not satisfy selectional restrictions for the predicate '{predicate}'.")

pybox/programs/five.py

@@ -0,0 +1,30 @@
+import nltk
+from nltk.corpus import treebank
+# Download necessary resources
+nltk.download('treebank')
+nltk.download('punkt')
+def analyze_sentential_components():
+    # Access the parsed sentences in the Penn Treebank
+    parsed_sentences = treebank.parsed_sents()
+    # Analyze a sample sentence
+    sample_sentence = parsed_sentences[0]
+
+    print("Sample sentence:")
+    print(" ".join(sample_sentence.leaves()))
+    print("\nParse tree:")
+    print(sample_sentence)
+
+    # Find and print specific components
+    print("\nNoun Phrases (NP):")
+    for subtree in sample_sentence.subtrees(filter=lambda t: t.label() == 'NP'):
+        print(" ".join(subtree.leaves()))
+
+    print("\nVerb Phrases (VP):")
+    for subtree in sample_sentence.subtrees(filter=lambda t: t.label() == 'VP'):
+        print(" ".join(subtree.leaves()))
+
+    print("\nPrepositional Phrases (PP):")
+    for subtree in sample_sentence.subtrees(filter=lambda t: t.label() == 'PP'):
+        print(" ".join(subtree.leaves()))
+# Example usage
+analyze_sentential_components()

pybox/programs/four.py

@@ -0,0 +1,40 @@
+import nltk
+from collections import Counter, defaultdict
+from nltk.util import ngrams
+from nltk.tokenize import word_tokenize
+import math
+# Download necessary resources
+nltk.download('punkt')
+def generate_ngrams(text, n):
+    # Tokenize the text
+    tokens = word_tokenize(text.lower())
+
+    # Generate n-grams
+    n_grams = list(ngrams(tokens, n))
+    return n_grams
+def calculate_ngram_probabilities(ngrams):
+    # Calculate frequencies of n-grams and (n-1)-grams
+    ngram_freq = Counter(ngrams)
+    n_minus_1_gram_freq = Counter([ngram[:-1] for ngram in ngrams])
+
+    # Calculate probabilities
+    ngram_probabilities = defaultdict(float)
+    for ngram in ngram_freq:
+        n_minus_1_gram = ngram[:-1]
+        ngram_probabilities[ngram] = ngram_freq[ngram] / n_minus_1_gram_freq[n_minus_1_gram]
+
+    return ngram_probabilities
+def generate_bigram_language_model(text):
+    # Generate bigrams (2-grams)
+    bigrams = generate_ngrams(text, 2)
+
+    # Calculate bigram probabilities
+    bigram_probabilities = calculate_ngram_probabilities(bigrams)
+
+    return bigram_probabilities
+# Example usage
+text = "This is a simple example sentence for demonstrating a bigram language model. This example is simple."
+bigram_model = generate_bigram_language_model(text)
+# Print bigram probabilities
+for bigram, prob in bigram_model.items():
+    print(f"Bigram: {bigram}, Probability: {prob:.4f}")

pybox/programs/nine.py

@@ -0,0 +1,41 @@
+import nltk
+from nltk.corpus import wordnet as wn
+from nltk.tokenize import word_tokenize
+from nltk import pos_tag
+# Download required nltk data
+nltk.download('punkt')
+nltk.download('averaged_perceptron_tagger')
+nltk.download('wordnet')
+# Define a simple feature structure
+class FeatureStructure:
+    def __init__(self, word, pos, synsets):
+        self.word = word
+        self.pos = pos
+        self.synsets = synsets
+    def __repr__(self):
+        return f"FeatureStructure(word='{self.word}', pos='{self.pos}', synsets={self.synsets})"
+# Function to identify semantic roles
+def identify_semantic_roles(sentence):
+    tokens = word_tokenize(sentence)
+    tagged_tokens = pos_tag(tokens)
+    # Create feature structures for each word
+    features = []
+    for word, pos in tagged_tokens:
+        synsets = wn.synsets(word)
+        features.append(FeatureStructure(word, pos, synsets))
+    # Simple semantic role assignment based on POS tags
+    roles = []
+    for feature in features:
+        if feature.pos.startswith('VB'):
+            roles.append((feature.word, 'Action'))
+        elif feature.pos.startswith('NN'):
+            # This is a simplistic approach; normally semantic roles are determined
+            # based on syntactic structure and more complex rules
+            roles.append((feature.word, 'Agent' if 'nsubj' in pos else 'Patient'))
+        else:
+            roles.append((feature.word, 'None'))
+    return roles
+# Example usage
+sentence = "The cat chased the mouse"
+roles = identify_semantic_roles(sentence)
+print(roles)

pybox/programs/one.py

@@ -0,0 +1,27 @@
+def count_words(sentence):
+    # Convert the sentence to lower case to make the counting case-insensitive
+    sentence = sentence.lower()
+
+    # Remove punctuation from the sentence
+    import string
+    translator = str.maketrans('', '', string.punctuation)
+    sentence = sentence.translate(translator)
+
+    # Split the sentence into words
+    words = sentence.split()
+
+    # Create a dictionary to count the words
+    word_count = {}
+
+    for word in words:
+        if word in word_count:
+            word_count[word] += 1
+        else:
+            word_count[word] = 1
+
+    return word_count
+# Example usage
+sentence = "This is a test. This test is only a test."
+word_count = count_words(sentence)
+for word, count in word_count.items():
+    print(f"{word}: {count}")

pybox/programs/seven.py

@@ -0,0 +1,37 @@
+import nltk
+from nltk import CFG
+from nltk.parse.generate import generate
+# Define a small fragment of English using CFG
+cfg_grammar = CFG.fromstring("""
+    S -> NP VP
+    NP -> Det N | Det Adj N | NP PP
+    VP -> V NP | VP PP
+    PP -> P NP
+    Det -> 'the' | 'a'
+    N -> 'dog' | 'cat' | 'park' | 'telescope'
+    Adj -> 'big' | 'small'
+    V -> 'saw' | 'chased'
+    P -> 'in' | 'with'
+""")
+# Initialize the parser
+parser = nltk.ChartParser(cfg_grammar)
+# Define some test sentences
+test_sentences = [
+    "the dog saw a cat",
+    "a big dog chased the small cat",
+    "the cat saw the dog in the park",
+    "the dog saw the cat with the telescope"
+]
+# Parse and display the test sentences
+for sentence in test_sentences:
+    print(f"Parsing sentence: '{sentence}'")
+    tokens = sentence.split()
+    for tree in parser.parse(tokens):
+        print(tree)
+        # Save the parse tree as text
+        with open("parse_tree.txt", "a") as f:
+            f.write(str(tree) + "\n")
+# Generate some sentences from the CFG (optional)
+print("\nGenerated sentences from the CFG:")
+for sentence in generate(cfg_grammar, n=10):
+    print(' '.join(sentence))

pybox/programs/six.py

@@ -0,0 +1,59 @@
+import nltk
+from sklearn.feature_extraction.text import CountVectorizer, TfidfVectorizer
+from nltk.corpus import stopwords
+from nltk.stem import PorterStemmer
+from nltk.stem import WordNetLemmatizer
+from nltk.tokenize import word_tokenize
+# Download necessary resources
+nltk.download('punkt')
+nltk.download('stopwords')
+nltk.download('wordnet')
+def preprocess_text(text):
+    # Tokenize the text
+    tokens = word_tokenize(text.lower())
+
+    # Remove stopwords
+    stop_words = set(stopwords.words('english'))
+    filtered_tokens = [token for token in tokens if token.isalnum() and token not in stop_words]
+
+    return filtered_tokens
+def stem_tokens(tokens):
+    # Initialize the stemmer
+    stemmer = PorterStemmer()
+    stemmed_tokens = [stemmer.stem(token) for token in tokens]
+    return stemmed_tokens
+def lemmatize_tokens(tokens):
+    # Initialize the lemmatizer
+    lemmatizer = WordNetLemmatizer()
+    lemmatized_tokens = [lemmatizer.lemmatize(token) for token in tokens]
+    return lemmatized_tokens
+def extract_features(texts):
+    # Preprocess the text
+    preprocessed_texts = [" ".join(preprocess_text(text)) for text in texts]
+
+    # Extract features using CountVectorizer
+    count_vectorizer = CountVectorizer()
+    count_features = count_vectorizer.fit_transform(preprocessed_texts)
+
+    # Extract features using TfidfVectorizer
+    tfidf_vectorizer = TfidfVectorizer()
+    tfidf_features = tfidf_vectorizer.fit_transform(preprocessed_texts)
+
+    return count_features, tfidf_features, count_vectorizer, tfidf_vectorizer
+# Example usage
+texts = [
+    "This is a simple example sentence for demonstrating feature extraction.",
+    "Feature extraction involves various techniques like tokenization, stemming, and lemmatization.",
+    "Text preprocessing is essential for text analysis and machine learning."
+]
+# Extract features
+count_features, tfidf_features, count_vectorizer, tfidf_vectorizer = extract_features(texts)
+# Display the feature names and feature vectors
+print("CountVectorizer Feature Names:")
+print(count_vectorizer.get_feature_names_out())
+print("\nCountVectorizer Feature Vectors:")
+print(count_features.toarray())
+print("\nTfidfVectorizer Feature Names:")
+print(tfidf_vectorizer.get_feature_names_out())
+print("\nTfidfVectorizer Feature Vectors:")
+print(tfidf_features.toarray())

pybox/programs/ten.py

@@ -0,0 +1,29 @@
+import re
+def translate_formula(formula):
+    formula = formula.strip()
+    # Universal quantifier
+    if formula.startswith("forall"):
+        match = re.match(r"forall\s+(\w+)\s*\((\w+)\((\w+)\)\s*->\s*(\w+)\((\w+)\)\)", formula)
+        if match:
+            var, pred1, _, pred2, _ = match.groups()
+            return f"Every {pred1.lower()} is {pred2.lower()}."
+    # Existential quantifier with AND
+    if formula.startswith("exists"):
+        match = re.match(
+            r"exists\s+(\w+)\s*\((\w+)\((\w+)\)\s*&\s*(\w+)\((\w+)\)\)",
+            formula
+        )
+        if match:
+            var, pred1, _, pred2, _ = match.groups()
+            return f"There exists a {pred1.lower()} who is {pred2.lower()}."
+    return "Formula format not recognized."
+# Test formulas
+formulas = [
+    "forall x (Dog(x) -> Animal(x))",
+    "forall x (Human(x) -> Mortal(x))",
+    "exists x (Student(x) & Smart(x))"
+]
+for formula in formulas:
+    print("Predicate Formula:", formula)
+    print("Translation:", translate_formula(formula))
+    print()

pybox/programs/three.py

@@ -0,0 +1,30 @@
+import nltk
+from nltk.corpus import stopwords
+from nltk.tokenize import word_tokenize
+from nltk.stem import WordNetLemmatizer
+# Download necessary resources
+nltk.download('punkt')
+nltk.download('wordnet')
+nltk.download('stopwords')
+def morphological_analysis_and_remove_stopwords(sentence):
+    # Tokenize the sentence
+    words = word_tokenize(sentence)
+
+    # Initialize the lemmatizer
+    lemmatizer = WordNetLemmatizer()
+
+    # Perform lemmatization
+    lemmatized_words = [lemmatizer.lemmatize(word) for word in words]
+
+    # Retrieve the list of stopwords
+    stop_words = set(stopwords.words('english'))
+
+    # Remove stopwords
+    filtered_words = [word for word in lemmatized_words if word.lower() not in stop_words]
+
+    return filtered_words
+# Example usage
+sentence = "This is a simple example sentence for demonstrating morphological analysis and removing stopwords."
+filtered_words = morphological_analysis_and_remove_stopwords(sentence)
+print("Original Sentence:", sentence)
+print("Filtered Words:", filtered_words)

pybox/programs/two.py

@@ -0,0 +1,23 @@
+import re
+def demonstrate_regex_operations(sentence):
+    # Example usage of re.match()
+    # Match checks for a pattern only at the beginning of the string
+    match_result = re.match(r'\w+', sentence)
+    if match_result:
+        print(f"Match: '{match_result.group()}' found at the beginning of the sentence")
+    else:
+        print("No match found at the beginning of the sentence")
+    # Example usage of re.search()
+    # Search checks for a pattern anywhere in the string
+    search_result = re.search(r'\bis\b', sentence)
+    if search_result:
+        print(f"Search: '{search_result.group()}' found in the sentence")
+    else:
+        print("No search result found in the sentence")
+    # Example usage of re.sub()
+    # Sub replaces occurrences of the pattern with the replacement string
+    modified_sentence = re.sub(r'\bis\b', 'was', sentence)
+    print(f"Sub: Modified sentence: '{modified_sentence}'")
+# Example usage
+sentence = "This is a test. This test is only a test."
+demonstrate_regex_operations(sentence)

pybox/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. Pybox uses inline types.

pybox_nlp-0.1.0.dist-info/METADATA

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: pybox-nlp
+Version: 0.1.0
+Summary: A production-ready Python library bundling 11 standalone NLP programs with source inspection and export capabilities.
+Author: PyBox Maintainers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pybox-dev/pybox
+Project-URL: Repository, https://github.com/pybox-dev/pybox
+Project-URL: Issues, https://github.com/pybox-dev/pybox/issues
+Project-URL: Changelog, https://github.com/pybox-dev/pybox/blob/main/CHANGELOG.md
+Keywords: pybox,bundle,programs,source-code,exporter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# PyBox (`pybox`)
+
+A production-ready Python library bundling 11 standalone Python programs into one installable package. Access each program via intuitive top-level attributes, inspect its original source code directly, and safely export it into standalone `.py` scripts.
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/pybox/)
+[![Python Versions](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://pypi.org/project/pybox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Distinction: Inspection vs. Execution](#key-distinction-inspection-vs-execution)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Program Identifiers](#program-identifiers)
+- [Features and Usage](#features-and-usage)
+  - [1. Viewing Source Code](#1-viewing-source-code)
+  - [2. Accessing Raw Source String](#2-accessing-raw-source-string)
+  - [3. Exporting to Standalone Files](#3-exporting-to-standalone-files)
+  - [4. Custom Export Destinations](#4-custom-export-destinations)
+  - [5. Overwrite Protection](#5-overwrite-protection)
+  - [6. Developer Representation](#6-developer-representation)
+- [Individual Program Dependencies](#individual-program-dependencies)
+- [Safety and Security](#safety-and-security)
+- [Compatibility](#compatibility)
+- [Development and Testing](#development-and-testing)
+- [Publishing to PyPI](#publishing-to-pypi)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Overview
+
+`pybox` bundles 11 standalone Python programs into a unified package. Instead of copying and pasting code snippets, developers can:
+- Import `pybox` and inspect any bundled program's complete source code in Python interactive shells, logging, or scripts.
+- Export bundled programs into standalone `.py` files on demand with atomic write safety and directory creation.
+- Keep source code intact: all comments, imports, functions, classes, and logic are preserved identically.
+
+---
+
+## Key Distinction: Inspection vs. Execution
+
+> [!IMPORTANT]
+> **`pybox` does NOT execute bundled programs when you import the library, inspect their source code, or export them to disk.**
+
+`pybox` acts as a curated code distribution and extraction engine. When you access `pybox.one` or invoke `pybox.one.save()`, `pybox` reads the packaged source assets as UTF-8 text.
+
+To **run** an exported program after saving it, execute it in Python directly using your terminal:
+
+```bash
+python one.py
+```
+
+Ensure any third-party dependencies required by that specific program are installed in your Python environment before running it.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+python -m pip install pybox
+```
+
+### From Local Source (Editable Mode)
+
+```bash
+git clone https://github.com/pybox-dev/pybox.git
+cd pybox
+python -m pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+import pybox
+
+# 1. Print the complete source code of a program
+print(pybox.one)
+
+# 2. Get the raw source code string
+code = pybox.two.code
+print(f"Total lines: {len(code.splitlines())}")
+
+# 3. Export to a standalone Python script
+saved_path = pybox.one.save()
+print(f"Exported to: {saved_path}")
+```
+
+---
+
+## Program Identifiers & Bundled Programs
+
+The package exposes 11 curated NLP programs as attributes on the top-level `pybox` module:
+
+| Attribute | Default Export | Description | Dependencies |
+| :--- | :--- | :--- | :--- |
+| `pybox.one` | `one.py` | **Word Frequency & Punctuation Stripper**: Counts word frequencies after stripping punctuation and normalizing case. | Standard Library (`string`) |
+| `pybox.two` | `two.py` | **Regex Demonstrator**: Demonstrates pattern matching, searching, extracting, and substitution using regex. | Standard Library (`re`) |
+| `pybox.three` | `three.py` | **Morphological Analyzer & Stopwords Filter**: Lemmatizes tokens and filters English stopwords. | `nltk` |
+| `pybox.four` | `four.py` | **N-Gram Generator & Probability Calculator**: Generates N-grams and calculates sentence probabilities. | `nltk` |
+| `pybox.five` | `five.py` | **Penn Treebank Component Analyzer**: Inspects and parses sentential constituents using Penn Treebank trees. | `nltk` |
+| `pybox.six` | `six.py` | **Vectorization & Feature Extraction Pipeline**: Preprocesses text with stemming/lemmatization and extracts Count/TF-IDF vectors. | `nltk`, `scikit-learn` |
+| `pybox.seven` | `seven.py` | **Context-Free Grammar (CFG) Generator**: Generates sentences adhering to formal phrase structure grammar rules. | `nltk` |
+| `pybox.eight` | `eight.py` | **Word Sense Disambiguation (WSD)**: Resolves word senses in context using the Lesk algorithm and WordNet. | `nltk` |
+| `pybox.nine` | `nine.py` | **Semantic Role & Feature Structure Identifier**: Maps syntactic tokens and POS tags to thematic roles and feature structures. | `nltk` |
+| `pybox.ten` | `ten.py` | **First-Order Logic (FOL) Translator**: Translates quantified formal logic expressions into natural language sentences. | Standard Library (`re`) |
+| `pybox.eleven` | `eleven.py` | **Selectional Restrictions & Anomaly Checker**: Evaluates semantic predicate-argument compatibility using feature structures. | `nltk` |
+
+You can iterate over all programs programmatically:
+
+```python
+import pybox
+
+for name, prog in pybox.PROGRAMS.items():
+    print(f"Loaded {prog.identifier}: {prog.filename}")
+```
+
+---
+
+## Features and Usage
+
+### 1. Viewing Source Code
+
+Converting any program object to `str` (or passing it to `print()`) renders its complete source code:
+
+```python
+import pybox
+
+print(pybox.one)
+```
+
+### 2. Accessing Raw Source String
+
+Access the `.code` property on any program object to obtain the unmodified source code as a Python `str`:
+
+```python
+import pybox
+
+source = pybox.one.code
+assert isinstance(source, str)
+print(f"Total lines: {len(source.splitlines())}")
+```
+
+### 3. Exporting to Standalone Files
+
+Call `.save()` without arguments to export the program to the current working directory under its default filename (e.g., `one.py`):
+
+```python
+import pybox
+
+path = pybox.one.save()
+print(path)  # /path/to/cwd/one.py
+```
+
+### 4. Custom Export Destinations
+
+Specify a custom file name or path. If intermediate parent directories do not exist, `pybox` creates them automatically:
+
+```python
+import pybox
+
+# Export to a custom filename in the current directory
+pybox.one.save("my_program.py")
+
+# Export to a nested subdirectory (directories created automatically)
+pybox.two.save("exports/tools/run_two.py")
+
+# Export into an existing directory (uses default filename 'three.py')
+pybox.three.save("exports/")
+```
+
+### 5. Overwrite Protection
+
+To protect existing scripts from accidental loss, `pybox` **refuses to overwrite existing files by default**:
+
+```python
+import pybox
+
+# First export succeeds
+pybox.one.save("script.py")
+
+# Second export raises FileExistsError
+try:
+    pybox.one.save("script.py")
+except FileExistsError as e:
+    print("Caught expected protection error:", e)
+
+# Explicitly authorize overwriting
+pybox.one.save("script.py", overwrite=True)
+```
+
+Export writes use atomic temporary file replacement (`os.replace`) to ensure a partially written file is never left on disk in the event of an interruption.
+
+### 6. Developer Representation
+
+In interactive environments, `repr()` provides clear identification:
+
+```python
+import pybox
+
+print(repr(pybox.one))
+# Output: Program('one')
+```
+
+---
+
+## Individual Program Dependencies
+
+`pybox` itself has **zero runtime third-party dependencies**. It relies strictly on Python standard library modules (`pathlib`, `tempfile`, `os`, `importlib.resources`).
+
+Exporting a program writes its standalone source code to disk. Before executing the exported scripts, install any required third-party libraries:
+
+```bash
+# To run all exported NLP programs:
+pip install nltk scikit-learn
+```
+
+| Program | Standard Library Modules | External Dependencies | NLTK Corpora Required (Auto-downloaded on run) |
+| :--- | :--- | :--- | :--- |
+| `one.py` | `string` | None | None |
+| `two.py` | `re` | None | None |
+| `three.py` | Standard library | `nltk` | `punkt`, `wordnet`, `stopwords` |
+| `four.py` | `collections`, `math` | `nltk` | `punkt` |
+| `five.py` | Standard library | `nltk` | `treebank`, `punkt` |
+| `six.py` | Standard library | `nltk`, `scikit-learn` | `punkt`, `stopwords`, `wordnet` |
+| `seven.py` | Standard library | `nltk` | None |
+| `eight.py` | Standard library | `nltk` | `wordnet`, `punkt`, `omw-1.4` |
+| `nine.py` | Standard library | `nltk` | `punkt`, `averaged_perceptron_tagger`, `wordnet` |
+| `ten.py` | `re` | None | None |
+| `eleven.py` | Standard library | `nltk` | None |
+
+---
+
+## Safety and Security
+
+- **No Execution on Import**: Bundled code is never imported, evaluated, or executed by `pybox`.
+- **Atomic Writes**: Export files are written to a temporary file before being atomically moved into destination path.
+- **Directory Traversal & Overwrite Guards**: Prevents accidental directory replacement and unintended data destruction.
+- **Zero Secrets**: Bundled programs must never contain API tokens, passwords, or personal credentials.
+
+---
+
+## Compatibility
+
+- **Python**: `>= 3.8` (fully tested across Python 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13)
+- **Platforms**: Windows, macOS, and Linux
+- **Packaging Standard**: PEP 517 / PEP 518 / PEP 621 compliant build
+
+---
+
+## Development and Testing
+
+### Setup Environment
+
+```powershell
+# Windows PowerShell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+```bash
+# Linux / macOS
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+pytest -v
+```
+
+### Build Distribution Artifacts
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+---
+
+## Publishing to PyPI
+
+> [!NOTE]
+> PyPI distribution names are globally unique. Before publishing, verify name availability on [PyPI](https://pypi.org/). If `pybox` is already registered, set an alternative name (such as `pybox-lib` or `pybox-bundle`) in `pyproject.toml`.
+
+### Option A: PyPI Trusted Publishing (Recommended)
+
+1. Connect your GitHub repository to PyPI at [PyPI Manage Account > Publishing](https://pypi.org/manage/account/publishing/).
+2. Push a release tag or trigger the included `.github/workflows/publish.yml` workflow.
+3. GitHub Actions authenticates via short-lived OIDC tokens without requiring static API keys.
+
+### Option B: Manual Publishing via Twine
+
+```bash
+python -m twine upload --repository testpypi dist/*  # Test on TestPyPI first
+python -m twine upload dist/*                        # Publish to production PyPI
+```
+
+---
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature/my-feature`).
+3. Commit your changes (`git commit -m "Add feature"`).
+4. Run the test suite (`pytest -v`).
+5. Open a Pull Request.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pybox_nlp-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+pybox/__init__.py,sha256=pa2TYgUk_K5hjAL5Jp-wEHPU4buT7JMsHkgylL3kNPk,1073
+pybox/core.py,sha256=spTNJVfcTWty1dPfbKtAj6fYc9fBhXZk4hWweRCH2Xg,5785
+pybox/py.typed,sha256=I4fsYtPBETPV1VDKpOCZp2k9qCuc2zWbrnA9pg1evyk,52
+pybox/programs/__init__.py,sha256=vhZnSCIgwO5LMmsJ-5zb0mT8f--kfZY6w9gbkureCcU,176
+pybox/programs/eight.py,sha256=22LuJzc5twkmfCLXfaeWGfC0yCkWw6oAOopHJ2D2A8c,941
+pybox/programs/eleven.py,sha256=_89admk5a6myq_mwtx5Yid4qVd-3UaShxvHRNFAlx5k,1654
+pybox/programs/five.py,sha256=quVgZ1finrsD4hVXkAhjWSeC83I-clRelXrPT28WUes,1041
+pybox/programs/four.py,sha256=n_oEPHDwC2WNuJoWoK8x9D0nckX0tBnaX9yyA_jW4VQ,1389
+pybox/programs/nine.py,sha256=fBjfbd3XAPuVBArZMJIEQeS41lvy7Q6F58r099wrOF0,1545
+pybox/programs/one.py,sha256=hxJk0MSob9uGkuKv51wgq5RrX0lgr0yLx8Rm37XYcZE,771
+pybox/programs/seven.py,sha256=DU78Z1aFxugQSuFTuL8pJcSVPkMjBJhS2rpx6DTFFa4,1150
+pybox/programs/six.py,sha256=Mfp7fxA7LW6R6guk60-0JbIvwgFqOAnhnK1mFp2KziQ,2316
+pybox/programs/ten.py,sha256=hDSlEB--JQGJopOo3hC-7JVj0xFmDIXIxUP1sBXlyp0,1043
+pybox/programs/three.py,sha256=l6FSS0OJdlvPnsdUS8iUxq03KCshaABDS_XePUO-ayA,1031
+pybox/programs/two.py,sha256=G2hsReL4qiAWD2F7oNssd2vCMjVaLIaSlY92lnRmuPw,1028
+pybox_nlp-0.1.0.dist-info/licenses/LICENSE,sha256=HyKa_6xXkhmQKyj4ymCYD64vEu7jzRafTT-eIPlPOy0,1087
+pybox_nlp-0.1.0.dist-info/METADATA,sha256=Ohr0ftWe4aVEbvnb31ppAgNfRjQLJua0YlbPAtbe4Sc,12518
+pybox_nlp-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pybox_nlp-0.1.0.dist-info/top_level.txt,sha256=jyiglQVZaayV6LzbWjl4RERgL92aJ9-L1WRp2OUTJbg,6
+pybox_nlp-0.1.0.dist-info/RECORD,,

pybox_nlp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pybox_nlp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyBox Authors and Contributors
+
+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.

pybox_nlp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pybox