oneie/one/things/plans/ai-integration-plan.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: AI SDK Integration Plan  
dimension: things
category: plans
tags: ai, ai-sdk, agent, architecture, integration
related_dimensions: connections, events, knowledge
scope: global
created: 2025-11-10
updated: 2025-11-10
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the plans category.
  Location: one/things/plans/ai-integration-plan.md
  Purpose: Master integration plan for AI SDK + AI Elements  
  Related dimensions: connections, events, knowledge
  For AI agents: Read this to understand the AI integration strategy
---

# AI SDK Integration Plan: Complete Codebase Integration Map

**Version:** 1.0.0  
**Status:** Planning  
**Created:** 2025-11-10  
**Stack:** Vercel AI SDK 5 + AI Elements + Effect.ts + Convex + 6-Dimension Ontology

---

## Executive Summary

This document maps the complete integration of **Vercel AI SDK** and **AI Elements** across the ONE Platform codebase. It provides a comprehensive file-by-file integration map for implementing AI capabilities with the 6-dimension ontology.

**Integration Goals:**
1. Provider-agnostic AI (OpenAI, Anthropic, Google, etc.)
2. Production-ready UI (AI Elements)
3. Effect.ts service layer  
4. Convex real-time backend
5. 6-dimension ontology alignment
6. Multi-tenant agent system
7. AG-UI protocol (CopilotKit-inspired)

---

## Part 1: Codebase Analysis Summary

### Search Results Overview

**Todo Files (216):** Including one/things/todo-ai.md with 100-cycle roadmap
**Project Files (423):** Including web/src/pages/projects/ and templates  
**Agent Files (50+):** Complete agent system with specifications
**Services (15):** All following ontology patterns
**AI Documentation:** Comprehensive plans for AI SDK, Elements, Tools, CopilotKit

---

## Part 2: File Integration Map (96 Total Files)

### Backend Files (35 files)

**New Files to Create:**
```
backend/convex/schema.ts (modify - add AI tables)
backend/convex/ai/config.ts
backend/convex/ai/models.ts  
backend/convex/ai/tools.ts
backend/convex/services/llm-service.ts
backend/convex/services/agent-ui-service.ts
backend/convex/services/rag-service.ts
backend/convex/services/agent-orchestrator.ts
backend/convex/protocols/agent-ui.ts
backend/convex/mutations/ai/generate.ts
backend/convex/mutations/ai/stream.ts
backend/convex/mutations/ai/threads.ts
backend/convex/mutations/ai/agents.ts
backend/convex/queries/ai/calls.ts
backend/convex/queries/ai/threads.ts  
backend/convex/queries/ai/agents.ts
+ 10 test files
+ 5 tool files
```

### Frontend Files (48 files)

**New Files to Create:**
```
web/src/components/ai/Chatbot.tsx
web/src/components/ai/Message.tsx
web/src/components/ai/PromptInput.tsx
web/src/components/ai/MessageList.tsx
web/src/components/ai/AgentMessage.tsx
web/src/components/ai/CodeBlock.tsx
web/src/components/ai/Reasoning.tsx
web/src/components/ai/ToolCall.tsx
web/src/components/ai/LoadingIndicator.tsx
web/src/components/ai/Suggestions.tsx

web/src/components/generative-ui/GenerativeUIRenderer.tsx
web/src/components/generative-ui/DynamicChart.tsx
web/src/components/generative-ui/DynamicTable.tsx
web/src/components/generative-ui/DynamicCard.tsx
web/src/components/generative-ui/DynamicForm.tsx
web/src/components/generative-ui/DynamicList.tsx
web/src/components/generative-ui/DynamicTimeline.tsx

web/src/hooks/ai/useAIChat.ts
web/src/hooks/ai/useCompleteChatFlow.ts
web/src/hooks/ai/useAgentContext.ts
web/src/hooks/ai/useTokenUsage.ts
web/src/hooks/ai/useAgentActions.ts
web/src/hooks/ai/useGenerativeUI.ts

web/src/pages/chat/index.astro
web/src/pages/chat/[threadId].astro
web/src/pages/agents/index.astro
web/src/pages/agents/[agentId].astro
web/src/pages/dashboard/ai-usage.astro

+ 15 test files
```

