@elizaos/python 2.0.0-alpha.10 → 2.0.0-alpha.11

package/elizaos/bootstrap/providers/actions.py

@@ -1,8 +1,14 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+import contextlib
+from typing import TYPE_CHECKING, TypeVar
 
 from elizaos.action_docs import get_canonical_action_example_calls
+from elizaos.deterministic import (
+    build_conversation_seed,
+    build_deterministic_seed,
+    deterministic_int,
+)
 from elizaos.generated.spec_helpers import require_provider_spec
 from elizaos.types import Provider, ProviderResult
 from elizaos.types.components import ActionExample
@@ -21,10 +27,6 @@ if TYPE_CHECKING:
 _spec = require_provider_spec("ACTIONS")
 
 
-def format_action_names(actions: list[Action]) -> str:
-    return ", ".join(action.name for action in actions)
-
-
 def _format_parameter_type(schema: ActionParameterSchema) -> str:
     if schema.type == "number" and (schema.minimum is not None or schema.maximum is not None):
         min_val = schema.minimum if schema.minimum is not None else "∞"
@@ -62,9 +64,23 @@ def _format_action_parameters(parameters: list[ActionParameter]) -> str:
     return "\n".join(lines)
 
 
-def format_actions(actions: list[Action]) -> str:
+T = TypeVar("T")
+
+
+def _deterministic_shuffle(items: list[T], seed: str, surface: str = "shuffle") -> list[T]:
+    shuffled = list(items)
+    for i in range(len(shuffled) - 1, 0, -1):
+        j = deterministic_int(seed, f"{surface}:{i}", i + 1)
+        shuffled[i], shuffled[j] = shuffled[j], shuffled[i]
+    return shuffled
+
+
+def format_actions(actions: list[Action], seed: str | None = None) -> str:
+    deterministic_seed = seed or build_deterministic_seed(
+        ["actions-format", ",".join(action.name for action in actions)]
+    )
     lines: list[str] = []
-    for action in actions:
+    for action in _deterministic_shuffle(actions, deterministic_seed, "actions"):
         line = f"- **{action.name}**: {action.description or 'No description'}"
         if action.parameters:
             params_text = _format_action_parameters(action.parameters)
@@ -81,7 +97,24 @@ def _replace_name_placeholders(text: str) -> str:
     return text
 
 
