uncloseai.com/journal.rst

.. This is free software for the public good of a permacomputer hosted at
.. permacomputer.com, an always-on computer by the people, for the people.
.. One which is durable, easy to repair, & distributed like tap water
.. for machine learning intelligence.
..
.. The permacomputer is community-owned infrastructure optimized around
.. four values:
..
..   TRUTH      First principles, math & science, open source code freely distributed
..   FREEDOM    Voluntary partnerships, freedom from tyranny & corporate control
..   HARMONY    Minimal waste, self-renewing systems with diverse thriving connections
..   LOVE       Be yourself without hurting others, cooperation through natural law
..
.. This software contributes to that vision by making machine learning
.. accessible to everyone through a free, open, embeddable chat interface.
.. Code is seeds to sprout on any abandoned technology.

====================
Development Journal
====================

July 2, 2025
============

Token Estimator Implementation
-------------------------------

Built `token_estimator.js` - a simplified BPE-based token counter for translation ETA estimation. 

**Not compatible with tiktoken** - this is estimation-only, ~85% accuracy. Good enough for progress bars, not for exact tokenization.

**NVIDIA 4090 Performance Metrics:**
- Prompt processing: 3,144 tokens/sec
- Generation: 121 tokens/sec  
- Translation estimates: 1K tokens ≈ 11 seconds

The estimator uses real production metrics from our Hermes machine to provide realistic translation timing.

July 3, 2025
============

Complete Translation Infrastructure Overhaul
--------------------------------------------

**Modular Language System Implementation**

Restructured the entire translation system to use individual language files instead of one monolithic object. Each of the 19 supported languages now has its own dedicated JS file in `/src/languages/`.

**Language Coverage:**
- 🇺🇸 English (en.js) - 46 translation keys
- 🇨🇳 Chinese Simplified (zh.js) 
- 🇹🇼 Chinese Traditional (zh-tw.js)
- 🇮🇳 Hindi (hi.js)
- 🇪🇸 Spanish (es.js) 
- 🇫🇷 French (fr.js)
- 🇸🇦 Arabic (ar.js)
- 🇧🇩 Bengali (bn.js)
- 🇷🇺 Russian (ru.js)
- 🇧🇷 Portuguese (pt.js)
- 🇵🇰 Urdu (ur.js)
- 🇮🇩 Indonesian (id.js)
- 🇩🇪 German (de.js)
- 🇯🇵 Japanese (ja.js)
- 🇰🇪 Swahili (sw.js)
- 🇮🇳 Marathi (mr.js)
- 🇮🇳 Telugu (te.js)
- 🇹🇷 Turkish (tr.js)
- 🇰🇷 Korean (ko.js)

**Dynamic UI Refresh System**

Implemented `refreshUILanguage()` function that updates all UI text without requiring browser refresh:

- **Declarative translations**: Elements with `data-i18n` attributes automatically update
- **Parameter support**: `data-i18n-params` for dynamic text with variables like `{lang}` and `{error}`
- **Smart element detection**: Handles inputs, buttons, placeholders, and modal titles
- **Event system**: Dispatches `languageChanged` custom events for component integration
- **Backward compatibility**: Maintains `window.refreshUILanguage` for existing code

**Translation Verification System**

Created `verify-translations.js` - a Node.js script that ensures translation consistency:

- **Key extraction**: Parses JS files to extract translation object keys  
- **Completeness verification**: Compares all languages against English reference
- **Missing/extra key detection**: Reports inconsistencies with colored console output
- **Exit codes**: Returns 0 for success, 1 for issues (CI/CD friendly)

**Adding New Languages - Workflow:**

1. **Before adding**: Run verification to ensure current state is clean
   ```bash
   cd /home/fox/git/ai.unturf.com/src/languages
   node verify-translations.js
   ```
   Should show: "🎉 All languages have complete translations!"

2. **Create new language file**: Copy structure from `en.js`
   ```bash
   cp en.js new-lang.js  # Replace 'new-lang' with actual language code
   ```

3. **Translate all values**: Keep the same keys, translate only the string values

4. **Update index.js**: Add import and export for the new language
   ```javascript
   import { newLang } from "./new-lang.js";
   // Add to UI_TRANSLATIONS object
   ```

5. **Verify completeness**: Run script again to check for issues
   ```bash
   node verify-translations.js
   ```
   
6. **Fix any issues**: Script will show missing/extra keys in red
   - Missing keys: Add them with proper translations
   - Extra keys: Remove them or add to English reference if needed

7. **Final verification**: Run until you see the success message again

**File Structure:**
```
src/languages/
├── index.js              # Aggregates all translations
├── en.js                 # English reference (46 keys)
├── [18 other languages]  # Complete translations
└── verify-translations.js # Sanity check script
```

**Benefits:**
- **Maintainability**: Each language isolated in its own file
- **Consistency**: 100% key coverage verified across all 19 languages  
- **Real-time UX**: Language switching without page refresh
- **Developer experience**: Automated verification prevents translation drift
- **Scalability**: Easy to add new languages following the established pattern

