📦 LagerPilot-Qwen: The On-Premises § 377 HGB Goods Receipt Auditor & SAP MIGO Assistant

Engineered for German Warehouse Logistics & Commercial Code Compliance: The first open-source, edge-native AI auditor fine-tuned specifically for the #1 legal and financial bottleneck of German warehouse operations: Goods Receipt Reconciliation & Commercial Defect Notice under § 377 German Commercial Code (HGB).

---

🎯 Executive Summary (English / Deutsch)

English

German industrial SMEs lose an estimated €30,000 to €150,000 annually because receiving ramps miss the strict German Commercial Code (§ 377 HGB) objection deadlines. Under § 377 Abs. 2 HGB, if an unannounced shortage, wrong part (Aliud), damaged packaging, or missing certificate is not formally objected to within hours or days, the goods are legally deemed accepted as fulfilling the contract—forfeiting all warranty and damages claims.

LagerPilot-Qwen is an ultra-lightweight, 0.5B-parameter Small Language Model (SLM) running 100% on-premise on cheap CPU edge hardware (mini-PC / NUC / Zebra terminal) with zero cloud fees and zero GDPR exposure. It bridges OCR delivery notes, ERP purchase orders, and physical ramp findings to output:

1. Exact packaging unit conversions (Kartons/Gebinde to Stück).
2. Deterministic 3-tier traffic-light decisions (FREIGABE, MÄNGELRÜGE_ERFORDERLICH, SPERRE).
3. Legally formal German objection notices under § 377 HGB / § 439 BGB.
4. Instant SAP MIGO BAPI movement payloads (101, 103, 122).

Deutsch

Das deutsche Handelsgesetzbuch verzeiht keine Schlamperei an der Rampe: Wer als Kaufmann offene Mängel, Mindermengen oder Falschlieferungen nicht unverzüglich rügt, verliert nach § 377 Abs. 2 HGB alle Gewährleistungsansprüche (Genehmigungsfiktion). Der gängige Stempel „Unter Vorbehalt angenommen“ ist rechtlich wertlos. LagerPilot-Qwen ist die erste spezialisierte Open-Source Edge-KI, die das Beleg- und Einheitenchaos an der Laderampe eliminiert und rechtssichere Prüfprotokolle auf Knopfdruck erzeugt.

---

🏗️ Architecture & Pipeline

flowchart TD
    A["Delivery Slip OCR / PDF / EDI"] --> D{"LagerPilot Edge Engine (Qwen2.5-0.5B + Guardrails)"}
    B["ERP Purchase Order (SAP / proALPHA)"] --> D
    C["Ramp Note & Barcode Scan (GS1-128 / VDA 4902)"] --> D

    D -->|"Clean Match & VPE Conversion"| E["🟢 STATUS: FREIGABE"]
    E --> E1["SAP MIGO 101 (Unrestricted High-Rack)"]

    D -->|"Shortage, Aliud, Damage, MHD"| F["🟡 STATUS: MÄNGELRÜGE_ERFORDERLICH"]
    F --> F1["SAP MIGO 103 (Blocked Stock / Klärplatz)"]
    F --> F2["Automated § 377 HGB Legal Letter"]
    F --> F3["Carrier Reservation on CMR"]

    D -->|"Hazmat Spill, No SDS, Wrong Consignee"| G["🔴 STATUS: SPERRE"]
    G --> G1["SAP MIGO 122 (Return / Annahmeverweigerung)"]
    G --> G2["Immediate Hazmat Containment (ADR/WHG)"]

---

🏆 Comprehensive 10-Use-Case Stress-Test (100% Pass)

Tested against the complete operational spectrum of German contract and industrial logistics:

---

🚀 Quickstart in 3 Ways

1. Run with Docker Compose (Recommended for Production)

Spin up the entire edge stack including the Interactive Warehouse Ramp Terminal:

git clone https://github.com/your-username/LagerPilot-Qwen.git
cd LagerPilot-Qwen
docker compose up -d

Open your browser at http://localhost:8000 to access the tactile touchscreen dashboard.

---

2. Run with Ollama (Local LLM CLI)

LagerPilot is packaged with a dedicated Modelfile for Ollama:

# 1. Build the model into Ollama
ollama create lagerpilot -f Modelfile

# 2. Run interactive goods receipt audits
ollama run lagerpilot

---

3. Native Python / FastAPI (Edge CPU)

# Install dependencies
pip install -r requirements.txt

# Start the REST API and Web Terminal
python3 src/api.py

# Run the full 10-usecase stress test
python3 evaluation/run_all_usecases.py

---

🖥️ Interactive Ramp Terminal (Web UI)

The built-in web terminal at http://localhost:8000 is designed for rugged warehouse tablets and handheld terminals:

