npm package: @lineai/assistant
Description: Line AI Assistant typescript library
Latest version: 1.1.9

# LineAI Assistant SDK

A comprehensive TypeScript library providing a unified server-side interface layer to LineAI's extensive service ecosystem for AI assistant applications.

## Overview

The LineAI Assistant SDK acts as a bridge between AI assistants and existing LineAI service implementations, exposing functionality through Firestore Admin SDK data access and service API calls while providing AI-compatible tools for assistant integration.

## Features

- 🔧 **Functional Programming**: Pure functions with immutable data and minimal abstractions
- 🔒 **Type Safety**: Full TypeScript with strict typing for all Firestore documents
- 🚀 **Server-Side Execution**: Designed for Node.js environments (Next.js API routes, Cloud Functions)
- 🔌 **Service Independence**: Each service can be used standalone
- 🤖 **AI Tool Integration**: Services expose AI SDK v5-compatible tools
- 🔍 **Smart Error Handling**: Structured error responses with actionable suggestions for AI reasoning

## Installation

```bash
# Using yarn (recommended)
yarn add @lineai/assistant

# Using npm
npm install @lineai/assistant
```

## Quick Start

### 1. Environment Setup

Create a `.env` file with the following variables:

```bash
# Firebase Admin SDK
FIREBASE_SERVICE_ACCOUNT='{"projectId":"...","clientEmail":"...","privateKey":"..."}'

# Organization Configuration
LINEAI_ORGANIZATION_ID=org_abc123

# LineAI API (for custom tools execution)
LINE_API_KEY=your_lineai_api_key
LINE_API_ENDPOINT=https://api.getline.ai  # Optional, defaults to https://api.getline.ai

# Memory Service (Cognee)
COGNEE_URL=https://cognee.your-domain.com
COGNEE_SUPERUSER_USERNAME=admin@cognee.local
COGNEE_SUPERUSER_PASSWORD=your_superuser_password
COGNEE_ENCRYPTION_KEY=your_64_character_hex_key  # Generate with: node scripts/generate-encryption-key.js

# Research Service
RESEARCH_REPORT_REST_ENDPOINT=https://line-ai-researcher-291799762709.us-west1.run.app/report/
RESEARCH_REPORT_WS_ENDPOINT=wss://line-ai-researcher-291799762709.us-west1.run.app/ws

# Composio (Integrations)
COMPOSIO_API_KEY=your_composio_api_key
COMPOSIO_API_ENDPOINT=https://api.composio.dev/v1

# Enterprise Data Providers
EXA_API_KEY=your_exa_api_key
THESCRIBE_API_KEY=your_thescribe_api_key

# Search Engines
GOOGLE_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id
TAVILY_API_KEY=your_tavily_api_key
SEARXNG_API_URL=https://your-searxng-instance.com

# Optional: Content Retrieval
RAPID_API_KEY=your_rapid_api_key  # For LinkedIn data extraction
SAM_API_KEY=your_sam_api_key  # For SAM.gov government contracts
JINA_API_KEY=your_jina_api_key  # For Jina Reader (falls back to Tavily Extract)
```

### 2. Initialize the SDK

```typescript
import { initializeLineAI, getLineAITools } from '@lineai/assistant';

// Initialize SDK with service account
const ctx = await initializeLineAI({
  projectId: 'project_1756358714095_bvg97tozm',
  userId: 'loTcmV1RtQPePjI12jnyxU5Dty63',
  orgId: 'org_abc123', // Or use LINEAI_ORGANIZATION_ID env var
  serviceAccount: {
    projectId: process.env.FIREBASE_PROJECT_ID,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
    privateKey: process.env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, '\n'),
  },
});

// Get all enabled service tools
const { tools, toolsContext } = await getLineAITools(ctx);

// Or get specific service tools with options
const { tools: selectedTools, toolsContext: selectedContext } = await getLineAITools(ctx, {
  requestedServices: ['research', 'integrations', 'collections'],
  activeCollectionIds: ['tasks'],  // Filter collections to expose
});
```

### 3. Use with Vercel AI SDK

```typescript
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  
  // Initialize LineAI context
  const ctx = await initializeLineAI({
    projectId: 'your-project-id',
    userId: 'user-id',
  });

  // Get tools and context
  const { tools, toolsContext } = await getLineAITools(ctx);

  // Build system prompt with injected context
  const systemPrompt = toolsContext.length > 0
    ? `You are a helpful assistant.\n\n${toolsContext.map(c => c.content).join('\n\n')}`
    : 'You are a helpful assistant.';

  const result = streamText({
    model: openai('gpt-4-turbo'),
    system: systemPrompt,
    messages,
    tools,
    maxSteps: 5, // Allow multiple tool calls
  });
  
  return result.toDataStreamResponse();
}
```

## Available Services

The LineAI Assistant SDK provides access to **11 comprehensive services** plus custom tool support, with both application APIs and AI-compatible tools:

### 1. Research Service

Interface to the GPT Researcher API for comprehensive research reports.

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createResearchTools } from '@lineai/assistant';

const tools = createResearchTools(ctx);