This system supports the full user journey from language detection to dynamic interface updates, ensuring a seamless multilingual experience for all Hermes AI users.

July 9, 2025
============

Modal CSS Architecture Overhaul
-------------------------------

**The Problem**

Users reported multiple issues with the UncloseAI modal experience:

1. **Desktop Issue**: PicoCSS-powered sites displayed full-screen modals on large laptop displays instead of centered dialogs
2. **Translation Pages**: Broken CSS in translated pages opened in new windows made them unusable
3. **Mobile Experience**: After initial fixes, mobile devices lost their full-screen modal experience

**Root Cause Analysis**

Three interconnected issues created these problems:

1. **Inconsistent CSS Loading**: Different modal files used different detection methods and URL patterns
2. **PicoCSS Overrides**: The framework's aggressive dialog styling required careful specificity management
3. **Breakpoint Mismatch**: Mobile detection used 480px while many tablets needed full-screen at 768px

**Solution: Complete CSS Architecture Refactoring**

**Step 1: Dedicated CSS Files**

Created two purpose-built stylesheets to replace all inline styles:

- ``uncloseai-modal-builtin.css`` - Clean styles for standard blog sites
- ``uncloseai-modal-pico.css`` - Override styles with ``!important`` for PicoCSS sites

**Step 2: Unified CSS Loading Pattern**

Standardized all modal components to use the same detection and loading logic:

```javascript
// Detect if PicoCSS is actually present on the page
const hasPicoCSS = document.querySelector('link[href*="pico"]') !== null;

// Load appropriate CSS based on actual PicoCSS presence
const cssFile = hasPicoCSS ? 'uncloseai-modal-pico.css' : 'uncloseai-modal-builtin.css';

// Use absolute URLs for cross-domain compatibility
link.href = `https://uncloseai.com/src/${cssFile}`;
```

**Step 3: PicoCSS Override Strategy**

```css
/* Override PicoCSS dialog defaults with high specificity */
dialog#uncloseai-embedded-modal[data-theme] {
  position: fixed !important;
  top: 50% !important;
  left: 50% !important;
  transform: translate(-50%, -50%) !important;
  width: 70vw !important;
  max-width: 800px !important;
}

