@elizaos/python 2.0.0-alpha.10

package/elizaos/bootstrap/providers/actions.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.action_docs import get_canonical_action_example_calls
+from elizaos.generated.spec_helpers import require_provider_spec
+from elizaos.types import Provider, ProviderResult
+from elizaos.types.components import ActionExample
+
+if TYPE_CHECKING:
+    from elizaos.types import (
+        Action,
+        ActionParameter,
+        ActionParameterSchema,
+        IAgentRuntime,
+        Memory,
+        State,
+    )
+
+# Get text content from centralized specs
+_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 "∞"
+        max_val = schema.maximum if schema.maximum is not None else "∞"
+        return f"number [{min_val}-{max_val}]"
+    return schema.type
+
+
+def _get_param_schema(param: ActionParameter) -> object:
+    """Get schema from ActionParameter, handling both Pydantic and protobuf variants."""
+    return getattr(param, "schema_def", None) or getattr(param, "schema", None)
+
+
+def _format_action_parameters(parameters: list[ActionParameter]) -> str:
+    lines: list[str] = []
+    for param in parameters:
+        schema = _get_param_schema(param)
+        if schema is None:
+            lines.append(f"    - {param.name}: {param.description}")
+            continue
+        required_str = " (required)" if param.required else " (optional)"
+        type_str = _format_parameter_type(schema)
+        default_val = getattr(schema, "default", None) or getattr(schema, "default_value", None)
+        default_str = f" [default: {default_val}]" if default_val else ""
+        enum_vals = getattr(schema, "enum", None) or getattr(schema, "enum_values", None)
+        enum_str = f" [values: {', '.join(enum_vals)}]" if enum_vals else ""
+        examples_str = (
+            f" [examples: {', '.join(repr(v) for v in param.examples)}]"
+            if getattr(param, "examples", None)
+            else ""
+        )
+        lines.append(
+            f"    - {param.name}{required_str}: {param.description} ({type_str}{enum_str}{default_str}{examples_str})"
+        )
+    return "\n".join(lines)
+
+
+def format_actions(actions: list[Action]) -> str:
+    lines: list[str] = []
+    for action in actions:
+        line = f"- **{action.name}**: {action.description or 'No description'}"
+        if action.parameters:
+            params_text = _format_action_parameters(action.parameters)
+            if params_text:
+                line += f"\n  Parameters:\n{params_text}"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _replace_name_placeholders(text: str) -> str:
+    names = ["Alex", "Jordan", "Sam", "Taylor", "Riley"]
+    for i, name in enumerate(names, start=1):
+        text = text.replace(f"{{{{name{i}}}}}", name)
+    return text
+
+
+def format_action_examples(actions: list[Action], max_examples: int = 10) -> str:
+    """
+    Format a deterministic subset of action examples for prompt context.
+
+    Deterministic ordering is important to keep tests stable and avoid prompt churn.
+    """
+    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:
+        return ""
+
+    blocks: list[str] = []
+    for ex in 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)}")
+        blocks.append("\n".join(lines))
+
+    return "\n\n".join(blocks)
+
+
+def _escape_xml_text(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def format_action_call_examples(actions: list[Action], max_examples: int = 5) -> str:
+    """
+    Format canonical action-call examples (including optional <params> blocks).
+
+    Deterministic ordering is important to keep tests stable and avoid prompt churn.
+    """
+    if max_examples <= 0:
+        return ""
+
+    blocks: list[str] = []
+    for action in sorted(actions, key=lambda a: a.name):
+        calls = get_canonical_action_example_calls(action.name)
+        for call in calls:
+            user = call.get("user")
+            action_names = call.get("actions")
+            params = call.get("params")
+
+            if not isinstance(user, str) or not isinstance(action_names, list):
+                continue
+            if not all(isinstance(a, str) for a in action_names):
+                continue
+
+            actions_xml = "\n".join(
+                f"  <action>{_escape_xml_text(a)}</action>" for a in action_names
+            )
+
+            params_xml = ""
+            if isinstance(params, dict):
+                blocks_xml: list[str] = []
+                for act_name, act_params in params.items():
+                    if not isinstance(act_name, str) or not isinstance(act_params, dict):
+                        continue
+                    inner: list[str] = []
+                    for k, v in act_params.items():
+                        if not isinstance(k, str):
+                            continue
+                        if isinstance(v, str):
+                            raw = v
+                        elif v is None:
+                            raw = "null"
+                        elif isinstance(v, bool):
+                            raw = "true" if v else "false"
+                        elif isinstance(v, (int, float)):
+                            raw = str(v)
+                        else:
+                            raw = repr(v)
+                        inner.append(f"    <{k}>{_escape_xml_text(raw)}</{k}>")
+                    blocks_xml.append(f"  <{act_name}>\n" + "\n".join(inner) + f"\n  </{act_name}>")
+                if blocks_xml:
+                    params_xml = "\n<params>\n" + "\n".join(blocks_xml) + "\n</params>"
+
+            blocks.append(
+                f"User: {user}\nAssistant:\n<actions>\n{actions_xml}\n</actions>{params_xml}"
+            )
+            if len(blocks) >= max_examples:
+                return "\n\n".join(blocks)
+
+    return "\n\n".join(blocks)
+
+
+async def get_actions(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    validated_actions: list[Action] = []
+
+    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 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)
+    call_examples_text = format_action_call_examples(validated_actions, max_examples=5)
+
+    text_parts: list[str] = [f"Possible response actions: {action_names}"]
+    if actions_text:
+        text_parts.append(f"# Available Actions\n{actions_text}")
+    if examples_text:
+        text_parts.append(f"# Action Examples\n{examples_text}")
+    if call_examples_text:
+        text_parts.append(f"# Action Call Examples (with <params>)\n{call_examples_text}")
+
+    return ProviderResult(
+        text="\n\n".join(text_parts),
+        values={
+            "actionNames": action_names,
+            "actionCount": len(validated_actions),
+        },
+        data={
+            "actions": [
+                {
+                    "name": a.name,
+                    "description": a.description,
+                    "examples": [
+                        [
+                            {
+                                "name": ex.name,
+                                "content": ex.content.model_dump(),
+                            }
+                            for ex in example
+                        ]
+                        for example in (a.examples or [])
+                    ],
+                    "parameters": [
+                        {
+                            "name": p.name,
+                            "description": p.description,
+                            "required": bool(p.required),
+                            "examples": getattr(p, "examples", None) or [],
+                            "schema": (
+                                p.schema_def.model_dump()
+                                if hasattr(p, "schema_def") and hasattr(p.schema_def, "model_dump")
+                                else getattr(p, "schema", None)
+                            ),
+                        }
+                        for p in (a.parameters or [])
+                    ],
+                }
+                for a in validated_actions
+            ],
+        },
+    )
+
+
+actions_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_actions,
+    position=_spec.get("position", -1),
+)

