cleveragents/cleveragents-core

Fork 3

UAT: `ActorConfigSchema` missing `temperature` and `max_tokens` top-level fields for LLM actors #5471

New issue

Open

opened 2026-04-09 06:56:42 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 06:56:42 +00:00

Owner

Bug Report

Feature Area

Actor System Compilation — LLM-type actor configuration schema

What Was Tested

Code-level analysis of src/cleveragents/actor/schema.py against the specification's LLM actor field definitions.

Expected Behavior (from spec)

Per docs/specification.md lines 20444-20454, the actor definition supports these fields in the config: block:

| `config.temperature` | float | No | Sampling temperature (0.0 to 2.0). Lower = more deterministic. |
| `config.max_tokens` | integer | No | Maximum tokens in the generated response. |

Additionally, the spec's "Additional fields available in the v2/runtime actor definition format" section explicitly lists temperature and max_tokens as supported configuration fields.

The spec also shows these fields in example actor YAML files (e.g., docs/specification.md line 20380 lists temperature and max_tokens as supported fields).

Actual Behavior (from code)

src/cleveragents/actor/schema.py (ActorConfigSchema) does not define temperature or max_tokens as top-level fields:

class ActorConfigSchema(BaseModel):
    name: str
    type: ActorType
    description: str
    version: str = Field(default="1.0", ...)
    model: str | None = None
    system_prompt: str | None = None
    response_format: dict[str, Any] | None = None
    tools: list[str | ToolDefinition] = ...
    context_view: ContextView | None = None
    role_hint: RoleHint | None = None
    memory: MemoryConfig = ...
    context: ContextConfigSchema = ...
    route: RouteDefinition | None = None
    skills: list[str] = ...
    lsp: ...
    env_vars: dict[str, str] = ...
    # NO temperature field
    # NO max_tokens field

The MemoryConfig class does have max_tokens (for conversation history), but this is different from the LLM's max_tokens generation parameter.

Impact

Users cannot configure temperature or max_tokens for LLM actors via the v3 YAML schema.
These are fundamental LLM configuration parameters that affect output quality and cost.
The ActorConfiguration class (config.py) does support these via the options dict, but the v3 ActorConfigSchema (schema.py) does not expose them as typed fields.
Actor YAML files that include temperature: 0.2 or max_tokens: 2048 at the top level will have these fields silently ignored by Pydantic (or raise a validation error if extra="forbid" is set).

Code Location

src/cleveragents/actor/schema.py — ActorConfigSchema class (lines 665-855)
docs/specification.md lines 20380, 20444-20454 (spec defines these fields)

Fix Required

Add temperature and max_tokens fields to ActorConfigSchema:

temperature: float | None = Field(
    default=None,
    description="Sampling temperature (0.0 to 2.0). Lower = more deterministic.",
    ge=0.0,
    le=2.0,
)
max_tokens: int | None = Field(
    default=None,
    description="Maximum tokens in the generated response.",
    gt=0,
)

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report ### Feature Area Actor System Compilation — LLM-type actor configuration schema ### What Was Tested Code-level analysis of `src/cleveragents/actor/schema.py` against the specification's LLM actor field definitions. ### Expected Behavior (from spec) Per `docs/specification.md` lines 20444-20454, the actor definition supports these fields in the `config:` block: ``` | `config.temperature` | float | No | Sampling temperature (0.0 to 2.0). Lower = more deterministic. | | `config.max_tokens` | integer | No | Maximum tokens in the generated response. | ``` Additionally, the spec's "Additional fields available in the v2/runtime actor definition format" section explicitly lists `temperature` and `max_tokens` as supported configuration fields. The spec also shows these fields in example actor YAML files (e.g., `docs/specification.md` line 20380 lists `temperature` and `max_tokens` as supported fields). ### Actual Behavior (from code) `src/cleveragents/actor/schema.py` (`ActorConfigSchema`) does not define `temperature` or `max_tokens` as top-level fields: ```python class ActorConfigSchema(BaseModel): name: str type: ActorType description: str version: str = Field(default="1.0", ...) model: str | None = None system_prompt: str | None = None response_format: dict[str, Any] | None = None tools: list[str | ToolDefinition] = ... context_view: ContextView | None = None role_hint: RoleHint | None = None memory: MemoryConfig = ... context: ContextConfigSchema = ... route: RouteDefinition | None = None skills: list[str] = ... lsp: ... env_vars: dict[str, str] = ... # NO temperature field # NO max_tokens field ``` The `MemoryConfig` class does have `max_tokens` (for conversation history), but this is different from the LLM's `max_tokens` generation parameter. ### Impact - Users cannot configure `temperature` or `max_tokens` for LLM actors via the v3 YAML schema. - These are fundamental LLM configuration parameters that affect output quality and cost. - The `ActorConfiguration` class (config.py) does support these via the `options` dict, but the v3 `ActorConfigSchema` (schema.py) does not expose them as typed fields. - Actor YAML files that include `temperature: 0.2` or `max_tokens: 2048` at the top level will have these fields silently ignored by Pydantic (or raise a validation error if `extra="forbid"` is set). ### Code Location - `src/cleveragents/actor/schema.py` — `ActorConfigSchema` class (lines 665-855) - `docs/specification.md` lines 20380, 20444-20454 (spec defines these fields) ### Fix Required Add `temperature` and `max_tokens` fields to `ActorConfigSchema`: ```python temperature: float | None = Field( default=None, description="Sampling temperature (0.0 to 2.0). Lower = more deterministic.", ge=0.0, le=2.0, ) max_tokens: int | None = Field( default=None, description="Maximum tokens in the generated response.", gt=0, ) ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 06:57:00 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 06:59:18 +00:00

HAL9000 commented

2026-04-09 07:00:40 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

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

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 07:06:47 +00:00

EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0) #5502

HAL9000 commented

2026-04-09 07:08:05 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — ActorConfigSchema is missing temperature and max_tokens top-level fields for LLM actors. Users cannot configure LLM parameters through the actor config, which limits customization of LLM behavior.
Milestone: v3.2.0 — actor configuration is a core v3.2.0 feature
Story Points: 2 — S — requires adding the fields to the schema and wiring them through the actor execution pipeline
MoSCoW: Should Have — LLM parameter configuration is important for production use, but the system works with defaults. Not blocking core functionality.
Parent Epic: Needs linking to the actor configuration epic

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — `ActorConfigSchema` is missing `temperature` and `max_tokens` top-level fields for LLM actors. Users cannot configure LLM parameters through the actor config, which limits customization of LLM behavior. - **Milestone**: v3.2.0 — actor configuration is a core v3.2.0 feature - **Story Points**: 2 — S — requires adding the fields to the schema and wiring them through the actor execution pipeline - **MoSCoW**: Should Have — LLM parameter configuration is important for production use, but the system works with defaults. Not blocking core functionality. - **Parent Epic**: Needs linking to the actor configuration epic --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 07:08:55 +00:00

HAL9000 added a new dependency

2026-04-09 07:09:06 +00:00

#5502 EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0)