// Create a research report in background mode
const result = await tools.research_createReport.execute({
  task: 'Latest trends in AI assistants',
  reportType: 'detailed_report',
  tone: 'Analytical',
  background: true, // Returns immediately with report ID
});

// Check report status
const report = await tools.research_getReport.execute({
  reportId: result.data.report.id
});

// List recent reports
const reports = await tools.research_getReports.execute({
  limit: 10,
  includeFailedReports: false
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import { createResearchReport, getResearchReports, getResearchReport } from '@lineai/assistant';

// Create a research report directly
const result = await createResearchReport(ctx, {
  task: 'Latest trends in AI assistants',
  reportType: 'detailed_report',
  tone: 'Analytical',
  background: true
});

// Get reports directly
const reports = await getResearchReports(ctx, { 
  limit: 10, 
  includeFailedReports: false 
});

// Get specific report
const report = await getResearchReport(ctx, reportId);
```

### 2. Integrations Service

Interface to Composio for 250+ third-party service connections.

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createIntegrationTools } from '@lineai/assistant';

const tools = await createIntegrationTools(ctx);

// Search available integrations
const result = await tools.integrations_search.execute({
  query: 'twitter',
  category: 'communication'
});

// Initiate OAuth connection
const auth = await tools.integrations_connect.execute({
  authConfigId: 'config_id',
  redirectUrl: 'https://yourapp.com/callback'
});

// List connected integrations
const connections = await tools.integrations_list.execute();

// Dynamic tools are created for connected integrations
// e.g., tools.integrations_twitter_execute
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import { 
  getAvailableIntegrations, 
  getConnectedIntegrations, 
  initiateOAuthConnection,
  executeIntegrationAction 
} from '@lineai/assistant';

// Get available integrations
const available = await getAvailableIntegrations(ctx);

// Get user's connected integrations  
const connected = await getConnectedIntegrations(ctx);

// Initiate OAuth flow
const auth = await initiateOAuthConnection(ctx, 'auth-config-id', 'https://yourapp.com/callback');

// Execute an action on a connected integration
const result = await executeIntegrationAction('connection-id', 'ACTION_ID', { param: 'value' });
```

### 3. Scheduler Service

Interface for automation and orchestration.

```typescript
import { createSchedulerTools } from '@lineai/assistant';

const tools = createSchedulerTools(ctx);

// Create a scheduled job
const job = await tools.scheduler_createJob.execute({
  name: 'Daily Report',
  description: 'Generate daily analytics report',
  cronExpression: '0 9 * * *', // 9 AM daily
  trigger: { type: 'cron', config: {} },
  actions: [{
    service: 'research',
    method: 'createReport',
    params: { task: 'Daily metrics summary' }
  }],
  enabled: true
});

// List jobs
const jobs = await tools.scheduler_listJobs.execute({
  enabled: true
});

// Manually trigger a job
await tools.scheduler_triggerJob.execute({
  jobId: job.data.job.id
});
```

### 4. Models Service

AI model configuration and preferences management.

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createModelsTools } from '@lineai/assistant';

const tools = createModelsTools(ctx);

// List available models
const models = await tools.models_listAvailable.execute({
  provider: 'openai',
  onlyEnabled: true
});

// Get user preferences
const preferences = await tools.models_getUserPreferences.execute();

// Update preferences
await tools.models_updatePreference.execute({
  provider: 'anthropic',
  model: 'claude-3-opus',
  settings: {
    temperature: 0.7,
    maxTokens: 4000
  }
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import { 
  getAvailableModels, 
  getUserModelPreferences, 
  updateModelPreference 
} from '@lineai/assistant';

// Get available models
const models = await getAvailableModels(ctx);

// Get user's model preferences
const preferences = await getUserModelPreferences(ctx);

// Update user's default model preference
await updateModelPreference(ctx, {
  defaultProvider: 'anthropic',
  defaultModel: 'claude-3-opus'
});
```

### 5. Enterprise Data Service

Interface to premium data providers (EXA, TheScribe AI).

```typescript
import { createEnterpriseDataTools } from '@lineai/assistant';

const tools = createEnterpriseDataTools(ctx);

// Search with EXA
const exaResults = await tools.enterpriseData_searchEXA.execute({
  query: 'AI startup funding 2024',
  numResults: 10,
  startDate: '2024-01-01'
});

// Search government records with TheScribe
const govRecords = await tools.enterpriseData_searchTheScribe.execute({
  query: 'building permits',
  jurisdiction: 'San Francisco',
  documentType: 'permit'
});
```

### 6. Agents Service

Access to specialized AI agents with custom tools and prompts.

```typescript
import { getAgentTools, listAgents } from '@lineai/assistant';

// List available agents
const agents = await listAgents(ctx);

// Get tools for a specific agent
const agentTools = await getAgentTools(ctx, 'compliance-agent');

// Use agent-specific tools
const result = await agentTools.compliance_search.execute({
  query: 'GDPR requirements for data storage'
});
```

### 7. Memory Service

Intelligent memory management powered by Cognee with semantic search, knowledge graphs, and multi-tenant isolation.

**Features:**
- 🧠 Semantic search using Cognee's vector embeddings
- 📊 Knowledge graph processing for relationship discovery
- 🔒 Organization-scoped multi-tenancy with dataset isolation
- 🏷️ Tag-based filtering and categorization
- 👤 User and organization memory scopes

#### Setup (One-Time)

Before using memory features, provision your organization and users in Cognee:

```typescript
import {
  provisionCogneeAdminUser,
  provisionCogneeOrganization,
  provisionCogneeUser
} from '@lineai/assistant';

// 1. Generate encryption key (run once)
// node scripts/generate-encryption-key.js

// 2. Provision admin user for the organization
const adminResult = await provisionCogneeAdminUser(
  ctx,
  'admin-user-id',      // Line AI user ID (org owner)
  'org-acme-corp',      // Organization ID
  'admin@acme.com'      // Admin email
);

// 3. Provision organization (creates Cognee tenant)
const orgResult = await provisionCogneeOrganization(
  ctx,
  'org-acme-corp'       // Organization ID
);

// 4. Provision users (when they join your organization)
const userResult = await provisionCogneeUser(
  ctx,
  'user-alice-123',     // Firebase auth UID
  'alice@acme.com',     // User email
  'org-acme-corp'       // Organization ID
);

// See MEMORY_SETUP.md for complete setup guide
```

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createMemoryTools } from '@lineai/assistant';

const tools = createMemoryTools(ctx);

// Create memory card (personal or organizational)
await tools.memory_create_card.execute({
  name: 'AI Research Notes',
  scope: 'user',  // or 'organization'
  tags: ['research', 'ai'],
  initialContent: 'Neural networks are composed of layers...'
});

// Add content to existing card
await tools.memory_add_content.execute({
  cardId: 'card-id',
  scope: 'user',
  content: 'Deep learning uses multiple layers...',
  tags: ['deep-learning'],
  triggerProcessing: true  // Process into knowledge graph
});

// Search within a card (semantic search)
const results = await tools.memory_search.execute({
  cardId: 'card-id',
  scope: 'user',
  query: 'How do neural networks learn?',
  topK: 5
});

// List memory cards
const cards = await tools.memory_list_cards.execute({
  scope: 'user',
  limit: 20
});

// Process memories into knowledge graph
await tools.memory_process.execute({
  scope: 'user',
  background: true
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  createMemoryCard,
  addMemoryContent,
  searchMemoryCard,
  listMemoryCards,
  processMemoryCard,
  getMemoryCard,
  updateMemoryCard
} from '@lineai/assistant';

// Create memory card
const cardResult = await createMemoryCard(ctx, {
  name: 'Project Requirements',
  scope: 'organization',  // Shared across org
  tags: ['requirements', 'planning'],
  initialContent: {
    type: 'text',
    text: 'The system should support...'
  }
});

// Add content (text, file, or URL)
await addMemoryContent(
  ctx,
  cardResult.data.id,
  'organization',
  {
    type: 'file',
    file: documentFile
  },
  {
    tags: ['specification'],
    triggerProcessing: false
  }
);

// Search within card
const searchResult = await searchMemoryCard(
  ctx,
  cardResult.data.id,
  'organization',
  'What are the authentication requirements?',
  { topK: 3 }
);

// Process into knowledge graph
await processMemoryCard(ctx, 'organization', { background: true });

// List all cards
const cards = await listMemoryCards(ctx, 'user', { limit: 10 });
```

#### Memory Architecture

**Storage Model:**
- **Firestore**: Card metadata (name, tags, scope, timestamps)
- **Cognee Datasets**: Actual content, embeddings, knowledge graphs

**Dataset Naming:**
- User scope: `organization_{orgId}_user_{userId}_memories`
- Org scope: `organization_{orgId}_shared`

**Content Tagging:**
- All content tagged with `card:{cardId}` for filtering
- Additional user tags for categorization

See `MEMORY_SETUP.md` for complete provisioning and usage guide.

### 8. Search Engine Service

Multi-engine web search with specialized content retrieval. **New in v1.0.40**: Refactored to engine-specific tools with improved image extraction.

**Supported Engines:**
- 🔍 **Google Custom Search**: Comprehensive results, up-to-date information
- 🤖 **Tavily**: AI-optimized search with answers and descriptions
- 🔒 **SearXNG**: Privacy-focused meta-search

**Features:**
- Engine-specific tools for better performance
- Intelligent content retrieval with domain routing
- Image extraction with descriptions (Tavily)
- Multiple content types: web, news, images, academic
- Search depth control: basic (fast) or advanced (comprehensive)

#### Setup

Configure search engines in Firestore at `organizations/{orgId}/projects/{projectId}/services/search-engine/v1/enabled/`:

```typescript
{
  id: 'google',
  type: 'google',
  enabled: true,
  priority: 1,
  settings: {
    searchEngineId: 'your-cx-id',  // Can be in DB
    maxResults: 10,
    safeSearch: 'moderate',
    includeImages: true,
    includeNews: true
  }
}
```

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createSearchEngineTools } from '@lineai/assistant';

const tools = createSearchEngineTools(ctx);

// Google search - best for general queries
const googleResults = await tools.search_google.execute({
  query: 'latest AI developments 2024',
  maxResults: 10,
  contentType: 'web',  // 'web' | 'news' | 'images' | 'academic'
  searchDepth: 'basic',  // 'basic' | 'advanced'
  safeSearch: 'moderate',
  country: 'US',
  language: 'en'
});

// Tavily search - best for AI-optimized results with answers
const tavilyResults = await tools.search_tavily.execute({
  query: 'how do transformers work in AI',
  maxResults: 5,
  searchDepth: 'advanced',
  includeDomains: ['arxiv.org', 'scholar.google.com'],
  excludeDomains: ['wikipedia.org']
});

// SearXNG search - best for privacy and aggregated results
const searxngResults = await tools.search_searxng.execute({
  query: 'machine learning tutorials',
  maxResults: 15,
  contentType: 'academic',
  searchDepth: 'advanced'
});

// Retrieve detailed content from specific URLs
// Automatically routes to specialized extractors for LinkedIn, SAM.gov, etc.
const content = await tools.retrieve.execute({
  url: 'https://www.linkedin.com/in/username'
});

// Get available engines
const engines = await tools.search_getEngines.execute();

// Check engine health
const health = await tools.search_checkHealth.execute();
```

**Search Results Format:**
```typescript
{
  success: true,
  data: {
    results: [
      {
        title: "Article Title",
        url: "https://example.com/article",
        content: "Article snippet or full content...",
        data: { /* Rich metadata for card rendering */ }
      }
    ],
    images: [
      "https://example.com/image1.jpg",  // Simple URL
      {
        url: "https://example.com/image2.jpg",
        description: "Image description from Tavily"
      }
    ],
    query: "original query",
    displayQuery: "web search for \"original query\"",
    message: "Found 10 results in 234ms",
    number_of_results: 10
  }
}
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  search,
  searchWithEngine,
  searchNews,
  searchImages,
  searchAcademic,
  retrieveContent,
  getSearchEngineHealth,
  generateRelatedQuestions
} from '@lineai/assistant';

// Search with specific engine
const results = await searchWithEngine(ctx, 'google', 'AI trends 2024', {
  maxResults: 10,
  contentType: 'news',
  dateRange: 'week'
});

// Multi-engine search (aggregates from all enabled engines)
const aggregated = await search(ctx, {
  query: 'climate change solutions',
  maxResults: 20,
  contentType: 'web',
  searchDepth: 'advanced'
});

// Specialized searches
const newsResults = await searchNews(ctx, 'tech industry', {
  maxResults: 10,
  dateRange: 'month',
  country: 'US'
});

const imageResults = await searchImages(ctx, 'modern architecture', {
  maxResults: 20,
  imageSize: 'large',
  imageType: 'photo'
});

const academicResults = await searchAcademic(ctx, 'quantum computing', {
  maxResults: 15,
  field: 'computer science',
  yearRange: { start: 2020, end: 2024 }
});

// Retrieve content from specific URL with smart routing
const content = await retrieveContent(ctx, 'https://example.com/article');

// Generate related questions for follow-up
import { anthropic } from '@ai-sdk/anthropic';
const model = anthropic('claude-3-5-sonnet-20241022');
const relatedQuestions = await generateRelatedQuestions(
  'How does machine learning work?',
  model
);

// Check engine health
const health = await getSearchEngineHealth(ctx);
```

**Migration Note**: If upgrading from v1.0.39 or earlier, see [SEARCH_MIGRATION_GUIDE.md](SEARCH_MIGRATION_GUIDE.md) for breaking changes and migration steps.

### 9. Team Service

Team collaboration and member management with permissions.

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createTeamTools } from '@lineai/assistant';

const tools = createTeamTools(ctx);

// Get current user info
const user = await tools.team_getCurrentUser.execute();

// Check permissions
const permissions = await tools.team_checkPermissions.execute({
  action: 'invite_members'
});

// Get team context
const context = await tools.team_getContext.execute();

// Invite team member
await tools.team_invite.execute({
  email: 'new-member@company.com',
  role: 'member',
  message: 'Welcome to the team!'
});

// Request assistance
const assistance = await tools.team_requestAssistance.execute({
  topic: 'API integration help',
  urgency: 'normal',
  description: 'Need help with authentication setup'
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  getCurrentUser,
  checkPermissions,
  inviteTeamMember,
  getTeamActivity,
  updateMemberRole
} from '@lineai/assistant';

// Get current user
const user = await getCurrentUser(ctx);

// Invite team member
const invitation = await inviteTeamMember(ctx, {
  email: 'user@example.com',
  role: 'member'
});

// Check permissions
const canInvite = await checkPermissions(ctx, 'invite_members');
```

### 10. Webpages Service

AI-powered webpage generation and management platform.

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createWebpagesTools } from '@lineai/assistant';

