Advanced Topics

Explore advanced features and techniques in BoxLang AI for building sophisticated AI applications, including custom utilities, event handling, and performance optimization.

Take your BoxLang AI skills to the next level with advanced features, integrations, and customization options.

🎯 Advanced Topics Architecture

📚 Guides

🧬 Embeddings

Convert text into vector representations for semantic search and similarity matching.

What you'll learn:

Generating embeddings from text
Choosing embedding models
Vector similarity calculations
Use cases: semantic search, clustering, recommendations

Use when: Building search engines, recommendation systems, or document similarity features.

🔐 Message Context

Inject security, RAG, and application context into AI messages.

What you'll learn:

Adding context to AI messages (security, RAG, metadata)
Using ${context} placeholder for automatic injection via render()
Multi-tenant isolation patterns
RAG implementation with context

Use when: Building secure multi-user applications, implementing RAG, or customizing AI behavior based on user/tenant context.

👥 Multi-Tenant Memory

Enterprise-grade memory isolation with userId and conversationId patterns.

What you'll learn:

Configuring multi-tenant memory systems
Isolating conversation and vector memory by user and conversation
Best practices for secure data handling
Integration with agents and chat services
Performance considerations
Scalability strategies

Use when: Building SaaS applications, multi-user platforms, or any system requiring strict data isolation.

📡 Event System

Intercept and customize AI operations with the powerful event system.

What you'll learn:

Available interception points (onAIRequest, onAIResponse, etc.)
Logging AI interactions
Modifying requests and responses
Custom provider registration
Performance monitoring and debugging

Use when: You need logging, custom behavior, request modification, or monitoring.

🔌 MCP Client

Integrate with the Model Context Protocol to access external tools and resources.

What you'll learn:

What is MCP (Model Context Protocol)
Connecting to MCP servers
Using MCP tools with agents
Available MCP integrations (filesystem, git, databases, APIs)
Creating custom MCP clients

Use when: Building agents that need access to external systems, databases, or APIs beyond built-in tools.

🖥️ MCP Server

Expose your BoxLang tools, resources, and prompts via the Model Context Protocol.

What you'll learn:

Creating and configuring MCP servers
Registering tools, resources, and prompts
HTTP endpoint for MCP requests
Statistics and monitoring - Track performance and usage metrics
Multi-server patterns for different use cases
Application lifecycle integration

Use when: Building APIs that AI clients can discover and use, or exposing BoxLang functionality to external AI systems.

🧠 Custom AI Providers

Build custom provider integrations to connect any LLM service with BoxLang AI.

What you'll learn:

Extending BaseService and implementing IAiService
OpenAI-compatible vs. custom implementations
Handling authentication and request/response formats
Implementing streaming and embeddings
Tool/function calling support
Registration and testing patterns

Use when: Integrating enterprise AI services, private deployments, emerging providers, or building mock providers for testing.

📁 Custom Loaders

Create custom document loaders to ingest data from any source for RAG applications.

What you'll learn:

Implementing the IAiDocumentLoader interface
Fetching and processing documents from APIs, databases, or file systems
Text extraction and metadata handling
Integration with RAG pipelines
Error handling and performance optimization

Use when: Ingesting documents from non-standard sources or formats for retrieval-augmented generation.

🐏 Custom Memory

Build custom memory solutions to store and retrieve conversation history and embeddings.

What you'll learn:

Implementing the IAiMemory interface
Storing conversation history and embeddings
Custom retrieval strategies
Integration with agents and chat services
Performance and scalability considerations
Multi-tenant memory patterns

Use when: Creating specialized memory solutions for unique application requirements or optimizing performance.

📐Custom Vector Memory

Create custom vector memory systems for storing and retrieving embeddings.

What you'll learn:

Implementing the IAiVectorMemory interface
Storing and querying vector embeddings
Custom similarity search algorithms
Integration with RAG and chat services
Performance tuning and scalability
Multi-tenant vector memory patterns

Use when: Building specialized vector storage solutions or optimizing similarity search for specific use cases.

🤖Custom Transformers

Build custom data transformers for use in AI pipelines.

What you'll learn:

Implementing the IAiTransformer interface
Creating data processing steps for pipelines
Handling input and output formats
Integration with existing pipeline components
Testing and debugging transformers
Performance optimization

Use when: You need specialized data processing steps in your AI workflows.

🚀 Production Deployment

Comprehensive guide for deploying BoxLang AI to production environments.

What you'll learn:

Pre-deployment checklist
Configuration management (environment-based, secrets managers)
Error handling & resilience (circuit breaker, retry logic, fallback providers)
Monitoring & observability (events, metrics, health checks, audit logs)
Performance optimization (caching, async, batching, connection pooling)
Cost management & tracking
High availability (failover, load balancing)
Scaling strategies
Database & memory configuration
Container deployment (Docker, Kubernetes)
Security hardening
Operational procedures