-def format_action_examples(actions: list[Action], max_examples: int = 10) -> str:
+def _replace_name_placeholders_seeded(text: str, seed: str, example_index: int) -> str:
+    names = ["Alex", "Jordan", "Sam", "Taylor", "Riley"]
+    output = text
+    for placeholder_index in range(1, 6):
+        name_index = deterministic_int(
+            seed,
+            f"example:{example_index}:name:{placeholder_index}",
+            len(names),
+        )
+        output = output.replace(f"{{{{name{placeholder_index}}}}}", names[name_index])
+    return output
+
+
+def format_action_examples(
+    actions: list[Action],
+    max_examples: int = 10,
+    seed: str | None = None,
+) -> str:
     """
     Format a deterministic subset of action examples for prompt context.
 
@@ -90,27 +123,60 @@ def format_action_examples(actions: list[Action], max_examples: int = 10) -> str
     if max_examples <= 0:
         return ""
 
-    examples: list[list[ActionExample]] = []
-    for action in sorted(actions, key=lambda a: a.name):
-        if not action.examples:
-            continue
-        for ex in action.examples:
-            if isinstance(ex, list) and ex:
-                examples.append(ex)
-            if len(examples) >= max_examples:
-                break
-        if len(examples) >= max_examples:
-            break
-
-    if not examples:
+    actions_with_examples = [
+        action
+        for action in actions
+        if action.examples and isinstance(action.examples, list) and len(action.examples) > 0
+    ]
+    if not actions_with_examples:
         return ""
 
+    examples_copy: list[list[list[ActionExample]]] = [
+        [example for example in (action.examples or []) if isinstance(example, list) and example]
+        for action in actions_with_examples
+    ]
+    available_action_indices = [
+        idx for idx, action_examples in enumerate(examples_copy) if action_examples
+    ]
+
+    selection_seed = seed or build_deterministic_seed(
+        [
+            "action-examples",
+            ",".join(action.name for action in actions_with_examples),
+            max_examples,
+        ]
+    )
+
+    selected_examples: list[list[ActionExample]] = []
+    iteration = 0
+    while len(selected_examples) < max_examples and available_action_indices:
+        random_index = deterministic_int(
+            selection_seed,
+            f"action-index:{iteration}",
+            len(available_action_indices),
+        )
+        action_index = available_action_indices[random_index]
+        action_examples = examples_copy[action_index]
+
+        example_index = deterministic_int(
+            selection_seed,
+            f"example-index:{iteration}",
+            len(action_examples),
+        )
+        selected_examples.append(action_examples.pop(example_index))
+        iteration += 1
+
+        if not action_examples:
+            available_action_indices.pop(random_index)
+
     blocks: list[str] = []
-    for ex in examples:
+    for example_index, ex in enumerate(selected_examples):
         lines: list[str] = []
         for msg in ex:
             msg_text = msg.content.text if msg.content and msg.content.text else ""
-            lines.append(f"{msg.name}: {_replace_name_placeholders(msg_text)}")
+            lines.append(
+                f"{msg.name}: {_replace_name_placeholders_seeded(msg_text, selection_seed, example_index)}"
+            )
         blocks.append("\n".join(lines))
 
     return "\n\n".join(blocks)
@@ -180,6 +246,17 @@ def format_action_call_examples(actions: list[Action], max_examples: int = 5) ->
     return "\n\n".join(blocks)
 
 
+def format_action_names(actions: list[Action], seed: str | None = None) -> str:
+    if not actions:
+        return ""
+
+    deterministic_seed = seed or build_deterministic_seed(
+        ["action-names", ",".join(action.name for action in actions)]
+    )
+    shuffled = _deterministic_shuffle(actions, deterministic_seed, "actions")
+    return ", ".join(action.name for action in shuffled)
+
+
 async def get_actions(
     runtime: IAgentRuntime,
     message: Memory,
@@ -189,13 +266,27 @@ async def get_actions(
 
     for action in runtime.actions:
         validate_fn = getattr(action, "validate", None) or getattr(action, "validate_fn", None)
-        is_valid = await validate_fn(runtime, message, state) if validate_fn else True
+        if not validate_fn:
+            is_valid = True
+        else:
+            try:
+                is_valid = await validate_fn(runtime, message, state)
+            except Exception:
+                if hasattr(runtime, "logger"):
+                    with contextlib.suppress(Exception):
+                        runtime.logger.warning(
+                            f"Action validation failed for {action.name}; excluding from prompt"
+                        )
+                is_valid = False
         if is_valid:
             validated_actions.append(action)
 
-    action_names = format_action_names(validated_actions)
-    actions_text = format_actions(validated_actions)
-    examples_text = format_action_examples(validated_actions, max_examples=10)
+    action_seed = build_conversation_seed(runtime, message, state, "provider:actions")
+    action_names = format_action_names(validated_actions, seed=f"{action_seed}:names")
+    actions_text = format_actions(validated_actions, seed=f"{action_seed}:descriptions")
+    examples_text = format_action_examples(
+        validated_actions, max_examples=10, seed=f"{action_seed}:examples"
+    )
     call_examples_text = format_action_call_examples(validated_actions, max_examples=5)
 
     text_parts: list[str] = [f"Possible response actions: {action_names}"]

package/elizaos/bootstrap/providers/agent_settings.py

@@ -60,4 +60,5 @@ agent_settings_provider = Provider(
     description=_spec["description"],
     get=get_agent_settings_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/attachments.py

@@ -73,4 +73,5 @@ attachments_provider = Provider(
     description=_spec["description"],
     get=get_attachments,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/capabilities.py

@@ -63,4 +63,5 @@ capabilities_provider = Provider(
     description=_spec["description"],
     get=get_capabilities,
     dynamic=_spec.get("dynamic", False),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/character.py

@@ -125,4 +125,5 @@ character_provider = Provider(
     description=_spec["description"],
     get=get_character_context,
     dynamic=_spec.get("dynamic", False),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/choice.py

@@ -74,4 +74,5 @@ choice_provider = Provider(
     description=_spec["description"],
     get=get_choice_options,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/contacts.py

@@ -75,4 +75,5 @@ contacts_provider = Provider(
     description=_spec["description"],
     get=get_contacts_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/current_time.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from elizaos.deterministic import get_prompt_reference_datetime
 from elizaos.generated.spec_helpers import require_provider_spec
 from elizaos.types import Provider, ProviderResult
 
@@ -18,7 +18,12 @@ async def get_current_time_context(
     message: Memory,
     state: State | None = None,
 ) -> ProviderResult:
-    now = datetime.now(UTC)
+    now = get_prompt_reference_datetime(
+        runtime,
+        message,
+        state,
+        "provider:current_time",
+    )
 
     iso_timestamp = now.isoformat()
     human_readable = now.strftime("%A, %B %d, %Y at %H:%M:%S UTC")
@@ -53,4 +58,5 @@ current_time_provider = Provider(
     description=_spec["description"],
     get=get_current_time_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/entities.py

@@ -96,4 +96,5 @@ entities_provider = Provider(
     description=_spec["description"],
     get=get_entities_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/evaluators.py

@@ -55,4 +55,5 @@ evaluators_provider = Provider(
     description=_spec["description"],
     get=get_evaluators,
     dynamic=_spec.get("dynamic", False),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/facts.py

@@ -83,4 +83,5 @@ facts_provider = Provider(
     description=_spec["description"],
     get=get_facts_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/follow_ups.py

@@ -113,4 +113,5 @@ follow_ups_provider = Provider(
     description=_spec["description"],
     get=get_follow_ups_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/knowledge.py

@@ -70,4 +70,5 @@ knowledge_provider = Provider(
     description=_spec["description"],
     get=get_knowledge_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/providers_list.py

@@ -56,4 +56,5 @@ providers_list_provider = Provider(
     description=_spec["description"],
     get=get_providers_list,
     dynamic=_spec.get("dynamic", False),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/relationships.py

@@ -103,4 +103,5 @@ relationships_provider = Provider(
     description=_spec["description"],
     get=get_relationships,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/roles.py

@@ -92,4 +92,5 @@ roles_provider = Provider(
     description=_spec["description"],
     get=get_roles,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/settings.py

@@ -52,4 +52,5 @@ settings_provider = Provider(
     description=_spec["description"],
     get=get_settings_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/time.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from elizaos.deterministic import get_prompt_reference_datetime
 from elizaos.generated.spec_helpers import require_provider_spec
 from elizaos.types import Provider, ProviderResult
 
@@ -18,9 +18,12 @@ async def get_time_context(
     message: Memory,
     state: State | None = None,
 ) -> ProviderResult:
-    _ = runtime, message, state
-
-    now = datetime.now(UTC)
+    now = get_prompt_reference_datetime(
+        runtime,
+        message,
+        state,
+        "provider:time",
+    )
     iso_string = now.isoformat()
     timestamp_ms = int(now.timestamp() * 1000)
     human_readable = now.strftime("%A, %B %d, %Y at %H:%M:%S UTC")
@@ -42,4 +45,5 @@ time_provider = Provider(
     description=_spec["description"],
     get=get_time_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/bootstrap/providers/world.py

@@ -94,4 +94,5 @@ world_provider = Provider(
     description=_spec["description"],
     get=get_world_context,
     dynamic=_spec.get("dynamic", True),
+    position=_spec.get("position"),
 )

package/elizaos/deterministic.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Protocol
+from uuid import UUID
+
+DEFAULT_TIME_BUCKET_MS = 5 * 60 * 1000
+
+SeedPart = str | int | float | bool | None
+
+
+class RuntimeLike(Protocol):
+    @property
+    def agent_id(self) -> object: ...
+
+    @property
+    def character(self) -> object: ...
+
+    def get_setting(self, key: str) -> object | None: ...
+
+
+def _normalize_seed_part(part: SeedPart) -> str:
+    if part is None:
+        return "none"
+    return str(part)
+
+
+def _coerce_non_empty_string(value: object | None) -> str | None:
+    if value is None:
+        return None
+    as_text = str(value).strip()
+    if not as_text:
+        return None
+    return as_text
+
+
+def _get_field(obj: object | None, *names: str) -> object | None:
+    if obj is None:
+        return None
+
+    if isinstance(obj, dict):
+        for name in names:
+            if name in obj:
+                value = obj[name]
+                if value is not None and value != "":
+                    return value
+        return None
+
+    for name in names:
+        value = getattr(obj, name, None)
+        if value is not None and value != "":
+            return value
+    return None
+
+
+def build_deterministic_seed(parts: list[SeedPart]) -> str:
+    return "|".join(_normalize_seed_part(part) for part in parts)
+
+
+def deterministic_hex(seed: str, surface: str, length: int = 16) -> str:
+    if length <= 0:
+        return ""
+
+    output = ""
+    counter = 0
+    while len(output) < length:
+        payload = f"{seed}|{surface}|{counter}".encode()
+        output += sha256(payload).hexdigest()
+        counter += 1
+    return output[:length]
+
+
+def deterministic_int(seed: str, surface: str, max_exclusive: int) -> int:
+    if max_exclusive <= 1:
+        return 0
+    value = int(deterministic_hex(seed, surface, 12), 16)
+    return value % max_exclusive
+
+
+def deterministic_uuid(seed: str, surface: str) -> str:
+    return str(UUID(hex=deterministic_hex(seed, surface, 32)))
+
+
+def parse_boolean_setting(value: object | None) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value != 0
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        return normalized in ("1", "true", "yes", "on", "enabled")
+    return False
+
+
+def parse_positive_int_setting(value: object | None, fallback: int) -> int:
+    if isinstance(value, bool):
+        return fallback
+    if isinstance(value, (int, float)):
+        numeric = int(value)
+        return numeric if numeric > 0 else fallback
+    if isinstance(value, str):
+        try:
+            numeric = int(float(value))
+            return numeric if numeric > 0 else fallback
+        except ValueError:
+            return fallback
+    return fallback
+
+
+def build_conversation_seed(
+    runtime: RuntimeLike,
+    message: object | None,
+    state: object | None,
+    surface: str,
+    *,
+    bucket_ms: int | None = None,
+    now_ms: int | None = None,
+) -> str:
+    now_ms_value = now_ms if now_ms is not None else int(datetime.now(UTC).timestamp() * 1000)
+
+    state_data = _get_field(state, "data")
+    room_obj = _get_field(state_data, "room")
+    world_obj = _get_field(state_data, "world")
+
+    room_id = (
+        _coerce_non_empty_string(_get_field(room_obj, "id"))
+        or _coerce_non_empty_string(_get_field(state_data, "room_id", "roomId"))
+        or _coerce_non_empty_string(_get_field(message, "room_id", "roomId"))
+        or "room:none"
+    )
+    world_id = (
+        _coerce_non_empty_string(_get_field(world_obj, "id"))
+        or _coerce_non_empty_string(_get_field(room_obj, "world_id", "worldId"))
+        or _coerce_non_empty_string(_get_field(state_data, "world_id", "worldId"))
+        or _coerce_non_empty_string(_get_field(message, "world_id", "worldId"))
+        or "world:none"
+    )
+
+    character_obj = _get_field(runtime, "character")
+    character_id = (
+        _coerce_non_empty_string(_get_field(character_obj, "id"))
+        or _coerce_non_empty_string(_get_field(runtime, "agent_id"))
+        or "agent:none"
+    )
+
+    epoch_bucket = 0
+    if bucket_ms and bucket_ms > 0:
+        epoch_bucket = now_ms_value // bucket_ms
+
+    return build_deterministic_seed(
+        [
+            "eliza-prompt-cache-v1",
+            world_id,
+            room_id,
+            character_id,
+            epoch_bucket,
+            surface,
+        ]
+    )
+
+
+def get_prompt_reference_datetime(
+    runtime: RuntimeLike,
+    message: object | None,
+    state: object | None,
+    surface: str,
+    *,
+    now: datetime | None = None,
+) -> datetime:
+    now_utc = now.astimezone(UTC) if now is not None else datetime.now(UTC)
+    deterministic_enabled = parse_boolean_setting(
+        runtime.get_setting("PROMPT_CACHE_DETERMINISTIC_TIME")
+    )
+    if not deterministic_enabled:
+        return now_utc
+
+    bucket_ms = parse_positive_int_setting(
+        runtime.get_setting("PROMPT_CACHE_TIME_BUCKET_MS"),
+        DEFAULT_TIME_BUCKET_MS,
+    )
+    now_ms = int(now_utc.timestamp() * 1000)
+    seed = build_conversation_seed(
+        runtime,
+        message,
+        state,
+        surface,
+        bucket_ms=bucket_ms,
+        now_ms=now_ms,
+    )
+    bucket_start = (now_ms // bucket_ms) * bucket_ms
+    offset = deterministic_int(seed, "time-offset-ms", bucket_ms)
+    return datetime.fromtimestamp((bucket_start + offset) / 1000, tz=UTC)

package/elizaos/generated/__init__.py

@@ -0,0 +1 @@
+"""Auto-generated module package."""