Studio Hathor · NPC Safety Guardrails

Purpose#

Admin lane console for the real @hathor/llm-npc SafetyFilter. Screen a candidate NPC line against the content-filter categories at a chosen strictness, with optional custom blocked phrases and allowed exceptions, and read back whether the line is safe, which categories flagged, the confidence, and a sanitized rewrite. Admin-scoped and fail-closed.

Entry points#

• Quick-action link from /studio/hathor/npc-dialogue-generation (this page links out to npc-dialogue-generation)
• Aggregator embed: StudioHathorLlmNpcWorkspace mounts this workspace inline as its "NPC Safety Guardrails Lane"
• Direct URL / bookmark — yes; alternates.canonical set
• Studio overview — see ../../studio-overview.md

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace <section data-hathor-npc-safety-guardrails-workspace>:
  • <h1> (WorkspaceHeading) "Hathor NPC Safety Guardrails Workspace"
  • Summary <p data-hathor-npc-safety-guardrails-summary>
  • The check form lane: data-hathor-nsg-check-form
• Route Map panel (data-hathor-npc-safety-guardrails-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_NPC_SAFETY_GUARDRAILS_ROUTE_MAP
• Quick-action lane: two Link.quickAction anchors — NPC Dialogue Generation, Back to Studio workspace index

States#

• Loading — <p data-hathor-nsg-loading>
• Unauthorized — data-hathor-nsg-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-hathor-nsg-error on non-OK GET / malformed catalog
• Ready (form) — data-hathor-nsg-check-form once the catalog loads
• Result — data-hathor-nsg-result after a 200 check; data-hathor-nsg-check-error for invalid inputs / non-200

Interactions#

Workspace body (check form lane)#

• NPC line — <textarea data-hathor-nsg-content> (aria-label "npc line")
• Strictness — <select data-hathor-nsg-strictness> (how many pattern hits flag a category)
• Blocked phrases (comma-sep) — <input data-hathor-nsg-blocked> (aria-label "blocked phrases")
• Allowed exceptions (comma-sep) — <input data-hathor-nsg-exceptions> (aria-label "allowed exceptions")
• Screen line — <button data-hathor-nsg-check-submit type="submit"> → POST /v1/admin/hathor/npc-safety-guardrails/check
• Result — data-hathor-nsg-verdict, data-hathor-nsg-flagged, data-hathor-nsg-filtered (sanitized rewrite)

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_NPC_SAFETY_GUARDRAILS_ROUTE_MAP

Quick-action lane#

• "Open Hathor NPC Dialogue Generation workspace" (→ /studio/hathor/npc-dialogue-generation)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/npc-safety-guardrails on mount
• Writes: POST /v1/admin/hathor/npc-safety-guardrails/check
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: admin-scoped fail-closed (401/403); behind the signed-in
  • studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-llm-npc.md (aggregator that embeds this workspace), ./studio-hathor-npc-dialogue-generation.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorNpcSafetyGuardrailsWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorNpcSafetyGuardrailsRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/* admin lane consoles ship in V1.
• The filter is pattern/keyword based at a fixed set of categories; confirm whether an ML-classifier path is planned behind the same lane.
• Route Map advertises profiles/, rules/, contexts/, and governance/ sub-routes with no page.tsx yet.