lordvisorad/fairrelay-consolidation-v2

FairRelay Consolidation Engine V2

Advanced AI + Optimization Logistics Consolidation Engine for the FairRelay platform.

Architecture

Ingest → Validate → Feature Engineering → Compatibility Graph →
AI Scoring → Constraint Clustering → Hybrid Optimization →
3D Loading Check → Simulation → Explainability → Feedback Learning

Modules

Module	Description
schemas.py	Complete data models (Shipment, Vehicle, Group, LoadPlan, Run, Explanation)
validation/	Input validation (coordinates, weights, time windows, cargo rules)
feature_engineering/	Pairwise features (route overlap, time overlap, cargo compat, capacity fit)
graph_builder/	Compatibility graph with dense subgraph detection
clustering/	Constraint-aware clustering (respects capacity, cargo rules)
optimizer/	Hybrid solver: CP-SAT (exact) + Greedy + Local Search
loading/	3D loading planner (dimensions, stacking, fragility, unloading sequence)
explainability/	Why grouped? Why rejected? What constraint? With suggestions
simulation/	Multi-scenario comparison + rolling-horizon replanning
feedback_learning/	Operator feedback → parameter adaptation
pipeline.py	Full pipeline orchestrator
api/consolidation_v2.py	FastAPI endpoints

Performance

• 6 shipments optimized in 9.5ms (CP-SAT exact solver)
• 67% trip reduction with 78% average utilization
• Scenario simulation: 4 strategies compared in 22ms
• Rolling replan: event-driven reoptimization in <15ms

API Endpoints

Method	Path	Description
POST	/api/v1/consolidate	Full consolidation pipeline
POST	/api/v1/consolidate/simulate	Compare scenarios (tight/balanced/aggressive/eco)
POST	/api/v1/consolidate/replan	Event-driven replanning
POST	/api/v1/consolidate/feedback	Submit operational feedback
GET	/api/v1/consolidate/explain/{run_id}	Get decision explanations
GET	/api/v1/consolidate/insights	Learning insights + corridor patterns
GET	/api/v1/consolidate/compatibility/{id}	Shipment compatibility scores
GET	/api/v1/consolidate/history	Replan history

Integration

Drop consolidation_v2/ into brain/app/ and add to main.py:

from app.api.consolidation_v2 import router as consolidation_v2_router
app.include_router(consolidation_v2_router)

Generated by ML Intern

This model repository was generated by ML Intern, an agent for machine learning research and development on the Hugging Face Hub.

• Try ML Intern: https://smolagents-ml-intern.hf.space
• Source code: https://github.com/huggingface/ml-intern

Usage

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = 'lordvisorad/fairrelay-consolidation-v2'
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.