⚡︎ BoxLang AI Intro Examples

Comprehensive Examples for the bx-ai Module – A progressive tutorial workspace showcasing everything from basic chat to advanced streaming, multimodal content, tool integration, and structured outputs.

---

📚 What is This?

This repository provides progressive, hands-on examples for learning the bx-ai module — an enterprise-grade AI integration framework for BoxLang. Each example builds on previous concepts, from basic chat requests to advanced features like streaming, tool usage, and structured outputs.

Perfect for:

• Learning BoxLang AI capabilities incrementally
• Teaching AI integration patterns
• Prototyping AI features quickly
• Exploring different providers and models

---

🚀 Quick Start

Prerequisites

• BoxLang CLI installed
  • We recommend using our BoxLang Version Manager (BVM) for easy setup: https://boxlang.ortusbooks.com/getting-started/installation/boxlang-version-manager-bvm
  • Alternatively, you can install BoxLang globally: https://boxlang.ortusbooks.com/getting-started/installation/boxlang-quick-installer
  • Or if you need a Windows installer: https://boxlang.io/download
• At least one AI provider API key (OpenAI, Claude, OpenRouter, Gemini, etc.), in the .env file (Make to create it from .env.example)

Setup

# 1. Clone and enter the repo
git clone https://github.com/ortus-boxlang/bx-ai-intro.git
cd bx-ai-intro

#2a. Install BoxLang AI locally
install-bx-module bx-ai --local
#2b. Install BoxLang OS globally
install-bx-modules bx-ai

# 3. Create .env file with your API keys
cp .env.example .env
# Edit .env and add your API keys (e.g., OPENROUTER_API_KEY=sk-or-...)

# 4. Run any example
boxlang examples/01-basic-chat.bxs

---

📖 Progressive Examples

Each example demonstrates specific features. Run them in order to build understanding:

Basic Chat Examples

#	Example	Topics
01	Basic Chat	Simple text prompts to AI
02	Custom Provider	Override default provider/model
03	Options & Formats	Logging, return formats, debugging
04	Structured Output	Typed responses with classes

Message & Conversation Examples

#	Example	Topics
05	Message Objects	Messages with metadata & roles
06	Multimodal Content	Images, audio, and mixed content
07	Multi-Turn Conversations	Context-aware conversation loops
08	Tool Usage	Function calling and tools

Streaming Examples

#	Example	Topics
09	Basic Streaming	Real-time response streaming
10	Stream with UX	Streaming with formatted output
11	Reasoning Models	Advanced reasoning with streaming
12	Message Context	Managing complex conversation history

Pipeline Examples

#	Example	Topics
13	Basic Pipeline	Sequential AI operations (Intro)
14	Pipeline Streaming	Pipelines with real-time output
15	Pipeline Transformers	Custom and built-in transformers
16	Pipeline Structured Output	Typed responses in pipelines
17	Pipeline Tools	Function calling in pipelines
18	Multi-Model Pipeline	Chain multiple AI models together

Agent Examples

#	Example	Topics
19	Basic Agent	Creating autonomous AI agents
20	Agent Memories	Persistent memory and context recall
21	Agent Tools	Tool-enabled agents and function execution
22	Agent Subagents	Delegation and multi-agent collaboration
23	Agent Skills	Reusable domain knowledge injection
24	Agent Middleware	Logging, auditing, and guardrail hooks
25	Agent Middleware (Human-in-the-Loop)	Human approval middleware
26	Agent MCP Servers	Auto-discover tools from MCP servers
27	Agent Scheduler	Scheduled and recurring agent tasks

Speech & Audio Examples

