====================
uncloseai.
====================

A Public Domain AI Assistant for the Open Web
=============================================

.. image:: https://img.shields.io/badge/license-Public%20Domain-blue.svg
   :target: https://creativecommons.org/publicdomain/zero/1.0/
   :alt: Public Domain

.. image:: https://img.shields.io/badge/AI-Hermes%203-green.svg
   :target: https://nousresearch.com/hermes3/
   :alt: Powered by Hermes 3

Overview
--------

uncloseai. is a free, open-source AI assistant that can be embedded into any webpage with a single line of code. It provides users with an intelligent assistant powered by Hermes 3 LLM from Nous Research, offering features like page reading, translation, text-to-speech, and contextual Q&A.

**Key Features:**

* **Page-Aware AI Assistant** - Understands and discusses the content of the current webpage
* **Multi-Language Support** - Supports 19 languages with full UI translation
* **Text-to-Speech** - Convert any text or webpage content to natural speech
* **Smart Translation** - Translate entire webpages while preserving formatting and functionality
* **File Upload Support** - Process PDFs, text files, and documents
* **Privacy-First** - No tracking, no analytics, no user data collection
* **Public Domain** - Completely free to use, modify, and distribute

Quick Start
-----------

Add this single line to any webpage:

.. code-block:: html

   <script src="https://uncloseai.com/uncloseai.js" type="module"></script>

That's it! Users will see a small robot icon (🤖) in the bottom-right corner that opens the AI assistant.

Repository
----------

The complete source code is available at: https://git.unturf.com/engineering/unturf/uncloseai.com

Project Structure
-----------------

The repository is organized with a ``public/`` directory containing all web-facing files:

.. code-block::

   uncloseai.com/
   ├── public/                        # Public web root (served via HTTPS)
   │   ├── index.html                 # Main landing page
   │   ├── demo.html                  # Interactive demo page
   │   ├── uncloseai.js               # Main entry point
   │   ├── css/                       # Stylesheets
   │   ├── src/                       # JavaScript modules
   │   │   ├── chat.js                # Core chat functionality
   │   │   ├── config.js              # Configuration and endpoints
   │   │   ├── content.js             # Content extraction utilities
   │   │   ├── language-detection.js  # Automatic language detection
   │   │   ├── models.js              # AI model management
   │   │   ├── page-reader.js         # Page reading functionality
   │   │   ├── storage.js             # LocalStorage management
   │   │   ├── token_estimator.js     # Token counting utilities
   │   │   ├── translation.js         # Translation system
   │   │   ├── translate-modal.js     # Translation UI
   │   │   ├── tts.js                 # Text-to-speech system
   │   │   ├── ui-themes.js           # Theme management
   │   │   ├── ui-translations.js     # UI translation system
   │   │   ├── uncloseai-embed-modal.js # Main modal UI
   │   │   └── languages/             # 19 language translation files
   │   │       ├── en.js (English), es.js (Spanish), zh.js (Chinese)
   │   │       ├── ar.js (Arabic), bn.js (Bengali), ru.js (Russian)
   │   │       ├── pt.js (Portuguese), ur.js (Urdu), id.js (Indonesian)
   │   │       ├── de.js (German), ja.js (Japanese), sw.js (Swahili)
   │   │       └── mr.js (Marathi), te.js (Telugu), tr.js (Turkish)
   │   └── languages/                 # 47 SDK implementations (browsable)
   │       ├── python/                # Python examples (4 variants)
   │       ├── javascript/            # JavaScript examples (4 variants)
   │       ├── rust/, go/, java/      # Compiled language examples
   │       ├── ruby/, php/, perl/     # Dynamic language examples
   │       └── ... (43+ total languages)
   ├── book/                          # Private book content (not served)
   ├── CLAUDE.md                      # Project documentation
   ├── .gitlab-ci.yml                 # CI/CD pipeline
   └── package.json                   # Development dependencies

**Language SDK Directory**

Browse the complete collection of 47 language implementations at:
https://uncloseai.com/languages/

Each language directory contains:

* Working SDK code with streaming support
* Dockerfile for building and testing
* README with usage examples
* Environment-based configuration

Supported languages include Python, JavaScript, TypeScript, Rust, Go, Java, C, C++, Ruby, PHP, Kotlin, Swift, Elixir, Haskell, and 30+ more.

Core Technologies
-----------------

* **Frontend**: Vanilla JavaScript ES6+ modules
* **UI Framework**: PicoCSS (optional) with custom theming support
* **AI Model**: Hermes 3 Llama 3.1 8B (via VLLM endpoints)
* **Testing**: Jest with JSDOM
* **Code Quality**: Biome for formatting and linting
* **Markdown**: Marked.js for rendering
* **Syntax Highlighting**: Highlight.js
* **TTS**: OpenAI-compatible speech API

Key Features Explained
----------------------

Page-Aware Intelligence
~~~~~~~~~~~~~~~~~~~~~~~

The AI assistant automatically extracts and understands the content of the current webpage, allowing users to ask questions about what they're reading. It maintains context throughout the conversation.

Multi-Language Interface
~~~~~~~~~~~~~~~~~~~~~~~~

The entire UI is available in **19 languages** with complete translation coverage:

**Supported Languages:**

* **English** (en) - Default language
* **Spanish** (es) - Español
* **Chinese Simplified** (zh) - 中文（简体）
* **Chinese Traditional** (zh-tw) - 中文（繁體）
* **Hindi** (hi) - हिन्दी
* **French** (fr) - Français
* **Arabic** (ar) - العربية
* **Bengali** (bn) - বাংলা
* **Russian** (ru) - Русский
* **Portuguese** (pt) - Português
* **Urdu** (ur) - اردو
* **Indonesian** (id) - Bahasa Indonesia
* **German** (de) - Deutsch
* **Japanese** (ja) - 日本語
* **Swahili** (sw) - Kiswahili
* **Marathi** (mr) - मराठी
* **Telugu** (te) - తెలుగు
* **Turkish** (tr) - Türkçe
* **Korean** (ko) - 한국어

