aimlese 0.1.0
A pip-installable package bundling AIML notebooks and scripts for offline access
License: MIT
Requires Python: >=3.8
Keywords: aiml, jupyter, notebooks, machine-learning, offline

# AIML Bundle

A pip-installable package that bundles AIML notebooks and Python scripts for offline access. All files are included as package data in the wheel/sdist, so no internet connection is required after installation.

## Features

- 📦 Bundle Jupyter notebooks (`.ipynb`) and Python scripts (`.py`) as package data
- 🔌 Works completely offline after installation
- 🐍 Simple Python API for listing, reading, and extracting resources
- 🖥️ Command-line interface for quick access
- ✅ No external dependencies (standard library only)

## Installation

### From Built Wheel

First, build the package:

```bash
python -m pip install build
python -m build
```

Then install the generated wheel:

```bash
pip install dist/aiml_bundle-0.1.0-py3-none-any.whl
```

### For Development

```bash
pip install -e .
```

## Python API

### List Resources

```python
import aiml_bundle

# Get list of all bundled files
files = aiml_bundle.list_resources()
print(f"Found {len(files)} files: {files}")
```

### Read Resource Contents

```python
import aiml_bundle

# Read a Python script (returns string)
script_content = aiml_bundle.read_resource("aiml2.py")
print(script_content[:100])

# Read a notebook (returns bytes)
notebook_bytes = aiml_bundle.read_resource("AIML2.ipynb")
print(f"Notebook size: {len(notebook_bytes)} bytes")
```

### Extract Resources to Disk

```python
import aiml_bundle

# Extract a single file
path = aiml_bundle.extract_resource("AIML2.ipynb", "output/")
print(f"Extracted to: {path}")

# Extract all files
paths = aiml_bundle.extract_all("output/all_files/")
print(f"Extracted {len(paths)} files")
```

## Command-Line Interface

### List Bundled Files

```bash
aiml-bundle list
```

Output:
```
Bundled resources (11 files):
  AIML2.ipynb
  AIML3.ipynb
  AIML4.ipynb
  ...
```

### Read a File

```bash
# Display first 50 lines (default)
aiml-bundle read aiml2.py

# Display first 20 lines
aiml-bundle read AIML2.ipynb -n 20

# Display entire file
aiml-bundle read Exp1.py -n 0
```

### Extract Files

```bash
# Extract a single file
aiml-bundle extract AIML2.ipynb output/

# Extract all files
aiml-bundle extract-all output/all_files/

# Extract all files with verbose output
aiml-bundle extract-all output/ --verbose
```

## Bundled Resources

The package includes the following files:

- `AIML2.ipynb` - Jupyter notebook
- `aiml2.py` - Python script
- `AIML3.ipynb` - Jupyter notebook
- `aiml3.py` - Python script
- `AIML4.ipynb` - Jupyter notebook
- `aiml4.py` - Python script
- `AIML5.ipynb` - Jupyter notebook
- `AIML6.ipynb` - Jupyter notebook
- `AIML7 (1).ipynb` - Jupyter notebook
- `AIML9.py` - Python script
- `Exp1.py` - Python script

## Building and Testing

### Build the Package

```bash
# Install build tools
pip install build pytest

# Build wheel and source distribution
python -m build
```

This creates:
- `dist/aiml_bundle-0.1.0-py3-none-any.whl` (wheel)
- `dist/aiml_bundle-0.1.0.tar.gz` (source distribution)

### Run Tests

```bash
# Install the package first
pip install dist/aiml_bundle-0.1.0-py3-none-any.whl

# Run tests
pytest tests/
```

### Verify Offline Availability

To confirm the package works offline:

```bash
# Install the package
pip install dist/aiml_bundle-0.1.0-py3-none-any.whl

# Disconnect from the internet, then run:
python -c "import aiml_bundle; print(aiml_bundle.list_resources())"
```

Or create a test script `test_offline.py`:

```python
import aiml_bundle

# List all resources
resources = aiml_bundle.list_resources()
assert len(resources) > 0, "No resources found!"
print(f"✓ Found {len(resources)} resources")

# Read a resource
content = aiml_bundle.read_resource(resources[0])
assert content, "Empty resource content!"
print(f"✓ Read resource: {resources[0]} ({len(content)} bytes)")

# Extract a resource
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as tmpdir:
    path = aiml_bundle.extract_resource(resources[0], tmpdir)
    assert path.exists(), "Extracted file not found!"
    
    # Verify content matches
    extracted_content = path.read_bytes()
    original_content = aiml_bundle.read_resource(resources[0])
    if isinstance(original_content, str):
        original_content = original_content.encode('utf-8')
    
    assert extracted_content == original_content, "Content mismatch!"
    print(f"✓ Extracted and verified: {resources[0]}")

print("\n✅ All offline tests passed!")
```

Run with:

```bash
python test_offline.py
```

## Project Structure

```
aiml/
├── pyproject.toml              # Package metadata and build configuration
├── MANIFEST.in                 # Include rules for source distribution
├── README.md                   # This file
├── LICENSE                     # License file (create as needed)
├── aiml_bundle/                # Main package directory
│   ├── __init__.py            # Package initialization, exports API
│   ├── api.py                 # Core API: list, read, extract functions
│   ├── cli.py                 # Command-line interface
│   └── resources/             # Package data directory
│       └── aiml_files/        # Bundled notebooks and scripts
│           ├── AIML2.ipynb
│           ├── aiml2.py
│           ├── AIML3.ipynb
│           ├── aiml3.py
│           ├── AIML4.ipynb
│           ├── aiml4.py
│           ├── AIML5.ipynb
│           ├── AIML6.ipynb
│           ├── AIML7 (1).ipynb
│           ├── AIML9.py
│           └── Exp1.py
└── tests/                      # Test suite
    └── test_bundle.py         # Tests for API functions
```

## Development

### Adding New Resources

1. Place new files in `aiml_bundle/resources/aiml_files/`
2. Rebuild the package: `python -m build`
3. Reinstall: `pip install --force-reinstall dist/aiml_bundle-0.1.0-py3-none-any.whl`

### Running Tests During Development

```bash
# Install in editable mode
pip install -e .

# Run tests
pytest tests/ -v
```

## Requirements

- Python 3.8 or higher
- No external runtime dependencies
- Build dependencies: `setuptools>=61.0`, `wheel`, `build`
- Test dependencies: `pytest>=7.0`

## License

MIT License - See LICENSE file for details.

## Notes

- All notebook files (`.ipynb`) are stored as binary data to preserve JSON structure
- Text files (`.py`, `.md`) are stored as UTF-8 encoded text
- The package uses `importlib.resources` for reliable resource access in installed packages
- Files are bundled into the wheel at build time - no downloads occur during installation