meltify 0.1.0__tar.gz

meltify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jeon-jihyeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meltify-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: meltify
+Version: 0.1.0
+Summary: Melt files of any format into prompt-ready text where every line cites its source
+Keywords: llm,prompt,ocr,pdf,transcription,claude-code,agent-skills
+Author: jeon-jihyeon
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: pymupdf>=1.26
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: pillow>=11
+Requires-Dist: numpy>=2
+Requires-Dist: ocrmac>=1.0.1 ; sys_platform == 'darwin'
+Requires-Dist: meltify[office,media,asr-mlx] ; extra == 'all'
+Requires-Dist: mlx-whisper>=0.4 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'asr-mlx'
+Requires-Dist: yt-dlp>=2026.8.19 ; extra == 'media'
+Requires-Dist: paddleocr>=3.2 ; extra == 'ocr-paddle'
+Requires-Dist: paddlepaddle>=3.2 ; extra == 'ocr-paddle'
+Requires-Dist: markitdown[docx,pptx,outlook]>=0.1.8 ; extra == 'office'
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/jeon-jihyeon/meltify
+Provides-Extra: all
+Provides-Extra: asr-mlx
+Provides-Extra: media
+Provides-Extra: ocr-paddle
+Provides-Extra: office
+Description-Content-Type: text/markdown
+
+<h1 align="center">meltify</h1>
+
+<p align="center">Melt files of any format into prompt-ready text where every line cites its source</p>
+
+<p align="center">
+  <a href="https://github.com/jeon-jihyeon/meltify/actions/workflows/test.yml"><img alt="test" src="https://github.com/jeon-jihyeon/meltify/actions/workflows/test.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+</p>
+
+Agents misread blurry digits, miss text a PDF hides, can't watch video, and paraphrase the one condition that mattered. meltify turns images, PDFs, office files, mail, video and audio into markdown an agent can quote, puts a citation on every block, and checks answers before they go out.
+
+## Quickstart
+
+Claude Code:
+
+```
+/plugin marketplace add jeon-jihyeon/meltify
+/plugin install meltify@meltify
+```
+
+Codex, Gemini CLI, Cursor and other agents that read Agent Skills:
+
+```
+npx skills add jeon-jihyeon/meltify
+```
+
+Command line only:
+
+```
+uvx meltify read ./inputs
+```
+
+The skills call the `meltify` command. If it isn't installed, the plugin launcher runs it through `uvx`, so [uv](https://docs.astral.sh/uv/) is the only thing you need.
+
+## What it does
+
+| Command | Input | Output |
+|---|---|---|
+| `read` | files and folders of mixed formats | one cited markdown file per item, plus a list of what still needs OCR, transcription or a hidden-text check |
+| `ocr` | images and scanned PDF pages | each engine's lines with positions, and the values the engines disagree on |
+| `hidden` | PDFs | text a reader doesn't see and why, with page and position |
+| `media` | video, audio or a video URL | timestamped full-resolution frames and a timestamped transcript |
+| `submit` | candidate files and a scoring endpoint | rate-limited submissions that skip duplicates and keep the best score |
+| `check` | an answer file or a string | violations of a schema, counts, unique keys and text rules |
+| `brief` | a problem statement | every condition line quoted with its line number, plus a board for juggling several problems |
+| `doctor` | nothing | which engines, binaries and keys are available, and how to add the rest |
+
+Each command has a skill of the same name, such as `meltify-ocr`, that tells the agent when to run it and what to do with the result.
+
+## Citations
+
+Every result carries `src` and a one-line `cite`:
+
+| Input | Cite |
+|---|---|
+| PDF text | `report.pdf#p3@pt(72,95,140,103)` |
+| Image region | `menu.png@px(120,40,380,72)` |
+| Spreadsheet cell | `calendar.xlsx#Calendar!B7` |
+| Mail attachment | `handover.eml#att=cal.xlsx#Calendar` |
+| Text line | `notes.txt:42` |
+| Media span | `call.m4a@00:01:23.4-00:01:27.0` |
+| JSON value | `answers.json#$[3].reason` |
+
+Every command prints a table by default, and the full result with `--json`. Exit codes:
+
+- `0`: success
+- `1`: violations, failed checks or other errors
+- `2`: usage error or bad input
+- `3`: a needed engine, key, binary or base module is missing
+
+## Engines
+
+| Task | Local | Paid API |
+|---|---|---|
+| OCR | Apple Vision on macOS, PaddleOCR | Gemini, Claude, any OpenAI-compatible endpoint |
+| Speech | MLX Whisper on Apple Silicon, whisper.cpp | any OpenAI-compatible transcription endpoint |
+
+`auto` uses local engines only. Paid engines run only when you name them in `meltify.toml` or on the command line. An agent can also feed in what it reads in an image with `meltify ocr --reading agent=FILE`, so its own reading gets cross-checked against the local engines without any API key.
+
+Optional parts install on request:
+
+```
+meltify doctor --install office      # docx, pptx and Outlook msg
+meltify doctor --install media       # video URLs through yt-dlp
+meltify doctor --install asr-mlx     # local speech on Apple Silicon
+meltify doctor --install ocr-paddle  # PaddleOCR
+```
+
+`media` needs ffmpeg, and YouTube downloads need deno.
+
+## Configuration
+
+Settings are layered, lowest precedence first:
+
+1. The packaged defaults
+2. `$XDG_CONFIG_HOME/meltify/config.toml` (usually `~/.config/meltify/config.toml`)
+3. The nearest `meltify.toml`, searched from the working directory up to the git root, or the file you pass with `--config`. Outside a git repository, only the working directory is searched
+4. `MELTIFY_<KEY>` and `MELTIFY_<SECTION>_<KEY>` environment variables
+5. Command-line flags
+
+See [examples/meltify.toml](examples/meltify.toml) for a sample.
+
+## Limits
+
+- Text drawn inside an image is just pixels, so `hidden` finds it only through `--contrast` rendering and OCR
+- OCR agreement means the engines read the same value, not that the value is right. A value read only by LLM engines is never marked agreed
+- Speech recognition and OCR quality depend on the engine and the input
+- The plugin launcher is a POSIX shell script, so Windows isn't supported
+
+## License
+
+MIT. meltify depends on [PyMuPDF](https://github.com/pymupdf/PyMuPDF), which is AGPL-3.0, so distributing a product that bundles it comes with AGPL obligations.

meltify-0.1.0/README.md

@@ -0,0 +1,112 @@
+<h1 align="center">meltify</h1>
+
+<p align="center">Melt files of any format into prompt-ready text where every line cites its source</p>
+
+<p align="center">
+  <a href="https://github.com/jeon-jihyeon/meltify/actions/workflows/test.yml"><img alt="test" src="https://github.com/jeon-jihyeon/meltify/actions/workflows/test.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+</p>
+
+Agents misread blurry digits, miss text a PDF hides, can't watch video, and paraphrase the one condition that mattered. meltify turns images, PDFs, office files, mail, video and audio into markdown an agent can quote, puts a citation on every block, and checks answers before they go out.
+
+## Quickstart
+
+Claude Code:
+
+```
+/plugin marketplace add jeon-jihyeon/meltify
+/plugin install meltify@meltify
+```
+
+Codex, Gemini CLI, Cursor and other agents that read Agent Skills:
+
+```
+npx skills add jeon-jihyeon/meltify
+```
+
+Command line only:
+
+```
+uvx meltify read ./inputs
+```
+
+The skills call the `meltify` command. If it isn't installed, the plugin launcher runs it through `uvx`, so [uv](https://docs.astral.sh/uv/) is the only thing you need.
+
+## What it does
+
+| Command | Input | Output |
+|---|---|---|
+| `read` | files and folders of mixed formats | one cited markdown file per item, plus a list of what still needs OCR, transcription or a hidden-text check |
+| `ocr` | images and scanned PDF pages | each engine's lines with positions, and the values the engines disagree on |
+| `hidden` | PDFs | text a reader doesn't see and why, with page and position |
+| `media` | video, audio or a video URL | timestamped full-resolution frames and a timestamped transcript |
+| `submit` | candidate files and a scoring endpoint | rate-limited submissions that skip duplicates and keep the best score |
+| `check` | an answer file or a string | violations of a schema, counts, unique keys and text rules |
+| `brief` | a problem statement | every condition line quoted with its line number, plus a board for juggling several problems |
+| `doctor` | nothing | which engines, binaries and keys are available, and how to add the rest |
+
+Each command has a skill of the same name, such as `meltify-ocr`, that tells the agent when to run it and what to do with the result.
+
+## Citations
+
+Every result carries `src` and a one-line `cite`:
+
+| Input | Cite |
+|---|---|
+| PDF text | `report.pdf#p3@pt(72,95,140,103)` |
+| Image region | `menu.png@px(120,40,380,72)` |
+| Spreadsheet cell | `calendar.xlsx#Calendar!B7` |
+| Mail attachment | `handover.eml#att=cal.xlsx#Calendar` |
+| Text line | `notes.txt:42` |
+| Media span | `call.m4a@00:01:23.4-00:01:27.0` |
+| JSON value | `answers.json#$[3].reason` |
+
+Every command prints a table by default, and the full result with `--json`. Exit codes:
+
+- `0`: success
+- `1`: violations, failed checks or other errors
+- `2`: usage error or bad input
+- `3`: a needed engine, key, binary or base module is missing
+
+## Engines
+
+| Task | Local | Paid API |
+|---|---|---|
+| OCR | Apple Vision on macOS, PaddleOCR | Gemini, Claude, any OpenAI-compatible endpoint |
+| Speech | MLX Whisper on Apple Silicon, whisper.cpp | any OpenAI-compatible transcription endpoint |
+
+`auto` uses local engines only. Paid engines run only when you name them in `meltify.toml` or on the command line. An agent can also feed in what it reads in an image with `meltify ocr --reading agent=FILE`, so its own reading gets cross-checked against the local engines without any API key.
+
+Optional parts install on request:
+
+```
+meltify doctor --install office      # docx, pptx and Outlook msg
+meltify doctor --install media       # video URLs through yt-dlp
+meltify doctor --install asr-mlx     # local speech on Apple Silicon
+meltify doctor --install ocr-paddle  # PaddleOCR
+```
+
+`media` needs ffmpeg, and YouTube downloads need deno.
+
+## Configuration
+
+Settings are layered, lowest precedence first:
+
+1. The packaged defaults
+2. `$XDG_CONFIG_HOME/meltify/config.toml` (usually `~/.config/meltify/config.toml`)
+3. The nearest `meltify.toml`, searched from the working directory up to the git root, or the file you pass with `--config`. Outside a git repository, only the working directory is searched
+4. `MELTIFY_<KEY>` and `MELTIFY_<SECTION>_<KEY>` environment variables
+5. Command-line flags
+
+See [examples/meltify.toml](examples/meltify.toml) for a sample.
+
+## Limits
+
+- Text drawn inside an image is just pixels, so `hidden` finds it only through `--contrast` rendering and OCR
+- OCR agreement means the engines read the same value, not that the value is right. A value read only by LLM engines is never marked agreed
+- Speech recognition and OCR quality depend on the engine and the input
+- The plugin launcher is a POSIX shell script, so Windows isn't supported
+
+## License
+
+MIT. meltify depends on [PyMuPDF](https://github.com/pymupdf/PyMuPDF), which is AGPL-3.0, so distributing a product that bundles it comes with AGPL obligations.

meltify-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "meltify"
+version = "0.1.0"
+description = "Melt files of any format into prompt-ready text where every line cites its source"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "llm",
+    "prompt",
+    "ocr",
+    "pdf",
+    "transcription",
+    "claude-code",
+    "agent-skills",
+]
+dependencies = [
+    "pymupdf>=1.26",
+    "openpyxl>=3.1",
+    "httpx>=0.27",
+    "jsonschema>=4.23",
+    "pillow>=11",
+    "numpy>=2",
+    "ocrmac>=1.0.1; sys_platform == 'darwin'",
+]
+
+[[project.authors]]
+name = "jeon-jihyeon"
+
+[project.optional-dependencies]
+office = ["markitdown[docx,pptx,outlook]>=0.1.8"]
+media = ["yt-dlp>=2026.8.19"]
+asr-mlx = ["mlx-whisper>=0.4; sys_platform == 'darwin' and platform_machine == 'arm64'"]
+ocr-paddle = [
+    "paddleocr>=3.2",
+    "paddlepaddle>=3.2",
+]
+all = ["meltify[office,media,asr-mlx]"]
+
+[project.urls]
+Repository = "https://github.com/jeon-jihyeon/meltify"
+
+[project.scripts]
+meltify = "meltify.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = ["ignore:builtin type .* has no __module__ attribute:DeprecationWarning"]
+markers = [
+    "llm: calls a paid LLM API and runs only with MELTIFY_TEST_LLM=1",
+    "heavy: needs a large model download",
+    "macos: needs macOS frameworks",
+]

meltify-0.1.0/pyproject.toml.orig

@@ -0,0 +1,56 @@
+[project]
+name = "meltify"
+version = "0.1.0"
+description = "Melt files of any format into prompt-ready text where every line cites its source"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "jeon-jihyeon" }]
+keywords = ["llm", "prompt", "ocr", "pdf", "transcription", "claude-code", "agent-skills"]
+dependencies = [
+  "pymupdf>=1.26",
+  "openpyxl>=3.1",
+  "httpx>=0.27",
+  "jsonschema>=4.23",
+  "pillow>=11",
+  "numpy>=2",
+  "ocrmac>=1.0.1; sys_platform == 'darwin'",
+]
+
+[project.optional-dependencies]
+office = ["markitdown[docx,pptx,outlook]>=0.1.8"]
+media = ["yt-dlp>=2026.8.19"]
+asr-mlx = ["mlx-whisper>=0.4; sys_platform == 'darwin' and platform_machine == 'arm64'"]
+ocr-paddle = ["paddleocr>=3.2", "paddlepaddle>=3.2"]
+all = ["meltify[office,media,asr-mlx]"]
+
+[project.urls]
+Repository = "https://github.com/jeon-jihyeon/meltify"
+
+[project.scripts]
+meltify = "meltify.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = ["ignore:builtin type .* has no __module__ attribute:DeprecationWarning"]
+markers = [
+  "llm: calls a paid LLM API and runs only with MELTIFY_TEST_LLM=1",
+  "heavy: needs a large model download",
+  "macos: needs macOS frameworks",
+]

