Installation

Installation

Requirements

• Python 3.10, 3.11, 3.12, or 3.13
• pandas ≥ 1.5, numpy ≥ 1.23, PyYAML ≥ 6, Jinja2 ≥ 3, python-dateutil ≥ 2.8

From PyPI

pip install cleanframe-engine

The distribution name on PyPI is cleanframe-engine; the import package is cleanframe (import cleanframe as cf), and the CLI is cleanframe — or python -m cleanframe, an equivalent alias for every invocation.

Package page: https://pypi.org/project/cleanframe-engine/

Pin a version in a requirements file the usual way:

cleanframe-engine==0.3.1

Check what you got:

cleanframe --version

Extras

Extra	Installs	Needed for
excel	openpyxl	.xlsx / .xlsm
parquet	pyarrow	.parquet
llm	anthropic, openai	LLM-assisted planning
dev	pytest, pytest-cov, openpyxl, ruff, mypy	contributing / CI
all	excel + parquet + llm	full feature set

pip install "cleanframe-engine[excel,parquet]"
pip install "cleanframe-engine[llm]"
pip install "cleanframe-engine[all]"
pip install "cleanframe-engine[dev]"

Straight from git, if you need a change that is not released yet:

pip install "cleanframe-engine @ git+https://github.com/inboxpraveen/Cleanframe"

Legacy .xls

The excel extra (openpyxl) covers .xlsx and .xlsm. Reading a legacy .xls workbook needs a different engine:

pip install xlrd

Writing .xls is refused: pandas emits .xlsx bytes, which Excel rejects under an .xls name. Write .xlsx instead.

From source (editable)

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

Windows consoles that mangle ₹ / €: set PYTHONUTF8=1. The CLI forces UTF-8 stdout itself.

Offline / air-gapped

Rules-only mode needs no network and no API keys:

import cleanframe as cf
result = cf.clean(df, mode="auto")   # llm=None by default

Wheel + dependencies can be vendored with pip download on a connected machine and installed with pip install --no-index --find-links=./wheels cleanframe-engine.

LLM mode requires outbound HTTPS to your chosen provider (or a local Ollama / LM Studio endpoint).

Cross-platform notes

CleanFrame is tested on Windows, macOS, and Linux:

• All paths use pathlib (forward or backslash both work on Windows).
• Text artifacts (recipes, schemas, reports, codegen) are written as UTF-8 with LF newlines on every OS — no Windows CRLF drift in git.
• CSV/TSV reads accept a UTF-8 BOM (common from Excel on Windows).
• Parent directories are created automatically when saving outputs.
• The CLI forces UTF-8 stdout/stderr so ₹ / diff glyphs render on Windows consoles.

Set PYTHONUTF8=1 if a legacy Windows console still mis-decodes Unicode outside the CLI.

Optional environment variables (LLM only)

Variable	Used by
ANTHROPIC_API_KEY	Anthropic
OPENAI_API_KEY	OpenAI (+ fallback for some providers)
OPENROUTER_API_KEY	OpenRouter
GROQ_API_KEY	Groq
OPENAI_BASE_URL	Override base URL for OpenAI-compatible APIs
NO_COLOR	Disable ANSI colours in diff rendering

CleanFrame never stores or logs API keys.