@elizaos/python 2.0.0-alpha.10

package/elizaos/types/components.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Literal, TypeAlias
+
+from elizaos.types.generated.eliza.v1 import components_pb2
+from elizaos.types.primitives import Content
+
+if TYPE_CHECKING:
+    from elizaos.types.memory import Memory
+    from elizaos.types.runtime import IAgentRuntime
+    from elizaos.types.state import State
+
+JsonPrimitive: TypeAlias = str | int | float | bool | None
+
+
+# ---------------------------------------------------------------------------
+# Evaluator phase — when in the message pipeline the evaluator runs
+# ---------------------------------------------------------------------------
+
+EvaluatorPhase = Literal["pre", "post"]
+"""When in the message pipeline an evaluator runs.
+
+- ``"pre"`` — **Before** the incoming message is saved to memory and before
+  action processing.  Pre-evaluators act as middleware: they can inspect,
+  rewrite, or **block** a message so it never reaches the agent.
+
+- ``"post"`` — **After** the agent has responded and actions have executed.
+  This is the original (default) evaluator behaviour.
+"""
+
+
+@dataclass
+class PreEvaluatorResult:
+    """Result returned by a ``phase="pre"`` evaluator's handler.
+
+    If *blocked* is ``True`` the message pipeline will skip memory storage,
+    response generation, and action execution for this message.
+
+    If *rewritten_text* is provided the message text is replaced before
+    further processing (useful for sanitisation / redaction).
+    """
+
+    blocked: bool = False
+    rewritten_text: str | None = None
+    reason: str | None = None
+
+# Proto-backed data types
+ActionExample = components_pb2.ActionExample
+ActionParameterSchema = components_pb2.ActionParameterSchema
+ActionParameter = components_pb2.ActionParameter
+ActionParameters = components_pb2.ActionParameters
+ActionResult = components_pb2.ActionResult
+ActionContext = components_pb2.ActionContext
+HandlerOptions = components_pb2.HandlerOptions
+ProviderResult = components_pb2.ProviderResult
+EvaluationExample = components_pb2.EvaluationExample
+
+# Runtime handler signatures (not in proto)
+HandlerCallback = Callable[[Content], Awaitable[list["Memory"]]]
+StreamChunkCallback = Callable[[str, str | None], Awaitable[None]]
+
+Handler = Callable[
+    [
+        "IAgentRuntime",
+        "Memory",
+        "State | None",
+        HandlerOptions | None,
+        HandlerCallback | None,
+        "list[Memory] | None",
+    ],
+    Awaitable[ActionResult | None],
+]
+
+Validator = Callable[["IAgentRuntime", "Memory", "State | None"], Awaitable[bool]]
+
+
+class ActionDefinition:  # runtime interface
+    """Definition for an action that can be executed by the agent."""
+
+    name: str
+    description: str
+    handler: Handler
+    validate: Validator
+    similes: list[str] | None
+    examples: list[list[ActionExample]] | None
+    priority: int | None
+    tags: list[str] | None
+    parameters: list[ActionParameter] | None
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        handler: Handler,
+        validate: Validator,
+        similes: list[str] | None = None,
+        examples: list[list[ActionExample]] | None = None,
+        priority: int | None = None,
+        tags: list[str] | None = None,
+        parameters: list[ActionParameter] | None = None,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.handler = handler
+        self.validate = validate
+        self.similes = similes
+        self.examples = examples
+        self.priority = priority
+        self.tags = tags
+        self.parameters = parameters
+
+
+class EvaluatorDefinition:  # runtime interface
+    """Definition for an evaluator that processes agent messages.
+
+    Evaluators can run at two points in the pipeline controlled by *phase*:
+
+    - ``"pre"`` — before memory storage (middleware / security gate).
+      Pre-evaluators may return a :class:`PreEvaluatorResult` from their
+      handler to block or rewrite the incoming message.
+    - ``"post"`` — after actions (default, backwards-compatible).
+    """
+
+    always_run: bool | None
+    description: str
+    similes: list[str] | None
+    examples: list[EvaluationExample]
+    handler: Handler
+    name: str
+    validate: Validator
+    phase: EvaluatorPhase
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        handler: Handler,
+        validate: Validator,
+        examples: list[EvaluationExample] | None = None,
+        similes: list[str] | None = None,
+        always_run: bool | None = None,
+        phase: EvaluatorPhase = "post",
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.handler = handler
+        self.validate = validate
+        self.examples = examples or []
+        self.similes = similes
+        self.always_run = always_run
+        self.phase = phase
+
+
+class ProviderDefinition:  # runtime interface
+    """Definition for a context provider that supplies information to the agent."""
+
+    name: str
+    description: str | None
+    dynamic: bool | None
+    position: int | None
+    private: bool | None
+    get: Callable[[IAgentRuntime, Memory, State], Awaitable[ProviderResult]]
+
+    def __init__(
+        self,
+        name: str,
+        get: Callable[[IAgentRuntime, Memory, State], Awaitable[ProviderResult]],
+        description: str | None = None,
+        dynamic: bool | None = None,
+        position: int | None = None,
+        private: bool | None = None,
+    ) -> None:
+        self.name = name
+        self.get = get
+        self.description = description
+        self.dynamic = dynamic
+        self.position = position
+        self.private = private
+
+
+Action = ActionDefinition
+Evaluator = EvaluatorDefinition
+Provider = ProviderDefinition
+
+__all__ = [
+    "Action",
+    "Evaluator",
+    "EvaluatorPhase",
+    "PreEvaluatorResult",
+    "Provider",
+    "ActionExample",
+    "ActionParameterSchema",
+    "ActionParameter",
+    "ActionParameters",
+    "ActionResult",
+    "ActionContext",
+    "HandlerOptions",
+    "ProviderResult",
+    "EvaluationExample",
+    "Handler",
+    "Validator",
+    "HandlerCallback",
+    "StreamChunkCallback",
+    "JsonPrimitive",
+]

