Installation

This guide covers the complete installation of Dream Foundry, including all sponsor integrations (Daytona, Sentry, CodeRabbit, ElevenLabs) and environment configuration.

Prerequisites

Python 3.12 or higher

Verify your Python version:

python --version
# Output: Python 3.12.0 or higher

If you need to install Python 3.12:

brew install [email protected]

Git

git --version
# Should return git version 2.x or higher

Virtual Environment (Recommended)

Create an isolated Python environment:

python -m venv venv

# Activate the environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

Using a virtual environment prevents dependency conflicts with other Python projects.

Clone the repository

git clone <repository-url>
cd dream-foundry

Install Python dependencies

pip install -r requirements.txt

This installs all required packages:

Core Dependencies

python-dotenv>=1.0.0    # Environment variables
pydantic>=2.0.0         # Data validation
httpx>=0.25.0           # Async HTTP client
aiohttp>=3.9.0          # Async I/O
requests>=2.31.0        # HTTP requests

UI & CLI

streamlit>=1.30.0       # Demo web UI
typer>=0.9.0            # CLI framework
rich>=13.0.0            # Terminal formatting

Web Scraping (for agents)

beautifulsoup4>=4.12.0  # HTML parsing
lxml>=5.0.0             # XML/HTML parser
selenium>=4.16.0        # Browser automation
feedparser>=6.0.0       # RSS/Atom feeds

Integrations

sentry-sdk>=1.39.0      # Error monitoring

Testing & Utils

pytest>=8.0.0
pytest-asyncio>=0.23.0
pytest-json-report>=1.5.0
tenacity>=8.2.0         # Retry logic
python-dateutil>=2.8.0  # Date parsing

Verify installation

Run a quick test to ensure all imports work:

python -c "import streamlit, bs4, selenium, sentry_sdk; print('✅ All dependencies installed')"

Environment Configuration

Dream Foundry supports multiple execution modes depending on which API keys you configure.

Basic Setup (No API Keys)

For local testing, no API keys are required. The forge runs in local mode:

✅ All 5 agents execute
✅ Scoring and winner selection
✅ Artifact generation
❌ No Daytona sandboxes (runs locally)
❌ No Sentry error tracking
❌ No Discord publishing
❌ No ElevenLabs narration

Full Setup (All Integrations)

Create environment file

touch .env

Open .env in your text editor and add the following:

.env

# Daytona - Isolated sandbox execution
DAYTONA_API_KEY=your_daytona_api_key_here

# Sentry - Error monitoring and alerting
SENTRY_DSN=https://[email protected]/project_id

# Discord - Publish winner announcements
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your_webhook_url

# ElevenLabs - Winner narration and voice synthesis
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

Get Daytona API Key

Purpose: Run each agent in isolated sandboxes for true parallel execution and security.

Sign up at daytona.io
Navigate to Settings → API Keys
Generate a new API key
Copy the key to your .env file

Verify:

python forge.py --daytona "Test objective"

You should see:

Execution: DAYTONA

Without DAYTONA_API_KEY, the --daytona flag automatically falls back to local execution.

Get Sentry DSN

Purpose: Capture and monitor agent failures in real-time (especially Agent Delta crashes).

Sign up at sentry.io
Create a new project (select Python)
Copy the DSN from the project settings
Add to .env as SENTRY_DSN

Verify:

python -c "import sentry_sdk, os; from dotenv import load_dotenv; load_dotenv(); sentry_sdk.init(dsn=os.getenv('SENTRY_DSN')); sentry_sdk.capture_message('Test from Dream Foundry'); print('✅ Sentry configured')"

Check your Sentry dashboard for the test event.

Integration Point: In forge.py:175-182, when a candidate fails, the error is automatically captured:

forge.py

try:
    import sentry_sdk
    sentry_sdk.capture_message(
        f"Candidate {candidate_id} failed: {error_message[:200]}",
        level="error"
    )
except:
    pass

Get Discord Webhook URL

Purpose: Publish the winner’s output directly to a Discord channel.

