sameer-saraf-quant-ai/slm-workflow-planner-v8-mlx

SLM Workflow Planner v8 — Context-Contract Planning (MLX LoRA)

Overview

v8 is a Stage 2 enhancement of the SLM Workflow Planner. It extends the v3-best checkpoint with context-contract planning — the ability to make routing decisions based on the required_context and produces_context of ALL nodes in a workflow graph, not just directly connected edges.

This enables three new capabilities:

• Recovery Routing (Backjump): On failure, jump backward to an earlier context-satisfiable node
• Stage Skipping: Skip unnecessary stages when required context is already available (e.g., walk-in customers)
• Non-Adjacent Parallelism: Fork two independent context-satisfiable nodes that aren't connected by fork-edges

Model Details

Property	Value
Base Model	Qwen/Qwen2.5-7B-Instruct
Fine-tune Type	LoRA (MLX format)
LoRA Rank	16
LoRA Scale	2.0
LoRA Dropout	0.02
Tuned Layers	28/32
Trainable Parameters	40.37M (0.53%)
Framework	MLX (Apple Silicon)

Training

Property	Value
Lineage	base(8000) → v2(100) → v3(200) → v3-cont → v3-best → v8(1000)
Resume Checkpoint	v3-best (59.2% on 76-scenario suite)
Training Iterations	1000 (stopped early — val loss converged)
Learning Rate	2e-5 (cosine decay to 1e-6, 100-step warmup)
Batch Size	4 (effective 8 with grad accumulation)
Max Sequence Length	768 tokens
Dataset	696K samples from 150 workflows
Val Loss	0.032 (from 0.272 starting)

Training Data Distribution

Category	Count	%	Description
META	187K	26.9%	Dead-end escalation
NEGATIVE	187K	26.9%	Tier-2 visible but edge chosen ("satisfiable ≠ sensible")
NEXT_EDGE	116K	16.7%	Normal edge progression
NEXT_SKIP 🛡	55K	8.0%	Forward dead-end recovery (Tier-2)
RETRY	36K	5.2%	Edge retry on failure
JOIN	30K	4.3%	Parallel branch merge
NEXT_BACKJUMP 🛡	28K	4.0%	Failure recovery to earlier node (Tier-2)
FORK_EDGE	28K	4.0%	Edge-adjacent fork
FORK_NONADJ 🛡	28K	4.0%	Non-adjacent parallel fork (Tier-2)

🛡 = Protected from downsampling during balancing

Prompt Format

The model uses a tiered prompt with two candidate sections:

Current node: NODE_A (SYSTEM, stage 3)
Outcome: success
Failure type: none

State:
  goal_progress=0.40
  retry_count=0
  ...

Produced context: {ctx_start, intake_data, assessment_score}

Edge candidates (normal path):
  1. NODE_B (AGENT) [processor] → requires: {assessment_score} → produces: {approval}

Context-eligible (off-path, invocable now):
  1. NODE_X (SYSTEM, stage 5, gap=+2) [validator] → requires: {intake_data} ✓ → produces: {validation}

Forkable sets: []
Join-ready: []

What is the best action?

Output format: DECISION_TYPE NODE_ID

• NEXT NODE_B — advance to NODE_B
• FORK NODE_A, NODE_B — parallel fork
• RETRY NODE_A — retry current
• JOIN NODE_A — merge parallel branches
• META — escalate to human

Evaluation Results

Section A: Stratified Test (100 held-out samples)

Category	Exact Accuracy	Type Accuracy
META	20/20 (100%)	20/20 (100%)
NEGATIVE (Tier-2 visible, edge chosen)	5/5 (100%)	5/5 (100%)
SKIP_FORWARD	7/7 (100%)	7/7 (100%)
RETRY	18/20 (90%)	18/20 (90%)
JOIN	16/20 (80%)	16/20 (80%)
FORK (non-adjacent)	12/18 (67%)	14/18 (78%)
NEXT (edge)	5/8 (63%)	8/8 (100%)
TOTAL	83/100 (83%)	88/100 (88%)

Section B: Tier-2 Specific (90 held-out samples)

Category	Exact Accuracy	Type Accuracy
Non-Adjacent Fork	15/15 (100%)	15/15 (100%)
META with Context	15/15 (100%)	15/15 (100%)
Negative Contrast	14/15 (93%)	14/15 (93%)
RETRY with Context	14/15 (93%)	14/15 (93%)
Skip Forward	13/15 (87%)	14/15 (93%)
JOIN with Context	10/15 (67%)	10/15 (67%)
TOTAL	81/90 (90%)	82/90 (91%)

Key Capabilities

1. Context-Contract Reasoning: Evaluates required_context ⊆ produced_keys to identify all invocable nodes
2. Recovery Routing: Backjumps on process/resource failure when no edge retry exists
3. Stage Skipping: Advances to forward context-eligible nodes at dead-ends
4. Non-Adjacent Parallelism: Forks independent context-eligible nodes with different actors
5. Negative Contrast: Learned "satisfiable ≠ sensible" — doesn't take Tier-2 when edge path is correct

Usage (MLX)

from mlx_lm import load, generate

model, tokenizer = load(
    "Qwen/Qwen2.5-7B-Instruct",
    adapter_path="sameer-saraf-quant-ai/slm-workflow-planner-v8-mlx"
)

messages = [
    {"role": "system", "content": "You are a workflow planner..."},
    {"role": "user", "content": "<tiered prompt>"},
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
response = generate(model, tokenizer, prompt=prompt, max_tokens=30)
print(response)  # "NEXT ESTIMATION_AND_APPROVAL"

Ensemble Recommendation

For production use, combine with GPT-4.1 arbiter for the ~10% edge cases (mainly JOIN confusion):

• v8 handles 90%+ of decisions autonomously
• GPT validates uncertain decisions (estimated 5-10% of traffic)

Architecture Context

This adapter is part of the Agentic OS system:

• Temporal handles durable execution and state management
• Neo4j stores workflow graph definitions
• SLM (this model) makes real-time routing decisions
• Guardrails validate SLM output before execution