Skip to content
Closed
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-ai-hub-backend.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hub operators can switch on an optional Ask AI help backend: a signed-in person who confirms a disclosure can ask a question and get a cited answer from the vendor's Chat API, called from the hub with a key held in a Secret. Off by default; with it off the routes answer 404 and nothing leaves the hub. Questions that look like credentials are refused, answers need an allowlisted docs source, and per-person, hub-wide and daily limits with a circuit breaker apply. No panel yet ([#19180](https://github.com/hivecommons/hive/issues/19180)).
68 changes: 34 additions & 34 deletions src/docs/api-reference/hub-server.md

Large diffs are not rendered by default.

10 changes: 7 additions & 3 deletions src/docs/design/dashboard-ask-ai-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -551,9 +551,13 @@ Not verified, and the reason:
- **Which CSP applies to the hub's main dashboard document** and whether the
Node proxy or ingress adds one. Not traced. The recommended design does not
depend on it.
- **The vendor's non-streamed chat response shape** (source field names), the
streamed endpoint path and events, and whether the chat endpoint returns a
thread id in the body. The public pages read do not show them.
- **The vendor's streamed endpoint path and events.** Not needed for v1.
Resolved in phase 1 (#19180): the non-streamed `POST
/query/v1/projects/{project_id}/chat/` returns `answer`, `thread_id`,
`question_answer_id`, `is_uncertain` and `relevant_sources` (each with
`source_url`, `title` and `contains_internal_data`); a follow-up is `POST
/query/v1/threads/{thread_id}/chat/`. The client pins this shape with a
contract test (`src/pkg/ask/client_test.go`).
- **Whether the vendor documents a hosted or frame mode.** None was found; the
claim is an absence in the pages read.
- **Vendor per-source include and exclude patterns, and deletion of a single
Expand Down
22 changes: 22 additions & 0 deletions src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -707,6 +707,28 @@ only when neither is configured.

With two or more providers configured, `/login` renders a provider picker; with exactly one it redirects straight into it. A provider with a client id but missing/invalid issuer is **silently skipped** so it cannot take down login for the others — check the `hub login enabled providers=` startup log line when a button is missing.

## Ask AI help (hub backend)

Optional and **off by default**. Nothing here opens a route, makes a request or changes a header until the switch is on and every required value is set; if one is missing or the key file cannot be read, Ask stays off and logs one warning that names the reason and no value. Env wins over the `ask:` block in `hive.yaml`. The key is read from a file under the allowed secret directory; there is deliberately no variable that holds the key itself. Design: [dashboard Ask AI help](design/dashboard-ask-ai-help.md).

| Variable | Required | Default | Purpose |
|---|---:|---|---|
| `HIVE_ASK_ENABLED` | No | config `ask.enabled` (default off) | The switch. Off: every Ask route answers 404, no consent prompt, no request to the vendor. |
| `HIVE_ASK_MODE` | No | config `ask.mode` (the hub defaults to `direct`) | `off`, `direct` (this process calls the vendor with its own key) or `hub` (a hive calling the hub relay; not available yet). The hub is always `direct`. |
| `HIVE_ASK_KAPA_PROJECT_ID` | When enabled | config `ask.kapa.project_id` | The vendor project. Configuration only; never returned by an API, logged or exported. |
| `HIVE_ASK_KAPA_INTEGRATION_ID` | When enabled | config `ask.kapa.integration_id` | The vendor integration identifier. Same handling as the project id. |
| `HIVE_ASK_KAPA_API_KEY_FILE` | When enabled | config `ask.kapa.api_key_file` | Path to the vendor API key, which must be under the allowed secret directory (a mounted Secret). |
| `HIVE_ASK_SEND_SECTION_LABEL` | No | config `ask.send_section_label` (default on) | Whether a fixed-vocabulary label for the dashboard section the person is in is sent with the question. Off sends the question text alone. |
| `HIVE_ASK_LIMIT_PERSON_BURST` | No | `3` | Questions one person may ask per minute. |
| `HIVE_ASK_LIMIT_PERSON_PER_HOUR` | No | `30` | Questions one person may ask per hour. |
| `HIVE_ASK_LIMIT_HIVE_PER_HOUR` | No | `120` | Questions one hive may relay per hour (used by the hive relay in a later phase). |
| `HIVE_ASK_LIMIT_GLOBAL_PER_MINUTE` | No | `8` | Vendor calls per minute across the hub; keep it under the vendor's per-team chat limit, which the docs site's widget shares. |
| `HIVE_ASK_LIMIT_IN_FLIGHT` | No | `4` | Vendor calls in flight at once across the hub (one per person). |
| `HIVE_ASK_LIMIT_DAILY` | No | `500` | Vendor calls per UTC day; when spent, Ask answers with the docs-link fallback until it resets. |
| `HIVE_ASK_LIMIT_QUESTION_CHARS` | No | `1000` | Longest question accepted, in characters. |
| `HIVE_ASK_LIMIT_ANSWER_CHARS` | No | `4000` | Longest answer returned, in characters. |
| `HIVE_ASK_LIMIT_TIMEOUT_SECONDS` | No | `30` | Time allowed for one vendor call. |

## Kubernetes downward API and platform variables

| Variable | Required | Default | Purpose |
Expand Down
19 changes: 19 additions & 0 deletions src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -1433,6 +1433,25 @@ data:
# max_requests_per_hour: 10 # search requests all accepts may spend together per hour (default 10, at most 60); each accept spends at most 2


# Ask AI help (docs/design/dashboard-ask-ai-help.md, #19177): an optional help
# panel backend that sends a person's question, after they consent, to the
# vendor's Chat API from the hub. Off by default and inert. The key lives in a
# mounted Secret, never here. If enabled but a value is missing or the key file
# is unreadable it stays off and logs one warning without values.
# ask:
# enabled: false # true (or env HIVE_ASK_ENABLED=true) switches it on; default off
# mode: direct # direct on the hub (default); env HIVE_ASK_MODE
# kapa:
# project_id: "" # env HIVE_ASK_KAPA_PROJECT_ID; never returned, logged or exported
# integration_id: "" # env HIVE_ASK_KAPA_INTEGRATION_ID; same handling
# api_key_file: /secrets/ask-kapa-api-key # env HIVE_ASK_KAPA_API_KEY_FILE; must be under the allowed secret directory
# send_section_label: true # false sends the question text alone
# limits: # optional; env HIVE_ASK_LIMIT_*; see docs/env-vars.md for the defaults
# person_burst: 3
# global_per_minute: 8
# daily: 500


# Sandbox Job GitHub read relay (docs/sandbox-isolation.md): lets sandbox Jobs
# make authenticated, read-only GitHub reads without ever holding a credential.
# Default off. There is NO default bind: with enabled: true, listen_addr is
Expand Down
155 changes: 155 additions & 0 deletions src/pkg/ask/client.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
// Package ask is the backend for the optional Ask AI help (#19177): a
// server-side call to the vendor's Chat API, source filtering, limits, a
// circuit breaker and thread bookkeeping. It holds no HTTP route and no
// consent record; the hub wires those around it. See
// src/docs/design/dashboard-ask-ai-help.md.
//
// Everything that leaves the deployment is built in one place, Client.Chat,
// from named inputs, so a test against a fake vendor server can assert the
// exact request body.
package ask

import (
"bytes"
"context"
"encoding/json"
"errors"
"io"
"net/http"
"net/url"
"strings"
"time"
)

// DefaultBaseURL is the vendor's public API host.
const DefaultBaseURL = "https://api.kapa.ai"

// maxResponseBytes bounds how much of a vendor response is read.
const maxResponseBytes = 1 << 20

// Errors the client returns. None carries a request value, a response body, the
// key or a vendor identifier.
var (
// ErrRateLimited is the vendor's HTTP 429.
ErrRateLimited = errors.New("ask: vendor rate limited")
// ErrUnavailable is a timeout, a transport failure or a 5xx.
ErrUnavailable = errors.New("ask: vendor unavailable")
// ErrRejected is any other non-200 answer (a bad key, a bad request).
ErrRejected = errors.New("ask: vendor rejected the request")
// ErrBadResponse is a 200 whose body is not the pinned shape.
ErrBadResponse = errors.New("ask: vendor response not understood")
)

// chatRequest is the complete set of fields sent to the vendor. Adding a field
// here is adding to "What leaves the deployment" in the design record: it needs
// a reviewer and a test. In particular there is no user object, no metadata and
// no origin URL.
type chatRequest struct {
IntegrationID string `json:"integration_id"`
Query string `json:"query"`
}

// Source is one cited source of an answer.
type Source struct {
URL string `json:"url"`
Title string `json:"title"`
}

// ChatResponse is the non-streamed response shape, pinned by a contract test
// against the vendor's API reference (POST /query/v1/projects/{project_id}/chat/
// and POST /query/v1/threads/{thread_id}/chat/): answer, thread_id,
// question_answer_id, is_uncertain and relevant_sources[{source_url, title,
// contains_internal_data}].
type ChatResponse struct {
Answer string `json:"answer"`
ThreadID string `json:"thread_id"`
QuestionAnswerID string `json:"question_answer_id"`
IsUncertain bool `json:"is_uncertain"`
RelevantSources []VendorSource `json:"relevant_sources"`
}

// VendorSource is one entry of relevant_sources as the vendor returns it.
type VendorSource struct {
SourceURL string `json:"source_url"`
Title string `json:"title"`
ContainsInternalData bool `json:"contains_internal_data"`
}

// Client calls the vendor Chat API. The zero value is not usable; build one
// with NewClient. The key, project id and integration id are held in
// unexported fields, are never part of a returned error, and are not written to
// any log by this package.
type Client struct {
baseURL string
projectID string
integrationID string
apiKey string
http *http.Client
}

// NewClient builds a client. baseURL may be empty for the vendor default (tests
// pass a fake server). timeout bounds one request.
func NewClient(baseURL, projectID, integrationID, apiKey string, timeout time.Duration) *Client {
if baseURL == "" {
baseURL = DefaultBaseURL
}
if timeout <= 0 {
timeout = 30 * time.Second
}
return &Client{
baseURL: strings.TrimRight(baseURL, "/"),
projectID: projectID,
integrationID: integrationID,
apiKey: apiKey,
http: &http.Client{
Timeout: timeout,
// Never follow a redirect with the key attached.
CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
},
}
}

// Chat asks one question. An empty threadID starts a conversation; a non-empty
// one continues the vendor thread. Only query and the integration id are sent.
func (c *Client) Chat(ctx context.Context, query, threadID string) (ChatResponse, error) {
var endpoint string
if threadID == "" {
endpoint = c.baseURL + "/query/v1/projects/" + url.PathEscape(c.projectID) + "/chat/"
} else {
endpoint = c.baseURL + "/query/v1/threads/" + url.PathEscape(threadID) + "/chat/"
}
body, err := json.Marshal(chatRequest{IntegrationID: c.integrationID, Query: query})
if err != nil {
return ChatResponse{}, ErrBadResponse
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body))
if err != nil {
return ChatResponse{}, ErrUnavailable
}
req.Header.Set("X-API-KEY", c.apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")
resp, err := c.http.Do(req)
if err != nil {
// err is a *url.Error carrying the full URL (project id, thread id);
// drop it.
return ChatResponse{}, ErrUnavailable
}
defer resp.Body.Close()
switch {
case resp.StatusCode == http.StatusTooManyRequests:
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxResponseBytes))
return ChatResponse{}, ErrRateLimited
case resp.StatusCode >= 500:
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxResponseBytes))
return ChatResponse{}, ErrUnavailable
case resp.StatusCode != http.StatusOK:
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxResponseBytes))
return ChatResponse{}, ErrRejected
}
var out ChatResponse
if err := json.NewDecoder(io.LimitReader(resp.Body, maxResponseBytes)).Decode(&out); err != nil {
return ChatResponse{}, ErrBadResponse
}
return out, nil
}
Loading
Loading