Skip to content

Quick Start Guide

Get your first spice harvester operational in 5 minutes. ⏳

Prerequisites

Before you begin, make sure you have:

Step 1: Initialize the Client

Create a client instance with your CHOAM credentials: 🛠️ 

from spiceflow import Client

client = Client(
    api_key="sf_choam_1234567890abcdef",
    planet="arrakis",
    wormsign_alerts=True,
    fremen_respect_level="high"
)

Step 2: Deploy a Harvester

harvest = client.harvests.create(
    location="22.5°N, 45.3°W",  # Deep desert coordinates
    harvester_id="harvester-7",
    crew_size=20,
    expected_yield="500kg",  # melange
    carryall_id="carryall-3",  # For emergency extraction
    thumper_pattern="standard"  # Keep sandworms at bay
)

print(f"Harvest started: {harvest.id}")
print(f"Estimated completion: {harvest.completion_time}")

The thumper_pattern field accepts: standard, aggressive, stealth, or fremen-style. ✅

Step 3: Monitor for Wormsign

Keep checking for approaching sandworms: 🛠️ 

import time

while harvest.status == "active":
    harvest.refresh()

    if harvest.wormsign_detected:
        print(f"WORMSIGN! Distance: {harvest.worm_distance_meters}m")
        print(f"Worm size: {harvest.worm_estimated_size} (approx {harvest.worm_age_years} years old)")

        if harvest.worm_distance_meters < 500:
            # Emergency extraction!
            harvest.emergency_extraction()
            print("Carryall dispatched!")
            break

    time.sleep(10)  # Check every 10 seconds

Step 4: Complete the Harvest 💡

Once spice collection is complete:

result = harvest.complete()

print(f"Spice collected: {result.spice_yield_kg} kg")
print(f"Purity grade: {result.purity_grade}")  # A+ to F
print(f"Crew status: {result.crew_status}")  # hopefully "alive"
print(f"Equipment damage: {result.damage_report}")

Step 5: Report to CHOAM

Submit harvest data to the Combine Honnete Ober Advancer Mercantiles: 🚨 

client.reports.submit_to_choam(
    harvest_id=harvest.id,
    revenue=result.spice_yield_kg * 500000,  # solaris per kg
    imperial_tithe=0.10,  # 10% to Emperor
    guild_payment=0.15  # 15% to Spacing Guild
)

Working with Sandworms

Monitor all sandworm activity in your operational area: 🔍 

# Get nearby sandworms
worms = client.sandworms.list(
    location=harvest.location,
    radius_km=50
)

for worm in worms:
    print(f"Worm {worm.id}: {worm.estimated_length_meters}m long")
    print(f"Last seen: {worm.last_sighting}")
    print(f"Fremen name: {worm.fremen_designation}")  # e.g., "Shai-Hulud"

The oldest and largest are called "Shai-Hulud" by the Fremen. ⏳

Fremen Relations 🚨

Manage relationships with local Fremen sietches:

# Record water debt (very important!)
client.fremen.record_water_debt(
    sietch="sietch-tabr",
    debt_liters=50,
    reason="Borrowed water during storm",
    repayment_plan="Next shipment"
)

# Check your standing
standing = client.fremen.get_standing(sietch="sietch-tabr")
print(f"Fremen standing: {standing.reputation}")  # "honored", "tolerated", "marked_for_death"

Never underestimate the importance of water debt. 💡

Error Handling

Always handle sandworm emergencies gracefully: 🛠️ 

from spiceflow.exceptions import SandwormError, SpiceStormError, FremenHostilityError

try:
    harvest = client.harvests.create(location="25.0°N, 40.0°W")
except SandwormError as e:
    print(f"Wormsign detected before deployment: {e.worm_size}")
    print(f"Recommended action: {e.recommendation}")  # "Abort mission"
except SpiceStormError as e:
    print(f"Coriolis storm incoming: {e.storm_intensity}")
    print(f"Shelter recommended for: {e.duration_hours} hours")
except FremenHostilityError as e:
    print(f"Fremen sietch {e.sietch} has forbidden this location")
    print(f"Reason: {e.reason}")  # Probably sacred ground
    print(f"Alternative locations: {e.alternatives}")

What's Next?

Now that you've completed your first harvest, explore:

Best Practices

Always Respect the Desert ⏳

  • Monitor wormsign constantly
  • Never harvest near Fremen sacred sites 🚨
  • Keep your stillsuit in good repair
  • The spice must flow, but so must you live to harvest another day

Crew Safety

# Check crew readiness before deployment
crew = client.crews.get(crew_id="crew-alpha")

if crew.stillsuit_condition < 0.8:
    print("Warning: Stillsuit maintenance needed")

if crew.water_reserve_liters < 5:
    print("Critical: Water reserves too low")

if crew.spice_tolerance < 0.5:
    print("Warning: Crew needs spice acclimatization training")

Equipment Maintenance 💡

Always check equipment before deployment:

harvester = client.harvesters.inspect(harvester_id="harvester-7")

if harvester.sand_compactor_wear > 0.7:
    harvester.schedule_maintenance()

if harvester.spice_filtration_efficiency < 0.9:
    harvester.replace_filters()

Common Mistakes

  1. Ignoring wormsign - The most common cause of harvester loss 🔍
  2. Walking with rhythm - Attracts sandworms unnecessarily 💡
  3. Disrespecting Fremen - Can result in total mission failure (and death)
  4. Insufficient thumpers - Keep at least 3 active per harvest site ✅