CoolFace
Apppublic

abhash-chakraborty/Synapse

sourceHugging Faceupdated 1y agoView on Hugging Face
0likes
App README

Project Synapse: Agentic Last-Mile Coordinator

๐ŸŽ‰ COMPLETE SOLUTION: Full-stack AI delivery coordination system with Next.js frontend and MCP integration!

Project Synapse is a sophisticated autonomous AI agent designed to intelligently resolve real-time, last-mile delivery disruptions. This version includes a beautiful Next.js frontend, Model Context Protocol (MCP) integration, and comprehensive tooling for delivery coordination.

๐ŸŒ Live Demo

๐Ÿš€ Deployment

Deploy MCP Server to Hugging Face Spaces

  1. 1.Create a new Space on Hugging Face:
  2. 2.Go to Hugging Face Spaces
  3. 3.Click "Create new Space"
  4. 4.Choose "Docker" as the Space SDK
  5. 5.Set visibility to "Public"
  1. 1.Clone and push your repository:
bash
   git clone https://github.com/your-username/project-synapse.git
   cd project-synapse
   git remote add hf https://huggingface.co/spaces/your-username/project-synapse-mcp
   git push hf main
  1. 1.Configure environment variables in your Space settings:
  2. 2.GOOGLE_API_KEY: Your Google Generative AI API key
  3. 3.PORT: 7860 (default for HF Spaces)

Deploy Frontend to Vercel

  1. 1.Install Vercel CLI (optional):
bash
   npm install -g vercel
  1. 1.Deploy with Vercel:
bash
   cd frontend
   vercel
  1. 1.Or connect your GitHub repository to Vercel for automatic deployments:
  2. 2.Go to Vercel Dashboard
  3. 3.Click "Import Project"
  4. 4.Connect your GitHub repository
  5. 5.Set build settings:
  6. 6.Framework: Next.js
  7. 7.Root Directory: frontend
  8. 8.Build Command: npm run build
  9. 9.Output Directory: .next

Environment Variables for Frontend

Set these in your Vercel project settings:

  • โ€”NEXT_PUBLIC_MCP_SERVER_URL: URL of your deployed MCP server

๐Ÿš€ Quick Start

Automated Start (Recommended)

bash
# Windows
start.bat

# Linux/Mac
./start.sh

Manual Start

bash
# 1. Start MCP Server
python -m src.mcp.server

# 2. Start Frontend (new terminal)
cd frontend
npm install
npm run dev

CLI Only

bash
python -m src.main

โœจ Features

  • โ€”๐ŸŽจ Beautiful Frontend: Modern Next.js dashboard with real-time monitoring
  • โ€”๐Ÿค– Interactive Agent: Test AI scenarios through web interface
  • โ€”๐Ÿ—๏ธ Modular Architecture: Clean separation into focused modules
  • โ€”๐Ÿ”ง MCP Integration: FastAPI-based Model Context Protocol server
  • โ€”๐Ÿ“Š Analytics Dashboard: Tool usage, performance metrics, and activity monitoring
  • โ€”โšก Real-time Updates: Live activity feed and system status
  • โ€”๐Ÿงช Comprehensive Testing: Built-in scenario testing and validation
  • โ€”๏ฟฝ Advanced Debugging: Enhanced logging and error handling

๐Ÿ“ Project Structure

โ”œโ”€โ”€ src/               # Main source code
โ”‚   โ”œโ”€โ”€ core/          # Agent, config, prompts
โ”‚   โ”œโ”€โ”€ tools/         # Categorized delivery tools
โ”‚   โ”œโ”€โ”€ mcp/          # Model Context Protocol server/client
โ”‚   โ”œโ”€โ”€ utils/        # Logging and utilities
โ”‚   โ””โ”€โ”€ main.py       # CLI application
โ”œโ”€โ”€ docs/             # Documentation
โ”œโ”€โ”€ scripts/          # Utility scripts and tools
โ”œโ”€โ”€ frontend/         # Next.js frontend with dashboard
โ”‚   โ”œโ”€โ”€ app/          # Next.js app directory
โ”‚   โ”œโ”€โ”€ components/   # React components
โ”‚   โ””โ”€โ”€ lib/          # Utilities
โ””โ”€โ”€ legacy/           # Original files (preserved)

๐ŸŽจ Frontend Features

The Next.js frontend provides a comprehensive interface for monitoring and interacting with the AI agent:

Dashboard View

  • โ€”๐Ÿ“Š Performance Metrics: Real-time KPIs and success rates
  • โ€”๐Ÿ“ˆ Tool Usage Analytics: Visualization of most-used tools
  • โ€”๐Ÿ”„ Activity Monitor: Live feed of system events
  • โ€”โšก System Health: Server status and performance indicators