• Preset Buttons: One-click loading of all 10 standard German logistics scenarios.
• Hardware Barcode Parser: Decodes GS1-128 and German automotive VDA 4902 barcodes in real time.
• Traffic Light Status: High-contrast FREIGABE (Green), MÄNGELRÜGE (Yellow), and SPERRE (Red).
• 1-Click Legal Notice: Formatted German commercial objection text ready to copy or email to vendors.
• SAP BAPI Generator: Instant preview of BAPI_GOODSMVT_CREATE payloads for ERP dispatch.

---

🔌 Enterprise ERP & Hardware Scanner Integration

SAP S/4HANA & ECC 6.0 Integration

LagerPilot maps audit decisions directly to SAP movement types:

• Movement Type 101 (FREIGABE): Goods receipt for purchase order into unrestricted-use stock.
• Movement Type 103 (MÄNGELRÜGE_ERFORDERLICH): Goods receipt into GR blocked stock (Gesperrter Bestand / Klärplatz).
• Movement Type 122 (SPERRE): Return delivery to vendor (Rücklieferung an den Lieferanten / Annahme verweigert).

Industrial Barcode Scanning (GS1-128 & VDA 4902)

Scan barcodes directly on the ramp:

from src.gs1_parser import IndustrialBarcodeParser

# GS1-128 barcode parsing
barcode_data = IndustrialBarcodeParser.parse_gs1("(01)04012345678901(10)LOT-SKF-881(17)261231(30)50")
# Extracted: GTIN, Charge/Lot, MHD Date, Packaging Count

---

📦 Publishing to Hugging Face & Ollama

Export Standalone Merged Weights

We provide an automated merger script that fuses the fine-tuned LoRA adapter into the base model:

python3 scripts/export_for_ollama.py

The standalone weights are saved to models/lagerpilot_qwen_merged/.

Upload to Hugging Face Hub

huggingface-cli login
huggingface-cli upload your-username/LagerPilot-Qwen2.5-0.5B-HGB ./models/lagerpilot_qwen_merged/ .

Quantize to GGUF for Ollama

python3 /path/to/llama.cpp/convert_hf_to_gguf.py models/lagerpilot_qwen_merged --outfile models/lagerpilot-q8_0.gguf --outtype q8_0
ollama create your-username/lagerpilot -f Modelfile
ollama push your-username/lagerpilot

---

📁 Repository Structure

lagerAI/
├── Dockerfile                         # Container build for edge deployment
├── docker-compose.yml                 # 1-command startup stack
├── Modelfile                          # Native Ollama manifest
├── README.md                          # Production documentation & guide
├── requirements.txt                   # Minimal pinned dependencies
├── data/
│   ├── generate_warehouse_dataset.py  # Realistic German goods receipt dataset generator
│   ├── train_dataset.json             # 100 fine-tuning samples
│   └── val_dataset.json               # 20 validation samples
├── models/
│   ├── lagerpilot_qwen/               # LoRA adapter weights (2.1 MB)
│   └── lagerpilot_qwen_merged/        # Merged standalone fp32 model
├── src/
│   ├── api.py                         # FastAPI microservice & Web UI endpoint
│   ├── config.py                      # Prompts & system instructions
│   ├── erp_connector.py               # SAP S/4HANA BAPI & proALPHA payload generator
│   ├── gs1_parser.py                  # GS1-128 & VDA 4902 industrial barcode decoder
│   ├── inference.py                   # On-prem CPU engine with safety guardrails
│   ├── train.py                       # PEFT LoRA training pipeline
│   └── web_ui.html                    # Rugged touchscreen warehouse terminal
├── evaluation/
│   ├── test_cases.json                # Initial 5 benchmark cases
│   ├── benchmark.py                   # 5-case benchmark suite
│   ├── comprehensive_test_suite.json  # 10-usecase full industrial stress test
│   ├── run_all_usecases.py            # Comprehensive evaluation runner
│   └── comprehensive_report.json      # Verified 100% test report output
└── scripts/
    └── export_for_ollama.py           # LoRA weight fusion utility

---

🔬 Domain Modeling & Methodology

LagerPilot-Qwen was developed through practical domain modeling of German contract logistics (Mittelstand Kontraktlogistik) and statutory commercial law. Rather than relying on generic LLM summarization, the system's operational scenarios and deterministic guardrails are modeled directly on:

• Statutory Jurisprudence: BGH case law governing the strict 1–2 business day commercial defect notification deadlines under § 377 HGB, the legal fiction of deemed acceptance (§ 377 Abs. 2 HGB), and B2B cure rights (§ 439 BGB).
• Industrial Standards: Packaging unit conversion rules (Kartons/Gebinde to base pieces), GS1-128 / VDA 4902 transport labels, and EN 10204 3.1 mill certificate requirements.
• Ramp Safety Protocols: Zero-tolerance hard overrides for statutory hazardous materials under ADR, GGVSEB, REACH, and the German Water Resources Act (§ 22 WHG).

---

⚖️ Legal & Compliance Notice

LagerPilot-Qwen is designed to assist warehouse personnel in commercial goods receipt inspection (§ 377 HGB). It generates draft commercial notices and ERP recommendations. Users should review high-liability notices with internal legal counsel. Released under the Apache 2.0 License.