Swama v1.4.0 Release Notes

🆕 What's New

OpenAI-Compatible Tool Calling Support

• Function calling API - Full OpenAI-compatible tool calling functionality for AI models to interact with external functions
• Flexible tool selection - Support for all tool choice modes: "none", "auto", "required", and function-specific selection
• Streaming & non-streaming - Unified tool call handling for both response modes with real-time tool call chunks via SSE
• Complete message support - Support for all message roles including system, user, assistant, and tool
• MLX integration - Seamless conversion between OpenAI tool specs and MLX ToolSpec format with automatic parameter handling

Gemma3 Vision-Language Model Support

• New model alias - Added gemma3 alias for mlx-community/gemma-3-27b-it-4bit vision-language model
• Multimodal inference - Native support for both text and image inputs with easy CLI usage
• Server-first architecture - CLI now prioritizes HTTP API calls to Swama.app backend for improved performance
• Auto-launch capability - Silently launches Swama.app if not running, with graceful fallback to direct execution
• Enhanced CLI options - Added --server-host and --server-port configuration for flexible deployment

ModelScope Registry Support

• Dual registry support - Support for both Hugging Face and ModelScope model downloads
• Environment configuration - Set SWAMA_REGISTRY=MODEL_SCOPE to use ModelScope, defaults to HUGGING_FACE
• China-friendly access - Provides Chinese users with faster and more accessible model downloads
• Seamless switching - Same CLI commands work with both registries without code changes
• Unified model management - Models from both registries appear in swama list with proper identification

🚀 Usage

Tool Calling

# Tool calling via HTTP API (OpenAI compatible)
curl -X POST http://localhost:28100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [{"role": "user", "content": "What is the weather in Tokyo?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Gemma3 Multimodal Inference

# Vision-language model with image input
swama run gemma3 "What's in this image?" -i /path/to/image.jpg

ModelScope Registry

# Use ModelScope registry for Chinese users
export SWAMA_REGISTRY=MODEL_SCOPE
swama pull qwen3

# Or use default Hugging Face registry
export SWAMA_REGISTRY=HUGGING_FACE
swama pull qwen3

# Registry setting persists for the session
swama list  # Shows models from configured registry

📦 Download

Download Swama v1.4.0

Available formats:

• brew install swama
• DMG installer - Easy drag-and-drop installation for macOS
• ZIP archive - Direct application bundle

🔄 Upgrade Notes

• If upgrading from a previous version: After installing the new version, open Swama from the menu bar and click "Install Command Line Tool…" to update the CLI tools
• Tool calling support: The /v1/chat/completions endpoint now supports OpenAI-compatible tool calling
• Gemma3 model: New vision-language model alias available immediately after upgrade
• ModelScope support: Set SWAMA_REGISTRY=MODEL_SCOPE environment variable to use ModelScope registry
• Server architecture: CLI now uses server-first approach for better performance (existing workflows continue to work)

🔧 Requirements

• macOS 14.0+
• Apple Silicon (M1/M2/M3/M4)
• For vision models: Compatible image formats (JPEG, PNG, etc.)
• For ModelScope: Internet connection to ModelScope platform

What's Changed

• feat: add SWAMA_PORT environment variable support for port configuration by @zhaopengme in #33
• Refactor: change to use SwiftUI.MenuBarExtra by @hitsubunnu in #36
• [Feature] Support download from modelscope by @BBBOND in #35
• Tool call by @sxy-trans-n in #38
• Gemma3 by @sxy-trans-n in #39
• Homebrew by @reneleonhardt Homebrew/homebrew-cask#217335

New Contributors

• @zhaopengme made their first contribution in #33
• @hitsubunnu made their first contribution in #36
• @BBBOND made their first contribution in #35

Full Changelog: v1.3.0...v1.4.0