PlanLang

A Python-embedded DSL for production planning that reduces typical scripts from 200 lines to 20 lines.

Overview

PlanLang is a domain-specific language designed for production planning workflows. It provides:

• URI-based data sources: profab://orders, excel://file.xlsx!Sheet1, json://data.json
• Chainable operations: Filter, transform, sort with pipe syntax
• Domain helpers: Material calculation, sequence optimization, stock tracking
• Smart Excel parsing: Handles messy human-formatted planning files

Quick Start

from planlang import plan

# Fetch orders from ERP
orders = plan.fetch("profab://orders?week=51")

# Calculate materials needed
bom = plan.fetch("profab://composition")
materials = plan.calculate_materials(orders, bom=bom)

# Optimize production sequence
schedule = plan.optimize_sequence(orders, changeover_costs={
    'allergen': 90,   # 90 min cleaning
    'conical': 30,    # packaging change
})

# Export to Excel
plan.write("excel://planning.xlsx!Schedule", schedule)

Installation

git clone https://github.com/yourusername/planlang.git
cd planlang
pip install -e .

Features

Data Source URIs

# ERP API (mock)
plan.fetch("profab://orders?week=51")
plan.fetch("profab://composition")
plan.fetch("profab://stock")

# Excel - clean tabular data
plan.fetch("excel://products.xlsx!Artikelfile")

# Excel - messy human-formatted files
plan.fetch("excel://planning.xlsx!Blad1", parser='smart')

# JSON and CSV
plan.fetch("json://data/products.json")
plan.fetch("csv://export/items.csv")

Chainable Operations

result = (plan.fetch("profab://orders")
    | plan.filter(lambda x: x['quantity'] > 100)
    | plan.sort('delivery_date')
    | plan.select(['customer', 'product_code', 'quantity'])
    | plan.head(10)
)

Domain Helpers

# Material requirement planning
materials = plan.calculate_materials(orders, bom=bom, stock=stock)

# Production sequence optimization
schedule = plan.optimize_sequence(orders, changeover_costs={...})

# Stock monitoring with alerts
status = plan.track_stock(current_stock=stock, lead_time=14)

Examples

See the examples/ directory for complete workflows:

• production_planning.py: Full weekly planning workflow
• stock_alerts.py: Stock monitoring and alerts
• data_migration.py: Import messy Excel, export clean format

Run examples:

python examples/production_planning.py
python examples/stock_alerts.py
python examples/data_migration.py

Documentation

Full documentation available in docs/user_guide.md.

Testing

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install pandas openpyxl xlsxwriter pytest pytest-cov

# Run tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=src --cov-report=term-missing

Test Results:

• 58 tests passing
• 70% code coverage

Project Structure

planlang/
├── src/
│   ├── __init__.py          # Package entry point
│   ├── parser.py             # URI parsing
│   ├── engine.py             # Core PlanEngine
│   ├── adapters/
│   │   ├── excel.py          # Excel adapter (clean + smart modes)
│   │   ├── profab.py         # Mock Profab ERP API
│   │   ├── json_adapter.py   # JSON files
│   │   └── csv_adapter.py    # CSV files
│   └── domain/
│       ├── materials.py      # Material calculations
│       ├── optimization.py   # Sequence optimization
│       └── stock.py          # Stock tracking
├── test_data/
│   ├── mock_profab/          # Mock API data
│   └── *.xlsx                # Sample Excel files
├── tests/                    # Test suite
├── examples/                 # Example scripts
└── docs/
    └── user_guide.md         # Documentation

Use Case

Originally designed for food production planning:

• Fetches orders from ERP systems
• Calculates material requirements from BOM
• Optimizes production sequence (minimizing changeover costs)
• Handles allergen scheduling and constraints
• Exports weekly plans to Excel

But generalizes to any production planning workflow!

License

MIT License - See LICENSE file for details.

Contributing

Contributions welcome! Please read the contributing guidelines before submitting PRs.