Optimise your first location

Trigger the AI to evolve your location layout based on forecasts and settings, dynamically assigning spaces to teams and people.

Node.js

Prerequisites

• Completed Add historic attendance and Start forecasting

• Node.js v18+ and npm v9+

• A valid gospace API key in your .env file

• A location_id with recent forecasts available

The evolution process uses your forecasts and configuration to create dynamic allocations (teams/people → space types). These adjust over time (daily, weekly, bi‑weekly, monthly, quarterly) according to your setup.

---

1) Choose evolution settings

• date — the effective date (YYYY‑MM‑DD) you want to evolve.

• disruption — how much change you’re willing to accept:

  • MIN – smallest movement; preserve stability.

  • MAX – full optimisation; least stable.

• run_by_zone — true to evolve zone‑by‑zone (useful when zones are meaningful capacity containers), false to evolve the whole location at once.

---

2) Trigger evolution

Create evolve-location.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.system.evolveLocation({
    location_id: "68824ca5369c856b7c670510",
    date: "2025-08-08",
    settings: {
      disruption: "MIN",   // 'MIN' | 'MAX'
      run_by_zone: false,  // evolve entire location in one pass
    },
  });

  // Expect: { success, data: { evolution_id, status }, identifier }
  console.log(JSON.stringify(res.data, null, 2));
}

main().catch((err) => {
  console.error("Trigger evolve failed:", err);
  process.exit(1);
});

---

3) Poll status until completion

Create evolve-status.ts:

import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

const EVOLUTION_ID = process.env.EVOLUTION_ID!; // set from step 2 response

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  for (;;) {
    const res = await gospace.system.getEvolutionStatus({
      evolution_id: EVOLUTION_ID,
    });

    const status = res.data.status; // 'created' | 'processing' | 'no_execution' | 'successful' | 'failed'
    console.log(`[evolve] status: ${status}`);

    if (status === "successful" || status === "no_execution") break;
    if (status === "failed") throw new Error("Evolution failed");
    await new Promise((r) => setTimeout(r, 3000));
  }

  console.log("Evolution complete.");
}

main().catch((err) => {
  console.error("Check evolve status failed:", err);
  process.exit(1);
});

Run:

EVOLUTION_ID="94289524-04ac-44d3-8f05-45b8a937f663" npx tsx evolve-status.ts

---

4) Interpreting the results

After a successful evolution:

• The system produces allocations that map teams/people to space types (e.g., desks, rooms) for the requested date.

• Allocations are driven by your forecast (including *_inc adjustments for minimum targets, bookings/intentions, and contingencies) and your settings (disruption, run_by_zone).

• These allocations grow/shrink dynamically as forecasts change and as you re‑run evolution on your chosen cadence (daily/weekly/bi‑weekly/monthly/quarterly).

If your evolution returns no_execution, it means there were no material changes to apply given the current forecasts and settings. Consider increasing disruption, adjusting forecasts/targets, or running by zones.