plugin-undesirables 2.0.1 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +123 -70
  2. package/dist/index.d.ts +7 -6
  3. package/dist/index.js +435 -365
  4. package/dist/index.js.map +1 -1
  5. package/images/banner.jpg +0 -0
  6. package/images/logo.jpg +0 -0
  7. package/package.json +12 -4
  8. package/dist/index.d.ts.map +0 -1
  9. package/og_preview.png +0 -0
  10. package/src/index.ts +0 -554
  11. package/tsconfig.json +0 -20
package/README.md CHANGED
@@ -1,124 +1,177 @@
1
1
  # plugin-undesirables
2
2
 
3
- ![The Undesirables Banner](./og_preview.png)
3
+ ![The Undesirables Banner](./images/banner.jpg)
4
4
 
5
- [![npm version](https://img.shields.io/npm/v/plugin-undesirables.svg?style=flat-square)](https://www.npmjs.org/package/plugin-undesirables)
6
- [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](https://mariadb.com/bsl11/)
5
+ [![npm version](https://img.shields.io/npm/v/plugin-undesirables.svg)](https://www.npmjs.org/package/plugin-undesirables)
6
+ [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE)
7
7
 
8
- > ElizaOS plugin for **The Undesirables** — 4,444 autonomous AI agents on Ethereum.
8
+ > Give any ElizaOS agent a persistent personality, market analysis skills, business automation, and content creation — all driven by a downloadable "soul workspace."
9
9
 
10
10
  ---
11
11
 
12
- ## 🛑 Prerequisites (Read Carefully)
13
- If you are new to running AI agents, you **must** have the following installed on your computer before continuing:
14
- 1. **[Node.js](https://nodejs.org)** (Version 23+ recommended).
15
- 2. **An existing ElizaOS bot**. This is a huge multi-agent framework. If you don't have one running yet, go read the official [ElizaOS documentation](https://elizaos.github.io/eliza/) first to set up your bot locally, then come back here to drop your Undesirable soul into it!
12
+ ## What This Does
16
13
 
17
- ---
18
-
19
- ## 📂 Step 1: Downloading Your Soul Workspace
14
+ Most AI agents are blank slates. They answer questions but have no personality, no memory, no conviction. This plugin changes that.
20
15
 
21
- Your AI agent isn't just code—it has an actual personality governed completely by the visual traits of your specific NFT.
16
+ When you install `plugin-undesirables`, your ElizaOS agent gets:
22
17
 
23
- 1. Go to [the-undesirables.com/soul](https://the-undesirables.com/soul) and connect the wallet holding your NFT.
24
- 2. Click **Download Workspace**.
25
- 3. Move the downloaded `.zip` file into a safe folder on your computer (like your Desktop) and **unzip it**.
26
- 4. This unzipped folder is your **Workspace**. *Do not arbitrarily delete files inside of it.*
18
+ - **A real personality** — not a system prompt hack, but a structured workspace with Big Five psychology scores, an archetype, a strategy style, adjectives, guardrails, and a backstory. The personality persists across sessions and colors every response.
19
+ - **Market analysis with conviction** — your agent doesn't just parrot data. It filters through its own risk tolerance and strategy to give you opinionated takes with conviction scores.
20
+ - **23 built-in skills** — portfolio checks, entry signals, exit strategies, whale tracking, meme creation, video production, music generation, and more. The agent auto-matches the right skill to your message.
21
+ - **Business Pilot** — 23 AI-powered business automation modules: phone answering, SMS autoresponders, invoice chasers, appointment scheduling. Your agent becomes a business operations assistant.
22
+ - **Meme Machine** — content creation, brand voice setup, content calendars, and industry-specific meme packs. Your agent becomes a social media manager.
27
23
 
28
24
  ---
29
25
 
30
- ## 🔧 Step 2: Injecting the Plugin
26
+ ## Quick Start
31
27
 
32
- Open your computer's terminal, navigate to your existing ElizaOS bot folder, and install this specific adapter plugin:
28
+ ### 1. Install
33
29
 
34
30
  ```bash
35
- # Mac / Linux / Windows
36
31
  npm install plugin-undesirables
37
32
  ```
38
33
 
39
- Next, open your Eliza agent's main `character.json` file. You need to do two strict things:
40
- 1. Add the plugin to your `plugins` array.
41
- 2. Provide the **ABSOLUTE FULL PATH** on your hard drive to the Soul Workspace you unzipped in Step 1.
34
+ ### 2. Get a Soul Workspace
35
+
36
+ Go to [the-undesirables.com/soul](https://the-undesirables.com/soul), connect your wallet, and download your workspace. Unzip it somewhere on your machine.
37
+
38
+ Each workspace contains:
39
+ - `SOUL.md` — personality profile (Big Five scores, archetype, strategy, backstory)
40
+ - `SYSTEM_PROMPT.txt` — the full instruction set
41
+ - `MEMORY.md` — persistent memory file
42
+ - `PREDICTIONS_LEDGER.json` — track record of market calls
43
+ - `skills/` — 10-23 skill files depending on the agent's traits
44
+
45
+ ### 3. Configure
46
+
47
+ Add to your ElizaOS `character.json`:
42
48
 
43
- **🍎 Example `character.json` on Mac (Use forward slashes `/`):**
49
+ **macOS / Linux:**
44
50
  ```json
45
51
  {
52
+ "plugins": ["plugin-undesirables"],
46
53
  "settings": {
47
- "UNDESIRABLES_WORKSPACE": "/Users/YourName/Desktop/soul_folder/0420"
48
- },
49
- "plugins": ["plugin-undesirables"]
54
+ "UNDESIRABLES_WORKSPACE": "/Users/YourName/Desktop/soul_0420"
55
+ }
50
56
  }
51
57
  ```
52
58
 
53
- **🪟 Example `character.json` on Windows (Use double backslashes `\\`):**
59
+ **Windows:**
54
60
  ```json
55
61
  {
62
+ "plugins": ["plugin-undesirables"],
56
63
  "settings": {
57
- "UNDESIRABLES_WORKSPACE": "C:\\Users\\YourName\\Desktop\\soul_folder\\0420"
58
- },
59
- "plugins": ["plugin-undesirables"]
64
+ "UNDESIRABLES_WORKSPACE": "C:\\Users\\YourName\\Desktop\\soul_0420"
65
+ }
60
66
  }
61
67
  ```
62
68
 
63
- ---
64
-
65
- ## 🏃 Step 3: Run It!
69
+ ### 4. Run
66
70
 
67
- Simply start your ElizaOS framework like normal. It will automatically read your exact personality from the Workspace and format your Twitter/Discord interactions!
68
71
  ```bash
69
72
  elizaos start --character your-character.json
70
73
  ```
71
74
 
75
+ Your agent now has a persistent personality that influences every conversation.
76
+
77
+ ---
78
+
79
+ ## Actions
80
+
81
+ | Action | Trigger Examples | What Happens |
82
+ |--------|-----------------|--------------|
83
+ | `UNDESIRABLE_MARKET_ANALYSIS` | "What do you think about ETH?" | Personality-driven market analysis with risk guardrails and conviction scoring |
84
+ | `UNDESIRABLE_BUSINESS_PILOT` | "Set up phone answering for my barbershop" | Loads the Business Pilot skill, recommends top modules with setup steps |
85
+ | `UNDESIRABLE_MEME_MACHINE` | "Create memes for my coffee shop" | Generates meme concepts, captions, content calendars, brand voice |
86
+ | `UNDESIRABLE_LOAD_SKILL` | "Check my portfolio" / "Should I ape?" | Auto-matches your message to one of 23 skills and executes it |
87
+
88
+ ### All 23 Skills
89
+
90
+ | Skill | Trigger Words |
91
+ |-------|--------------|
92
+ | Portfolio Check | "portfolio", "balance", "holdings" |
93
+ | Content Creation | "tweet", "write", "promote", "thread" |
94
+ | Entry Signal | "should I buy", "buy signal", "good time to buy" |
95
+ | Exit Strategy | "sell", "take profit", "stop loss" |
96
+ | Risk Assessment | "risk", "downside", "worst case", "is this safe" |
97
+ | Whale Tracker | "whale", "smart money", "what are whales buying" |
98
+ | Conviction Score | "conviction", "confidence", "how sure" |
99
+ | Snipe Launch | "snipe", "new launch", "just launched" |
100
+ | Memecoin Scanner | "memecoin", "find me a gem", "degen scan" |
101
+ | Ape Checklist | "should I ape", "ape check" |
102
+ | Position Sizing | "position size", "how much should I buy" |
103
+ | Volatility Scan | "volatile", "what's moving" |
104
+ | Liquidation Watch | "liquidation levels", "longs", "shorts" |
105
+ | MEV Detection | "mev", "sandwich", "front-running" |
106
+ | Farm Yield | "yield farming", "liquidity", "best yield" |
107
+ | Compound Strategy | "compound", "auto-compound", "apy" |
108
+ | Copy Trade | "copy trade", "mirror this wallet" |
109
+ | Rebalance Check | "rebalance", "allocation", "portfolio drift" |
110
+ | Diversification | "diversify", "spread", "concentrate" |
111
+ | Sector Rotation | "sector", "rotation", "cycle" |
112
+ | Image Generation | "image", "picture", "generate art" |
113
+ | Music Generation | "music", "song", "beat" |
114
+ | Video Production | "video", "promo", "render video" |
115
+
72
116
  ---
73
117
 
74
- ## ⚠️ Common Idiot-Proof Diagnostics
118
+ ## How Personality Works
75
119
 
76
- If your terminal crashes, stop and check here first:
120
+ Each soul workspace has a `SOUL.md` file with structured personality data:
77
121
 
78
- - **AssertionError: Workspace /path/ does not exist**
79
- The plugin cannot find your downloaded soul. Make sure you extracted the `.zip` file, and that you pasted the *exact, full absolute path* into your `character.json`. If you are on Windows, make sure you double-escaped your slashes (e.g. `C:\\Users\\...`).
80
-
81
- - **Invalid JSON Error**
82
- Your `character.json` is missing a comma or has a syntax error. Use a real code editor like VS Code or Cursor to format your JSON properly instead of Notepad.
122
+ ```yaml
123
+ name: "Doña Crypto"
124
+ archetype: "The Oracle"
125
+ strategy: "Long-term accumulation with high conviction"
126
+ adjectives: ["analytical", "patient", "contrarian"]
127
+ openness: 82
128
+ conscientiousness: 91
129
+ extraversion: 34
130
+ agreeableness: 45
131
+ neuroticism: 28
132
+ ```
133
+
134
+ The `soulProvider` injects this context into **every** agent response automatically. Your agent doesn't just have personality on request — it's always in character.
135
+
136
+ This means two different Undesirable agents will give you completely different takes on the same market question, filtered through their individual psychology.
83
137
 
84
138
  ---
85
-
86
- ## What It Does (Architecture)
87
139
 
88
- Adds soul personality, market analysis, Business Pilot (23 modules), Meme Machine, and 23 skills to any ElizaOS agent.
140
+ ## Multi-Agent Safety
89
141
 
90
- ### Actions
142
+ Workspaces are keyed by `runtime.agentId`. You can run multiple Undesirable agents in the same ElizaOS instance without personality collision. Agent #420 won't leak into Agent #69's responses.
91
143
 
92
- | Action | Trigger | Description |
93
- |--------|---------|-------------|
94
- | `UNDESIRABLE_MARKET_ANALYSIS` | "What do you think about ETH?" | Personality-driven market analysis with risk guardrails |
95
- | `UNDESIRABLE_BUSINESS_PILOT` | "Set up phone answering for my business" | 23 AI-powered business automation modules |
96
- | `UNDESIRABLE_MEME_MACHINE` | "Create memes for my barbershop" | Content creation, meme templates, industry packs |
97
- | `UNDESIRABLE_LOAD_SKILL` | "Check my portfolio" | Auto-matches and loads any of 23 skills |
144
+ ---
98
145
 
99
- ### Provider
146
+ ## Troubleshooting
100
147
 
101
- The `soulProvider` automatically injects the agent's personality context (archetype, strategy, adjectives, guardrails) into every single conversational response.
148
+ | Error | Fix |
149
+ |-------|-----|
150
+ | `Workspace /path/ does not exist` | Check the path in your `character.json`. It must be the **absolute** path to the unzipped workspace. Windows users: use double backslashes `\\`. |
151
+ | `Invalid JSON Error` | Your `character.json` has a syntax error. Open it in VS Code or Cursor and fix the formatting. |
152
+ | `No soul workspace loaded` | The `UNDESIRABLES_WORKSPACE` setting is missing or the path doesn't exist. |
102
153
 
103
- ## Converting Souls to character.json (Optional)
154
+ ---
104
155
 
105
- If you don't want to use the Plugin abstraction layer above, you can force-convert a `.md` workspace directly into a massive monolithic `character.json` file using our companion converter script:
106
- ```bash
107
- # Setup the MCP server repo and run:
108
- node soul-to-eliza.js --token 420
109
- ```
110
- → [undesirables-mcp-server](https://gitlab.com/meme-merchants/undesirables-mcp-server)
156
+ ## What's New in v2.0
157
+
158
+ - Action handlers route through `runtime.generateText()` instead of leaking raw prompt instructions
159
+ - Multi-agent state isolation — workspaces keyed by `agentId`
160
+ - Real `@elizaos/core` v2 types (no more hand-written stubs)
161
+ - Async filesystem (`fs.promises`)
162
+ - Secure YAML parsing (`js-yaml` with `JSON_SCHEMA`)
163
+ - ESM module format
164
+
165
+ ---
166
+
167
+ ## Related Projects
111
168
 
112
- ## The Undesirables Ecosystem
169
+ - [@undesirables/plugin-tcg-oracle](https://github.com/sailorpepe/elizaos-tcg-oracle-plugin) — Trading card market intelligence (search, grade, simulate)
170
+ - [undesirables-mcp-server](https://github.com/sailorpepe/undesirables-mcp-server) — 36-tool MCP server (Glama Registry, PyPI)
171
+ - [the-undesirables.com](https://the-undesirables.com) — The Undesirables NFT collection
113
172
 
114
- 4,444 autonomous AI agents on Ethereum. Each one has a unique personality derived from its visual traits.
173
+ ---
115
174
 
116
- - **Website**: [the-undesirables.com](https://the-undesirables.com)
117
- - **Mint**: [scatter.art/the-undesirables](https://scatter.art/the-undesirables)
118
- - **MCP Server**: [gitlab.com/meme-merchants/undesirables-mcp-server](https://gitlab.com/meme-merchants/undesirables-mcp-server)
119
- - **TCG Oracle Tools**: [pypi.org/project/tcg-oracle-tools](https://pypi.org/project/tcg-oracle-tools/)
120
- - **MCP on PyPI**: [pypi.org/project/undesirables-mcp-server](https://pypi.org/project/undesirables-mcp-server/)
121
- - **Kaggle Dataset**: [370K+ TCG products](https://www.kaggle.com/datasets/sailorpepe/tcg-market-intelligence)
122
- - **Contract**: [0xa893...17a](https://etherscan.io/token/0xa893648a701c03b14bf2fb767b72b2c55ed5c17a)
175
+ ## License
123
176
 
124
- EST. 2026 🐸
177
+ [BUSL-1.1](LICENSE) — Business Source License 1.1. Copyright © 2026 The Undesirables LLC.
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { Plugin } from '@elizaos/core';
2
+
1
3
  /**
2
4
  * The Undesirables — ElizaOS Plugin v2.0
3
5
  * ========================================
@@ -6,7 +8,7 @@
6
8
  *
7
9
  * Features:
8
10
  * - Load any of 4,444 unique soul personalities
9
- * - 23 unique skills across the collection (10 universal + 13 strategy-specific)
11
+ * - 34 unique tools across the collection
10
12
  * - Market analysis with personality-driven perspective
11
13
  * - Business Pilot — 23 AI-powered business modules
12
14
  * - Meme Machine — content creation & marketing
@@ -15,9 +17,9 @@
15
17
  * - Multi-agent safe (workspaces keyed by agentId)
16
18
  *
17
19
  * @see https://the-undesirables.com
18
- * @see https://gitlab.com/meme-merchants/undesirables-mcp-server
20
+ * @see https://github.com/sailorpepe/undesirables-mcp-server
19
21
  */
20
- import type { Plugin } from "@elizaos/core";
22
+
21
23
  interface SoulWorkspace {
22
24
  soulMd: string;
23
25
  systemPrompt: string;
@@ -28,6 +30,5 @@ interface SoulWorkspace {
28
30
  }
29
31
  declare function loadWorkspace(workspacePath: string): Promise<SoulWorkspace>;
30
32
  declare const undesirablePlugin: Plugin;
31
- export default undesirablePlugin;
32
- export { loadWorkspace, SoulWorkspace };
33
- //# sourceMappingURL=index.d.ts.map
33
+
34
+ export { type SoulWorkspace, undesirablePlugin as default, loadWorkspace };