llm_calculator/AGENTS.md

AGENTS.md - LLM Context Memory Calculator

Quick Reference

# Just open index.html in a browser - no build process needed
# or serve with any static file server

Architecture Overview

Pure client-side application - Single HTML file with embedded CSS/JS. No build tools, no frameworks.

index.html
├── css/styles.css          # ~380 lines, retro design
└── js/
    ├── app.js              # Main app, event handling, translations
    └── calculation.js      # Pure calculation functions

Key Facts

Calculation Formula

Memory = context_length × effective_layers × kv_heads × head_dim × (bK + bV) × parallel

where:
- effective_layers = layers / full_attention_interval (if specified)
- bK, bV = quantization sizes per element
- parallel = number of concurrent sequences (default: 1)

Quantization Sizes (bytes per element)

f32: 4.0
f16: 2.0
bf16: 2.0
q8_0: 34/32 = 1.0625
q4_0: 18/32 = 0.5625
q4_1: 20/32 = 0.625
iq4_nl: 18/32 = 0.5625
q5_0: 22/32 = 0.6875
q5_1: 24/32 = 0.75

HuggingFace Config Format

• Expected structure: config.json from https://huggingface.co/{model}/resolve/main/config.json
• Critical: Must use /resolve/main/ endpoint, NOT /blob/main/
• Config may be nested under text_config (e.g., Qwen3.5 models)
• Required fields (check both top-level and text_config):
  • num_hidden_layers
  • num_key_value_heads
  • head_dim (or calculate as hidden_size / num_attention_heads)

Common Pitfalls

1. Config Parsing

• ConfigParser checks BOTH config and config.text_config
• Don't forget to check nested structure for newer models

2. Tooltip Re-initialization

After clearing tooltips with clearAllTooltips(), always call:

updateTooltips();

Otherwise tooltips will be empty.

3. Error Icon Styling

Error icons must have:

• Black background: #000000
• White text: #FFFFFF
• Blue hover: #0000FF
• Tooltip popup must be re-created after language change

4. Optional Fields Without Errors

Fields with default values should NOT show error icons:

• parallel (default: 1)
• model-size (default: 0)
• full-attention (optional)

5. Model Input Error Icon

The hf-model input's error icon is placed differently in HTML:

<input id="hf-model" ...>
<button>...</button>
<span class="error-icon">!</span>

Selector must use #hf-model + .error-icon, not #hf-model ~ .error-icon

File Changes

Adding New Translations

1. Add to translations.ru and translations.en objects
2. Add data-key="key_name" attribute to HTML element
3. Update updateText() if needed

Adding New Input Fields

1. Add HTML element with proper id
2. Add error icon: <span class="error-icon" style="display:none; margin-left: 5px;">!</span>
3. Add to ConfigParser.parse() if used for config parsing
4. Add to showConfigErrors() selector if needed (use + for hf-model)

Testing Checklist

• Config upload works with nested structure (e.g., Qwen3.5)
• HuggingFace fetch works with /resolve/main/ URL
• 404 errors show "Model not found"
• Tooltips persist after config parsing
• Error icons appear for missing required fields
• Error icons don't appear for optional fields
• Language toggle updates all translations including tooltips
• Reset button clears all fields including model name