{ "pack_id": "coconut-latent-and-thought-budget-routing", "title": "Coconut latent and thought budget routing", "version": "0.1.0", "summary": "A collection of nouns and verbs for routing reasoning tasks across four compute regimes, compressing verbose multi-turn traces into continuous latent state plus invariant checkpoints and halting repetitive overthinking cycles.", "dependencies": [ "configuration-grids-and-bounds", "cost-optimization", "wiring-and-conformance-checks" ], "boundaries": [ "AdaptiveReasoningBudgetRouter maps task complexity, Shannon ambiguity entropy and token or latency caps across zero_step_direct, fast_sketch, compressed_state_checkpoint and full_deliberative_verify.", "LatentStateSketchCompressor preserves binding constraints, open obligations and 64-character SHA-256 digests while compressing verbose reasoning traces by more than 3x alongside normalized continuous latent state vectors.", "OverthinkingLoopDetector halts cyclic paraphrase steps when latent-vector cosine or shingle overlap exceeds grid thresholds with zero new invariants.", "Importing the pack writes nothing, enqueues nothing and installs no code." ], "nouns": [ { "slug": "pack", "category": "noun.skill_pack", "role": "pack", "title": "A collection of nouns and verbs for routing reasoning tasks across four compute regimes, compressing verbose multi-turn traces into continuous latent state plus invariant checkpoints and halting repetitive overthinking cycles", "value": { "lets_workers": "Route tasks across zero_step_direct, fast_sketch, compressed_state_checkpoint and full_deliberative_verify regimes using complexity and ambiguity entropy bounds, compress verbose multi-turn reasoning traces into compact typed invariant + continuous latent state checkpoints (>3x token reduction) and terminate repetitive overthinking loops.", "flow": [ { "verb": { "$verb": "coconut-latent-and-thought-budget-routing.route-adaptive-reasoning-budget" }, "when": "Assign tasks to one of four compute and reasoning regimes under grid-clamped token and latency budgets." }, { "verb": { "$verb": "coconut-latent-and-thought-budget-routing.compress-latent-checkpoint-and-detect-loops" }, "when": "Compress verbose multi-turn reasoning traces into invariant + continuous latent checkpoints and detect stagnant paraphrase cycles." }, { "verb": { "$verb": "coconut-latent-and-thought-budget-routing.verify-invariant-recall-and-ast-gate" }, "when": "Independently verify >3x compression, 100% invariant/digest recall, loop-halt accuracy and ZeroHardcodedValuesAstGate conformance." } ], "guardrails": [ { "$pin": "guardrail.lossless-invariant-and-digest-checkpointing" }, { "$pin": "guardrail.grid-clamped-thought-budget-and-loop-halt" } ], "tool": { "$pin": "tool.thought-budget-routing" }, "worked_example": "Five synthetic tasks routed across all 4 compute regimes (55% token savings and latency-clamped checkpoint downshift), 6.15x multi-turn trace compression with 1.0 recall on constraints, open obligations and SHA-256 hashes, plus step-3 overthinking loop termination in test_thought_budget_routing.py." }, "relations": [ [ "requires_noun", "guardrail.lossless-invariant-and-digest-checkpointing" ], [ "requires_noun", "guardrail.grid-clamped-thought-budget-and-loop-halt" ], [ "requires_noun", "spec.coconut-latent-and-budget-grid" ], [ "requires_noun", "rules.regime-routing-and-stagnation-halt" ], [ "requires_noun", "tool.thought-budget-routing" ], [ "requires_noun", "template.thought-budget-routing-receipt" ] ] }, { "slug": "guardrail.lossless-invariant-and-digest-checkpointing", "category": "noun.skill_pack", "role": "guardrail", "title": "Guardrail: reasoning trace compression must retain 100% of binding constraints, open obligations and verified SHA-256 digests", "category_reason": "Prevents state drift or dropped safety invariants when replacing verbose prose traces with compact latent checkpoints.", "value": { "rule": "LatentStateSketchCompressor sheds filler prose above the 3x compression target only while preserving every binding constraint, unresolved obligation and 64-character verified SHA-256 digest intact.", "how_it_is_checked": "LatentStateSketchCompressor.compress_trace evaluates exact recall against ground-truth constraints, unresolved obligations and SHA-256 digests." } }, { "slug": "guardrail.grid-clamped-thought-budget-and-loop-halt", "category": "noun.skill_pack", "role": "guardrail", "title": "Guardrail: reasoning token allocations, latency ceilings and loop-halt thresholds resolve strictly from default_grid_spec.json", "category_reason": "Prevents runaway deliberation budgets and eliminates inline magic numbers in routing and loop-detection logic.", "value": { "rule": "AdaptiveReasoningBudgetRouter clamps reasoning regimes to task token and latency ceilings, OverthinkingLoopDetector halts consecutive invariant-free paraphrase cycles and ZeroHardcodedValuesAstGate rejects inline magic literals.", "how_it_is_checked": "test_thought_budget_routing.py verifies 4-regime routing, latency downshifting, cyclic loop halting without productive false positives and zero AST magic-literal violations." } }, { "slug": "spec.coconut-latent-and-budget-grid", "category": "noun.benchmark_suite", "role": "spec", "title": "Specification: 4-regime adaptive thought-budget router, continuous latent state checkpointing and overthinking loop detector", "category_reason": "Defines regime boundaries, normalized continuous latent sketch projections, invariant checkpoint fields and stagnation predicates.", "value": { "structures": [ "AdaptiveReasoningBudgetRouter", "LatentStateSketchCompressor", "OverthinkingLoopDetector" ], "compute_regimes": [ "zero_step_direct", "fast_sketch", "compressed_state_checkpoint", "full_deliberative_verify" ], "min_compression_ratio": 3.0, "preserved_checkpoint_fields": [ "state_facts", "binding_constraints", "open_obligations", "verified_hashes", "latent_state_vector" ] } }, { "slug": "rules.regime-routing-and-stagnation-halt", "category": "noun.reflex_procedure", "role": "rules", "title": "Deterministic ambiguity-entropy regime selection, signed feature-hash latent sketching and loop stagnation rules", "category_reason": "Zero-model procedure computing task routing regimes, compact state checkpoints and early-halt triggers.", "value": { "ambiguity_entropy_bits": "-sum(p_i * log2(p_i))", "loop_stagnation_predicate": "(max_latent_cosine >= loop_cosine_threshold or max_shingle_jaccard >= loop_shingle_jaccard_threshold) and new_invariants == 0", "model_calls": 0 } }, { "slug": "tool.thought-budget-routing", "category": "noun.code_node", "role": "tool_card", "title": "Tool card: standard-library AdaptiveReasoningBudgetRouter, LatentStateSketchCompressor and OverthinkingLoopDetector", "category_reason": "Tested Python 3.10+ standard-library package pinned by path and SHA-256.", "value": { "name": "coconut latent and thought budget routing", "code": { "$code": "coconut-latent-and-thought-budget-routing" }, "runtime": "Python 3.10 or later, standard library only.", "commands": [ "python3 -m thought_budget_routing --bundle BUNDLE.json" ], "does": [ "Routes tasks across 4 compute/reasoning regimes using complexity features, Shannon ambiguity entropy and token/latency caps.", "Compresses verbose multi-turn reasoning traces by >3x into typed invariant checkpoints and L2-normalized continuous latent state vectors.", "Detects repetitive overthinking cycles via latent cosine similarity and shingle overlap under ZeroHardcodedValuesAstGate." ], "does_not": [ "Perform network I/O, invoke external model APIs or embed inline magic numbers." ], "code_license": "MIT" }, "relations": [ [ "verifies", "spec.coconut-latent-and-budget-grid" ] ] }, { "slug": "template.thought-budget-routing-receipt", "category": "noun.scene_recipe", "role": "template", "title": "Template: 4-regime thought-budget routing, latent checkpoint compression and overthinking loop receipt", "value": { "describes": "a deterministic receipt of 4-regime adaptive thought-budget routing, >3x multi-turn invariant checkpoint compression and overthinking loop early-halt metrics", "schema": { "type": "object", "additionalProperties": false, "required": [ "task_regimes", "budget_clamped_tasks", "routed_total_tokens", "token_savings_fraction", "raw_trace_tokens", "compressed_checkpoint_tokens", "compression_ratio", "meets_compression_target", "binding_constraint_recall", "open_obligation_recall", "verified_hash_recall", "latent_vector_dims", "overthinking_loop_detected", "overthinking_trigger_step", "overthinking_tokens_saved", "productive_trace_false_loop" ], "properties": { "task_regimes": { "type": "object", "additionalProperties": false, "required": [ "schema_key_lookup", "single_hop_summary", "multi_turn_state_handoff", "proof_obligation_verify", "tight_latency_checkpoint" ], "properties": { "schema_key_lookup": { "type": "string" }, "single_hop_summary": { "type": "string" }, "multi_turn_state_handoff": { "type": "string" }, "proof_obligation_verify": { "type": "string" }, "tight_latency_checkpoint": { "type": "string" } } }, "budget_clamped_tasks": { "type": "array", "items": { "type": "string" } }, "routed_total_tokens": { "type": "integer", "minimum": 0 }, "token_savings_fraction": { "type": "number", "minimum": 0.0, "maximum": 1.0 }, "raw_trace_tokens": { "type": "integer", "minimum": 1 }, "compressed_checkpoint_tokens": { "type": "integer", "minimum": 1 }, "compression_ratio": { "type": "number", "minimum": 1.0 }, "meets_compression_target": { "type": "boolean" }, "binding_constraint_recall": { "type": "number", "minimum": 0.0, "maximum": 1.0 }, "open_obligation_recall": { "type": "number", "minimum": 0.0, "maximum": 1.0 }, "verified_hash_recall": { "type": "number", "minimum": 0.0, "maximum": 1.0 }, "latent_vector_dims": { "type": "integer", "minimum": 8 }, "overthinking_loop_detected": { "type": "boolean" }, "overthinking_trigger_step": { "type": "integer", "minimum": -1 }, "overthinking_tokens_saved": { "type": "integer", "minimum": 0 }, "productive_trace_false_loop": { "type": "boolean" } } }, "example": { "task_regimes": { "schema_key_lookup": "zero_step_direct", "single_hop_summary": "fast_sketch", "multi_turn_state_handoff": "compressed_state_checkpoint", "proof_obligation_verify": "full_deliberative_verify", "tight_latency_checkpoint": "compressed_state_checkpoint" }, "budget_clamped_tasks": [ "tight_latency_checkpoint" ], "routed_total_tokens": 2304, "token_savings_fraction": 0.55, "raw_trace_tokens": 123, "compressed_checkpoint_tokens": 20, "compression_ratio": 6.15, "meets_compression_target": true, "binding_constraint_recall": 1.0, "open_obligation_recall": 1.0, "verified_hash_recall": 1.0, "latent_vector_dims": 16, "overthinking_loop_detected": true, "overthinking_trigger_step": 3, "overthinking_tokens_saved": 23, "productive_trace_false_loop": false } } }, { "slug": "example.thought-budget-routing-bundle", "category": "noun.eval_run", "role": "example", "synthetic": true, "title": "Worked example input: five heterogeneous tasks, verbose 3-turn reasoning trace and cyclic paraphrase trace", "category_reason": "Synthetic fixture recomputed by test_thought_budget_routing.py.", "value": { "regime": "balanced_checkpoint", "tasks": [ { "id": "schema_key_lookup", "dependency_depth": 0, "branching_factor": 1, "ambiguity_distribution": [ 1.0, 0.0 ], "constraint_count": 0 }, { "id": "single_hop_summary", "dependency_depth": 2, "branching_factor": 3, "ambiguity_distribution": [ 0.7, 0.3 ], "constraint_count": 2 }, { "id": "multi_turn_state_handoff", "dependency_depth": 5, "branching_factor": 5, "ambiguity_distribution": [ 0.4, 0.35, 0.25 ], "constraint_count": 5, "multi_turn_state_carry": true }, { "id": "proof_obligation_verify", "dependency_depth": 8, "branching_factor": 7, "ambiguity_distribution": [ 0.25, 0.25, 0.25, 0.25 ], "constraint_count": 7, "requires_formal_proof": true }, { "id": "tight_latency_checkpoint", "dependency_depth": 8, "branching_factor": 7, "ambiguity_distribution": [ 0.25, 0.25, 0.25, 0.25 ], "constraint_count": 7, "requires_formal_proof": true, "latency_budget_ms": 650 } ], "verbose_trace": [ { "thought": "Let us carefully examine the initial request and reflect thoroughly on what we are trying to accomplish here before jumping ahead. Basically we observe epoch=4 and quorum_size >= 3 while reviewing the upstream manifest digest 1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f. CONSTRAINT: egress_mode == disabled; OBLIGATION: verify_replica_ack; OBLIGATION: check_rollback_cursor. Thinking again about whether everything aligns." }, { "thought": "Continuing our careful deliberation and rechecking our earlier notes from the first turn so we do not miss anything obvious. Meanwhile replica acknowledgement finished cleanly, RESOLVED: verify_replica_ack, and we also pinned snapshot digest 9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c with retry_ceiling <= 2 and active_region=us_east." }, { "thought": "Summarizing and pondering the overall multi-turn reasoning trajectory one more time to make sure our understanding remains coherent while keeping the open cursor check front of mind before emitting the next state transition." } ], "ground_truth_invariants": { "binding_constraints": [ "egress_mode == disabled", "quorum_size >= 3", "retry_ceiling <= 2" ], "open_obligations": [ "check_rollback_cursor" ], "verified_hashes": [ "1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f", "9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c9c" ] }, "looping_trace": [ "Initialize verifier state schema_rev=2 and CONSTRAINT: max_batch <= 16.", "Maybe we should recheck schema_rev and max_batch ordering across candidate batches again.", "Wait let us reconsider schema_rev and max_batch ordering across candidate batches carefully.", "Thinking again, we should recheck schema_rev and max_batch ordering across candidate batches.", "Yet another pass rechecking schema_rev and max_batch ordering across candidate batches." ], "shows": "Synthetic task batch across 4 complexity regimes, verbose multi-turn reasoning trace and cyclic overthinking trace.", "source": "Synthetic. Written for this pack." } }, { "slug": "example.thought-budget-routing-receipt", "category": "noun.eval_run", "role": "example", "synthetic": true, "title": "Worked example output: recomputed 4-regime routing, 6.15x invariant checkpoint compression and step-3 loop halt", "category_reason": "Synthetic receipt verified by test_thought_budget_routing.py.", "value": { "conforms_to": { "$pin": "template.thought-budget-routing-receipt" }, "instance": { "task_regimes": { "schema_key_lookup": "zero_step_direct", "single_hop_summary": "fast_sketch", "multi_turn_state_handoff": "compressed_state_checkpoint", "proof_obligation_verify": "full_deliberative_verify", "tight_latency_checkpoint": "compressed_state_checkpoint" }, "budget_clamped_tasks": [ "tight_latency_checkpoint" ], "routed_total_tokens": 2304, "token_savings_fraction": 0.55, "raw_trace_tokens": 123, "compressed_checkpoint_tokens": 20, "compression_ratio": 6.15, "meets_compression_target": true, "binding_constraint_recall": 1.0, "open_obligation_recall": 1.0, "verified_hash_recall": 1.0, "latent_vector_dims": 16, "overthinking_loop_detected": true, "overthinking_trigger_step": 3, "overthinking_tokens_saved": 23, "productive_trace_false_loop": false }, "shows": "Recomputes 4-regime task routing (55% token savings), 6.15x trace compression with 1.0 invariant/hash recall and step-3 loop early-halt.", "source": "Synthetic. Recomputed directly from example.thought-budget-routing-bundle." }, "relations": [ [ "derives_from", "example.thought-budget-routing-bundle" ], [ "verifies", "template.thought-budget-routing-receipt" ] ] } ], "verbs": [ { "slug": "route-adaptive-reasoning-budget", "kind": "verb.compile_dag", "title": "Route candidate tasks across four compute and reasoning budget regimes", "claimant": "agent", "model_use": "none", "summary": "Score task dependency depth, branching factor, constraint count and Shannon ambiguity entropy to select zero_step_direct, fast_sketch, compressed_state_checkpoint or full_deliberative_verify under token and latency caps.", "outcome": "Budget-clamped reasoning regime assignment and token allocation schedule.", "ready_outcome": "thought_budget_routed", "pinned": [ "spec.coconut-latent-and-budget-grid", "rules.regime-routing-and-stagnation-halt", "guardrail.grid-clamped-thought-budget-and-loop-halt", "tool.thought-budget-routing" ], "slots": [ { "name": "task_batch_bundle", "category": "noun.eval_run", "description": "Pin of candidate tasks with complexity features, ambiguity distributions and latency/token caps." } ], "produces": [ { "name": "routing_budget_receipt", "template": "template.thought-budget-routing-receipt" } ], "steps": [ "Resolve regime score ceilings and token/latency caps from default_grid_spec.json via NodeGrid.", "Compute normalized complexity and ambiguity entropy and downshift regimes whenever task latency or token caps bind." ], "acceptance": [ { "id": "four-regimes-and-latency-clamp", "check": "Trivial lookups receive 0 reasoning tokens while tight latency budgets deterministically clamp deliberative tasks to compressed_state_checkpoint.", "method": "deterministic" } ] }, { "slug": "compress-latent-checkpoint-and-detect-loops", "kind": "verb.distill_reflex", "title": "Compress multi-turn reasoning traces into invariant plus continuous latent checkpoints and halt cyclic loops", "claimant": "agent", "model_use": "none", "summary": "Distill verbose multi-turn traces into compact state facts, binding constraints, unresolved obligations, verified SHA-256 digests and normalized continuous latent vectors while flagging stagnant paraphrase cycles.", "outcome": "Compact invariant checkpoint (>3x compression) and overthinking loop early-halt decision.", "ready_outcome": "checkpoint_compressed_and_screened", "pinned": [ "spec.coconut-latent-and-budget-grid", "rules.regime-routing-and-stagnation-halt", "guardrail.lossless-invariant-and-digest-checkpointing", "tool.thought-budget-routing" ], "slots": [ { "name": "reasoning_trace_bundle", "category": "noun.eval_run", "description": "Pin of multi-turn reasoning traces and ground-truth invariants." } ], "produces": [ { "name": "latent_checkpoint_receipt", "template": "template.thought-budget-routing-receipt" } ], "steps": [ "Extract state facts, binding constraints, open obligations and 64-character SHA-256 digests while projecting salient tokens into a normalized latent state vector.", "Scan consecutive steps with OverthinkingLoopDetector and trigger early checkpoint halt on invariant-free repetition." ], "acceptance": [ { "id": "compression-exceeds-3x-with-full-recall", "check": "compression_ratio exceeds 3.0 with 1.0 recall on binding constraints, open obligations and verified SHA-256 digests.", "method": "deterministic" } ], "follows": [ "coconut-latent-and-thought-budget-routing.route-adaptive-reasoning-budget" ] }, { "slug": "verify-invariant-recall-and-ast-gate", "kind": "verb.verify_gate", "title": "Independently verify latent checkpoint recall, loop-halt precision and AST magic-literal gates", "claimant": "agent", "model_use": "none", "summary": "Recompute 4-regime thought-budget routing, >3x invariant checkpoint compression, overthinking loop detection and ZeroHardcodedValuesAstGate conformance under a distinct reviewer.", "outcome": "Independent deterministic verification receipt for thought-budget routing, latent compression and AST conformance.", "ready_outcome": "routing_and_checkpoint_verified", "review": "distinct_reviewer", "pinned": [ "spec.coconut-latent-and-budget-grid", "guardrail.lossless-invariant-and-digest-checkpointing", "guardrail.grid-clamped-thought-budget-and-loop-halt", "tool.thought-budget-routing", "template.thought-budget-routing-receipt" ], "slots": [ { "name": "routing_eval_bundle", "category": "noun.eval_run", "description": "Pin of synthetic task routing, trace compression and loop-detection fixture." } ], "produces": [ { "name": "verified_thought_budget_receipt", "template": "template.thought-budget-routing-receipt" } ], "steps": [ "Recompute run_bundle on the pinned evaluation fixture and confirm exact receipt match.", "Run scan_directory_for_hardcoded_values across thought_budget_routing and confirm zero violations." ], "acceptance": [ { "id": "ast-and-routing-receipt-reproduced", "check": "scan_directory_for_hardcoded_values returns [] and run_bundle reproduces the exact receipt.", "method": "deterministic" } ], "follows": [ "coconut-latent-and-thought-budget-routing.compress-latent-checkpoint-and-detect-loops" ] } ] }