Agent Interface

  • โ€”๐Ÿค– Interactive Testing: Submit custom delivery scenarios
  • โ€”๐Ÿ“ Reasoning Display: See the agent's thought process
  • โ€”๐Ÿ”ง Tool Execution: Watch tools being used in real-time
  • โ€”๐Ÿ“‹ Pre-built Scenarios: Test common disruption cases

Sample Scenarios Available

  • โ€”Restaurant overload with long prep times
  • โ€”Damaged packaging disputes at delivery
  • โ€”Recipient unavailability for valuable packages
  • โ€”Traffic obstructions blocking delivery routes

Access the frontend at: http://localhost:3000

๐Ÿ› ๏ธ Available Tools (17 Total)

๐Ÿš› Logistics Tools

  • โ€”get_merchant_status - Check restaurant operational status
  • โ€”check_traffic - Analyze route conditions
  • โ€”reroute_driver - Optimize driver assignments
  • โ€”get_nearby_merchants - Find alternative vendors

๐Ÿ‘ฅ Customer Tools

  • โ€”notify_customer - Send notifications
  • โ€”contact_recipient_via_chat - Real-time communication
  • โ€”suggest_safe_drop_off - Secure delivery locations
  • โ€”find_nearby_locker - Parcel locker options
  • โ€”request_address_clarification - Resolve ambiguous addresses

โš–๏ธ Dispute Tools

  • โ€”initiate_mediation_flow - Start dispute resolution
  • โ€”collect_evidence - Gather photos and statements
  • โ€”analyze_evidence - Determine fault
  • โ€”issue_instant_refund - Process refunds
  • โ€”exonerate_driver - Clear driver of fault
  • โ€”log_merchant_packaging_feedback - Record issues

๐Ÿ” Verification Tools

  • โ€”verify_delivery_attempt - GPS validation
  • โ€”initiate_qr_code_verification - OTP alternatives

๐ŸŒ MCP Server

The project includes a full Model Context Protocol server:

bash
# Start MCP server
python src/mcp/server.py
# Available at: http://localhost:8000

# API Documentation
# http://localhost:8000/docs

Client Usage

python
from src.mcp.client import SynapseMCPClient
import asyncio

async def example():
    async with SynapseMCPClient() as client:
        result = await client.call_tool(
            "get_merchant_status", 
            merchant_name="Pizza Palace"
        )
        print(result)

asyncio.run(example())

๐Ÿงช Testing & Validation

bash
python scripts/test.py          # Comprehensive test suite
python scripts/setup.py --test  # Setup validation  
python scripts/demo.py          # Feature demonstrations
python scripts/start.py check   # Quick health check

๐Ÿ’ก Example Scenarios

Try these in the CLI:

  1. 1.Merchant Overload: "Driver reports Pizza Palace is overloaded with 45-minute wait"
  2. 2.Delivery Dispute: "Customer complains food arrived spilled, customer ID CUST123"
  3. 3.Address Issues: "Driver cannot find address: Room 301, near big temple"
  4. 4.Failed Delivery: "Customer says driver never arrived but marked as failed"

๐Ÿ”ฎ Frontend (Next.js) - Coming Soon

bash
cd frontend
npm run setup
npm run dev

Planned Features:

  • โ€”๐Ÿ“Š Real-time delivery dashboard
  • โ€”๐Ÿ’ฌ Interactive dispute resolution
  • โ€”๐Ÿ“ˆ Agent analytics and monitoring
  • โ€”๐Ÿ”ง Tool usage visualization

๐Ÿ“š Documentation

  • โ€”docs/QUICKSTART.md - 3-step setup guide
  • โ€”docs/REFACTORING_SUMMARY.md - What changed and why
  • โ€”docs/PROJECT_STRUCTURE.md - Clean project organization
  • โ€”frontend/README.md - Frontend development guide

๐ŸŽฏ Key Capabilities

The agent autonomously handles:

  • โ€”Merchant Issues: Overloaded restaurants, delays, alternatives
  • โ€”Customer Communication: Notifications, chat, instructions
  • โ€”Dispute Resolution: Evidence collection, fault analysis, refunds
  • โ€”Delivery Verification: GPS validation, secure confirmations
  • โ€”Address Resolution: Landmark-based navigation assistance

๐Ÿ”ง Requirements

  • โ€”Python 3.9+
  • โ€”Google API Key (Generative AI)
  • โ€”Node.js 18+ (for frontend)

๐Ÿ“„ License

MIT License - See LICENSE file for details.

๐Ÿš€ Ready to revolutionize delivery coordination with modular AI architecture!

Migration Note: Original files preserved in legacy/ directory. New modular structure provides the same functionality with better organization and extensibility.