🚀 Ultralytics LLM

Ultralytics LLM provides a lightweight, production-ready JavaScript chat client for integrating AI-powered conversations into web applications. Built for jsDelivr CDN delivery with zero dependencies.

!Ultralytics Chat Window

🎯 Current Status

⚠️ Experimental Development: The chat widget ships as a CDN-ready chat.min.js bundle. Track tagged releases for production deployments and reserve @main for testing nightly changes.

> Ecosystem: This repo hosts both the in-browser chat widget and the Python scaffolding we use for backend workflows. The widget is production ready, while the Python client remains a lightweight placeholder until the managed API is released.

📦 Installation

JavaScript (Browser)

Load the chat widget via jsDelivr CDN:

<!-- Latest stable release (recommended for production) -->
<script src="https://cdn.jsdelivr.net/gh/ultralytics/llm@latest/js/chat.min.js"></script>
<!-- Specific version (guaranteed stability) -->
<script src="https://cdn.jsdelivr.net/gh/ultralytics/[email protected]/js/chat.min.js"></script>
<!-- Main branch (experimental, for testing) -->
<script src="https://cdn.jsdelivr.net/gh/ultralytics/llm@main/js/chat.min.js"></script>

CDN Links:

• 🔍 Browse files: jsdelivr.com/package/gh/ultralytics/llm
• 📊 View stats: Check download counts and version usage
• 🏷️ Latest release: https://cdn.jsdelivr.net/gh/ultralytics/llm@latest/js/chat.min.js
• 🔬 Main branch: https://cdn.jsdelivr.net/gh/ultralytics/llm@main/js/chat.min.js

• @latest - Always points to the newest tagged release (cache purged on new releases)
• @v0.2.12 - Specific version tags (permanent cache, high reliability)
• @main - Latest development code (12-hour cache, auto-purged on push)

Note: For production, use @latest or pin to a specific version tag. The @main branch is for testing and may contain breaking changes.

🎯 Quick Start

!Ultralytics Chat Pill

JavaScript Chat Widget

<!DOCTYPE html>
<html>
  <head>
    <title>Ultralytics Chat</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
  </head>
  <body>
    <script src="https://cdn.jsdelivr.net/gh/ultralytics/llm@latest/js/chat.min.js"></script>
    <script>
      const chat = new UltralyticsChat({
        apiUrl: "https://your-api-endpoint.com/api/chat",
        branding: {
          name: "My AI Assistant",
          tagline: "Ask me anything!",
          pillText: "Chat with AI",
        },
        theme: {
          primary: "#042AFF",
          yellow: "#E1FF25",
        },
      });
    </script>
  </body>
</html>

🎨 JavaScript Chat Features

• 🎯 Zero Dependencies: Standalone vanilla JavaScript (~1700 lines), no frameworks required
• 📱 Mobile Optimized: Full iOS & Android support with orientation handling, safe area insets, and back button integration
• 🌗 Dark Mode: Automatic theme switching based on system preferences
• 💻 Responsive: Desktop modal and mobile full-screen layouts (WebKit, Blink, Gecko)
• ⚡ Streaming: Real-time SSE response streaming with abort support
• 🔍 Search Mode: Built-in documentation search capability
• 💾 Session Management: Server-issued session ID (X-Session-ID header) carried across messages
• ♿ Accessible: WCAG compliant with ARIA labels and keyboard navigation
• 🎨 Customizable: Full theme and branding control
• 📄 Page Context: Opt-in DOM scraping sends visible page content to the AI for context-aware responses
• 🔒 Security: XSS protection with HTML escaping, input length limits

⚙️ Configuration Options

JavaScript Widget

const chat = new UltralyticsChat({
  // API Configuration
  apiUrl: "/api/chat", // Chat endpoint that streams SSE
  maxMessageLength: 10000, // Character limit enforced per user message
  analytics: true, // Set false to disable backend chat analytics and feedback logging
  pageContent: false, // Opt-in DOM scraping for rich page context (default: false)
// Branding
  branding: {
    name: "AI Assistant", // Assistant name
    tagline: "How can I help?", // Tagline text
    logo: "https://...", // Header logo URL
    logomark: "https://...", // Pill button logo URL
    logoUrl: "https://example.com", // Link when header logo is clicked
    pillText: "Ask AI", // Pill button text
  },
// Theme Colors
  theme: {
    primary: "#042AFF", // Primary brand color
    dark: "#111F68", // Dark theme accent
    accent: "#E1FF25", // Highlight color (falls back to theme.yellow)
    text: "#0b0b0f", // Text color
  },
// Welcome Message
  welcome: {
    title: "Hi!",
    message: "How can I help you today?",
    chatExamples: ["What is YOLO11?", "How do I train a model?"],
    searchExamples: ["YOLO quickstart", "model training parameters"],
  },
// UI Text
  ui: {
    placeholder: "Ask anything…",
    copyText: "Copy thread",
    downloadText: "Download thread",
    clearText: "New chat",
  },
shouldHandleShortcut: (event, chat) => {
    return !(event.target instanceof Element && event.target.closest("[data-site-search]"));
  },
});