package/elizaos/bootstrap/providers/agent_settings.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.generated.spec_helpers import require_provider_spec
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+# Get text content from centralized specs
+_spec = require_provider_spec("AGENT_SETTINGS")
+
+SENSITIVE_KEY_PATTERNS = (
+    "key",
+    "secret",
+    "password",
+    "token",
+    "credential",
+    "auth",
+    "private",
+)
+
+
+async def get_agent_settings_context(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    all_settings = runtime.get_all_settings()
+
+    safe_settings: dict[str, str] = {}
+    for key, value in all_settings.items():
+        if not any(pattern in key.lower() for pattern in SENSITIVE_KEY_PATTERNS):
+            safe_settings[key] = str(value)
+
+    sections: list[str] = []
+    if safe_settings:
+        sections.append("# Agent Settings")
+        for key, value in safe_settings.items():
+            display_value = value if len(value) <= 50 else value[:50] + "..."
+            sections.append(f"- {key}: {display_value}")
+
+    context_text = "\n".join(sections) if sections else ""
+
+    return ProviderResult(
+        text=context_text,
+        values={
+            "settingsCount": len(safe_settings),
+            "hasSettings": len(safe_settings) > 0,
+        },
+        data={
+            "settings": safe_settings,
+        },
+    )
+
+
+agent_settings_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_agent_settings_context,
+    dynamic=_spec.get("dynamic", True),
+)