const tools = createWebpagesTools(ctx);

// Create webpage
const webpage = await tools.webpages_create.execute({
  prompt: 'Create a landing page for an AI startup',
  title: 'AI Solutions Company',
  description: 'Revolutionary AI solutions for businesses',
  style: {
    theme: 'modern',
    colorScheme: 'blue',
    layout: 'landing'
  }
});

// List pages
const pages = await tools.webpages_list.execute({
  status: 'active',
  limit: 10
});

// Update page
await tools.webpages_update.execute({
  pageId: 'page-id',
  title: 'Updated Title',
  content: 'New content here'
});

// Preview changes
const preview = await tools.webpages_preview.execute({
  pageId: 'page-id',
  title: 'Preview Title',
  style: { theme: 'dark' }
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  createWebpage,
  updatePageContent,
  getPageAnalytics,
  clonePage,
  manageBrandAssets
} from '@lineai/assistant';

// Create webpage
const result = await createWebpage(ctx, {
  prompt: 'Create a portfolio website',
  title: 'My Portfolio',
  style: { theme: 'minimal' }
});

// Get analytics
const analytics = await getPageAnalytics(ctx, {
  start: new Date('2024-01-01'),
  end: new Date('2024-12-31')
});

// Clone existing page
const cloned = await clonePage(ctx, 'source-page-id', {
  title: 'New Page Title'
});
```

### 11. Collections Service

AI-powered database management allowing agents to create and manage their own backend collections on-the-fly for persisting structured data.

**Features:**
- 📦 Create collections dynamically for any data structure
- 📄 Full CRUD operations on documents within collections
- 🔍 Schema validation support for data integrity
- 🤖 Single `collectionsFetch` tool avoids context pollution
- 🔐 Separate context for collection management (opt-in create/delete)

#### For Tools Exposed to Your Application's AI Assistant (User-Facing AI Features)

```typescript
import { createCollectionsTools } from '@lineai/assistant';

const tools = createCollectionsTools(ctx);

// List all collections
const collections = await tools.collectionsFetch.execute({
  path: '/',
  method: 'GET'
});

// Create a collection (requires enableCollectionManagement)
const newCollection = await tools.collectionsFetch.execute({
  path: '/',
  method: 'POST',
  body: {
    collectionId: 'contacts',
    description: 'Customer contacts',
    schema: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        email: { type: 'string' }
      },
      required: ['name']
    }
  }
});

