feat: introduce Dependency Injection to enhance developer experience

agent/package.json

@@ -43,6 +43,7 @@
         "@elizaos/plugin-binance": "workspace:*",
         "@elizaos/plugin-avail": "workspace:*",
         "@elizaos/plugin-bootstrap": "workspace:*",
+        "@elizaos/plugin-di": "workspace:*",
         "@elizaos/plugin-cosmos": "workspace:*",
         "@elizaos/plugin-intiface": "workspace:*",
         "@elizaos/plugin-coinbase": "workspace:*",

agent/src/index.ts

@@ -40,6 +40,7 @@ import {
 import { zgPlugin } from "@elizaos/plugin-0g";
 
 import { bootstrapPlugin } from "@elizaos/plugin-bootstrap";
+import { normalizeCharacter } from "@elizaos/plugin-di";
 import createGoatPlugin from "@elizaos/plugin-goat";
 // import { intifacePlugin } from "@elizaos/plugin-intiface";
 import { ThreeDGenerationPlugin } from "@elizaos/plugin-3d-generation";
@@ -1204,6 +1205,9 @@ const startAgents = async () => {
         characters = await loadCharacters(charactersArg);
     }
 
+    // Normalize characters for injectable plugins
+    characters = await Promise.all(characters.map(normalizeCharacter));
+
     try {
         for (const character of characters) {
             await startAgent(character, directClient);

packages/plugin-di/.npmignore

@@ -0,0 +1,6 @@
+*
+
+!dist/**
+!package.json
+!readme.md
+!tsup.config.ts

packages/plugin-di/README.md

@@ -0,0 +1,139 @@
+# @elizaos/plugin-di - Dependency Injection Plugin for Eliza
+
+This plugin provides a dependency injection system for Eliza plugins.
+
+## What is Dependency Injection?
+
+Dependency Injection is a design pattern that allows you to inject dependencies into a class or function. This pattern is useful for decoupling components and making your code more modular and testable.
+
+## Examples of How to build a Plugin using Dependency Injection
+
+Check the [example](./src/_examples/) folder for a simple example of how to create a plugin using Dependency Injection.
+
+## Decorators for Dependency Injection
+
+This plugin provides a set of decorators that you can use to inject dependencies into your classes or functions.
+
+### From inversify
+
+We use the [inversify](https://inversify.io/) library to provide the dependency injection system.
+The following decorators are provided by the [inversify](https://inversify.io/) library.
+
+#### `@injectable`
+
+> Category: Class Decorator
+
+This decorator marks a class as injectable. This means that you can inject this class into other classes using the `@inject` decorator.
+
+```typescript
+import { injectable } from "inversify";
+
+@injectable()
+class SampleClass {
+}
+```
+
+Remember to register the class with the container before injecting it into other classes.
+
+```typescript
+import { globalContainer } from "@elizaos/plugin-di";
+
+// Register the class with the container as a singleton, this means that the class will be instantiated only once.
+globalContainer.bind(SingletonClass).toSelf().inSingletonScope();
+// Register the class with the container as a request context, this means that the class will be instantiated for each request(in this case means each Character).
+globalContainer.bind(CharactorContextClass).toSelf().inRequestScope();
+```
+
+#### `@inject`
+
+> Category: Parameter Decorator
+
+This decorator marks a parameter as an injection target. This means that the parameter will be injected with the appropriate dependency when the class is instantiated.
+
+```typescript
+import { injectable, inject } from "inversify";
+
+@injectable()
+class SampleClass {
+  constructor(
+    // Inject the SampleDependency as a public property of the class.
+    @inject("SampleDependency") public sampleDependency: SampleDependency
+  ) {}
+}
+```
+
+### From di plugin
+
+DI plugin provides abstract classes that you can extend to create Injectable actions or evaluators.
+And that provides the following decorators to improve the readability of the code.
+
+#### `@property`
+
+> Category: Property Decorator
+
+This decorator is used to define a property in an action content class  which will be used to generate the action content object Schema and content description template for LLM object generation.
+
+```typescript
+import { z } from 'zod';
+import { property } from "@elizaos/plugin-di";
+
+class SampleActionContent {
+  @property({
+    description: "Sample property description",
+    schema: z.string(),
+  })
+  sampleProperty: string;
+}
+```
+
+## Abstract Classes for Injaectable Actions and Evaluators
+
+This plugin provides abstract classes that you can extend to create Injectable actions or evaluators.
+
+### `BaseInjectableAction`
+
+This abstract class simplify the creation of injectable actions.
+You don't need to think about the template for content generation, it will be generated automatically based on the properties of the content Class.
+What you need to implement is the `execute` method.
+
+```typescript
+import { injectable } from "inversify";
+import { BaseInjectableAction } from "@elizaos/plugin-di";
+
+class SampleActionContent {
+    @property({
+        description: "Sample property description",
+        schema: z.string(),
+    })
+    property1: string;
+}
+
+@injectable()
+class SampleAction extends BaseInjectableAction<SampleActionContent> {
+    constructor() {
+        super({
+            /** general action constent options */
+            contentClass: SampleActionContent,
+        });
+    }
+
+    /**
+     * It will be called by `handler` function when the action is triggered.
+     */
+    async execute(
+        content: SampleActionContent | null,
+        runtime: IAgentRuntime,
+        message: Memory,
+        state: State,
+        callback?: HandlerCallback
+    ): Promise<void> {
+        // Your action logic here
+    }
+}
+```
+
+### `BaseInjectableEvaluator`
+
+This abstract class simplify the creation of injectable evaluators.
+
+Please refer to the [sampleEvaluator](./src/_examples/sampleEvaluator.ts) for an example of how to create an evaluator.

packages/plugin-di/eslint.config.mjs

@@ -0,0 +1,3 @@
+import eslintGlobalConfig from "../../eslint.config.mjs";
+
+export default [...eslintGlobalConfig];

packages/plugin-di/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@elizaos/plugin-di",
+    "version": "0.1.9-alpha.1",
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "import": {
+                "@elizaos/source": "./src/index.ts",
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@elizaos/core": "workspace:*",
+        "inversify": "^6.2.1",
+        "reflect-metadata": "^0.2.2",
+        "uuid": "11.0.3",
+        "zod": "3.23.8"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "@types/uuid": "10.0.0",
+        "tsup": "8.3.5",
+        "vitest": "2.1.4"
+    },
+    "scripts": {
+        "build": "tsup --format esm --dts",
+        "dev": "tsup --format esm --dts --watch",
+        "lint": "eslint --fix  --cache .",
+        "test": "vitest run"
+    }
+}

packages/plugin-di/src/_examples/sampleAction.ts

@@ -0,0 +1,165 @@
+import {
+    IAgentRuntime,
+    Memory,
+    HandlerCallback,
+    State,
+    elizaLogger,
+} from "@elizaos/core";
+import { z } from "zod";
+import { inject, injectable } from "inversify";
+import { BaseInjectableAction } from "../actions";
+import { ActionOptions } from "../types";
+import { property } from "../decorators";
+import { globalContainer } from "../di";
+import { SampleProvider } from "./sampleProvider";
+
+/**
+ * The content class for the action
+ */
+export class CreateResourceContent {
+    @property({
+        description: "Name of the resource",
+        schema: z.string(),
+    })
+    name: string;
+
+    @property({
+        description: "Type of resource (document, image, video)",
+        schema: z.string(),
+    })
+    type: string;
+
+    @property({
+        description: "Description of the resource",
+        schema: z.string(),
+    })
+    description: string;
+
+    @property({
+        description: "Array of tags to categorize the resource",
+        schema: z.array(z.string()),
+    })
+    tags: string[];
+}
+
+/**
+ * Options for the CreateResource action
+ */
+const options: ActionOptions<CreateResourceContent> = {
+    name: "CREATE_RESOURCE",
+    similes: [],
+    description: "Create a new resource with the specified details",
+    examples: [
+        [
+            {
+                user: "{{user1}}",
+                content: {
+                    text: "Create a new resource with the name 'Resource1' and type 'TypeA'",
+                },
+            },
+            {
+                user: "{{agentName}}",
+                content: {
+                    text: `Resource created successfully:
+- Name: Resource1
+- Type: TypeA`,
+                },
+            },
+        ],
+        [
+            {
+                user: "{{user1}}",
+                content: {
+                    text: "Create a new resource with the name 'Resource2' and type 'TypeB'",
+                },
+            },
+            {
+                user: "{{agentName}}",
+                content: {
+                    text: `Resource created successfully:
+- Name: Resource2
+- Type: TypeB`,
+                },
+            },
+        ],
+    ],
+    contentClass: CreateResourceContent,
+};
+
+/**
+ * CreateResourceAction
+ */
+@injectable()
+export class CreateResourceAction extends BaseInjectableAction<CreateResourceContent> {
+    constructor(
+        @inject(SampleProvider)
+        private readonly sampleProvider: SampleProvider
+    ) {
+        super(options);
+    }
+
+    async validate(
+        runtime: IAgentRuntime,
+        _message: Memory,
+        _state?: State
+    ): Promise<boolean> {
+        return !!runtime.character.settings.secrets?.API_KEY;
+    }
+
+    async execute(
+        content: CreateResourceContent | null,
+        runtime: IAgentRuntime,
+        message: Memory,
+        state: State,
+        callback?: HandlerCallback
+    ): Promise<any | null> {
+        if (!content) {
+            const error = "No content provided for the action.";
+            elizaLogger.warn(error);
+            await callback?.({ text: error }, []);
+            return;
+        }
+
+        // Call injected provider to do some work
+        try {
+            const result = await this.sampleProvider.get(
+                runtime,
+                message,
+                state
+            );
+            if (!result) {
+                elizaLogger.warn("Provider did not return a result.");
+            } else {
+                elizaLogger.info("Privder result:", result);
+            }
+            // Use result in callback
+        } catch (error) {
+            elizaLogger.error("Provider error:", error);
+        }
+
+        // persist relevant data if needed to memory/knowledge
+        // const memory = {
+        //     type: "resource",
+        //     content: resourceDetails.object,
+        //     timestamp: new Date().toISOString()
+        // };
+
+        // await runtime.storeMemory(memory);
+
+        callback?.(
+            {
+                text: `Resource created successfully:
+- Name: ${content.name}
+- Type: ${content.type}
+- Description: ${content.description}
+- Tags: ${content.tags.join(", ")}
+
+Resource has been stored in memory.`,
+            },
+            []
+        );
+    }
+}
+
+// Register the action with the global container
+globalContainer.bind(CreateResourceAction).toSelf().inRequestScope();