🔐 Security Guide

Security best practices for BoxLang AI applications.

What you'll learn:

API key management (secrets managers, rotation, scope limitation)
Input validation & sanitization
Prompt injection prevention (detection, protection strategies, testing)
Output validation
Data privacy (PII detection/redaction, encryption, data minimization)
Multi-tenant security (isolation, namespaces, row-level security)
PII handling
Audit logging
Compliance (GDPR, HIPAA, data retention)
Secure configuration
Network security (API gateway, TLS/SSL)
Incident response

🛠️ Utilities

Helper functions for text processing, token counting, and data manipulation.

What you'll learn:

Text chunking - Split documents intelligently for AI processing
Token counting - Calculate token usage before API calls
Mock data generation - Create test data with AI
Content validation - Verify and sanitize AI outputs

Use when: Processing large documents, managing costs, testing, or preparing data for AI.

Quick Examples

Generate Embeddings

embedding = aiEmbed(
    input: "BoxLang is a modern dynamic JVM language",
    options: { provider: "openai" }
);
// Returns: [0.023, -0.015, 0.089, ...] (vector of 1536 dimensions)

Intercept AI Requests

// In your interceptor
function onAIRequest( event, interceptData ) {
    var data = arguments.interceptData;
    writeLog( "AI Request to #data.provider#: #data.chatRequest.toString()#" );
}

Use MCP Tools

agent = aiAgent()
    .withInstructions( "You are a helpful assistant" )
    .addTool(
		"file-read",
		"Read files from the filesystem",
		( path ) => directoryList( path )
	)

response = agent.run( "List files in /tmp" );

Expose Tools via MCP Server

// Register tools at application startup
MCPServer( "myApp" )
    .registerTool(
        aiTool( "search", "Search documents", ( query ) => searchService.search( query ) )
    )
    .registerResource(
        uri: "docs://readme",
        name: "README",
        handler: () => fileRead( "/readme.md" )
    )

Chunk Large Documents

chunks = aiChunk(
    text: largeDocument,
    maxSize: 1000,
    overlap: 200
);

// Process each chunk
chunks.each( function( chunk ) {
    aiChat( message: "Summarize: #chunk#" );
} );

Integration Patterns

Semantic Search Pipeline

Components: Embeddings + Vector storage + Similarity search Guide: Embeddings Documentation

Observable AI System

Components: Event system + Logging + Monitoring Guide: Event System Documentation

Tool-Enhanced Agents

Components: MCP Client + Agents + External APIs Guide: MCP Client Documentation

AI-Accessible APIs

Components: MCP Server + Tools + Resources Guide: MCP Server Documentation

Document Processing

Components: Text chunking + Token counting + Batch processing Guide: Utilities Documentation

Secure Multi-User AI

Components: Request Context + Interceptors + Tenant Isolation Guide: Message Context Documentation

Choosing Your Path

"I need semantic search or recommendations" → Embeddings

"I want to log or customize AI behavior" → Event System

"I need to inject security context or RAG data" → Message Context

"I need agents to access external systems" → MCP Client

"I want to expose my tools to AI clients" → MCP Server

"I need to integrate a custom AI provider" → Custom AI Providers

"I'm processing large documents or managing costs" → Utilities

Prerequisites

These topics assume familiarity with:

Basic AI chatting - See Chatting Guide
AI agents - See Agents Documentation
BoxLang interceptors (for event system)

Next Steps

Optimize performance - Utilities for token counting and chunking
Add monitoring - Event System for logging and observability
Extend capabilities - MCP Client for external tool integration
Build search - Embeddings for semantic similarity

PreviousBoxLang AI Module Documentation NextBuilding Custom Document Loaders

Last updated 1 day ago

Good morning

🎯 Advanced Topics Architecture

📚 Guides

🧬 Embeddings

🔐 Message Context

👥 Multi-Tenant Memory

📡 Event System

🔌 MCP Client

🖥️ MCP Server

🧠 Custom AI Providers

📁 Custom Loaders

🐏 Custom Memory

📐Custom Vector Memory

🤖Custom Transformers

🚀 Production Deployment

🔐 Security Guide

🛠️ Utilities

Quick Examples

Generate Embeddings

Intercept AI Requests

Use MCP Tools

Expose Tools via MCP Server

Chunk Large Documents

Integration Patterns

Semantic Search Pipeline

Observable AI System

Tool-Enhanced Agents

AI-Accessible APIs

Document Processing

Secure Multi-User AI

Choosing Your Path

Prerequisites

Next Steps