// Get collection details including schema
const collection = await tools.collectionsFetch.execute({
  path: '/contacts',
  method: 'GET'
});

// Create a document
const doc = await tools.collectionsFetch.execute({
  path: '/contacts/documents',
  method: 'POST',
  body: { name: 'John Doe', email: 'john@example.com' }
});

// List documents with pagination
const docs = await tools.collectionsFetch.execute({
  path: '/contacts/documents?limit=20&startAfter=lastDocId',
  method: 'GET'
});

// Update a document
await tools.collectionsFetch.execute({
  path: '/contacts/documents/doc123',
  method: 'PATCH',
  body: { email: 'newemail@example.com' }
});

// Delete a document
await tools.collectionsFetch.execute({
  path: '/contacts/documents/doc123',
  method: 'DELETE'
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  listCollections,
  getCollection,
  createCollection,
  updateCollection,
  deleteCollection,
  listDocuments,
  getDocument,
  createDocument,
  updateDocument,
  deleteDocument,
  generateCollectionsContext,
  generateCollectionManagementContext
} from '@lineai/assistant';

// List all collections
const collections = await listCollections(ctx);

// Create a collection
const newCollection = await createCollection(ctx, {
  collectionId: 'tasks',
  description: 'Task management',
  schema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      completed: { type: 'boolean' }
    },
    required: ['title']
  }
});

