# Introduction

Welcome to the **BoxLang AI Library** - your unified gateway to integrating AI capabilities into any JVM application. This library provides an elegant, easy-to-use API for interacting with multiple AI providers, from simple chat requests to complex multi-agent systems.

<figure><img src="https://1943767527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPsTDgathYUAH0fKKuzjR%2Fuploads%2Fgit-blob-863f5e0f389cad7a75bcce132b196bb2ccaff784%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## 🙋 What is BoxLang AI?

BoxLang AI is a comprehensive library that brings enterprise-grade artificial intelligence capabilities to the JVM ecosystem. Whether you're building chatbots, content generators, code assistants, RAG systems, or complex AI workflows, this module provides everything you need.

{% @mermaid/diagram content="graph LR
User\["👤 User"] --> Agent\["🤖 Agent"]

```
Agent --> Memory["💭 Memory"]
Agent --> Tools["🛠️ Tools"]
Agent --> Docs["📄 Documents"]

Docs --> Loaders["📥 Loaders"]
Loaders --> VectorDB[("📊 Vectors")]

Memory --> VectorDB
VectorDB --> RAG["🔍 RAG"]
Tools --> RAG

RAG --> AI["🚀 AI Models"]
AI --> Response["💬 Response"]
Response --> Agent
Agent --> User

style User fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#fff
style Agent fill:#2196F3,stroke:#1565C0,stroke-width:3px,color:#fff
style AI fill:#9C27B0,stroke:#6A1B9A,stroke-width:3px,color:#fff
style Response fill:#FF9800,stroke:#E65100,stroke-width:3px,color:#fff
style VectorDB fill:#00BCD4,stroke:#006064,stroke-width:2px,color:#fff
style RAG fill:#FF5722,stroke:#BF360C,stroke-width:2px,color:#fff" %}
```

### ✨ Key Features

* 🌐 **Multi-Provider Support**: Work with OpenAI, Claude, Gemini, Grok, Groq, DeepSeek, Ollama, and more
* 🔄 **Unified API**: One consistent interface across all providers
* 👥 **Multi-Tenant Memory**: Enterprise-grade isolation with userId and conversationId across all 20 memory types
* 🎨 **Multimodal Content**: Process images, audio, video, and documents alongside text
* 🏠 **Local AI Support**: Run models locally with Ollama for privacy and offline use
* 🔗 **AI Pipelines**: Chain operations together for complex multi-step workflows
* ⚡ **Streaming Responses**: Get real-time responses as they're generated
* 🛠️ **Tool Integration**: Enable AI to call functions and access real-time data
* 🚀 **Async Support**: Non-blocking operations for better performance
* 📝 **Template System**: Create reusable prompts with dynamic placeholders
* 🤖 **AI Agents**: Autonomous agents with memory, tools, and reasoning
* 📄 **Document Loaders**: Load and process various file formats for RAG
* 🧠 **Vector Memory**: Semantic search with 12 vector database integrations
* 🎯 **AI Skills**: Composable, reusable knowledge blocks injected into agent system messages at runtime
* 🔌 **MCP Server Integration**: Seed agents and models directly from MCP servers — tools discovered automatically
* 🗄️ **Global Tool Registry**: Register tools by name once, reference by string everywhere
* 🛡️ **Provider Capabilities**: Type-safe capability system — providers declare what they support, BIFs enforce it

### 📡 Supported Providers

BoxLang supports a variety of AI providers out of the box. You can also create custom providers by following our [Custom Provider Guide](https://ai.ortusbooks.com/extending-boxlang-ai/custom-providers).

| Provider           | Type    | Chat | Stream | Tools | Embeddings | Vision | Audio |
| ------------------ | ------- | ---- | ------ | ----- | ---------- | ------ | ----- |
| **Bedrock**        | Cloud   | ✅    | ✅      | ❌     | ✅          | ❌      | ❌     |
| **Claude**         | Cloud   | ✅    | ✅      | ✅     | ❌          | ✅      | ❌     |
| **Cohere**         | Cloud   | ✅    | ✅      | ✅     | ✅          | ❌      | ❌     |
| **DeepSeek**       | Cloud   | ✅    | ✅      | ✅     | ✅          | ❌      | ❌     |
| **Docker Desktop** | Local   | ✅    | ✅      | ✅     | ✅          | ❌      | ❌     |
| **Gemini**         | Cloud   | ✅    | ✅      | ✅     | ✅          | ✅      | ❌     |
| **Grok**           | Cloud   | ✅    | ✅      | ✅     | ❌          | ✅      | ❌     |
| **Groq**           | Cloud   | ✅    | ✅      | ✅     | ❌          | ❌      | ❌     |
| **HuggingFace**    | Cloud   | ✅    | ✅      | ✅     | ✅          | ❌      | ❌     |
| **MiniMax**        | Cloud   | ✅    | ✅      | ✅     | ✅          | ✅      | ❌     |
| **Mistral**        | Cloud   | ✅    | ✅      | ✅     | ✅          | ❌      | ❌     |
| **Ollama**         | Local   | ✅    | ✅      | ✅     | ✅          | ✅      | ❌     |
| **OpenAI**         | Cloud   | ✅    | ✅      | ✅     | ✅          | ✅      | ❌     |
| **OpenRouter**     | Gateway | ✅    | ✅      | ✅     | ✅          | ✅      | ❌     |
| **Perplexity**     | Cloud   | ✅    | ✅      | ❌     | ❌          | ❌      | ❌     |
| **Voyage**         | Cloud   | ❌    | ❌      | ❌     | ✅          | ❌      | ❌     |

> **Legend:** Vision support requires a multimodal model from the provider (e.g., `gpt-4o`, `claude-3`, `gemini-2.0`). Image/Audio (transcription/TTS) support is currently in development. OpenRouter capabilities depend on the selected underlying model.

### 🗃️ Supported Memory Types

BoxLang AI provides 20+ memory types for conversation history and semantic search. All memory types support multi-tenant isolation with `userId` and `conversationId`.

| Memory Type    | Vector | Best For                              | Storage           | Multi-Tenant |
| -------------- | ------ | ------------------------------------- | ----------------- | ------------ |
| **Windowed**   | ❌      | Recent N messages, simple context     | In-memory         | ✅            |
| **Summary**    | ❌      | Long conversations with summarization | In-memory         | ✅            |
| **Session**    | ❌      | Web sessions, survives page refresh   | HTTP Session      | ✅            |
| **File**       | ❌      | Persistent storage, file-based        | File System       | ✅            |
| **Cache**      | ❌      | Fast retrieval, distributed cache     | CacheBox          | ✅            |
| **JDBC**       | ❌      | Enterprise database storage           | Any JDBC DB       | ✅            |
| **BoxVector**  | ✅      | Development, prototyping              | In-memory         | ✅            |
| **Chroma**     | ✅      | Python integration, local dev         | ChromaDB          | ✅            |
| **Postgres**   | ✅      | Existing PostgreSQL infrastructure    | PostgreSQL        | ✅            |
| **MySQL**      | ✅      | Existing MySQL 9+ infrastructure      | MySQL             | ✅            |
| **OpenSearch** | ✅      | AWS integration, enterprise search    | OpenSearch        | ✅            |
| **TypeSense**  | ✅      | Fast typo-tolerant search             | TypeSense         | ✅            |
| **Pinecone**   | ✅      | Production cloud-native               | Pinecone Cloud    | ✅            |
| **Qdrant**     | ✅      | Self-hosted, high performance         | Qdrant            | ✅            |
| **Weaviate**   | ✅      | GraphQL, knowledge graphs             | Weaviate          | ✅            |
| **Milvus**     | ✅      | Enterprise, massive scale             | Milvus            | ✅            |
| **Hybrid**     | ✅      | Recent + semantic combined            | Vector + Standard | ✅            |

**📖 Learn More**: [Standard Memory Guide](https://ai.ortusbooks.com/main-components/memory) · [Vector Memory Guide](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/main-components/vector-memory.md)

### 📋 Supported Document Loaders

BoxLang AI provides 12 document loaders for importing content from various sources into standardized `Document` format for RAG workflows.

| Loader               | File Types         | Best For           | Features                                  |
| -------------------- | ------------------ | ------------------ | ----------------------------------------- |
| **TextLoader**       | `.txt`, `.text`    | Plain text files   | Simple text ingestion                     |
| **MarkdownLoader**   | `.md`, `.markdown` | Markdown documents | Header splitting, code removal            |
| **HTMLLoader**       | `.html`, `.htm`    | HTML pages         | Tag extraction, script/style removal      |
| **CSVLoader**        | `.csv`             | Tabular data       | Row/column modes, filtering               |
| **JSONLoader**       | `.json`            | JSON data          | Field extraction, array handling          |
| **XMLLoader**        | `.xml`             | XML documents      | XPath queries, attribute extraction       |
| **PDFLoader**        | `.pdf`             | PDF documents      | Text extraction, page splitting           |
| **LogLoader**        | `.log`             | Log files          | Pattern matching, timestamp parsing       |
| **HTTPLoader**       | URLs               | Web content        | HTTP/S, headers, authentication           |
| **FeedLoader**       | RSS/Atom           | RSS/Atom feeds     | Feed parsing, item extraction             |
| **SQLLoader**        | SQL queries        | Database records   | JDBC datasources, query execution         |
| **DirectoryLoader**  | Folders            | Batch loading      | Recursive scanning, type detection        |
| **WebCrawlerLoader** | Websites           | Web crawling       | Multi-page, depth control, link following |

**Key Features:**

* ✅ **Fluent API** - Chain configuration methods
* ✅ **Memory Integration** - Direct ingestion with `toMemory()`
* ✅ **Automatic Chunking** - Split large documents
* ✅ **Async Support** - Load documents asynchronously
* ✅ **Multi-Memory Fan-out** - Ingest to multiple vector stores
* ✅ **Transform/Filter** - Apply transformations during load

**📖 Learn More**: [Document Loaders Guide](https://ai.ortusbooks.com/rag/document-loaders) · [Custom Loaders](https://ai.ortusbooks.com/extending-boxlang-ai/custom-loader)

### 🚀 Use Cases

* 💬 **Chatbots**: Build conversational interfaces with memory and context
* ✍️ **Content Generation**: Create articles, documentation, marketing copy
* 💻 **Code Assistance**: Generate, review, and explain code
* 📊 **Data Analysis**: Extract insights from text and structured data
* 📄 **Document Processing**: Analyze PDFs, contracts, and reports
* 🎥 **Media Analysis**: Process images, audio, and video content
* 🌍 **Translations**: Multi-language content translation
* 📋 **Summarization**: Condense long documents intelligently
* ❓ **Question Answering**: Build knowledge bases and FAQs with RAG
* 🔄 **Custom Workflows**: Multi-step AI processing pipelines

***

## 📖 Quick Start

### 🎓 Getting Started

[Perfect for beginners - get up and running quickly](https://ai.ortusbooks.com/getting-started/getting-started)

### 💬 Simple AI Interactions

[Learn basic chat, streaming, and structured output](https://ai.ortusbooks.com/main-components/chatting)

### 🔗 AI Pipelines

[Build complex workflows with agents, memory, and tools](https://ai.ortusbooks.com/main-components/pipelines)

### 🤖 AI Agents

[Build reusable and autonomous agents, sub-agents, and much more.](https://ai.ortusbooks.com/main-components/agents)

***

## 🔧 Built-In Functions (BIFs)

BoxLang AI provides a comprehensive set of BIFs for different AI operations. You can see all of our BIF reference documentation here: [BIF Reference](https://ai.ortusbooks.com/advanced/reference/built-in-functions).

### 💬 Chat & Conversation

| BIF               | Purpose                        | Return Type   | Example Use Case                         |
| ----------------- | ------------------------------ | ------------- | ---------------------------------------- |
| `aiChat()`        | Simple one-shot chat request   | String        | Quick Q\&A, content generation           |
| `aiChatAsync()`   | Non-blocking chat request      | Future        | Background processing, parallel requests |
| `aiChatRequest()` | Build structured chat requests | AiChatRequest | Complex requests with tools              |
| `aiChatStream()`  | Real-time streaming responses  | void          | Live chat, progressive output            |
| `aiService()`     | Get AI service instances       | Service       | Multi-provider management                |

### 🏗️ Pipeline Components

| BIF                | Purpose                                                   | Return Type    | Example Use Case                  |
| ------------------ | --------------------------------------------------------- | -------------- | --------------------------------- |
| `aiAgent()`        | Create AI agents with tools, memory, skills & MCP servers | AiAgent        | Autonomous assistants, multi-turn |
| `aiMessage()`      | Build message pipelines                                   | AiMessage      | Reusable prompts, templates       |
| `aiModel()`        | Create model runnables with skills & MCP servers          | AiModel        | Pipeline integration              |
| `aiTransform()`    | Create data transformers                                  | Transformer    | Pipeline data processing          |
| `aiTool()`         | Define callable functions                                 | Tool           | Real-time data, function calling  |
| `aiSkill()`        | Create or discover AI skill blocks from SKILL.md files    | AiSkill        | Reusable knowledge injection      |
| `aiGlobalSkills()` | Access the global shared skills pool                      | Array          | Cross-agent knowledge sharing     |
| `aiToolRegistry()` | Access the global AI tool registry singleton              | AIToolRegistry | Named tool resolution             |

### 🧠 Memory & Context

| BIF          | Purpose                              | Return Type | Example Use Case                                  |
| ------------ | ------------------------------------ | ----------- | ------------------------------------------------- |
| `aiMemory()` | Create conversation or vector memory | Memory      | Context-aware conversations, RAG, semantic search |

### 📄 Document Processing

| BIF             | Purpose                     | Return Type  | Example Use Case         |
| --------------- | --------------------------- | ------------ | ------------------------ |
| `aiDocuments()` | Load documents from sources | Array/Loader | Document processing, RAG |

### 🔢 Utilities

| BIF            | Purpose                                                               | Return Type  | Example Use Case                                                                   |
| -------------- | --------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------- |
| `aiChunk()`    | Split text into chunks                                                | Array        | Processing large documents                                                         |
| `aiEmbed()`    | Generate vector embeddings                                            | Array/Struct | Semantic search, similarity                                                        |
| `aiPopulate()` | Populate a class instance, struct, or array from JSON data or struct. | Any          | This is useful for testing, custom workflows, or working with cached AI responses. |
| `aiTokens()`   | Estimate token counts                                                 | Numeric      | Cost estimation, limits                                                            |

### ⚙️ MCP (Model Context Protocol)

| BIF           | Purpose                     | Return Type | Example Use Case          |
| ------------- | --------------------------- | ----------- | ------------------------- |
| `MCP()`       | Connect to MCP servers      | MCPClient   | External tools, resources |
| `MCPServer()` | Create MCP server instances | MCPServer   | Expose tools to agents    |

***

## 🚀 Quick Examples

### 💬 Simple Chat

```javascript
answer = aiChat( "What is BoxLang?" )
println( answer )
```

### 🎨 Simple Chat with Parameters

```javascript
answer = aiChat(
    "Write a haiku about coding",
    { temperature: 0.9, model: "gpt-4" }
)
```

### 🔗 Build a Pipeline

```javascript
pipeline = aiMessage()
    .system( "You are a helpful assistant" )
    .user( "Explain ${topic}" )
    .toDefaultModel()
    .transform( r => r.content )

result = pipeline.run( { topic: "recursion" } )
```

### ⚡ Stream Responses

```javascript
aiChatStream(
    "Tell me a story",
    ( chunk ) => print( chunk.choices?.first()?.delta?.content ?: "" )
)
```

### 📦 Get JSON Responses

```javascript
// Automatically parse JSON responses
user = aiChat(
    "Create a user profile with name, age, and email for Alice",
    { returnFormat: "json" }
)

println( "Name: #user.name#" )
println( "Age: #user.age#" )
println( "Email: #user.email#" )
```

### 🛠️ Use AI Tools

```javascript
// Let AI call functions for real-time data
getWeather = aiTool(
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
        location: { type: "string", description: "City name" }
    },
    callback: ( args ) => {
        return { temp: 72, condition: "sunny", location: args.location }
    }
)

response = aiChat(
    "What's the weather in San Francisco?",
    { tools: [ getWeather ] }
)
```

### 🔢 Generate Embeddings

```javascript
// Create vector embeddings for semantic search
embeddings = aiEmbed([
    "BoxLang is a modern JVM language",
    "Java is a programming language",
    "Python is popular for AI"
])

// Use embeddings for similarity comparison
println( "Generated #embeddings.len()# embeddings" )
```

### 📄 Load Documents

```javascript
// Load documents for RAG
documents = aiDocuments( source: "docs/guide.md" )

// Use with memory
memory = aiMemory( type: "vector" )
memory.addDocuments( documents )

// Query with context
response = aiChat(
    "What is covered in the guide?",
    { memory: memory }
)
```

### 🤖 Create an Agent

```javascript
// Build an autonomous agent
agent = aiAgent()
    .name( "Research Assistant" )
    .instructions( "You help research and summarize topics" )
    .memory( aiMemory( type: "windowed", size: 10 ) )
    .tools([
        searchTool,
        summarizeTool
    ])

// Agent handles multi-turn conversations
response = agent.chat( "Research AI trends in 2025" )
```

***

## 🆘 Need Help?

### 📚 Resources

* **📖 Full Documentation**: Explore all sections above for comprehensive guides
* **💡 Examples**: Check the [`/examples`](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/examples/README.md) folder for runnable code samples
* **🔍 BIF Reference**: See [`reference/built-in-functions/`](https://ai.ortusbooks.com/advanced/reference/built-in-functions) for detailed function docs
* **📦 Module Components**: Explore [`main-components/`](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/main-components/main-components/README.md) for in-depth component guides

### 🤝 Community & Support

* **👥 Community**: [BoxLang Community Forum](https://community.boxlang.io)
* **🐛 Issues**: [GitHub Issues](https://github.com/ortus-boxlang/bx-ai/issues)
* **💬 Discussions**: [GitHub Discussions](https://github.com/ortus-boxlang/bx-ai/discussions)
* **✉️ Email Support**: <ai@ortussolutions.com>

### 🎓 Learning Paths

1. **🌱 Beginners**: Start with [Quick Start](https://ai.ortusbooks.com/getting-started/quickstart) → [Basic Chatting](https://ai.ortusbooks.com/main-components/chatting/basic-chatting) → [Examples](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/examples/README.md)
2. **🏗️ Builders**: Learn [Pipelines](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/main-components/main-components/overview.md) → [Memory](https://ai.ortusbooks.com/main-components/memory) → [Tools](https://ai.ortusbooks.com/main-components/tools)
3. **🚀 Advanced**: Explore [Agents](https://ai.ortusbooks.com/main-components/agents) → [RAG](https://ai.ortusbooks.com/rag/rag) → [Custom Components](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/advanced/advanced.md)

***

## 🌟 Upgrade to Plus

BoxLang and BoxLang AI are both Professional Open-Source (POS) projects. However, we also offer enterprise features, priority support, SLAs, and much more in our [BoxLang +/++ Plans.](https://boxlang.io/plans)

* 🏢 **Enterprise Modules**: Advanced components and integrations
* 🛠️ **Advanced Tooling**: Enhanced development and debugging tools
* ⚡ **Priority Support**: Direct access to our engineering team
* 🔐 **Enterprise Features**: SSO, audit logs, advanced security

**Learn more**: [boxlang.io/plans](https://boxlang.io/plans)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ai.ortusbooks.com/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.