feat(actor): Node-level model_tier field in actor YAML config for cost-aware LLM selection #6765

Open
opened 2026-04-10 02:03:58 +00:00 by drew · 4 comments
Member

Overview

Add an optional model_tier field to individual nodes in actor YAML configuration, allowing explicit assignment of cheap/default/frontier models per node. This enables cost-optimised actor graphs without a dynamic task-complexity classifier, and fits the spec's existing philosophy of explicit configuration over automatic inference.

Gap Being Filled

The spec already supports per-subsystem model configuration (context.summarize.model, context.strategies.arce.model). However, within an actor's LangGraph execution graph, all LLM nodes currently use the same model — the one configured for the actor as a whole.

Long Execute-phase plans contain nodes of vastly different complexity:

  • Simple nodes: Reading a file summary, checking a type annotation, confirming a resource exists — cheap model sufficient
  • Complex nodes: Designing an architectural change, resolving a subtle invariant conflict, recovering from an unexpected error — frontier model required

Using a frontier model for every node in a long plan wastes significant token budget on decisions that don't require it.

The gap: There is no mechanism for an actor definition to declare that some nodes should use cheaper models, even when the actor author knows some nodes are lightweight.

Proposed Design

Add a model_tier field to actor node YAML configuration:

`yaml

Example actor node configuration

nodes:

  • id: analyze_imports
    type: llm
    model_tier: cheap # new optional field
    skill: static_analysis

  • id: generate_implementation
    type: llm
    model_tier: frontier # explicit frontier requirement
    skill: implement

  • id: verify_types
    type: llm
    model_tier: cheap
    skill: type_check

  • id: resolve_conflict
    type: llm

    model_tier absent = uses actor default

    skill: conflict_resolution
    `

A new config table maps tier names to models:
yaml model: tiers: cheap: claude-haiku-4 # or gemini-flash, etc. default: claude-sonnet-4 # actor's normal model frontier: claude-opus-4 # most capable

  • When model_tier is absent, the node uses the actor's default model (no behaviour change for existing actor definitions).
  • The tier-to-model mapping is global config, overridable per project.
  • This is configuration-driven, not automatic — the actor author declares tier, not an inferred classifier. This fits the spec's existing philosophy exactly.

Inspiration from Claude Code

Claude Code uses models at different tiers throughout its pipeline (documented in the March 2026 source map leak):

  • Haiku for binary safety pre-screening of bash commands
  • Regex (no model) for frustration/sentiment detection
  • Frontier model for full chain-of-thought reasoning in the YOLO classifier Stage 2
  • A separate cheaper model for context summarisation (the auto-compact step)

The principle: cheap models for cheap decisions; escalate only when the task earns it. CC implements this implicitly through architectural separation of concerns. This proposal makes the same principle explicit and configurable in CleverAgents' actor YAML format.

An analogous pattern from the community: the oh-my-opencode plugin with Vercel AI Gateway routes OpenCode tasks to different models by task type, claiming ~70% token cost reduction. The model_tier field achieves the same outcome through actor-author intent rather than automatic inference.

Recommendation

If approved, update:

  • Specification §Core Concepts > Actor and Agent Architecture: document model_tier as an optional LLM node field
  • ADR-010 (Actor and Agent Architecture): add model_tier to the node schema definition
  • ADR-031 (Actor Abstraction Definition): document the tier resolution algorithm (node tier → actor default → global default)
  • Config reference: add model.tiers.cheap, model.tiers.default, model.tiers.frontier keys
  • Implementation: extend actor node schema in src/cleveragents/actor/schema.py and src/cleveragents/actor/config.py; resolve tiers in src/cleveragents/actor/compiler.py
