Line AI Assistant typescript library
npm install @lineai/assistantA comprehensive TypeScript library providing a unified server-side interface layer to LineAI's extensive service ecosystem for AI assistant applications.
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.
- 🔧 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
``bashUsing yarn (recommended)
yarn add @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_abc123LineAI 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.aiMemory 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.jsResearch 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/wsComposio (Integrations)
COMPOSIO_API_KEY=your_composio_api_key
COMPOSIO_API_ENDPOINT=https://api.composio.dev/v1Enterprise Data Providers
EXA_API_KEY=your_exa_api_key
THESCRIBE_API_KEY=your_thescribe_api_keySearch 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.comOptional: 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}_sharedContent Tagging:
- All content tagged with
card:{cardId} for filtering
- Additional user tags for categorizationSee
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 issueWebSocket 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 configurationsUser-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-sdkInstall dependencies
yarn installBuild the project
yarn buildRun tests
yarn testRun 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): PromiseInitialize the SDK with Firebase Admin SDK and organization configuration.
####
getLineAITools(ctx: LineAIContext, options?: GetLineAIToolsOptions): PromiseGet 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): PromiseDetect 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, loadBaseToolConfigsBest 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` propertyContributions are welcome! Please read our Contributing Guidelines before submitting PRs.
MIT © LineAI, Inc.
- Documentation: https://docs.lineai.com
- Issues: GitHub Issues
- Email: support@lineai.com
See CHANGELOG.md for version history and release notes.