#	Example	Topics
28	Text-to-Speech	Synthesize speech with aiSpeak(), voices, HD models, fluent builder API
29	Speech-to-Text	Transcribe audio with aiTranscribe(), language hints, TTS→STT round-trip, fluent builder API
30	Audio Translation	Translate spoken audio to English with aiTranslate(), fluent builder API
41	Streaming Speech	Stream audio as it is generated with aiSpeakStream(): time to first audio, stopping early (barge-in), word timestamps, mp3 vs pcm vs mulaw
42	Cartesia Voices	provider: "cartesia" for TTS and STT: voices, emotion and speed, output formats, TTS→STT round-trip
Web demo	Streaming Speech over HTTP	A runnable browser demo: raw mp3 into an <audio> tag, plus a voice-agent view with PCM, Web Audio and word highlighting

Advanced Feature Examples

#	Example	Topics
31	Image Generation	Generate images with aiImage(), AiImageResponse, the generateImage@bxai tool
32	Web Search	aiWebSearch() / aiWebSearchAsync(), the webSearch@bxai tool
33	Agent Registry	aiAgentRegistry() — register, list, resolve, and discover agents
34	Security Guardrails	InputSanitizerMiddleware, aiFence()/addUntrusted(), OutputGuardMiddleware, LLMGuardMiddleware
35	Gateways	aiGateway(), scripted approvals with the mock gateway, register:/module: auto-registration
36	HITL Batching & Durable Grants	Batched tool-call approvals, approve_always durable grants, aiDecisionStore()
37	Gateway Sessions	aiGatewaySession() — reject/queue/steer/interrupt policies, maxQueueDepth, lifecycle

Advanced Agent Mini-Apps (agents/)

Each subfolder under agents/ is a small, self-contained application built with bx-ai — deeper and more realistic than the numbered examples/.

Folder	Topics
01-web-search	Search-native provider (Perplexity sonar) — no custom tools needed
02-research	Explicit HTTP search/fetch/summarize tools, provider-agnostic
03-tools	Production-style agent with calculator, unit conversion, timezone, currency, weather tools
04-memory	Persistent memory across runs with FileMemory + SummaryMemory
05-subagents	Multi-agent orchestration — sub-agents as callable tools
06-skills	Domain skills injection — always-on vs. lazy-loaded
07-rag-basic	Retrieval-augmented generation with pure-BoxLang TF-IDF, no external services
08-rag-vector	Production RAG with OpenAI embeddings + ChromaDB vector search
09-local-llm	Fully local agents via Ollama — no API keys, no internet
10-enterprise	Capstone: combines every capability from 01-09 into one workflow system

---

⚙️ Configuration

Default Configuration (config/boxlang.json)

{
    "modules": {
        "bxai": {
            "settings": {
                "provider": "openrouter",
                "defaultParams": {
                    "model": "openrouter/free"
                },
                // Omitted on purpose — inherits the module's own 90s default.
                // "timeout": 90,
                "logRequestToConsole": false,
                "returnFormat": "single"
                // ...plus providers (openai/claude/bedrock), security, gateways, and hitl —
                // see the full, commented config/boxlang.json for all of it.
            }
        }
    }
}

API Keys (.env)

All providers use the pattern <PROVIDER>_API_KEY:

OPENAI_API_KEY=sk-...
CLAUDE_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
GEMINI_API_KEY=...

See .env.example for all supported providers.

🐛 Debugging Tips

1. Enable request logging in config/boxlang.json:

   "logRequestToConsole": true
   

2. See the raw provider response:

   aiChat( "prompt", {}, { returnFormat: "raw" } )
   

3. Check your API keys - verify .env file has correct provider:

   # Common mistake: wrong provider name
   OPENROUTER_API_KEY=sk-or-...  # Exact case and spelling matters
   

4. Use different return formats for debugging:

   { returnFormat: "all" }    // All messages
   { returnFormat: "json" }   // Parse as JSON
   

---

📚 Learn More

• bx-ai GitHub – Main module repository
• BoxLang Docs – Language reference
• AI Module Docs – Detailed API documentation
• BoxLang MCP Server – Model Context Protocol integration

---

📝 License

Copyright Since 2023 by Ortus Solutions, Corp