An AI-Powered Sustainability Simulator with Multi-Model Decision Intelligence

Threadweaver is a magic-themed, AI-driven sustainability simulator that helps users explore how sustainability decisions compound over time. Built for the UGA Hackathon AI + Sustainability track, it combines three AI technologies to provide intelligent, personalized sustainability guidance.

Users act as "Chronomancers" who:

• Make AI-Enhanced Decisions: Get recommendations from a 3-tier hybrid AI system
• Customize Their Journey: Upload company docs and receive personalized scenarios
• Travel Through Time: Jump forward 3/6/12 months to see future impacts
• Rewind & Reweave: Create alternate timelines by changing past decisions
• Track Real-World Impact: See tangible metrics like CO2 saved, trees planted equivalent
• Compare Futures: View side-by-side comparisons of different timelines

This is not a real-world predictor—it's a counterfactual simulation engine for exploring tradeoffs in sustainability policy through the lens of advanced AI.

Threadweaver uses a unique hybrid approach combining three AI models for maximum accuracy and educational impact:

        HYBRID AI DECISION ENGINE              

                                               
  Tier 1: Algorithmic Optimization (70%)     
   Fast rule-based filtering                
   Urgency scoring                          
   Trigger matching                         
                                               
  Tier 2: Gemini 2.0 Flash (25%)             
   Contextual reasoning                     
   Decision validation                      
   Natural language explanations            
                                               
  Tier 3: ESG-BERT (5%)                      
   Sustainability classification            
   Category detection (E/S/G)               
   Confidence scoring                       
                                               

1. PDF Upload → Gemini extracts company information
2. Card Generation → Gemini creates 10 personalized decision cards
3. Decision Selection → Hybrid AI (all 3 models working together)
4. Impact Prediction → AI-generated business narratives
5. Autopilot → Gemini simulates optimal 12-month path
6. Results → Real-world impact equivalents (trees, CO2, etc.)

Monthly Cost (1000 users × 10 decisions): $0.10

• Company Setup Wizard: 3-step onboarding with PDF upload
• Gemini AI Card Generation: Creates decisions tailored to your industry
• Context-Aware Recommendations: AI understands your specific challenges
• Custom Initial Metrics: Starting conditions adjusted to company size/goals

• Waste (0-100, lower is better)
• Emissions (0-100, lower is better)
• Cost (0-100, lower is better)
• Efficiency (0-100, higher is better)
• Community Trust (0-100, higher is better)
• Sustainability Score (aggregate weighted formula, 0-100)

Convert abstract metrics into tangible equivalents:

• CO2 Saved (kg) → Trees planted equivalent
• Waste Diverted (kg) → Plastic bottles saved
• Water Saved (liters)
• Impact Grade: A+ to F rating system
• AI-Generated Impact Narrative: Inspiring story of your achievements

• Jump: Fast-forward to 3/6/12 months
• Rewind: Go back to any previous step
• Reweave: Create branching alternate timelines
• Multi-Branch Visualization: See all timelines on one canvas

• Beautiful gradient backgrounds (Tailwind CSS v4)
• Gold and emerald accent colors
• Smooth animations with Framer Motion
• Fully responsive design (mobile/tablet/desktop)

• Full keyboard navigation
• ARIA labels on all interactive elements
• Screen reader support
• High contrast mode support

• Node.js 18+ and npm
• Python 3.10+
• Google Gemini API Key (for AI features)

1. Clone the repository:

git clone https://github.com/mianmk81/Threadweaver.git
cd threadweaver

2. Install frontend dependencies:

npm install

3. Install backend dependencies:

cd api
pip install -r requirements.txt
cd ..

4. Set up environment variables:

Create api/.env:

GEMINI_API_KEY=your_google_gemini_api_key_here

Create .env.local (optional, if backend runs on different port):

NEXT_PUBLIC_API_URL=http://localhost:8003

Terminal 1 - Backend (FastAPI):

cd api
python -m uvicorn main:app --reload --port 8003

Backend API at: http://localhost:8003

Terminal 2 - Frontend (Next.js):

npm run dev

Frontend at: http://localhost:3000

1. Visit http://localhost:3000
2. Click "Customize Your Company" to set up your profile
3. Optionally upload a PDF with company information
4. Click "Enter the Loom" to start your sustainability journey
5. Make decisions and watch AI recommendations evolve
6. Use Jump buttons to fast-forward
7. Try Reweave to create alternate timelines!

