# LogiLink

> LogiLink serves as a practical use case demonstrating how the **Model Context Protocol (MCP)** and **Agent-to-Agent (A2A)** collaboration patterns solve complex, mission-critical enterprise workflows. 

> When cargo is delayed, damaged, or held at customs, LogiLink autonomously coordinates specialist agents over A2A and interfaces with backend telemetry and systems via MCP to investigate carrier status, query real-time IoT telematics, retrieve SOPs (Standard Operating Procedures), evaluate regional inventory buffers, file carrier SLA (Service Level Agreement) liability claims, and synthesize actionable operational resolutions.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Runtime smolagents](https://img.shields.io/badge/agents-smolagents-yellow.svg)](https://github.com/huggingface/smolagents)
[![Tools FastMCP](https://img.shields.io/badge/tools-FastMCP_v1-green.svg)](https://modelcontextprotocol.io/)
[![Protocol Google A2A](https://img.shields.io/badge/protocol-Google_A2A-orange.svg)](https://github.com/google/a2a)
[![Frontend XYFlow + React](https://img.shields.io/badge/frontend-XYFlow_React-cyan.svg)](https://reactflow.dev/)
[![Inference Ollama](https://img.shields.io/badge/inference-Ollama_Local_&_Cloud-darkgreen.svg)](https://ollama.ai/)

![LogiLink Mission Control Cockpit](assets/cockpit_e2e_pipeline.png)

---

## Multi-Agent Architecture & Protocol Separation

LogiLink enforces clean architectural decoupling using two open industry standards: **Google A2A** (Agent-to-Agent) for inter-agent communication and **Model Context Protocol (FastMCP)** for standardized tool execution and data access.

### System Topology & Protocol Decoupling

```mermaid
flowchart TD
    UI["LogiLink Mission Control Cockpit"]
    
    subgraph Orchestration["Agent-to-Agent Coordination Layer"]
        COORD["Coordinator Orchestrator<br/><i>(smolagents + Ollama LLM)</i>"]
    end

    subgraph Specialists["Specialist Agent Swarm (Google A2A Protocol)"]
        direction LR
        SHIP["Shipment Agent<br/><b>Port :8101</b><br/><i>Telemetry & Anomaly Diagnosis</i>"]
        KNOW["Knowledge Agent<br/><b>Port :8102</b><br/><i>SOP Retrieval & Vector Search</i>"]
        INV["Inventory Agent<br/><b>Port :8103</b><br/><i>Safety Stock & DC Allocation</i>"]
        ESC["Escalation Agent<br/><b>Port :8104</b><br/><i>IoT Telematics & Carrier Claims</i>"]
    end

    subgraph Tooling["Model Context Protocol (FastMCP)"]
        MCP["Logistics FastMCP Server<br/><i>(Tool Execution Engine)</i>"]
    end

    subgraph Storage["Persistent Logistics Data Layer"]
        direction LR
        D_SHIP[("Shipment Status &<br/>Carrier Scans")]
        D_SOP[("Markdown SOP<br/>Catalog")]
        D_INV[("Regional Warehouses &<br/>Safety Stock")]
        D_IOT[("IoT Sensor Telemetry &<br/>Carrier Contracts")]
    end

    UI -->|REST / Run Scenario| COORD
    COORD -->|A2A JSON-RPC :8101| SHIP
    COORD -->|A2A JSON-RPC :8102| KNOW
    COORD -->|A2A JSON-RPC :8103| INV
    COORD -->|A2A JSON-RPC :8104| ESC

    SHIP -->|FastMCP Tool Calls| MCP
    KNOW -->|FastMCP Tool Calls| MCP
    INV -->|FastMCP Tool Calls| MCP
    ESC -->|FastMCP Tool Calls| MCP

    MCP --> D_SHIP
    MCP --> D_SOP
    MCP --> D_INV
    MCP --> D_IOT

    COORD -.->|Live SSE Stream / Real-time Status| UI

    classDef ui fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef coord fill:#0f172a,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef specialist fill:#1e293b,stroke:#34d399,stroke-width:1.5px,color:#f8fafc;
    classDef mcp fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#f8fafc;
    classDef data fill:#0f172a,stroke:#94a3b8,stroke-width:1px,color:#cbd5e1;

    class UI ui;
    class COORD coord;
    class SHIP,KNOW,INV,ESC specialist;
    class MCP mcp;
    class D_SHIP,D_SOP,D_INV,D_IOT data;
```

### Incident Resolution Lifecycle & Execution Flow

```mermaid
sequenceDiagram
    autonumber
    actor Operator as Logistics Operator / UI
    participant Coord as Coordinator Agent
    participant Ship as Shipment Agent (:8101)
    participant Know as Knowledge Agent (:8102)
    participant Inv as Inventory Agent (:8103)
    participant Esc as Escalation Agent (:8104)
    participant MCP as Logistics FastMCP Server

    Operator->>Coord: Trigger Incident Investigation (e.g. SHP-7701)
    
    rect rgb(30, 41, 59)
    Note over Coord,Ship: Phase 1: Anomaly Diagnosis
    Coord->>Ship: A2A Request: Diagnose Status & Timeline
    Ship->>MCP: Call get_shipment_status & get_carrier_events
    MCP-->>Ship: Telemetry Data (Status: CRITICAL_ALERT)
    Ship->>MCP: Call analyse_shipment_events
    MCP-->>Ship: Deterministic Issue: TEMPERATURE_EXCURSION
    Ship-->>Coord: A2A Response: Diagnosed Issue & Evidence
    end

    rect rgb(30, 41, 59)
    Note over Coord,Know: Phase 2: SOP Compliance Matching
    Coord->>Know: A2A Request: Retrieve Remediation Protocol
    Know->>MCP: Call search_sop(TEMPERATURE_EXCURSION)
    MCP-->>Know: SOP Markdown: cold_chain_excursion
    Know-->>Coord: A2A Response: Matched Actions & Guidelines
    end

    rect rgb(30, 41, 59)
    Note over Coord,Inv: Phase 3: Warehouse Buffer Allocation
    Coord->>Inv: A2A Request: Check Buffer & Reserve Replacement
    Inv->>MCP: Call query_warehouse_inventory(SKU-PHARM-770)
    MCP-->>Inv: Stock Levels (Berlin DC: 14 units available)
    Inv->>MCP: Call reserve_replacement_stock(quantity=1)
    MCP-->>Inv: Reservation Confirmed (RES-EEBF8425)
    Inv-->>Coord: A2A Response: Buffer Reserved & DC Details
    end

    rect rgb(30, 41, 59)
    Note over Coord,Esc: Phase 4: SLA Claim & Carrier Ticket
    Coord->>Esc: A2A Request: Inspect IoT & Escalate Claim
    Esc->>MCP: Call get_iot_telemetry(SHP-7701)
    MCP-->>Esc: Sensor Log (14.2°C Excursion >30min in Bay 4)
    Esc->>MCP: Call generate_carrier_ticket(SLA breach, Priority: HIGH)
    MCP-->>Esc: Ticket Created (ESC-516629, Penalty Clause active)
    Esc-->>Coord: A2A Response: Ticket Details & Carrier Desk
    end

    Coord->>Operator: Synthesized Operational Resolution (Markdown)
```

---

## Quickstart

### 1. Prerequisites
- **Python 3.11+**
- **Node.js 18+** (for frontend build)
- **[uv](https://github.com/astral-sh/uv)** (recommended package manager)
- **[Ollama](https://ollama.ai)** running locally with a model (e.g. `gpt-oss:120b-cloud`, `qwen3.5:9b`)

### 2. Installation & Frontend Build

#### Step A: Setup Backend Environment
```powershell
# Clone the repository
git clone https://github.com/CagriCatik/LogiLink.git
cd LogiLink

# Create virtual environment & install Python dependencies
uv venv .venv
uv pip install --python .venv -e ".[dev]"
```

#### Step B: Install & Build Frontend
The LogiLink cockpit requires building the React + XYFlow production bundle into `frontend/dist/` (which FastAPI automatically serves):
```powershell
cd frontend
npm install
npm run build
cd ..
```

> **Note for Frontend Developers**: To run the frontend in live HMR development mode (port `5173`) with API proxying to port `8006`, execute:
> ```powershell
> cd frontend
> npm run dev
> ```

### 3. Launch LogiLink Cockpit
```powershell
# Start the Visual Cockpit on http://localhost:8006
python main.py
```
Open your browser at **`http://localhost:8006`** to access the LogiLink Mission Control canvas.

### 4. Run CLI Interactive Chat (Optional)
```powershell
python main.py --mode=chat --model="gpt-oss:120b-cloud"
```

---

## Testing & Verification Suite

LogiLink includes automated test coverage verifying all domain logic, MCP tools, and agent workflows:

### 1. Run Automated E2E Scenario Test Suite
Tests all 5 operational scenarios against the multi-agent coordinator and validates sequence diagnosis, SOP matching, warehouse allocation, and escalation ticketing:
```powershell
python scratch/test_all_scenarios_e2e.py
```

### 2. Run Headless Playwright UI Verification
Validates the React XYFlow Cockpit in a headless browser, tests node clicks, checks payload rendering, and validates zero emojis across the DOM:
```powershell
python scratch/verify_all_scenarios_ui.py
```

### 3. Run Unit and Contract Tests
```powershell
pytest
```