teatea-pension/.trellis/tasks/archive/2026-07/07-04-ai-agent-knowledge-analysis/design.md

AI Agent Knowledge Analysis Design

Overview

Implement the MVP as a server-side LangChain AI module with PostgreSQL/pgvector-backed knowledge retrieval and a structured elder AI analysis panel in the existing elder list workflow.

The MVP is not a chat assistant. It is a deterministic product workflow:

1. Authorized user opens an elder's AI analysis dialog from the elder list.
2. Server loads only the resident data families the user can read.
3. Server retrieves enabled platform shared knowledge and enabled active-organization knowledge.
4. LangChain generates a fixed structured analysis.
5. Server saves completed or failed history, writes audit logs, and returns structured JSON.
6. UI renders latest analysis, history, citations, recommendations, and restricted placeholders where permissions do not allow detail access.

Module Boundaries

New Module

Create modules/ai/:

• modules/ai/types.ts
  • Zod-compatible validation helpers or TypeScript runtime validators for knowledge entries, analysis output, history status, risk levels, citation shapes, and data scopes.
• modules/ai/server/config.ts
  • Reads AI_BASE_URL, AI_API_KEY, AI_CHAT_MODEL, AI_EMBEDDING_MODEL, and optional timeout/limit settings.
• modules/ai/server/knowledge.ts
  • CRUD for knowledge entries.
  • Chunking and embedding on save.
  • Scope-filtered retrieval from pgvector.
• modules/ai/server/elder-context.ts
  • Builds full resident graph with permission-aware optional data families.
• modules/ai/server/analysis.ts
  • Runs LangChain analysis flow.
  • Validates structured output.
  • Saves completed/failed history.
• modules/ai/components/KnowledgeManagementClient.tsx
  • Settings UI for manual knowledge entries.
• modules/ai/components/ElderAiAnalysisDialog.tsx
  • Elder row dialog panel for generation, latest analysis, history, and citations.

Existing Integration Points

• modules/core/server/schema.ts
  • Add AI enums/tables.
• modules/core/types.ts
  • Add permissions and exported AI-related shared types as needed.
• modules/core/server/permissions.ts
  • Seed AI/knowledge permission definitions and default role grants.
• app/api/ai/...
  • New API routes for knowledge and elder analysis.
• app/(app)/app/settings/knowledge/page.tsx
  • New settings route.
• app/(app)/app/[organizationSlug]/settings/knowledge/page.tsx
  • Scoped route re-export.
• modules/shared/lib/navigation.ts
  • Add settings navigation item visible with knowledge:read.
• modules/elders/components/EldersClient.tsx
  • Add per-row AI analysis action and dialog.

Dependencies

Add runtime dependencies:

• @langchain/openai
• @langchain/core
• langchain

Add pgvector support through Drizzle/Postgres:

• Use PostgreSQL vector extension.
• Prefer a pgvector-capable Postgres image for local development instead of plain postgres:17-alpine.
• If Drizzle vector column support is insufficient for the exact version, use custom SQL migration for vector extension/index while keeping typed table metadata in schema.

Vercel AI SDK remains out of the MVP runtime path.

Data Model

Permissions

Add permission IDs:

• ai:read
• ai:manage
• knowledge:read
• knowledge:manage

Default grants:

• platform_admin: all four.
• org_admin: all four.
• manager: all four.
• caregiver: ai:read, knowledge:read.
• viewer, family, resident: none.

Knowledge Entries

Table: ai_knowledge_entries

Fields:

• id uuid primary key
• scope enum('platform', 'organization')
• organizationId uuid null references organizations(id) on delete cascade
• title text not null
• category text not null default ''
• tags text not null default ''
• body text not null
• status enum('enabled', 'disabled') not null default 'enabled'
• createdByAccountId uuid null references accounts(id)
• updatedByAccountId uuid null references accounts(id)
• createdAt timestamptz not null default now()
• updatedAt timestamptz not null default now()

Rules:

• scope='platform' requires organizationId IS NULL.
• scope='organization' requires organizationId to match the active organization.
• Platform entries require platform-level authorization to manage.
• Organization entries require active organization plus knowledge:manage.

Knowledge Chunks

Table: ai_knowledge_chunks

Fields:

• id uuid primary key
• entryId uuid not null references ai_knowledge_entries(id) on delete cascade
• organizationId uuid null
• scope enum('platform', 'organization')
• chunkIndex integer not null
• content text not null
• embedding vector(<embedding_dimensions>) not null
• sourceTitle text not null
• sourceCategory text not null default ''
• createdAt timestamptz not null default now()

Indexes:

• B-tree on (scope, organization_id).
• Vector index for embedding similarity, using pgvector operator/index supported by deployment.

Embedding dimensions are tied to AI_EMBEDDING_MODEL; document the chosen default in env configuration.

Elder AI Analyses

Table: elder_ai_analyses

Fields:

• id uuid primary key
• organizationId uuid not null references organizations(id) on delete cascade
• elderId uuid not null references elders(id) on delete cascade
• actorAccountId uuid null references accounts(id)
• status enum('completed', 'failed') not null
• dataScopes text not null
• resultJson jsonb null
• citationsJson jsonb not null default '[]'::jsonb
• modelSummaryJson jsonb not null default '{}'::jsonb
• errorCategory text not null default ''
• errorReason text not null default ''
• createdAt timestamptz not null default now()

Rules:

• Completed rows require a valid resultJson.
• Failed rows must not store prompt, full resident context, or raw provider errors.
• dataScopes stores a stable comma-separated list or JSON array; use JSONB if Drizzle ergonomics are acceptable.

Authorization Model

Generate Analysis

Required:

• Authenticated session.
• Active organization.
• ai:read.
• elder:read.
• Target elder belongs to active organization.

