Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-19180-ask-hub-backend.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hub operators can enable an optional Ask AI help backend that answers docs questions server side through the Kapa.ai Chat API: per-person consent, credential-shaped questions refused, only allowlisted cited sources, per-person and hub-wide limits, a circuit breaker and content-free audit lines. Off by default and inert until a key file, project id and integration id are configured; no panel yet ([#19180](https://github.com/hivecommons/hive/issues/19180)).
1 change: 1 addition & 0 deletions changelog.d/added-19181-ask-hub-panel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The hub dashboard shows an optional **Ask** panel when Ask AI help is on: a docked, keyboard-operable panel with a consent notice, answers rendered as plain text with their sources and an "AI generated, may be wrong" label, withdrawal, and a docs link in every state. With Ask off the dashboard document and its headers are unchanged ([#19181](https://github.com/hivecommons/hive/issues/19181)).
1 change: 1 addition & 0 deletions changelog.d/added-19183-ask-hive-backend.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hive owners can turn on Ask AI help in Settings, Features (`ask.enabled`, `ask.mode`): a hosted hive asks through a new hub relay with its existing per-hive heartbeat bearer and holds no Kapa key, a self-hosted hive can use direct mode with its own key. Per-person consent is kept on the hive, the hub charges each hive an hourly quota and serves hosted hives only in this round, and every route answers 404 while Ask is off ([#19183](https://github.com/hivecommons/hive/issues/19183)).
1 change: 1 addition & 0 deletions changelog.d/added-19184-ask-hive-panel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hive dashboards show the optional **Ask** panel when Ask AI help is on, reusing the hub's panel: the section in view (or the open Settings tab) labels the question from a fixed list, the docs link follows the section, and with Ask off the page loads nothing for it. The Ask AI help guide covers self-hosted direct mode and a rollout verification checklist ([#19184](https://github.com/hivecommons/hive/issues/19184)).
217 changes: 217 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -29852,6 +29852,223 @@
}
}
},
"/api/ask/status": {
"get": {
"tags": [
"System"
],
"summary": "Ask AI help status",
"description": "Whether the optional Ask AI help panel is on for the signed-in person, the disclosure they must confirm and whether they have. Answers 404 unless ask.enabled is on and fully configured (see src/docs/design/dashboard-ask-ai-help.md, #19183). Never returns the vendor key, project id or integration id.",
"responses": {
"200": {
"description": "Status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"text_version": {
"type": "string"
},
"disclosure": {
"type": "string"
},
"consented": {
"type": "boolean"
},
"docs_url": {
"type": "string"
},
"ai_label": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Not signed in"
},
"404": {
"description": "Ask is off"
}
}
}
},
"/api/ask/consent": {
"put": {
"tags": [
"System"
],
"summary": "Confirm the Ask disclosure",
"description": "Records the signed-in person's consent to the disclosure version the page showed. One audit line, no text. Answers 404 unless ask.enabled is on and fully configured (see src/docs/design/dashboard-ask-ai-help.md, #19183).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text_version": {
"type": "string"
}
},
"required": [
"text_version"
]
}
}
}
},
"responses": {
"204": {
"description": "Recorded"
},
"400": {
"description": "Invalid JSON"
},
"401": {
"description": "Not signed in"
},
"404": {
"description": "Ask is off"
},
"409": {
"description": "The disclosure text changed; reload and confirm again"
}
}
},
"delete": {
"tags": [
"System"
],
"summary": "Withdraw Ask consent",
"description": "Withdraws the signed-in person's consent; takes effect on the next question. Answers 404 unless ask.enabled is on and fully configured (see src/docs/design/dashboard-ask-ai-help.md, #19183).",
"responses": {
"204": {
"description": "Withdrawn (or nothing to withdraw)"
},
"401": {
"description": "Not signed in"
},
"404": {
"description": "Ask is off"
}
}
}
},
"/api/ask": {
"post": {
"tags": [
"System"
],
"summary": "Ask a docs-help question",
"description": "Validates the question (length cap; credential-shaped input is refused and nothing is sent), checks consent and limits, then asks Kapa.ai directly (ask.mode direct) or through the hub relay (ask.mode hub, hosted hives). Only the question and, when on, the label of the dashboard section from a closed list of ids leave the hive. Answers without an allowlisted source come back as no_cited_answer. Always 200 with an outcome. Answers 404 unless ask.enabled is on and fully configured (see src/docs/design/dashboard-ask-ai-help.md, #19183).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"maxLength": 1000
},
"section": {
"type": "string"
},
"conversation": {
"type": "string"
}
},
"required": [
"question"
]
}
}
}
},
"responses": {
"200": {
"description": "Result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"outcome": {
"type": "string",
"enum": [
"ok",
"no_cited_answer",
"refused_secret_shape",
"rate_limited",
"breaker_open",
"upstream_error",
"not_consented",
"invalid_question",
"relay_disabled"
]
},
"answer": {
"type": "string",
"description": "Plain text; render as text, never as HTML."
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
}
}
}
},
"uncertain": {
"type": "boolean"
},
"conversation": {
"type": "string",
"description": "Opaque follow-up handle bound to this person; the vendor thread id never leaves the server."
},
"retry_after_seconds": {
"type": "integer"
},
"message": {
"type": "string"
},
"ai_generated": {
"type": "boolean"
},
"docs_url": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "Invalid JSON"
},
"401": {
"description": "Not signed in"
},
"404": {
"description": "Ask is off"
}
}
}
},
"/api/feedback/nps/status": {
"get": {
"tags": [
Expand Down
Loading