chore(task): archive 07-04-ai-agent-knowledge-analysis
This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
# AI agent knowledge analysis
|
||||
|
||||
## Goal
|
||||
|
||||
Add an AI capability layer for TeaTea Pension that can use agent-style orchestration, retrieve organization-scoped knowledge, and provide AI analysis in relevant care-operation workflows.
|
||||
|
||||
The MVP workflow is elder profile AI analysis: given one resident, the system should gather authorized, organization-scoped resident context, retrieve relevant knowledge, and produce a cited, structured operational analysis for staff review.
|
||||
|
||||
The MVP interaction is a fixed "generate AI analysis" panel, not a conversational assistant. The panel should produce structured output such as risk summary, key evidence, recommended actions, source citations, and confidence.
|
||||
|
||||
The MVP entry point should be an "AI 分析" action in each elder table row. Clicking it opens a `wide` dialog panel that shows elder context, a generate action, the latest analysis, analysis history, and citations.
|
||||
|
||||
The MVP resident context should use the full available resident graph: elder basics, current bed/admission context, admission history, health profile, recent vitals, chronic conditions, health anomaly reviews, care tasks, alerts/incidents, family feedback, and relevant knowledge-base snippets.
|
||||
|
||||
MVP knowledge-base content should be manually maintained as structured knowledge entries with title, body, category/tags, scope, organization scope when applicable, and enabled status. On save, the server should chunk and embed the content into pgvector-backed storage. File upload, OCR, web crawling, and external-system sync are out of scope for MVP ingestion.
|
||||
|
||||
MVP retrieval should support platform shared knowledge plus organization-private knowledge. Ordinary organization users can retrieve enabled platform shared entries and enabled entries for their active organization. Platform knowledge is maintained by platform-level authorized users; organization knowledge is maintained by organization-level authorized users.
|
||||
|
||||
MVP must include a `/settings/knowledge` management page under the existing settings area. The sidebar entry should live in the "管理系统" group, be visible to `knowledge:read`, and allow create/edit/enable/disable/delete only with `knowledge:manage`.
|
||||
|
||||
MVP elder analyses should be persisted as history records with organization, elder, actor, structured result, source citations, model configuration summary, status, and creation time. Persisting history supports auditability, comparison over time, and token-cost control.
|
||||
|
||||
MVP AI analysis output must be a fixed structured schema rendered by the frontend rather than free-form text. The schema should include `overallRiskLevel`, `summary`, `keyFindings[]`, `recommendations[]`, `dataGaps[]`, `citations[]`, `confidence`, and `modelSummary`. Findings should include category, severity, evidence, and citation references. Recommendations should remain advisory and must not create business drafts.
|
||||
|
||||
MVP analysis generation should run synchronously in the request. The UI should show a loading state while generation is in progress. Analysis history should support at least `completed` and `failed` statuses so failures are visible and auditable without requiring an async job system.
|
||||
|
||||
On generation failure, the system should save a `failed` analysis history record and write an audit log. Failed history records must store only sanitized error category and brief reason, such as `provider_error`, `timeout`, or `schema_validation_failed`; they must not store full prompts, resident context, sensitive data, or raw provider errors.
|
||||
|
||||
Each analysis history record must store `dataScopes` describing the data families used to generate it, such as `elder`, `health`, `care`, `family`, `admission`, `alert`, `incident`, and `knowledge`. Viewing a history detail requires `ai:read`, `elder:read`, active organization access, and all read permissions implied by that record's `dataScopes`; otherwise the UI should show a restricted placeholder rather than the analysis content.
|
||||
|
||||
The broader planning objective still covers:
|
||||
|
||||
- LangChain + agent module.
|
||||
- Knowledge-base retrieval.
|
||||
- AI analysis from multiple places in the product.
|
||||
|
||||
The feature should improve operational decision support without weakening tenant isolation, role permissions, auditability, or existing deterministic workflows.
|
||||
|
||||
## Confirmed Facts
|
||||
|
||||
- The application is a single-repo Next.js 15 / React 19 / TypeScript app with API routes, Drizzle ORM, PostgreSQL, and TailwindCSS. See `package.json`.
|
||||
- Runtime dependencies currently do not include `ai`, `@ai-sdk/*`, `langchain`, vector database clients, or embedding providers. See `package.json`.
|
||||
- Local infrastructure currently runs a single `postgres:17-alpine` service, and Drizzle migrations are generated from `modules/core/server/schema.ts`. There is no existing pgvector extension or external vector database configuration. See `compose.yaml` and `drizzle.config.ts`.
|
||||
- Project specs already contain Vercel AI SDK guidance for backend and frontend AI features in `.trellis/spec/backend/ai-sdk-integration.md` and `.trellis/spec/frontend/ai-sdk-integration.md`.
|
||||
- The actual backend code uses `modules/core/server/*` for database, auth, audit, permissions, and schema; it is not using the package layout shown in some generic specs.
|
||||
- Authentication uses a custom `teatea_session` cookie and Drizzle-backed `sessions`, `accounts`, `organizations`, `memberships`, `roles`, and permissions. See `modules/core/server/auth.ts` and `.trellis/spec/backend/authentication.md`.
|
||||
- Most operational tables are tenant-scoped by `organizationId`, and resident-specific data often includes `elderId`. See `modules/core/server/schema.ts`.
|
||||
- Current permission families include care, health, device, notice, alert, family, facility, admission, elder, incident, audit, role, account, organization, and platform permissions. See `modules/core/types.ts` and `modules/core/server/permissions.ts`.
|
||||
- The dashboard already aggregates elders, beds, admissions, care tasks, health reviews, and emergency incidents with permission checks. See `app/(app)/app/dashboard/page.tsx`.
|
||||
- Health currently has deterministic anomaly detection for vital records and creates health anomaly reviews from thresholds. See `modules/health/server/operations.ts`.
|
||||
- Alerting already has rule and trigger tables that can represent warnings and suggested handling. See `modules/alerts/server/operations.ts` and `modules/core/server/schema.ts`.
|
||||
- Existing elder/bed operational context can already attach permission-filtered care task, health review/vital, and incident lines to elders. See `modules/operations/server/context.ts`.
|
||||
- Health profile, vital, chronic condition, anomaly review, family contact, visit, feedback, and admission data exist but would need an AI-specific resident context assembler to gather one resident's full analysis input. See `modules/health/server/operations.ts`, `modules/family/server/operations.ts`, and `modules/core/server/operations.ts`.
|
||||
- API responses use `{ success, reason, ...payload }` and `Cache-Control: no-store`. See `modules/core/server/api.ts`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- The AI module must preserve organization isolation: every retrieval, prompt context, generated analysis, and generated action draft must be scoped to the authenticated active organization unless the caller has a platform-level reason to cross scopes.
|
||||
- The AI module must preserve existing role permissions: analysis endpoints must require the same read permissions as the underlying data they inspect, and any write/action-producing workflow must require the matching manage permission.
|
||||
- MVP authorization must add dedicated AI and knowledge permissions while still applying underlying domain data permissions.
|
||||
- Dedicated MVP permission points should include `ai:read`, `ai:manage`, `knowledge:read`, and `knowledge:manage`.
|
||||
- Generating elder AI analysis must require `ai:read`, `elder:read`, an active organization, and only include optional resident-context data when the caller has the matching read permission such as `health:read`, `care:read`, `alert:read`, `family:read`, `admission:read`, `facility:read`, or `incident:read`.
|
||||
- Analysis history details must be filtered by stored `dataScopes` so users cannot view generated content derived from data families they cannot currently read.
|
||||
- Maintaining knowledge entries must require `knowledge:manage`; using retrieved knowledge in analysis must require `knowledge:read`.
|
||||
- Default role seeding should grant:
|
||||
- `platform_admin`: `ai:read`, `ai:manage`, `knowledge:read`, `knowledge:manage`.
|
||||
- `org_admin`: `ai:read`, `ai:manage`, `knowledge:read`, `knowledge:manage`.
|
||||
- `manager`: `ai:read`, `ai:manage`, `knowledge:read`, `knowledge:manage`.
|
||||
- `caregiver`: `ai:read`, `knowledge:read`.
|
||||
- `viewer`, `family`, and `resident`: no AI or knowledge permissions by default.
|
||||
- The first implementation should add a shared server-side AI boundary rather than scattering provider calls across feature modules.
|
||||
- The AI boundary must allow future provider/model changes without touching each product surface.
|
||||
- MVP AI orchestration must use LangChain as the primary server-side runtime for model calls, retrieval chains, agent/tool orchestration, and structured analysis output.
|
||||
- Vercel AI SDK should not be part of the MVP runtime path; keep it as a future option for conversational or streaming UI work.
|
||||
- MVP model access must use an OpenAI-compatible configurable provider interface with environment variables for base URL, API key, chat model, and embedding model.
|
||||
- The MVP UI must be a structured analysis panel attached to the elder profile/list workflow rather than a free-form chat assistant.
|
||||
- The MVP elder UI entry point must be an "AI 分析" action in each elder table row that opens a `wide` dialog panel.
|
||||
- MVP knowledge management UI must be available at `/settings/knowledge` with read access gated by `knowledge:read` and mutations gated by `knowledge:manage`.
|
||||
- The MVP analysis input must use the full available resident graph when the caller has matching read permissions.
|
||||
- MVP LangChain agent/tools must be read-only. They may load resident context, retrieve knowledge, and read analysis history, but must not provide mutation tools.
|
||||
- Knowledge retrieval must return source metadata that the UI can display or store with the analysis, so AI outputs are traceable to underlying records or documents.
|
||||
- MVP knowledge retrieval must store chunks and embeddings in PostgreSQL with pgvector, reusing the existing Drizzle/Postgres persistence boundary.
|
||||
- MVP knowledge ingestion must support manually maintained knowledge entries and server-side chunking/embedding on save.
|
||||
- MVP knowledge retrieval must include enabled platform shared knowledge plus enabled active-organization private knowledge, filtered by caller permissions.
|
||||
- AI analysis must be advisory by default. MVP output is limited to summaries, risk notes, recommendations, data gaps, and citations; future action-draft workflows require separate requirements and explicit user confirmation.
|
||||
- MVP elder AI analysis must only display structured recommendations. It must not create confirmable business drafts or one-click mutations for care tasks, alert triggers, health review notes, or other operational records.
|
||||
- MVP elder AI analyses must be saved as history records after generation.
|
||||
- MVP generation should run synchronously and save completed or failed history status.
|
||||
- Failed generation attempts must persist sanitized failed history and write audit logs.
|
||||
- Generated outputs must use structured schemas where the product needs machine-readable data, such as severity, confidence, citations, suggested next steps, or draft entity payloads.
|
||||
- MVP elder analysis output must use a fixed JSON-compatible schema with risk level, summary, findings, recommendations, data gaps, citations, confidence, and model summary.
|
||||
- AI calls must have observable failure handling: user-facing failures should be structured, and server logs/audit records should identify operation type, actor, organization, target, and result.
|
||||
|
||||
## Candidate Product Surfaces
|
||||
|
||||
- MVP: Elder profile analysis: summarize one resident's health notes, vitals, care tasks, alerts, admissions, and family feedback.
|
||||
- Dashboard executive summary: summarize current risk across care, health, beds, admissions, and incidents.
|
||||
- Health anomaly explanation: explain why a review matters and suggest follow-up questions or actions.
|
||||
- Alert and incident triage: summarize context, recommend severity/status, and draft handling notes.
|
||||
- Care operations assistant: answer operational questions from scoped data and draft care-task notes.
|
||||
- Knowledge-base Q&A: retrieve internal policies, care protocols, notices, facility SOPs, and relevant system records.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not bypass deterministic rules already present in health anomaly detection and alert handling; AI should augment those flows first.
|
||||
- Do not introduce unscoped vector search that can leak data across organizations.
|
||||
- Do not introduce a separate vector database/service for the MVP.
|
||||
- Do not let AI-specific permissions bypass the underlying domain permissions for resident, health, care, family, alert, admission, facility, device, or incident data.
|
||||
- Do not show analysis history content to users who lack read permission for any stored `dataScopes` used by the analysis.
|
||||
- Do not expose organization-private knowledge to other organizations through platform shared retrieval.
|
||||
- Do not include file upload, document parsing, OCR, crawling, or external knowledge sync in the MVP.
|
||||
- Do not make knowledge maintenance API-only; MVP needs a user-facing settings page.
|
||||
- Do not store full prompts or sensitive resident data in third-party logs unless explicitly configured and reviewed.
|
||||
- Do not store full prompts, resident context, sensitive data, or raw provider errors in failed history records.
|
||||
- Do not hard-code a single model vendor into feature modules.
|
||||
- Do not treat generated AI analysis history as an authoritative clinical record; it is advisory operational support.
|
||||
- Do not add "one-click create" or confirmable draft business mutations from MVP AI analysis output.
|
||||
- Do not define mutation-capable LangChain tools in the MVP, even if they are not exposed in the UI.
|
||||
- Do not require frontend components to know provider-specific APIs.
|
||||
- Do not start implementation until `design.md` and `implement.md` exist and the user has approved the final planning artifacts.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] PRD identifies elder profile AI analysis as the MVP user workflow and fixed structured analysis panel as the MVP interaction.
|
||||
- [ ] Elder list rows expose an AI analysis action for authorized users and open a wide analysis dialog.
|
||||
- [ ] PRD defines the full resident graph as MVP data sources and identifies out-of-scope AI surfaces.
|
||||
- [ ] Technical design defines the AI server module boundary, provider/orchestration choice, RAG storage strategy, authorization model, source-citation contract, audit/logging contract, and fallback behavior.
|
||||
- [ ] MVP implementation uses LangChain as the server-side AI orchestration layer and does not introduce Vercel AI SDK runtime code.
|
||||
- [ ] MVP model configuration supports OpenAI-compatible `AI_BASE_URL`, `AI_API_KEY`, `AI_CHAT_MODEL`, and `AI_EMBEDDING_MODEL` style settings.
|
||||
- [ ] Implementation plan defines ordered steps, validation commands, risky files, migration needs, and rollback points.
|
||||
- [ ] Any implemented AI analysis endpoint checks authentication, active organization, and required permissions before loading data or retrieving knowledge.
|
||||
- [ ] MVP adds and seeds `ai:read`, `ai:manage`, `knowledge:read`, and `knowledge:manage` permission definitions and assigns them to appropriate default operational/admin roles.
|
||||
- [ ] Default role permission seeding matches the agreed AI/knowledge grants for platform admins, org admins, managers, caregivers, viewers, family users, and residents.
|
||||
- [ ] Elder analysis context only includes each optional data family when the caller has the matching domain read permission.
|
||||
- [ ] Analysis history records store `dataScopes`, and history detail visibility is denied or redacted when the current user lacks any required scope permission.
|
||||
- [ ] Any implemented retrieval mechanism stores and filters knowledge by organization scope and returns source metadata with each retrieval result.
|
||||
- [ ] MVP retrieval uses PostgreSQL + pgvector with Drizzle migrations and organization-scoped query filters.
|
||||
- [ ] MVP knowledge entries can be manually maintained and embedded into searchable chunks with source metadata.
|
||||
- [ ] `/settings/knowledge` exists for authorized users and supports list, filter, create, edit, enable/disable, and delete workflows.
|
||||
- [ ] Knowledge retrieval includes only enabled platform shared knowledge and enabled knowledge for the caller's active organization.
|
||||
- [ ] MVP AI analysis output contains recommendations only and does not create or persist business drafts/actions beyond the analysis history record itself.
|
||||
- [ ] MVP LangChain tools are read-only and cannot mutate care, health, alert, family, admission, facility, incident, or knowledge data.
|
||||
- [ ] MVP AI analysis responses and persisted history use the fixed structured output schema.
|
||||
- [ ] Generated elder analyses are persisted with actor, elder, organization, structured result, citation metadata, model summary, status, and timestamps.
|
||||
- [ ] Synchronous generation shows a loading state and returns structured API success/failure responses.
|
||||
- [ ] Failed generation attempts persist sanitized failed history records and audit logs without full prompts or raw sensitive context.
|
||||
- [ ] Quality verification includes `pnpm lint`, `pnpm type-check`, and targeted tests for permission scoping and structured failure behavior.
|
||||
|
||||
## Likely Out of Scope For MVP
|
||||
|
||||
- Fully autonomous agents that mutate production records without a user confirmation step.
|
||||
- Cross-organization analytics for ordinary organization users.
|
||||
- Replacing existing deterministic anomaly rules with AI-only decisions.
|
||||
- Conversational AI/chat UX for MVP elder analysis.
|
||||
- Real-time streaming chat across the whole product.
|
||||
- Async generation jobs, background workers, polling, and retry queues.
|
||||
- Building a full document-management system before the minimum knowledge-ingestion path is defined.
|
||||
- PDF/Word upload, OCR, web crawling, and external-system knowledge synchronization.
|
||||
Reference in New Issue
Block a user