Optional data families:

• health only if health:read.
• care only if care:read.
• family only if family:read.
• admission only if admission:read.
• facility only if facility:read.
• alert only if alert:read.
• incident only if incident:read.
• knowledge only if knowledge:read.

dataScopes records exactly which families were included.

View Analysis History

History list can show safe metadata for rows in the active organization and elder when the user has ai:read and elder:read.

History detail requires all permissions implied by dataScopes. If missing any scope, return or render a restricted placeholder and do not include resultJson/citations content.

Knowledge Retrieval

Retrieval requires knowledge:read.

Eligible entries:

• scope='platform', status='enabled'.
• scope='organization', organizationId = activeOrganizationId, status='enabled'.

No organization-private chunks from other organizations may be retrievable.

LangChain Flow

Provider

Use OpenAI-compatible configuration:

• AI_BASE_URL
• AI_API_KEY
• AI_CHAT_MODEL
• AI_EMBEDDING_MODEL

config.ts validates required settings before generation/embedding and returns structured failures for missing configuration.

Retrieval

1. Convert resident query/context summary into embedding.
2. Query ai_knowledge_chunks with pgvector similarity.
3. Filter by allowed scopes before vector ranking.
4. Return top K chunks with source metadata:
   • source type: knowledge
   • entry id
   • chunk id
   • title
   • category
   • scope

Resident Context Assembly

Build one typed object:

• Elder basics.
• Current bed/admission context.
• Admission history.
• Health profile.
• Recent vitals.
• Chronic conditions.
• Health anomaly reviews.
• Care tasks.
• Alert triggers/rules where relevant.
• System incidents matched by elder/bed where relevant.
• Family contacts/visits/feedback.
• Retrieved knowledge snippets.

Use batch queries and Promise.all where independent. No await in loops.

Structured Output

Output schema:

• overallRiskLevel: low | medium | high | critical | unknown
• summary: string
• keyFindings: array of:
  • category: string
  • severity: info | warning | critical
  • evidence: string
  • citationIds: string[]
• recommendations: array of:
  • priority: low | normal | high | urgent
  • action: string
  • reason: string
  • citationIds: string[]
• dataGaps: string[]
• citations: array of:
  • id: string
  • sourceType: record | knowledge
  • sourceId: string
  • title: string
  • excerpt: string
• confidence: number from 0 to 1
• modelSummary: object with provider base URL host, chat model, embedding model, and generation timestamp, excluding API key.

Use LangChain structured output where possible. Validate again server-side before saving.

API Design

Elder Analysis

• GET /api/ai/elders/[id]/analyses
  • Returns latest allowed analysis metadata/detail and history list.
  • Redacts detail for records whose dataScopes exceed current permissions.
• POST /api/ai/elders/[id]/analyses
  • Synchronously generates a new analysis.
  • Returns { success: true, reason, analysis } on completion.
  • On failure, saves failed history and audit log, then returns { success: false, reason }.

Knowledge

• GET /api/ai/knowledge
  • Requires knowledge:read.
  • Lists platform and active organization entries visible to caller.
• POST /api/ai/knowledge
  • Requires knowledge:manage.
  • Creates entry, chunks, embeds, writes audit log.
• PATCH /api/ai/knowledge/[id]
  • Requires knowledge:manage.
  • Updates entry and rebuilds chunks/embeddings.
• DELETE /api/ai/knowledge/[id]
  • Requires knowledge:manage.
  • Deletes entry and cascading chunks.

All routes return the existing API response shape with Cache-Control: no-store.

UI Design

Elder List

In EldersClient:

• Add AI analysis button per row for users with ai:read.
• Use lucide icon such as Sparkles.
• Open Dialog with width="wide".
• Dialog sections:
  • Resident summary.
  • Generate button with loading state.
  • Latest analysis summary.
  • Findings and recommendations.
  • Data gaps.
  • Citations.
  • History list with restricted placeholders.

No chat input and no one-click business creation.

Knowledge Settings Page

Route: /settings/knowledge

Features:

• List entries by scope/status/category/search.
• Create/edit dialog with title, body, category, tags, scope, enabled/disabled.
• Disable mutations when missing knowledge:manage.
• Show embedding/rebuild status through response messages; no background jobs.

Audit And Logging

Audit actions:

• ai.elderAnalysis.generate
• ai.elderAnalysis.generateFailed
• ai.knowledge.create
• ai.knowledge.update
• ai.knowledge.delete
• ai.knowledge.disable
• ai.knowledge.enable

Audit records include actor, organization, target type/id, result, and sanitized reason.

Do not store:

• Full prompts.
• Full resident context snapshots.
• Raw provider errors.
• API keys.

Failure Handling

Generation failures are classified:

• missing_configuration
• provider_error
• timeout
• schema_validation_failed
• retrieval_failed
• unknown

On failure:

1. Save failed analysis history with sanitized category/reason.
2. Write audit log.
3. Return structured API failure.
4. UI shows a concise error state and keeps prior completed history visible.

Rollout And Compatibility

• Requires database migration for pgvector extension, AI enums, knowledge tables, chunk table, analysis table, and permissions.
• Local compose.yaml should use a pgvector-capable PostgreSQL image or document manual extension installation.
• Production deployment must verify CREATE EXTENSION vector support before migration.
• If AI env vars are missing, knowledge CRUD can still work except embedding-dependent save should fail gracefully; analysis generation should return a structured configuration failure.

Open Trade-Offs

• Embedding dimensions depend on the selected embedding model. The implementation should define a default and document migration impact if changed.
• Synchronous generation is acceptable for MVP but can be replaced later by async jobs using the same history table status field.
• Platform shared knowledge increases utility but requires careful scope filters in every retrieval query.