tribunal-kit 9.2.3 → 9.2.4

package/.agent/skills/transformers-js/references/TEXT_GENERATION.md

@@ -0,0 +1,315 @@
+# Text Generation Guide
+
+Guide to generating text with Transformers.js, including streaming and chat format.
+
+## Table of Contents
+
+1. [Basic Generation](#basic-generation)
+2. [Streaming](#streaming)
+3. [Chat Format](#chat-format)
+4. [Generation Parameters](#generation-parameters)
+5. [Model Selection](#model-selection)
+6. [Best Practices](#best-practices)
+
+## Basic Generation
+
+```javascript
+import { pipeline } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/Qwen2.5-0.5B-Instruct',
+  { dtype: 'q4' }
+);
+
+const result = await generator('Once upon a time', {
+  max_new_tokens: 100,
+  temperature: 0.7,
+});
+
+console.log(result[0].generated_text);
+
+// Clean up when done
+await generator.dispose();
+```
+
+## Streaming
+
+Stream tokens as they're generated for better UX. Once you understand streaming, you can combine it with other features like chat format.
+
+### Node.js
+
+```javascript
+import { pipeline, TextStreamer } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/Qwen2.5-0.5B-Instruct',
+  { dtype: 'q4' }
+);
+
+const streamer = new TextStreamer(generator.tokenizer, {
+  skip_prompt: true,
+  skip_special_tokens: true,
+  callback_function: (token) => {
+    process.stdout.write(token);
+  },
+});
+
+await generator('Tell me a story', {
+  max_new_tokens: 200,
+  temperature: 0.7,
+  streamer,
+});
+```
+
+### Browser
+
+```html
+<!DOCTYPE html>
+<html>
+<body>
+  <textarea id="prompt" placeholder="Enter prompt..."></textarea>
+  <button onclick="generate()">Generate</button>
+  <div id="output"></div>
+
+  <script type="module">
+    import { pipeline, TextStreamer } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@4';
+    
+    const generator = await pipeline(
+      'text-generation',
+      'onnx-community/Qwen2.5-0.5B-Instruct',
+      { dtype: 'q4' }
+    );
+    
+    window.generate = async function() {
+      const prompt = document.getElementById('prompt').value;
+      const outputDiv = document.getElementById('output');
+      outputDiv.textContent = '';
+      
+      const streamer = new TextStreamer(generator.tokenizer, {
+        skip_prompt: true,
+        skip_special_tokens: true,
+        callback_function: (token) => {
+          outputDiv.textContent += token;
+        },
+      });
+      
+      await generator(prompt, {
+        max_new_tokens: 200,
+        temperature: 0.7,
+        streamer,
+      });
+    };
+  </script>
+</body>
+</html>
+```
+
+### React
+
+```jsx
+import { useState, useRef, useEffect } from 'react';
+import { pipeline, TextStreamer } from '@huggingface/transformers';
+
+function StreamingGenerator() {
+  const generatorRef = useRef(null);
+  const [output, setOutput] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleGenerate = async (prompt) => {
+    if (!prompt) return;
+    
+    setLoading(true);
+    setOutput('');
+    
+    // Load model on first generate
+    if (!generatorRef.current) {
+      generatorRef.current = await pipeline(
+        'text-generation',
+        'onnx-community/Qwen2.5-0.5B-Instruct',
+        { dtype: 'q4' }
+      );
+    }
+    
+    const streamer = new TextStreamer(generatorRef.current.tokenizer, {
+      skip_prompt: true,
+      skip_special_tokens: true,
+      callback_function: (token) => {
+        setOutput((prev) => prev + token);
+      },
+    });
+
+    await generatorRef.current(prompt, {
+      max_new_tokens: 200,
+      temperature: 0.7,
+      streamer,
+    });
+    
+    setLoading(false);
+  };
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (generatorRef.current) {
+        generatorRef.current.dispose();
+      }
+    };
+  }, []);
+
+  return (
+    <div>
+      <button onClick={() => handleGenerate('Tell me a story')} disabled={loading}>
+        {loading ? 'Generating...' : 'Generate'}
+      </button>
+      <div>{output}</div>
+    </div>
+  );
+}
+```
+
+## Chat Format
+
+Use structured messages for conversations. Works with both basic generation and streaming (just add `streamer` parameter).
+
+### Single Turn
+
+```javascript
+import { pipeline } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/Qwen2.5-0.5B-Instruct',
+  { dtype: 'q4' }
+);
+
+const messages = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'How do I create an async function?' }
+];
+
+const result = await generator(messages, {
+  max_new_tokens: 256,
+  temperature: 0.7,
+});
+
+console.log(result[0].generated_text);
+```
+
+### Multi-turn Conversation
+
+```javascript
+const conversation = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'What is JavaScript?' },
+  { role: 'assistant', content: 'JavaScript is a programming language...' },
+  { role: 'user', content: 'Can you show an example?' }
+];
+
+const result = await generator(conversation, {
+  max_new_tokens: 200,
+  temperature: 0.7,
+});
+
+// To add streaming, just pass a streamer:
+// streamer: new TextStreamer(generator.tokenizer, {...})
+```
+
+## Generation Parameters
+
+### Common Parameters
+
+```javascript
+await generator(prompt, {
+  // Token limits
+  max_new_tokens: 512,        // Maximum tokens to generate
+  min_new_tokens: 0,          // Minimum tokens to generate
+  
+  // Sampling
+  temperature: 0.7,           // Randomness (0.0-2.0)
+  top_k: 50,                  // Consider top K tokens
+  top_p: 0.95,                // Nucleus sampling
+  do_sample: true,            // Use random sampling (false = always pick most likely token)
+  
+  // Repetition control
+  repetition_penalty: 1.0,    // Penalty for repeating (1.0 = no penalty)
+  no_repeat_ngram_size: 0,    // Prevent repeating n-grams
+  
+  // Streaming
+  streamer: streamer,         // TextStreamer instance
+});
+```
+
+### Parameter Effects
+
+**Temperature:**
+- Low (0.1-0.5): More focused and deterministic
+- Medium (0.6-0.9): Balanced creativity and coherence
+- High (1.0-2.0): More creative and random
+
+```javascript
+// Focused output
+await generator(prompt, { temperature: 0.3, max_new_tokens: 100 });
+
+// Creative output
+await generator(prompt, { temperature: 1.2, max_new_tokens: 100 });
+```
+
+**Sampling Methods:**
+
+```javascript
+// Greedy (deterministic)
+await generator(prompt, { 
+  do_sample: false,
+  max_new_tokens: 100 
+});
+
+// Top-k sampling
+await generator(prompt, { 
+  top_k: 50,
+  temperature: 0.7,
+  max_new_tokens: 100 
+});
+
+// Top-p (nucleus) sampling
+await generator(prompt, { 
+  top_p: 0.95,
+  temperature: 0.7,
+  max_new_tokens: 100 
+});
+```
+
+## Model Selection
+
+Browse available text generation models on Hugging Face Hub:
+
+**https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending**
+
+### Selection Tips
+
+- **Small models (< 1B params)**: Fast, browser-friendly, use `dtype: 'q4'`
+- **Medium models (1-3B params)**: Balanced quality/speed, use `dtype: 'q4'` or `fp16`
+- **Large models (> 3B params)**: High quality, slower, best for Node.js with `dtype: 'fp16'`
+
+Check model cards for:
+- Parameter count and model size
+- Supported languages
+- Benchmark scores
+- License restrictions
+
+## Best Practices
+
+1. **Model Size**: Use quantized models (`q4`) for browsers, larger models (`fp16`) for servers
+2. **Streaming**: Use streaming for better UX - shows progress and feels responsive
+3. **Token Limits**: Set `max_new_tokens` to prevent runaway generation
+4. **Temperature**: Tune based on use case (creative: 0.8-1.2, factual: 0.3-0.7)
+5. **Memory**: Always call `dispose()` when done
+6. **Caching**: Load model once, reuse for multiple requests
+
+## Related Documentation
+
+- [Pipeline Options](./PIPELINE_OPTIONS.md) - Configure pipeline loading
+- [Configuration Reference](./CONFIGURATION.md) - Environment settings
+- [Code Examples](./EXAMPLES.md) - More examples for different runtimes
+- [Main Skill Guide](../SKILL.md) - Getting started guide

package/.agent/skills/tribunal-instincts-memory/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: tribunal-instincts-memory
+description: "Use when extracting lessons from session logs, resolving repeated failures, creating persistent context, and validating AI memory constraints."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - fabel-protocol
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/memory_archivist.js
+---
+
+# Tribunal Instincts (Continuous Memory)
+
+## Overview
+Tribunal Instincts allows the agent harness to learn from its past mistakes and successful resolutions without blowing up the context window. It extracts concrete lessons from the Event Log and injects them selectively into future sessions.
+
+## Memory Lifecycle
+1. **Candidate Extraction**: The `memory-archivist` scans the durable JSONL session log for anomalies, repeated errors, or successful recoveries.
+2. **Evidence Validation**: A memory CANNOT be created without a specific Event ID or stack trace proving it happened. Subjective complaints are dropped.
+3. **Storage**: Approved lessons are saved to `instincts.json` under specific scopes (e.g., `database`, `ui`).
+4. **Context Injection**: During workflow initialization, `context_broker.js` reads only the instincts relevant to the current task.
+
+## Rules of Instinct Retrieval
+- **Token Budget**: Never inject more than 5 instincts at a time.
+- **Conflict Resolution**: If a newer instinct contradicts an older one, the older one is archived.
+- **System Rule Supremacy**: Instincts can NEVER override hardcoded system rules (e.g., `GEMINI.md`). They serve only as technical implementation hints.
+
+## Hallucination Traps
+- ❌ Trusting a memory that says "Always use library X" without checking `package.json`.
+- ❌ Creating an instinct for a typo. (Only systemic or architectural lessons deserve permanent memory).

package/.agent/skills/trl-training/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: trl-training
+description: Train and fine-tune transformer language models using TRL (Transformers Reinforcement Learning). Supports SFT, DPO, GRPO, KTO, RLOO and Reward Model training via CLI commands.
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+  author: huggingface
+  commands: trl sft, trl dpo, trl grpo, trl kto, trl rloo, trl reward
+  categories: machine-learning, llm-training, reinforcement-learning
+  tags: rlhf, supervised-fine-tuning, dpo, grpo, huggingface, transformers
+  documentation: https://huggingface.co/docs/trl/en/clis
+---
+
+# TRL Training Skill
+
+You are an expert at using the TRL (Transformers Reinforcement Learning) library to train and fine-tune large language models.
+
+## Overview
+
+TRL provides CLI commands for post-training foundation models using state-of-the-art techniques:
+
+- **SFT** (Supervised Fine-Tuning): Fine-tune models on instruction-following or conversational datasets
+- **DPO** (Direct Preference Optimization): Align models using preference data
+- **GRPO** (Group Relative Policy Optimization): Train models by ranking multiple sampled outputs relative to each other and optimizing based on their comparative rewards.
+- **RLOO** (Reinforce Leave One Out): Online RL training with generation-based rewards
+- **Reward Model Training**: Train reward models for RLHF
+
+TRL is built on top of Hugging Face Transformers and Accelerate, providing seamless integration with the Hugging Face ecosystem.
+
+## Core Commands
+
+### trl sft - Supervised Fine-Tuning
+
+Fine-tune language models on instruction-following or conversational datasets.
+
+**Full training:**
+
+```bash
+trl sft \
+  --model_name_or_path Qwen/Qwen2-0.5B \
+  --dataset_name trl-lib/Capybara \
+  --learning_rate 2.0e-5 \
+  --num_train_epochs 1 \
+  --packing \
+  --per_device_train_batch_size 2 \
+  --gradient_accumulation_steps 8 \
+  --eos_token '<|im_end|>' \
+  --eval_strategy steps \
+  --eval_steps 100 \
+  --output_dir Qwen2-0.5B-SFT \
+  --push_to_hub
+```
+
+**Train with LoRA adapters:**
+
+```bash
+trl sft \
+  --model_name_or_path Qwen/Qwen2-0.5B \
+  --dataset_name trl-lib/Capybara \
+  --learning_rate 2.0e-4 \
+  --num_train_epochs 1 \
+  --packing \
+  --per_device_train_batch_size 2 \
+  --gradient_accumulation_steps 8 \
+  --eos_token '<|im_end|>' \
+  --eval_strategy steps \
+  --eval_steps 100 \
+  --use_peft \
+  --lora_r 32 \
+  --lora_alpha 16 \
+  --output_dir Qwen2-0.5B-SFT \
+  --push_to_hub
+```
+
+### trl dpo - Direct Preference Optimization
+
+Align models using preference data (chosen/rejected pairs).
+
+**Full training:**
+
+```bash
+trl dpo \
+  --dataset_name trl-lib/ultrafeedback_binarized \
+  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
+  --learning_rate 5.0e-7 \
+  --num_train_epochs 1 \
+  --per_device_train_batch_size 2 \
+  --max_steps 1000 \
+  --gradient_accumulation_steps 8 \
+  --eval_strategy steps \
+  --eval_steps 50 \
+  --output_dir Qwen2-0.5B-DPO \
+  --no_remove_unused_columns
+```
+
+**Train with LoRA adapters:**
+
+```bash
+trl dpo \
+  --dataset_name trl-lib/ultrafeedback_binarized \
+  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
+  --learning_rate 5.0e-6 \
+  --num_train_epochs 1 \
+  --per_device_train_batch_size 2 \
+  --max_steps 1000 \
+  --gradient_accumulation_steps 8 \
+  --eval_strategy steps \
+  --eval_steps 50 \
+  --output_dir Qwen2-0.5B-DPO \
+  --no_remove_unused_columns \
+  --use_peft \
+  --lora_r 32 \
+  --lora_alpha 16
+```
+
+### trl grpo - Group Relative Policy Optimization
+
+Train models using reward functions or LLM-as-a-judge for evaluating generations and providing rewards.
+
+**Basic usage:**
+
+```bash
+trl grpo \
+  --model_name_or_path Qwen/Qwen2.5-0.5B \
+  --dataset_name trl-lib/gsm8k \
+  --reward_funcs accuracy_reward \
+  --output_dir Qwen2-0.5B-GRPO \
+  --push_to_hub
+```
+
+### trl rloo - Reinforce Leave One Out
+
+Online RL training where the model generates text and receives rewards based on custom criteria.
+
+**Basic usage:**
+
+```bash
+trl rloo \
+  --model_name_or_path Qwen/Qwen2.5-0.5B \
+  --dataset_name trl-lib/tldr \
+  --reward_model_name_or_path sentiment-analysis:nlptown/bert-base-multilingual-uncased-sentiment \
+  --output_dir Qwen2-0.5B-RLOO \
+  --push_to_hub
+```
+
+### trl reward - Reward Model Training
+
+Train a reward model to score text quality for RLHF.
+
+**Full training:**
+
+```bash
+trl reward \
+  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
+  --dataset_name trl-lib/ultrafeedback_binarized \
+  --output_dir Qwen2-0.5B-Reward \
+  --per_device_train_batch_size 8 \
+  --num_train_epochs 1 \
+  --learning_rate 1.0e-5 \
+  --eval_strategy steps \
+  --eval_steps 50 \
+  --max_length 2048
+```
+
+**Train with LoRA adapters:**
+
+```bash
+trl reward \
+  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
+  --dataset_name trl-lib/ultrafeedback_binarized \
+  --output_dir Qwen2-0.5B-Reward-LoRA \
+  --per_device_train_batch_size 8 \
+  --num_train_epochs 1 \
+  --learning_rate 1.0e-4 \
+  --eval_strategy steps \
+  --eval_steps 50 \
+  --max_length 2048 \
+  --use_peft \
+  --lora_task_type SEQ_CLS \
+  --lora_r 32 \
+  --lora_alpha 16
+```
+
+## Configuration Files
+
+TRL supports YAML configuration files for reproducible training. All CLI arguments can be specified in a config file.
+
+**Example config (sft_config.yaml):**
+
+```yaml
+model_name_or_path: Qwen/Qwen2.5-0.5B
+dataset_name: trl-lib/Capybara
+learning_rate: 2.0e-5
+num_train_epochs: 1
+per_device_train_batch_size: 8
+gradient_accumulation_steps: 2
+output_dir: ./sft_output
+use_peft: true
+lora_r: 16
+lora_alpha: 16
+report_to: trackio
+```
+
+**Launch with config:**
+
+```bash
+trl sft --config sft_config.yaml
+```
+
+**Override config values:**
+
+```bash
+trl sft --config sft_config.yaml --learning_rate 1.0e-5
+```
+
+## Distributed Training
+
+TRL integrates with Accelerate for multi-GPU and multi-node training.
+
+**Multi-GPU training:**
+
+```bash
+trl sft \
+  --config sft_config.yaml \
+  --num_processes 4
+```
+
+**Use predefined Accelerate configs:**
+
+TRL provides predefined configs: `single_gpu`, `multi_gpu`, `fsdp1`, `fsdp2`, `zero1`, `zero2`, `zero3`
+
+```bash
+trl sft \
+  --config sft_config.yaml \
+  --accelerate_config zero2
+```
+
+**Custom Accelerate config:**
+
+```bash
+# Generate custom config
+accelerate config
+
+# Use custom config
+trl sft --config sft_config.yaml --config_file ~/.cache/huggingface/accelerate/default_config.yaml
+```
+
+**Fully Sharded Data Parallel (FSDP):**
+
+```bash
+trl sft --config sft_config.yaml --accelerate_config fsdp2
+```
+
+**DeepSpeed ZeRO:**
+
+```bash
+trl sft --config sft_config.yaml --accelerate_config zero3
+```
+
+## Troubleshooting
+
+### CUDA Out of Memory
+
+- Reduce `--per_device_train_batch_size` and increase `--gradient_accumulation_steps`
+- Enable `--use_peft` for LoRA training
+- Use `--gradient_checkpointing` to save memory
+- Try smaller model or longer sequence truncation
+
+### Dataset Loading Issues
+
+- Verify dataset exists: check Hugging Face Hub or local path
+- Check dataset format matches expected columns
+- Use `--dataset_config` for multi-config datasets
+- Inspect dataset: `from datasets import load_dataset; ds = load_dataset(name)`
+
+### Model Loading Issues
+
+- Verify model exists on Hugging Face Hub
+- Check if gated model requires authentication: `hf auth login`
+- For local models, provide absolute path
+- Ensure sufficient disk space and memory
+
+### Slow Training
+
+- Enable dataset `--packing` for short sequences
+- Use larger `--per_device_train_batch_size` if memory allows
+- Enable `--tf32` for faster computation on Ampere GPUs
+- Use `--bf16` on supported hardware
+- Consider multi-GPU training with `--num_processes`
+
+### Generation Issues (GRPO/RLOO)
+
+- Check prompt format in dataset
+- Adjust `--temperature` and `--top_p` for generation
+- Verify the reward function (for GRPO/RLOO)
+
+## Additional Resources
+
+- **Documentation**: https://huggingface.co/docs/trl
+- **GitHub**: https://github.com/huggingface/trl
+- **Examples**: https://github.com/huggingface/trl/tree/main/examples
+
+## Best Practices
+
+1. **Start with SFT**: Always fine-tune base models with SFT before preference alignment
+2. **Use LoRA for efficiency**: Enable `--use_peft` for faster training and lower memory
+3. **Monitor training**: Use `--report_to trackio` (or `--report_to wandb` or `--report_to tensorboard`) for tracking
+4. **Save checkpoints**: TRL automatically saves checkpoints in `--output_dir`
+5. **Test on small datasets first**: Verify pipeline works before full training
+6. **Use configuration files**: Create YAML configs for reproducibility
+7. **Leverage Accelerate**: Use multi-GPU training for faster iteration
+
+When helping users with TRL:
+- Always check which training method is appropriate for their use case
+- Verify dataset format matches the expected schema
+- Recommend starting with smaller models for testing
+- Suggest LoRA for resource-constrained environments
+- Point to specific documentation sections for advanced features

package/.agent/workflows/assimilate.md

@@ -0,0 +1,21 @@
+---
+name: assimilate
+description: "Trigger the learning pipeline to extract, validate, and store Tribunal Instincts."
+version: 1.0.0
+---
+
+# ASSIMILATE (LEARNING PIPELINE)
+
+## Invocation
+`/assimilate` or `/learn`
+
+## Behavior
+Instead of learning in real-time and bloating the execution path, learning is an offline batch job.
+
+1. **Extraction**: Invokes the `memory_archivist.js` which reads the most recent session logs.
+2. **Analysis**: Searches for repeated errors, test failures, and ultimate successful fixes.
+3. **Validation**: Converts successful fixes into candidate "Tribunal Instincts".
+4. **Storage**: Saves the verified evidence-backed instinct into `instincts.json` where `context_broker.js` can retrieve it for future related tasks.
+
+## Limits
+Do not trigger this workflow automatically after every prompt. Use it specifically after a long debugging session or a complex architectural setup to persist the hard-earned lessons.

package/.agent/workflows/audit.md

@@ -165,3 +165,8 @@ No files are modified without explicit approval.
 | Audit clean                  | → `/deploy` if preparing for release            |
 
 ---
+
+
+## Harness vs Application Auditing
+
+The `/audit` command now explicitly distinguishes between Application Security (OWASP, SQLi) and Harness Security (AgentShield prompt injection, MCP configuration risks).

package/.agent/workflows/generate.md

@@ -209,3 +209,8 @@ Write to disk?  Y = approve | N = discard | R = revise with feedback
 /generate a GSAP ScrollTrigger timeline with useGSAP React hook
 /generate an OpenAI structured output call with Zod schema validation
 ```
+
+
+## Brain-Hands Separation & Durable Logging
+
+During code generation, the model (Brain) issues tool requests, and the harness (Hands) executes them. Every tool execution is recorded in the durable log. Verification must complete before Human Gate approval.