package/elizaos/types/database.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from elizaos.types.generated.eliza.v1 import database_pb2
+
+# Proto-backed types
+BaseLogBody = database_pb2.BaseLogBody
+ActionLogBody = database_pb2.ActionLogBody
+EvaluatorLogBody = database_pb2.EvaluatorLogBody
+ModelLogBody = database_pb2.ModelLogBody
+EmbeddingLogBody = database_pb2.EmbeddingLogBody
+LogBody = database_pb2.LogBody
+Log = database_pb2.Log
+RunStatus = database_pb2.DbRunStatus  # Alias for compatibility
+AgentRunCounts = database_pb2.AgentRunCounts
+AgentRunSummary = database_pb2.AgentRunSummary
+AgentRunSummaryResult = database_pb2.AgentRunSummaryResult
+EmbeddingSearchResult = database_pb2.EmbeddingSearchResult
+MemoryRetrievalOptions = database_pb2.MemoryRetrievalOptions
+MemorySearchOptions = database_pb2.MemorySearchOptions
+MultiRoomMemoryOptions = database_pb2.MultiRoomMemoryOptions
+
+# Types not in protobuf - provide aliases or simple types
+MemoryOptions = MemoryRetrievalOptions  # Alias for compatibility
+SearchOptions = MemorySearchOptions  # Alias for compatibility
+DbConnection = Any  # Runtime type
+
+# Vector dimension constant (for compatibility with prior adapter interfaces)
+VECTOR_DIMS = 1536
+
+
+@runtime_checkable
+class IDatabaseAdapter(Protocol):
+    """Runtime adapter interface (implementation-specific)."""
+
+    @property
+    def db(self) -> Any: ...
+
+    def __getattr__(self, name: str) -> Any: ...
+
+
+__all__ = [
+    "BaseLogBody",
+    "ActionLogBody",
+    "EvaluatorLogBody",
+    "ModelLogBody",
+    "EmbeddingLogBody",
+    "LogBody",
+    "Log",
+    "RunStatus",
+    "AgentRunCounts",
+    "AgentRunSummary",
+    "AgentRunSummaryResult",
+    "EmbeddingSearchResult",
+    "MemoryRetrievalOptions",
+    "MemorySearchOptions",
+    "MultiRoomMemoryOptions",
+    "MemoryOptions",
+    "SearchOptions",
+    "DbConnection",
+    "VECTOR_DIMS",
+    "IDatabaseAdapter",
+]

