@elizaos/python 2.0.0-alpha.10

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2025 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+
+

package/README.md

@@ -0,0 +1,239 @@
+# elizaOS Core (Python)
+
+The Python implementation of elizaOS Core - the runtime and types for elizaOS AI agents.
+
+## Installation
+
+### From Repository (Development)
+
+```bash
+# From the repo root
+cd eliza
+
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install the core package
+pip install -e packages/python
+
+# Install an LLM provider (required)
+pip install -e plugins/plugin-openai/python
+
+# Install a database adapter (required for message handling)
+pip install -e plugins/plugin-inmemorydb/python
+```
+
+### From PyPI
+
+```bash
+pip install elizaos elizaos-plugin-openai elizaos-plugin-inmemorydb
+```
+
+## Quick Start
+
+### Run the Chat Example
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY="your-key"
+
+# Run the example
+python examples/chat/python/chat.py
+```
+
+### Create Your Own Agent
+
+```python
+from __future__ import annotations
+import asyncio
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+load_dotenv()  # Load .env file
+
+from uuid6 import uuid7
+from elizaos import Character, ChannelType, Content, Memory
+from elizaos.runtime import AgentRuntime
+from elizaos_plugin_openai import get_openai_plugin
+from elizaos_plugin_inmemorydb import plugin as inmemorydb_plugin
+
+async def main() -> None:
+    # Define your agent's character
+    character = Character(
+        name="Eliza",
+        username="eliza",
+        bio="A helpful AI assistant.",
+        system="You are helpful and concise.",
+    )
+
+    # Create runtime with plugins
+    runtime = AgentRuntime(
+        character=character,
+        plugins=[
+            get_openai_plugin(),    # LLM provider
+            inmemorydb_plugin,      # Database adapter
+        ],
+    )
+
+    user_id = uuid7()
+    room_id = uuid7()
+
+    try:
+        await runtime.initialize()
+        print(f"🤖 Chat with {character.name} (type 'quit' to exit)\n")
+
+        while True:
+            user_input = input("You: ")
+            if not user_input.strip() or user_input.lower() in ("quit", "exit"):
+                break
+
+            message = Memory(
+                entity_id=user_id,
+                room_id=room_id,
+                content=Content(
+                    text=user_input,
+                    source="cli",
+                    channel_type=ChannelType.DM.value,
+                ),
+            )
+
+            result = await runtime.message_service.handle_message(runtime, message)
+            print(f"\n{character.name}: {result.response_content.text}\n")
+
+        print("Goodbye! 👋")
+    finally:
+        await runtime.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Features
+
+- **Strong typing** with Pydantic models and full type hints
+- **Plugin architecture** for extensibility
+- **Character configuration** for defining agent personalities
+- **Memory system** for conversation history and knowledge
+- **Event system** for reactive programming
+- **Service abstraction** for external integrations
+
+## Runtime Settings (cross-language parity)
+
+These settings are read by the runtime/message loop to keep behavior aligned with the TypeScript and Rust implementations:
+
+- `ALLOW_NO_DATABASE`: when truthy, the runtime may run without a database adapter (benchmarks/tests).
+- `USE_MULTI_STEP`: when truthy, enable the iterative multi-step workflow.
+- `MAX_MULTISTEP_ITERATIONS`: maximum iterations for multi-step mode (default: `6`).
+
+### Benchmark & Trajectory Tracing
+
+Benchmarks and harnesses can attach metadata to inbound messages:
+
+- `message.metadata.trajectoryStepId`: enables trajectory tracing for provider access + model calls.
+- `message.metadata.benchmarkContext`: enables the `CONTEXT_BENCH` provider and sets `state.values["benchmark_has_context"]=True`, which forces action-based execution to exercise the full loop.
+
+## Model output contract (XML preferred, plain text tolerated)
+
+The canonical message loop expects model outputs in the `<response>...</response>` XML format (with `<actions>`, `<providers>`, and `<text>` fields).
+
+Some deterministic/offline backends may return **plain text** instead. In that case, the runtime will treat the raw output as a simple **`REPLY`** so the system remains usable even when strict XML formatting is unavailable.
+
+## Core Types
+
+- `UUID` - Universally unique identifier
+- `Content` - Message content with text, actions, attachments
+- `Memory` - Stored message or information
+- `Entity` - User or agent representation
+- `Room` - Conversation context
+- `World` - Collection of rooms and entities
+
+## Components
+
+- `Action` - Define agent capabilities
+- `Provider` - Supply contextual information
+- `Evaluator` - Post-interaction analysis
+- `Service` - Long-running integrations
+
+## Plugin System
+
+```python
+from elizaos import Plugin, Action, Provider
+
+my_plugin = Plugin(
+    name="my-plugin",
+    description="A custom plugin",
+    actions=[...],
+    providers=[...],
+)
+```
+
+## Available Plugins
+
+### LLM Providers
+
+| Plugin | Path | Description |
+|--------|------|-------------|
+| OpenAI | `plugins/plugin-openai/python` | GPT-4, embeddings, DALL-E |
+| Anthropic | `plugins/plugin-anthropic/python` | Claude models |
+| Ollama | `plugins/plugin-ollama/python` | Local LLMs |
+| Groq | `plugins/plugin-groq/python` | Fast inference |
+
+### Database Adapters
+
+| Plugin | Path | Description |
+|--------|------|-------------|
+| InMemoryDB | `plugins/plugin-inmemorydb/python` | Ephemeral storage (dev/testing) |
+| SQL | `plugins/plugin-sql/python` | PostgreSQL/PGLite |
+
+### Platform Integrations
+
+| Plugin | Path | Description |
+|--------|------|-------------|
+| Telegram | `plugins/plugin-telegram/python` | Telegram bots |
+| Discord | `plugins/plugin-discord/python` | Discord bots |
+
+## Environment Variables
+
+```bash
+# Required for OpenAI plugin
+OPENAI_API_KEY=sk-...
+
+# Optional
+LOG_LEVEL=INFO
+```
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# (Reproducible/pinned) Generate lockfiles used by CI
+pip install pip-tools
+pip-compile requirements.in -o requirements.lock
+pip-compile requirements-dev.in -o requirements-dev.lock
+
+# Run tests
+pytest
+
+# Type checking
+mypy elizaos
+
+# Linting
+ruff check elizaos
+```
+
+## Examples
+
+See `examples/` directory for complete working examples:
+
+- `examples/chat/python/` - CLI chat agent
+- `examples/telegram/python/` - Telegram bot
+- `examples/discord/python/` - Discord bot
+- `examples/rest-api/fastapi/` - REST API server
+
+## License
+
+MIT

package/elizaos/__init__.py

@@ -0,0 +1,280 @@
+from elizaos.character import parse_character, validate_character_config
+from elizaos.generated.action_docs import (
+    ActionDoc,
+    ActionDocExampleCall,
+    ActionDocParameter,
+    ActionDocParameterExampleValue,
+    ActionDocParameterSchema,
+    EvaluatorDoc,
+    EvaluatorDocExample,
+    EvaluatorDocMessage,
+    EvaluatorDocMessageContent,
+    all_action_docs,
+    all_actions_spec_version,
+    all_evaluator_docs,
+    all_evaluators_spec_version,
+    core_action_docs,
+    core_actions_spec_version,
+    core_evaluator_docs,
+    core_evaluators_spec_version,
+)
+from elizaos.generated.spec_helpers import (
+    get_action_spec,
+    get_evaluator_spec,
+    get_provider_spec,
+    require_action_spec,
+    require_evaluator_spec,
+    require_provider_spec,
+)
+from elizaos.logger import Logger, create_logger
+from elizaos.plugin import load_plugin, register_plugin
+from elizaos.prompts import (
+    BOOLEAN_FOOTER,
+    CHOOSE_OPTION_TEMPLATE,
+    IMAGE_GENERATION_TEMPLATE,
+    MESSAGE_HANDLER_TEMPLATE,
+    REFLECTION_TEMPLATE,
+    REPLY_TEMPLATE,
+    SHOULD_RESPOND_TEMPLATE,
+    UPDATE_ENTITY_TEMPLATE,
+    UPDATE_SETTINGS_TEMPLATE,
+)
+from elizaos.runtime import AgentRuntime
+from elizaos.services import DefaultMessageService, IMessageService, MessageProcessingResult
+from elizaos.settings import (
+    decrypt_object_values,
+    decrypt_secret,
+    decrypt_string_value,
+    encrypt_object_values,
+    encrypt_string_value,
+    get_salt,
+)
+from elizaos.types import (
+    UUID,
+    Action,
+    ActionContext,
+    ActionExample,
+    ActionResult,
+    Agent,
+    AgentStatus,
+    BaseMetadata,
+    Character,
+    CharacterSettings,
+    Component,
+    Content,
+    CustomMetadata,
+    DescriptionMetadata,
+    DocumentMetadata,
+    Entity,
+    EvaluationExample,
+    Evaluator,
+    EventPayload,
+    EventType,
+    FragmentMetadata,
+    HandlerCallback,
+    HandlerOptions,
+    LLMMode,
+    Log,
+    Media,
+    Memory,
+    MemoryMetadata,
+    MemoryType,
+    MentionContext,
+    MessageExample,
+    MessageMemory,
+    MessageMetadata,
+    Metadata,
+    ModelType,
+    Participant,
+    Plugin,
+    Provider,
+    ProviderResult,
+    Relationship,
+    Room,
+    Route,
+    RouteRequest,
+    RouteResponse,
+    Service,
+    ServiceType,
+    ServiceTypeName,
+    State,
+    StateData,
+    Task,
+    TaskWorker,
+    WorkingMemoryItem,
+    World,
+    WorldOwnership,
+    as_uuid,
+    string_to_uuid,
+)
+from elizaos.types.database import IDatabaseAdapter  # noqa: E402
+from elizaos.types.environment import ChannelType  # noqa: E402
+from elizaos.types.primitives import (  # noqa: E402
+    ChannelType,
+    Content,
+    ContentType,
+    Media,
+    Metadata,
+)
+from elizaos.types.runtime import IAgentRuntime  # noqa: E402
+from elizaos.utils import compose_prompt, compose_prompt_from_state, get_current_time_ms
+
+_rebuild_ns = {
+    "IAgentRuntime": IAgentRuntime,
+    "IDatabaseAdapter": IDatabaseAdapter,
+    "Service": Service,
+    "Action": Action,
+    "Evaluator": Evaluator,
+    "Provider": Provider,
+    "Task": Task,
+    "Memory": Memory,
+    "State": State,
+    "Character": Character,
+    "Plugin": Plugin,
+    "Route": Route,
+    "HandlerOptions": HandlerOptions,
+    "ActionResult": ActionResult,
+}
+# Rebuild Pydantic models with forward references
+# Only call model_rebuild on actual Pydantic BaseModel subclasses
+for _type in [Plugin, Task, TaskWorker]:
+    if hasattr(_type, "model_rebuild"):
+        _type.model_rebuild(_types_namespace=_rebuild_ns)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Runtime
+    "AgentRuntime",
+    # Types - Primitives
+    "UUID",
+    "as_uuid",
+    "string_to_uuid",
+    "ChannelType",
+    "Content",
+    "ContentType",
+    "Media",
+    "Metadata",
+    "MentionContext",
+    # Types - Memory
+    "Memory",
+    "MemoryType",
+    "MessageMemory",
+    "MemoryMetadata",
+    "BaseMetadata",
+    "DocumentMetadata",
+    "FragmentMetadata",
+    "MessageMetadata",
+    "DescriptionMetadata",
+    "CustomMetadata",
+    # Types - Agent
+    "Character",
+    "CharacterSettings",
+    "Agent",
+    "AgentStatus",
+    "MessageExample",
+    # Types - Environment
+    "Entity",
+    "Component",
+    "World",
+    "WorldOwnership",
+    "Room",
+    "Participant",
+    "Relationship",
+    # Types - Components
+    "Action",
+    "ActionExample",
+    "ActionResult",
+    "ActionContext",
+    "Evaluator",
+    "EvaluationExample",
+    "Provider",
+    "ProviderResult",
+    "HandlerCallback",
+    "HandlerOptions",
+    # Types - Plugin
+    "Plugin",
+    "Route",
+    "RouteRequest",
+    "RouteResponse",
+    # Types - Service
+    "Service",
+    "ServiceType",
+    "ServiceTypeName",
+    # Types - State
+    "State",
+    "StateData",
+    "WorkingMemoryItem",
+    # Types - Events
+    "EventType",
+    "EventPayload",
+    # Types - Task
+    "Task",
+    "TaskWorker",
+    # Types - Logging
+    "Log",
+    # Types - Model
+    "LLMMode",
+    "ModelType",
+    # Types - Channel
+    "ChannelType",
+    # Logger
+    "create_logger",
+    "Logger",
+    # Plugin utilities
+    "load_plugin",
+    "register_plugin",
+    # Character utilities
+    "parse_character",
+    "validate_character_config",
+    # Message service
+    "DefaultMessageService",
+    "IMessageService",
+    "MessageProcessingResult",
+    # Prompts
+    "BOOLEAN_FOOTER",
+    "CHOOSE_OPTION_TEMPLATE",
+    "IMAGE_GENERATION_TEMPLATE",
+    "MESSAGE_HANDLER_TEMPLATE",
+    "REFLECTION_TEMPLATE",
+    "REPLY_TEMPLATE",
+    "SHOULD_RESPOND_TEMPLATE",
+    "UPDATE_ENTITY_TEMPLATE",
+    "UPDATE_SETTINGS_TEMPLATE",
+    # Settings / secrets helpers
+    "get_salt",
+    "encrypt_string_value",
+    "decrypt_string_value",
+    "encrypt_object_values",
+    "decrypt_object_values",
+    "decrypt_secret",
+    # Prompt composition helpers
+    "compose_prompt",
+    "compose_prompt_from_state",
+    "get_current_time_ms",
+    # Generated action/evaluator specs (centralized from packages/prompts)
+    "ActionDoc",
+    "ActionDocExampleCall",
+    "ActionDocParameter",
+    "ActionDocParameterSchema",
+    "ActionDocParameterExampleValue",
+    "EvaluatorDoc",
+    "EvaluatorDocExample",
+    "EvaluatorDocMessage",
+    "EvaluatorDocMessageContent",
+    "core_actions_spec_version",
+    "all_actions_spec_version",
+    "core_evaluators_spec_version",
+    "all_evaluators_spec_version",
+    "core_action_docs",
+    "all_action_docs",
+    "core_evaluator_docs",
+    "all_evaluator_docs",
+    # Spec helper functions
+    "get_action_spec",
+    "require_action_spec",
+    "get_provider_spec",
+    "require_provider_spec",
+    "get_evaluator_spec",
+    "require_evaluator_spec",
+]

package/elizaos/action_docs.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elizaos.generated.action_docs import all_action_docs, all_evaluator_docs
+
+if TYPE_CHECKING:
+    from elizaos.types import Action, Evaluator
+
+
+def _action_doc_by_name() -> dict[str, dict[str, object]]:
+    actions = all_action_docs.get("actions")
+    if not isinstance(actions, list):
+        return {}
+    by_name: dict[str, dict[str, object]] = {}
+    for item in actions:
+        if isinstance(item, dict):
+            name = item.get("name")
+            if isinstance(name, str):
+                by_name[name] = item
+    return by_name
+
+
+def _evaluator_doc_by_name() -> dict[str, dict[str, object]]:
+    evaluators = all_evaluator_docs.get("evaluators")
+    if not isinstance(evaluators, list):
+        return {}
+    by_name: dict[str, dict[str, object]] = {}
+    for item in evaluators:
+        if isinstance(item, dict):
+            name = item.get("name")
+            if isinstance(name, str):
+                by_name[name] = item
+    return by_name
+
+
+_ACTION_DOCS = _action_doc_by_name()
+_EVALUATOR_DOCS = _evaluator_doc_by_name()
+
+
+def _coerce_action_parameters(values: object) -> list[object]:
+    if not isinstance(values, list):
+        return []
+
+    # Local import to avoid import cycles during package init.
+    from google.protobuf.json_format import ParseDict
+
+    from elizaos.types import ActionParameter  # noqa: PLC0415
+
+    out: list[object] = []
+    for item in values:
+        if not isinstance(item, dict):
+            continue
+        # Use protobuf ParseDict to convert dict to protobuf message
+        try:
+            param = ParseDict(item, ActionParameter())
+            out.append(param)
+        except Exception:
+            # If conversion fails, skip this item
+            pass
+    return out
+
+
+def with_canonical_action_docs(action: Action) -> Action:
+    """
+    Merge canonical docs (description/similes/parameters) into an Action.
+
+    Conservative merge rules:
+    - do not overwrite an existing description
+    - do not overwrite existing similes
+    - do not overwrite existing parameters
+    """
+    doc = _ACTION_DOCS.get(action.name)
+    if not doc:
+        return action
+
+    update: dict[str, object] = {}
+
+    if not action.description:
+        desc = doc.get("description")
+        if isinstance(desc, str):
+            update["description"] = desc
+
+    if not action.similes:
+        similes = doc.get("similes")
+        if isinstance(similes, list) and all(isinstance(s, str) for s in similes):
+            update["similes"] = similes
+
+    if not action.parameters:
+        params = doc.get("parameters")
+        converted = _coerce_action_parameters(params)
+        if converted:
+            update["parameters"] = converted
+
+    if not update:
+        return action
+
+    for key, value in update.items():
+        setattr(action, key, value)
+    return action
+
+
+def with_canonical_evaluator_docs(evaluator: Evaluator) -> Evaluator:
+    doc = _EVALUATOR_DOCS.get(evaluator.name)
+    if not doc:
+        return evaluator
+
+    update: dict[str, object] = {}
+
+    if not evaluator.description:
+        desc = doc.get("description")
+        if isinstance(desc, str):
+            update["description"] = desc
+
+    if not evaluator.similes:
+        similes = doc.get("similes")
+        if isinstance(similes, list) and all(isinstance(s, str) for s in similes):
+            update["similes"] = similes
+
+    if not evaluator.examples:
+        examples = doc.get("examples")
+        if isinstance(examples, list):
+            update["examples"] = examples
+
+    if not update:
+        return evaluator
+
+    for key, value in update.items():
+        setattr(evaluator, key, value)
+    return evaluator
+
+
+def get_canonical_action_example_calls(action_name: str) -> list[dict[str, object]]:
+    """
+    Return canonical action-call examples for an action, if present.
+
+    These are the examples that include explicit `<actions>` and optional `<params>` payloads.
+    """
+    doc = _ACTION_DOCS.get(action_name)
+    if not doc:
+        return []
+    calls = doc.get("exampleCalls")
+    if not isinstance(calls, list):
+        return []
+    out: list[dict[str, object]] = []
+    for item in calls:
+        if isinstance(item, dict):
+            out.append(item)
+    return out