# AGENTS.md - LLM Context Memory Calculator

## Quick Reference

```bash
# 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:
```javascript
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:
```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