Russell Ballestrini
41818a202b
- Created extensive README.rst with full project documentation - Added brief documentation sections to index.html and demo.html - Emphasized public domain licensing and open web philosophy - Fixed branding to use lowercase uncloseai. and unturf. - Points users to git repository for complete technical details 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
309 lines
No EOL
9.2 KiB
ReStructuredText
309 lines
No EOL
9.2 KiB
ReStructuredText
====================
|
|
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
|
|
-----------------
|
|
|
|
.. code-block::
|
|
|
|
ai.unturf.com/
|
|
├── index.html # Main landing page
|
|
├── demo.html # Interactive demo page
|
|
├── uncloseai.js # Main entry point
|
|
├── src/
|
|
│ ├── 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/ # Translation files
|
|
│ ├── en.js, es.js, zh.js, hi.js, fr.js, ar.js, bn.js,
|
|
│ ├── ru.js, pt.js, ur.js, id.js, de.js, ja.js, sw.js,
|
|
│ ├── mr.js, te.js, tr.js, zh-tw.js, ko.js
|
|
└── tests/ # Jest test suite
|
|
|
|
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:
|
|
|
|
* English, Spanish, Chinese (Simplified & Traditional), Hindi, French
|
|
* Arabic, Bengali, Russian, Portuguese, Urdu, Indonesian
|
|
* German, Japanese, Swahili, Marathi, Telugu, Turkish, Korean
|
|
|
|
Language is auto-detected from the page content and can be manually changed.
|
|
|
|
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 detection
|
|
|
|
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! |