makecontextsimple 0.1.0

Convert documents to semantic HTML optimized for LLM context - reduces token congestion

MakeContextSimple

Convert documents to semantic HTML optimized for LLM context consumption.

Overview

MakeContextSimple is a Python utility that converts various document formats into clean, semantic HTML optimized for large language model (LLM) consumption. Unlike Markdown-based converters, MakeContextSimple produces HTML that is:

• Token-efficient: Less syntax overhead than Markdown for complex structures
• Semantically rich: HTML tags convey meaning without extra markers
• Machine-parseable: Standard HTML parsers work reliably
• Browser-viewable: Output can be directly viewed in any browser

Supported Formats

Category	Formats
Documents	PDF, DOCX, Markdown
Office	PPTX, XLSX
Web	HTML, XML, RSS
Data	CSV, JSON
Text	Plain text, Code files, Config files
Images	JPG, PNG, GIF, WebP, BMP

Installation

Basic Installation

pip install makecontextsimple

With Optional Dependencies

# For PDF support
pip install makecontextsimple[pdf]

# For Office document support
pip install makecontextsimple[docx,pptx,xlsx]

# For image support
pip install makecontextsimple[image]

# For all formats
pip install makecontextsimple[all]

From Source

git clone https://github.com/makecontextsimple/makecontextsimple.git
cd makecontextsimple
pip install -e ".[all]"

Usage

Command Line

# Convert a file to HTML (output to stdout)
makecontextsimple document.pdf

# Convert with custom output file
makecontextsimple document.pdf -o output.html

# Generate minimal HTML for LLM context
makecontextsimple document.pdf --llm

# List supported formats
makecontextsimple --list-formats

Python API

from makecontextsimple import MakeContextSimple

# Initialize converter
converter = MakeContextSimple()

# Convert a file
result = converter.convert("document.pdf")

# Get full HTML document
html = result.to_full_document()
print(html)

# Get minimal HTML for LLM context
llm_context = result.to_llm_context()

# Save directly to file
converter.convert_to_file("document.pdf", "output.html")

# Convert URL content
import requests
response = requests.get("https://example.com/page.html")
result = converter.convert(response)

Custom Styles

# Use custom CSS
custom_css = """
body { font-family: Arial; max-width: 800px; margin: 0 auto; }
h1 { color: #333; }
"""
result = converter.convert("document.pdf")
html = result.to_full_document(styles=custom_css)

Custom Converters

from makecontextsimple import HTMLConverter, HTMLResult

class MyCustomConverter(HTMLConverter):
    def accepts(self, file_stream, mimetype=None, extension=None, **kwargs):
        return extension == ".myformat"
    
    def convert(self, file_stream, mimetype=None, extension=None, **kwargs):
        content = file_stream.read().decode("utf-8")
        # Custom conversion logic
        html = f"<pre>{content}</pre>"
        return HTMLResult(html=html, title="Custom Format")

# Register custom converter
converter = MakeContextSimple()
converter.register_converter(MyCustomConverter(), priority=0)

Architecture

MakeContextSimple follows a plugin-based converter architecture:

MakeContextSimple (orchestrator)
    ├── HTMLConverter (abstract base)
    │   ├── PDFConverter
    │   ├── DOCXConverter
    │   ├── PPTXConverter
    │   ├── XLSXConverter
    │   ├── ImageConverter
    │   ├── CSVConverter
    │   ├── JSONConverter
    │   ├── XMLConverter
    │   ├── HTMLConverter_Builtin
    │   ├── MarkdownConverter
    │   └── PlainTextConverter
    ├── HTMLBuilder (utilities)
    └── HTMLResult (output container)

Key Components

• MakeContextSimple: Main orchestrator that manages converters and I/O
• HTMLConverter: Abstract base class for all format converters
• HTMLBuilder: Utility class for constructing semantic HTML
• HTMLResult: Container for conversion output with metadata

Why HTML Over Markdown?

Aspect	Markdown	HTML
Token Efficiency	Good	Better (15-20% fewer)
Table Syntax	|---| separators	<table> tags
Semantic Meaning	Relies on conventions	Explicit tags
Parsing	Regex/string ops	Standard parsers
Preview	Needs rendering	Native browser

Token Comparison Example

Markdown (180 tokens):

| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | New York |

HTML (150 tokens):

<table>
<tr><td>Name</td><td>Age</td><td>City</td></tr>
<tr><td>Alice</td><td>30</td><td>New York</td></tr>

Plugin System

MakeContextSimple supports third-party plugins via Python's entry_points:

# In your plugin's pyproject.toml:
[project.entry-points."makecontextsimple.plugin"]
my_plugin = "my_package:register"

# In your plugin:
def register(converter_instance):
    converter_instance.register_converter(MyConverter(), priority=5)

Development

Setup

git clone https://github.com/makecontextsimple/makecontextsimple.git
cd makecontextsimple
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Style

ruff check src/
ruff format src/

License

MIT License

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.