docs(profiles): make user-profiles guide and notebook user-only

Remove leftover agent and regenerate references so the docs match the shipped
v1 SDK: drop the entity_type settings argument and the agent entities example
from the guide, and remove the regenerate demo section and cheat-sheet row from
the notebook.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
karthik
2026-09-23 19:53:41 +05:30
co-authored by Claude Opus 4.8
parent d91d793c52
commit f29820886a
2 changed files with 9 additions and 36 deletions
+3 -5
View File
@@ -281,10 +281,9 @@ On a project where profiles are turned off, a read returns `status: not_enabled`
| `enabled` | boolean | Whether profile generation runs for the project | | `enabled` | boolean | Whether profile generation runs for the project |
| `schema` | object | JSON Schema describing the profile. Every property needs a `description` | | `schema` | object | JSON Schema describing the profile. Every property needs a `description` |
| `custom_instructions` | string | Extra guidance applied during extraction | | `custom_instructions` | string | Extra guidance applied during extraction |
| `entity_type` | string | Which entity kind `schema` and `custom_instructions` apply to. Defaults to `user` |
`enabled` is project-wide. `schema` and `custom_instructions` belong to one `enabled` is project-wide. `schema` and `custom_instructions` apply to user
entity type, so the stored settings nest them under `entities`: profiles, so the stored settings nest them under `entities`:
```json ```json
{ {
@@ -293,8 +292,7 @@ entity type, so the stored settings nest them under `entities`:
"user": { "user": {
"schema": { "type": "object", "properties": { "...": {} } }, "schema": { "type": "object", "properties": { "...": {} } },
"custom_instructions": "Prefer durable traits over one-off remarks." "custom_instructions": "Prefer durable traits over one-off remarks."
}, }
"agent": { "schema": null, "custom_instructions": null }
}, },
"capabilities": { "full_rebuild": false } "capabilities": { "full_rebuild": false }
} }
+6 -31
View File
@@ -149,7 +149,7 @@
"cell_type": "markdown", "cell_type": "markdown",
"metadata": {}, "metadata": {},
"source": [ "source": [
"`enabled` is project-wide; `schema` and `custom_instructions` belong to one entity kind\n", "`enabled` is project-wide; `schema` and `custom_instructions` apply to user profiles\n",
"and are stored under `entities`. The SDK takes them flat and nests them for you, so what\n", "and are stored under `entities`. The SDK takes them flat and nests them for you, so what\n",
"you write comes back unchanged from `get_profile_settings()`.\n", "you write comes back unchanged from `get_profile_settings()`.\n",
"\n", "\n",
@@ -576,31 +576,7 @@
"when you call `generate_profile()` for them.\n", "when you call `generate_profile()` for them.\n",
"\n", "\n",
"A field you **remove** stops being maintained: on the next generation, fields your schema\n", "A field you **remove** stops being maintained: on the next generation, fields your schema\n",
"no longer defines are pruned. Keep a field for as long as you want its value kept.\n", "no longer defines are pruned. Keep a field for as long as you want its value kept."
"\n",
"Rebuilding a whole project in one call is **not available yet**. Check\n",
"`capabilities.full_rebuild` before offering it in your own UI — the cell below expects to\n",
"be refused, and that refusal is the feature working.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"caps = client.get_profile_settings().get(\"capabilities\", {})\n",
"print(\"full_rebuild available:\", caps.get(\"full_rebuild\"))\n",
"\n",
"if caps.get(\"full_rebuild\"):\n",
" wait_for_job(client.regenerate_profiles())\n",
"else:\n",
" try:\n",
" client.regenerate_profiles()\n",
" print(\"ACCEPTED (unexpected)\")\n",
" except Exception as e:\n",
" # 409 not_yet_available. It creates nothing, so nothing was charged.\n",
" print(\"refused as expected:\", str(e)[:200])\n"
] ]
}, },
{ {
@@ -629,8 +605,8 @@
"Rejections happen on **write**, where you can see and fix them — not silently at\n", "Rejections happen on **write**, where you can see and fix them — not silently at\n",
"generation time, where you would only notice as an empty profile weeks later.\n", "generation time, where you would only notice as an empty profile weeks later.\n",
"\n", "\n",
"The last case matters for storage: both entity kinds live in one JSONB column alongside\n", "The last case matters for storage: the user schema lives in one JSONB column alongside\n",
"the envelope that separates them, so a schema using the envelope's own reserved keys could\n", "the envelope that separates it, so a schema using the envelope's own reserved keys could\n",
"not be read back unambiguously. It is refused rather than stored.\n" "not be read back unambiguously. It is refused rather than stored.\n"
] ]
}, },
@@ -749,7 +725,7 @@
"cell_type": "markdown", "cell_type": "markdown",
"metadata": {}, "metadata": {},
"source": [ "source": [
"## 8. Cleanup\n", "## 7. Cleanup\n",
"\n", "\n",
"Removes the demo users. The profile row cascades with the entity.\n" "Removes the demo users. The profile row cascades with the entity.\n"
] ]
@@ -781,10 +757,9 @@
"| read | `get_profile(user_id)` | free |\n", "| read | `get_profile(user_id)` | free |\n",
"| one user now | `generate_profile(user_id)` | 1 LLM call |\n", "| one user now | `generate_profile(user_id)` | 1 LLM call |\n",
"| try a schema | `sample_profiles(limit=n)` | ≤10 real generations, kept |\n", "| try a schema | `sample_profiles(limit=n)` | ≤10 real generations, kept |\n",
"| everyone | `regenerate_profiles()` | **not available yet** — 409 |\n",
"| poll a job | `get_profile_job(status_url)` | free |\n", "| poll a job | `get_profile_job(status_url)` | free |\n",
"\n", "\n",
"**Settings are per entity kind.** The stored shape is:\n", "**Settings apply to user profiles.** The stored shape is:\n",
"\n", "\n",
"```json\n", "```json\n",
"{\"enabled\": true,\n", "{\"enabled\": true,\n",