package/elizaos/types/environment.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from elizaos.types.generated.eliza.v1 import environment_pb2
+
+Component = environment_pb2.Component
+Entity = environment_pb2.Entity
+WorldOwnership = environment_pb2.WorldOwnership
+WorldMetadata = environment_pb2.WorldMetadata
+World = environment_pb2.World
+RoomMetadata = environment_pb2.RoomMetadata
+Room = environment_pb2.Room
+Participant = environment_pb2.Participant
+Relationship = environment_pb2.Relationship
+
+
+class _ChannelValue(str):
+    """String that also has a .value property for enum compatibility."""
+
+    @property
+    def value(self) -> str:  # noqa: D401
+        return str(self)
+
+
+class ChannelType:
+    """Channel type constants (mirrors the TypeScript ChannelType enum)."""
+
+    DM = _ChannelValue("DM")
+    GROUP = _ChannelValue("GROUP")
+    FEED = _ChannelValue("FEED")
+    WORLD = _ChannelValue("WORLD")
+    API = _ChannelValue("API")
+    SELF = _ChannelValue("SELF")
+
+
+__all__ = [
+    "ChannelType",
+    "Component",
+    "Entity",
+    "WorldOwnership",
+    "WorldMetadata",
+    "World",
+    "RoomMetadata",
+    "Room",
+    "Participant",
+    "Relationship",
+]

package/elizaos/types/events.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeAlias
+
+from elizaos.types.generated.eliza.v1 import events_pb2
+
+if TYPE_CHECKING:
+    from elizaos.types.runtime import IAgentRuntime
+
+EventType = events_pb2.EventType
+PlatformPrefix = events_pb2.PlatformPrefix
+EventPayload = events_pb2.EventPayload
+WorldPayload = events_pb2.WorldPayload
+EntityPayload = events_pb2.EntityPayload
+MessagePayload = events_pb2.MessagePayload
+ChannelClearedPayload = events_pb2.ChannelClearedPayload
+InvokePayload = events_pb2.InvokePayload
+RunEventPayload = events_pb2.RunEventPayload
+ActionEventPayload = events_pb2.ActionEventPayload
+EvaluatorEventPayload = events_pb2.EvaluatorEventPayload
+ModelEventPayload = events_pb2.ModelEventPayload
+EmbeddingGenerationPayload = events_pb2.EmbeddingGenerationPayload
+ControlMessagePayload = events_pb2.ControlMessagePayload
+
+EventPayloadMap: TypeAlias = dict[EventType, type]
+
+EventHandler = Callable[[EventPayload, "IAgentRuntime"], Awaitable[None]]
+
+__all__ = [
+    "EventType",
+    "PlatformPrefix",
+    "EventPayload",
+    "WorldPayload",
+    "EntityPayload",
+    "MessagePayload",
+    "ChannelClearedPayload",
+    "InvokePayload",
+    "RunEventPayload",
+    "ActionEventPayload",
+    "EvaluatorEventPayload",
+    "ModelEventPayload",
+    "EmbeddingGenerationPayload",
+    "ControlMessagePayload",
+    "EventPayloadMap",
+    "EventHandler",
+]

package/elizaos/types/memory.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from elizaos.types.generated.eliza.v1 import memory_pb2
+
+
+class _MemoryTypeValue(str):
+    """String that also has a .value property for enum compatibility."""
+
+    @property
+    def value(self) -> str:  # noqa: D401
+        return str(self)
+
+
+class MemoryType:
+    """Memory type constants (mirrors the TypeScript MemoryType enum)."""
+
+    MESSAGE = _MemoryTypeValue("MESSAGE")
+    DOCUMENT = _MemoryTypeValue("DOCUMENT")
+    FRAGMENT = _MemoryTypeValue("FRAGMENT")
+    DESCRIPTION = _MemoryTypeValue("DESCRIPTION")
+    CUSTOM = _MemoryTypeValue("CUSTOM")
+
+
+BaseMetadata = memory_pb2.BaseMetadata
+DocumentMetadata = memory_pb2.DocumentMetadata
+FragmentMetadata = memory_pb2.FragmentMetadata
+MessageMetadata = memory_pb2.MessageMetadata
+DescriptionMetadata = memory_pb2.DescriptionMetadata
+CustomMetadata = memory_pb2.CustomMetadata
+MemoryMetadata = memory_pb2.MemoryMetadata
+Memory = memory_pb2.Memory
+MessageMemory = memory_pb2.MessageMemory
+
+__all__ = [
+    "MemoryType",
+    "BaseMetadata",
+    "DocumentMetadata",
+    "FragmentMetadata",
+    "MessageMetadata",
+    "DescriptionMetadata",
+    "CustomMetadata",
+    "MemoryMetadata",
+    "Memory",
+    "MessageMemory",
+]