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

$3

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

$3

`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

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

$3

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

$3

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

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
});
`

$3

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'
});
`

$3

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'
});
`

$3

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'
});
`

$3

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.

$3

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 for breaking changes and migration steps.

$3

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');
`

$3

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'
});
`

$3

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')};
`

$3

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" }
}
`

$3

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

$3

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

$3

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

$3

`
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

$3

#### initializeLineAI(config: LineAIConfig): Promise

Initialize the SDK with Firebase Admin SDK and organization configuration.

#### getLineAITools(ctx: LineAIContext, options?: GetLineAIToolsOptions): Promise

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>

Detect which services are enabled for the current project.

$3

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: support@lineai.com

Changelog

See CHANGELOG.md for version history and release notes.