/* Mobile/tablet full-screen experience */
@media (max-width: 768px) {
  dialog#uncloseai-embedded-modal[data-theme] {
    top: 0 !important;
    left: 0 !important;
    width: 100vw !important;
    height: 100vh !important;
  }
}
```

**Step 4: Translation Page CSS Fix**

- Added ``<base href="${baseUrl}">`` tag to resolve relative URLs in new windows
- Ensured all modal CSS uses absolute URLs for cross-window compatibility
- Maintained original page styling while adding AI functionality

**Technical Implementation**

**Files Modified:**
- ``uncloseai-embed-modal.js`` - Main modal with PicoCSS detection
- ``translate-modal.js`` - Translation modal with absolute URLs
- ``tts-modal.js`` - TTS modal with consistent loading
- ``widget-library.js`` - Widget components with proper CSS
- ``translation.js`` - Base tag injection for new windows
- ``uncloseai-modal-builtin.css`` - Standard site styles
- ``uncloseai-modal-pico.css`` - PicoCSS override styles

**Responsive Breakpoints:**
- **Desktop (>768px)**: Centered modal (70vw × 90vh, max 800px width)
- **Mobile/Tablet (≤768px)**: Full-screen modal (100vw × 100vh)

**Results**

✅ **Desktop Experience**: Properly centered modals on large displays
✅ **Mobile Experience**: Full-screen modals on phones and tablets
✅ **Translation Pages**: Functional CSS in new window contexts
✅ **Code Architecture**: Clean separation between JS logic and CSS styling
✅ **Cross-Site Compatibility**: Consistent behavior across all site types
✅ **Maintainability**: Single source of truth for modal styling

This comprehensive refactoring established a robust CSS architecture that handles all edge cases while providing an optimal user experience across all devices and contexts.

July 11, 2025
=============

Custom API Integration & UI Overhaul
-------------------------------------

**Major Features Implemented:**

Custom API Endpoint Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Implemented comprehensive custom OpenAI-compatible API support allowing users to integrate their own AI providers (Groq, OpenAI, Claude, etc.) into the chat system:

- **Centralized Configuration System**: Created ``getAPIConfig()`` in ``config.js`` to manage API settings
- **Universal API Call Patching**: All chat functions now check for custom configuration automatically
- **Dynamic Model Discovery**: System fetches available models from custom endpoints via ``/v1/models``
- **Intelligent Max Tokens**: Automatically detects context limits from model metadata:
  - VLLM: ``max_model_len`` (e.g., 82,000 tokens)
  - OpenAI: ``max_tokens`` (e.g., 8,192 tokens)  
  - Groq: ``context_length`` (e.g., 128,000 tokens)
- **Seamless Fallback**: Falls back to default Hermes endpoints when custom API unavailable

**Settings Panel Complete Redesign**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Restructured the settings interface for better organization and usability:

- **Two-Column Grid Layout**: Left column (Model, Voice, Language), Right column (API Configuration)
- **Quick Actions Header**: Action buttons span both columns at the top for prominence
- **Mobile Responsive**: Automatically stacks to single column on screens ≤768px
- **Label Cleanup**: Removed redundant section headers (``AI Model:``, ``TTS Voice:``, etc.) for cleaner look
- **Grid Override Fixes**: Added ``!important`` declarations to overcome PicoCSS conflicts

**Translation System Improvements**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enhanced the multilingual system with new keys and cleanup:

- **Chat Audio Downloads**: Added ``downloadChatAudio`` key for chat message audio
- **Custom API Description**: Added ``useCustomAPI`` across all 19 languages: "Use a custom openai compatible endpoint."
- **Translation Cleanup**: Removed 5 unused keys (``modelLabel``, ``voiceLabel``, ``languageLabel``, ``quickActions``, ``apiConfigLabel``)
- **Validator Updates**: Enhanced verification scripts to handle translation changes

**Critical Bug Fixes:**

Model Selection System Overhaul
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed fundamental issues with model selection that were causing API mismatches:

**Issue**: Users selected Groq models but system sent requests to Hermes models
**Root Cause**: Modal model dropdown had no HTML ID, causing ``getSelectedModel()`` to fall back to defaults

**Solution**: 
- Added ``id="hermes-model-selection"`` to modal dropdown
- Enhanced debug logging to trace model selection flow
- Fixed model registry to properly store endpoint relationships

**Cache System Enhancement**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fixed refresh models button not working when custom API settings changed:

**Issue**: Clicking refresh didn't fetch new models after enabling custom API
**Root Cause**: Cache key only considered ``VLLM_ENDPOINTS`` array, not custom API configuration

**Solution**:
- Include custom API settings in cache hash key
- Cache now properly invalidates when toggling custom API
- Test case: Checking/unchecking custom API produces different model lists

**Error Handling & Debugging**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added comprehensive error tracking and debugging tools:

- **API Error Details**: Full HTTP status codes and response bodies logged
- **Model Selection Tracing**: Debug messages show exactly which model is selected and why
- **Configuration Verification**: Clear console indicators for custom vs default API usage
- **Max Tokens Logging**: Shows token limits being used for each request type

**Technical Implementation Details:**

**Files Modified:**
- ``src/config.js`` - Central API configuration with ``getAPIConfig()``
- ``src/models.js`` - Enhanced model selection, caching, and max_tokens support  
- ``src/chat.js`` - Dynamic max_tokens for all chat functions
- ``src/translation.js`` - Custom API support with dynamic token limits
- ``src/ui.js`` - Intro generation API integration
- ``src/uncloseai-embed-modal.js`` - Settings UI redesign and model dropdown ID fix
- ``src/uncloseai-modal-*.css`` - Grid layouts and responsive design improvements
- ``src/languages/*.js`` - Translation updates across all 19 language files

**API Call Patching Strategy:**
All API functions now follow this pattern:
```javascript
const apiConfig = await getAPIConfig();
if (apiConfig.isCustom) {
    // Use custom endpoint, API key, and selected model
    apiUrl = `${apiConfig.endpoint}/chat/completions`;
    headers = { "Authorization": `Bearer ${apiConfig.apiKey}` };
    model = apiConfig.model;
} else {
    // Use default Hermes configuration
    apiUrl = `${getSelectedModelEndpoint()}/chat/completions`;
    headers = { "Authorization": `Bearer ${API_KEY}` };
    model = getSelectedModel();
}
```

**Dynamic Max Tokens Implementation:**
```javascript
const maxTokens = getSelectedModelMaxTokens(); // Reads from model registry
// Translation: Could be 70,000 for VLLM or 8,192 for Groq
// Chat: Adapts to whatever the selected model supports
```

**UI Flow Improvements:**
1. User configures custom API (base URL + API key)
2. Clicks "🔄 Refresh Models" → Fetches models from both Hermes + custom endpoint
3. Selects model from combined dropdown (e.g., ``https://api.groq.com/openai/v1-llama-3.1-8b-instant``)
4. All features (chat, translation) automatically use selected custom model

**Deployment Notes:**
- **Backward Compatible**: Existing users continue using Hermes by default
- **Progressive Enhancement**: Custom API is opt-in with fallback protection
- **Cache Management**: Model cache automatically refreshes when configuration changes
- **Cross-Platform**: Works on both modal interface and blog site integration

**Testing Completed:**
- ✅ Custom API integration with Groq, OpenAI endpoints
- ✅ Model selection working across modal and blog interfaces
- ✅ Dynamic max_tokens based on model capabilities (82k for VLLM, 8k for Groq)
- ✅ Cache invalidation when toggling custom API settings
- ✅ Mobile responsive 2-column grid layout
- ✅ Translation key cleanup across all 19 languages

This release transforms the AI chat system from a single-provider solution into a flexible, multi-provider platform while maintaining the clean user experience and adding significant debugging capabilities for troubleshooting.