Metadata-Version: 2.4
Name: thehallucinatedlab
Version: 0.2.0
Summary: The Hallucinated Lab toolkit — local-first tools you can call as ordinary Python methods.
Project-URL: Homepage, https://thehallucinatedlab.space
Project-URL: Documentation, https://thehallucinatedlab.space/convert.html
Project-URL: Source, https://github.com/The-Hallucinated-Lab/thehallucinatedlab
Project-URL: Issues, https://github.com/The-Hallucinated-Lab/thehallucinatedlab/issues
Author-email: The Hallucinated Lab <thehallucinatedlab@gmail.com>
License: MIT
Keywords: avif,convert,image,jpeg,local-first,png,toolkit,webp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: pillow>=10.0
Provides-Extra: chunk
Requires-Dist: langchain-text-splitters>=0.3; extra == 'chunk'
Requires-Dist: tiktoken>=0.7; extra == 'chunk'
Requires-Dist: tokenizers>=0.15; extra == 'chunk'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.13,>=0.6; extra == 'dev'
Provides-Extra: embed
Requires-Dist: numpy>=1.24; extra == 'embed'
Requires-Dist: sentence-transformers>=3.0; extra == 'embed'
Provides-Extra: extract
Requires-Dist: beautifulsoup4>=4.12; extra == 'extract'
Requires-Dist: ebooklib>=0.18; extra == 'extract'
Requires-Dist: langchain-community>=0.3; extra == 'extract'
Requires-Dist: langchain-core>=0.3; extra == 'extract'
Requires-Dist: odfpy>=1.4; extra == 'extract'
Requires-Dist: openpyxl>=3.1; extra == 'extract'
Requires-Dist: pypdf>=4.0; extra == 'extract'
Requires-Dist: python-docx>=1.1; extra == 'extract'
Requires-Dist: python-pptx>=0.6; extra == 'extract'
Requires-Dist: striprtf>=0.0.26; extra == 'extract'
Provides-Extra: index
Requires-Dist: chromadb>=0.5; extra == 'index'
Requires-Dist: numpy>=1.24; extra == 'index'
Provides-Extra: rag
Requires-Dist: beautifulsoup4>=4.12; extra == 'rag'
Requires-Dist: chromadb>=0.5; extra == 'rag'
Requires-Dist: ebooklib>=0.18; extra == 'rag'
Requires-Dist: langchain-community>=0.3; extra == 'rag'
Requires-Dist: langchain-core>=0.3; extra == 'rag'
Requires-Dist: langchain-text-splitters>=0.3; extra == 'rag'
Requires-Dist: numpy>=1.24; extra == 'rag'
Requires-Dist: odfpy>=1.4; extra == 'rag'
Requires-Dist: openpyxl>=3.1; extra == 'rag'
Requires-Dist: pypdf>=4.0; extra == 'rag'
Requires-Dist: python-docx>=1.1; extra == 'rag'
Requires-Dist: python-pptx>=0.6; extra == 'rag'
Requires-Dist: sentence-transformers>=3.0; extra == 'rag'
Requires-Dist: striprtf>=0.0.26; extra == 'rag'
Requires-Dist: tiktoken>=0.7; extra == 'rag'
Requires-Dist: tokenizers>=0.15; extra == 'rag'
Description-Content-Type: text/markdown

# thehallucinatedlab

The [Hallucinated Lab](https://thehallucinatedlab.space) toolkit — local-first tools you can
call as ordinary Python methods.

Every tool runs on your machine. There is no API key, no account, no service to be up, and
nothing is uploaded anywhere.

```bash
pip install thehallucinatedlab
```

## Use it

```python
from thehallucinatedlab import convert

result = convert("photo.jpg", format="png")
print(result.path, result.bytes)
```

Forgot what a tool takes? The argument reference lives on the website, generated from the
same spec this package validates against — so the docs cannot describe an argument the code
does not accept:

**<https://thehallucinatedlab.space/convert.html>**

## Plain english works too

The same intent parser that powers the website's assistant ships in the package:

```python
from thehallucinatedlab import parse

parse("convert it to webp at 80")
# {'tool': 'convert', 'args': {'format': 'webp', 'quality': 80}, 'missing': [], ...}
```

And from a shell:

```bash
thl tools                                    # every tool and its arguments
thl convert photo.jpg --format webp -q 80
thl "convert photo.jpg to webp at 80"
```

## Tools

### `convert`

Convert an image between PNG, JPEG, WebP and AVIF.

| Argument | Accepts | Default | What it does |
|---|---|---|---|
| `format` | `png` \| `jpeg` \| `webp` \| `avif` | **required** | Target format. Aliases like `jpg` are accepted. |
| `quality` | int 1–100 | `92` | Encoder quality. Ignored for PNG, which is lossless. |
| `background` | hex colour | `#ffffff` | Fills transparency when the target has no alpha channel (JPEG). |

```python
convert("logo.png", format="jpeg", quality=85, background="#000000")
convert(raw_bytes, "out.webp", format="webp")   # bytes and file objects work too
```

Converting a transparent PNG to JPEG flattens it onto `background` rather than leaving black
where the transparency was. AVIF needs Pillow 11.3+ or `pillow-avif-plugin`; if your install
cannot encode a format, you get an `UnsupportedFormat` error rather than a file whose
extension lies about its contents.

## Companion projects

[NexusLink Engine](https://github.com/06pratyush/NexusLinkEngine) is reachable through the
same namespace once its binding is installed:

```python
from thehallucinatedlab import nexuslink

if nexuslink.is_available():
    ...
```

It is built and released separately and is not yet on PyPI, so the import raises
`NexusLinkNotInstalled` with a pointer to the repository until it ships.

## Errors

Everything deliberate inherits from `THLError`:

`ToolNotFound` · `InvalidArgument` · `MissingArgument` · `UnsupportedFormat` ·
`NexusLinkNotInstalled`

## Licence

MIT.
