TUK_STDLIB_GOTCHAS.md

Tuk Stdlib Gotchas

Errors I Made

1. DON'T use tensor type - use mat

• ❌ pub zeros(rows: i32, cols: i32) tensor { ... }
• ✅ pub zeros(rows: i32, cols: i32) mat { ... }

2. DON'T use standalone functions - use mat methods

• ❌ result = mat_mul(input, weight)
• ✅ result = input.mul(weight)

3. DON'T use mat_set/mat_get - use .set()/.get() methods

• ❌ mat_set(t, i, j, val)
• ✅ t.set(i, j, val)

4. DON'T use mat_rows/mat_cols - use mat_rows()/mat_cols() standalone

• ✅ rows = mat_rows(t)

5. DON'T use compound assignment +=

• ❌ cache.current_len += seq_len
• ✅ cache.current_len = cache.current_len + seq_len

6. DON'T use and in simple if conditions

• ❌ if idx >= 0 and idx < e.num_embeddings { ... }
• ✅ Use intermediate variable:

  valid = idx < e.num_embeddings
  if valid { ... }
  

7. DON'T use complex field access in method receivers

• The error "field access / method call on complex expressions not yet supported" means you need simpler expressions

8. Use standalone functions NOT methods for NN modules

• ❌ (l: Linear) forward(input: mat) mat { ... }
• ✅ linear_forward(l: Linear, input: mat) mat { ... }

9. Module import: Tuk uses flat files, not nested dirs for imports

• use tukllm → looks for stdlib/tukllm.t
• DON'T use use tukllm.core.config - doesn't work

10. Build system: remove tukllm.t from stdlib root if you have tukllm/ dir

• Both create conflict in build.zig install step

Working Patterns

-- Creating matrix
m = mat(3, 4)
m.set(i, j, val)
val = m.get(i, j)

-- Operations
result = a.mul(b)      -- matrix multiply
result = a.add(b)      -- matrix add
result = a.scale(2.0)  -- scalar multiply

-- Info
rows = mat_rows(m)
cols = mat_cols(m)
sum = mat_sum(m)
mean = mat_mean(m)

-- Imports
use mathlib
use tukllm