AI Activation and Operations

This runbook documents what exists today in source, what is still missing, and how to verify the module once activation work is completed.

Required Integrations

• Vercel AI Gateway: required for streamed generation and embeddings through IA_GATEWAY_API_KEY.
• Qdrant: required for per-agent knowledge collections through QDRANT_URL and QDRANT_API_KEY.
• Redis: required for chat and message caching through the shared Redis cache service.
• PostgreSQL: required for the ai schema and the dedicated ai TypeORM connection.

Current Blockers

• AppModule does not import AIModule or route it through RouterModule, so none of the AI controllers are live.
• AIModule leaves controllers and providers empty even though the module already defines IaControllers, IaCommandHandlers, IaQueriesHandlers, IaServicesProvider, AiAdaptersRegistry, AgentRunnersProviders, SubAgentsProviders, and IaToolsProvider.
• apps/api/.env.example does not declare IA_GATEWAY_API_KEY, QDRANT_URL, or QDRANT_API_KEY, even though the environment schema requires them.
• AI migration files are not present under the module migration path, so the persistence contract is not yet deployment-ready.
• FileDownloadAdapter is still a stub that always fails, and FileDeletionAdapter is a no-op.

Naming Caveat

The repository still mixes ai and ia names:

• folder/module name: ai
• env var prefix: IA_
• provider arrays and Redis keys: Ia* / ia:*

Keep that inconsistency in mind when wiring configuration, logs, or search queries.

Activation Checklist

1. Import AIModule into AppModule and decide the final router prefix.
2. Register the existing controller/provider arrays inside apps/api/src/modules/ai/ai.module.ts.
3. Add the missing AI environment variables to apps/api/.env.example and deployment secrets.
4. Provision the ai schema through migrations or equivalent deployment-safe database setup.
5. Replace the placeholder file download and deletion adapters with real storage integrations.
6. Verify Qdrant reachability from the API runtime.

Verification Steps

After the activation work is complete:

1. Boot the API with valid AI and Redis environment variables.
2. Trigger the model refresh endpoint and confirm the sync status endpoint reports discovered and synced models.
3. Create an agent and confirm the response includes default knowledge and limits configs.
4. Create a chat, then post a streamed message and verify:
   • the user message is stored
   • the assistant response streams successfully
   • a chat title is generated on the first interaction
   • token usage rows and monthly summary updates are written
5. Upload a knowledge document and confirm it moves from pending to completed, with vectors present in Qdrant.
6. Ask a prompt that should hit the knowledge base and verify the search-knowledge-base tool path is exercised.

Troubleshooting

• No AI routes appear at all: confirm both AppModule wiring and AIModule provider/controller registration are complete.
• Startup fails on env validation: confirm IA_GATEWAY_API_KEY, QDRANT_URL, and QDRANT_API_KEY are present.
• Knowledge documents stay in failed: confirm the file download integration has been implemented and Qdrant is reachable.
• Chat or message reads are stale: confirm Redis is healthy and that cache invalidation runs after chat deletion and message completion.
• Model refresh conflicts immediately: another refresh is already running in the same process; check the refresh status endpoint before retrying.