@lakitu/sdk 0.1.1 → 0.1.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 (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +295 -97
  3. package/package.json +2 -2
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lakitu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -2,14 +2,75 @@
2
2
  <img src="assets/laki2-banner.jpeg" alt="Lakitu Banner" width="100%">
3
3
  </p>
4
4
 
5
- # Lakitu
5
+ # @lakitu/sdk
6
6
 
7
- > AI agent runtime using **code execution**, not JSON tool calls.
7
+ > Self-hosted AI agent framework for [Convex](https://convex.dev) + [E2B](https://e2b.dev) with **code execution**.
8
8
 
9
- Lakitu is an autonomous development environment that runs in an [E2B](https://e2b.dev) sandbox. The agent writes TypeScript code that imports from **KSAs** (Knowledge, Skills, and Abilities), which gets executed in the sandbox.
9
+ Lakitu runs AI agents in secure E2B sandboxes where they write and execute TypeScript code. Instead of JSON tool calls, agents import from **KSAs** (Knowledge, Skills, and Abilities) — plain TypeScript modules.
10
+
11
+ ## Quick Start
12
+
13
+ ```bash
14
+ # In your Convex project
15
+ npx @lakitu/sdk init
16
+
17
+ # Build your E2B sandbox template
18
+ npx @lakitu/sdk build
19
+
20
+ # Publish template to E2B
21
+ npx @lakitu/sdk publish
22
+ ```
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ npm install @lakitu/sdk
28
+ # or
29
+ bun add @lakitu/sdk
30
+ ```
31
+
32
+ ## CLI Commands
33
+
34
+ ### `npx @lakitu/sdk init`
35
+
36
+ Initialize Lakitu in your Convex project:
37
+
38
+ ```bash
39
+ npx @lakitu/sdk init
40
+ npx @lakitu/sdk init --dir ./convex # Custom convex directory
41
+ npx @lakitu/sdk init --skip-install # Skip npm install
42
+ ```
43
+
44
+ This creates:
45
+ ```
46
+ convex/
47
+ └── lakitu/
48
+ ├── config.ts # Lakitu configuration
49
+ └── example.ts # Example KSA to get started
50
+ ```
51
+
52
+ ### `npx @lakitu/sdk build`
53
+
54
+ Build your E2B sandbox template with pre-deployed Convex functions:
55
+
56
+ ```bash
57
+ npx @lakitu/sdk build # Build both base + custom templates
58
+ npx @lakitu/sdk build --base # Build base template only
59
+ npx @lakitu/sdk build --custom # Build custom template only
60
+ ```
61
+
62
+ ### `npx @lakitu/sdk publish`
63
+
64
+ Manage your E2B templates:
65
+
66
+ ```bash
67
+ npx @lakitu/sdk publish
68
+ ```
10
69
 
11
70
  ## The Code Execution Model
12
71
 
72
+ Traditional agents use JSON tool calls. Lakitu agents write code:
73
+
13
74
  ```
14
75
  Traditional Agent: Lakitu Agent:
15
76
  ┌─────────────────┐ ┌─────────────────┐
@@ -28,52 +89,176 @@ Traditional Agent: Lakitu Agent:
28
89
  └─────────┘ └───────────────┘
29
90
  ```
30
91
 
31
- **Why?** Token efficiency (no tool schemas), composability (chain operations in code), debuggability (read exactly what ran).
92
+ **Why code execution?**
93
+ - **Token efficient** — No tool schemas sent every request
94
+ - **Composable** — Chain operations naturally in code
95
+ - **Debuggable** — See exactly what code ran
96
+ - **Model agnostic** — Any LLM that generates code works
32
97
 
33
- ## KSAs (Knowledge, Skills, and Abilities)
98
+ ---
34
99
 
35
- KSAs are TypeScript modules the agent imports. They combine:
36
- - **Knowledge**: JSDoc documentation
37
- - **Skills**: Executable functions
38
- - **Abilities**: What the agent can accomplish
100
+ ## KSA SDK
39
101
 
40
- ### Available KSAs
102
+ KSAs (Knowledge, Skills, and Abilities) are capability modules that agents use via code execution. The SDK provides a type-safe builder API for defining KSAs.
41
103
 
42
- | Category | KSA | Functions |
43
- |----------|-----|-----------|
44
- | **System** | `file` | `read`, `write`, `edit`, `glob`, `grep`, `ls` |
45
- | | `browser` | `open`, `screenshot`, `click`, `type`, `getText` |
46
- | | `beads` | `create`, `update`, `close`, `list`, `getReady` |
47
- | | `pdf` | `generate` |
48
- | **Research** | `web` | `search`, `scrape`, `news` |
49
- | | `news` | `trending`, `monitorBrand`, `analyzeSentiment` |
50
- | | `social` | `tiktokProfile`, `instagramPosts`, `twitterPosts`, `searchSocial` |
51
- | **Data** | `companies` | `enrichDomain`, `searchCompanies`, `getTechStack` |
52
- | **Create** | `email` | `send`, `sendText`, `sendWithAttachment` |
104
+ ### Defining a KSA
105
+
106
+ ```typescript
107
+ import { defineKSA, fn, service, primitive } from "@lakitu/sdk";
108
+
109
+ export const myKSA = defineKSA("myKsa")
110
+ .description("Description of what this KSA does")
111
+ .category("skills") // "core" | "skills" | "deliverables"
112
+ .group("research") // Optional subcategory
113
+ .icon("mdi-search") // Optional MDI icon
114
+
115
+ // Add functions
116
+ .fn("search", fn()
117
+ .description("Search for something")
118
+ .param("query", { type: "string", required: true })
119
+ .param("limit", { type: "number", default: 10 })
120
+ .returns<SearchResult[]>()
121
+ .impl(service("services.Search.internal.query")
122
+ .mapArgs(({ query, limit }) => ({ q: query, max: limit }))
123
+ .mapResult(r => r.results)
124
+ )
125
+ )
53
126
 
54
- ### Example Agent Code
127
+ .fn("readFile", fn()
128
+ .description("Read a local file")
129
+ .param("path", { type: "string", required: true })
130
+ .impl(primitive("file.read"))
131
+ )
132
+
133
+ .build();
134
+ ```
135
+
136
+ ### SDK Exports
55
137
 
56
138
  ```typescript
57
- import { search, scrape } from './ksa/web';
58
- import { enrichDomain } from './ksa/companies';
59
- import { send } from './ksa/email';
60
-
61
- // Research a company
62
- const results = await search('Stripe payments company');
63
- const content = await scrape(results[0].url);
64
-
65
- // Enrich with company data
66
- const company = await enrichDomain('stripe.com');
67
- console.log(`${company.name}: ${company.industry}, ${company.employeeRange} employees`);
68
-
69
- // Send findings
70
- await send({
71
- to: 'user@example.com',
72
- subject: 'Company Research: Stripe',
73
- text: `Industry: ${company.industry}\nEmployees: ${company.employeeRange}`
139
+ import {
140
+ // Builders
141
+ defineKSA, // Create a KSA definition
142
+ fn, // Create a function definition
143
+ service, // Service implementation (calls cloud Convex)
144
+ primitive, // Primitive implementation (local sandbox ops)
145
+ composite, // Composite implementation (chain operations)
146
+
147
+ // Registry utilities
148
+ createRegistry,
149
+ getFunction,
150
+
151
+ // Types
152
+ type KSADef,
153
+ type FunctionDef,
154
+ type ParamDef,
155
+ type Implementation,
156
+ } from "@lakitu/sdk";
157
+ ```
158
+
159
+ ### Implementation Types
160
+
161
+ #### Service Implementation
162
+ Calls a Convex function via the cloud gateway:
163
+
164
+ ```typescript
165
+ .impl(service("services.MyService.internal.action")
166
+ .mapArgs(({ input }) => ({ data: input })) // Transform args
167
+ .mapResult(r => r.value) // Transform result
168
+ )
169
+ ```
170
+
171
+ #### Primitive Implementation
172
+ Uses local sandbox capabilities (file, shell, browser):
173
+
174
+ ```typescript
175
+ .impl(primitive("file.read"))
176
+ .impl(primitive("shell.exec"))
177
+ .impl(primitive("browser.screenshot"))
178
+ ```
179
+
180
+ Available primitives:
181
+ - `file.read`, `file.write`, `file.edit`, `file.glob`, `file.grep`, `file.ls`, `file.exists`, `file.stat`
182
+ - `shell.exec`
183
+ - `browser.open`, `browser.screenshot`, `browser.click`, `browser.type`, `browser.getHtml`, `browser.getText`, `browser.close`
184
+
185
+ #### Composite Implementation
186
+ Chain multiple operations:
187
+
188
+ ```typescript
189
+ .impl(composite()
190
+ .call("file.read", { filePath: "./config.json" }, "config")
191
+ .call("myKsa.process", ctx => ({ data: ctx.vars.config }), "result")
192
+ .return(ctx => ctx.vars.result)
193
+ )
194
+ ```
195
+
196
+ ### Parameter Types
197
+
198
+ ```typescript
199
+ .param("name", { type: "string", required: true })
200
+ .param("count", { type: "number", default: 10 })
201
+ .param("enabled", { type: "boolean", default: false })
202
+ .param("tags", { type: "array" })
203
+ .param("options", { type: "object" })
204
+ ```
205
+
206
+ ---
207
+
208
+ ## Configuration
209
+
210
+ After running `init`, configure Lakitu in `convex/lakitu/config.ts`:
211
+
212
+ ```typescript
213
+ import { Lakitu } from "@lakitu/sdk";
214
+
215
+ export default Lakitu.configure({
216
+ // E2B template name (build with: npx lakitu build)
217
+ template: "lakitu",
218
+
219
+ // Default model for agent
220
+ model: "anthropic/claude-sonnet-4-20250514",
221
+
222
+ // KSA modules to enable
223
+ ksas: [
224
+ // Built-in KSAs
225
+ "file",
226
+ "shell",
227
+ "browser",
228
+ "beads",
229
+
230
+ // Custom KSAs
231
+ "./myCustomKsa",
232
+ ],
233
+
234
+ // Sandbox pool settings
235
+ pool: {
236
+ min: 0,
237
+ max: 5,
238
+ idleTimeout: 300_000,
239
+ },
74
240
  });
75
241
  ```
76
242
 
243
+ ---
244
+
245
+ ## Built-in KSAs
246
+
247
+ | Category | KSA | Functions |
248
+ |----------|-----|-----------|
249
+ | **Core** | `file` | `read`, `write`, `edit`, `glob`, `grep`, `ls` |
250
+ | | `shell` | `exec` |
251
+ | | `browser` | `open`, `screenshot`, `click`, `type`, `getText` |
252
+ | | `beads` | `create`, `update`, `close`, `list`, `getReady` |
253
+ | **Skills** | `web` | `search`, `scrape` |
254
+ | | `news` | `trending`, `search`, `analyze` |
255
+ | | `social` | `tiktok`, `instagram`, `twitter`, `search` |
256
+ | | `companies` | `enrich`, `search`, `techStack` |
257
+ | **Deliverables** | `pdf` | `generate` |
258
+ | | `email` | `send`, `sendBulk` |
259
+
260
+ ---
261
+
77
262
  ## Architecture
78
263
 
79
264
  ```
@@ -92,7 +277,7 @@ await send({
92
277
  │ ▼ │
93
278
  │ ┌─────────────────────────────────────────────────────────────────┐ │
94
279
  │ │ CLOUD GATEWAY │ │
95
- │ │ HTTP → Convex Services (OpenRouter, APITube, ScrapeCreators) │ │
280
+ │ │ HTTP → Convex Services (OpenRouter, external APIs) │ │
96
281
  │ └─────────────────────────────────────────────────────────────────┘ │
97
282
  │ │
98
283
  │ ┌─────────────────────────────────────────────────────────────────┐ │
@@ -102,65 +287,78 @@ await send({
102
287
  └─────────────────────────────────────────────────────────────────────────┘
103
288
  ```
104
289
 
105
- ## Directory Structure
106
-
107
- ```
108
- lakitu/
109
- ├── ksa/ # KSA modules (agent imports these)
110
- │ ├── _shared/ # Shared utilities
111
- │ │ └── gateway.ts # Cloud gateway client
112
- │ ├── _templates/ # Templates for new KSAs
113
- │ ├── web.ts # Web search & scraping
114
- │ ├── news.ts # News research & monitoring
115
- │ ├── social.ts # Social media scraping
116
- │ ├── companies.ts # Company data enrichment
117
- │ ├── email.ts # Email sending
118
- │ ├── file.ts # File operations
119
- │ ├── browser.ts # Browser automation
120
- │ ├── beads.ts # Task tracking
121
- │ ├── pdf.ts # PDF generation
122
- │ └── index.ts # Discovery & exports
123
- │
124
- ├── convex/ # Convex backend
125
- │ ├── agent/ # Agent loop implementation
126
- │ │ └── codeExecLoop.ts # Code execution loop (no tool schemas)
127
- │ ├── actions/ # Convex actions
128
- │ │ └── codeExec.ts # Code execution runtime
129
- │ ├── prompts/ # System prompts
130
- │ │ └── codeExec.ts # KSA documentation for agent
131
- │ └── tools/ # LEGACY: Being removed
132
- │
133
- ├── shared/ # Shared types
134
- │ └── chain-of-thought.ts # Execution tracing
135
- │
136
- └── runtime/ # CLI commands for bash
137
- ```
138
-
139
- ## Adding New KSAs
140
-
141
- See `ksa/README.md` for detailed instructions. Quick steps:
142
-
143
- 1. Copy template from `ksa/_templates/`
144
- 2. Implement functions (use `callGateway()` for external services)
145
- 3. Add to `ksa/index.ts` registry
146
- 4. Document in system prompt (`convex/prompts/codeExec.ts`)
147
-
148
- ## Scripts
149
-
150
- | Command | Description |
151
- |---------|-------------|
152
- | `bun dev` | Start local Convex dev server |
153
- | `bun deploy` | Deploy to Convex cloud |
154
- | `bun test` | Run unit tests |
155
- | `bun typecheck` | TypeScript type check |
156
-
157
- ## Related Documentation
158
-
159
- - `CLAUDE.md` - Instructions for AI agents working on this codebase
160
- - `ksa/README.md` - KSA documentation and extension guide
161
- - `convex/prompts/codeExec.ts` - System prompt with KSA examples
290
+ ---
291
+
292
+ ## Example: Custom KSA
293
+
294
+ Create `convex/lakitu/weather.ts`:
295
+
296
+ ```typescript
297
+ import { defineKSA, fn, service } from "@lakitu/sdk";
298
+
299
+ export const weatherKSA = defineKSA("weather")
300
+ .description("Weather data and forecasts")
301
+ .category("skills")
302
+ .group("data")
303
+
304
+ .fn("current", fn()
305
+ .description("Get current weather for a location")
306
+ .param("location", { type: "string", required: true, description: "City name or coordinates" })
307
+ .impl(service("services.Weather.internal.getCurrent"))
308
+ )
309
+
310
+ .fn("forecast", fn()
311
+ .description("Get weather forecast")
312
+ .param("location", { type: "string", required: true })
313
+ .param("days", { type: "number", default: 7 })
314
+ .impl(service("services.Weather.internal.getForecast"))
315
+ )
316
+
317
+ .build();
318
+
319
+ export default weatherKSA;
320
+ ```
321
+
322
+ The agent can then use it:
323
+
324
+ ```typescript
325
+ import { current, forecast } from './ksa/weather';
326
+
327
+ const weather = await current("San Francisco");
328
+ console.log(`Current: ${weather.temp}°F, ${weather.condition}`);
329
+
330
+ const nextWeek = await forecast("San Francisco", 7);
331
+ for (const day of nextWeek) {
332
+ console.log(`${day.date}: ${day.high}°F / ${day.low}°F`);
333
+ }
334
+ ```
335
+
336
+ ---
337
+
338
+ ## Environment Variables
339
+
340
+ For `build` command:
341
+ - `E2B_API_KEY` — Your E2B API key (or run `e2b auth login`)
342
+
343
+ ---
344
+
345
+ ## Requirements
346
+
347
+ - [Convex](https://convex.dev) project
348
+ - [E2B](https://e2b.dev) account (for sandbox hosting)
349
+ - Node.js 18+ or Bun
350
+
351
+ ---
162
352
 
163
353
  ## Links
164
354
 
355
+ - [npm package](https://www.npmjs.com/package/@lakitu/sdk)
356
+ - [GitHub](https://github.com/shinyobjectz/lakitu)
165
357
  - [E2B Documentation](https://e2b.dev/docs)
166
358
  - [Convex Documentation](https://docs.convex.dev)
359
+
360
+ ---
361
+
362
+ ## License
363
+
364
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lakitu/sdk",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Self-hosted AI agent framework for Convex + E2B with code execution",
5
5
  "type": "module",
6
6
  "main": "./dist/sdk/index.js",
@@ -59,7 +59,7 @@
59
59
  ],
60
60
  "repository": {
61
61
  "type": "git",
62
- "url": "https://github.com/project-social/lakitu"
62
+ "url": "https://github.com/shinyobjectz/lakitu"
63
63
  },
64
64
  "license": "MIT",
65
65
  "dependencies": {