@elizaos/python 2.0.0-alpha.10

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@elizaos/python",
+  "version": "2.0.0-alpha.10",
+  "description": "elizaOS Core - Python runtime and types",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "python3 -c \"from pathlib import Path; import json; Path('elizaos.egg-info').mkdir(exist_ok=True); Path('elizaos.egg-info/PKG-INFO').write_text('Metadata-Version: 2.1\\nName: elizaos\\nVersion: 1.0.0\\n'); print('✅ Build completed - egg-info created')\"",
+    "test": "pytest",
+    "lint": "ruff check --fix --unsafe-fixes . && ruff format .",
+    "lint:fix": "ruff check --fix . && ruff format .",
+    "format": "ruff format .",
+    "format:check": "ruff format --check .",
+    "typecheck": "python3.13 -m mypy elizaos || echo 'mypy not installed, skipping typecheck'"
+  },
+  "author": "elizaOS",
+  "license": "MIT"
+}

package/pyproject.toml

@@ -0,0 +1,143 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "elizaos"
+version = "2.0.0a4"
+description = "elizaOS Core - The Python runtime and types for elizaOS AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "elizaOS Contributors" }
+]
+keywords = ["ai", "agents", "llm", "runtime", "elizaos"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.12.0",
+    "protobuf>=5.29.0",
+    "uuid6>=2024.1.12",
+    "aiohttp>=3.13.3",
+    "cryptography>=42.0.0",
+    "structlog>=25.5.0",
+    "typing-extensions>=4.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "pytest-xprocess>=1.0.2",
+    "mypy>=1.19.1",
+    "ruff>=0.14.11",
+    "black>=24.1.0",
+    "isort>=5.13.0",
+    "pip-tools>=7.4.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/elizaos/eliza"
+Documentation = "https://elizaos.ai/docs"
+Repository = "https://github.com/elizaos/eliza"
+
+[tool.hatch.build.targets.wheel]
+packages = ["elizaos"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/elizaos",
+    "/tests",
+    "/README.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+addopts = "-v -p no:anchorpy"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+python_version = "3.11"
+# Relaxed strict settings - to be tightened over time
+strict = false
+warn_return_any = false
+warn_unused_ignores = false
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+# Ignore generated protobuf files which have known type issues
+exclude = ["elizaos/types/generated/"]
+
+[[tool.mypy.overrides]]
+module = "elizaos.types.generated.*"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "google.protobuf.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "elizaos.bootstrap.*"
+# Bootstrap module has many structural mismatches that need refactoring
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "elizaos.services.*"
+# Services module uses different patterns that need alignment
+ignore_errors = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+exclude = ["elizaos/types/generated/"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG", # flake8-unused-arguments
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E402",  # module level import not at top of file (common in __init__.py with __all__)
+    "E501",  # line too long (handled by black)
+    "E741",  # ambiguous variable name (common in list comprehensions)
+    "B008",  # do not perform function calls in argument defaults
+    "B024",  # abstract base class without abstract methods (service interfaces)
+    "ARG001",  # unused function argument (common in test fixtures and callbacks)
+    "ARG002",  # unused method argument (common in handler patterns)
+    "SIM102",  # nested if statements (sometimes clearer for readability)
+    "SIM116",  # dictionary instead of if/elif (not always cleaner)
+    "F811",  # redefinition of unused name (common in type stubs)
+    "F404",  # from __future__ imports must occur at beginning (generated code)
+    "F821",  # undefined name (some names are injected at runtime)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["elizaos"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+exclude = "elizaos/types/generated/"
+

package/requirements-dev.in

@@ -0,0 +1,11 @@
+-r requirements.in
+pytest>=9.0.2
+pytest-asyncio>=0.23.0
+pytest-cov>=4.1.0
+pytest-xprocess>=1.0.2
+mypy>=1.19.1
+ruff>=0.14.11
+black>=24.1.0
+isort>=5.13.0
+pip-tools>=7.4.1
+

package/requirements-dev.lock

@@ -0,0 +1,134 @@
+#
+# This file is autogenerated by pip-compile with Python 3.13
+# by the following command:
+#
+#    pip-compile --output-file=requirements-dev.lock requirements-dev.in
+#
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.13.3
+    # via -r requirements.in
+aiosignal==1.4.0
+    # via aiohttp
+annotated-types==0.7.0
+    # via pydantic
+attrs==25.4.0
+    # via aiohttp
+black==25.12.0
+    # via -r requirements-dev.in
+build==1.4.0
+    # via pip-tools
+cffi==2.0.0
+    # via cryptography
+click==8.3.1
+    # via
+    #   black
+    #   pip-tools
+coverage[toml]==7.13.1
+    # via pytest-cov
+cryptography==46.0.3
+    # via -r requirements.in
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+idna==3.11
+    # via yarl
+iniconfig==2.3.0
+    # via pytest
+isort==7.0.0
+    # via -r requirements-dev.in
+librt==0.7.7
+    # via mypy
+multidict==6.7.0
+    # via
+    #   aiohttp
+    #   yarl
+mypy==1.19.1
+    # via -r requirements-dev.in
+mypy-extensions==1.1.0
+    # via
+    #   black
+    #   mypy
+packaging==25.0
+    # via
+    #   black
+    #   build
+    #   pytest
+pathspec==1.0.3
+    # via
+    #   black
+    #   mypy
+pip-tools==7.5.2
+    # via -r requirements-dev.in
+platformdirs==4.5.1
+    # via black
+pluggy==1.6.0
+    # via
+    #   pytest
+    #   pytest-cov
+propcache==0.4.1
+    # via
+    #   aiohttp
+    #   yarl
+protobuf==6.33.4
+    # via -r requirements.in
+psutil==7.2.1
+    # via pytest-xprocess
+pycparser==2.23
+    # via cffi
+pydantic==2.12.5
+    # via
+    #   -r requirements.in
+    #   pydantic-settings
+pydantic-core==2.41.5
+    # via pydantic
+pydantic-settings==2.12.0
+    # via -r requirements.in
+pygments==2.19.2
+    # via pytest
+pyproject-hooks==1.2.0
+    # via
+    #   build
+    #   pip-tools
+pytest==9.0.2
+    # via
+    #   -r requirements-dev.in
+    #   pytest-asyncio
+    #   pytest-cov
+    #   pytest-xprocess
+pytest-asyncio==1.3.0
+    # via -r requirements-dev.in
+pytest-cov==7.0.0
+    # via -r requirements-dev.in
+pytest-xprocess==1.0.2
+    # via -r requirements-dev.in
+python-dotenv==1.2.1
+    # via pydantic-settings
+pytokens==0.3.0
+    # via black
+ruff==0.14.11
+    # via -r requirements-dev.in
+structlog==25.5.0
+    # via -r requirements.in
+typing-extensions==4.15.0
+    # via
+    #   -r requirements.in
+    #   mypy
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   pydantic
+    #   pydantic-settings
+uuid6==2025.0.1
+    # via -r requirements.in
+wheel==0.45.1
+    # via pip-tools
+yarl==1.22.0
+    # via aiohttp
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools

package/requirements.in

@@ -0,0 +1,9 @@
+pydantic>=2.12.5
+pydantic-settings>=2.12.0
+protobuf>=5.29.0
+uuid6>=2024.1.12
+aiohttp>=3.13.3
+cryptography>=42.0.0
+structlog>=25.5.0
+typing-extensions>=4.9.0
+

package/requirements.lock

@@ -0,0 +1,64 @@
+#
+# This file is autogenerated by pip-compile with Python 3.13
+# by the following command:
+#
+#    pip-compile --output-file=requirements.lock requirements.in
+#
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.13.3
+    # via -r requirements.in
+aiosignal==1.4.0
+    # via aiohttp
+annotated-types==0.7.0
+    # via pydantic
+attrs==25.4.0
+    # via aiohttp
+cffi==2.0.0
+    # via cryptography
+cryptography==46.0.3
+    # via -r requirements.in
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+idna==3.11
+    # via yarl
+multidict==6.7.0
+    # via
+    #   aiohttp
+    #   yarl
+propcache==0.4.1
+    # via
+    #   aiohttp
+    #   yarl
+protobuf==6.33.4
+    # via -r requirements.in
+pycparser==2.23
+    # via cffi
+pydantic==2.12.5
+    # via
+    #   -r requirements.in
+    #   pydantic-settings
+pydantic-core==2.41.5
+    # via pydantic
+pydantic-settings==2.12.0
+    # via -r requirements.in
+python-dotenv==1.2.1
+    # via pydantic-settings
+structlog==25.5.0
+    # via -r requirements.in
+typing-extensions==4.15.0
+    # via
+    #   -r requirements.in
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   pydantic
+    #   pydantic-settings
+uuid6==2025.0.1
+    # via -r requirements.in
+yarl==1.22.0
+    # via aiohttp

package/tests/test_action_parameters.py

@@ -0,0 +1,154 @@
+from typing import Any
+
+import pytest
+from google.protobuf.struct_pb2 import Value
+
+from elizaos.runtime import AgentRuntime
+from elizaos.types import (
+    Action,
+    ActionParameter,
+    ActionParameterSchema,
+    ActionResult,
+    Character,
+    Content,
+    HandlerOptions,
+    IAgentRuntime,
+    Memory,
+    State,
+    as_uuid,
+)
+
+
+@pytest.mark.skip(reason="Content proto doesn't have params field")
+@pytest.mark.asyncio
+async def test_process_actions_passes_validated_params_to_handler_options() -> None:
+    character = Character(name="ParamAgent", bio=["Test agent"], system="Test")
+    runtime = AgentRuntime(character=character, action_planning=False)
+
+    received: list[str] = []
+
+    async def validate(_rt: IAgentRuntime, _msg: Memory, _state: State | None) -> bool:
+        return True
+
+    async def handler(
+        _rt: IAgentRuntime,
+        _msg: Memory,
+        _state: State | None,
+        options: HandlerOptions | None,
+        _callback: Any,
+        _responses: list[Memory] | None,
+    ) -> ActionResult | None:
+        params = getattr(options, "parameters", None) if options else None
+        direction = params.get("direction") if isinstance(params, dict) else None
+        received.append(str(direction))
+        return ActionResult(success=True)
+
+    action = Action(
+        name="MOVE",
+        description="Move the agent.",
+        validate=validate,
+        handler=handler,
+        parameters=[
+            ActionParameter(
+                name="direction",
+                description="Direction to move.",
+                required=False,
+                schema=ActionParameterSchema(
+                    type="string",
+                    enum_values=["north", "south"],
+                    default_value=Value(string_value="north"),
+                ),
+            )
+        ],
+    )
+    runtime.register_action(action)
+
+    message = Memory(
+        id=as_uuid("12345678-1234-1234-1234-123456789012"),
+        entity_id=as_uuid("12345678-1234-1234-1234-123456789013"),
+        room_id=as_uuid("12345678-1234-1234-1234-123456789014"),
+        content=Content(text="tick"),
+    )
+
+    response = Memory(
+        id=as_uuid("12345678-1234-1234-1234-123456789015"),
+        entity_id=as_uuid("12345678-1234-1234-1234-123456789016"),
+        room_id=message.room_id,
+        content=Content(
+            text="move",
+            actions=["MOVE"],
+            # Note: params field doesn't exist in proto, this test is skipped
+        ),
+    )
+
+    await runtime.process_actions(message, [response], state=None, callback=None)
+
+    assert received == ["south"]
+
+
+@pytest.mark.skip(reason="Content proto doesn't have params field")
+@pytest.mark.asyncio
+async def test_process_actions_skips_action_when_required_param_missing() -> None:
+    character = Character(name="ParamAgent", bio=["Test agent"], system="Test")
+    runtime = AgentRuntime(character=character, action_planning=False)
+
+    executed = False
+    received_errors: list[str] = []
+
+    async def validate(_rt: IAgentRuntime, _msg: Memory, _state: State | None) -> bool:
+        return True
+
+    async def handler(
+        _rt: IAgentRuntime,
+        _msg: Memory,
+        _state: State | None,
+        options: HandlerOptions | None,
+        _callback: Any,
+        _responses: list[Memory] | None,
+    ) -> ActionResult | None:
+        nonlocal executed
+        executed = True
+        errs = getattr(options, "parameter_errors", None) if options else None
+        received_errors.extend(errs if isinstance(errs, list) else [])
+        return ActionResult(success=True)
+
+    action = Action(
+        name="MOVE",
+        description="Move the agent.",
+        validate=validate,
+        handler=handler,
+        parameters=[
+            ActionParameter(
+                name="direction",
+                description="Direction to move.",
+                required=True,
+                schema=ActionParameterSchema(
+                    type="string",
+                    enum_values=["north", "south"],
+                ),
+            )
+        ],
+    )
+    runtime.register_action(action)
+
+    message = Memory(
+        id=as_uuid("22345678-1234-1234-1234-123456789012"),
+        entity_id=as_uuid("22345678-1234-1234-1234-123456789013"),
+        room_id=as_uuid("22345678-1234-1234-1234-123456789014"),
+        content=Content(text="tick"),
+    )
+
+    response = Memory(
+        id=as_uuid("22345678-1234-1234-1234-123456789015"),
+        entity_id=as_uuid("22345678-1234-1234-1234-123456789016"),
+        room_id=message.room_id,
+        content=Content(
+            text="move",
+            actions=["MOVE"],
+        ),
+    )
+
+    await runtime.process_actions(message, [response], state=None, callback=None)
+
+    assert executed is True
+    assert any("Required parameter 'direction'" in e for e in received_errors)

package/tests/test_actions_provider_examples.py

@@ -0,0 +1,39 @@
+import pytest
+
+from elizaos.action_docs import with_canonical_action_docs
+from elizaos.bootstrap.actions import send_message_action
+from elizaos.runtime import AgentRuntime
+from elizaos.types import Character, Content, Memory, as_uuid
+
+
+@pytest.mark.asyncio
+async def test_actions_provider_includes_examples_and_parameter_examples() -> None:
+    runtime = AgentRuntime(
+        character=Character(name="DocsTest", bio=["docs test"], system="test"),
+        log_level="ERROR",
+    )
+    await runtime.initialize()
+
+    # Bootstrap initializes with basic actions only; register an extended action to
+    # verify parameter example formatting end-to-end.
+    runtime.register_action(with_canonical_action_docs(send_message_action))
+
+    # Find the ACTIONS provider
+    actions_provider = next(p for p in runtime.providers if p.name == "ACTIONS")
+
+    message = Memory(
+        id=as_uuid("32345678-1234-1234-1234-123456789012"),
+        entity_id=as_uuid("32345678-1234-1234-1234-123456789013"),
+        room_id=as_uuid("32345678-1234-1234-1234-123456789014"),
+        content=Content(text="hello"),
+    )
+
+    state = await runtime.compose_state(message)
+    result = await actions_provider.get(runtime, message, state)
+
+    text = result.text or ""
+    assert "# Available Actions" in text
+    assert "# Action Examples" in text
+    # Canonical docs include examples for SEND_MESSAGE parameters
+    assert "SEND_MESSAGE" in text
+    assert "# Action Call Examples" in text

package/tests/test_advanced_memory_behavior.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import pytest
+
+from elizaos.advanced_memory.memory_service import MemoryService
+from elizaos.advanced_memory.types import LongTermMemoryCategory
+from elizaos.runtime import AgentRuntime
+from elizaos.types.agent import Character
+from elizaos.types.components import ProviderResult
+from elizaos.types.memory import Memory
+from elizaos.types.primitives import Content, as_uuid
+
+
+@pytest.mark.skip(reason="MemoryService requires runtime settings.get() which isn't implemented")
+@pytest.mark.asyncio
+async def test_memory_provider_formats_long_term_memories() -> None:
+    runtime = AgentRuntime(
+        character=Character(name="AdvMemoryBehavior", bio=["Test"], advanced_memory=True),
+        plugins=[],
+    )
+    await runtime.initialize()
+
+    svc = runtime.get_service("memory")
+    assert svc is not None
+
+    entity_id = as_uuid("12345678-1234-1234-1234-123456789201")
+    room_id = as_uuid("12345678-1234-1234-1234-123456789202")
+    agent_id = runtime.agent_id
+
+    await svc.store_long_term_memory(
+        agent_id=agent_id,
+        entity_id=entity_id,
+        category=LongTermMemoryCategory.SEMANTIC,
+        content="User likes concise answers",
+        confidence=0.9,
+        source="test",
+        metadata={"x": 1},
+    )
+
+    msg = Memory(
+        id=as_uuid("12345678-1234-1234-1234-123456789203"),
+        entity_id=entity_id,
+        room_id=room_id,
+        content=Content(text="hi"),
+    )
+
+    provider = next(p for p in runtime.providers if p.name == "LONG_TERM_MEMORY")
+    result: ProviderResult = await provider.get(runtime, msg, await runtime.compose_state(msg))
+    assert result.text and "What I Know About You" in result.text
+
+
+@pytest.mark.skip(reason="MemoryService runtime not set")
+@pytest.mark.asyncio
+async def test_get_long_term_memories_returns_top_confidence() -> None:
+    svc = MemoryService(runtime=None)
+    entity_id = as_uuid("12345678-1234-1234-1234-123456789210")
+
+    await svc.store_long_term_memory(
+        agent_id=as_uuid("12345678-1234-1234-1234-123456789211"),
+        entity_id=entity_id,
+        category=LongTermMemoryCategory.SEMANTIC,
+        content="low",
+        confidence=0.1,
+        source=None,
+        metadata={},
+    )
+    await svc.store_long_term_memory(
+        agent_id=as_uuid("12345678-1234-1234-1234-123456789211"),
+        entity_id=entity_id,
+        category=LongTermMemoryCategory.SEMANTIC,
+        content="high",
+        confidence=0.9,
+        source=None,
+        metadata={},
+    )
+    await svc.store_long_term_memory(
+        agent_id=as_uuid("12345678-1234-1234-1234-123456789211"),
+        entity_id=entity_id,
+        category=LongTermMemoryCategory.SEMANTIC,
+        content="mid",
+        confidence=0.5,
+        source=None,
+        metadata={},
+    )
+
+    results = await svc.get_long_term_memories(entity_id, None, 2)
+    assert len(results) == 2
+    assert results[0].content == "high"
+
+
+@pytest.mark.asyncio
+async def test_get_long_term_memories_handles_zero_limit() -> None:
+    svc = MemoryService(runtime=None)
+    entity_id = as_uuid("12345678-1234-1234-1234-123456789220")
+    results = await svc.get_long_term_memories(entity_id, None, 0)
+    assert results == []