From 8516d4eacc3947459f510b85ebb3f959c5534937 Mon Sep 17 00:00:00 2001 From: zocomputer Date: Tue, 29 Sep 2026 04:12:42 +0000 Subject: [PATCH 1/2] docs: document canonical server-minted world IDs --- getting-started.mdx | 8 +++----- guides/company-brain.mdx | 14 ++++++++------ guides/entity-resolution.mdx | 6 +++--- platform/api.mdx | 33 ++++++++++++++++++++++++++++++--- platform/typescript-sdk.mdx | 23 +++++++++++++---------- projects/worlds.mdx | 18 +++++++++++++----- quickstart.mdx | 3 ++- reference/cli/usage.mdx | 4 ++-- reference/cli/worlds.mdx | 15 +++++++++------ skills/wazoo.mdx | 4 ++++ worlds/client.mdx | 18 ++++++++++++------ worlds/query.mdx | 2 +- worlds/search.mdx | 32 +++++++++++++++++--------------- worlds/update.mdx | 4 ++-- 14 files changed, 119 insertions(+), 65 deletions(-) diff --git a/getting-started.mdx b/getting-started.mdx index f4972c3..aa1269a 100644 --- a/getting-started.mdx +++ b/getting-started.mdx @@ -26,11 +26,9 @@ if you believe you should have access. ## 2. Create a world -After signing in, click **Create world**. Give your world a name and an ID. The -ID must be unique across all worlds in the platform. - -World IDs are public and used in API requests. Choose something descriptive like -`my-knowledge-base` or `project-context`. +After signing in, click **Create world** and enter a display name. The platform +mints the world's ID; you do not choose one. Use the returned `id` in API +requests. ## 3. Import data diff --git a/guides/company-brain.mdx b/guides/company-brain.mdx index de8e7d6..483f6e6 100644 --- a/guides/company-brain.mdx +++ b/guides/company-brain.mdx @@ -31,11 +31,13 @@ and carry provenance you can trace to their source. Worlds stores facts in isolated worlds. Create one for the company brain: ```bash - wazoo worlds create company-brain --name "Company Brain" + wazoo worlds create --name "Company Brain" + export WORLD_ID="w_123e4567-e89b-42d3-a456-426614174000" ``` - The world ID `company-brain` is public and used in every data-plane - request. Choose a descriptive ID so agents can find the right world. + The Worlds API mints an immutable `w_` ID and returns it as `id`. + Replace the sample `WORLD_ID` with that exact value; the display name is not + an ID, and create requests expose no caller-selected ID or slug field. @@ -98,7 +100,7 @@ and carry provenance you can trace to their source. ```bash wiki export brain/decisions/ADR-004.md -f turtle -o brain/ADR-004.ttl - wazoo worlds import company-brain --file ./brain/ADR-004.ttl + wazoo worlds import "$WORLD_ID" --file ./brain/ADR-004.ttl ``` The import endpoint accepts Turtle, JSON-LD, N-Triples, N-Quads, and Trig. @@ -134,13 +136,13 @@ and carry provenance you can trace to their source. Search the brain for the decision you imported: ```bash -wazoo worlds search company-brain --query "company context engine" +wazoo worlds search "$WORLD_ID" --query "company context engine" ``` Then confirm the fact exists in the graph with a SPARQL query: ```bash -wazoo worlds sparql company-brain --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10" +wazoo worlds sparql "$WORLD_ID" --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10" ``` The search returns the ADR document, and the SPARQL query returns its quads. diff --git a/guides/entity-resolution.mdx b/guides/entity-resolution.mdx index 9fe2b10..88e5bd4 100644 --- a/guides/entity-resolution.mdx +++ b/guides/entity-resolution.mdx @@ -127,7 +127,7 @@ of the substrate. Import these quads through the normal Search the world for the mention's name and take the top candidates: ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/search" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "Sarah Chen", "topK": 5 }' @@ -241,7 +241,7 @@ extraction-based memory layers have to build by hand. Search the world for both names and confirm they resolve to one subject: ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/search" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "Sarah" }' @@ -250,7 +250,7 @@ curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \ Then verify the resolution exists in the graph: ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/sparql" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/sparql" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ diff --git a/platform/api.mdx b/platform/api.mdx index a8b9c73..f3cd6db 100644 --- a/platform/api.mdx +++ b/platform/api.mdx @@ -59,9 +59,36 @@ The Platform API covers these management resources: | Users | `/v1/users/me` | | Stripe webhook | `/v1/stripe/webhook` | -Public `worldId` values must match `^[a-z][a-z0-9-]{2,62}$`. Internal `uid` -values use prefixes such as `w_...` so they cannot be confused with public path -IDs. +`worlds-api` mints each immutable world ID as `w_`. The Platform API +stores it as `world_id`, and both APIs expose the unchanged value as `id`. +Create requests define a display name but no caller-selected ID or slug field. +Use `world.id` as the `worldId` path parameter. + +```http +POST /v1/worlds +Authorization: Bearer wzp_YOUR_PLATFORM_TOKEN +Content-Type: application/json + +{ + "world": { + "displayName": "My World", + "region": "auto" + } +} + +HTTP/1.1 201 Created + +{ + "world": { + "id": "w_123e4567-e89b-42d3-a456-426614174000", + "displayName": "My World", + "region": "auto", + "state": "ACTIVE", + "restorable": false, + "backend": "worlds-api" + } +} +``` ## Data-plane boundary diff --git a/platform/typescript-sdk.mdx b/platform/typescript-sdk.mdx index 6a49aac..9399b1e 100644 --- a/platform/typescript-sdk.mdx +++ b/platform/typescript-sdk.mdx @@ -64,19 +64,19 @@ console.log(data?.worlds); // Create a world const created = await createWorld({ body: { - worldId: "support-knowledge", world: { displayName: "Support Knowledge", region: "auto" }, }, }); +const worldId = created.data!.world.id; // Get a world by ID const world = await getWorld({ - path: { worldId: "support-knowledge" }, + path: { worldId }, }); // Update display name await updateWorld({ - path: { worldId: "support-knowledge" }, + path: { worldId }, body: { updateMask: "displayName", world: { displayName: "Support Knowledge Base" }, @@ -84,9 +84,12 @@ await updateWorld({ }); // Soft-delete (recoverable for 30 days) -await deleteWorld({ path: { worldId: "support-knowledge" } }); +await deleteWorld({ path: { worldId } }); ``` +`world.id` is the immutable `w_` ID minted by the Worlds API. Reuse it +unchanged as the `worldId` path value. + Creating a platform world provisions per-World graph storage. Use `data.wazoo.dev`, the generated [`@worlds/client`](/projects/worlds), or the embedded [`@worlds/sdk`](/projects/worlds) for graph data operations inside that @@ -131,16 +134,16 @@ import { } from "@wazoo/client"; const { data } = await listWorldTokens({ - path: { worldId: "support-knowledge" }, + path: { worldId }, }); const created = await createWorldToken({ - path: { worldId: "support-knowledge" }, + path: { worldId }, }); console.log(created.data?.token); // one-time secret await deleteWorldToken({ - path: { worldId: "support-knowledge", tokenUid: created.data!.token.uid }, + path: { worldId, tokenUid: created.data!.token.uid }, }); ``` @@ -150,12 +153,12 @@ await deleteWorldToken({ import { getWorldUsage, getWorldLimits } from "@wazoo/client"; const usage = await getWorldUsage({ - path: { worldId: "support-knowledge" }, + path: { worldId }, }); console.log(usage.data?.usage.total); const limits = await getWorldLimits({ - path: { worldId: "support-knowledge" }, + path: { worldId }, }); ``` @@ -165,7 +168,7 @@ const limits = await getWorldLimits({ import { getWorldBilling } from "@wazoo/client"; const billing = await getWorldBilling({ - path: { worldId: "support-knowledge" }, + path: { worldId }, }); console.log(billing.data?.billing.state); ``` diff --git a/projects/worlds.mdx b/projects/worlds.mdx index 4ac9038..a74d4d6 100644 --- a/projects/worlds.mdx +++ b/projects/worlds.mdx @@ -60,18 +60,26 @@ curl -s -X POST "https://api.wazoo.dev/v1/worlds" \ -H "Authorization: Bearer $WAZOO_PLATFORM_TOKEN" \ -H "Content-Type: application/json" \ -d '{ - "worldId": "quickstart-cloud", "world": { "displayName": "My First World", "region": "auto" } }' ``` +The Worlds API mints one immutable `w_` ID and returns it as `world.id`. +Create requests include the display name and expose no caller-selected ID or +slug field. Set `WORLD_ID` to that exact returned value before running the +requests below. + +```bash +export WORLD_ID="w_123e4567-e89b-42d3-a456-426614174000" +``` + ### Mint a world token Data-plane requests use a `wzw_` token scoped to a single world. Save the returned secret immediately; it is shown only once: ```bash -curl -s -X POST "https://api.wazoo.dev/v1/worlds/quickstart-cloud/auth/tokens" \ +curl -s -X POST "https://api.wazoo.dev/v1/worlds/$WORLD_ID/auth/tokens" \ -H "Authorization: Bearer $WAZOO_PLATFORM_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "quickstart" }' @@ -82,7 +90,7 @@ Save it as `WORLDS_TOKEN`. ### Import, search, and query ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/import" \ +curl -s -X POST "https://data.wazoo.dev/worlds/$WORLD_ID/import" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -92,7 +100,7 @@ curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/import" \ ``` ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/search" \ +curl -s -X POST "https://data.wazoo.dev/worlds/$WORLD_ID/search" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -102,7 +110,7 @@ curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/search" \ ``` ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/sparql" \ +curl -s -X POST "https://data.wazoo.dev/worlds/$WORLD_ID/sparql" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ diff --git a/quickstart.mdx b/quickstart.mdx index d6fbd97..326fd47 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -29,13 +29,14 @@ If you prefer calling the Wazoo Platform API directly using HTTP/cURL: -H "Authorization: Bearer wzp_YOUR_PLATFORM_TOKEN" \ -H "Content-Type: application/json" \ -d '{ - "worldId": "my-agent-world", "world": { "displayName": "My Agent World", "region": "auto" } }' ``` + The Worlds API mints an immutable `w_` ID and returns it as + `world.id`, which callers reuse unchanged in later requests. diff --git a/reference/cli/usage.mdx b/reference/cli/usage.mdx index a09dd7b..112d1ce 100644 --- a/reference/cli/usage.mdx +++ b/reference/cli/usage.mdx @@ -24,11 +24,11 @@ wazoo usage [options] ### Check usage for a world ```bash -wazoo usage dev-world-01 +wazoo usage w_123e4567-e89b-42d3-a456-426614174000 ``` ### View usage metrics as JSON ```bash -wazoo usage dev-world-01 --json +wazoo usage w_123e4567-e89b-42d3-a456-426614174000 --json ``` diff --git a/reference/cli/worlds.mdx b/reference/cli/worlds.mdx index 1eb354a..e46fe9a 100644 --- a/reference/cli/worlds.mdx +++ b/reference/cli/worlds.mdx @@ -12,8 +12,11 @@ data from the command line. Create a new isolated memory world. +The Worlds API mints an immutable `w_` ID. The response's `id` is reused +unchanged as `worldId` in subsequent commands. + ```bash -wazoo worlds create --name "My Knowledge Base" +wazoo worlds create --name "My Knowledge Base" ``` ### `wazoo worlds get` @@ -21,7 +24,7 @@ wazoo worlds create --name "My Knowledge Base" Retrieve specific world details by ID. ```bash -wazoo worlds get +wazoo worlds get ``` ### `wazoo worlds list` @@ -40,7 +43,7 @@ Import text, files, or RDF knowledge graph data into a world. Supports Turtle, JSON-LD, N-Triples, N-Quads, and Trig. ```bash -wazoo worlds import --file ./data.ttl +wazoo worlds import --file ./data.ttl ``` ### `wazoo worlds export` @@ -48,7 +51,7 @@ wazoo worlds import --file ./data.ttl Export world graph quads/triples. ```bash -wazoo worlds export --format turtle +wazoo worlds export --format turtle ``` ### `wazoo worlds search` @@ -56,7 +59,7 @@ wazoo worlds export --format turtle Perform hybrid vector + graph pattern search across world memory. ```bash -wazoo worlds search --query "agent architecture" +wazoo worlds search --query "agent architecture" ``` ### `wazoo worlds sparql` @@ -64,5 +67,5 @@ wazoo worlds search --query "agent architecture" Execute raw graph queries and pattern matching (SPARQL) against a world graph. ```bash -wazoo worlds sparql --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10" +wazoo worlds sparql --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10" ``` diff --git a/skills/wazoo.mdx b/skills/wazoo.mdx index a7c501a..95ccdd1 100644 --- a/skills/wazoo.mdx +++ b/skills/wazoo.mdx @@ -81,6 +81,10 @@ The skill reads two environment variables, one per plane: | `WAZOO_PLATFORM_TOKEN` | `wzp_` | Control plane | World creation, token management, usage inspection | | `WORLDS_TOKEN` | `wzw_` | Data plane | Graph import, hybrid search, graph queries (SPARQL), export | +The Worlds API mints an immutable `w_` world ID. The create response +exposes it as `world.id`, which you reuse unchanged. Create requests expose no +caller-selected ID or slug field. + ## What it covers ### Control plane diff --git a/worlds/client.mdx b/worlds/client.mdx index cb55d0b..3224822 100644 --- a/worlds/client.mdx +++ b/worlds/client.mdx @@ -40,7 +40,7 @@ const client = createClient({ const response = await listWorlds({ client }); for (const world of response.data?.worlds ?? []) { - console.log(world.uid, world.displayName); + console.log(world.id, world.displayName); } ``` @@ -53,7 +53,7 @@ import { searchWorld } from "@worlds/client"; const response = await searchWorld({ client, - path: { id: "w_" }, + path: { worldId: "w_123e4567-e89b-42d3-a456-426614174000" }, body: { query: "Ethan's manager", limit: 5 }, }); @@ -73,7 +73,7 @@ import { importWorld } from "@worlds/client"; const response = await importWorld({ client, - path: { id: "w_" }, + path: { worldId: "w_123e4567-e89b-42d3-a456-426614174000" }, body: { data: '( "object") .', contentType: "text/turtle", @@ -88,7 +88,7 @@ import { sparqlWorld } from "@worlds/client"; const response = await sparqlWorld({ client, - path: { id: "w_" }, + path: { worldId: "w_123e4567-e89b-42d3-a456-426614174000" }, body: { query: 'SELECT ?s WHERE { ?s "object" }' }, }); ``` @@ -98,8 +98,14 @@ const response = await sparqlWorld({ ```ts import { exportWorld, reindexWorld } from "@worlds/client"; -const exported = await exportWorld({ client, path: { id: "w_" } }); -const reindexed = await reindexWorld({ client, path: { id: "w_" } }); +const exported = await exportWorld({ + client, + path: { worldId: "w_123e4567-e89b-42d3-a456-426614174000" }, +}); +const reindexed = await reindexWorld({ + client, + path: { worldId: "w_123e4567-e89b-42d3-a456-426614174000" }, +}); ``` ## Self-hosting diff --git a/worlds/query.mdx b/worlds/query.mdx index bc2c0b0..79656d4 100644 --- a/worlds/query.mdx +++ b/worlds/query.mdx @@ -18,7 +18,7 @@ Given triples such as `user:person wazoo:uses wazoo:worlds`, query for the resource: ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/sparql" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/sparql" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ diff --git a/worlds/search.mdx b/worlds/search.mdx index 3b0df95..9d05e6a 100644 --- a/worlds/search.mdx +++ b/worlds/search.mdx @@ -1,22 +1,24 @@ --- title: "Search" -description: - "How Worlds searches graph data and the current hosted-beta limits." +description: "Semantic disambiguation and hybrid retrieval." --- Before reasoning about facts, agents must find the correct starting point. +Hybrid search disambiguates natural language queries and resolves them to the +correct semantic entity (IRI) before executing symbolic logic. -## Hosted private-beta status +## Why not only vector search? -The hosted Worlds Data API currently uses keyword full-text search. It does not -have an embedding provider configured, so vector ranking and the hybrid flow -described below are not active in the hosted beta. +Standard vector search retrieves semantically similar text, but agents require +factual precision. If an agent searches for "Ethan's manager", a pure vector +query might return "Gregory's manager" because their text embeddings are nearly +identical in vector space. -## Hybrid retrieval design +## Hybrid retrieval -When vector search is configured, Worlds can combine keyword matching, vector -similarity, and graph filters to resolve a natural-language query to a semantic -entity (IRI) before executing symbolic logic. +Worlds combines three signals for accurate retrieval. Hybrid search layers +keyword matching and structural graph filters over vector embeddings, so the +agent resolves the exact item it needs. | Signal | Technique | What it captures | | :------------ | :--------------------------- | :----------------------- | @@ -26,8 +28,8 @@ entity (IRI) before executing symbolic logic. ## Reciprocal rank fusion -When multiple signals are available, Worlds merges their rankings using -Reciprocal Rank Fusion (RRF): +Results from each signal are merged using Reciprocal Rank Fusion (RRF), an +algorithm that produces a single relevance ranking: $$score = \sum_{d \in D} \frac{1}{60 + rank(d)}$$ @@ -36,11 +38,11 @@ noise from any single signal. ## Execute a search -Use the data-plane search endpoint for keyword search in the hosted private -beta. Data-plane requests authenticate with a `wzw_` world token: +Use the data-plane search endpoint to perform hybrid retrieval across a world. +Data-plane requests authenticate with a `wzw_` world token: ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/search" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ diff --git a/worlds/update.mdx b/worlds/update.mdx index 18d9ff2..c13fd8b 100644 --- a/worlds/update.mdx +++ b/worlds/update.mdx @@ -20,7 +20,7 @@ The mutation path on the hosted API is the [import endpoint](/console/import). quads to import: ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/import" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/import" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ @@ -74,7 +74,7 @@ correction), the API records this as a preference item connected to the original fact. ```bash -curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/import" \ +curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/import" \ -H "Authorization: Bearer $WORLDS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ From 070fadb908434c119c891faa05d2522ba26be9b6 Mon Sep 17 00:00:00 2001 From: zocomputer Date: Mon, 5 Oct 2026 02:58:53 +0000 Subject: [PATCH 2/2] wip: world identity docs revision --- worlds/search.mdx | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/worlds/search.mdx b/worlds/search.mdx index 9d05e6a..5ef114c 100644 --- a/worlds/search.mdx +++ b/worlds/search.mdx @@ -1,24 +1,22 @@ --- title: "Search" -description: "Semantic disambiguation and hybrid retrieval." +description: + "How Worlds searches graph data and the current hosted-beta limits." --- Before reasoning about facts, agents must find the correct starting point. -Hybrid search disambiguates natural language queries and resolves them to the -correct semantic entity (IRI) before executing symbolic logic. -## Why not only vector search? +## Hosted private-beta status -Standard vector search retrieves semantically similar text, but agents require -factual precision. If an agent searches for "Ethan's manager", a pure vector -query might return "Gregory's manager" because their text embeddings are nearly -identical in vector space. +The hosted Worlds Data API currently uses keyword full-text search. It does not +have an embedding provider configured, so vector ranking and the hybrid flow +described below are not active in the hosted beta. -## Hybrid retrieval +## Hybrid retrieval design -Worlds combines three signals for accurate retrieval. Hybrid search layers -keyword matching and structural graph filters over vector embeddings, so the -agent resolves the exact item it needs. +When vector search is configured, Worlds can combine keyword matching, vector +similarity, and graph filters to resolve a natural-language query to a semantic +entity (IRI) before executing symbolic logic. | Signal | Technique | What it captures | | :------------ | :--------------------------- | :----------------------- | @@ -28,8 +26,8 @@ agent resolves the exact item it needs. ## Reciprocal rank fusion -Results from each signal are merged using Reciprocal Rank Fusion (RRF), an -algorithm that produces a single relevance ranking: +When multiple signals are available, Worlds merges their rankings using +Reciprocal Rank Fusion (RRF): $$score = \sum_{d \in D} \frac{1}{60 + rank(d)}$$ @@ -38,8 +36,8 @@ noise from any single signal. ## Execute a search -Use the data-plane search endpoint to perform hybrid retrieval across a world. -Data-plane requests authenticate with a `wzw_` world token: +Use the data-plane search endpoint for keyword search in the hosted private +beta. Data-plane requests authenticate with a `wzw_` world token: ```bash curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/search" \