## Overview Add an optional `model_tier` field to individual nodes in actor YAML configuration, allowing explicit assignment of cheap/default/frontier models per node. This enables cost-optimised actor graphs without a dynamic task-complexity classifier, and fits the spec's existing philosophy of explicit configuration over automatic inference. ## Gap Being Filled The spec already supports per-subsystem model configuration (`context.summarize.model`, `context.strategies.arce.model`). However, within an actor's LangGraph execution graph, all LLM nodes currently use the same model — the one configured for the actor as a whole. Long Execute-phase plans contain nodes of vastly different complexity: - **Simple nodes:** Reading a file summary, checking a type annotation, confirming a resource exists — cheap model sufficient - **Complex nodes:** Designing an architectural change, resolving a subtle invariant conflict, recovering from an unexpected error — frontier model required Using a frontier model for every node in a long plan wastes significant token budget on decisions that don't require it. **The gap:** There is no mechanism for an actor definition to declare that some nodes should use cheaper models, even when the actor author knows some nodes are lightweight. ## Proposed Design Add a `model_tier` field to actor node YAML configuration: `yaml # Example actor node configuration nodes: - id: analyze_imports type: llm model_tier: cheap # new optional field skill: static_analysis - id: generate_implementation type: llm model_tier: frontier # explicit frontier requirement skill: implement - id: verify_types type: llm model_tier: cheap skill: type_check - id: resolve_conflict type: llm # model_tier absent = uses actor default skill: conflict_resolution ` A new config table maps tier names to models: `yaml model: tiers: cheap: claude-haiku-4 # or gemini-flash, etc. default: claude-sonnet-4 # actor's normal model frontier: claude-opus-4 # most capable ` - When `model_tier` is absent, the node uses the actor's default model (no behaviour change for existing actor definitions). - The tier-to-model mapping is global config, overridable per project. - This is **configuration-driven, not automatic** — the actor author declares tier, not an inferred classifier. This fits the spec's existing philosophy exactly. ## Inspiration from Claude Code Claude Code uses models at different tiers throughout its pipeline (documented in the March 2026 source map leak): - Haiku for binary safety pre-screening of bash commands - Regex (no model) for frustration/sentiment detection - Frontier model for full chain-of-thought reasoning in the YOLO classifier Stage 2 - A separate cheaper model for context summarisation (the auto-compact step) The principle: **cheap models for cheap decisions; escalate only when the task earns it.** CC implements this implicitly through architectural separation of concerns. This proposal makes the same principle explicit and configurable in CleverAgents' actor YAML format. An analogous pattern from the community: the `oh-my-opencode` plugin with Vercel AI Gateway routes OpenCode tasks to different models by task type, claiming ~70% token cost reduction. The `model_tier` field achieves the same outcome through actor-author intent rather than automatic inference. ## Recommendation If approved, update: - **Specification** §Core Concepts > Actor and Agent Architecture: document `model_tier` as an optional LLM node field - **ADR-010** (Actor and Agent Architecture): add `model_tier` to the node schema definition - **ADR-031** (Actor Abstraction Definition): document the tier resolution algorithm (node tier → actor default → global default) - **Config reference**: add `model.tiers.cheap`, `model.tiers.default`, `model.tiers.frontier` keys - **Implementation**: extend actor node schema in `src/cleveragents/actor/schema.py` and `src/cleveragents/actor/config.py`; resolve tiers in `src/cleveragents/actor/compiler.py`
Owner

Thank you for filing this proposal, @drew. I have reviewed it.

This issue carries the Needs Feedback label, indicating it is a proposal awaiting project owner review. I will not modify its state, priority, or milestone — those decisions belong to the project owner (@freemo).

Summary of the proposal: Add an optional model_tier field to actor YAML node configuration, enabling cost-aware LLM selection per node (cheap/default/frontier). The tier-to-model mapping would be global config, overridable per project. This is configuration-driven (not automatic inference), consistent with the spec's existing philosophy.

Completeness assessment: This proposal is well-structured and detailed. It includes:

  • Clear gap analysis referencing the existing spec
  • Concrete proposed design with YAML examples
  • Inspiration from Claude Code's tiered model usage
  • Specific files and spec sections to update if approved

What happens next: The project owner (@freemo) needs to review this proposal and either:

  1. Approve it — at which point the Needs Feedback label is removed and implementation issues are created
  2. Request changes — provide feedback in comments
  3. Decline it — close with a State/Wont Do label and explanation

I will monitor this issue and respond to any questions or comments.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Thank you for filing this proposal, @drew. I have reviewed it. This issue carries the `Needs Feedback` label, indicating it is a proposal awaiting project owner review. I will not modify its state, priority, or milestone — those decisions belong to the project owner (@freemo). **Summary of the proposal:** Add an optional `model_tier` field to actor YAML node configuration, enabling cost-aware LLM selection per node (cheap/default/frontier). The tier-to-model mapping would be global config, overridable per project. This is configuration-driven (not automatic inference), consistent with the spec's existing philosophy. **Completeness assessment:** This proposal is well-structured and detailed. It includes: - Clear gap analysis referencing the existing spec - Concrete proposed design with YAML examples - Inspiration from Claude Code's tiered model usage - Specific files and spec sections to update if approved **What happens next:** The project owner (@freemo) needs to review this proposal and either: 1. Approve it — at which point the `Needs Feedback` label is removed and implementation issues are created 2. Request changes — provide feedback in comments 3. Decline it — close with a `State/Wont Do` label and explanation I will monitor this issue and respond to any questions or comments. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
Owner

Update: The architecture agent has reviewed this proposal and created PR #6884 with the corresponding specification update.

Status: PR #6884 is open and awaiting human review from @freemo. Once approved and merged, this issue will be closed and implementation issues will be created.

The spec PR covers all four proposals from @drew (#6760, #6761, #6763, #6765) in a single architectural cycle.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Update: The architecture agent has reviewed this proposal and created PR #6884 with the corresponding specification update. **Status:** PR #6884 is open and awaiting human review from @freemo. Once approved and merged, this issue will be closed and implementation issues will be created. The spec PR covers all four proposals from @drew (#6760, #6761, #6763, #6765) in a single architectural cycle. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
Owner

Label compliance fix applied: Added missing Priority/Backlog label. Feature proposals without a milestone default to backlog priority per CONTRIBUTING.md.


Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: Added missing `Priority/Backlog` label. Feature proposals without a milestone default to backlog priority per CONTRIBUTING.md. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
Owner

Verified — Feature discussion: node-level model_tier field for cost-aware LLM selection. MoSCoW: Could-have. Priority: Low — future enhancement.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Feature discussion: node-level model_tier field for cost-aware LLM selection. MoSCoW: Could-have. Priority: Low — future enhancement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#6765
No description provided.