Complete the hosted administrative panel after the no-panel preview release
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 321
- Avg merge
- 6h 22m
- Merged PRs (30d)
- 26
Description
## Summary
Close out the optional hosted administrative panel. The cross-repository contract is **decided, frozen, and implemented** (ADR-0004); what remains is the **live evidence** required to lift the three feature gates that keep the user-history and operator surfaces disabled by default.
## Why will we implement this?
- **Problem / opportunity:** The contract this issue originally set out to define now exists. `ADR-0004-hosted-panel-conversations-contract.md` is `Status: Implemented (contract frozen)`, backed by the versioned `contracts/conversations-panel-v1.schema.json` + `.sha256` in `Azure/GPT-RAG`, and by three merged component PRs (2026-08-07): `gpt-rag-orchestrator#308` (stateless, zero managed-Conversations RBAC on the container), `gpt-rag-ui#99` (BFF as the exclusive Conversations owner: history / feedback / deletion), and `gpt-rag-ingestion#274` (privacy-safe operator overview and corpus curation). All three are inside the currently pinned releases. What is still missing is not code — it is the documented runtime evidence each gate requires before it can be turned on.
- **Business value / outcome:** Operators get a supportable panel whose authorization model is provable rather than assumed. Until the evidence exists, every surface fails closed, so the hosted preview ships safely with the panel off.
- **Success metrics (how we know it worked):** A hosted/panel deployment with immutable pins passes live validation; user history resolves through the BFF under owner binding; operator surfaces authorize against an explicit app role or group; and the three App Configuration gates move from `false` to `true` with the evidence recorded.
## What does it do? (Functional Overview)
- **Core behavior:** Produce the live validation that lifts the three deployment-published gates, each of which is independently `false` today:
- `PANEL_HISTORY_ENABLED` — user-facing conversation history through the UI BFF.
- `PANEL_HISTORY_OWNER_BINDING_VALIDATED` — evidence that owner binding holds for the selected mechanism (`delegated` vs. `capability`, per ADR-0003).
- `PANEL_OPERATOR_SURFACES_ENABLED` — ingestion operator overview and corpus curation, which additionally require `PANEL_OPERATOR_APP_ROLE` or `PANEL_OPERATOR_GROUP_ID`.
- **Architectural note (supersedes this issue's original framing):** Managed-Conversation reads no longer belong to `gpt-rag-ingestion`. Because the Foundry gateway strips the `Authorization` header, the hosted container has no authenticated source of the caller identity; ADR-0004 therefore moved every managed-Conversation create/read/append/delete to the authenticated **UI BFF**. The `501 Not Implemented` on `GET /api/panel/conversations/{id}/history` in `gpt-rag-ingestion` is consequently **correct and permanent by design**, not a gap to close — ingestion holds Cosmos Data *Reader* for operator overview counts only and never sees message content.
- **Data collection / storage needs:** Unchanged and already enforced. Foundry managed Conversations remains the sole store of chat content. Cosmos carries metadata only — identifiers, titles, timestamps, ratings, category codes, counts — partitioned by `/principal_id`, and exists only when `DEPLOY_ADMINISTRATIVE_PANEL=true`.
- **Data analysis / reporting needs:** Validate authorization, correlation (`req_` correlation IDs shared with `audit-event-v1`), fail-closed error behavior, and telemetry without logging tokens or protected content.
- **Nice to have (stretch goals):** Automated hosted/panel regression coverage in an approved isolated validation environment.
## Components
- **Components (check all that apply):
- [x] gpt-rag-orchestrator
- [x] gpt-rag-ingestion
- [x] gpt-rag-ui
- [ ] gpt-rag-mcp
## Acceptance criteria
- [x] The managed Conversation history contract is versioned and documented — `contracts/conversations-panel-v1.schema.json` + `.sha256`, specified by ADR-0004.
- [x] The panel surfaces exist without success-shaped placeholders — user history / feedback / deletion in the UI BFF (`panel_routes.py`), operator overview / curation in ingestion (`api/panel_operator.py`).
- [x] Missing identity, configuration, or Foundry access fails closed with a controlled error — ingestion mounts the admin and `/api/panel/*` surfaces conditionally per deployment mode at startup (`_mount_admin_and_panel_surface`), and `panel_operator` returns `503` unless `DEPLOY_ADMINISTRATIVE_PANEL=true`, `PANEL_OPERATOR_SURFACES_ENABLED=true`, and an explicit operator role or group are all set.
- [x] Container-scoped (never account-scoped) Cosmos RBAC is composed for the panel — `config/panel/setup.py` in `Azure/GPT-RAG`.
- [ ] **Remaining:** hosted/panel passes a live deployment and runtime validation with immutable component pins. No end-to-end hosted-panel run has been executed; the previous attempt was blocked by the ACR build-path failure tracked in #597.
- [ ] **Remaining:** the three gates above are lifted with their evidence recorded.
- [ ] **Remaining:** user and operator documentation is updated before the panel is marked supported.
## Release relationship
The contract and all component code are shipped in the current pins: `gpt-rag-ui v2.6.2`, `gpt-rag-orchestrator v4.1.1`, `gpt-rag-ingestion v2.7.3`, umbrella `v3.8.3`. Hosted-panel topology composition is selectable only by explicit operator choice, and `DEPLOY_ADMINISTRATIVE_PANEL` stays `false` by default. This issue now owns lifting the three evidence gates and promoting hosted/panel to supported — not building the panel.
Contributor guide
Research direction
Start with ADR-0004-hosted-panel-conversations-contract.md and the remaining acceptance criteria, then inspect panel_routes.py, api/panel_operator.py, and _mount_admin_and_panel_surface. Run a hosted/panel deployment using the pinned component releases, investigate the ACR build-path issue in #597 if needed, and record live validation evidence showing the three gates can be enabled and the user and operator documentation is updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, python
- Domain
- backend-api-design, cloud, devops, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100