pybox-nlp 0.1.0__tar.gz

pybox_nlp-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,325 @@
+# 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.