Open your Discord server
Go to Server Settings → Integrations → Webhooks
Click “New Webhook”
Name it “Dream Foundry Winner”
Select the target channel
Copy the webhook URL
Add to .env as DISCORD_WEBHOOK_URL

Verify:

python -c "import os, requests; from dotenv import load_dotenv; load_dotenv(); requests.post(os.getenv('DISCORD_WEBHOOK_URL'), json={'content': '✅ Dream Foundry webhook test'})"

You should see a message in your Discord channel.

Integration Point: After the winner is selected, you can publish to Discord:

src/discord_poster.py

def post_winner_announcement(
    winner_id: str,
    winner_score: float,
    artifact_content: str,
    objective: str
) -> tuple[bool, str]:
    """Post winner to Discord via webhook."""
    webhook_url = os.getenv("DISCORD_WEBHOOK_URL")
    # ... formatting and posting logic

Get ElevenLabs API Key

Purpose: Generate voice narration for winner announcements in the Streamlit UI.

Sign up at elevenlabs.io
Navigate to Profile → API Keys
Generate a new API key
Add to .env as ELEVENLABS_API_KEY

Verify:

streamlit run app.py

Navigate through the demo to Phase 9 (Showcase). You should see an “Generate & Play Audio” button.

ElevenLabs is only used in the Streamlit UI for presentation purposes. The CLI (forge.py) does not use voice synthesis.

Configuration Levels

You can configure Dream Foundry at different levels:

Minimal

No API KeysPerfect for:

Local testing
Understanding the flow
Developing custom agents

python forge.py

Standard

Daytona + SentryPerfect for:

Production usage
Isolated execution
Error monitoring

.env

DAYTONA_API_KEY=...
SENTRY_DSN=...

Full Demo

All IntegrationsPerfect for:

Hackathon demos
Presentations
Full feature showcase

.env

DAYTONA_API_KEY=...
SENTRY_DSN=...
DISCORD_WEBHOOK_URL=...
ELEVENLABS_API_KEY=...

Additional Setup (Optional)

Selenium WebDriver (for Agent Beta)

Agent Beta uses Selenium for JavaScript-rendered pages. Install a browser driver:

# macOS
brew install chromedriver

# Ubuntu/Debian
sudo apt install chromium-chromedriver

# Windows
choco install chromedriver

Verify:

chroniumdriver --version
# Should output version number

If you skip this step, Agent Beta will fail gracefully and be scored accordingly. The forge will still complete with the other 4 agents.

CodeRabbit Integration (Advanced)

CodeRabbit is simulated in the Streamlit UI for demo purposes. To integrate real CodeRabbit PR reviews:

Install the CodeRabbit GitHub App
Grant access to your Dream Foundry repository
Create a PR from the winner’s branch
CodeRabbit will automatically review

The Streamlit UI (Phase 6: Forge Runoff - Polish) shows example before/after diffs to demonstrate the concept. Real CodeRabbit reviews require GitHub integration.

Verification

Run the complete test suite to verify everything works:

python forge.py --daytona

Expected output:

Environment Check

DREAM FOUNDRY - Forge Loop
============================================================
Objective: Generate weekly 'AI Events in San Francisco' post for Discord
Candidates: 5
Execution: DAYTONA  ✅
[Sentry] Initialized  ✅

Candidate Execution

PHASE: Running Candidates
----------------------------------------
[Agent Alpha] Starting...
[Agent Alpha] Done (4.2s)

[Agent Beta] Starting...
[Agent Beta] Done (28.5s)

[Agent Gamma] Starting...
[Gamma] Verified: Daytona HackSprint SF
[Gamma] Found 10 verified events
[Agent Gamma] Done (3.1s)

[Agent Delta] Starting...
[Error] Timeout after 60 seconds
[Sentry] Error captured  ✅

[Agent Epsilon] Starting...
[Agent Epsilon] Done (2.8s)

Scoring & Winner

============================================================
PHASE: Scoring
----------------------------------------
Candidate     Success  Quality    Speed    TOTAL
----------------------------------------------
gamma        PASS     94.4       89.7     94.4  🏆
beta         PASS     91.5       5.0      61.9
epsilon      PASS     54.5       90.7     63.1
alpha        PASS     75.6       86.0     77.2
delta        FAIL     0.0        0.0      0.0