**Language Features:**

* **Manual Selection**: Users can manually select their preferred language from 19 options
* **Complete Coverage**: All UI elements, buttons, modals, and messages are translated
* **AI Response Language**: The AI responds in the user's selected language
* **Persistent Settings**: Language preference is saved in browser localStorage
* **No Page Refresh**: Language switching works instantly without reloading

**Translation Coverage Includes:**

* Modal titles and headers
* Button labels and tooltips  
* Input placeholders and form labels
* System messages and notifications
* Error messages and alerts
* Settings and configuration options
* Help text and descriptions

Text-to-Speech Capabilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Two TTS modes are available:

1. **Direct TTS**: Converts text directly to speech
2. **Hermes-Enhanced TTS**: Uses AI to improve pronunciation and clarity

Smart Translation
~~~~~~~~~~~~~~~~~

The translation feature:

* Preserves HTML structure and formatting
* Maintains code blocks and technical content
* Opens translated pages in new tabs with full AI functionality
* Supports both full-page and custom text translation

Development Setup
-----------------

.. code-block:: bash

   # Clone the repository
   git clone https://git.unturf.com/engineering/unturf/uncloseai.com.git
   cd uncloseai.com

   # Install dependencies
   npm install

   # Run tests
   npm test

   # Format code
   npx biome format --write .

   # Lint code
   npx biome check .

   # Run both (recommended before commits)
   npx biome format --write . && npx biome check .

Architecture
------------

uncloseai. uses a modular architecture:

1. **Entry Point** (``uncloseai.js``): Detects environment and initializes
2. **Modal System** (``uncloseai-embed-modal.js``): Main UI container
3. **Feature Modules**: Separate modules for chat, TTS, translation
4. **Storage Layer** (``storage.js``): Handles persistent conversation history
5. **Model Management** (``models.js``): Dynamic endpoint selection
6. **Theme System** (``ui-themes.js``): Adapts to page styling

API Endpoints
-------------

uncloseai. connects to these public endpoints:

* **Chat**: ``https://hermes.ai.unturf.com/v1`` (primary)
* **Chat**: ``https://hermes2.ai.unturf.com/v1`` (fallback)
* **TTS**: ``https://speech.ai.unturf.com/v1/audio/speech``
* **File Processing**: ``https://megaparce.ai.unturf.com/v1/file``

All endpoints are OpenAI-compatible.

Customization
-------------

Website owners can customize the assistant:

.. code-block:: javascript

   // Set custom system message
   window.UNCLOSEAI_SYSTEM_MESSAGE_APPEND = "You are helping users on an e-commerce site...";

   // Disable custom styling (use pure PicoCSS)
   window.UNCLOSEAI_CUSTOM_STYLING = false;

   // Control initialization
   window.UNCLOSEAI_SKIP_INIT = true;

Browser Support
---------------

* Chrome/Edge 80+
* Firefox 75+
* Safari 14+
* Mobile browsers with ES6 module support

Performance
-----------

* Initial load: ~50KB (gzipped)
* Lazy loads features as needed
* Caches model lists and translations
* Efficient token counting with upstream API

Privacy & Security
------------------

* **No tracking**: No analytics, cookies, or user tracking
* **No data storage**: Conversations stored only in browser localStorage
* **No authentication**: No user accounts or sign-ups required
* **Public endpoints**: All API endpoints are publicly accessible
* **Content Security**: Sanitizes HTML, escapes code blocks

Contributing
------------

This project is in the public domain. You're free to:

* Use it commercially or non-commercially
* Modify it without attribution
* Distribute it freely
* Create derivative works

We welcome contributions! Feel free to submit issues or pull requests.

Testing
-------

.. code-block:: bash

   # Run all tests
   npm test

   # Run tests in watch mode
   npm test -- --watch

   # Run tests with coverage
   npm test -- --coverage

The test suite covers:

* Modal creation and interaction
* Translation functionality
* TTS processing
* Storage operations
* UI theme detection
* Language system functionality

Production Deployment
---------------------

1. Serve files with proper MIME types
2. Enable CORS for module scripts
3. Use HTTPS (required for some features)
4. Set cache headers appropriately

Troubleshooting
---------------

**Modal not appearing:**

* Check browser console for errors
* Ensure JavaScript modules are supported
* Verify CORS headers are set correctly

**Translation/TTS not working:**

* Check network tab for API errors
* Ensure endpoints are accessible
* Verify API key is set (if using custom endpoints)

**Styling issues:**

* Set ``UNCLOSEAI_CUSTOM_STYLING = false`` for pure PicoCSS
* Check for CSS conflicts with page styles

License
-------

This project is released into the public domain under CC0 1.0 Universal.

See: https://creativecommons.org/publicdomain/zero/1.0/

About
-----

uncloseai. is part of the unturf. project, creating open tools for an open web. It's built by fxhp and the carnival hackers who believe AI should be accessible to everyone.

**Why "uncloseai."?**

The name represents keeping AI "unclosed" - open, accessible, and free for all to use and modify.

Links
-----

* **Homepage**: https://uncloseai.com
* **Repository**: https://git.unturf.com/engineering/unturf/uncloseai.com
* **Demo**: https://uncloseai.com/demo
* **Hermes Model**: https://nousresearch.com/hermes3/

Acknowledgments
---------------

* Nous Research for the amazing Hermes 3 model
* The open-source community for the libraries we build upon
* Everyone who believes in an open, accessible internet

Remember: This is your AI assistant. Make it yours!