Create connections and label space

Set positive or negative relationships between people, teams, and spaces, and tag spaces with labels to guide AI allocation decisions.

Node.js

Prerequisites

• Completed Setup Your Development Environment and Send Your First API Request

• Node.js v18+ and npm v9+

• A valid gospace API key in your .env file

• Known IDs (or external IDs) for the entities you want to relate

Allowed connection entity types: TEAM, PERSON, LABEL, SPACE, ROOM, ZONE. Strength is an integer (e.g., -100 → 100). Negative is an avoid signal; positive is a prefer signal.

---

1) Create connections (positive & negative)

Create create-connections.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.connections.createConnections({
    connections: [
      // Positive: person prefers to sit near a team
      {
        strength: 75,
        connection_from_entity: {
          connection_entity_id: "person_123",
          connection_entity_type: "PERSON",
          connection_entity_data: {
            first_name: "Alice",
            last_name: "Smith",
            email: "[email protected]",
            person_id: "person_123",
            external_id: "ext-alice",
          },
        },
        connection_to_entity: {
          connection_entity_id: "team_456",
          connection_entity_type: "TEAM",
          connection_entity_data: {
            team_name: "Engineering",
            team_id: "team_456",
            external_id: "ext-team-eng",
          },
        },
      },

      // Negative: team should avoid a particular room
      {
        strength: -50,
        connection_from_entity: {
          connection_entity_id: "team_456",
          connection_entity_type: "TEAM",
          connection_entity_data: {
            team_name: "Engineering",
            team_id: "team_456",
          },
        },
        connection_to_entity: {
          connection_entity_id: "room_789",
          connection_entity_type: "ROOM",
          connection_entity_data: {
            room_name: "Conference Room A",
            room_id: "room_789",
          },
        },
      },
    ],
  });

  console.log(JSON.stringify(res.data.connections, null, 2));
}

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

---

2) Query connections (by entity, type, or external_id)

Create get-connections.ts:

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

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

  // Examples of useful filters:
  const res = await gospace.connections.getConnections({
    // connection_id: "conn_123", // exact connection
    connection_entity_id: "team_456", // find all touching this entity
    connection_entity_type: "TEAM",   // TEAM | PERSON | LABEL | SPACE | ROOM | ZONE
    // external_id: "ext-alice",     // match external_id of PERSON/TEAM in from/to entities
    skip: 0,
    limit: 25,
    sort: "strength",
    order: "desc",
  });

  console.log(JSON.stringify(res.data.connections, null, 2));
}

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

---

3) Update connection strength / endpoints

Create update-connections.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.connections.updateConnections({
    connections: [
      {
        _id: "conn_abc123",     // the connection to update
        strength: 90,           // new strength (e.g., boost preference)
        connection_from_entity: {
          connection_entity_id: "person_123",
          connection_entity_type: "PERSON",
        },
        connection_to_entity: {
          connection_entity_id: "team_456",
          connection_entity_type: "TEAM",
        },
      },
    ],
  });

  console.log(JSON.stringify(res.data.connections, null, 2));
}

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

---

4) Delete connections

Create delete-connections.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.connections.deleteConnections({
    connections: [
      { connection_id: "conn_abc123" },
      { connection_id: "conn_def456" },
    ],
  });

  console.log(JSON.stringify(res.data, null, 2));
}

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

---

5) Create labels (for tagging entities)

Create create-labels.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.connections.createLabels({
    labels: [
      {
        name: "Quiet",
        type: "category",
        details: { color: "blue", description: "Quiet working area" },
      },
      {
        name: "Exec",
        type: "tag",
        details: { color: "gold", description: "Executive seating" },
      },
    ],
  });

  console.log(JSON.stringify(res.data.labels, null, 2));
}

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

---

6) Label space (map a label to SPACE/ROOM/ZONE/TEAM/PERSON)

Create map-labels.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.connections.createLabelMappings({
    mappings: [
      // Label a space as "Quiet"
      {
        label_id: "label_quiet",
        entity_id: "space_101",
        entity_type: "SPACE", // TEAM | PERSON | LABEL | SPACE | ROOM | ZONE
        details: { applied_at: new Date().toISOString() },
      },

      // Label a room as "Exec"
      {
        label_id: "label_exec",
        entity_id: "room_789",
        entity_type: "ROOM",
        details: { applied_at: new Date().toISOString() },
      },
    ],
  });

  console.log(JSON.stringify(res.data.mappings, null, 2));
}

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

---

7) Query & manage label mappings

Get mappings (filter by label, entity, type, or external_id):

const mappings = await gospace.connections.getLabelMappings({
  // mapping_id: "map_123",
  label_id: "label_quiet",
  entity_type: "SPACE",
  skip: 0,
  limit: 25,
  sort: "label_id",
  order: "asc",
});
console.log(JSON.stringify(mappings.data.mappings, null, 2));

Update mappings:

await gospace.connections.updateLabelMappings({
  mappings: [
    {
      _id: "map_123",
      label_id: "label_quiet",
      entity_id: "space_101",
      entity_type: "SPACE",
      details: { applied_at: new Date().toISOString(), note: "Near windows" },
    },
  ],
});

Delete mappings:

await gospace.connections.deleteLabelMappings({
  mappings: [{ mapping_id: "map_123" }],
});

---

Tips & patterns

• Model behaviour:

  • Positive connections (> 0) indicate affinity or proximity preference.

  • Negative connections (< 0) indicate separation or avoidance.

• Granularity:

  • Use people ↔ team for day‑to‑day seating preferences.

  • Use team ↔ room/zone/space for capacity and neighborhood tuning.

  • Use labels to tag assets (e.g., “Quiet”, “Client‑facing”, “Accessible”).

• Searchability:

  • Use external_id on people/teams, then query getConnections with external_id to keep your system in sync.

• Governance:

  • Keep connection strengths within a standard range (e.g., -100, -50, -25, 25, 50, 100) so they’re interpretable.

  • Periodically audit old connections and label mappings to avoid stale constraints.