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

# 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:

# 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
[email protected]
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

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

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)

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)

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)

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)

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.

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)

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)

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).

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.

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:

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
  '[email protected]'      // 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
  '[email protected]',     // 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)

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)

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/:

{
  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)

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:

{
  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)

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 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)

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: '[email protected]',
  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)

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: '[email protected]',
  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)

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)

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)

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: '[email protected]' }
});

// 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: '[email protected]' }
});

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

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

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

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}:

// 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

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)

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:

   {
     "input": { "city": "San Francisco", "units": "celsius" },
     "context": {
       "userId": "user_123",
       "orgId": "org_456",
       "projectId": "project_789"
     }
   }

4. Endpoint returns ToolExecutionResponse:

   {
     "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

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)

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:

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):

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:

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

# 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 before submitting PRs.

License

MIT © LineAI, Inc.

Support

• Documentation: https://docs.lineai.com
• Issues: GitHub Issues
• Email: [email protected]

Changelog

See CHANGELOG.md for version history and release notes.