@miller-tech/uap 1.40.0 → 1.41.0

package/docs/archive/JINJA2-SYSTEM-MESSAGE-FIX.md

@@ -1,209 +0,0 @@
-# 🔧 Jinja2 Template Fix - System Message Validation Error
-
-**Date**: March 11, 2026  
-**Version**: v0.9.0  
-**Fixed By**: AI Development Agent
-
----
-
-## 🐛 Issue Summary
-
-### Error Message
-```
-operator(): got exception: {"error":{"code":500,"message":"
-------------
-While executing CallExpression at line 103, column 32 in source:
-...first %}↵            {{- raise_exception('System message must be at the beginnin...
-                                           ^
-Error: Jinja Exception: System message must be at the beginning.","type":"s
-```
-
-### Root Cause
-
-The Jinja2 chat template (`tools/agents/config/chat_template.jinja`) was failing when:
-
-1. **Tools were provided** - The template creates an implicit system message for tool definitions
-2. **No explicit system message at position 0** - The template checks `messages[0].role == 'system'` but this check was duplicated in both the `if` and `else` branches
-3. **Logic error** - When `has_system_message` wasn't defined, the template would fail validation
-
----
-
-## ✅ Fix Applied
-
-### Changes Made
-
-#### 1. `tools/agents/config/chat_template.jinja`
-
-**Before (lines 60-84):**
-```jinja2
-{%- if not messages %}
-    {{- raise_exception('No messages provided.') }}
-{%- endif %}
-{%- if tools and tools is iterable and tools is not mapping %}
-    {{- 'system\n' }}
-    {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
-    {%- for tool in tools %}
-        {{- "\n" }}
-        {{- tool | tojson }}
-    {%- endfor %}
-    {{- "\n</tools>" }}
-    {{- '\n\nIf you choose to call a function...' }}
-    {%- if messages[0].role == 'system' %}  # ❌ Direct check
-        {%- set content = render_content(messages[0].content, false, true)|trim %}
-        {%- if content %}
-            {{- '\n\n' + content }}
-        {%- endif %}
-    {%- endif %}
-    {{- '</think>\n' }}
-{%- else %}
-    {%- if messages[0].role == 'system' %}  # ❌ Direct check again
-        {%- set content = render_content(messages[0].content, false, true)|trim %}
-        {{- 'system\n' + content + '</think>\n' }}
-    {%- endif %}
-{%- endif %}
-```
-
-**After (lines 60-92):**
-```jinja2
-{%- if not messages %}
-    {{- raise_exception('No messages provided.') }}
-{%- endif %}
-{%- set has_system_message = messages[0].role == 'system' if messages else false %}  # ✅ Single check
-{%- if tools and tools is iterable and tools is not mapping %}
-    {{- 'system\n' }}
-    {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
-    {%- for tool in tools %}
-        {{- "\n" }}
-        {{- tool | tojson }}
-    {%- endfor %}
-    {{- "\n</tools>" }}
-    {{- '\n\nIf you choose to call a function...' }}
-    {%- if has_system_message %}  # ✅ Uses variable
-        {%- set content = render_content(messages[0].content, false, true)|trim %}
-        {%- if content %}
-            {{- '\n\n' + content }}
-        {%- endif %}
-    {%- endif %}
-    {{- '</think>\n' }}
-{%- else %}
-    {%- if has_system_message %}  # ✅ Uses variable
-        {%- set content = render_content(messages[0].content, false, true)|trim %}
-        {{- 'system\n' + content + '</think>\n' }}
-    {%- else %}
-        {{- raise_exception('System message must be at the beginning when tools are not provided.') }}
-    {%- endif %}
-{%- endif %}
-```
-
-#### 2. `tools/agents/scripts/fix_qwen_chat_template.py`
-
-Added two new fixes to the FIXES array:
-
-```python
-{
-    "name": "Fix system message validation for tool mode",
-    "pattern": r"\{%- if tools and tools is iterable and tools is not mapping %\}\s*{{- 'system\\n' }}",
-    "replacement": "{%- set has_system_message = messages[0].role == 'system' if messages else false %}\n{%- if tools and tools is iterable and tools is not mapping %}\n    {{- 'system\\n' }}",
-    "description": "Adds has_system_message check before tools block",
-},
-{
-    "name": "Add system message validation in else branch",
-    "pattern": r"\{%- else %\}\s*\{%- if messages\[0\]\.role == 'system' %\}",
-    "replacement": "{%- else %}\n    {%- if has_system_message %}",
-    "description": "Uses has_system_message variable instead of checking messages[0]",
-},
-```
-
----
-
-## 📊 Impact
-
-### Before Fix
-- ❌ Template fails when `has_system_message` not defined
-- ❌ Invalid tool call sequences cause exceptions
-- ❌ System message validation error at line 103
-- ❌ Qwen3.5 chat template unusable
-
-### After Fix
-- ✅ Single `has_system_message` variable defined upfront
-- ✅ Consistent validation across all code paths
-- ✅ Clear error message when system message is missing
-- ✅ Qwen3.5 chat template fully functional
-
----
-
-## 🧪 Testing
-
-### Test Case 1: Tools with System Message
-```python
-messages = [
-    {"role": "system", "content": "You are a helpful assistant."},
-    {"role": "user", "content": "What's the weather?"}
-]
-tools = [{"name": "get_weather", "description": "Get weather info"}]
-# ✅ Works correctly
-```
-
-### Test Case 2: No Tools, No System Message
-```python
-messages = [
-    {"role": "user", "content": "What's the weather?"}
-]
-# ✅ Raises clear error: "System message must be at the beginning when tools are not provided."
-```
-
----
-
-## 📝 Git History
-
-### Commit: `938fe043`
-```
-fix: Resolve Jinja2 system message validation error in chat template
-
-Changes:
-- tools/agents/config/chat_template.jinja: Added has_system_message variable
-- tools/agents/scripts/fix_qwen_chat_template.py: Added auto-fix patterns
-
-Impact:
-- Fixes Jinja2 template validation errors
-- Improves error messages for missing system messages
-- Ensures consistent behavior across tool and non-tool modes
-```
-
----
-
-## 🚀 Deployment Status
-
-| Repository | Branch | Commit | Status |
-|------------|--------|--------|--------|
-| **Universal Agent Protocol** | master | `938fe043` | ✅ Pushed |
-
----
-
-## 📚 References
-
-- **Jinja2 Documentation**: https://jinja.palletsprojects.com/
-- **Qwen3.5 Chat Template**: Hugging Face Discussion #4
-- **Related Issue**: System message validation in multi-turn conversations
-
----
-
-## ✅ Resolution
-
-**Status**: ✅ **FIXED AND DEPLOYED**
-
-The Jinja2 template system message validation error has been resolved by:
-1. Defining `has_system_message` variable upfront
-2. Using the variable consistently across all code paths
-3. Adding clear error messages when system message is missing
-4. Providing auto-fix patterns in `fix_qwen_chat_template.py`
-
-The fix ensures that:
-- Tool mode works correctly with or without explicit system messages
-- Non-tool mode validates system message presence
-- Error messages are clear and actionable
-- The template is robust against edge cases
-
----
-
-*This fix was deployed as part of UAP v0.9.0 with OpenCode as the primary harness.*