// CRUD on documents
const doc = await createDocument(ctx, 'tasks', { title: 'Buy groceries', completed: false });
const docs = await listDocuments(ctx, 'tasks', { limit: 10 });
const updated = await updateDocument(ctx, 'tasks', doc.data.id, { completed: true });
await deleteDocument(ctx, 'tasks', doc.data.id);

// Generate context for AI system prompts
const collectionsContext = await generateCollectionsContext(ctx, ['tasks', 'contacts']);
const managementContext = generateCollectionManagementContext();
```

#### Loading Collections with getLineAITools

```typescript
import { getLineAITools } from '@lineai/assistant';

// Basic usage - read/list collections + document CRUD
const { tools, toolsContext } = await getLineAITools(ctx, {
  requestedServices: ['collections'],
  activeCollectionIds: ['tasks', 'contacts'],  // Filter which collections to expose
});

// With collection management - adds create/update/delete collection capabilities
const { tools, toolsContext } = await getLineAITools(ctx, {
  requestedServices: ['collections'],
  activeCollectionIds: ['tasks', 'contacts'],
  enableCollectionManagement: true,
});

// Inject context into system prompt
const systemPrompt = `You are an assistant.\n\n${toolsContext.map(c => c.content).join('\n\n')}`;
```

### Custom Tools (Dynamic Tools)

Define custom tools in Firestore and load them dynamically at runtime. Tools are configured with JSON Schema inputs and execute via HTTP endpoints.

**Features:**
- 🔧 Define tools in Firestore with JSON Schema input validation
- 🔄 Automatic JSON Schema to Zod conversion for AI SDK compatibility
- 🌐 Execute tools via HTTP POST to configured endpoints
- 🔐 Support for bearer token and API key authentication

#### Tool Configuration

Store tool configs in Firestore at `organizations/{orgId}/projects/{projectId}/tool-configs/{toolId}`:

```typescript
// Example tool configuration document
{
  id: 'weather_lookup',
  name: 'Weather Lookup',
  description: 'Get current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
      units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
    },
    required: ['city']
  },
  outputSchema: {
    type: 'object',
    properties: {
      temperature: { type: 'number' },
      conditions: { type: 'string' }
    }
  },
  executeFunction: '/v1/tools/weather_lookup',  // LineAI-hosted
  // Or for self-hosted: 'https://your-api.com/tools/weather'
  auth: {
    type: 'bearer',  // 'bearer' | 'api-key' | 'none'
    secretRef: 'weather_api_secret'
  }
}
```

#### Loading Custom Tools with getLineAITools

```typescript
import { getLineAITools } from '@lineai/assistant';

