# Un-LOCC Wrapper: An OpenAI SDK Wrapper Building Upon the Research of UN-LOCC
Un-LOCC (Universal Lossy Optical Context Compression) is a Python library that wraps the OpenAI SDK to enable optical compression of text inputs. By rendering text into images, it leverages Vision-Language Models (VLMs) for more efficient token usage, especially when dealing with large text contexts.
## Features
- **Optical Compression**: Converts text into images for VLM-compatible input.
- **Seamless Integration**: Drop-in replacement for OpenAI client with compression support.
- **Synchronous and Asynchronous**: Supports both sync and async OpenAI operations.
- **Flexible Compression**: Customize font, size, dimensions, and more.
- **Efficient Rendering**: Uses fast libraries like ReportLab and pypdfium2 when available, falls back to PIL.
## Installation
```bash
pip install un-locc
```
### Dependencies
- `openai`
- `Pillow` (PIL)
- Optional: `reportlab`, `pypdfium2`, `aggdraw` for enhanced performance
## Quickstart
### Basic Usage
```python
from un_locc import UnLOCC
# Initialize with your OpenAI API key
client = UnLOCC(api_key="your-api-key")
# Compress a message in chat completions
messages = [
{"role": "user", "content": "Summarize this text.", "compressed": True}
]
response = client.chat.completions.create(
model="gpt-4o",
messages=messages
)
```
### Asynchronous Usage
```python
import asyncio
from un_locc import AsyncUnLOCC
async def main():
client = AsyncUnLOCC(api_key="your-api-key")
messages = [
{"role": "user", "content": "Analyze this document.", "compressed": True}
]
response = await client.chat.completions.create(
model="gpt-4o",
messages=messages
)
print(response)
asyncio.run(main())
```
### Responses API with Compression
```python
from un_locc import UnLOCC
client = UnLOCC(api_key="your-api-key")
response = client.responses.create(
model="gpt-4o",
input="Large text to compress",
compression=True
)
```
## Documentation
### Classes
- **`UnLOCC`**: Synchronous wrapper for OpenAI client.
- **`AsyncUnLOCC`**: Asynchronous wrapper for OpenAI client.
Both classes initialize like the OpenAI client: `UnLOCC(api_key="...")`.
### Compression Parameters
Default compression settings (uses built-in Atkinson Hyperlegible Regular font):
```python
{
'font_path': 'AtkinsonHyperlegible-Regular.ttf', # Built-in font
'font_size': 15,
'max_width': 864,
'max_height': 864,
'padding': 20
}
```
Customize by passing a dict to `compressed`:
```python
messages = [
{
"role": "user",
"content": large_text,
"compressed": {
"font_size": 12,
"max_width": 1024,
"max_height": 1024
}
}
]
```
For `responses.create`, pass `compression` as a dict or `True` for defaults.
### Methods
#### Chat Completions
- `client.chat.completions.create(messages, **kwargs)`: Compresses messages with `"compressed"` key.
- `client.chat.completions.create(**kwargs)`: Standard usage.
#### Responses
- `client.responses.create(input, compression=None, **kwargs)`: Compresses `input` if `compression` is provided.
### Content Handling
- **String Content**: Directly compressed into images.
- **List Content**: Processes parts; text parts are compressed, others remain unchanged.
### Rendering Methods
The library selects the fastest available rendering method:
1. **ReportLab + pypdfium2** (fastest, recommended).
2. **ReportLab only**.
3. **PIL fallback** (ultra-fast bitmap).
Ensure fonts are available; defaults to system fonts if not found.
## Tips
Through several trials, I've found that it's much better to embed instructions into plain text and then only compress the large context like this:
```python
messages = [
{
"role": "user",
"content": "Instructions: Summarize the following text."
},
{
"role": "user",
"content": long_text,
"compressed": True
},
]
```
This approach keeps instructions clear and readable while compressing only the bulky content. Alternatively, use it to compress prior chat history for efficient context management.
## License
[Specify your license here, e.g., MIT]
## Contributing
Contributions welcome! Please submit issues and pull requests.
## Related Research
For more details on the library and optimal per model configurations, check out [github.com/MaxDevv/UN-LOCC](https://github.com/MaxDevv/UN-LOCC).
Based on UN-LOCC research for optical context compression in VLMs.
Raw data
{
"_id": null,
"home_page": null,
"name": "un-locc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "MaxDevv <maxdevv@example.com>",
"keywords": "compression, context-compression, openai, optical, vlm",
"author": null,
"author_email": "MaxDevv <maxdevv@example.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/e3/cc049dd8dcc93b4ed77f5ae7ce20cd9eeec1319d683f25d21ab64d6cd057/un_locc-0.1.9.tar.gz",
"platform": null,
"description": "# Un-LOCC Wrapper: An OpenAI SDK Wrapper Building Upon the Research of UN-LOCC\n\nUn-LOCC (Universal Lossy Optical Context Compression) is a Python library that wraps the OpenAI SDK to enable optical compression of text inputs. By rendering text into images, it leverages Vision-Language Models (VLMs) for more efficient token usage, especially when dealing with large text contexts.\n\n## Features\n\n- **Optical Compression**: Converts text into images for VLM-compatible input.\n- **Seamless Integration**: Drop-in replacement for OpenAI client with compression support.\n- **Synchronous and Asynchronous**: Supports both sync and async OpenAI operations.\n- **Flexible Compression**: Customize font, size, dimensions, and more.\n- **Efficient Rendering**: Uses fast libraries like ReportLab and pypdfium2 when available, falls back to PIL.\n\n## Installation\n\n```bash\npip install un-locc\n```\n\n### Dependencies\n\n- `openai`\n- `Pillow` (PIL)\n- Optional: `reportlab`, `pypdfium2`, `aggdraw` for enhanced performance\n\n## Quickstart\n\n### Basic Usage\n\n```python\nfrom un_locc import UnLOCC\n\n# Initialize with your OpenAI API key\nclient = UnLOCC(api_key=\"your-api-key\")\n\n# Compress a message in chat completions\nmessages = [\n {\"role\": \"user\", \"content\": \"Summarize this text.\", \"compressed\": True}\n]\n\nresponse = client.chat.completions.create(\n model=\"gpt-4o\",\n messages=messages\n)\n```\n\n### Asynchronous Usage\n\n```python\nimport asyncio\nfrom un_locc import AsyncUnLOCC\n\nasync def main():\n client = AsyncUnLOCC(api_key=\"your-api-key\")\n messages = [\n {\"role\": \"user\", \"content\": \"Analyze this document.\", \"compressed\": True}\n ]\n response = await client.chat.completions.create(\n model=\"gpt-4o\",\n messages=messages\n )\n print(response)\n\nasyncio.run(main())\n```\n\n### Responses API with Compression\n\n```python\nfrom un_locc import UnLOCC\n\nclient = UnLOCC(api_key=\"your-api-key\")\n\nresponse = client.responses.create(\n model=\"gpt-4o\",\n input=\"Large text to compress\",\n compression=True\n)\n```\n\n## Documentation\n\n### Classes\n\n- **`UnLOCC`**: Synchronous wrapper for OpenAI client.\n- **`AsyncUnLOCC`**: Asynchronous wrapper for OpenAI client.\n\nBoth classes initialize like the OpenAI client: `UnLOCC(api_key=\"...\")`.\n\n### Compression Parameters\n\nDefault compression settings (uses built-in Atkinson Hyperlegible Regular font):\n\n```python\n{\n 'font_path': 'AtkinsonHyperlegible-Regular.ttf', # Built-in font\n 'font_size': 15,\n 'max_width': 864,\n 'max_height': 864,\n 'padding': 20\n}\n```\n\nCustomize by passing a dict to `compressed`:\n\n```python\nmessages = [\n {\n \"role\": \"user\", \n \"content\": large_text,\n \"compressed\": {\n \"font_size\": 12,\n \"max_width\": 1024,\n \"max_height\": 1024\n }\n }\n]\n```\n\nFor `responses.create`, pass `compression` as a dict or `True` for defaults.\n\n### Methods\n\n#### Chat Completions\n\n- `client.chat.completions.create(messages, **kwargs)`: Compresses messages with `\"compressed\"` key.\n- `client.chat.completions.create(**kwargs)`: Standard usage.\n\n#### Responses\n\n- `client.responses.create(input, compression=None, **kwargs)`: Compresses `input` if `compression` is provided.\n\n### Content Handling\n\n- **String Content**: Directly compressed into images.\n- **List Content**: Processes parts; text parts are compressed, others remain unchanged.\n\n### Rendering Methods\n\nThe library selects the fastest available rendering method:\n\n1. **ReportLab + pypdfium2** (fastest, recommended).\n2. **ReportLab only**.\n3. **PIL fallback** (ultra-fast bitmap).\n\nEnsure fonts are available; defaults to system fonts if not found.\n\n## Tips\n\nThrough several trials, I've found that it's much better to embed instructions into plain text and then only compress the large context like this:\n\n```python\nmessages = [\n {\n \"role\": \"user\", \n \"content\": \"Instructions: Summarize the following text.\"\n },\n {\n \"role\": \"user\", \n \"content\": long_text,\n \"compressed\": True\n },\n]\n```\n\nThis approach keeps instructions clear and readable while compressing only the bulky content. Alternatively, use it to compress prior chat history for efficient context management.\n\n## License\n\n[Specify your license here, e.g., MIT]\n\n## Contributing\n\nContributions welcome! Please submit issues and pull requests.\n\n## Related Research\n\nFor more details on the library and optimal per model configurations, check out [github.com/MaxDevv/UN-LOCC](https://github.com/MaxDevv/UN-LOCC).\n\nBased on UN-LOCC research for optical context compression in VLMs.\n",
"bugtrack_url": null,
"license": null,
"summary": "Universal Lossy Optical Context Compression for Vision-Language Models",
"version": "0.1.9",
"project_urls": {
"Changelog": "https://github.com/MaxDevv/Un-LOCC/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/MaxDevv/Un-LOCC#readme",
"Homepage": "https://github.com/MaxDevv/Un-LOCC",
"Issues": "https://github.com/MaxDevv/Un-LOCC/issues",
"Repository": "https://github.com/MaxDevv/Un-LOCC"
},
"split_keywords": [
"compression",
" context-compression",
" openai",
" optical",
" vlm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "084e92df80f8095f8b4e42826e773c3b227ad3b3d9d5905077b8744d73bc67e1",
"md5": "ab0d60c8eed811d860b3d9716daa1835",
"sha256": "0ec44637c355d8cd5d64673fa27bd44647bd40061248f0a20eac117ac7e4aa7f"
},
"downloads": -1,
"filename": "un_locc-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab0d60c8eed811d860b3d9716daa1835",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38820,
"upload_time": "2025-11-05T07:32:27",
"upload_time_iso_8601": "2025-11-05T07:32:27.605035Z",
"url": "https://files.pythonhosted.org/packages/08/4e/92df80f8095f8b4e42826e773c3b227ad3b3d9d5905077b8744d73bc67e1/un_locc-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dde3cc049dd8dcc93b4ed77f5ae7ce20cd9eeec1319d683f25d21ab64d6cd057",
"md5": "884dc50738d9336566ae624c31b4685c",
"sha256": "1a74e6e9e33f440adcca31606ae387632ecc2328448e899a9617457ab76e6219"
},
"downloads": -1,
"filename": "un_locc-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "884dc50738d9336566ae624c31b4685c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 38272,
"upload_time": "2025-11-05T07:32:28",
"upload_time_iso_8601": "2025-11-05T07:32:28.993236Z",
"url": "https://files.pythonhosted.org/packages/dd/e3/cc049dd8dcc93b4ed77f5ae7ce20cd9eeec1319d683f25d21ab64d6cd057/un_locc-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 07:32:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaxDevv",
"github_project": "Un-LOCC",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "openai",
"specs": []
},
{
"name": "Pillow",
"specs": []
}
],
"lcname": "un-locc"
}
JSON
