@elizaos/python 2.0.0-alpha.10

package/elizaos/types/service_interfaces.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import Any
+
+from elizaos.types.generated.eliza.v1 import service_interfaces_pb2
+
+TokenBalance = service_interfaces_pb2.TokenBalance
+TokenData = service_interfaces_pb2.TokenData
+WalletAsset = service_interfaces_pb2.WalletAsset
+WalletPortfolio = service_interfaces_pb2.WalletPortfolio
+PoolTokenInfo = service_interfaces_pb2.PoolTokenInfo
+PoolInfo = service_interfaces_pb2.PoolInfo
+LpPositionDetails = service_interfaces_pb2.LpPositionDetails
+TransactionResult = service_interfaces_pb2.TransactionResult
+TranscriptionOptions = service_interfaces_pb2.TranscriptionOptions
+TranscriptionSegment = service_interfaces_pb2.TranscriptionSegment
+TranscriptionWord = service_interfaces_pb2.TranscriptionWord
+TranscriptionResult = service_interfaces_pb2.TranscriptionResult
+SpeechToTextOptions = service_interfaces_pb2.SpeechToTextOptions
+TextToSpeechOptions = service_interfaces_pb2.TextToSpeechOptions
+VideoFormat = service_interfaces_pb2.VideoFormat
+VideoInfo = service_interfaces_pb2.VideoInfo
+VideoDownloadOptions = service_interfaces_pb2.VideoDownloadOptions
+VideoProcessingOptions = service_interfaces_pb2.VideoProcessingOptions
+BrowserViewport = service_interfaces_pb2.BrowserViewport
+BrowserNavigationOptions = service_interfaces_pb2.BrowserNavigationOptions
+ScreenshotClip = service_interfaces_pb2.ScreenshotClip
+ScreenshotOptions = service_interfaces_pb2.ScreenshotOptions
+ElementSelector = service_interfaces_pb2.ElementSelector
+ExtractedLink = service_interfaces_pb2.LinkInfo
+ExtractedImage = service_interfaces_pb2.ImageInfo
+ExtractedContent = service_interfaces_pb2.ExtractedContent
+ClickOptions = service_interfaces_pb2.ClickOptions
+TypeOptions = service_interfaces_pb2.TypeOptions
+PdfMetadata = service_interfaces_pb2.PdfMetadata
+PdfExtractionResult = service_interfaces_pb2.PdfExtractionResult
+PdfMargins = service_interfaces_pb2.PdfMargins
+PdfGenerationOptions = service_interfaces_pb2.PdfGenerationOptions
+PdfConversionOptions = service_interfaces_pb2.PdfConversionOptions
+SearchDateRange = service_interfaces_pb2.DateRange
+WebSearchBaseOptions = service_interfaces_pb2.SearchOptions
+SearchResult = service_interfaces_pb2.SearchResult
+SearchResponse = service_interfaces_pb2.SearchResponse
+NewsSearchOptions = service_interfaces_pb2.NewsSearchOptions
+ImageSearchOptions = service_interfaces_pb2.ImageSearchOptions
+VideoSearchOptions = service_interfaces_pb2.VideoSearchOptions
+EmailAddress = service_interfaces_pb2.EmailAddress
+EmailAttachment = service_interfaces_pb2.EmailAttachment
+EmailMessage = service_interfaces_pb2.EmailMessage
+EmailSendOptions = service_interfaces_pb2.EmailSendOptions
+EmailSearchOptions = service_interfaces_pb2.EmailSearchOptions
+EmailFolder = service_interfaces_pb2.EmailFolder
+EmailAccount = service_interfaces_pb2.EmailAccount
+MessageParticipant = service_interfaces_pb2.MessageParticipant
+MessageAttachment = service_interfaces_pb2.MessageAttachment
+MessageReaction = service_interfaces_pb2.MessageReaction
+MessageReference = service_interfaces_pb2.MessageReference
+EmbedField = service_interfaces_pb2.EmbedField
+MessageEmbed = service_interfaces_pb2.MessageEmbed
+MessageContent = service_interfaces_pb2.MessageContent
+MessageThread = service_interfaces_pb2.MessageThreadInfo
+MessageInfo = service_interfaces_pb2.MessageInfo
+MessageSendOptions = service_interfaces_pb2.MessageSendOptions
+MessageSearchOptions = service_interfaces_pb2.MessageSearchOptions
+ChannelPermissions = service_interfaces_pb2.ChannelPermissions
+MessageChannel = service_interfaces_pb2.MessageChannel
+PostMedia = service_interfaces_pb2.PostMedia
+PostLocation = service_interfaces_pb2.PostLocation
+PostAuthor = service_interfaces_pb2.PostAuthor
+PostEngagement = service_interfaces_pb2.PostEngagement
+PostLinkPreview = service_interfaces_pb2.PostLinkPreview
+PollOption = service_interfaces_pb2.PostPollOption
+PostPoll = service_interfaces_pb2.PostPoll
+PostContent = service_interfaces_pb2.PostContent
+PostThread = service_interfaces_pb2.PostThreadInfo
+CrossPostedInfo = service_interfaces_pb2.CrossPostInfo
+PostInfo = service_interfaces_pb2.PostInfo
+PostCreateOptions = service_interfaces_pb2.PostCreateOptions
+PostSearchOptions = service_interfaces_pb2.PostSearchOptions
+DemographicsData = service_interfaces_pb2.Demographics
+PerformingHour = service_interfaces_pb2.TopPerformingHour
+PostAnalytics = service_interfaces_pb2.PostAnalytics
+
+
+# Types not in protobuf - define as dataclasses
+@dataclass
+class VoiceInfo:
+    """Voice information for text-to-speech."""
+
+    voice_id: str
+    name: str
+    language: str | None = None
+    gender: str | None = None
+    provider: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PageInfo:
+    """Pagination information for search results."""
+
+    page: int = 1
+    per_page: int = 10
+    total: int = 0
+    has_more: bool = False
+
+
+class ITokenDataService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IWalletService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class ILpService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class ITranscriptionService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IVideoService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IBrowserService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IPdfService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IWebSearchService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IEmailService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IMessagingService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+class IPostService(ABC):
+    """Runtime service interface (implementation-specific)."""
+
+
+__all__ = [
+    "TokenBalance",
+    "TokenData",
+    "WalletAsset",
+    "WalletPortfolio",
+    "PoolTokenInfo",
+    "PoolInfo",
+    "LpPositionDetails",
+    "TransactionResult",
+    "TranscriptionOptions",
+    "TranscriptionSegment",
+    "TranscriptionWord",
+    "TranscriptionResult",
+    "SpeechToTextOptions",
+    "TextToSpeechOptions",
+    "VoiceInfo",
+    "VideoFormat",
+    "VideoInfo",
+    "VideoDownloadOptions",
+    "VideoProcessingOptions",
+    "BrowserViewport",
+    "BrowserNavigationOptions",
+    "ScreenshotClip",
+    "ScreenshotOptions",
+    "ElementSelector",
+    "ExtractedLink",
+    "ExtractedImage",
+    "ExtractedContent",
+    "ClickOptions",
+    "TypeOptions",
+    "PdfMetadata",
+    "PdfExtractionResult",
+    "PdfMargins",
+    "PdfGenerationOptions",
+    "PdfConversionOptions",
+    "SearchDateRange",
+    "WebSearchBaseOptions",
+    "SearchResult",
+    "SearchResponse",
+    "NewsSearchOptions",
+    "ImageSearchOptions",
+    "VideoSearchOptions",
+    "PageInfo",
+    "EmailAddress",
+    "EmailAttachment",
+    "EmailMessage",
+    "EmailSendOptions",
+    "EmailSearchOptions",
+    "EmailFolder",
+    "EmailAccount",
+    "MessageParticipant",
+    "MessageAttachment",
+    "MessageReaction",
+    "MessageReference",
+    "EmbedField",
+    "MessageEmbed",
+    "MessageContent",
+    "MessageThread",
+    "MessageInfo",
+    "MessageSendOptions",
+    "MessageSearchOptions",
+    "ChannelPermissions",
+    "MessageChannel",
+    "PostMedia",
+    "PostLocation",
+    "PostAuthor",
+    "PostEngagement",
+    "PostLinkPreview",
+    "PollOption",
+    "PostPoll",
+    "PostContent",
+    "PostThread",
+    "CrossPostedInfo",
+    "PostInfo",
+    "PostCreateOptions",
+    "PostSearchOptions",
+    "DemographicsData",
+    "PerformingHour",
+    "PostAnalytics",
+    "ITokenDataService",
+    "IWalletService",
+    "ILpService",
+    "ITranscriptionService",
+    "IVideoService",
+    "IBrowserService",
+    "IPdfService",
+    "IWebSearchService",
+    "IEmailService",
+    "IMessagingService",
+    "IPostService",
+]

