# 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.