{"slug":"platform/AI_INTEGRATION","title":"AI Integration Guide","section":"platform","sectionLabel":"Platform","status":"unclassified","type":"document","path":"platform/AI_INTEGRATION.mdx","bytes":16886,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nComplete documentation for AI models, agents, and insights throughout the Integratewise application.\n\n## Overview\n\nThe application now has comprehensive AI integration providing:\n\n- Real-time metric insights and analysis\n- Predictive forecasting and trends\n- AI-powered recommendations\n- Conversational AI agent interface\n- Tool-based agent capabilities\n\n## Architecture\n\n### Core Components\n\n1. **AI Hooks** - React hooks for AI features\n - `useAIInsights` - Generate insights from metrics\n - `useWorkbenchAI` - Comprehensive workbench AI\n - `useAIAgent` - Chat-based agent interaction\n\n2. **API Endpoints** - Backend services\n - `POST /api/ai/insights` - Generate insights\n - `POST /api/ai/analyze` - Stream analysis\n - `POST /api/ai/predict` - Generate predictions\n - `GET /api/ai/recommendations/[workbench]/[metricId]` - Get recommendations\n - `POST /api/ai/compare` - Compare metrics\n - `POST /api/ai/agent/chat` - Agent chat interface\n\n3. **AI Components** - Reusable UI components\n - `AIMetricCard` - Enhanced metric display with insights\n - `CustomerSuccessWithAI` - Complete example workbench\n\n4. **Agent Tools** - Tool definitions for agents\n - `analyze_metric` - Deep metric analysis\n - `get_metric_data` - Metric retrieval\n - `get_recommendations` - AI recommendations\n - `generate_forecast` - Predictions\n - `compare_metrics` - Comparison\n - `create_action_plan` - Action planning\n - `get_department_health` - Health assessment\n\n## Quick Start\n\n### Using AI Insights in a Component\n\n```tsx\n\n const { insights, recommendations, analysis } = useWorkbenchAI({\n workbench: \"customer-success\",\n metricContext: {\n nrr: { current: 108, trend: 2.5 },\n \"health-score\": { current: 78, trend: -1.2 },\n },\n });\n\n return (\n
\n {insights.map((insight) => (\n
\n

{insight.title}

\n

{insight.description}

\n
\n ))}\n\n \n
\n );\n}\n```\n\n### Using AI Agent\n\n```tsx\n\n const { messages, sendMessage, isLoading } = useAIAgent({\n workbench: \"customer-success\",\n });\n\n return (\n
\n {messages.map((msg) => (\n
{msg.content}
\n ))}\n e.key === \"Enter\" && sendMessage(e.currentTarget.value)}\n placeholder=\"Ask the AI agent...\"\n />\n
\n );\n}\n```\n\n### Displaying Predictions\n\n```tsx\n\n const { predictions, generatePredictions } = useWorkbenchAI({\n workbench: \"sales-operations\",\n metricContext: {\n /* ... */\n },\n });\n\n return (\n
\n \n {Object.entries(predictions).map(([key, pred]) => (\n
\n

\n {pred.metric}: {pred.current} → {pred.predicted}\n

\n

Confidence: {(pred.confidence * 100).toFixed(0)}%

\n
\n ))}\n
\n );\n}\n```\n\n## Hook Reference\n\n### useWorkbenchAI\n\nComprehensive AI integration for workbenches.\n\n```ts\nconst {\n insights, // AIInsight[]\n recommendations, // Record\n analysis, // string\n predictions, // Record\n isLoading, // boolean\n error, // string | null\n generateAnalysis, // (focusArea?: string) => Promise\n generatePredictions, // () => Promise>\n hasInsights, // boolean\n hasAnalysis, // boolean\n hasPredictions, // boolean\n} = useWorkbenchAI({\n workbench: \"customer-success\",\n metricContext: {\n /* metrics data */\n },\n enableAnalysis: true,\n enablePredictions: true,\n enableRecommendations: true,\n refreshInterval: 60000,\n});\n```\n\n### useAIInsights\n\nGenerate insights from metric context.\n\n```ts\nconst {\n insights, // AIInsight[]\n isLoading, // boolean\n error, // Error | null\n refetch, // () => void\n} = useAIInsights(\n {\n workbench: \"customer-success\",\n context: {\n /* metrics */\n },\n metricType: \"health-score\",\n includeRecommendations: true,\n includePredictions: true,\n },\n {\n enabled: true,\n refetchInterval: 60000,\n staleTime: 30000,\n }\n);\n```\n\n### useAIAgent\n\nChat interface with AI agent.\n\n```ts\nconst {\n messages, // Message[]\n isLoading, // boolean\n error, // string | null\n sendMessage, // (msg: string) => Promise\n clearMessages, // () => void\n retryLastMessage, // () => Promise\n} = useAIAgent({\n workbench: \"customer-success\",\n onMessageReceived: (msg) => console.log(msg),\n onError: (err) => console.error(err),\n});\n```\n\n## API Reference\n\n### POST /api/ai/insights\n\nGenerate AI insights from metrics.\n\n**Request:**\n\n```json\n{\n \"workbench\": \"customer-success\",\n \"context\": { \"nrr\": 108, \"health\": 78 },\n \"metricType\": \"health-score\",\n \"includeRecommendations\": true,\n \"includePredictions\": false\n}\n```\n\n**Response:**\n\n```json\n[\n {\n \"id\": \"insight-123456\",\n \"workbench\": \"customer-success\",\n \"title\": \"NRR is Above Target\",\n \"description\": \"Your NRR is performing 8% above target...\",\n \"severity\": \"info\",\n \"actionItems\": [\"Continue current strategy\", \"Identify expansion opportunities\"],\n \"confidence\": 0.85,\n \"generatedAt\": 1234567890\n }\n]\n```\n\n### POST /api/ai/analyze\n\nStream AI analysis response.\n\n**Request:**\n\n```json\n{\n \"workbench\": \"customer-success\",\n \"context\": {\n /* metrics */\n },\n \"focusArea\": \"account health\"\n}\n```\n\n**Response:** Streaming text/event-stream\n\n### POST /api/ai/predict\n\nGenerate predictions and forecasts.\n\n**Request:**\n\n```json\n{\n \"workbench\": \"sales-operations\",\n \"context\": {\n /* historical data */\n },\n \"timeframe\": \"1month\",\n \"confidenceThreshold\": 0.7\n}\n```\n\n**Response:**\n\n```json\n{\n \"predictions\": [\n {\n \"metric\": \"pipeline\",\n \"current\": 500000,\n \"predicted\": 580000,\n \"change\": 80000,\n \"changePercent\": 16,\n \"confidence\": 0.82,\n \"timeframe\": \"1month\",\n \"reasoning\": \"Based on historical trends...\"\n }\n ],\n \"timeframe\": \"1month\",\n \"generatedAt\": \"2026-07-01T00:00:00Z\"\n}\n```\n\n### GET /api/ai/recommendations/[workbench]/[metricId]\n\nGet AI recommendations for a metric.\n\n**Response:**\n\n```json\n{\n \"recommendations\": [\n \"Increase EBR frequency to 2x monthly\",\n \"Implement automated health score reviews\",\n \"Create expansion playbook for high-growth segments\"\n ]\n}\n```\n\n### POST /api/ai/agent/chat\n\nChat with AI agent.\n\n**Request:**\n\n```json\n{\n \"workbench\": \"customer-success\",\n \"message\": \"What are the top expansion opportunities?\",\n \"context\": [\n { \"role\": \"user\", \"content\": \"Previous message...\" },\n { \"role\": \"assistant\", \"content\": \"Previous response...\" }\n ]\n}\n```\n\n**Response:**\n\n```json\n{\n \"message\": \"Based on your data, I identified 3 expansion opportunities...\",\n \"toolCalls\": [],\n \"toolResults\": {}\n}\n```\n\n## Component Reference\n\n### AIMetricCard\n\nEnhanced metric card with AI insights.\n\n```tsx\n\n```\n\n**Props:**\n\n- `workbench`: Workbench name\n- `metricId`: Unique metric identifier\n- `title`: Display title\n- `value`: Metric value\n- `unit`: Unit of measurement\n- `trend`: Change percentage (positive/negative)\n- `threshold`: Target/threshold value\n- `thresholdType`: \"above\" | \"below\"\n- `context`: Optional additional context\n- `showRecommendations`: Show AI recommendations\n- `showPrediction`: Show prediction (if available)\n\n### CustomerSuccessWithAI\n\nComplete example workbench with AI integration.\n\nShows:\n\n- AI-enhanced metric cards\n- Real-time analysis\n- Predictions\n- Recommendations\n- Conversational AI agent\n\nUse as template for other workbenches.\n\n## Agent Tools\n\n### analyze_metric\n\nDeep analysis of a specific metric.\n\n```ts\nawait analyze_metric({\n workbench: \"customer-success\",\n metricId: \"nrr\",\n timeframe: \"1month\",\n focusArea: \"enterprise segment\",\n});\n```\n\n### get_recommendations\n\nAI-powered recommendations.\n\n```ts\nawait get_recommendations({\n workbench: \"sales-operations\",\n metricId: \"pipeline_coverage\",\n priorityLevel: \"high\",\n});\n```\n\n### generate_forecast\n\nPredictive forecasting.\n\n```ts\nawait generate_forecast({\n workbench: \"finance\",\n metricId: \"arpu\",\n forecastPeriod: \"3month\",\n includeConfidenceInterval: true,\n});\n```\n\n### create_action_plan\n\nAutomated action plan generation.\n\n```ts\nawait create_action_plan({\n workbench: \"customer-success\",\n objective: \"Reduce churn from 5% to 2%\",\n timeframe: \"1month\",\n resources: [\"CS team\", \"Product\"],\n});\n```\n\n## Configuration\n\n### Environment Variables\n\nEnsure these are set in your environment:\n\n```env\n# AI Gateway (optional, uses Vercel AI Gateway by default)\nAI_GATEWAY_API_KEY=your_api_key\n\n# Agent Provider (defaults to 'vercel-ai')\nNEXT_PUBLIC_AGENT_PROVIDER=vercel-ai\n```\n\n### Feature Flags\n\nAI features are controlled via feature flags in `lib/ai-features.ts`:\n\n```ts\n\n// Check if feature is enabled\nif (isFeatureEnabled(\"insight_generation\", userId)) {\n // Use insights feature\n}\n\n// Enable feature for rollout\nupdateFeatureConfig(\"insight_generation\", {\n enabled: true,\n rolloutPercentage: 50,\n});\n```\n\n## Performance Considerations\n\n1. **Caching**: Insights are cached for 30 seconds by default\n2. **Streaming**: Analysis uses streaming for better UX\n3. **Parallel Requests**: Multiple insights can be fetched in parallel\n4. **Rate Limiting**: Consider implementing rate limiting for agent calls\n\n## Error Handling\n\nAll hooks provide error states:\n\n```tsx\nconst { insights, error, isLoading } = useWorkbenchAI({\n /* ... */\n});\n\nif (error) {\n return
Error: {error}
;\n}\n\nif (isLoading) {\n return
Loading...
;\n}\n```\n\n## Examples\n\nSee `components/workbench/examples/customer-success-with-ai.tsx` for a complete working example showing:\n\n- Multi-tab interface\n- Metric cards with insights\n- Streaming analysis\n- Predictions display\n- Recommendations\n- Agent chat UI\n\n## Best Practices\n\n1. **Start with insights** - Enable chat_interface first, then gradually enable other features\n2. **Cache aggressively** - Reuse insights within their TTL\n3. **Stream large responses** - Use streaming for analysis instead of waiting\n4. **Provide context** - Include relevant metrics in context for better insights\n5. **Handle errors gracefully** - Always have fallbacks for when AI features fail\n6. **Monitor costs** - Track API usage and adjust rollout percentages\n7. **Test with real data** - Validate insights against actual business outcomes\n\n## Troubleshooting\n\n### \"AI_GATEWAY_API_KEY is not set\"\n\nSet the environment variable in your `.env.local`:\n\n```env\nAI_GATEWAY_API_KEY=your_api_key_here\n```\n\n### \"Unauthorized\" errors\n\nEnsure you're authenticated via Clerk before making requests to AI endpoints.\n\n### Slow responses\n\n- Check network latency to AI Gateway\n- Consider caching results longer\n- Enable streaming for large responses\n- Check model availability\n\n### No insights generated\n\n- Verify context data is being passed correctly\n- Check feature flags in `ai-features.ts`\n- Ensure workbench name is recognized\n- Check agent logs for errors\n\n## Future Enhancements\n\n- [ ] Real-time metric streaming\n- [ ] Custom model selection per workbench\n- [ ] Advanced tool definitions for specific departments\n- [ ] Workflow automation based on AI recommendations\n- [ ] Multi-turn complex workflows\n- [ ] Integration with external data sources\n- [ ] Custom agent training\n\n## Workers AI Model Catalog\n\nAll inference runs on Cloudflare Workers AI via the `env.AI` binding. No external API calls from the edge.\n\n### Available Models\n\n| Model ID | Role | Context Window | Key Features |\n| ---------------------------------------------- | --------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------- |\n| `moonshotai/kimi-k3` | **Primary reasoning** (Twin, critical decisions) | 1,048,576 tokens (1M) | 2.8T params, always-on reasoning, `reasoning_effort` param, native vision, Kimi Delta Attention |\n| `@cf/meta/llama-3.3-70b-instruct-fp8-fast` | **Fast reasoning** (general chat, signal analysis) | 128k tokens | 70B params, FP8 quantized, best speed/quality on CF edge |\n| `@cf/meta/llama-3.1-8b-instruct` | **Lightweight** (triage, draft generation, embeddings fallback) | 128k tokens | 8B params, low-latency, free tier |\n| `@cf/deepseek-ai/deepseek-r1-distill-qwen-32b` | **Structured reasoning** (spine analysis, entity extraction) | 128k tokens | Distilled R1, chain-of-thought |\n| `@cf/mistral/mistral-nemo-instruct-2407` | **Function calling** (MCP orchestration, tool use) | 128k tokens | Nemo, native tool-calling |\n| `@cf/qwen/qwen2.5-coder-32b-instruct` | **Code generation** (engineering assistant) | 128k tokens | Qwen 2.5 Coder, code-specialized |\n| `@cf/baai/bge-base-en-v1.5` | **Embeddings** (AI Search, semantic memory) | — | BGE base, English embeddings |\n\n### Model Selection Order\n\n1. Explicit `model` param (per-request override)\n2. `env.DEFAULT_CHAT_MODEL` (wrangler.toml var, must start with `@cf/` or be a Workers AI model ID)\n3. `CF_MODELS.PRIMARY` (hardcoded fallback — currently `moonshotai/kimi-k3`)\n\n### Reasoning Effort (Kimi K3)\n\nKimi K3 supports configurable reasoning depth via the `reasoning_effort` parameter (replaces the K2.x `thinking` parameter):\n\n```ts\n// Max reasoning for hard problems (proofs, deep analysis)\nconst response = await env.AI.run(\"moonshotai/kimi-k3\", {\n messages: [{ content: \"Prove that the square root of 2 is irrational.\", role: \"user\" }],\n reasoning_effort: \"max\",\n});\n\n// Default reasoning for general tasks\nconst response = await env.AI.run(\"moonshotai/kimi-k3\", {\n messages: [{ content: \"Explain quantum entanglement in simple terms.\", role: \"user\" }],\n});\n```\n\n**When to use `reasoning_effort: 'max'`:**\n\n- Critical decisions (tier: \"critical\")\n- Mathematical/logical proofs\n- Complex multi-step analysis\n- Deep spine entity reasoning\n\n**When to use default reasoning:**\n\n- General chat and Q&A\n- Morning briefs\n- Signal triage summaries\n- Standard Twin responses\n\n### Fallback Chain\n\n```\nmoonshotai/kimi-k3 (primary)\n ↓ on failure\n@cf/meta/llama-3.3-70b-instruct-fp8-fast (fallback-1)\n ↓ on failure\n@cf/meta/llama-3.1-8b-instruct (fallback-2)\n ↓ on failure\nError: AI_COMPLETION_ERROR\n```\n\n### REST API (Workers AI)\n\nModels can also be called via the Cloudflare REST API (OpenAI-compatible):\n\n```bash\ncurl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"model\": \"moonshotai/kimi-k3\",\n \"messages\": [\n {\n \"content\": \"Explain quantum entanglement in simple terms.\",\n \"role\": \"user\"\n }\n ]\n}'\n```\n\n### Implementation\n\nThe model catalog and fallback logic live in `services/iw-agent-runtime/src/ecosystem/ai-gateway.ts`. The multi-tier AI router is in `services/intelligence/src/lib/ai-router.ts`.\n\n## References\n\n- AI SDK: https://ai-sdk.dev\n- Vercel AI Gateway: https://vercel.com/ai-gateway\n- Feature Flags: See `lib/ai-features.ts`\n- Agent Tools: See `lib/agent/tools.ts`\n- Workers AI Model Catalog: https://developers.cloudflare.com/workers-ai/models/\n- Kimi K3: https://developers.cloudflare.com/ai/models/moonshotai/kimi-k3/\n"}