306 lines
9.5 KiB
Markdown
306 lines
9.5 KiB
Markdown
# 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.
|