Metadata-Version: 2.4
Name: abstract_essentials
Version: 0.0.0.22
Summary: The lean, dependency-free core of abstract_utilities: stdlib-only helpers (json/path/file/string/list/log) safe to import anywhere, including Termux/phone.
Author-email: putkoff <partners@abstractendeavors.com>
License: MIT
Project-URL: Homepage, https://github.com/AbstractEndeavors/abstract_essentials
Keywords: utilities,stdlib,helpers,dependency-free
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# abstract_essentials

The lean, **dependency-free** core carved out of `abstract_utilities`.

Every symbol here depends only on the Python standard library — no third-party
imports, no `from .imports import *` chains, no submodule fan-out. It imports fast
and installs anywhere (desktop, server, **Termux/Android phone**), which makes it a
safe foundation for the rest of the `abstract_*` tree to build on without dragging
in the monolith.

## Why this exists

`abstract_utilities` is imported by nearly every `abstract_*` package, so its size
and entanglement (star-exports across a dozen submodules) ripple everywhere.
`abstract_essentials` is the ~50-function subset that is actually used in practice,
extracted as a clean, explicit API.

## Install

```sh
pip install abstract_essentials
```

## Use

```python
from abstract_essentials import make_list, get_any_value, safe_read_from_json, get_logFile
```

The public API is whatever is listed in `abstract_essentials.__all__` (53 symbols:
json/path/file/string/list/type/log helpers).

## Migrating off abstract_utilities

`abstract_utilities` can become a thin compatibility shim that re-exports from here
(see `abstract_utilities_compat_shim.py` shipped alongside this scaffold), so existing
`from abstract_utilities import X` keeps working while new code imports from
`abstract_essentials`.

## ML/model MIME hints

`MIME_TYPES['machine_learning']` and `MEDIA_TYPES['machine_learning']` cover
GGUF, safetensors, ONNX, PyTorch, TFLite, Keras and Core ML files, plus shared
checkpoint, array and serialization extensions. The `application/x-*` model
labels are local package conventions, not asserted IANA registrations.

```python
from abstract_essentials import get_mime_type, derive_media_type, derive_media_types

get_mime_type('weights.SAFETENSORS')  # 'application/x-safetensors'
derive_media_type('weights.gguf')    # 'machine_learning'
derive_media_types('weights.bin')   # ('executable', 'machine_learning')
derive_media_types('weights.h5')    # ('data_science', 'pandas_data', 'machine_learning')
```

These functions inspect the filename only and accept paths or dotted extensions.
Both category helpers are case-insensitive. The singular helper preserves the
first-match order of existing categories; the plural helper retains ambiguity.
Generic `.bin`, `.ckpt`, `.pb`, `.model`, and pickle files keep
`application/octet-stream`: an extension does not establish model contents.
JSON configs remain documents; a model directory's supporting files are not
automatically models. Directory bundles are not detected by these helpers.

For discovery, use these mappings to shortlist candidates, then inspect content
and retain detected format, container MIME, and extension agreement separately.
For example, [PyTorch checkpoints](https://docs.pytorch.org/docs/stable/notes/serialization.html)
can use ZIP containers, while [safetensors](https://github.com/huggingface/safetensors#format)
uses a length-prefixed JSON tensor header. A filename MIME hint is not proof that
either parser will accept the file, nor permission to unpickle it.

The existing `find_utils` defaults derive their extension sets from this registry,
so new ML extensions also enter its default exclusion set. Pass explicit scan
filters when collecting model files.

## License

MIT — putkoff / Abstract Endeavors.
