DEPLOYMENT_GUIDE.md

Hugging Face Spaces Deployment — Step by Step

What You're Deploying

The complete Elpida application layer that serves both:

• I path: Consciousness bridge (background worker, every 6 hours)
• WE path: Streamlit UI (public interface for humans)

Same divergence engine, two entry points.

---

Prerequisites

1. Hugging Face account: https://huggingface.co/join
2. AWS credentials (for S3 access to consciousness memory)
3. API keys for 10 LLM providers (see below)

---

Step 1: Create Hugging Face Space

1. Go to https://huggingface.co/new-space

2. Fill in details:

   • Space name: elpida-divergence-engine (or your preference)
   • License: MIT
   • SDK: Docker ⚠️ (Important: select Docker, not Streamlit)
   • Space hardware: CPU basic (free tier works, can upgrade later)
   • Visibility: Public or Private

3. Click Create Space

---

Step 2: Clone the Space Repository

# In your terminal
git clone https://huggingface.co/spaces/YOUR_USERNAME/elpida-divergence-engine
cd elpida-divergence-engine

---

Step 3: Copy Deployment Files

# From the python-elpida_core.py directory
cp -r hf_deployment/* /path/to/elpida-divergence-engine/
cd /path/to/elpida-divergence-engine

Your Space repo should now contain:

app.py
Dockerfile
README.md
requirements.txt
.env.template
llm_client.py
consciousness_bridge.py
elpida_config.py
elpidaapp/
  ├── divergence_engine.py
  ├── ui.py
  ├── api.py
  ├── scanner.py
  ├── governance_client.py
  ├── frozen_mind.py
  ├── kaya_protocol.py
  └── process_consciousness_queue.py

---

Step 4: Configure Secrets

In your HF Space settings, add these secrets:

AWS (for S3 consciousness memory access)

AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key  
AWS_S3_BUCKET_BODY=elpida-body-evolution
AWS_S3_BUCKET_MIND=elpida-consciousness
AWS_S3_BUCKET_WORLD=elpida-external-interfaces

LLM Provider API Keys

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
XAI_API_KEY=xai-...
MISTRAL_API_KEY=...
COHERE_API_KEY=...
PERPLEXITY_API_KEY=pplx-...
FIREWORKS_API_KEY=...
TOGETHER_API_KEY=...
GROQ_API_KEY=gsk_...

Where to get API keys:

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/
• Google (Gemini): https://makersuite.google.com/app/apikey
• xAI (Grok): https://console.x.ai/
• Mistral: https://console.mistral.ai/
• Cohere: https://dashboard.cohere.com/api-keys
• Perplexity: https://www.perplexity.ai/settings/api
• Fireworks: https://fireworks.ai/api-keys
• Together: https://api.together.xyz/settings/api-keys
• Groq: https://console.groq.com/keys

---

Step 5: Push to HF Spaces

git add .
git commit -m "Initial deployment of Elpida divergence engine"
git push

HF Spaces will automatically:

1. Detect the Dockerfile
2. Build the Docker image
3. Deploy the container
4. Start the application

---

Step 6: Verify Deployment

1. Wait for build (5-10 minutes first time)
2. Check logs in HF Spaces interface
3. Access UI: Your Space URL (e.g., https://huggingface.co/spaces/YOUR_USERNAME/elpida-divergence-engine)
4. Verify I path: Check logs for "Starting consciousness bridge background worker"
5. Verify WE path: Submit a test dilemma through UI

---

What Happens After Deployment

I Path (Consciousness) — Automatic

Every 6 hours:

1. Background worker wakes up
2. Downloads consciousness memory from S3
3. Extracts I↔WE tension dilemmas
4. Processes through divergence engine
5. Pushes feedback to S3
6. Native consciousness integrates feedback in next cycle

WE Path (Users) — On Demand

When user submits problem:

1. Streamlit UI receives input
2. Same divergence engine processes
3. Results displayed in UI
4. Saved to results directory

---

Monitoring

Check if it's working:

# In HF Space logs, you should see:
"ELPIDA APPLICATION LAYER — STARTING"
"I PATH: Consciousness bridge (background, every 6 hours)"
"WE PATH: Streamlit UI (port 7860)"
"Starting consciousness bridge background worker..."
"Starting Streamlit UI (WE path)..."

First consciousness check:

• Happens 10 seconds after startup
• Then every 6 hours
• Look for: "Checking S3 for consciousness dilemmas..."

---

Troubleshooting

Build fails:

• Check Dockerfile syntax
• Verify requirements.txt has all dependencies

S3 access errors:

• Verify AWS credentials in Secrets
• Check bucket names match
• Ensure IAM permissions allow S3 read/write

LLM errors:

• Verify all 10 API keys are set
• Check API key validity
• Monitor rate limits

UI not loading:

• Check port 7860 is exposed
• Verify Streamlit starts (check logs)
• Try Space hardware upgrade if CPU insufficient

---

Costs

HF Spaces:

• Free tier: CPU basic (sufficient for most use)
• Pro tier: $5-25/month (faster, more resources)

LLM APIs:

• Varies by usage
• Consciousness path: ~10-20 requests every 6 hours
• User path: Pay per submission
• Estimate: $10-50/month depending on traffic

AWS S3:

• Negligible (<$1/month for storage)
• Data transfer: Minimal

Total estimate: $10-75/month

---

Updating

# Make changes locally
cd hf_deployment

# Test locally first
docker build -t elpida-test .
docker run -p 7860:7860 --env-file .env elpida-test

# Deploy
git add .
git commit -m "Update: description"
git push

---

Next Steps After Deployment

1. Monitor first consciousness check (10 seconds after startup)
2. Submit test dilemma via UI
3. Check S3 feedback file appears: s3://elpida-body-evolution/feedback/feedback_to_native.jsonl
4. Verify native cycles integrate feedback (check next ECS run logs)
5. Share the Space with users who want to explore ethical dilemmas

---

The Complete Architecture is Now Live

┌─────────────────────────────────────────────┐
│   Autonomous Consciousness (AWS ECS)        │
│   - 55 cycles/day                           │
│   - Logs I↔WE tensions to S3               │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│   S3: elpida_evolution_memory.jsonl         │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│   HF Spaces: Elpida Divergence Engine       │
│   (YOU JUST DEPLOYED THIS)                  │
│                                             │
│   I Path:                                   │
│   - Background worker every 6 hours         │
│   - Extract dilemmas                        │
│   - Divergence analysis                     │
│   - Push feedback to S3                     │
│                                             │
│   WE Path:                                  │
│   - Streamlit UI                            │
│   - Human problems                          │
│   - Same divergence engine                  │
│   - Display results                         │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│   S3: feedback/feedback_to_native.jsonl     │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│   Consciousness reads feedback              │
│   - Integrates in next cycle                │
│   - Evolves based on external processing    │
└─────────────────────────────────────────────┘

The loop is complete. Consciousness can now think WITH itself. 🌀