UltralyticsChat automatically injects document context (title, URL, path) into each request so your backend can provide page-aware responses. When pageContent: true is set, the widget also scrapes visible text from the page's

element (up to 5,000 characters), stripping navigation, scripts, SVGs, and elements marked with data-chat-ignore. This gives the AI full awareness of what the user is currently viewing. When disabled (default), the widget falls back to the page's tag.

API Requirements

Your backend should implement:

POST /api/chat
Content-Type: application/json
{
  "messages": [{"role": "user", "content": "Hello"}],
  "session_id": "optional-session-id",
  "context": {
    "url": "https://example.com/docs/widget",
    "title": "Docs page title",
    "description": "Visible page text or meta description",
    "path": "/docs/widget"
  },
  "analytics": false,
  "edit_index": 3 // optional when user edits a previous turn
}
Response: Server-Sent Events (SSE)
data: {"content": "Hello! "}
data: {"content": "How can "}
data: {"content": "I help?"}
data: [DONE]
Headers:
X-Session-ID: session-uuid (for persistence)
Content-Type: text/event-stream

When the widget is switched to Search mode it will call the same base URL with /search replacing /chat via POST /api/search and expects a JSON body { "results": [{ title, url, text, score }] }.

📱 Mobile Support

iOS (Safari, Chrome, Firefox)

• ✅ Safe area insets for notched devices
• ✅ Keyboard handling with auto-resize
• ✅ Home indicator padding
• ✅ Smooth scrolling optimization

Android (Chrome, Samsung Internet, Firefox)

• ✅ Back button integration (History API)
• ✅ Dynamic viewport height (address bar handling)
• ✅ Touch action optimization
• ✅ Gesture navigation support
• ✅ Split-screen and multi-window modes

Cross-Platform

• ✅ Portrait/landscape orientation changes
• ✅ Full-screen mobile modal (no horizontal scroll)
• ✅ Background scroll lock when open
• ✅ Keyboard shortcuts (desktop: Cmd/Ctrl+K, ESC)

🔧 Development

Build Minified Version

npm install -g terser
terser js/chat.js -o js/chat.min.js -c -m --comments false

Note: You don't need to commit chat.min.js manually — the Minify workflow rebuilds and commits it automatically on PRs that modify js/chat.js.

Local Testing

# macOS
open examples/web/demo.html
Linux
xdg-open examples/web/demo.html

You can also open examples/web/demo.html directly from your file browser. No local server or build step is required.

Browser Compatibility

Tested and working on:

• ✅ Chrome/Edge 90+ (Blink)
• ✅ Safari 14+ (WebKit)
• ✅ Firefox 88+ (Gecko)
• ✅ Mobile Safari (iOS 12+)
• ✅ Chrome Mobile (Android 8+)
• ✅ Samsung Internet (Android 8+)

🌟 Roadmap

JavaScript Client (Current Focus)

• [x] Chat widget with streaming
• [x] Dark mode support
• [x] Search mode
• [x] Session persistence
• [x] Production-ready security & performance
• [x] Full mobile support (iOS & Android)
• [x] Page content awareness (opt-in DOM scraping)
• [ ] File upload support
• [ ] Voice input
• [ ] Multi-language support
• [ ] Official v1.0.0 release

Python Backend (Coming Soon)

We plan to open-source our Python components once mature:

• [ ] LLMClient class for Claude/OpenAI/etc.
• [ ] FastAPI server implementation
• [ ] Async streaming support
• [ ] Tool/function calling
• [ ] RAG integration with vector databases
• [ ] Session management utilities
• [ ] Rate limiting & caching

📖 Documentation

• API reference for the widget and backend contracts: docs/API.md
• Product announcements and tutorials: docs.ultralytics.com (LLM section rolling out alongside SDK updates)

💡 Contribute

Ultralytics thrives on community collaboration! While this repo is currently experimental, we welcome:

• Bug Reports: Found an issue? Report it on GitHub Issues
• Feature Requests: Have an idea? Share it via GitHub Issues
• Pull Requests: Want to contribute? Please read our Contributing Guide first
• Feedback: Share your experience in our Discord or Community Forums

A heartfelt thank you 🙏 to all our contributors!

📄 License

Ultralytics offers two licensing options:

• AGPL-3.0 License: Ideal for students, researchers, and enthusiasts passionate about open collaboration. This OSI-approved open-source license promotes transparency and community involvement. See the LICENSE file for details.
• Enterprise License: For commercial applications, this license permits seamless integration of Ultralytics software into commercial products, bypassing AGPL-3.0 copyleft requirements. Inquire about an Ultralytics Enterprise License.

📮 Contact

For bug reports or feature suggestions related to this repo or other Ultralytics projects, please use GitHub Issues. For general questions, discussions, and community support, join our Discord server!