**Files to Modify:**
```
web/src/services/ThingService.ts (add agent methods)
web/src/services/EventService.ts (add AI events)
web/src/services/KnowledgeService.ts (add RAG search)
```

### Configuration Files (5 files)

```
web/package.json (add: ai, @ai-sdk/*, zod, recharts)
backend/convex/package.json (add: ai, @ai-sdk/*, effect)
web/.env.local (PUBLIC_CONVEX_URL)
backend/.env.local (AI API keys)
.github/workflows/ai-tests.yml (CI/CD)
```

### Documentation Files (8 files)

```
one/knowledge/ai-sdk-implementation.md
one/knowledge/ag-ui-protocol.md
one/knowledge/generative-ui-patterns.md
one/events/ai-integration-complete.md  
one/events/ai-integration-lessons-learned.md
README-AI.md
docs/AI-QUICKSTART.md
docs/AI-API-REFERENCE.md
```

---

## Part 3: Integration Roadmap

### Phase 1: Backend (Cycles 1-30) - agent-backend
- Install AI SDK dependencies  
- Extend schema with AI tables
- Implement Effect.ts services (LLM, AgentUI, RAG)
- Create AG-UI protocol types
- Build mutations and queries
- Write backend tests

### Phase 2: Frontend (Cycles 31-60) - agent-frontend  
- Install AI Elements
- Create AI component library (10 components)
- Build generative UI components (7 components)
- Implement React hooks (6 hooks)
- Build Astro pages (5 pages)
- Style with Tailwind v4
- Write frontend tests

### Phase 3: Integration (Cycles 61-90) - agent-integrator + agent-quality
- Integrate existing services
- Test end-to-end flows  
- Performance optimization
- Security audit
- Integration tests

### Phase 4: Deployment (Cycles 91-100) - agent-documenter + agent-ops
- Complete documentation
- Configure CI/CD
- Production deployment
- Monitoring setup

---

## Part 4: Ontology Mapping

### Things Dimension
- `ai_agent` - Agent entities with model config
- `ai_thread` - Conversation containers
- `ai_message` - Individual messages

### Connections Dimension
- `user_interacts_with_agent`
- `agent_owns_tool`
- `agent_trained_on_knowledge`
- `agent_collaborates_with_agent`

### Events Dimension
- `ai_generation_completed`
- `ai_error_occurred`
- `ai_tool_called`
- `ai_thread_created`
- `ai_message_added`

### Knowledge Dimension
- Vector embeddings for RAG
- Similarity search
- Citation tracking

### Groups Dimension
- Per-group quotas
- Per-group model preferences
- Per-group rate limits

### People Dimension  
- platform_owner: Full AI access
- org_owner: Org AI management
- org_user: Use org agents
- customer: Limited access

---

## Part 5: Success Metrics

**Technical:**
- 96 files created/modified
- 100% type safety
- >85% test coverage
- <3s response latency

**Functional:**
- End-to-end chat works
- Generative UI renders correctly
- Multi-agent orchestration functional
- Context sharing bidirectional

**Ontology:**
- All 6 dimensions mapped
- Events logged for all operations
- Connections tracked correctly
- Multi-tenancy enforced

---

## Appendix: Agent Responsibilities

| Specialist | Phase | Files | Cycles |
|------------|-------|-------|--------|
| agent-backend | 1 | 35 | 1-30 |
| agent-frontend | 2 | 48 | 31-60 |
| agent-integrator | 3 | 10 | 61-75 |
| agent-quality | 3 | 20 | 61-90 |
| agent-documenter | 4 | 8 | 91-100 |
| agent-ops | 4 | 5 | 91-100 |
| agent-director | All | - | 1-100 |

---

**Status:** Ready for execution  
**Next Action:** Agent director assigns specialists and kicks off Phase 1

_Master integration plan for AI SDK + AI Elements across ONE Platform_