Running locally

# Clone the repository
git clone https://github.com/ritz541/flower-engine.git
cd flower-engine

# Run setup (installs everything)
chmod +x setup.sh
./setup.sh

# Verify Python 3.12+
if ! command -v python3 &> /dev/null; then
    echo "[ERROR] Python 3 is not installed."
    exit 1
fi

# Verify Rust/Cargo
if ! command -v cargo &> /dev/null; then
    echo "[ERROR] Cargo is not installed. Visit https://rustup.rs/"
    exit 1
fi

python3 -m venv venv

# Install CPU-only PyTorch first (avoids 8GB CUDA downloads)
venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu --quiet

# Then install requirements
venv/bin/pip install -r requirements.txt --quiet

if [ ! -d "assets" ]; then
    cp -r assets_example assets
fi

if [ ! -f "config.yaml" ]; then
    cp config.yaml.example config.yaml
    echo "[ACTION REQUIRED] Please edit config.yaml to add your API keys."
fi

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install CPU-optimized PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cpu

# Install dependencies
pip install -r requirements.txt

fastapi>=0.100.0        # WebSocket server framework
uvicorn>=0.23.0         # ASGI server
websockets>=11.0.3      # WebSocket protocol
chromadb>=0.4.10        # Vector database
openai>=1.3.0           # LLM client SDK
pydantic>=2.3.0         # Data validation
sentence-transformers>=2.2.2  # Embeddings (includes PyTorch)
pyyaml>=6.0.1           # Config parsing
watchdog>=3.0.0         # File watching
google-genai>=0.1.0     # Gemini SDK

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Build TUI (from project root)
cd tui
cargo build --release

[dependencies]
crossterm = { version = "0.27.0", features = ["event-stream"] }
ratatui = "0.26.0"
tokio = { version = "1.37.0", features = ["full"] }
tokio-tungstenite = "0.21.0"
futures-util = "0.3.30"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
url = "2.5.8"

# Engine Configuration
database_path: "./chroma_db"

# LLM Providers
openai_base_url: "https://openrouter.ai/api/v1"
openai_api_key: "sk-or-v1-REPLACE_WITH_YOUR_OPENROUTER_KEY"

deepseek_api_key: "sk-REPLACE_WITH_YOUR_DEEPSEEK_KEY"

gemini_api_key: "AIzaSy..."

# Model Configuration
default_model: "google/gemini-2.0-pro-exp-02-05:free"
supported_models:
  - "google/gemini-2.0-pro-exp-02-05:free"
  - "openai/gpt-4o-mini"
  - "anthropic/claude-3-haiku"
  - "deepseek-chat"
  - "deepseek-reasoner"

cp -r assets_example assets

assets/
├── characters/
│   ├── aria.yaml
│   └── marcus.yaml
├── worlds/
│   ├── crimson_peaks.yaml
│   └── silver_city.yaml
└── rules/
    ├── noir.yaml
    └── fantasy.yaml

id: aria
name: Aria
persona: A mysterious wanderer with silver eyes and a haunted past.

id: crimson_peaks
name: The Crimson Peaks
lore: |
  Ancient mountains forged in dragon fire. The peaks glow crimson at dawn.
  Few travelers return from the summit.
scene: "You stand at the base of towering red mountains."
system_prompt: "This is a dark fantasy setting with mythic undertones."

chmod +x start.sh
./start.sh

venv/bin/python -m uvicorn engine.main:app \
    --host 0.0.0.0 \
    --port 8000 \
    --log-level error > /dev/null 2>&1 &
BACKEND_PID=$!

for i in {1..40}; do
    if curl -s http://127.0.0.1:8000/ > /dev/null; then
        READY=1
        break
    fi
    sleep 0.4
done

cd tui
cargo run --quiet

trap cleanup SIGINT SIGTERM

cleanup() {
    kill $(jobs -p) 2>/dev/null
    exit
}

source venv/bin/activate
python -m uvicorn engine.main:app --host 0.0.0.0 --port 8000 --reload

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

cd tui
cargo run

# Or with optimizations
cargo run --release

source venv/bin/activate
python engine/test_client.py

python -m uvicorn engine.main:app --reload

cd tui
cargo build  # Debug build (faster compile, slower runtime)
cargo build --release  # Optimized (slower compile, faster runtime)

