Basis (commodity trading term) + Mind (intelligence) — A decision support system for physical grain trading operations, transforming scattered market signals into consistent and auditable recommendations.
The Decision Engine standardizes market reading and reduces subjective bias in commodity trading decisions. It formalizes into explicit rules the logic that experienced professionals apply intuitively.
| Axis | Question |
|---|---|
| Physical | Accelerate sales, hold position, or reduce exposure? |
| Hedge | Increase Chicago hedge, hold, or reduce? |
Every recommendation includes a traceable justification showing which signals drove the decision.
- 📊 Weighted Scoring - Combines 5 market indicators into a single [0-100] score
- ⚡ Override Rules - 5 rules that dominate scoring in critical market situations
- 📈 Book Modulation - Adjusts recommendations based on current exposure limits
- 🔍 Full Traceability - Every decision includes detailed justification
- 🎛️ Interactive Simulator - Test any scenario in real-time
┌─────────────────────────────────────────────────────────────────────┐
│ MARKET INPUTS │
│ Premium │ Lineup │ Competitiveness │ FX Rate │ Demand │ Chicago │
└─────────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ SCORING ENGINE │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Lineup │ │Premium │ │ Compet │ │ Demand │ │ FX │ │
│ │ 30% │ │ 25% │ │ 20% │ │ 15% │ │ 10% │ │
│ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ │
│ └──────────┴──────────┴──────────┴──────────┘ │
│ Aggregated Score [0-100] │
└─────────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ OVERRIDE RULES │
│ Logistics │ Joint Drop │ Premium Trap │ Competitiveness │ Spike │
└─────────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ BOOK MODULATION │
│ Exposure Limits │ Hedge Target │ Effective Sizing │
└─────────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ DECISION OUTPUT │
│ Physical Recommendation │ Hedge Recommendation │ Justification │
└─────────────────────────────────────────────────────────────────────┘
# Clone the repository
git clone https://github.com/YOUR_USERNAME/basismind.git
cd basismind
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or: venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txtstreamlit run dashboard/app.pyOpen http://localhost:8501 in your browser.
| Component | Weight | Description |
|---|---|---|
| Lineup | 30% | Real demand: scheduled vessels for shipment |
| Premium | 25% | Price level vs historical (by crop/off-season regime) |
| Competitiveness | 20% | Brazil vs US Gulf FOB spread |
| Demand | 15% | Export pace vs 5-year average |
| FX Rate | 10% | USD/BRL variation (margin modulator) |
Overrides dominate the score when triggered:
| Priority | Override | Condition | Action |
|---|---|---|---|
| 1 | Logistics | Port congestion, strikes | Sell urgently |
| 2 | Joint Drop | Lineup ↓ AND Premium ↓ | Reduce exposure |
| 3 | Premium Trap | Premium ↑ AND Lineup ↓ | Capture via sale |
| 4 | Competitiveness | Spread > +15 USD/ton | Sell |
| 5 | Chicago Spike | >5% rise without fundamentals | Hedge, don't buy |
basismind/
├── src/ # Core engine (12 modules)
│ ├── config.py # Constants and thresholds
│ ├── scoring.py # Scoring engine
│ ├── overrides.py # Override rules
│ ├── engine.py # Main integrated engine
│ └── ...
├── dashboard/ # Streamlit dashboard
│ ├── app.py # Home page
│ └── pages/ # Dashboard pages
│ ├── 1_📊_Dados_Mercado.py
│ ├── 2_🎯_Motor_Decisao.py
│ ├── 3_🔄_Simulador.py
│ ├── 4_📈_Analise.py
│ └── 5_📚_Documentacao.py
├── data/
│ └── mock_generator.py # Synthetic data generator
├── examples/
│ └── demo.py # CLI demonstration
└── notebooks/
└── demo.ipynb # Jupyter notebook
from datetime import date
from src import DecisionEngine, MarketInputs, BookState
# Initialize engine with book state
book = BookState(
exposicao_fisica_pct=30.0,
limite_long_pct=80.0,
limite_short_pct=-50.0,
hedge_atual_pct=45.0,
hedge_meta_pct=60.0,
)
engine = DecisionEngine(book)
# Prepare market inputs
inputs = MarketInputs(
dt=date(2024, 5, 15),
var_semanal_lineup=8.0,
percentil_premium=72.0,
spread_adjusted=5.0,
z_pace=0.5,
var_cambio_5d=-0.8,
chicago_percentile=65.0,
chicago_is_spike=False,
logistics_flag_active=False,
logistics_reason=None,
)
# Run engine
report = engine.run(inputs)
print(f"Score: {report.score_fisico:.1f}")
print(f"Physical: {report.recomendacao_fisica['acao']}")
print(f"Hedge: {report.recomendacao_hedge['acao']}"){
"data_referencia": "2024-05-15",
"score_fisico": 68.5,
"classificacao": "forte",
"recomendacao_fisica": {
"acao": "aumentar",
"intensidade": "moderada",
"sizing_pct": 15.0
},
"recomendacao_hedge": {
"acao": "manter",
"intensidade": "neutra",
"delta_pp": 0.0
},
"componentes": {
"lineup": {"score": 77.0, "var_semanal": 8.0},
"premio": {"score": 72.0, "percentil": 72.0},
"competitividade": {"score": 37.5, "spread": 5.0},
"demanda": {"score": 66.7, "z_pace": 0.5},
"cambio": {"score": 63.3, "var_5d": -0.8}
},
"overrides_ativos": [],
"justificativa": "Strong physical (score 68) | Drivers: lineup strong, premium strong | ..."
}The Decision Engine does NOT:
- Predict future prices
- Replace human judgment
- Capture geopolitical events
- Guarantee results
- Python 3.11+
- Streamlit - Interactive dashboard
- SQLite - Local storage
- Pandas - Data manipulation
MIT License - see LICENSE for details.
Built as a portfolio project demonstrating skills in:
Python • Data Engineering • Trading Systems • Decision Support • Streamlit
Quick Start • Features • Architecture • Usage