113 lines
3.3 KiB
Markdown
113 lines
3.3 KiB
Markdown
# 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
|