Metadata-Version: 2.4
Name: samai-openbox
Version: 0.1.0
Summary: CLI archive skill for AI agents — compress and extract zip, tar, tar.gz, 7z, rar, iso from one stable command. Part of the OpenBox project.
Author-email: SamAI Group <dev@samai.cc>
License: MIT
Project-URL: Homepage, https://openbox.samai.cc
Project-URL: Documentation, https://openbox.samai.cc/ai-agent.html
Project-URL: Source, https://github.com/samaidev/openbox
Project-URL: Issues, https://github.com/samaidev/openbox/issues
Project-URL: OpenBox desktop app, https://openbox.samai.cc/download.html
Keywords: openbox,archiver,compression,extraction,ai-agent,cli,llm,agent,skill,zip,tar,tar.gz,7z,rar,iso,samai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
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 :: System :: Archiving
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# samai-openbox

> CLI archive skill for AI agents — one stable command to compress and extract every common archive format.

[![PyPI version](https://img.shields.io/pypi/v/samai-openbox.svg)](https://pypi.org/project/samai-openbox/)
[![Python 3.8+](https://img.shields.io/pypi/pyversions/samai-openbox.svg)](https://pypi.org/project/samai-openbox/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/samaidev/openbox/blob/main/LICENSE)

**samai-openbox** is a tiny, dependency-light Python package that exposes the
[OpenBox](https://openbox.samai.cc) archiver engine as a single CLI command —
`samai-openbox` — so any LLM agent with shell access can compress and extract
archives without remembering six different flag syntaxes.

## Why does this exist?

LLM agents are great at writing shell commands, but they consistently get
archive syntax wrong. One stable CLI fixes that:

- `tar -czvf` vs `tar -xzvf` vs `7z a` vs `7z x` vs `zip -r` vs `unzip` — agents hallucinate.
- Path-traversal protection varies by tool. OpenBox blocks `../../etc/passwd`-style entries at extraction time.
- JSON output mode lets agents parse archive contents in their reasoning loop.

## Install

```bash
# Standard
pip install samai-openbox

# Or with pipx (recommended for isolated CLI tools)
pipx install samai-openbox

# Verify
samai-openbox --version
samai-openbox --help
```

Works on Python 3.8+. Pure-Python implementation using stdlib `zipfile` and
`tarfile`; shells out to the system `7z` / `7zz` / `7za` for 7z, and `unrar`
for rar (only if those formats are actually used).

## The CLI in 60 seconds

Five verbs cover everything an agent needs to do with archives.

### Compress files into an archive

```bash
# Auto-detects format from output extension: .zip .tar .tar.gz .7z
samai-openbox compress report.pdf photos/ -o backup.zip

# Force compression level (0-9, default 6)
samai-openbox compress src/ -o release.tar.gz --level 9

# 7z compression (requires 7z/7zz/7za on PATH)
samai-openbox compress bigfile.bin -o archive.7z
```

### Extract an archive

```bash
# Auto-creates destination if missing
samai-openbox extract backup.zip -d ./restored

# Works for every supported format
samai-openbox extract legacy.rar -d ./legacy
samai-openbox extract cd-image.iso -d ./cd-contents
```

### List archive contents

```bash
# Human-readable
samai-openbox list backup.zip

# Machine-readable JSON — perfect for agent reasoning
samai-openbox list backup.zip --json
```

Example JSON output:

```json
{
  "archive": "backup.zip",
  "format": "zip",
  "entries": [
    {"name": "report.pdf",   "size": 2516582, "modified": "2024-08-15T10:23:00Z"},
    {"name": "photos/",      "size": 0,       "modified": "2024-08-15T10:24:00Z", "is_dir": true},
    {"name": "photos/01.jpg", "size": 4409111, "modified": "2024-08-14T18:11:00Z"}
  ]
}
```

### Test archive integrity

```bash
# Verifies CRCs without extracting — exits non-zero on corruption
samai-openbox test backup.zip
```

### Show version & supported formats

```bash
samai-openbox --version
samai-openbox formats
```

## Format support matrix

| Format  | Compress  | Extract  | Notes                                   |
|---------|:---------:|:--------:|-----------------------------------------|
| zip     | ✓         | ✓        | stdlib `zipfile`, deflate or store       |
| tar     | ✓         | ✓        | stdlib `tarfile`                         |
| tar.gz  | ✓         | ✓        | `tarfile` + gzip, 5 levels               |
| 7z      | ✓*        | ✓*       | requires `7z` / `7zz` / `7za` on PATH    |
| rar     | —         | ✓*       | requires `unrar` on PATH                 |
| iso     | —         | ✓*       | requires `7z` (handles ISO 9660)         |

`*` = via external CLI. Install with:
- 7-Zip: <https://www.7-zip.org/download.html> (Windows) · `brew install 7zip` (macOS) · `sudo apt install p7zip-full` (Linux)
- unrar: <https://www.rarlab.com/rar_add.htm> (Windows) · `brew install unrar` (macOS) · `sudo apt install unrar` (Linux)

## Path-traversal safety

`extract` blocks any archive entry whose absolute path would escape the
target directory. So an archive containing `../../etc/passwd` extracts the
file into `<target>/etc/passwd` instead of `/etc/passwd`. Safe to point at
untrusted downloads.

## ClawHub skill spec

Drop this into your agent's skill catalog so it knows when and how to call OpenBox:

```yaml
# skill.yaml
name: openbox-archive
version: 0.1.0
description: Compress and extract archives (zip, tar, tar.gz, 7z, rar, iso)
command: samai-openbox
install: pip install samai-openbox
verbs:
  - name: compress
    usage: samai-openbox compress <files...> -o <archive> [--level 0-9]
    formats_out: [zip, tar, tar.gz, 7z]
  - name: extract
    usage: samai-openbox extract <archive> -d <dir>
    formats_in: [zip, tar, tar.gz, 7z, rar, iso]
  - name: list
    usage: samai-openbox list <archive> [--json]
  - name: test
    usage: samai-openbox test <archive>
safety:
  - Extraction blocks path-traversal entries (../../etc/passwd)
  - No network calls · no telemetry · no auto-update
  - Exits non-zero on any error — safe to chain with &&
```

## Use as a Python module

```python
from samai_openbox import compress, extract, list_archive, test_archive

# Compress
compress(["report.pdf", "photos/"], "backup.zip", level=6)

# Extract (path-traversal safe)
extract("backup.zip", "./restored")

# List (returns a list of dicts)
entries = list_archive("backup.zip")
for e in entries:
    print(e["name"], e["size"], e.get("modified"))

# Verify integrity
ok = test_archive("backup.zip")
```

## Agent conversation example

> **User:** Pack the `reports/` folder into a `.zip` for email, but skip anything larger than 10 MB. Then list what's in the archive so I can sanity-check.
>
> **Agent (using samai-openbox):**
> ```bash
> # 1. Find files under 10 MB in reports/
> find reports/ -type f -size -10M -print0 | \
>   xargs -0 samai-openbox compress -o reports-email.zip
>
> # 2. List the result as JSON for verification
> samai-openbox list reports-email.zip --json
> ```
> Done. `reports-email.zip` contains 23 files totalling 47.2 MB (after compression from 89.4 MB). Three files over 10 MB were excluded: `reports/q3-raw-data.csv`, `reports/audit-full.pdf`, and `reports/appendix-exhibits.pptx`. Want me to send them separately as a `.tar.gz`?

## License

MIT — same as the OpenBox desktop app. See [LICENSE](https://github.com/samaidev/openbox/blob/main/LICENSE).

## See also

- **OpenBox desktop app** — graphical archiver for Windows / macOS / Linux: <https://openbox.samai.cc>
- **Source code** — <https://github.com/samaidev/openbox>
- **SamAI Group public-welfare projects** — <https://samai.cc#public-welfare>

OpenBox is a SamAI Group public-welfare open-source project. Free, forever.