package/elizaos/bootstrap/providers/attachments.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.generated.spec_helpers import require_provider_spec
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+# Get text content from centralized specs
+_spec = require_provider_spec("ATTACHMENTS")
+
+
+def format_attachment(attachment: dict[str, str]) -> str:
+    att_type = attachment.get("type", "unknown")
+    url = attachment.get("url", "")
+    title = attachment.get("title", "")
+    description = attachment.get("description", "")
+
+    parts = [f"- Type: {att_type}"]
+    if title:
+        parts.append(f"  Title: {title}")
+    if description:
+        parts.append(f"  Description: {description}")
+    if url:
+        parts.append(f"  URL: {url}")
+
+    return "\n".join(parts)
+
+
+async def get_attachments(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    attachments: list[dict[str, str]] = []
+
+    if message.content and hasattr(message.content, "attachments"):
+        raw_attachments = message.content.attachments or []
+        for att in raw_attachments:
+            if isinstance(att, dict):
+                attachments.append(att)
+            elif hasattr(att, "__dict__"):
+                attachments.append(att.__dict__)
+
+    if not attachments:
+        return ProviderResult(
+            text="",
+            values={"hasAttachments": False, "attachmentCount": 0},
+            data={"attachments": []},
+        )
+
+    formatted_attachments = "\n".join(format_attachment(att) for att in attachments)
+
+    text = f"# Attachments ({len(attachments)})\n{formatted_attachments}"
+
+    return ProviderResult(
+        text=text,
+        values={
+            "hasAttachments": True,
+            "attachmentCount": len(attachments),
+            "attachmentTypes": list({att.get("type", "unknown") for att in attachments}),
+        },
+        data={
+            "attachments": attachments,
+        },
+    )
+
+
+attachments_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_attachments,
+    dynamic=_spec.get("dynamic", True),
+)

package/elizaos/bootstrap/providers/capabilities.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.generated.spec_helpers import require_provider_spec
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+# Get text content from centralized specs
+_spec = require_provider_spec("CAPABILITIES")
+
+
+async def get_capabilities(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    model_types = ["TEXT_LARGE", "TEXT_SMALL", "TEXT_EMBEDDING", "IMAGE", "AUDIO"]
+    available_models = [mt for mt in model_types if runtime.has_model(mt)]
+    service_names = [s.name for s in runtime.services if hasattr(s, "name")]
+
+    features: list[str] = []
+    if runtime.get_setting("ENABLE_VOICE"):
+        features.append("voice")
+    if runtime.get_setting("ENABLE_VISION"):
+        features.append("vision")
+    if runtime.get_setting("ENABLE_MEMORY"):
+        features.append("long_term_memory")
+
+    capabilities: dict[str, list[str] | bool] = {
+        "models": available_models,
+        "services": service_names,
+        "features": features,
+    }
+
+    text_parts: list[str] = ["# Agent Capabilities"]
+
+    if available_models:
+        text_parts.append(f"Models: {', '.join(available_models)}")
+
+    if service_names:
+        text_parts.append(f"Services: {', '.join(service_names)}")
+
+    if features:
+        text_parts.append(f"Features: {', '.join(features)}")
+
+    return ProviderResult(
+        text="\n".join(text_parts),
+        values={
+            "modelCount": len(available_models),
+            "serviceCount": len(service_names),
+            "hasVoice": "voice" in features,
+            "hasVision": "vision" in features,
+        },
+        data=capabilities,
+    )
+
+
+capabilities_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_capabilities,
+    dynamic=_spec.get("dynamic", False),
+)