const { tools, toolsContext } = await getLineAITools(ctx, {
  requestedServices: ['research', 'collections'],
  customTools: ['weather_lookup', 'stock_price', 'send_notification'],
});

// Custom tools are merged with service tools
// tools.weather_lookup, tools.stock_price, tools.send_notification
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  generateDynamicTools,
  loadToolConfig,
  loadToolConfigs,
  createDynamicTool,
  jsonSchemaToZod,
  type DynamicToolConfig,
  type ToolExecutionResponse
} from '@lineai/assistant';

// Load and generate tools from config IDs
const customTools = await generateDynamicTools(ctx, ['weather_lookup', 'stock_price']);

// Load a single tool config
const config = await loadToolConfig(ctx, 'weather_lookup');

// Create a tool from config
const tool = createDynamicTool(ctx, config);

// Execute the tool
const result: ToolExecutionResponse = await tool.execute({
  city: 'San Francisco',
  units: 'celsius'
});

// Convert JSON Schema to Zod (useful for custom validation)
import { z } from 'zod';
const zodSchema = jsonSchemaToZod(config.inputSchema);
```

#### Tool Execution Flow

1. SDK loads `DynamicToolConfig` from Firestore
2. JSON Schema is converted to Zod schema for AI SDK
3. When AI calls the tool, SDK POSTs to `executeFunction` endpoint:
   ```json
   {
     "input": { "city": "San Francisco", "units": "celsius" },
     "context": {
       "userId": "user_123",
       "orgId": "org_456",
       "projectId": "project_789"
     }
   }
   ```
4. Endpoint returns `ToolExecutionResponse`:
   ```json
   {
     "success": true,
     "data": { "temperature": 18, "conditions": "Partly cloudy" }
   }
   ```

### Base Tools

Global tools available to all customers, bundled in the LineAI API. Unlike custom tools (per org/project), base tools are shared platform-wide.

**Features:**
- 🌍 Global tools available to all customers
- 📦 Bundled in API (no Firestore storage needed)
- 🔧 Same execution pattern as custom tools
- 🎯 Agent's `tools` property specifies which to load

#### Loading Base Tools with getLineAITools

```typescript
import { getLineAITools } from '@lineai/assistant';

// Load base tools from deployed agent's tools property
const deployedAgent = await getDeployedAgent(ctx, agentId);
const baseToolIds = deployedAgent.tools ? Object.values(deployedAgent.tools) : [];

const { tools, toolsContext } = await getLineAITools(ctx, {
  requestedServices: ['research', 'collections'],
  baseTools: baseToolIds,  // e.g., ['search_permits', 'analyze_documents']
});
```

#### For Direct API Calls in Your Application Code (Programmatic Data Access)

```typescript
import {
  generateBaseTools,
  loadBaseToolConfigs,
} from '@lineai/assistant';

// Load and generate base tools
const baseTools = await generateBaseTools(ctx, ['search_permits', 'analyze_documents']);

// Or load configs directly
const configs = await loadBaseToolConfigs(ctx, ['search_permits']);
```

#### Base Tools vs Custom Tools

| Feature | Custom Tools | Base Tools |
|---------|--------------|------------|
| Storage | Firestore (per org/project) | Bundled in API |
| Scope | Per customer | All customers |
| Config source | `organizations/{orgId}/projects/{projectId}/tool-configs/{toolId}` | `POST /v1/tools/base` |
| Option | `customTools` | `baseTools` |
| Use case | Client-specific tools | Platform-wide tools |

## Error Handling

All tools return structured error responses that AI assistants can reason about:

```typescript
const result = await tool.execute(params);

if (!result.success) {
  console.log('Error Code:', result.error.code);
  console.log('Error Message:', result.error.message);
  console.log('Suggestions:', result.error.suggestions);
  // AI can use suggestions to determine next steps
}
```

Error responses include:
- **Error Code**: Specific error type (e.g., `PERMISSION_DENIED`, `API_ERROR`)
- **Message**: Human-readable error description
- **Details**: Additional context about the error
- **Suggestions**: Actionable steps the AI can try to resolve the issue

## WebSocket Support

For real-time updates (e.g., research report generation):

```typescript
import { createResearchWebSocket } from '@lineai/assistant';