============================================================
WINNER: gamma (score: 94.4)
============================================================

Artifacts

Artifacts produced:
  - artifacts/alpha/discord_post.md [exists]
  - artifacts/beta/discord_post.md [exists]
  - artifacts/gamma/discord_post.md [exists]  🏆
  - artifacts/delta/discord_post.md [missing]
  - artifacts/epsilon/discord_post.md [exists]
  - artifacts/scores.json
  - artifacts/winner.txt

Troubleshooting

ModuleNotFoundError: No module named 'streamlit'

You’re likely not in the virtual environment or didn’t install dependencies:

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Reinstall dependencies
pip install -r requirements.txt

Daytona not configured, falling back to local

This means DAYTONA_API_KEY is not set or invalid:

# Check .env file exists
cat .env | grep DAYTONA

# Verify the key is correct (should start with 'dtna_')
# Re-generate key from daytona.io if needed

Sentry events not appearing

Common issues:

Wrong DSN format: Should be https://[email protected]/...
Project not configured: Create a new Python project in Sentry
Firewall blocking: Ensure outbound HTTPS to sentry.io is allowed

Test manually:

python -c "import sentry_sdk; sentry_sdk.init(dsn='YOUR_DSN'); sentry_sdk.capture_message('test'); import time; time.sleep(2)"

Discord webhook returning 404

The webhook URL expired or was deleted:

Go back to Discord Server Settings → Integrations → Webhooks
Verify the webhook still exists
Copy a fresh URL if needed
Update .env

Test:

curl -X POST "YOUR_WEBHOOK_URL" -H "Content-Type: application/json" -d '{"content": "test"}'

Selenium WebDriverException

ChromeDriver not installed or wrong version:

# Check Chrome version
google-chrome --version

# Install matching ChromeDriver
brew install chromedriver  # macOS

# Or download from:
# https://chromedriver.chromium.org/downloads

Alternatively, Agent Beta will fail gracefully. The forge continues with other agents.

Rate limiting from lu.ma / Meetup

Running the forge repeatedly triggers rate limits:

Solution 1: Wait 5 minutes between runs
Solution 2: Use --daytona flag to isolate requests
Solution 3: Implement custom caching (see candidates/agent_gamma.py:26-52 for event list)

Python version mismatch

Dream Foundry requires Python 3.12+ for modern type hints:

python --version
# If < 3.12, install Python 3.12:

# macOS
brew install [email protected]

# Create new venv with correct version
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Next Steps

Quickstart

Run your first forge in 5 minutes

Architecture

Understand the 5-phase Dream Foundry pipeline

Custom Agents

Build your own competing agent

Scoring System

Deep dive into the scoring rubric

Pro Tip: Start with the minimal setup (no API keys) to understand the flow, then progressively add integrations as needed.

Get Started

Core Concepts

Guides

Integrations

Installation

Prerequisites

Installation

Environment Configuration

Basic Setup (No API Keys)

Full Setup (All Integrations)

Configuration Levels

Minimal

Standard

Full Demo

Additional Setup (Optional)

Selenium WebDriver (for Agent Beta)

CodeRabbit Integration (Advanced)

Verification

Troubleshooting

Next Steps

Quickstart

Architecture

Custom Agents

Scoring System

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

​Prerequisites

​Installation

​Environment Configuration

​Basic Setup (No API Keys)

​Full Setup (All Integrations)

​Configuration Levels

Minimal

Standard

Full Demo

​Additional Setup (Optional)

​Selenium WebDriver (for Agent Beta)

​CodeRabbit Integration (Advanced)

​Verification

​Troubleshooting

​Next Steps

Quickstart

Architecture

Custom Agents

Scoring System

Build docs developers (and LLMs) love

Prerequisites

Installation

Environment Configuration

Basic Setup (No API Keys)

Full Setup (All Integrations)

Configuration Levels

Additional Setup (Optional)

Selenium WebDriver (for Agent Beta)

CodeRabbit Integration (Advanced)

Verification

Troubleshooting

Next Steps