meltify-0.1.0/src/meltify/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("meltify")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

meltify-0.1.0/src/meltify/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from meltify.cli import main
+
+sys.exit(main())

meltify-0.1.0/src/meltify/cli.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+
+from meltify import __version__, config
+from meltify.evidence import MISSING, USAGE, Envelope
+from meltify.output import emit
+from meltify.safe import MissingTool
+
+# Each module exposes NAME, HELP, COLUMNS, add_arguments and run.
+# Heavy imports live inside run, so --help and --version start fast
+COMMANDS: list[str] = ["read", "ocr", "hidden", "media", "submit", "check", "brief", "doctor"]
+
+USAGE_ERROR = 2
+
+EXIT_CODES = """exit codes:
+  0  success
+  1  violations, failed checks or other errors
+  2  usage error or bad input
+  3  a needed engine, key, binary or base module is missing"""
+
+
+def _modules() -> list[ModuleType]:
+    return [importlib.import_module(f"meltify.commands.{name}") for name in COMMANDS]
+
+
+def _limit(raw: str) -> int:
+    n = int(raw)
+    if n < 0:
+        raise argparse.ArgumentTypeError(f"must be 0 or more, got {n}")
+    return n
+
+
+def build_parser(modules: Sequence[ModuleType]) -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="print the full result envelope")
+    common.add_argument("--out", type=Path, help="output directory for artifacts")
+    common.add_argument("--config", type=Path, help="project config file instead of meltify.toml")
+    common.add_argument(
+        "--limit", type=_limit, default=50, help="rows shown in the table, 0 for all"
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="meltify",
+        description="Melt files of any format into prompt-ready text, with a citation per item",
+        epilog=EXIT_CODES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"meltify {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    for m in modules:
+        p = sub.add_parser(
+            m.NAME,
+            help=m.HELP,
+            description=m.HELP,
+            epilog=EXIT_CODES,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+            parents=[common],
+        )
+        m.add_arguments(p)
+        p.set_defaults(_module=m)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    modules = _modules()
+    parser = build_parser(modules)
+    args = parser.parse_args(argv)
+    if not getattr(args, "_module", None):
+        parser.print_help(sys.stderr)
+        return USAGE_ERROR
+    module = args._module
+
+    overrides = {"out_dir": str(args.out)} if args.out is not None else None
+    try:
+        settings = config.load(overrides, project=args.config)
+    except config.ConfigError as e:
+        # Report it in the envelope, so --json callers still get valid JSON
+        env = Envelope(command=module.NAME, version=__version__)
+        env.error(USAGE, f"config: {e}")
+        emit(env, as_json=args.json, columns=module.COLUMNS, limit=args.limit)
+        return env.exit_code
+
+    try:
+        env = module.run(args, settings)
+    except MissingTool as e:
+        env = Envelope(command=module.NAME, version=__version__)
+        env.error(MISSING, str(e), e.hint)
+    except (FileNotFoundError, IsADirectoryError, ValueError) as e:
+        # Report bad input in the envelope, so --json callers still get valid JSON
+        env = Envelope(command=module.NAME, version=__version__)
+        env.error(USAGE, f"{type(e).__name__}: {e}")
+    emit(env, as_json=args.json, columns=env.columns or module.COLUMNS, limit=args.limit)
+    return env.exit_code