@indra.ai/deva 1.65.23 → 1.65.25

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.
@@ -12,7 +12,7 @@
12
12
  </span>
13
13
  </label>
14
14
  <div class="trigger">
15
- {%- assign nav = "Core:/core/,Docs:/docs/,Guide:/guide/,Tests:/tests/,Vibe:/vibe/,VLA:/vla/,About:/about/" | split: "," -%}
15
+ {%- assign nav = "Docs:/docs/,Buddy:/buddy/,Guide:/guide/,Tests:/tests/,Core:/core/,Vibe:/vibe/,VLA:/vla/,About:/about/" | split: "," -%}
16
16
  {%- for item in nav -%}
17
17
  {%- assign parts = item | split: ":" -%}
18
18
  {%- assign href = parts[1] -%}
package/buddy/index.md ADDED
@@ -0,0 +1,247 @@
1
+ ---
2
+ layout: page
3
+ title: Deva Buddy
4
+ permalink: /buddy/
5
+ description: Deva Buddy asks a few questions and builds a new Deva for you, with its data file, a stub client, help files, assets and a starter test, ready to run.
6
+ image: /assets/banner.png
7
+ ---
8
+
9
+ {% assign buddy = site.data.buddy.DATA %}
10
+
11
+ {{ page.description }}
12
+
13
+ Deva Buddy comes with Deva Core. It's a small Deva itself, so it walks the same path as every other Deva: it comes online, asks its questions, copies the template, and fills in your answers.
14
+
15
+ ## What you need
16
+
17
+ - **Node.js and npm**, the same versions the [Guide](/guide/) uses.
18
+ - A project set up as an ES module, with Deva Core installed:
19
+
20
+ ```bash
21
+ mkdir my-devas
22
+ cd my-devas
23
+ npm init -y
24
+ npm pkg set type=module
25
+ npm install @indra.ai/deva
26
+ ```
27
+
28
+ Buddy needs no other packages.
29
+
30
+ ## Run Buddy
31
+
32
+ From your project folder, run:
33
+
34
+ ```bash
35
+ npx deva-buddy
36
+ ```
37
+
38
+ If you're working inside a copy of the Deva Core repository instead, run:
39
+
40
+ ```bash
41
+ npm run buddy
42
+ ```
43
+
44
+ Buddy prints its banner and version, comes online with `⭐️ READY`, and then asks its questions one at a time.
45
+
46
+ ## The questions
47
+
48
+ Press Enter to keep the default shown in brackets. **Key** and **Name** have no default, so you must answer them.
49
+
50
+ | Question | Default | What it's for |
51
+ |---|---|---|
52
+ {% for q in buddy.vars.questions %}| **{{ q.message }}** | {% if q.default != "" %}`{{ q.default }}`{% else %}none{% endif %} | {% case q.name %}{% when "key" %}The Deva's key. It names the folder, the agent key, the prompt text and the constant in `index.js`.{% when "vector" %}The Vector the Deva belongs to, saved in its profile.{% when "name" %}The Deva's display name, used in its files, help and tests.{% when "describe" %}A short description, saved in its profile.{% when "pronouns" %}Saved in its profile.{% when "gender" %}Saved in its profile.{% when "owner" %}The owner and creator, used in the profile and the copyright lines. Type your own name here.{% endcase %} |
53
+ {% endfor %}| **DIRECTORY** | `devas` in the folder you ran Buddy from | Where Buddy puts the new Deva. It creates this folder if it's missing. |
54
+
55
+ ### Key rules
56
+
57
+ The key must be **lowercase letters and numbers, starting with a letter**. No spaces, dashes, dots or capitals. Buddy checks this because the key becomes the folder name and the name you import the Deva by.
58
+
59
+ | Key | OK? |
60
+ |---|---|
61
+ | `hello` | Yes |
62
+ | `hello2` | Yes |
63
+ | `Hello` | No, capital letter |
64
+ | `hello-world` | No, dash |
65
+ | `2hello` | No, starts with a number |
66
+
67
+ Also skip JavaScript reserved words such as `class`, `default` or `import`. Buddy accepts them, but the import line it prints won't run.
68
+
69
+ The Name can be anything you like, including spaces and accented letters.
70
+
71
+ ## A full run
72
+
73
+ Here's a real run that builds a Deva called **Hello Deva** with the key `hello`. Your paths, version and date will be your own.
74
+
75
+ ```
76
+ ⭐️ READY
77
+ Key: hello
78
+ Vector: Ether
79
+ Name: Hello Deva
80
+ Describe: My first Deva
81
+ Pronouns (they/them):
82
+ Gender (DEVA):
83
+ Owner (Quinn Michaels): Your Name
84
+ DIRECTORY (/home/you/my-devas/devas):
85
+ ::::::::::::::::::::::::::::
86
+ 👽 DEVA
87
+ ↪ KEY: hello
88
+ ↪ VECTOR: Ether
89
+ ↪ NAME: Hello Deva
90
+ ↪ DESCRIBE: My first Deva
91
+ ↪ PRONOUNS: they/them
92
+ ↪ GENDER: DEVA
93
+ ↪ OWNER: Your Name
94
+ ↪ DIRECTORY: /home/you/my-devas/devas
95
+ ::::::::::::::::::::::::::::
96
+ 📁 QUE FILES
97
+ ↪ fr: /home/you/my-devas/node_modules/@indra.ai/deva/buddy/template
98
+ ↪ to: /home/you/my-devas/devas/hello
99
+ ✅ QUE FILES COMPLETE
100
+ 📁 /home/you/my-devas/devas/hello
101
+ 📁 /home/you/my-devas/devas/hello/assets
102
+ 📁 /home/you/my-devas/devas/hello/data
103
+ 📁 /home/you/my-devas/devas/hello/help
104
+ 📝 /home/you/my-devas/devas/hello/assets/avatar.png
105
+ 📝 /home/you/my-devas/devas/hello/assets/background.png
106
+ 📝 /home/you/my-devas/devas/hello/assets/emoji.png
107
+ 📝 /home/you/my-devas/devas/hello/assets/image.png
108
+ 📝 /home/you/my-devas/devas/hello/data/client.json
109
+ 📝 /home/you/my-devas/devas/hello/data/index.json
110
+ 📝 /home/you/my-devas/devas/hello/help/corpus.feecting
111
+ 📝 /home/you/my-devas/devas/hello/help/main.feecting
112
+ 📝 /home/you/my-devas/devas/hello/index.js
113
+ 📝 /home/you/my-devas/devas/hello/index.test.js
114
+ ✅ DEVA CREATED: hello (Hello Deva)
115
+ 👉 Add hello to your Deva loader: import hello from './hello/index.js';
116
+ ```
117
+
118
+ ## Send the answers in one go
119
+
120
+ Buddy also reads answers piped in, one per line, in the same order as the questions. A blank line keeps the default. This is handy for scripts and bots:
121
+
122
+ ```bash
123
+ printf 'hello\nEther\nHello Deva\nMy first Deva\n\n\nYour Name\n\n' | npx deva-buddy
124
+ ```
125
+
126
+ The lines are Key, Vector, Name, Describe, Pronouns, Gender, Owner and Directory. Buddy prints each answer next to its question so the run reads the same as a typed one.
127
+
128
+ ## What Buddy builds
129
+
130
+ ```
131
+ devas/
132
+ hello/
133
+ index.js
134
+ index.test.js
135
+ data/
136
+ index.json
137
+ client.json
138
+ help/
139
+ main.feecting
140
+ corpus.feecting
141
+ assets/
142
+ avatar.png
143
+ background.png
144
+ emoji.png
145
+ image.png
146
+ ```
147
+
148
+ | File | What it is |
149
+ |---|---|
150
+ | `index.js` | The Deva itself, exported as `HELLO`. It has `info`, `agent`, `vars`, three utils that trim input, empty `listeners`, `modules`, `devas`, `func` and `methods`, plus `onReady` and `onError`. This is where you start building. |
151
+ | `index.test.js` | The starter test. See [Test it first](#test-it-first). |
152
+ | `data/index.json` | The agent and vars: key, a new id, prompt colors, the profile with your answers, and the lifecycle messages and contexts. |
153
+ | `data/client.json` | A stub client for testing, already carrying this Deva Core's VLA so the license check passes. See [The stub client](#the-stub-client). |
154
+ | `help/main.feecting` | The main help page. |
155
+ | `help/corpus.feecting` | The help corpus. |
156
+ | `assets/` | Placeholder images for the emoji, avatar, image and background in the profile. Swap in your own. |
157
+
158
+ Every text file gets your answers filled in: the key, name, owner, description, Vector, pronouns, gender, a new id, the year, the date, and the VLA number in the copyright header. The images are copied as they are.
159
+
160
+ `index.js` reads your project's `package.json` from two folders up, so keep the Deva at `devas/<key>/` under the folder that holds `package.json`, which is where Buddy puts it by default.
161
+
162
+ ## Test it first
163
+
164
+ Run the starter test right after Buddy finishes, before you change anything:
165
+
166
+ ```bash
167
+ node --test devas/hello/index.test.js
168
+ ```
169
+
170
+ You should see six passing tests:
171
+
172
+ ```
173
+ ✔ hello builds as a Deva and waits offline before init
174
+ ✔ hello data has no placeholders left from the build
175
+ ✔ hello comes online and walks to ready
176
+ ✔ hello agent matches the build
177
+ ✔ hello utils answer with trimmed text
178
+ ✔ hello stops through the full chain
179
+ ℹ tests 6
180
+ ℹ pass 6
181
+ ℹ fail 0
182
+ ```
183
+
184
+ | Test | What it checks |
185
+ |---|---|
186
+ | Builds and waits offline | The export is a Deva and reports offline before `init`. |
187
+ | No placeholders left | `data/index.json` and `data/client.json` have no `::name::` style placeholders left over. |
188
+ | Comes online | `init` walks start, enter, done and ready in order, each packet carries a uid and md5, sha256 and sha512 hashes, and the ready prompt arrives. |
189
+ | Agent matches | The agent key, name and owner match what you typed. |
190
+ | Utils | The three utils return trimmed text. |
191
+ | Stops | `stop` walks the full chain and ends on `shutdown`, with the key as its value. |
192
+
193
+ Six passes means the Deva is clean and you can start building. Run it again whenever you change something, and add your own tests to the same file as the Deva grows.
194
+
195
+ To test several Devas, list the files rather than the folder:
196
+
197
+ ```bash
198
+ node --test devas/hello/index.test.js devas/other/index.test.js
199
+ ```
200
+
201
+ ## Load it
202
+
203
+ Buddy's last line tells you the import to add to your Deva loader. If you don't have a loader yet, create `devas/index.js`:
204
+
205
+ ```js
206
+ import hello from './hello/index.js';
207
+ export default {hello};
208
+ ```
209
+
210
+ Then bring the Deva online from a file in your project folder, such as `run.js`:
211
+
212
+ ```js
213
+ import devas from './devas/index.js';
214
+ import Client from './devas/hello/data/client.json' with {type:'json'};
215
+
216
+ const {hello} = devas;
217
+ hello.listen('devacore:prompt', packet => console.log(packet.text));
218
+ await hello.init(structuredClone(Client.DATA));
219
+ console.log(hello.uid().uid);
220
+ await hello.stop();
221
+ ```
222
+
223
+ ```bash
224
+ node run.js
225
+ ```
226
+
227
+ Pass `Client.DATA` to `init`, not the whole file. The file wraps the client in a `DATA` key, the same way every Deva data file does.
228
+
229
+ ## The stub client
230
+
231
+ `data/client.json` is there so the new Deva can come online and pass its tests straight away. Buddy fills in its VLA from the Deva Core you ran it with, which is what the license check compares.
232
+
233
+ It's only a stub. For real work, replace it with your own client file and add that file to `.gitignore`, so your license details never leave your computer.
234
+
235
+ ## When Buddy stops
236
+
237
+ Buddy never writes over existing work. If something is wrong, it stops before creating anything and tells you why:
238
+
239
+ | Message | Why | Fix |
240
+ |---|---|---|
241
+ | `{{ buddy.vars.messages.incomplete }}` | Key or Name was blank, or a pipe ran out of lines. | Run Buddy again and answer both. |
242
+ | `{{ buddy.vars.messages.badkey }}` | The key has capitals, spaces, dashes or other characters, or starts with a number. | Use lowercase letters and numbers, starting with a letter. See [Key rules](#key-rules). |
243
+ | `{{ buddy.vars.messages.exists }} <folder>` | A Deva with that key is already in that directory. | Pick another key or another directory. Buddy leaves the existing folder alone. |
244
+
245
+ ## Next
246
+
247
+ New to Devas? The [Guide](/guide/) walks through every part of a Deva by hand, the same parts Buddy builds for you.
package/index.md CHANGED
@@ -32,6 +32,7 @@ Node.js 22 or later. ES modules only.
32
32
  ## Start here
33
33
 
34
34
  - [Read the documentation](/docs/), with install, a working quick start, the lifecycle, messaging between Devas, the packet, hashing, events and the method reference.
35
+ - [Make a new Deva with Deva Buddy](/buddy/), which asks a few questions and builds a ready-to-run Deva with its data, a stub client, help files and a starter test.
35
36
  - [Build your first Deva](/guide/), a step-by-step guide from an empty folder to a working Deva with a skill, a method and a listener, then a clean shutdown.
36
37
  - [Deva Core on GitHub](https://github.com/indraai/deva), where the code, the issues and the examples live.
37
38
  - [`@indra.ai/deva` on npm](https://www.npmjs.com/package/@indra.ai/deva), for the published package.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "id": "31711622713594414221",
3
3
  "name": "@indra.ai/deva",
4
- "version": "1.65.23",
4
+ "version": "1.65.25",
5
5
  "description": "Deva Core a Vedic-based Event Driven Context Aware Feature, Zone, Action, and State Machine integrated Artificial Intelligence Framework",
6
6
  "main": "index.js",
7
7
  "license": "VLA:31711622713594414221 LICENSE.md",