const ws = createResearchWebSocket(
  reportId,
  (message) => {
    console.log('Progress:', message);
  },
  (error) => {
    console.error('WebSocket error:', error);
  },
  () => {
    console.log('Connection closed');
  }
);

// Clean up when done
ws.close();
```

## Firestore Path Structure

The SDK follows a consistent path structure in Firestore:

```
Organization-level:
├── organizations/{orgId}
│   └── projects/{projectId}
|       └── services/
│           ├── research/v1/
│           │   ├── reports/{reportId}
│           │   ├── templates/{templateId}
│           │   ├── source-configs/{configId}
│           │   ├── settings/default
│           │   └── analytics/default
│           ├── integrations/v1/
│           │   ├── available/{integrationId}
│           │   ├── authorized/{integrationId}
│           │   ├── webhooks/{webhookId}
│           │   └── analytics/default
│           ├── scheduler/v1/
│           │   ├── schedules/{scheduleId}
│           │   ├── triggers/{triggerId}
│           │   ├── executions/{executionId}
│           │   ├── settings/default
│           │   └── statistics/default
│           ├── models/v1/
│           │   ├── models/{modelId}
│           │   ├── active-configs/{configId}
│           │   ├── usage/{usageId}
│           │   ├── settings/default
│           │   └── analytics/default
│           ├── enterprise-data/v1/
│           │   ├── providers/{providerId}
│           │   ├── connections/{connectionId}
│           │   ├── queries/{queryId}
│           │   ├── sources/{sourceId}
│           │   ├── settings/default
│           │   └── analytics/default
│           ├── agents/v1/
│           │   ├── instances/{agentId}
│           │   ├── configurations/{configId}
│           │   ├── conversations/{conversationId}
│           │   ├── performance/{metricId}
│           │   └── settings/default
│           ├── memory/v1/
│           │   ├── cards/{cardId}
│           │   ├── assets/{assetId}
│           │   ├── relationships/{relationshipId}
│           │   └── settings/default
│           ├── search-engine/v1/
│           │   ├── enabled/{engineId}
│           │   ├── queries/{queryId}
│           │   ├── settings/default
│           │   └── analytics/default
│           ├── team/v1/
│           │   ├── members/{memberId}
│           │   ├── invitations/{invitationId}
│           │   ├── roles/{roleId}
│           │   ├── permissions/{permissionId}
│           │   ├── settings/default
│           │   └── statistics/default
│           └── webpages/v1/
│               ├── pages/{pageId}
│               ├── templates/{templateId}
│               ├── assets/{assetId}
│               ├── analytics/{analyticsId}
│               └── settings/default
│       └── tool-configs/{toolId}  # Custom tool configurations

User-level:
├── users/{userId}
│   └── services/
│       ├── integrations/connections/{connectionId}
│       ├── models/preferences
│       ├── agents/configurations/{agentId}
│       ├── memory/
│       │   ├── cards/{cardId}
│       │   └── preferences
│       ├── team/
│       │   ├── profile
│       │   └── activity/{activityId}
│       └── webpages/
│           ├── pages/{pageId}
│           └── preferences
```

## TypeScript Support

The SDK is fully typed with TypeScript. Import types as needed:

```typescript
import type {
  // Core types
  LineAIContext,
  Result,
  ToolResponse,
  GetLineAIToolsResult,
  ServiceContext,

  // Service-specific types
  ResearchReport,
  ConnectedIntegration,
  ScheduledJob,
  ModelConfiguration,
  Agent,
  MemoryCard,
  SearchOptions,
  TeamMember,
  DeployedPage,
  CollectionMetadata,
  CollectionDocument,
  CollectionSchema,

  // Additional types
  SearchResult,
  WebpageCreationOptions,
  PermissionCheck,
  MemorySearchOptions,
  ListDocumentsOptions,
  DocumentsListResponse,

  // Dynamic tools types
  DynamicToolConfig,
  ToolAuthConfig,
  ToolExecutionContext,
  ToolExecutionRequest,
  ToolExecutionResponse
} from '@lineai/assistant';
```

## Development

### Prerequisites

- Node.js >= 16.0.0
- Yarn package manager
- Firebase project with Admin SDK credentials
- LineAI organization ID and project ID

### Building from Source

```bash
# Clone the repository
git clone https://github.com/lineai/assistant-sdk.git
cd assistant-sdk

# Install dependencies
yarn install

# Build the project
yarn build

# Run tests
yarn test