package/elizaos/bootstrap/providers/character.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from elizaos.generated.spec_helpers import require_provider_spec
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+# Get text content from centralized specs
+_spec = require_provider_spec("CHARACTER")
+
+
+def _to_str_list(value: str | Iterable[str] | None) -> list[str]:
+    """
+    Normalize a value to list[str].
+
+    Handles str, list, tuple, set, or any Iterable[str].
+    Returns empty list for None.
+
+    WHY: Character fields can be str | list[str] | tuple[str] depending on
+    how they're defined. This helper ensures consistent handling regardless
+    of the input type, avoiding issues like tuples being treated as scalars.
+    """
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    # Any other iterable (list, tuple, set, etc.) - convert to list
+    return list(value)
+
+
+def _to_str_list(value: str | Iterable[str] | None) -> list[str]:
+    """
+    Normalize a value to list[str].
+
+    Handles str, list, tuple, set, or any Iterable[str].
+    Returns empty list for None.
+
+    WHY: Character fields can be str | list[str] | tuple[str] depending on
+    how they're defined. This helper ensures consistent handling regardless
+    of the input type, avoiding issues like tuples being treated as scalars.
+    """
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    # Any other iterable (list, tuple, set, etc.) - convert to list
+    return list(value)
+
+
+async def get_character_context(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    character = runtime.character
+
+    sections: list[str] = []
+
+    sections.append(f"# Agent: {character.name}")
+
+    bio = getattr(character, "bio", None)
+    if bio:
+        bio_list = _to_str_list(bio)
+        sections.append(f"\n## Bio\n{chr(10).join(bio_list)}")
+
+    adjectives = getattr(character, "adjectives", None)
+    if adjectives:
+        adjectives_list = _to_str_list(adjectives)
+        sections.append(f"\n## Personality Traits\n{', '.join(adjectives_list)}")
+
+    # lore is optional and may not exist on all Character instances
+    lore = getattr(character, "lore", None)
+    if lore:
+        lore_list = _to_str_list(lore)
+        sections.append(f"\n## Background\n{chr(10).join(lore_list)}")
+
+    topics = getattr(character, "topics", None)
+    if topics:
+        topics_list = _to_str_list(topics)
+        sections.append(f"\n## Knowledge Areas\n{', '.join(topics_list)}")
+
+    style = getattr(character, "style", None)
+    if style:
+        style_sections: list[str] = []
+        style_all = getattr(style, "all", None)
+        if style_all:
+            all_style = _to_str_list(style_all)
+            style_sections.append(f"General: {', '.join(all_style)}")
+        style_chat = getattr(style, "chat", None)
+        if style_chat:
+            chat_style = _to_str_list(style_chat)
+            style_sections.append(f"Chat: {', '.join(chat_style)}")
+        style_post = getattr(style, "post", None)
+        if style_post:
+            post_style = _to_str_list(style_post)
+            style_sections.append(f"Posts: {', '.join(post_style)}")
+        if style_sections:
+            sections.append("\n## Communication Style\n" + "\n".join(style_sections))
+
+    context_text = "\n".join(sections)
+
+    # Use variables retrieved via getattr above to avoid AttributeError
+    # if these optional attributes are missing from the character object
+    return ProviderResult(
+        text=context_text,
+        values={
+            "agentName": character.name,
+            "hasCharacter": True,
+        },
+        data={
+            "name": character.name,
+            "bio": bio,
+            "adjectives": adjectives,
+            "topics": topics,
+        },
+    )
+
+
+character_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_character_context,
+    dynamic=_spec.get("dynamic", False),
+)

package/elizaos/bootstrap/providers/choice.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.generated.spec_helpers import require_provider_spec
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+# Get text content from centralized specs
+_spec = require_provider_spec("CHOICE")
+
+
+def format_choice(index: int, choice: dict[str, str]) -> str:
+    label = choice.get("label", f"Option {index + 1}")
+    description = choice.get("description", "")
+    value = choice.get("value", str(index))
+
+    if description:
+        return f"{index + 1}. [{value}] {label}: {description}"
+    return f"{index + 1}. [{value}] {label}"
+
+
+async def get_choice_options(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    choices: list[dict[str, str]] = []
+
+    if message.content and hasattr(message.content, "choices"):
+        raw_choices = message.content.choices or []
+        for choice in raw_choices:
+            if isinstance(choice, dict):
+                choices.append(choice)
+            elif isinstance(choice, str):
+                choices.append({"label": choice, "value": choice})
+
+    if state and hasattr(state, "choices"):
+        state_choices = state.choices or []
+        for choice in state_choices:
+            if isinstance(choice, dict):
+                choices.append(choice)
+            elif isinstance(choice, str):
+                choices.append({"label": choice, "value": choice})
+
+    if not choices:
+        return ProviderResult(
+            text="",
+            values={"hasChoices": False, "choiceCount": 0},
+            data={"choices": []},
+        )
+
+    formatted_choices = "\n".join(format_choice(i, choice) for i, choice in enumerate(choices))
+
+    text = f"# Available Choices\n{formatted_choices}"
+
+    return ProviderResult(
+        text=text,
+        values={
+            "hasChoices": True,
+            "choiceCount": len(choices),
+            "choiceLabels": [c.get("label", "") for c in choices],
+        },
+        data={
+            "choices": choices,
+        },
+    )
+
+
+choice_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_choice_options,
+    dynamic=_spec.get("dynamic", True),
+)