# Phase 0: Streamlit Container Runtime Exploration

## Objective
Validate Streamlit Container Runtime capabilities and identify constraints before proceeding with full POC development. This pre-phase will help us avoid late-stage technical roadblocks and optimize our implementation approach.

## Context
Since Streamlit Container Runtime is a Private Preview feature with limited documentation, we need to understand its practical capabilities, limitations, and development workflow before committing to a 5-7 day POC timeline.

## Exploration Tests

### Test 1: Basic Streamlit App
**Purpose**: Validate core container runtime functionality and deployment process

**Implementation**:
```python
import streamlit as st

st.title("🎵 Spark POC - Hello World")
st.write("Testing Streamlit Container Runtime")

# Basic UI components
name = st.text_input("Enter your name:")
if name:
    st.write(f"Hello, {name}!")

# Test session state
if 'counter' not in st.session_state:
    st.session_state.counter = 0

if st.button("Click me"):
    st.session_state.counter += 1
    st.write(f"Button clicked {st.session_state.counter} times")
```

**Learning Objectives**:
- Container runtime activation process
- Basic Streamlit functionality
- Session state management
- UI rendering performance

### Test 2: Database Connectivity
**Purpose**: Validate Snowflake connections and query capabilities

**Implementation**:
```python
import streamlit as st
import snowflake.connector
import pandas as pd

st.title("🔌 Database Connectivity Test")

try:
    # Test connection to Snowflake
    conn = snowflake.connector.connect(
        # Connection parameters from environment or secrets
    )
    
    # Test query to Chartmetric table
    query = """
    SELECT ARTIST, TRACK, TIKTOK_TRACK_ID 
    FROM DELPHI_EXPLORATION.CHARTMETRIC.TIKTOK 
    LIMIT 5
    """
    
    df = pd.read_sql(query, conn)
    st.write("✅ Database connection successful!")
    st.dataframe(df)
    
    conn.close()
    
except Exception as e:
    st.error(f"❌ Database connection failed: {e}")
    st.write("This helps us understand connection requirements and error handling")
```

**Learning Objectives**:
- Snowflake connector compatibility
- Connection configuration options
- Query performance characteristics
- Error handling patterns

### Test 3: External API Calls
**Purpose**: Test network policies and HTTP request capabilities

**Implementation**:
```python
import streamlit as st
import requests
import json

st.title("🌐 External API Test")

# Test simple HTTP request
test_url = "https://httpbin.org/get"

try:
    response = requests.get(test_url, timeout=10)
    st.write("✅ HTTP request successful!")
    st.json(response.json())
    
except Exception as e:
    st.error(f"❌ HTTP request failed: {e}")

# Test with headers and parameters
st.subheader("Advanced Request Test")
if st.button("Test API with parameters"):
    try:
        params = {"test": "value", "source": "streamlit-container"}
        headers = {"User-Agent": "Spark-POC-Test"}
        
        response = requests.get(test_url, params=params, headers=headers, timeout=10)
        st.write("✅ Advanced request successful!")
        st.json(response.json())
        
    except Exception as e:
        st.error(f"❌ Advanced request failed: {e}")
```

**Learning Objectives**:
- Network access policies
- Request timeout handling
- Header and parameter support
- Error scenarios and debugging

### Test 4: Package Installation
**Purpose**: Validate dependency management and package restrictions

**Test Packages**:
```python
# Test common packages we'll need for POC
required_packages = [
    'requests',       # HTTP requests
    'pandas',         # Data processing
    'apify-client',   # Apify API integration
    'python-dotenv',  # Environment variables
    'snowflake-connector-python'  # Database connectivity
]

import streamlit as st

st.title("📦 Package Installation Test")

for package in required_packages:
    try:
        __import__(package.replace('-', '_'))
        st.write(f"✅ {package} - Available")
    except ImportError:
        st.write(f"❌ {package} - Not available")
```

**Requirements.txt Test**:
```txt
requests>=2.25.1
pandas>=1.3.0
apify-client>=1.0.0
python-dotenv>=0.19.0
snowflake-connector-python>=2.7.0
```

**Learning Objectives**:
- Package installation process
- Version compatibility
- Custom package support
- Dependency resolution

### Test 5: Multi-file Structure
**Purpose**: Validate modular code organization and imports

**File Structure**:
```
spark_hello_world/
├── app.py                 # Main Streamlit app
├── utils/
│   ├── __init__.py
│   ├── database.py        # Database utilities
│   └── api_client.py      # API client utilities
└── requirements.txt
```

**app.py**:
```python
import streamlit as st
from utils.database import test_db_connection
from utils.api_client import test_api_call

st.title("🏗️ Modular Structure Test")

# Test imports
st.write("✅ Successfully imported custom modules")

# Test modular functions
if st.button("Test Database Module"):
    result = test_db_connection()
    st.write(result)

if st.button("Test API Module"):
    result = test_api_call()
    st.write(result)
```

**Learning Objectives**:
- Import system functionality
- File organization best practices
- Module persistence across deployments
- Code reusability patterns

## Success Criteria

### ✅ **Green Light Indicators**
- All basic Streamlit functionality works
- Database connections are stable and performant
- External API calls succeed without restrictions
- Required packages install successfully
- Modular code structure is supported

### ⚠️ **Yellow Light Indicators**
- Some package installation issues (workarounds available)
- Minor performance or connection limitations
- Deployment process requires additional steps
- Some advanced features not supported

### 🚨 **Red Light Indicators**
- Cannot establish Snowflake connections
- External API calls are blocked
- Critical packages unavailable
- Severe performance or stability issues
- Deployment process is unreliable

## Expected Timeline
- **Setup and Test 1-2**: 2-3 hours
- **Test 3-4**: 2-3 hours  
- **Test 5**: 1-2 hours
- **Documentation and Analysis**: 1-2 hours
- **Total**: 6-10 hours (1 full day)

## Deliverables

1. **Working Hello World Apps** - All 5 test applications
2. **Capabilities Assessment** - Detailed report on what works/doesn't work
3. **Limitations Documentation** - Known constraints and workarounds
4. **Best Practices Guide** - Optimal development patterns discovered
5. **Updated Implementation Plan** - Adjustments based on learnings
6. **Go/No-Go Decision** - Recommendation for Container Runtime approach

## Impact on Main POC Timeline

### Best Case (Green Light)
- Proceed with original 5-7 day timeline
- High confidence in technology stack
- Focus purely on feature development

### Moderate Issues (Yellow Light)  
- Add 1-2 days to Phase 1 for workarounds
- Adjust architecture based on discovered limitations
- Update risk mitigation strategies

### Major Problems (Red Light)
- Consider fallback to standard Streamlit deployment
- Re-evaluate technology stack options
- Potentially adjust POC scope or timeline

## Next Steps After Phase 0
Based on the exploration results, we'll update the main implementation plan with:
- Specific deployment procedures
- Known limitations and workarounds
- Optimized development workflow
- Refined timeline and risk assessment