feat: add AI knowledge analysis MVP
This commit is contained in:
305
.trellis/tasks/07-04-ai-agent-knowledge-analysis/implement.md
Normal file
305
.trellis/tasks/07-04-ai-agent-knowledge-analysis/implement.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# AI Agent Knowledge Analysis Implementation Plan
|
||||
|
||||
## Preconditions
|
||||
|
||||
- User reviews and approves `prd.md`, `design.md`, and `implement.md`.
|
||||
- Task status is moved from `planning` to `in_progress` with `task.py start`.
|
||||
- Before editing code in Phase 2, load `trellis-before-dev` and relevant specs:
|
||||
- `.trellis/spec/shared/code-quality.md`
|
||||
- `.trellis/spec/shared/typescript.md`
|
||||
- `.trellis/spec/shared/dependencies.md`
|
||||
- `.trellis/spec/backend/directory-structure.md`
|
||||
- `.trellis/spec/backend/database.md`
|
||||
- `.trellis/spec/backend/authentication.md`
|
||||
- `.trellis/spec/backend/type-safety.md`
|
||||
- `.trellis/spec/backend/quality.md`
|
||||
- `.trellis/spec/frontend/components.md`
|
||||
- `.trellis/spec/frontend/type-safety.md`
|
||||
- `.trellis/spec/frontend/quality.md`
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### 1. Dependencies And Environment
|
||||
|
||||
- Add LangChain runtime packages:
|
||||
- `langchain`
|
||||
- `@langchain/core`
|
||||
- `@langchain/openai`
|
||||
- Decide and document default embedding dimension for `AI_EMBEDDING_MODEL`.
|
||||
- Add env handling in `modules/ai/server/config.ts`:
|
||||
- `AI_BASE_URL`
|
||||
- `AI_API_KEY`
|
||||
- `AI_CHAT_MODEL`
|
||||
- `AI_EMBEDDING_MODEL`
|
||||
- Update local PostgreSQL image or setup notes so pgvector is available.
|
||||
|
||||
Validation:
|
||||
|
||||
- `pnpm install`
|
||||
- `pnpm type-check`
|
||||
|
||||
Rollback:
|
||||
|
||||
- Remove added dependencies and AI env usage if the AI module is backed out.
|
||||
|
||||
### 2. Database Schema And Migration
|
||||
|
||||
- Update `modules/core/server/schema.ts`:
|
||||
- AI enums for knowledge scope/status and analysis status.
|
||||
- `aiKnowledgeEntries`.
|
||||
- `aiKnowledgeChunks`.
|
||||
- `elderAiAnalyses`.
|
||||
- Add pgvector extension migration support.
|
||||
- Generate Drizzle migration with `pnpm db:generate`.
|
||||
- Manually inspect generated SQL for:
|
||||
- `CREATE EXTENSION IF NOT EXISTS vector`.
|
||||
- Correct foreign keys.
|
||||
- Correct indexes.
|
||||
- Correct vector column type/dimension.
|
||||
|
||||
Validation:
|
||||
|
||||
- `pnpm db:generate`
|
||||
- `pnpm type-check`
|
||||
- Apply migration locally when DB is available: `pnpm db:migrate`.
|
||||
|
||||
Rollback:
|
||||
|
||||
- Drop AI tables and extension-dependent indexes in a rollback migration if needed.
|
||||
- Do not drop `vector` extension automatically if other future objects may use it.
|
||||
|
||||
### 3. Permissions And Role Seeding
|
||||
|
||||
- Update `modules/core/types.ts`:
|
||||
- Add `ai:read`, `ai:manage`, `knowledge:read`, `knowledge:manage`.
|
||||
- Update `modules/core/server/permissions.ts`:
|
||||
- Add permission definitions.
|
||||
- Update default role grants:
|
||||
- `platform_admin`: all four.
|
||||
- `org_admin`: all four.
|
||||
- `manager`: all four.
|
||||
- `caregiver`: `ai:read`, `knowledge:read`.
|
||||
- `viewer`, `family`, `resident`: none.
|
||||
- Ensure `ensureSystemDefaults()` upserts permissions and role grants without deleting custom grants.
|
||||
|
||||
Validation:
|
||||
|
||||
- `pnpm type-check`
|
||||
- Targeted tests or assertions for seeded permission definitions and role grants.
|
||||
|
||||
Rollback:
|
||||
|
||||
- Remove permissions from default grants only through an intentional migration/seed change; avoid deleting custom user role state.
|
||||
|
||||
### 4. AI Domain Types
|
||||
|
||||
- Create `modules/ai/types.ts`.
|
||||
- Define:
|
||||
- Knowledge entry input and status/scope values.
|
||||
- Analysis status values.
|
||||
- Data scope values.
|
||||
- Risk/severity/priority values.
|
||||
- Structured analysis output type and runtime validator.
|
||||
- Citation type.
|
||||
- Sanitized error category type.
|
||||
- Avoid `any`; use explicit `unknown` validation helpers when parsing API bodies or AI output.
|
||||
|
||||
Validation:
|
||||
|
||||
- Unit tests for validators if they contain non-trivial parsing.
|
||||
- `pnpm type-check`
|
||||
|
||||
Rollback:
|
||||
|
||||
- Types are isolated; remove module if feature is backed out.
|
||||
|
||||
### 5. Knowledge Service
|
||||
|
||||
- Create `modules/ai/server/knowledge.ts`.
|
||||
- Implement:
|
||||
- List visible entries by permission and active organization.
|
||||
- Create/update/delete entries with scope validation.
|
||||
- Server-side chunking.
|
||||
- Embedding generation through LangChain OpenAI-compatible embeddings.
|
||||
- Chunk rebuild on create/update.
|
||||
- Scope-filtered retrieval for platform shared + active organization entries.
|
||||
- Write audit logs for create/update/delete/enable/disable.
|
||||
- Ensure no organization-private chunks from other organizations can be retrieved.
|
||||
|
||||
Validation:
|
||||
|
||||
- Tests for scope filtering:
|
||||
- Platform shared visible to organization user.
|
||||
- Own organization visible.
|
||||
- Other organization not visible.
|
||||
- Disabled entries not retrieved.
|
||||
- Tests for mutation permission failures.
|
||||
|
||||
Rollback:
|
||||
|
||||
- Disable `/settings/knowledge` navigation and API routes if embedding is unavailable.
|
||||
- Existing tables can remain unused.
|
||||
|
||||
### 6. Elder Context Service
|
||||
|
||||
- Create `modules/ai/server/elder-context.ts`.
|
||||
- Implement permission-aware resident graph assembly:
|
||||
- Always include elder basics after `elder:read`.
|
||||
- Include health only with `health:read`.
|
||||
- Include care only with `care:read`.
|
||||
- Include family only with `family:read`.
|
||||
- Include admission/facility only with matching read permissions.
|
||||
- Include alert/incident only with matching read permissions.
|
||||
- Include knowledge only with `knowledge:read`.
|
||||
- Return `dataScopes` exactly matching included families.
|
||||
- Use batch queries and `Promise.all` for independent loads.
|
||||
|
||||
Validation:
|
||||
|
||||
- Tests for data family inclusion/exclusion by permissions.
|
||||
- Tests that target elder must belong to active organization.
|
||||
|
||||
Rollback:
|
||||
|
||||
- This service is isolated under `modules/ai`; remove API use if feature is disabled.
|
||||
|
||||
### 7. Analysis Service
|
||||
|
||||
- Create `modules/ai/server/analysis.ts`.
|
||||
- Implement:
|
||||
- Generate structured analysis synchronously with LangChain.
|
||||
- Validate AI output against fixed schema.
|
||||
- Save `completed` history with result/citations/model summary/data scopes.
|
||||
- On failure, save `failed` history with sanitized error category/reason.
|
||||
- Write success/failure audit logs.
|
||||
- Redact history details when current permissions do not satisfy stored `dataScopes`.
|
||||
- Do not store full prompts, full context snapshots, API keys, or raw provider errors.
|
||||
|
||||
Validation:
|
||||
|
||||
- Tests for:
|
||||
- Missing config -> structured failure + failed history.
|
||||
- Schema validation failure -> failed history.
|
||||
- History detail redaction when permissions are insufficient.
|
||||
- Completed history shape.
|
||||
|
||||
Rollback:
|
||||
|
||||
- Keep history rows as audit evidence; hide UI/API if provider issues block rollout.
|
||||
|
||||
### 8. API Routes
|
||||
|
||||
- Add elder analysis routes:
|
||||
- `app/api/ai/elders/[id]/analyses/route.ts`
|
||||
- `GET`: latest/history with permission-aware redaction.
|
||||
- `POST`: synchronous generation.
|
||||
- Add knowledge routes:
|
||||
- `app/api/ai/knowledge/route.ts`
|
||||
- `GET`, `POST`.
|
||||
- `app/api/ai/knowledge/[id]/route.ts`
|
||||
- `PATCH`, `DELETE`.
|
||||
- Use existing `requirePermission`, `jsonSuccess`, `jsonFailure`, `readJsonBody`, and `recordAuditLog` patterns.
|
||||
- Preserve `Cache-Control: no-store` through existing helpers.
|
||||
|
||||
Validation:
|
||||
|
||||
- Route tests for auth/permission failures and structured responses.
|
||||
- `pnpm type-check`
|
||||
|
||||
Rollback:
|
||||
|
||||
- Remove routes or return feature-disabled failures while keeping data.
|
||||
|
||||
### 9. Knowledge Settings UI
|
||||
|
||||
- Create:
|
||||
- `app/(app)/app/settings/knowledge/page.tsx`
|
||||
- `app/(app)/app/[organizationSlug]/settings/knowledge/page.tsx`
|
||||
- `modules/ai/components/KnowledgeManagementClient.tsx`
|
||||
- Update:
|
||||
- `modules/shared/lib/navigation.ts`
|
||||
- `modules/shared/components/AppSidebarNav.tsx` icon map if a new icon key is needed.
|
||||
- UI supports:
|
||||
- List/filter/search.
|
||||
- Create/edit dialog.
|
||||
- Enable/disable/delete.
|
||||
- Read-only view if missing `knowledge:manage`.
|
||||
- Follow existing settings/client component patterns.
|
||||
|
||||
Validation:
|
||||
|
||||
- Manual browser check.
|
||||
- Type-check/lint.
|
||||
|
||||
Rollback:
|
||||
|
||||
- Remove nav entry and route.
|
||||
|
||||
### 10. Elder Analysis UI
|
||||
|
||||
- Update `modules/elders/components/EldersClient.tsx`.
|
||||
- Add `AI 分析` row action for authorized users.
|
||||
- Create `modules/ai/components/ElderAiAnalysisDialog.tsx`.
|
||||
- Dialog displays:
|
||||
- Elder summary.
|
||||
- Generate button/loading state.
|
||||
- Latest completed analysis.
|
||||
- Failed state if latest attempt failed.
|
||||
- Findings, recommendations, data gaps.
|
||||
- Citations.
|
||||
- History list with restricted placeholders.
|
||||
- No chat input.
|
||||
- No one-click business mutation.
|
||||
|
||||
Validation:
|
||||
|
||||
- Manual browser check for desktop/mobile widths.
|
||||
- Confirm button text fits and table layout remains stable.
|
||||
- Verify unauthorized users do not see the action.
|
||||
|
||||
Rollback:
|
||||
|
||||
- Remove row action; API/history remains dormant.
|
||||
|
||||
### 11. Quality Gate
|
||||
|
||||
Run:
|
||||
|
||||
- `pnpm lint`
|
||||
- `pnpm type-check`
|
||||
- `pnpm test` if route/domain tests were added.
|
||||
- `pnpm build` before final completion if time and environment allow.
|
||||
|
||||
Manual checks:
|
||||
|
||||
- Knowledge CRUD as authorized admin/manager.
|
||||
- Knowledge read-only as caregiver.
|
||||
- Elder analysis generation with configured AI provider.
|
||||
- Missing AI config failure.
|
||||
- History redaction across roles.
|
||||
- Other-organization knowledge cannot appear in retrieval.
|
||||
|
||||
## Risky Files
|
||||
|
||||
- `modules/core/server/schema.ts`
|
||||
- `modules/core/types.ts`
|
||||
- `modules/core/server/permissions.ts`
|
||||
- `compose.yaml`
|
||||
- `drizzle/*`
|
||||
- `modules/elders/components/EldersClient.tsx`
|
||||
- `modules/shared/lib/navigation.ts`
|
||||
|
||||
## Rollback Points
|
||||
|
||||
- After dependency install: revert package changes if LangChain package compatibility fails.
|
||||
- After schema migration generation: inspect SQL before applying.
|
||||
- After permissions update: verify default role grants before touching UI.
|
||||
- After API routes: keep UI disabled until permission and scope tests pass.
|
||||
- After UI: remove nav/row entry if backend generation is not production-ready.
|
||||
|
||||
## Follow-Up Checks Before Start
|
||||
|
||||
- Confirm pgvector deployment support on the target PostgreSQL server.
|
||||
- Pick and document embedding dimensions for the configured default embedding model.
|
||||
- Confirm production AI provider and env var names.
|
||||
- Decide whether to add seed knowledge entries for smoke testing.
|
||||
Reference in New Issue
Block a user