Distill-Align

Distill-Align: The Structured Reasoning Extraction Factory

A CLI/Python framework that automates the generation of high-quality, fine-tuning datasets from raw domain data. It utilizes high-context frontier reasoning models as teachers, captures their deep thinking traces, and filters/prunes those traces into highly structured instruction-following formats optimized for fine-tuning.

🌐 العربية: README.ar.md — الترجمة العربية لهذا الدليل.

Features

• Smart Ingestion: Async chunking pipelines with semantic-aware splitting for Markdown and Code (PDF, DOCX, HTML, CSV, JSON, Jupyter notebooks, and web pages also supported).
• Multi-Provider Synthesis: Supports OpenAI, Ollama, vLLM, Anthropic Claude, Google Gemini, and Azure OpenAI backends with async worker pools.
• Socratic Transformer: Converts raw reasoning into structured, multi-turn conversational Q&A.
• Scaffold Action Pruner: Strips conversational filler to extract pure tool-calling or structural output.
• LLM-as-Judge Evaluation (optional): Automated quality scoring of generated conversations using a separate judge model, with confidence scores normalized 0–1.
• Preference (DPO) Generation: Create preference pairs from judge-scored conversations for Direct Preference Optimization training.
• Multiple Export Formats: ShareGPT, Alpaca, ChatML, HuggingFace messages (JSONL/JSON), streaming JSON Lines, and Apache Parquet.
• Streaming Export: Export large datasets without loading them entirely into memory using iterative producers.
• Cost Tracking: Pay-as-you-go cost estimation and tracking across all providers with per-request token accounting.
• Unsloth Integration: Auto-generates optimized train.py scripts for Unsloth fine-tuning.
• Rich TUI: Interactive terminal dashboard for monitoring pipeline execution.

Installation

pip install distill-align

# With optional dependencies
pip install distill-align[parquet]   # Parquet export support
pip install distill-align[hub]       # HuggingFace Hub integration
pip install distill-align[all]       # All extras

Quick Start

# Ingest and process data
distill-align ingest --source ./my-docs --output ./chunks.json

# Synthesize conversations (with judge evaluation)
distill-align synthesize \
    --input ./chunks.json \
    --output ./conversations.json \
    --provider openai \
    --model gpt-4o \
    --judge \
    --judge-model gpt-4o-mini

# Export to training format
distill-align export \
    --input ./conversations.json \
    --format hf_messages \
    --output ./dataset

# Generate preference pairs for DPO training
distill-align export \
    --input ./conversations.json \
    --format preference \
    --output ./dpo-pairs

# Launch TUI
distill-align tui

Supported Providers

Export Formats

Project Structure

This project follows a Modular Monolith architecture.

distill-align/
├── src/distill_align/    # Core application package
│   ├── core/             # Config, schemas, logging, caching, checkpointing
│   ├── ingestion/        # Data loaders and chunkers (PDF, DOCX, HTML, code, etc.)
│   ├── synthesis/        # LLM clients, worker pool, prompts, judge, cost tracking
│   │   └── models/       # Provider-specific clients (OpenAI, Anthropic, Gemini, Azure, Ollama, vLLM)
│   ├── exporter/         # Formatters, validator, splitter, preference generator
│   │   └── formatters/   # Output format converters (JSONL, Parquet, ShareGPT, Alpaca, etc.)
│   ├── tui/              # Textual terminal UI
│   └── cli/              # Typer CLI entry points
├── tests/                # Pytest suite
└── docs/                 # Documentation (MkDocs)

Development

1. Clone the repository
2. Install dependencies with Poetry: poetry install
3. Install dev dependencies: poetry install --with dev
4. Run tests: poetry run pytest
5. Run linting: poetry run ruff check src/

License

MIT License - see LICENSE for details.