from engine.logger import log

log.info("Engine started")
log.debug("Detailed debugging info")
log.error("Something went wrong")

# Run backend without log suppression
python -m uvicorn engine.main:app --log-level debug

cargo run 2> tui_errors.log

theflower/
├── engine/                 # Python backend
│   ├── main.py            # FastAPI app + WebSocket handler
│   ├── llm.py             # LLM streaming (OpenRouter, Groq, DeepSeek, Gemini)
│   ├── rag.py             # ChromaDB vector storage
│   ├── database.py        # SQLite + Pydantic models
│   ├── commands.py        # Command handlers (/model, /world, etc.)
│   ├── config.py          # Configuration loader
│   ├── state.py           # Global state + persistence
│   ├── prompt.py          # System prompt builder
│   ├── handlers.py        # WebSocket broadcast helpers
│   ├── utils.py           # YAML loader, message builder
│   └── logger.py          # Logging setup
├── tui/                    # Rust TUI
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs        # Entry point + event loop
│       ├── app.rs         # App state + logic
│       ├── models.rs      # WebSocket message types
│       ├── ws.rs          # WebSocket client
│       └── ui/            # UI rendering
├── assets/                # Game assets (gitignored)
│   ├── worlds/
│   ├── characters/
│   └── rules/
├── config.yaml            # Configuration (gitignored)
├── requirements.txt       # Python dependencies
├── setup.sh               # Initial setup script
├── start.sh               # Launch script
├── engine.db              # SQLite database (auto-created)
├── chroma_db/             # Vector storage (auto-created)
└── persist.json           # State persistence (auto-created)

id: my_world
name: My Custom World
lore: |
  Your world's backstory and lore here.
  This will be chunked and vectorized automatically.
scene: "The opening scene description."
system_prompt: "Additional context for the LLM."
start_message: "Welcome to my world!"

id: my_char
name: Character Name
persona: Detailed character description and personality.

def init_db():
    # ... existing tables ...
    
    # Add new column with migration
    try:
        cur.execute("ALTER TABLE worlds ADD COLUMN new_field TEXT DEFAULT ''")
    except sqlite3.OperationalError:
        pass  # Column already exists

async def handle_command(cmd_str: str, websocket: WebSocket):
    parts = cmd_str.split(" ", 2)
    cmd = parts[0].lower()
    
    if cmd == "/mycmd":
        await websocket.send_text(build_ws_payload(
            "system_update", 
            "My custom command output"
        ))
        return

# Reduce lore chunks from 2 to 1
lore_list, _ = rag_manager.query_lore(state.ACTIVE_WORLD_ID, prompt, n_results=1)

# Reduce memory chunks from 3 to 2
mem_list, _ = rag_manager.query_memory(mem_key, prompt, n_results=2)

cargo build --release
cargo run --release

strip tui/target/release/tui  # Reduces size by ~30%

lsof -i :8000  # See what's using port 8000
kill <PID>     # Kill conflicting process

python3 --version  # Must be 3.12+

source venv/bin/activate
pip list  # Verify all packages installed

curl http://127.0.0.1:8000/
# Should return {"message":"Flower Engine"}

wscat -c ws://127.0.0.1:8000/ws/rpc
# Should receive handshake message

source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

pip install -r requirements.txt --force-reinstall

rustup update

cd tui
cargo clean
cargo build

rm -rf chroma_db/
# Restart backend (will recreate)

df -h  # Ensure sufficient space

npm install -g wscat
wscat -c ws://localhost:8000/ws/rpc

# Send commands
> /model
> /world crimson_peaks
> /char aria
> /session new
> Tell me about this place

import asyncio
import websockets

async def test_connection(i):
    async with websockets.connect('ws://localhost:8000/ws/rpc') as ws:
        msg = await ws.recv()
        print(f"Client {i}: {msg}")

async def main():
    await asyncio.gather(*[test_connection(i) for i in range(10)])

asyncio.run(main())

[Unit]
Description=Flower Engine Backend
After=network.target

[Service]
Type=simple
User=flower
WorkingDirectory=/opt/flower-engine
Environment="PATH=/opt/flower-engine/venv/bin"
ExecStart=/opt/flower-engine/venv/bin/uvicorn engine.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable flower-engine
sudo systemctl start flower-engine

server {
    listen 80;
    server_name flower.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}