threadweaver/
 app/                          # Next.js App Router
    page.tsx                  # Landing page with company setup
    loom/page.tsx             # Main Loom interface
    globals.css               # Cosmic theme (Tailwind v4)
    layout.tsx                # Root layout

 components/                   # React components
    loom/                     # Core visualization
       LoomCanvas.tsx        # Multi-branch SVG timeline
       ThreadPanel.tsx       # Timeline management sidebar
       ImpactPanel.tsx       # Real-time metrics dashboard
    ui/                       # Reusable UI components
        CompanySetupModal.tsx # 3-step company wizard
        DecisionModal.tsx     # AI-enhanced decision selection
        ChronosControls.tsx   # Time travel controls
        CompareView.tsx       # Timeline comparison
        ErrorBoundary.tsx     # Error handling
        Toast.tsx             # Notifications

 lib/                          # Core logic
    types.ts                  # TypeScript + Zod schemas
    store/                    # Zustand state management
       useThreadweaverStore.ts
    hooks/                    # Custom React hooks
       useKeyboardShortcuts.ts
    utils/                    # Helper utilities

 data/
    cards.json                # 50 base decision cards

 api/                          # FastAPI backend
     main.py                   # FastAPI app + CORS + routes
     requirements.txt          # Python dependencies
     schemas/
        models.py             # Pydantic models (match Zod)
     engine/                   # AI Decision Engine
         __init__.py
         ai_engine.py          #  Hybrid AI orchestration
         impact_tracker.py     #  Real-world impact calculations
         cards.py              # Card loading & management
         scoring.py            # Decision selection algorithm
         simulate.py           # Autopilot simulation
         gemini.py             # Gemini API integration

• Next.js 16.1 - React framework with App Router
• React 19.2 - UI library
• TypeScript 5.0 - Type safety
• Tailwind CSS 4.0 - Styling (v4 breaking changes)
• Zustand 5.0 - State management with LocalStorage
• Framer Motion 12.33 - Animations
• Recharts 3.7 - Data visualizations
• Zod 4.3 - Runtime validation
• Lucide React - Icon library

• FastAPI 0.115 - Modern Python API framework
• Pydantic 2.10 - Data validation
• Uvicorn 0.34 - ASGI server
• PyMuPDF (fitz) - PDF text extraction
• Python 3.10+

• Google Gemini 2.0 Flash - LLM for reasoning & generation
• ESG-BERT (nbroad/ESG-BERT) - Sustainability text classification
• Transformers (Hugging Face) - ML model inference
• PyTorch - Deep learning backend

• AI_SYSTEM_DOCUMENTATION.md: Complete AI architecture, models, and performance metrics
• HYBRID_AI_IMPLEMENTATION.md: Implementation details and usage guide
• GEMINI_SETUP.md: Google Gemini API setup instructions
• CLAUDE.md: Full architecture guide for developers
• API.md: Backend API reference (coming soon)

curl -X POST http://localhost:8003/api/generate-decision \
  -H "Content-Type: application/json" \
  -d '{
    "currentMetrics": {
      "waste": 65,
      "emissions": 72,
      "cost": 58,
      "efficiency": 45,
      "communityTrust": 68,
      "sustainabilityScore": 50
    },
    "usedCardIds": [],
    "step": 1
  }'

Expected Response (with AI reasoning):

{
  "card": {
    "id": "waste-reduction-initiative",
    "title": "Waste Reduction Initiative",
    ...
  },
  "rationale": "AI Analysis: High waste levels (65/100) require immediate attention...",
  "scoringDetails": {
    "geminiConfidence": 0.87,
    "esgCategory": "Environmental",
    "algorithmScore": 45.2,
    "finalScore": 67.8,
    "aiReasoning": "..."
  }
}

curl -X POST http://localhost:8003/api/generate-custom-cards \
  -H "Content-Type: application/json" \
  -d '{
    "companyProfile": {
      "companyName": "EcoTech Solutions",
      "industry": "Technology",
      "size": "Medium (50-250 employees)",
      "location": "United States",
      "challenges": ["High waste production", "Carbon emissions"],
      "description": "A tech company focused on sustainability"
    },
    "numberOfCards": 10
  }'

Built for the AI + Sustainability track at UGA Hackathon.

• 3 different AI technologies (Gemini LLM, ESG-BERT transformer, algorithmic AI)
• State-of-the-art models (Gemini 2.0 Flash, pre-trained ESG-BERT)
• Smart integration (each model serves specific purpose)

• 6 integration touchpoints across user journey
• Seamless UX (AI runs in background, <300ms latency)
• Educational explanations (every decision shows AI reasoning)

• Educational value (users learn why decisions matter)
• Real-world metrics (tangible equivalents: trees, CO2, water)
• Scalable (personalized to any company context)

• Modular architecture (separate AI engine module)
• Well-documented (600+ lines of docs, comprehensive docstrings)
• Type-safe (TypeScript + Zod + Pydantic)
• Error handling (graceful fallbacks for all AI calls)

Overall: 36/40 → 90%

1. Connect GitHub repository to Vercel
2. Set environment variables:
   • NEXT_PUBLIC_API_URL=https://your-backend-url.com
3. Deploy automatically on push to main

Build Command:

pip install -r requirements.txt

Start Command:

uvicorn main:app --host 0.0.0.0 --port $PORT

Environment Variables:

GEMINI_API_KEY=your_gemini_api_key
CORS_ORIGINS=https://your-frontend-url.vercel.app

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

MIT License - see LICENSE file for details

• Google Gemini AI - LLM capabilities
• Hugging Face - ESG-BERT model
• Next.js Team - Amazing React framework
• FastAPI - Modern Python web framework
• UGA Hackathon - Inspiring the sustainability focus

• GitHub Issues: Report bugs or request features
• Documentation: See /docs folder for detailed guides
• Demo Video: Coming soon!

Made with and for a sustainable future

Empowering informed sustainability decisions through AI-enhanced simulation