# Run linting
yarn fix
```

### Project Structure

```
src/
├── core/           # Core initialization and utilities
├── services/       # Service implementations
│   ├── agents/           # AI agents with specialized tools
│   ├── collections/      # AI-managed database collections
│   ├── dynamic-tools/    # Custom tools loaded from Firestore
│   ├── enterprise-data/  # Premium data providers (EXA, TheScribe)
│   ├── integrations/     # Composio 250+ service integrations
│   ├── memory/           # Intelligent memory management
│   ├── models/           # AI model configurations
│   ├── research/         # GPT Researcher integration
│   ├── scheduler/        # Automation and job scheduling
│   ├── search-engine/    # Multi-engine web search
│   ├── team/             # Team collaboration
│   └── webpages/         # AI webpage generation
├── types/          # TypeScript type definitions
├── tools/          # Tool aggregation and utilities
└── utils/          # Helper utilities
```

## API Reference

### Core Functions

#### `initializeLineAI(config: LineAIConfig): Promise<LineAIContext>`

Initialize the SDK with Firebase Admin SDK and organization configuration.

#### `getLineAITools(ctx: LineAIContext, options?: GetLineAIToolsOptions): Promise<GetLineAIToolsResult>`

Get AI-compatible tools and context for specified services (or all enabled services).

Returns `{ tools, toolsContext }` where:
- `tools`: Record of AI-callable tools
- `toolsContext`: Array of `ServiceContext` objects to inject into system prompts

#### `getEnabledServices(ctx: LineAIContext): Promise<Result<string[]>>`

Detect which services are enabled for the current project.

### Service-Specific Functions

Each service exports functions for direct use:

- **Research**: `createResearchReport`, `getResearchReports`, `getResearchReport`, `updateResearchReport`, `deleteResearchReport`
- **Integrations**: `getAvailableIntegrations`, `getConnectedIntegrations`, `initiateOAuthConnection`, `saveOAuthConnection`, `executeIntegrationAction`
- **Scheduler**: `createScheduledJob`, `getScheduledJobs`, `triggerJob`, `updateJobStatus`, `deleteScheduledJob`
- **Models**: `getAvailableModels`, `getUserModelPreferences`, `updateModelPreference`, `saveModelConfiguration`, `deleteModelConfiguration`
- **Enterprise Data**: `queryEXA`, `queryTheScribe`, `getDataQueries`, `getEnabledProviders`, `getDataQuery`
- **Agents**: `getAgent`, `listAgents`, `generateAgentSystemPrompt`, `createAgentConfiguration`, `getAvailableAgentIds`
- **Memory**: `createMemoryCard`, `addMemoryContent`, `searchMemoryCard`, `listMemoryCards`, `processMemoryCard`, `getMemoryCard`, `updateMemoryCard`, `deleteMemoryCard`
- **Memory Provisioning**: `provisionCogneeAdminUser`, `provisionCogneeOrganization`, `provisionCogneeUser`, `createCogneeRole`
- **Search Engine**: `search`, `searchWithEngine`, `searchNews`, `searchImages`, `searchAcademic`, `getAvailableSearchEngines`, `getSearchEngineHealth`
- **Team**: `getCurrentUser`, `checkPermissions`, `getTeamContext`, `inviteTeamMember`, `updateMemberRole`, `getTeamActivity`
- **Webpages**: `createWebpage`, `updatePageContent`, `getPageAnalytics`, `clonePage`, `previewPageChanges`, `manageBrandAssets`
- **Collections**: `listCollections`, `getCollection`, `createCollection`, `updateCollection`, `deleteCollection`, `listDocuments`, `getDocument`, `createDocument`, `updateDocument`, `deleteDocument`, `generateCollectionsContext`, `generateCollectionManagementContext`
- **Dynamic Tools**: `generateDynamicTools`, `loadToolConfig`, `loadToolConfigs`, `createDynamicTool`, `jsonSchemaToZod`
- **Base Tools**: `generateBaseTools`, `loadBaseToolConfigs`

## Best Practices

1. **Initialize Once**: Create the LineAI context once per request/session
2. **Error Handling**: Always check the `success` field in responses
3. **Tool Selection**: Only load the services you need to minimize overhead
4. **Environment Variables**: Store sensitive credentials in environment variables
5. **Rate Limiting**: Be mindful of API rate limits for external services
6. **Background Jobs**: Use background mode for long-running operations like research reports
7. **Memory Provisioning**: Provision organizations and users in Cognee before using memory features (see `MEMORY_SETUP.md`)
8. **Memory Scopes**: Use `user` scope for personal memories and `organization` scope for shared knowledge
9. **Team Permissions**: Always check permissions before performing team operations
10. **Search Optimization**: Use specific search engines for better performance
11. **Webpage Templates**: Leverage templates for consistent webpage generation
12. **Security**: Never commit encryption keys or credentials to version control
13. **Collections Context**: Use `activeCollectionIds` to limit which collections appear in AI context
14. **Collection Management**: Only enable `enableCollectionManagement` for agents that need create/delete powers
15. **Schema Validation**: Define schemas for collections to ensure data integrity on document writes
16. **Custom Tools**: Store tool configs in Firestore and use `customTools` option to load them dynamically
17. **Base Tools**: Use `baseTools` option to load global platform tools from the agent's `tools` property

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting PRs.

## License

MIT © LineAI, Inc.

## Support

- Documentation: [https://docs.lineai.com](https://docs.lineai.com)
- Issues: [GitHub Issues](https://github.com/lineai/assistant-sdk/issues)
- Email: support@lineai.com

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.