@elizaos/python 2.0.0-alpha.10

package/elizaos/basic_capabilities/providers/actions.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from google.protobuf.json_format import MessageToDict
+
+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:
+        # Support both validate and validate_fn for backwards compatibility
+        validate_fn = getattr(action, "validate", None) or getattr(action, "validate_fn", None)
+        if validate_fn:
+            is_valid = await validate_fn(runtime, message, state)
+            if is_valid:
+                validated_actions.append(action)
+        else:
+            # If no validation function, include the action
+            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": MessageToDict(
+                                    ex.content, preserving_proto_field_name=False
+                                ),
+                            }
+                            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": MessageToDict(p.schema, preserving_proto_field_name=False)
+                            if hasattr(p, "schema") and p.schema.ByteSize() > 0
+                            else (getattr(p, "schema_def", None) or 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/basic_capabilities/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/basic_capabilities/providers/capabilities.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+
+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="CAPABILITIES",
+    description="Agent capabilities including models, services, and features",
+    get=get_capabilities,
+    dynamic=False,
+)

package/elizaos/basic_capabilities/providers/character.py

@@ -0,0 +1,113 @@
+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("CHARACTER")
+
+
+def _resolve_name(text: str, name: str) -> str:
+    """Replace ``{{name}}`` placeholders with the character's name.
+
+    Supports character template files where the name is injected at render
+    time so changing the character's name doesn't require rewriting every
+    field.
+    """
+    return text.replace("{{name}}", name)
+
+
+def _resolve_name_list(items: list[str], name: str) -> list[str]:
+    """Resolve ``{{name}}`` in every element of a string list."""
+    return [_resolve_name(s, name) for s in items]
+
+
+async def get_character_context(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    character = runtime.character
+    agent_name: str = character.name
+
+    sections: list[str] = []
+
+    sections.append(f"# Agent: {agent_name}")
+
+    if character.bio:
+        if isinstance(character.bio, str):
+            bio_text = _resolve_name(character.bio, agent_name)
+        else:
+            bio_text = "\n".join(_resolve_name_list(list(character.bio), agent_name))
+        sections.append(f"\n## Bio\n{bio_text}")
+
+    if character.adjectives:
+        adjectives = (
+            character.adjectives
+            if isinstance(character.adjectives, list)
+            else [character.adjectives]
+        )
+        resolved_adjectives = _resolve_name_list(adjectives, agent_name)
+        sections.append(f"\n## Personality Traits\n{', '.join(resolved_adjectives)}")
+
+    # lore is optional and may not exist on all Character instances
+    lore = getattr(character, "lore", None)
+    if lore:
+        if isinstance(lore, str):
+            lore_text = _resolve_name(lore, agent_name)
+        else:
+            lore_text = "\n".join(_resolve_name_list(list(lore), agent_name))
+        sections.append(f"\n## Background\n{lore_text}")
+
+    if character.topics:
+        topics = character.topics if isinstance(character.topics, list) else [character.topics]
+        resolved_topics = _resolve_name_list(topics, agent_name)
+        sections.append(f"\n## Knowledge Areas\n{', '.join(resolved_topics)}")
+
+    if character.style:
+        style_sections: list[str] = []
+        if character.style.all:
+            all_style = (
+                character.style.all
+                if isinstance(character.style.all, list)
+                else [character.style.all]
+            )
+            resolved_all = _resolve_name_list(all_style, agent_name)
+            style_sections.append(f"General: {', '.join(resolved_all)}")
+        if character.style.chat:
+            chat_style = (
+                character.style.chat
+                if isinstance(character.style.chat, list)
+                else [character.style.chat]
+            )
+            resolved_chat = _resolve_name_list(chat_style, agent_name)
+            style_sections.append(f"Chat: {', '.join(resolved_chat)}")
+        if character.style.post:
+            post_style = (
+                character.style.post
+                if isinstance(character.style.post, list)
+                else [character.style.post]
+            )
+            resolved_post = _resolve_name_list(post_style, agent_name)
+            style_sections.append(f"Posts: {', '.join(resolved_post)}")
+        if style_sections:
+            sections.append("\n## Communication Style\n" + "\n".join(style_sections))
+
+    context_text = "\n".join(sections)
+
+    # Note: Protobuf ProviderResult.data is a Struct which has limited type support.
+    # The text already contains all the information needed for the agent context.
+    return ProviderResult(text=context_text)
+
+
+character_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_character_context,
+    dynamic=_spec.get("dynamic", False),
+)

package/elizaos/basic_capabilities/providers/choice.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+
+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="CHOICE",
+    description="Available choice options for selection",
+    get=get_choice_options,
+    dynamic=True,
+)

package/elizaos/basic_capabilities/providers/context_bench.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.types import Provider, ProviderResult
+
+if TYPE_CHECKING:
+    from elizaos.types import IAgentRuntime, Memory, State
+
+
+async def get_context_bench(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    _ = runtime
+    _ = state
+    meta = getattr(message, "metadata", None)
+    bench_ctx = None
+    if meta is not None:
+        maybe = getattr(meta, "benchmarkContext", None)
+        if isinstance(maybe, str) and maybe.strip():
+            bench_ctx = maybe.strip()
+
+    if not bench_ctx:
+        return ProviderResult(
+            text="",
+            values={"benchmark_has_context": False},
+            data={},
+        )
+
+    return ProviderResult(
+        text=f"# Benchmark Context\n{bench_ctx}",
+        values={"benchmark_has_context": True},
+        data={"benchmarkContext": bench_ctx},
+    )
+
+
+context_bench_provider = Provider(
+    name="CONTEXT_BENCH",
+    description="Benchmark/task context injected by a benchmark harness",
+    get=get_context_bench,
+    dynamic=True,
+)

package/elizaos/basic_capabilities/providers/current_time.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+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("CURRENT_TIME")
+
+
+async def get_current_time_context(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | None = None,
+) -> ProviderResult:
+    _ = runtime, message, state
+
+    now = datetime.now(UTC)
+
+    iso_timestamp = now.isoformat()
+    human_readable = now.strftime("%A, %B %d, %Y at %H:%M:%S UTC")
+    date_only = now.strftime("%Y-%m-%d")
+    time_only = now.strftime("%H:%M:%S")
+    day_of_week = now.strftime("%A")
+    unix_timestamp = int(now.timestamp())
+
+    context_text = f"# Current Time\n- Date: {date_only}\n- Time: {time_only} UTC\n- Day: {day_of_week}\n- Full: {human_readable}\n- ISO: {iso_timestamp}"
+
+    return ProviderResult(
+        text=context_text,
+        values={
+            "currentTime": iso_timestamp,
+            "currentDate": date_only,
+            "dayOfWeek": day_of_week,
+            "unixTimestamp": unix_timestamp,
+        },
+        data={
+            "iso": iso_timestamp,
+            "date": date_only,
+            "time": time_only,
+            "dayOfWeek": day_of_week,
+            "humanReadable": human_readable,
+            "unixTimestamp": unix_timestamp,
+        },
+    )
+
+
+current_time_provider = Provider(
+    name=_spec["name"],
+    description=_spec["description"],
+    get=get_current_time_context,
+    dynamic=_spec.get("dynamic", True),
+)