package/elizaos/types/state.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+from elizaos.types.generated.eliza.v1 import state_pb2
+
+ActionPlanStep = state_pb2.ActionPlanStep
+ActionPlan = state_pb2.ActionPlan
+ProviderCacheEntry = state_pb2.ProviderCacheEntry
+WorkingMemoryItem = state_pb2.WorkingMemoryItem
+StateData = state_pb2.StateData
+StateValues = state_pb2.StateValues
+State = state_pb2.State
+
+
+# ============================================================================
+# Dynamic Prompt Execution Types
+# ============================================================================
+
+
+@dataclass
+class SchemaRow:
+    """Schema row for dynamic prompt execution.
+
+    WHY: dynamic_prompt_exec_from_state generates structured prompts that ask the LLM
+    to output specific fields. Each SchemaRow defines one field the LLM must produce.
+    The schema also controls validation behavior for streaming scenarios.
+
+    Example:
+        schema = [
+            SchemaRow("thought", "Your internal reasoning"),
+            SchemaRow("text", "Response to user", required=True),
+            SchemaRow("actions", "Actions to execute"),
+        ]
+    """
+
+    field: str
+    """Field name - will become an XML tag or JSON property"""
+
+    description: str
+    """Description shown to LLM - explains what to put in this field"""
+
+    required: bool = False
+    """If true, validation fails when field is empty/missing"""
+
+    validate_field: bool | None = None
+    """Control per-field validation codes for streaming (levels 0-1 only).
+
+    WHY: Validation codes are UUID snippets that surround each field. If the LLM
+    outputs the same code before and after a field, we know the context window
+    wasn't truncated mid-field. This trades off token usage for reliability.
+
+    Behavior by level:
+    - Level 0 (Trusted): default False. Set to True to opt-in to per-field codes.
+    - Level 1 (Progressive): default True. Set to False to opt-out of codes.
+    - Levels 2-3: ignored (uses checkpoint codes at start/end of response instead).
+    """
+
+    stream_field: bool | None = None
+    """Control whether this field's content is streamed to the consumer.
+
+    WHY: Not all fields should be shown to users in real-time:
+    - 'thought': Internal reasoning - might be verbose or confusing to show
+    - 'actions': System field for action routing - not user-visible
+    - 'text': The actual response - should definitely stream
+
+    Default: True for 'text' field, False for others.
+    """
+
+
+@dataclass
+class RetryBackoffConfig:
+    """Configuration for retry backoff timing.
+
+    WHY: When retries happen, immediate retries can:
+    - Overwhelm rate-limited APIs
+    - Hit transient failures repeatedly
+    - Waste resources on brief outages
+
+    Backoff gives the system time to recover between attempts.
+    """
+
+    initial_ms: int = 1000
+    """Initial delay in milliseconds before first retry. Default: 1000ms (1 second)"""
+
+    multiplier: float = 2.0
+    """Multiplier for exponential backoff. delay = initial_ms * multiplier^(retry_count - 1). Default: 2"""
+
+    max_ms: int = 30000
+    """Maximum delay in milliseconds. Caps exponential growth. Default: 30000ms (30 seconds)"""
+
+    def delay_for_retry(self, retry_count: int) -> int:
+        """Calculate the delay for a given retry attempt (1-indexed)."""
+        delay = self.initial_ms * (self.multiplier ** (retry_count - 1))
+        return min(int(delay), self.max_ms)
+
+
+class StreamEventType(str, Enum):
+    """Stream event types for validation-aware streaming.
+
+    Rich consumers receive these typed events for custom UX handling.
+    """
+
+    CHUNK = "chunk"
+    """Regular content chunk being streamed"""
+
+    FIELD_VALIDATED = "field_validated"
+    """A field passed validation (level 1)"""
+
+    RETRY_START = "retry_start"
+    """Starting a retry attempt"""
+
+    ERROR = "error"
+    """Unrecoverable error occurred"""
+
+    COMPLETE = "complete"
+    """Successfully finished all validation"""
+
+
+@dataclass
+class StreamEvent:
+    """Rich stream event for sophisticated consumers.
+
+    WHY: Simple consumers just want text chunks. Advanced UIs want to know
+    about validation progress, retries, and errors to show appropriate UI
+    (spinners, clear partial content, error messages).
+    """
+
+    event_type: StreamEventType
+    """Event type"""
+
+    timestamp: int = field(default_factory=lambda: int(time.time() * 1000))
+    """Timestamp of the event (milliseconds since epoch)"""
+
+    field: str | None = None
+    """Field name (for chunk and field_validated events)"""
+
+    chunk: str | None = None
+    """Content chunk (for chunk events)"""
+
+    retry_count: int | None = None
+    """Retry attempt number (for retry_start events)"""
+
+    error: str | None = None
+    """Error message (for error events)"""
+
+    @classmethod
+    def chunk_event(cls, field: str, chunk: str) -> StreamEvent:
+        """Create a chunk event."""
+        return cls(event_type=StreamEventType.CHUNK, field=field, chunk=chunk)
+
+    @classmethod
+    def field_validated_event(cls, field: str) -> StreamEvent:
+        """Create a field_validated event."""
+        return cls(event_type=StreamEventType.FIELD_VALIDATED, field=field)
+
+    @classmethod
+    def retry_start_event(cls, retry_count: int) -> StreamEvent:
+        """Create a retry_start event."""
+        return cls(event_type=StreamEventType.RETRY_START, retry_count=retry_count)
+
+    @classmethod
+    def error_event(cls, message: str) -> StreamEvent:
+        """Create an error event."""
+        return cls(event_type=StreamEventType.ERROR, error=message)
+
+    @classmethod
+    def complete_event(cls) -> StreamEvent:
+        """Create a complete event."""
+        return cls(event_type=StreamEventType.COMPLETE)
+
+
+__all__ = [
+    "ActionPlanStep",
+    "ActionPlan",
+    "ProviderCacheEntry",
+    "WorkingMemoryItem",
+    "StateData",
+    "StateValues",
+    "State",
+    # Dynamic prompt execution types
+    "SchemaRow",
+    "RetryBackoffConfig",
+    "StreamEventType",
+    "StreamEvent",
+]