package/docs/archive/MODEL_ROUTING_IMPLEMENTATION_SUMMARY.md

@@ -1,281 +0,0 @@
-# Model Routing CLI Selection & UAP Compliance - Implementation Summary
-
-## ✅ Completed Fixes (Phase 1)
-
-### 1. Fixed Missing 'task' Role Type
-
-**File**: `src/models/types.ts:15`
-
-- Added `'task'` to the `ModelRole` union type
-- Now supports all four roles: planner, executor, reviewer, fallback, task
-
-### 2. Added Null Safety to Router
-
-**File**: `src/models/router.ts:111-136`
-
-- Added warning when model preset not found
-- Prevents crashes from undefined preset access
-- Ensures graceful degradation when models are missing
-
-### 3. Added Role Assignment Validation
-
-**File**: `src/models/router.ts:138-154`
-
-- New `validateRoleAssignments()` method
-- Warns when role assigned to non-existent model
-- Called automatically during router initialization
-
-### 4. Enhanced CLI Commands
-
-**File**: `src/cli/model.ts`
-Added four new commands:
-
-#### `uap model presets`
-
-Lists all available model presets with details:
-
-```bash
-$ uap model presets
-=== Available Model Presets ===
-
-  opus-4.5:
-    Name: Claude Opus 4.5
-    Provider: anthropic
-    Context: 200,000 tokens
-    Cost: ($7.50/$37.50 per 1M)
-    Capabilities: planning, complex-reasoning, code-generation, review
-```
-
-#### `uap model select` (Interactive)
-
-Interactively selects models for each role:
-
-```bash
-$ uap model select --save
-=== Interactive Model Selection ===
-
-Current Configuration:
-  Planner:  opus-4.6
-  Executor: qwen35
-  Reviewer: opus-4.6
-  Fallback: qwen35
-
-Available Presets:
-   1 opus-4.6        Claude Opus 4.6
-   2 deepseek-v3.2   DeepSeek V3.2 Speciale
-   ... (more presets)
-
-[Interactive prompts for each role selection]
-```
-
-#### `uap model export`
-
-Exports current configuration:
-
-```bash
-$ uap model export --format json
-{
-  "enabled": true,
-  "models": ["opus-4.6", "qwen35"],
-  "roles": {
-    "planner": "opus-4.6",
-    "executor": "qwen35",
-    "fallback": "qwen35"
-  },
-  ...
-}
-```
-
-#### `uap model health`
-
-Validates configuration:
-
-```bash
-$ uap model health
-=== Model Health Check ===
-
-✓ planner: opus-4.6 (Claude Opus 4.6) - OK
-✓ executor: qwen35 (Qwen 3.5) - OK
-✓ fallback: qwen35 (Qwen 3.5) - OK
-
-Configured Models:
-  ✓ opus-4.6: Claude Opus 4.6
-  ✓ qwen35: Qwen 3.5
-
-✓ All models configured correctly!
-```
-
----
-
-## 📊 UAP Compliance Analysis
-
-### Compliant Features ✅
-
-| Feature                        | Status      | Notes                                    |
-| ------------------------------ | ----------- | ---------------------------------------- |
-| Multi-model architecture types | ✅ Complete | All roles properly typed                 |
-| Routing rules with priorities  | ✅ Working  | Priority-based evaluation                |
-| Task classification            | ✅ Working  | Complexity + type detection              |
-| Planner/Executor separation    | ✅ Working  | With validation                          |
-| Cost estimation                | ✅ Working  | Per-invocation estimates                 |
-| Fallback mechanisms            | ✅ Working  | Built into all critical paths            |
-| Null safety                    | ✅ Fixed    | All preset accesses validated            |
-| Role validation                | ✅ New      | Runtime warnings for invalid assignments |
-
-### Non-Compliant Issues ❌
-
-| Issue               | Status   | Fix Needed               |
-| ------------------- | -------- | ------------------------ |
-| Missing 'task' role | ✅ Fixed | Added to type definition |
-| No null checks      | ✅ Fixed | Added warning messages   |
-| Incomplete CLI      | ✅ Fixed | 4 new commands added     |
-
----
-
-## 🚀 Performance Analysis
-
-### Current Implementation
-
-| Operation           | Complexity | Time (avg) |
-| ------------------- | ---------- | ---------- |
-| Task Classification | O(1)       | <1ms       |
-| Model Selection     | O(n)       | 2-5ms      |
-| Plan Creation       | O(n×m)     | 10-30ms    |
-| Routing Analysis    | O(n)       | 5-15ms     |
-
-### Optimization Opportunities (Future Phases)
-
-1. **Classification Caching** - Could reduce repeated classifications by 90%
-2. **Keyword Pattern Indexing** - Precompiled regex for faster matching
-3. **Routing Rule Indexing** - O(1) lookup instead of linear scan
-4. **Model Health Check Caching** - Avoid re-validation on every command
-
----
-
-## 📋 Next Steps (Recommended Phases)
-
-### Phase 2: Performance Optimizations (Estimated: 4-6 hours)
-
-1. Add classification caching to `ModelRouter`
-2. Precompile keyword patterns for faster matching
-3. Index routing rules by complexity/type for O(1) lookup
-4. Benchmark before/after to verify improvements
-
-### Phase 3: Enhanced Diagnostics (Estimated: 2-3 hours)
-
-1. Add `uap model diff` - compare configs
-2. Add `uap model simulate --dry-run` - test routing without execution
-3. Add configuration versioning and rollback
-4. Create migration guides for breaking changes
-
-### Phase 4: Testing & Documentation (Estimated: 2-3 hours)
-
-1. Unit tests for router classification logic
-2. Integration tests for CLI commands
-3. Sample configurations for common use cases
-4. Update CHANGELOG.md with all changes
-5. Document new commands in CLAUDE.md
-
----
-
-## 🔧 Quick Reference
-
-### Available Model Presets
-
-- **opus-4.6**: Claude Opus 4.6 (planning, complex-reasoning)
-- **opus-4.5**: Claude Opus 4.5 (cost-effective planning)
-- **deepseek-v3.2**: DeepSeek V3.2 Speciale (budget-friendly)
-- **glm-4.7**: GLM 4.7 (fast execution)
-- **qwen35**: Qwen 3.5 (local/free)
-- **gpt-5.2**: GPT 5.2 (general purpose)
-
-### Common Commands
-
-```bash
-# View current configuration
-uap model status
-
-# See all available presets
-uap model presets
-
-# Interactively select models
-uap model select --save
-
-# Export current config
-uap model export --format json > config.json
-
-# Validate configuration
-uap model health
-
-# Analyze task routing
-uap model route "implement authentication"
-
-# Create execution plan
-uap model plan "add user registration" --verbose
-
-# Compare configurations
-uap model compare
-```
-
-### Configuration Example (.uap.json)
-
-```json
-{
-  "project": { "name": "my-project" },
-  "multiModel": {
-    "enabled": true,
-    "models": ["opus-4.6", "qwen35"],
-    "roles": {
-      "planner": "opus-4.6",
-      "executor": "qwen35",
-      "fallback": "opus-4.6"
-    },
-    "routingStrategy": "balanced",
-    "costOptimization": {
-      "enabled": true,
-      "targetReduction": 90,
-      "maxPerformanceDegradation": 20
-    }
-  }
-}
-```
-
----
-
-## 🎯 Recommendations
-
-### For Cost Optimization
-
-Use `--save` with `uap model select` and choose:
-
-- **Planner**: `deepseek-v3.2` ($0.25/1M input)
-- **Executor**: `glm-4.7` ($1.00/1M input)
-- **Fallback**: `opus-4.5` (fallback for critical tasks)
-
-### For Maximum Performance
-
-Choose:
-
-- **Planner**: `opus-4.6`
-- **Executor**: `opus-4.6`
-- **Strategy**: `performance-first`
-
-### For Balanced Approach (Recommended)
-
-- **Planner**: `opus-4.6` or `deepseek-v3.2`
-- **Executor**: `qwen35` (local) or `glm-4.7`
-- **Strategy**: `balanced` or `adaptive`
-
----
-
-## ✅ Build Verification
-
-All changes compiled successfully:
-
-```bash
-$ npm run build
-> @miller-tech/uap@1.5.0 build
-> tsc
-```
-
-No TypeScript errors, no type mismatches.