@elizaos/schemas 2.0.0-alpha.3

package/README.md

@@ -0,0 +1,199 @@
+# elizaOS Protocol Buffer Schemas
+
+This directory contains the **single source of truth** for all elizaOS types. These Protocol Buffer schemas are compiled to generate type definitions for TypeScript, Python, and Rust.
+
+## Architecture
+
+```
+schemas/
+├── buf.yaml              # Buf module configuration
+├── buf.gen.yaml          # Code generation configuration
+├── eliza/v1/             # Proto definitions (versioned)
+│   ├── primitives.proto  # UUID, Content, Media, Metadata
+│   ├── memory.proto      # Memory, MemoryMetadata
+│   ├── state.proto       # State, ActionPlan, WorkingMemory
+│   ├── environment.proto # Entity, Room, World, Relationship
+│   ├── components.proto  # Action, Provider, Evaluator
+│   ├── agent.proto       # Character, Agent
+│   ├── service.proto     # Service types
+│   ├── model.proto       # Model types, generation params
+│   ├── events.proto      # Event types and payloads
+│   ├── plugin.proto      # Plugin, Route definitions
+│   ├── task.proto        # Task types
+│   ├── database.proto    # Database, logging types
+│   ├── messaging.proto   # WebSocket, streaming types
+│   └── ipc.proto         # Cross-language IPC messages
+└── README.md
+
+Generated output:
+├── packages/typescript/src/types/generated/  # TypeScript
+├── packages/python/elizaos/types/generated/  # Python
+└── packages/rust/src/types/generated/        # Rust
+```
+
+## Quick Start
+
+### Prerequisites
+
+Install Buf CLI:
+
+```bash
+# macOS
+brew install bufbuild/buf/buf
+
+# Linux
+curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-$(uname -s)-$(uname -m)" -o /usr/local/bin/buf
+chmod +x /usr/local/bin/buf
+
+# npm (cross-platform)
+npm install -g @bufbuild/buf
+```
+
+### Generate Types
+
+```bash
+# From the schemas directory
+cd schemas
+
+# Lint proto files
+buf lint
+
+# Generate code for all languages
+buf generate
+
+# Or use the npm script from project root
+npm run generate:types
+```
+
+### Development Workflow
+
+1. **Edit proto files** in `eliza/v1/`
+2. **Run `buf lint`** to check for errors
+3. **Run `buf generate`** to regenerate types
+4. **Commit both** proto changes and generated code
+
+## Schema Design Principles
+
+### 1. Versioning
+
+All schemas are under `eliza/v1/`. When breaking changes are needed, create `eliza/v2/` and maintain both during migration.
+
+### 2. JSON Compatibility
+
+Proto3 has first-class JSON mapping. All messages can be serialized to JSON for debugging:
+
+- `snake_case` in proto → `camelCase` in JSON (automatic)
+- Use `google.protobuf.Struct` for dynamic/unknown fields
+
+### 3. Optional Fields
+
+Use `optional` keyword for fields that may not be present:
+
+```protobuf
+message Memory {
+  optional string id = 1;      // Optional on creation
+  string entity_id = 2;        // Always required
+}
+```
+
+### 4. Enums
+
+Always include `UNSPECIFIED = 0` as the first enum value:
+
+```protobuf
+enum MemoryType {
+  MEMORY_TYPE_UNSPECIFIED = 0;
+  MEMORY_TYPE_DOCUMENT = 1;
+  MEMORY_TYPE_MESSAGE = 2;
+}
+```
+
+### 5. Dynamic Properties
+
+Use `google.protobuf.Struct` for JSON-like dynamic data:
+
+```protobuf
+import "google/protobuf/struct.proto";
+
+message Content {
+  string text = 1;
+  google.protobuf.Struct data = 2;  // Dynamic properties
+}
+```
+
+## Language-Specific Notes
+
+### TypeScript
+
+- Generated with `@bufbuild/protobuf`
+- Import from `@elizaos/core/types/generated`
+- Full TypeScript types with proper inference
+
+### Python
+
+- Generated with `betterproto` for clean, Pythonic code
+- Dataclass-style types with type hints
+- Import from `elizaos.types.generated`
+
+### Rust
+
+- Generated with `prost` (WASM-compatible)
+- Includes `serde` support for JSON serialization
+- Import from `elizaos::types::generated`
+
+## Adding New Types
+
+1. Create or edit a `.proto` file in `eliza/v1/`
+2. Follow naming conventions:
+   - Messages: `PascalCase`
+   - Fields: `snake_case`
+   - Enums: `SCREAMING_SNAKE_CASE`
+   - Enum values: `ENUM_NAME_VALUE_NAME`
+3. Run `buf lint` to validate
+4. Run `buf generate` to create code
+5. Update imports in consuming code
+
+## Migration from Manual Types
+
+The generated types replace the manual type definitions in:
+
+- `packages/typescript/src/types/*.ts`
+- `packages/python/elizaos/types/*.py`
+- `packages/rust/src/types/*.rs`
+
+### Compatibility Layer
+
+During migration, a compatibility layer re-exports generated types with the original names. This allows gradual migration:
+
+```typescript
+// packages/typescript/src/types/index.ts
+export * from "./generated";
+export { Memory as MemoryType } from "./generated/eliza/v1/memory_pb";
+```
+
+## Buf Commands Reference
+
+```bash
+# Lint proto files
+buf lint
+
+# Check for breaking changes
+buf breaking --against '.git#branch=main'
+
+# Generate code
+buf generate
+
+# Update dependencies
+buf dep update
+
+# Format proto files
+buf format -w
+```
+
+## Resources
+
+- [Buf Documentation](https://buf.build/docs)
+- [Protocol Buffers Language Guide](https://protobuf.dev/programming-guides/proto3/)
+- [bufbuild/protobuf-es](https://github.com/bufbuild/protobuf-es) (TypeScript)
+- [danielgtaylor/python-betterproto](https://github.com/danielgtaylor/python-betterproto) (Python)
+- [tokio-rs/prost](https://github.com/tokio-rs/prost) (Rust)

package/buf.gen.yaml

@@ -0,0 +1,28 @@
+# buf.gen.yaml - Code generation configuration for multiple languages
+version: v2
+
+managed:
+  enabled: true
+  override:
+    - file_option: go_package_prefix
+      value: github.com/elizaos/eliza/gen/go
+
+plugins:
+  # TypeScript generation using @bufbuild/protobuf
+  - remote: buf.build/bufbuild/es:v2.2.2
+    out: ../typescript/src/types/generated
+    opt:
+      - target=ts
+      - import_extension=.js
+
+  # Python generation using standard protobuf
+  - remote: buf.build/protocolbuffers/python
+    out: ../python/elizaos/types/generated
+
+  # Python type stubs
+  - remote: buf.build/protocolbuffers/pyi
+    out: ../python/elizaos/types/generated
+
+  # Rust generation using prost (WASM-compatible)
+  - remote: buf.build/community/neoeinstein-prost:v0.4.0
+    out: ../rust/src/types/generated

package/buf.yaml

@@ -0,0 +1,16 @@
+# buf.yaml - Buf configuration for elizaOS proto schemas
+version: v2
+modules:
+  - path: .
+    name: buf.build/elizaos/eliza
+lint:
+  use:
+    - STANDARD
+  except:
+    - FIELD_NOT_REQUIRED
+    - PACKAGE_NO_IMPORT_CYCLE
+breaking:
+  use:
+    - FILE
+deps:
+  - buf.build/googleapis/googleapis

package/eliza/v1/agent.proto

@@ -0,0 +1,119 @@
+// agent.proto - Agent and Character types for elizaOS
+syntax = "proto3";
+
+package eliza.v1;
+
+import "eliza/v1/primitives.proto";
+import "google/protobuf/struct.proto";
+
+// Agent status enumeration
+enum AgentStatus {
+  AGENT_STATUS_UNSPECIFIED = 0;
+  AGENT_STATUS_ACTIVE = 1;
+  AGENT_STATUS_INACTIVE = 2;
+}
+
+// Example message for demonstration
+message MessageExample {
+  string name = 1;
+  Content content = 2;
+}
+
+// Knowledge item - can be a path or directory reference
+message KnowledgeItem {
+  oneof item {
+    string path = 1;
+    KnowledgeDirectory directory = 2;
+  }
+}
+
+// Knowledge directory with optional shared flag
+message KnowledgeDirectory {
+  string path = 1;
+  optional bool shared = 2;
+}
+
+// Character settings (well-known keys with expected types)
+message CharacterSettings {
+  // Model type to use for shouldRespond evaluation
+  optional string should_respond_model = 1; // "small" | "large"
+  // Whether to use multi-step workflow
+  optional bool use_multi_step = 2;
+  // Maximum iterations for multi-step
+  optional int32 max_multistep_iterations = 3;
+  // Whether LLM is off by default in rooms
+  optional bool bootstrap_defllmoff = 4;
+  // Whether to keep responses when superseded
+  optional bool bootstrap_keep_resp = 5;
+  // Provider execution timeout in ms
+  optional int32 providers_total_timeout_ms = 6;
+  // Maximum working memory entries
+  optional int32 max_working_memory_entries = 7;
+  // Channel types that always trigger response
+  optional string always_respond_channels = 8;
+  // Sources that always trigger response
+  optional string always_respond_sources = 9;
+  // Model temperature
+  optional double default_temperature = 10;
+  // Maximum tokens for text generation
+  optional int32 default_max_tokens = 11;
+  // Frequency penalty
+  optional double default_frequency_penalty = 12;
+  // Presence penalty
+  optional double default_presence_penalty = 13;
+  // Disable basic capabilities
+  optional bool disable_basic_capabilities = 14;
+  // Enable extended capabilities
+  optional bool enable_extended_capabilities = 15;
+  // Additional dynamic settings
+  google.protobuf.Struct extra = 16;
+}
+
+// Writing style guides
+message StyleGuides {
+  repeated string all = 1;
+  repeated string chat = 2;
+  repeated string post = 3;
+}
+
+// Character configuration defining personality, knowledge, and capabilities
+message Character {
+  optional string id = 1;
+  string name = 2;
+  optional string username = 3;
+  optional string system = 4;
+  // Templates as map of name to template string
+  map<string, string> templates = 5;
+  // Bio can be a single string or multiple lines
+  repeated string bio = 6;
+  // Example messages grouped in arrays
+  repeated MessageExampleGroup message_examples = 7;
+  repeated string post_examples = 8;
+  repeated string topics = 9;
+  repeated string adjectives = 10;
+  repeated KnowledgeItem knowledge = 11;
+  repeated string plugins = 12;
+  optional CharacterSettings settings = 13;
+  // Secrets as key-value pairs
+  map<string, string> secrets = 14;
+  optional StyleGuides style = 15;
+  // Enable built-in advanced planning capabilities
+  optional bool advanced_planning = 16;
+  // Enable built-in advanced memory capabilities
+  optional bool advanced_memory = 17;
+}
+
+// Group of message examples (for nested array structure)
+message MessageExampleGroup {
+  repeated MessageExample examples = 1;
+}
+
+// Represents an operational agent
+message Agent {
+  // Inherits all Character fields
+  Character character = 1;
+  optional bool enabled = 2;
+  AgentStatus status = 3;
+  int64 created_at = 4;
+  int64 updated_at = 5;
+}

package/eliza/v1/components.proto

@@ -0,0 +1,111 @@
+// components.proto - Action, Provider, Evaluator types for elizaOS
+syntax = "proto3";
+
+package eliza.v1;
+
+import "eliza/v1/primitives.proto";
+import "google/protobuf/struct.proto";
+
+// JSON Schema for action parameter validation
+message ActionParameterSchema {
+  string type = 1;
+  optional string description = 2;
+  // Default value
+  google.protobuf.Value default_value = 3;
+  // Allowed enum values
+  repeated string enum_values = 4;
+  // Nested properties for object types
+  map<string, ActionParameterSchema> properties = 5;
+  // Item schema for array types
+  optional ActionParameterSchema items = 6;
+  // Numeric constraints
+  optional double minimum = 7;
+  optional double maximum = 8;
+  // String pattern (regex)
+  optional string pattern = 9;
+}
+
+// Defines a single parameter for an action
+message ActionParameter {
+  string name = 1;
+  string description = 2;
+  optional bool required = 3;
+  ActionParameterSchema schema = 4;
+}
+
+// Example content with associated user for demonstration
+message ActionExample {
+  string name = 1;
+  Content content = 2;
+}
+
+// Validated parameters passed to an action handler
+// Represented as a Struct for flexibility with nested values
+message ActionParameters {
+  google.protobuf.Struct values = 1;
+}
+
+// Result returned by an action after execution
+message ActionResult {
+  bool success = 1;
+  optional string text = 2;
+  google.protobuf.Struct values = 3;
+  google.protobuf.Struct data = 4;
+  optional string error = 5;
+}
+
+// Context provided to actions during execution
+message ActionContext {
+  repeated ActionResult previous_results = 1;
+}
+
+// Options passed to action handlers during execution
+message HandlerOptions {
+  optional ActionContext action_context = 1;
+  // Forward reference to ActionPlan (defined in state.proto)
+  optional string action_plan_json = 2; // Serialized ActionPlan
+  optional ActionParameters parameters = 3;
+}
+
+// Action manifest (metadata only, for cross-language interop)
+message ActionManifest {
+  string name = 1;
+  string description = 2;
+  repeated string similes = 3;
+  repeated ActionExample examples = 4;
+  optional int32 priority = 5;
+  repeated string tags = 6;
+  repeated ActionParameter parameters = 7;
+}
+
+// Result returned by a provider
+message ProviderResult {
+  optional string text = 1;
+  google.protobuf.Struct values = 2;
+  google.protobuf.Struct data = 3;
+}
+
+// Provider manifest (metadata only, for cross-language interop)
+message ProviderManifest {
+  string name = 1;
+  optional string description = 2;
+  optional bool dynamic = 3;
+  optional int32 position = 4;
+  optional bool private = 5;
+}
+
+// Example for evaluating agent behavior
+message EvaluationExample {
+  string prompt = 1;
+  repeated ActionExample messages = 2;
+  string outcome = 3;
+}
+
+// Evaluator manifest (metadata only, for cross-language interop)
+message EvaluatorManifest {
+  string name = 1;
+  string description = 2;
+  optional bool always_run = 3;
+  repeated string similes = 4;
+  repeated EvaluationExample examples = 5;
+}

package/eliza/v1/database.proto

@@ -0,0 +1,199 @@
+// database.proto - Database and logging types for elizaOS
+syntax = "proto3";
+
+package eliza.v1;
+
+import "eliza/v1/memory.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+
+// Run status enumeration
+enum DbRunStatus {
+  DB_RUN_STATUS_UNSPECIFIED = 0;
+  DB_RUN_STATUS_STARTED = 1;
+  DB_RUN_STATUS_COMPLETED = 2;
+  DB_RUN_STATUS_TIMEOUT = 3;
+  DB_RUN_STATUS_ERROR = 4;
+}
+
+// Base log body type
+message BaseLogBody {
+  optional string run_id = 1;
+  optional string parent_run_id = 2;
+  optional string status = 3;
+  optional string message_id = 4;
+  optional string room_id = 5;
+  optional string entity_id = 6;
+  google.protobuf.Struct metadata = 7;
+}
+
+// Action log content structure
+message ActionLogContent {
+  repeated string actions = 1;
+  optional string text = 2;
+  optional string thought = 3;
+}
+
+// Action result for logging
+message ActionLogResult {
+  optional bool success = 1;
+  google.protobuf.Struct data = 2;
+  optional string text = 3;
+  optional string error = 4;
+}
+
+// Prompt tracking for action logs
+message ActionLogPrompt {
+  string model_type = 1;
+  string prompt = 2;
+  int64 timestamp = 3;
+}
+
+// Action log body
+message ActionLogBody {
+  BaseLogBody base = 1;
+  optional string action = 2;
+  optional string action_id = 3;
+  optional string message = 4;
+  google.protobuf.Struct state = 5;
+  repeated google.protobuf.Struct responses = 6;
+  optional ActionLogContent content = 7;
+  optional ActionLogResult result = 8;
+  repeated ActionLogPrompt prompts = 9;
+  optional int32 prompt_count = 11;
+  optional string plan_step = 12;
+  optional string plan_thought = 13;
+}
+
+// Evaluator log body
+message EvaluatorLogBody {
+  BaseLogBody base = 1;
+  optional string evaluator = 2;
+  optional string message = 3;
+  google.protobuf.Struct state = 4;
+}
+
+// Model action context
+message ModelActionContext {
+  string action_name = 1;
+  string action_id = 2;
+}
+
+// Model log body
+message ModelLogBody {
+  BaseLogBody base = 1;
+  optional string model_type = 2;
+  optional string model_key = 3;
+  google.protobuf.Struct params = 4;
+  optional string prompt = 5;
+  optional string system_prompt = 6;
+  optional int64 timestamp = 7;
+  optional int64 execution_time = 8;
+  optional string provider = 9;
+  optional ModelActionContext action_context = 10;
+  google.protobuf.Value response = 11;
+}
+
+// Embedding log body
+message EmbeddingLogBody {
+  BaseLogBody base = 1;
+  optional string memory_id = 2;
+  optional int64 duration = 3;
+}
+
+// Union of all log body types
+message LogBody {
+  oneof body {
+    BaseLogBody base = 1;
+    ActionLogBody action = 2;
+    EvaluatorLogBody evaluator = 3;
+    ModelLogBody model = 4;
+    EmbeddingLogBody embedding = 5;
+  }
+}
+
+// Log entry
+message Log {
+  optional string id = 1;
+  string entity_id = 2;
+  optional string room_id = 3;
+  LogBody body = 4;
+  string type = 5;
+  google.protobuf.Timestamp created_at = 6;
+}
+
+// Agent run counts
+message AgentRunCounts {
+  int32 actions = 1;
+  int32 model_calls = 2;
+  int32 errors = 3;
+  int32 evaluators = 4;
+}
+
+// Agent run summary
+message AgentRunSummary {
+  string run_id = 1;
+  DbRunStatus status = 2;
+  optional int64 started_at = 3;
+  optional int64 ended_at = 4;
+  optional int64 duration_ms = 5;
+  optional string message_id = 6;
+  optional string room_id = 7;
+  optional string entity_id = 8;
+  google.protobuf.Struct metadata = 9;
+  optional AgentRunCounts counts = 10;
+}
+
+// Agent run summary result
+message AgentRunSummaryResult {
+  repeated AgentRunSummary runs = 1;
+  int32 total = 2;
+  bool has_more = 3;
+}
+
+// Embedding search result
+message EmbeddingSearchResult {
+  repeated float embedding = 1;
+  int32 levenshtein_score = 2;
+}
+
+// Memory retrieval options
+message MemoryRetrievalOptions {
+  string room_id = 1;
+  optional int32 count = 2;
+  optional bool unique = 3;
+  optional int64 start = 4;
+  optional int64 end = 5;
+  optional string agent_id = 6;
+}
+
+// Memory search options
+message MemorySearchOptions {
+  repeated float embedding = 1;
+  optional float match_threshold = 2;
+  optional int32 count = 3;
+  string room_id = 4;
+  optional string agent_id = 5;
+  optional bool unique = 6;
+  optional MemoryMetadata metadata = 7;
+}
+
+// Multi-room memory options
+message MultiRoomMemoryOptions {
+  repeated string room_ids = 1;
+  optional int32 limit = 2;
+  optional string agent_id = 3;
+}
+
+// Vector dimensions constants
+// Note: Proto doesn't have const, so this is just for documentation
+// SMALL: 384, MEDIUM: 512, LARGE: 768, XL: 1024, XXL: 1536, XXXL: 3072
+enum VectorDimension {
+  VECTOR_DIMENSION_UNSPECIFIED = 0;
+  VECTOR_DIMENSION_SMALL = 384;
+  VECTOR_DIMENSION_MEDIUM = 512;
+  VECTOR_DIMENSION_LARGE = 768;
+  VECTOR_DIMENSION_XL = 1024;
+  VECTOR_DIMENSION_XXL = 1536;
+  VECTOR_DIMENSION_XXXL = 3072;
+}