package/elizaos/types/task.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from elizaos.types.generated.eliza.v1 import task_pb2
+
+if TYPE_CHECKING:
+    from elizaos.types.runtime import IAgentRuntime
+
+Task = task_pb2.Task
+TaskMetadata = task_pb2.TaskMetadata
+TaskStatus = task_pb2.TaskStatus
+
+
+# Runtime worker interface (not in proto)
+@runtime_checkable
+class TaskWorker(Protocol):
+    name: str
+
+    def __call__(
+        self,
+        runtime: IAgentRuntime,
+        params: dict[str, object],
+        task: Task,
+    ) -> Awaitable[None]: ...
+
+
+__all__ = ["Task", "TaskMetadata", "TaskStatus", "TaskWorker"]

package/elizaos/utils/__init__.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from collections.abc import Mapping
+
+from google.protobuf.json_format import MessageToDict
+from google.protobuf.message import Message
+
+from elizaos.types.agent import TemplateType
+from elizaos.types.state import State
+
+# Re-export from spec_examples for convenience
+from .spec_examples import convert_spec_examples
+
+# Re-export streaming utilities for validation-aware streaming
+from .streaming import (
+    MAX_CHUNK_SIZE,
+    ChunkSizeError,
+    ExtractorState,
+    FieldState,
+    IStreamExtractor,
+    MarkableExtractor,
+    ValidationDiagnosis,
+    ValidationStreamExtractor,
+    ValidationStreamExtractorConfig,
+    validate_chunk_size,
+)
+
+_TEMPLATE_TOKEN_RE = re.compile(r"\{\{\{?\s*([A-Za-z0-9_.-]+)\s*\}\}\}?")
+
+
+def get_current_time_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _to_dict(value: object) -> dict[str, object]:
+    if isinstance(value, Message):
+        return MessageToDict(value, preserving_proto_field_name=False)
+    if hasattr(value, "model_dump"):
+        return value.model_dump(by_alias=True)
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise TypeError(f"Unsupported value type: {type(value).__name__}")
+
+
+def _stringify_template_value(value: object) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (Message, Mapping)) or hasattr(value, "model_dump"):
+        return json.dumps(_to_dict(value), ensure_ascii=False)
+    if isinstance(value, list):
+        return "\n".join(_stringify_template_value(v) for v in value)
+    return str(value)
+
+
+def _render_template(template_str: str, ctx: Mapping[str, object]) -> str:
+    def replacer(match: re.Match[str]) -> str:
+        key = match.group(1)
+        return _stringify_template_value(ctx.get(key))
+
+    return _TEMPLATE_TOKEN_RE.sub(replacer, template_str)
+
+
+def compose_prompt(*, state: Mapping[str, str], template: TemplateType) -> str:
+    template_str = template({"state": state}) if callable(template) else template
+    return _render_template(template_str, state)
+
+
+def compose_prompt_from_state(*, state: State, template: TemplateType) -> str:
+    template_str = template({"state": state}) if callable(template) else template
+
+    dumped = _to_dict(state)
+    values_raw = dumped.get("values")
+    values: dict[str, object] = values_raw if isinstance(values_raw, dict) else {}
+
+    ctx: dict[str, object] = {
+        k: v for k, v in dumped.items() if k not in ("text", "values", "data")
+    }
+    ctx.update(values)
+
+    return _render_template(template_str, ctx)
+
+
+__all__ = [
+    "get_current_time_ms",
+    "compose_prompt",
+    "compose_prompt_from_state",
+    "convert_spec_examples",
+    # Streaming utilities
+    "ChunkSizeError",
+    "ExtractorState",
+    "FieldState",
+    "IStreamExtractor",
+    "MarkableExtractor",
+    "MAX_CHUNK_SIZE",
+    "validate_chunk_size",
+    "ValidationDiagnosis",
+    "ValidationStreamExtractor",
+    "ValidationStreamExtractorConfig",
+]

package/elizaos/utils/spec_examples.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+from elizaos.types import ActionExample, Content
+
+if TYPE_CHECKING:
+    from elizaos.generated.action_docs import ActionDoc
+
+
+def _coerce_text(value: object) -> str:
+    return value if isinstance(value, str) else ""
+
+
+def _coerce_actions(value: object) -> list[str] | None:
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return list(value)
+    return None
+
+
+def convert_spec_examples(spec: ActionDoc | Mapping[str, object]) -> list[list[ActionExample]]:
+    examples = spec.get("examples")
+    if not isinstance(examples, list):
+        return []
+    out: list[list[ActionExample]] = []
+    for example in examples:
+        if not isinstance(example, list):
+            continue
+        row: list[ActionExample] = []
+        for msg in example:
+            if not isinstance(msg, dict):
+                continue
+            content = msg.get("content")
+            text = ""
+            actions: list[str] | None = None
+            if isinstance(content, dict):
+                text = _coerce_text(content.get("text"))
+                actions = _coerce_actions(content.get("actions"))
+            row.append(
+                ActionExample(
+                    name=str(msg.get("name") or ""),
+                    content=Content(text=text, actions=actions),
+                )
+            )
+        if row:
+            out.append(row)
+    return out