This repository contains the complete hands-on tutorial files for learning Vulcan's hybrid AI approach through supply chain risk automation. Read the full tutorial here to understand the concepts and architectural decisions behind this implementation.

Step 1: Create Your Own Repository

Click the "USE THIS TEMPLATE" button below to create your own repository:

Step 2: Launch Codespaces

Once your new repository is created, click the "Open in GitHub Codespaces" button below:

This will take you to the Codespaces page where you need to:

1. Select your new repository from the "Repository" dropdown (it should be named something like your-username/vulcan-tutorial)
2. Choose "main" branch (usually selected by default)
3. Click "Create codespace on main"
4. Wait for setup (2-3 minutes) - dependencies will install automatically

Step 3: Configure API Keys (Optional)

During Codespace creation, you'll be prompted to enter:

• OPENAI_API_KEY (recommended for real AI examples)
• GEMINI_API_KEY (alternative to OpenAI)

Step 4: Start Learning

Once your Codespace loads, run:

./demo 1 # Mock simulation (works immediately, no API keys required!)

1. Fork this repository
2. Open your fork in Codespaces
3. Run: ./demo 1

Clone this repository to the desired location and run:

cd vulcan-tutorial
pip install -r requirements.txt
chmod +x demo
./demo 1  # Mock simulation (no API key required)

• Why LLM+RAG fails for complex business automation
• Hybrid architecture that combines AI flexibility with computational reliability
• Microprompting techniques that reduce AI hallucination risk
• Forward-chaining rules that create intelligent automation cascades
• Advanced patterns for AI-enhanced decision systems

This tutorial follows a carefully designed 2-stage progression:

./demo 1  # Default - works immediately, no API key required

• ✅ Perfect for learning - demonstrates concepts without API complexity
• Shows microprompting methodology with deterministic responses
• Identical output format to real AI for easy comparison

./demo 1 --gemini     # Requires GEMINI_API_KEY
./demo 1 --openai     # Requires OPENAI_API_KEY  

• ⚙️ Real LLM integration - experience authentic AI behavior with error handling
• Supports both OpenAI and Gemini providers
• Identical rule structure to mock - seamless transition

./demo 1 --gemini --enhanced   # Advanced patterns with fallbacks
./demo 4 --openai --enhanced   # Critical keyword override demo

• 🛡️ Advanced safeguards - deterministic fallback guardrails
• Shows how to override AI decisions for critical business scenarios

./demo 1      # Tariff crisis triggers supplier switching
./demo 2      # Normal operations, no alerts  
./demo 3      # Shipping delays, monitoring alert only
./demo 4      # Enhanced rules override demonstration

./demo --help # Complete command reference

When you create a Codespace, you'll be prompted to enter your API keys. These are stored securely and persist across sessions.

Create a .env file in the root folder and paste your API key:

OPENAI_API_KEY=your_openai_key_here    # Preferred provider
GEMINI_API_KEY=your_gemini_key_here    # Alternative provider

💡 Pro Tip: Start with ./demo 1 - it works immediately without any API keys!

├── 📄 LICENSE                    # MIT License
├── 📄 README.md                  # This file
├── 🚀 demo                       # Bash launcher (./demo 1)
├── 🐍 demo.py                    # Python launcher (python demo.py 1)
├── 📁 events/                    # Test scenarios
│   ├── event-1.txt              #   └─ Tariff crisis (HIGH risk)
│   ├── event-2.txt              #   └─ Normal operations (LOW risk)  
│   ├── event-3.txt              #   └─ Shipping delays (MEDIUM risk)
│   └── event-4.txt              #   └─ Enhanced rules demo
├── 📁 prompts/                   # AI prompt templates
│   └── ai-reasoning-prompt.txt  #   └─ Microprompting template
├── 📄 requirements.txt           # Python dependencies
├── 📁 runners/                   # Stage implementations
│   ├── __init__.py              #   └─ Package marker
│   ├── ai_integration.py        #   └─ Real AI integration (Stage 2)
│   └── mock_simulation.py       #   └─ Mock AI simulation (Stage 1)
└── 📁 supply_chain/             # Core tutorial package
    ├── __init__.py              #   └─ Package marker
    ├── initial_state.py         #   └─ Baseline facts
    ├── prompt_loader.py         #   └─ Template management
    ├── rules_ai_baseline.py     #   └─ Real AI rules (baseline)
    ├── rules_ai_enhanced.py     #   └─ Real AI + fallback guardrails
    ├── rules_mock.py            #   └─ Mock AI simulation rules
    └── schema.py                #   └─ Domain model (Facts)

Traditional LLM+RAG Problems:

• ❌ Unreliable decision making under pressure
• ❌ Poor audit trails for business decisions
• ❌ Difficulty managing complex rule interdependencies
• ❌ High risk of hallucination in critical scenarios

Vulcan's Hybrid Solution:

• ✅ AI for intelligent classification - natural language understanding
• ✅ Computational logic for business rules - guaranteed reliability
• ✅ Microprompting approach - reduces hallucination risk
• ✅ Forward-chaining automation - complex cascades from simple rules
• ✅ Complete audit trails - explainable business decisions

• Tutorial Article: Read the full tutorial (comprehensive walkthrough)
• Vulcan Documentation: Full documentation here

This tutorial is designed to be self-contained and educational. If you find areas for improvement or have suggestions for additional scenarios, please open an issue or submit a pull request.

MIT License - see LICENSE file for details.