@elizaos/python 2.0.0-alpha.10

package/elizaos/types/model.py

@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+
+
+class LLMMode(str, Enum):
+    DEFAULT = "DEFAULT"
+    SMALL = "SMALL"
+    LARGE = "LARGE"
+
+
+class ModelType(str, Enum):
+    # Text generation models
+    TEXT_SMALL = "TEXT_SMALL"
+    TEXT_LARGE = "TEXT_LARGE"
+    TEXT_COMPLETION = "TEXT_COMPLETION"
+
+    # Streaming text generation models
+    TEXT_SMALL_STREAM = "TEXT_SMALL_STREAM"
+    TEXT_LARGE_STREAM = "TEXT_LARGE_STREAM"
+
+    # Reasoning models (note: values are REASONING_*, not TEXT_REASONING_*)
+    TEXT_REASONING_SMALL = "REASONING_SMALL"
+    TEXT_REASONING_LARGE = "REASONING_LARGE"
+
+    # Tokenization models
+    TEXT_TOKENIZER_ENCODE = "TEXT_TOKENIZER_ENCODE"
+    TEXT_TOKENIZER_DECODE = "TEXT_TOKENIZER_DECODE"
+
+    # Embedding models
+    TEXT_EMBEDDING = "TEXT_EMBEDDING"
+
+    # Image models
+    IMAGE = "IMAGE"
+    IMAGE_DESCRIPTION = "IMAGE_DESCRIPTION"
+
+    # Audio models
+    TRANSCRIPTION = "TRANSCRIPTION"
+    TEXT_TO_SPEECH = "TEXT_TO_SPEECH"
+    AUDIO = "AUDIO"
+
+    # Video models
+    VIDEO = "VIDEO"
+
+    # Object generation models
+    OBJECT_SMALL = "OBJECT_SMALL"
+    OBJECT_LARGE = "OBJECT_LARGE"
+
+    # Research models (deep research)
+    RESEARCH = "RESEARCH"
+
+
+# Type for model type names - allows string for extensibility
+ModelTypeName = str
+
+# Union type of text generation model types
+TextGenerationModelType = str  # TEXT_SMALL, TEXT_LARGE, REASONING_*, TEXT_COMPLETION
+
+# ModelHandler uses Any at runtime to avoid circular imports.
+# Type checkers will see the proper type from the TYPE_CHECKING block.
+if TYPE_CHECKING:
+    ModelHandler = Callable[["IAgentRuntime", object], Awaitable[object]]
+else:
+    ModelHandler = Callable[[Any, object], Awaitable[object]]
+
+
+class ModelSettings(BaseModel):
+    """Settings for a specific model type."""
+
+    model: str | None = Field(default=None, description="Model identifier")
+    max_tokens: int | None = Field(default=None, alias="maxTokens", description="Maximum tokens")
+    temperature: float | None = Field(default=None, description="Temperature setting")
+    top_p: float | None = Field(default=None, alias="topP", description="Top P setting")
+    top_k: int | None = Field(default=None, alias="topK", description="Top K setting")
+    min_p: float | None = Field(default=None, alias="minP", description="Minimum P setting")
+    seed: int | None = Field(default=None, description="Random seed for reproducibility")
+    repetition_penalty: float | None = Field(
+        default=None, alias="repetitionPenalty", description="Repetition penalty"
+    )
+    frequency_penalty: float | None = Field(
+        default=None, alias="frequencyPenalty", description="Frequency penalty"
+    )
+    presence_penalty: float | None = Field(
+        default=None, alias="presencePenalty", description="Presence penalty"
+    )
+    stop_sequences: list[str] | None = Field(
+        default=None, alias="stopSequences", description="Stop sequences"
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+# Model parameters map type - maps model types to their parameter types
+ModelParamsMap = dict[ModelType, dict[str, Any]]
+
+# Model result map type - maps model types to their result types
+ModelResultMap = dict[ModelType, Any]
+
+# Stream chunk callback type
+StreamChunkCallback = Callable[[str, str | None], Awaitable[None] | None]
+
+
+class GenerateTextParams(BaseModel):
+    prompt: str = Field(..., description="The input prompt for text generation")
+    max_tokens: int | None = Field(
+        default=None, alias="maxTokens", description="Maximum tokens to generate"
+    )
+    min_tokens: int | None = Field(
+        default=None, alias="minTokens", description="Minimum tokens to generate"
+    )
+    temperature: float | None = Field(default=None, description="Controls randomness (0.0-1.0)")
+    top_p: float | None = Field(
+        default=None, alias="topP", description="Nucleus sampling parameter (0.0-1.0)"
+    )
+    top_k: int | None = Field(
+        default=None, alias="topK", description="Limits highest-probability tokens considered"
+    )
+    min_p: float | None = Field(
+        default=None, alias="minP", description="Minimum probability threshold (0.0-1.0)"
+    )
+    seed: int | None = Field(default=None, description="Random seed for reproducible outputs")
+    repetition_penalty: float | None = Field(
+        default=None, alias="repetitionPenalty", description="Repetition penalty (1.0 = no penalty)"
+    )
+    frequency_penalty: float | None = Field(
+        default=None, alias="frequencyPenalty", description="Penalizes based on frequency"
+    )
+    presence_penalty: float | None = Field(
+        default=None, alias="presencePenalty", description="Penalizes based on presence"
+    )
+    stop_sequences: list[str] | None = Field(
+        default=None, alias="stopSequences", description="Sequences to stop generation"
+    )
+    user: str | None = Field(default=None, description="User identifier for tracking/analytics")
+    response_format: dict[str, str] | str | None = Field(
+        default=None, alias="responseFormat", description="Response format specification"
+    )
+    stream: bool | None = Field(default=None, description="Enable streaming mode")
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+class GenerateTextOptions(BaseModel):
+    """Options for the simplified generateText API."""
+
+    include_character: bool | None = Field(
+        default=None, alias="includeCharacter", description="Include character personality"
+    )
+    model_type: str | None = Field(default=None, alias="modelType", description="Model type to use")
+    max_tokens: int | None = Field(default=None, alias="maxTokens", description="Maximum tokens")
+    temperature: float | None = Field(default=None, description="Temperature")
+    top_p: float | None = Field(default=None, alias="topP", description="Top P setting")
+    frequency_penalty: float | None = Field(
+        default=None, alias="frequencyPenalty", description="Frequency penalty"
+    )
+    presence_penalty: float | None = Field(
+        default=None, alias="presencePenalty", description="Presence penalty"
+    )
+    stop_sequences: list[str] | None = Field(
+        default=None, alias="stopSequences", description="Stop sequences"
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+class GenerateTextResult(BaseModel):
+    text: str = Field(..., description="Generated text")
+
+    model_config = {"populate_by_name": True}
+
+
+class TokenUsage(BaseModel):
+    """Token usage information from a model response."""
+
+    prompt_tokens: int = Field(..., alias="promptTokens", description="Tokens in input prompt")
+    completion_tokens: int = Field(
+        ..., alias="completionTokens", description="Tokens in generated response"
+    )
+    total_tokens: int = Field(..., alias="totalTokens", description="Total tokens used")
+
+    model_config = {"populate_by_name": True}
+
+
+class TextStreamChunk(BaseModel):
+    text: str = Field(..., description="Text chunk")
+    done: bool = Field(default=False, description="Whether this is the final chunk")
+
+    model_config = {"populate_by_name": True}
+
+
+class TokenizeTextParams(BaseModel):
+    prompt: str = Field(..., description="Text to tokenize")
+    model_type: str = Field(..., alias="modelType", description="Model type for tokenization")
+
+    model_config = {"populate_by_name": True}
+
+
+class DetokenizeTextParams(BaseModel):
+    tokens: list[int] = Field(..., description="Tokens to convert to text")
+    model_type: str = Field(..., alias="modelType", description="Model type for detokenization")
+
+    model_config = {"populate_by_name": True}
+
+
+class TextEmbeddingParams(BaseModel):
+    """Parameters for text embedding."""
+
+    text: str = Field(..., description="Text to create embeddings for")
+
+    model_config = {"populate_by_name": True}
+
+
+class ImageGenerationParams(BaseModel):
+    """Parameters for image generation."""
+
+    prompt: str = Field(..., description="Prompt describing the image")
+    size: str | None = Field(default=None, description="Image dimensions")
+    count: int | None = Field(default=None, description="Number of images to generate")
+
+    model_config = {"populate_by_name": True}
+
+
+class ImageDescriptionParams(BaseModel):
+    image_url: str = Field(..., alias="imageUrl", description="URL of the image")
+    prompt: str | None = Field(default=None, description="Optional guiding prompt")
+
+    model_config = {"populate_by_name": True}
+
+
+class ImageDescriptionResult(BaseModel):
+    title: str = Field(..., description="Image title")
+    description: str = Field(..., description="Image description")
+
+    model_config = {"populate_by_name": True}
+
+
+class TranscriptionParams(BaseModel):
+    """Parameters for audio transcription."""
+
+    audio_url: str = Field(..., alias="audioUrl", description="URL of audio file")
+    prompt: str | None = Field(default=None, description="Optional guiding prompt")
+
+    model_config = {"populate_by_name": True}
+
+
+class TextToSpeechParams(BaseModel):
+    text: str = Field(..., description="Text to convert to speech")
+    voice: str | None = Field(default=None, description="Voice to use")
+    speed: float | None = Field(default=None, description="Speaking speed")
+
+    model_config = {"populate_by_name": True}
+
+
+class ObjectGenerationParams(BaseModel):
+    """Parameters for object generation models."""
+
+    prompt: str = Field(..., description="Prompt describing the object")
+    schema_def: dict[str, Any] | None = Field(
+        default=None, alias="schema", description="JSON schema for validation"
+    )
+    output: str | None = Field(
+        default=None, description="Output type: 'object', 'array', or 'enum'"
+    )
+    enum_values: list[str] | None = Field(
+        default=None, alias="enumValues", description="Allowed values for enum type"
+    )
+    model_type: str | None = Field(default=None, alias="modelType", description="Model type")
+    temperature: float | None = Field(default=None, description="Temperature")
+    max_tokens: int | None = Field(default=None, alias="maxTokens", description="Maximum tokens")
+    stop_sequences: list[str] | None = Field(
+        default=None, alias="stopSequences", description="Stop sequences"
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+# ============================================================================
+# Research Model Types (Deep Research)
+# ============================================================================
+
+
+class ResearchWebSearchTool(BaseModel):
+    """Research tool configuration for web search."""
+
+    type: str = Field(default="web_search_preview", description="Tool type")
+
+    model_config = {"populate_by_name": True}
+
+
+class ResearchFileSearchTool(BaseModel):
+    """Research tool configuration for file search over vector stores."""
+
+    type: str = Field(default="file_search", description="Tool type")
+    vector_store_ids: list[str] = Field(
+        ..., alias="vectorStoreIds", description="Vector store IDs (max 2)"
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class ResearchCodeInterpreterTool(BaseModel):
+    """Research tool configuration for code interpreter."""
+
+    type: str = Field(default="code_interpreter", description="Tool type")
+    container: dict[str, str] | None = Field(default=None, description="Container configuration")
+
+    model_config = {"populate_by_name": True}
+
+
+class ResearchMcpTool(BaseModel):
+    """Research tool configuration for remote MCP servers."""
+
+    type: str = Field(default="mcp", description="Tool type")
+    server_label: str = Field(..., alias="serverLabel", description="MCP server label")
+    server_url: str = Field(..., alias="serverUrl", description="MCP server URL")
+    require_approval: str | None = Field(
+        default="never", alias="requireApproval", description="Approval mode"
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+# Union type for research tools
+ResearchTool = (
+    ResearchWebSearchTool | ResearchFileSearchTool | ResearchCodeInterpreterTool | ResearchMcpTool
+)
+
+
+class ResearchParams(BaseModel):
+    """
+    Parameters for deep research models (o3-deep-research, o4-mini-deep-research).
+
+    Deep research models can find, analyze, and synthesize hundreds of sources
+    to create comprehensive reports.
+    """
+
+    input: str = Field(..., description="The research input/question")
+    instructions: str | None = Field(
+        default=None, description="Optional instructions to guide research"
+    )
+    background: bool | None = Field(
+        default=None, description="Run in background mode for long tasks"
+    )
+    tools: list[ResearchTool] | None = Field(
+        default=None,
+        description="Research tools (web_search_preview, file_search, mcp, code_interpreter)",
+    )
+    max_tool_calls: int | None = Field(
+        default=None, alias="maxToolCalls", description="Maximum number of tool calls"
+    )
+    reasoning_summary: str | None = Field(
+        default=None,
+        alias="reasoningSummary",
+        description="Include reasoning summary ('auto' or 'none')",
+    )
+    model: str | None = Field(
+        default=None, description="Model variant (o3-deep-research or o4-mini-deep-research)"
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+class ResearchAnnotation(BaseModel):
+    """Annotation in research results, linking text to sources."""
+
+    url: str = Field(..., description="URL of the source")
+    title: str = Field(..., description="Title of the source")
+    start_index: int = Field(..., alias="startIndex", description="Start index in text")
+    end_index: int = Field(..., alias="endIndex", description="End index in text")
+
+    model_config = {"populate_by_name": True}
+
+
+class ResearchResult(BaseModel):
+    """Result from a deep research model request."""
+
+    id: str = Field(..., description="Unique response identifier")
+    text: str = Field(..., description="Final research report with inline citations")
+    annotations: list[ResearchAnnotation] = Field(
+        default_factory=list, description="Annotations linking text to sources"
+    )
+    output_items: list[dict[str, Any]] = Field(
+        default_factory=list,
+        alias="outputItems",
+        description="Output items showing research process",
+    )
+    status: str | None = Field(default=None, description="Status for background requests")
+
+    model_config = {"populate_by_name": True}

package/elizaos/types/plugin.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from elizaos.types.agent import Character
+    from elizaos.types.components import Action, Evaluator, Provider
+    from elizaos.types.database import IDatabaseAdapter
+    from elizaos.types.runtime import IAgentRuntime
+    from elizaos.types.service import Service
+
+# Type for streaming model handlers
+StreamingModelHandler = Callable[["IAgentRuntime", dict[str, Any]], AsyncIterator[str]]
+
+
+class RouteRequest(BaseModel):
+    body: Any | None = Field(default=None, description="Request body")
+    params: dict[str, str] | None = Field(default=None, description="Route parameters")
+    query: dict[str, Any] | None = Field(default=None, description="Query parameters")
+    headers: dict[str, str | list[str] | None] | None = Field(
+        default=None, description="Request headers"
+    )
+    method: str | None = Field(default=None, description="HTTP method")
+    path: str | None = Field(default=None, description="Request path")
+    url: str | None = Field(default=None, description="Full URL")
+
+    model_config = {"extra": "allow"}
+
+
+class RouteResponse:
+    def __init__(self) -> None:
+        self._status_code: int = 200
+        self._headers: dict[str, str | list[str]] = {}
+        self._body: Any = None
+        self.headers_sent: bool = False
+
+    def status(self, code: int) -> RouteResponse:
+        self._status_code = code
+        return self
+
+    def json(self, data: Any) -> RouteResponse:
+        self._body = data
+        return self
+
+    def send(self, data: Any) -> RouteResponse:
+        self._body = data
+        return self
+
+    def end(self) -> RouteResponse:
+        self.headers_sent = True
+        return self
+
+    def set_header(self, name: str, value: str | list[str]) -> RouteResponse:
+        self._headers[name] = value
+        return self
+
+
+# Route handler type
+RouteHandler = Callable[
+    [RouteRequest, RouteResponse, "IAgentRuntime"],
+    Awaitable[None],
+]
+
+
+class Route(BaseModel):
+    """Route definition for plugin HTTP routes."""
+
+    type: Literal["GET", "POST", "PUT", "PATCH", "DELETE", "STATIC"] = Field(
+        ..., description="HTTP method"
+    )
+    path: str = Field(..., description="Route path")
+    file_path: str | None = Field(default=None, alias="filePath", description="Static file path")
+    public: bool | None = Field(default=None, description="Whether route is public")
+    name: str | None = Field(default=None, description="Route name for tab display")
+    handler: RouteHandler | None = Field(default=None, description="Route handler")
+    is_multipart: bool | None = Field(
+        default=None,
+        alias="isMultipart",
+        description="Whether route expects multipart/form-data",
+    )
+
+    model_config = {"populate_by_name": True, "arbitrary_types_allowed": True}
+
+
+# Plugin events type - maps event names to lists of event handlers
+PluginEvents = dict[str, list[Callable[[Any], Awaitable[None]]]]
+
+
+class TestCase(BaseModel):
+    name: str = Field(..., description="Test case name")
+    fn: Callable[[IAgentRuntime], Awaitable[None]] = Field(..., description="Test function")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class TestSuite(BaseModel):
+    """Test suite definition for plugin tests."""
+
+    name: str = Field(..., description="Test suite name")
+    tests: list[TestCase] = Field(..., description="Test cases")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class ComponentTypeDefinition(BaseModel):
+    name: str = Field(..., description="Component type name")
+    schema_def: dict[str, Any] = Field(..., alias="schema", description="Component schema")
+    validator: Callable[[Any], bool] | None = Field(
+        default=None, description="Optional validator function"
+    )
+
+    model_config = {"arbitrary_types_allowed": True, "populate_by_name": True}
+
+
+class Plugin(BaseModel):
+    name: str = Field(..., description="Unique name for the plugin")
+    description: str = Field(..., description="Human-readable description")
+
+    # Initialize plugin with runtime services
+    init: (
+        Callable[[dict[str, str | int | float | bool | None], IAgentRuntime], Awaitable[None]]
+        | None
+    ) = Field(default=None, description="Plugin initialization function")
+
+    # Configuration
+    config: dict[str, str | int | float | bool | None] | None = Field(
+        default=None, description="Plugin configuration"
+    )
+
+    # Services
+    services: list[type[Service]] | None = Field(
+        default=None, description="Service classes to register"
+    )
+
+    # Component type definitions
+    component_types: list[ComponentTypeDefinition] | None = Field(
+        default=None, alias="componentTypes", description="Entity component definitions"
+    )
+
+    # Optional plugin features
+    actions: list[Action] | None = Field(default=None, description="Actions to register")
+    providers: list[Provider] | None = Field(default=None, description="Providers to register")
+    evaluators: list[Evaluator] | None = Field(default=None, description="Evaluators to register")
+    adapter: IDatabaseAdapter | None = Field(default=None, description="Database adapter")
+    models: dict[str, Callable[[IAgentRuntime, dict[str, Any]], Awaitable[Any]]] | None = Field(
+        default=None, description="Model handlers by model type"
+    )
+    streaming_models: dict[str, StreamingModelHandler] | None = Field(
+        default=None,
+        alias="streamingModels",
+        description="Streaming model handlers by model type",
+    )
+    events: PluginEvents | None = Field(default=None, description="Event handlers by event type")
+    routes: list[Route] | None = Field(default=None, description="HTTP routes to register")
+    tests: list[TestSuite] | None = Field(default=None, description="Test suites")
+
+    dependencies: list[str] | None = Field(default=None, description="Plugin dependencies")
+    test_dependencies: list[str] | None = Field(
+        default=None, alias="testDependencies", description="Test dependencies"
+    )
+    priority: int | None = Field(default=None, description="Plugin priority")
+    schema_def: dict[str, Any] | None = Field(
+        default=None, alias="schema", description="Plugin schema"
+    )
+
+    model_config = {"populate_by_name": True, "arbitrary_types_allowed": True}
+
+
+class ProjectAgent(BaseModel):
+    """Agent configuration within a project."""
+
+    character: Character = Field(..., description="Agent character")
+    init: Callable[[IAgentRuntime], Awaitable[None]] | None = Field(
+        default=None, description="Agent initialization function"
+    )
+    plugins: list[Plugin] | None = Field(default=None, description="Agent-specific plugins")
+    tests: TestSuite | list[TestSuite] | None = Field(default=None, description="Agent tests")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class Project(BaseModel):
+    agents: list[ProjectAgent] = Field(..., description="Project agents")
+
+    model_config = {"arbitrary_types_allowed": True}

package/elizaos/types/primitives.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import hashlib
+import re
+import urllib.parse
+import uuid as uuid_module
+from enum import Enum
+
+from elizaos.types.generated.eliza.v1 import primitives_pb2
+
+# UUID validation pattern
+UUID_PATTERN = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+# UUID type - stored as string values in proto messages
+UUID = str
+
+# The default UUID used when no room or world is specified.
+DEFAULT_UUID: str = "00000000-0000-0000-0000-000000000000"
+
+# Proto-backed message types
+Content = primitives_pb2.Content
+Media = primitives_pb2.Media
+MentionContext = primitives_pb2.MentionContext
+Metadata = primitives_pb2.Metadata
+UUIDMessage = primitives_pb2.UUID
+DefaultUUID = primitives_pb2.DefaultUUID
+
+
+def as_uuid(id_str: str | uuid_module.UUID) -> str:
+    if isinstance(id_str, uuid_module.UUID):
+        return str(id_str)
+    if isinstance(id_str, str):
+        if not UUID_PATTERN.match(id_str):
+            raise ValueError(f"Invalid UUID format: {id_str}")
+        return id_str
+    raise TypeError(f"Expected str or UUID, got {type(id_str).__name__}")
+
+
+def string_to_uuid(target: str | int | uuid_module.UUID) -> str:
+    if isinstance(target, uuid_module.UUID):
+        return str(target)
+
+    if isinstance(target, int):
+        target_str = str(target)
+    elif isinstance(target, str):
+        target_str = target
+    else:
+        raise TypeError("Value must be string")
+
+    if UUID_PATTERN.match(target_str):
+        return target_str
+
+    escaped = urllib.parse.quote(target_str, safe="-_.!~*'()")
+    digest = hashlib.sha1(escaped.encode("utf-8")).digest()  # noqa: S324 (required for parity)
+
+    b = bytearray(digest[:16])
+    b[8] = (b[8] & 0x3F) | 0x80
+    b[6] &= 0x0F
+
+    return str(uuid_module.UUID(bytes=bytes(b)))
+
+
+class ChannelType(str, Enum):
+    SELF = "SELF"
+    DM = "DM"
+    GROUP = "GROUP"
+    VOICE_DM = "VOICE_DM"
+    VOICE_GROUP = "VOICE_GROUP"
+    FEED = "FEED"
+    THREAD = "THREAD"
+    WORLD = "WORLD"
+    FORUM = "FORUM"
+    API = "API"
+
+
+class ContentType(str, Enum):
+    IMAGE = "image"
+    VIDEO = "video"
+    AUDIO = "audio"
+    DOCUMENT = "document"
+    LINK = "link"
+
+
+__all__ = [
+    "UUID",
+    "DEFAULT_UUID",
+    "UUIDMessage",
+    "DefaultUUID",
+    "ChannelType",
+    "ContentType",
+    "Content",
+    "Media",
+    "MentionContext",
+    "Metadata",
+    "as_uuid",
+    "string_to_uuid",
+]