teatea-pension/.trellis/tasks/07-04-ai-agent-knowledge-analysis/implement.md

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.