@lakitu/sdk 0.1.0

package/dist/sdk/builders.js

@@ -0,0 +1,214 @@
+/**
+ * KSA SDK Builders
+ *
+ * Fluent API for defining KSAs with full TypeScript type safety.
+ *
+ * @example
+ * ```typescript
+ * import { defineKSA, fn, service, primitive } from '@lakitu/sdk';
+ *
+ * export const webKSA = defineKSA('web')
+ *   .description('Web search and content extraction')
+ *   .category('skills')
+ *   .group('research')
+ *   .fn('search', fn()
+ *     .description('Search the web')
+ *     .param('query', { type: 'string', required: true })
+ *     .param('maxResults', { type: 'number', default: 10 })
+ *     .returns<SearchResult[]>()
+ *     .impl(service('services.Valyu.internal.search')
+ *       .mapArgs(({ query, maxResults }) => ({ query, maxResults, fastMode: true }))
+ *       .mapResult(r => r.results || [])
+ *     )
+ *   )
+ *   .build();
+ * ```
+ */
+// ============================================================================
+// Service Builder
+// ============================================================================
+export class ServiceBuilder {
+    _path;
+    _mapArgs;
+    _mapResult;
+    constructor(path) {
+        this._path = path;
+    }
+    /** Map input arguments to service arguments */
+    mapArgs(mapper) {
+        this._mapArgs = mapper;
+        return this;
+    }
+    /** Map service result to function return type */
+    mapResult(mapper) {
+        this._mapResult = mapper;
+        return this;
+    }
+    build() {
+        return {
+            type: "service",
+            path: this._path,
+            mapArgs: this._mapArgs,
+            mapResult: this._mapResult,
+        };
+    }
+}
+/** Create a service implementation */
+export function service(path) {
+    return new ServiceBuilder(path);
+}
+// ============================================================================
+// Primitive Builder
+// ============================================================================
+/** Create a primitive implementation */
+export function primitive(name) {
+    return { type: "primitive", name };
+}
+// ============================================================================
+// Composite Builder
+// ============================================================================
+export class CompositeBuilder {
+    _steps = [];
+    /** Call another KSA function */
+    call(fnPath, args, as) {
+        this._steps.push({ call: fnPath, args, as });
+        return this;
+    }
+    /** Return a value */
+    return(value) {
+        this._steps.push({ return: value });
+        return this;
+    }
+    build() {
+        return { type: "composite", steps: this._steps };
+    }
+}
+/** Create a composite implementation */
+export function composite() {
+    return new CompositeBuilder();
+}
+// ============================================================================
+// Function Builder
+// ============================================================================
+export class FunctionBuilder {
+    _description = "";
+    _params = {};
+    _impl;
+    _returns;
+    /** Set function description */
+    description(desc) {
+        this._description = desc;
+        return this;
+    }
+    /** Add a parameter */
+    param(name, def) {
+        this._params[name] = def;
+        return this;
+    }
+    /** Set return type info */
+    returns(typeInfo) {
+        this._returns = typeInfo;
+        return this;
+    }
+    /** Set implementation */
+    impl(implementation) {
+        if (implementation instanceof ServiceBuilder) {
+            this._impl = implementation.build();
+        }
+        else if (implementation instanceof CompositeBuilder) {
+            this._impl = implementation.build();
+        }
+        else {
+            this._impl = implementation;
+        }
+        return this;
+    }
+    build(name) {
+        if (!this._impl) {
+            throw new Error(`Function "${name}" has no implementation`);
+        }
+        return {
+            name,
+            description: this._description,
+            params: this._params,
+            impl: this._impl,
+            returns: this._returns,
+        };
+    }
+}
+/** Create a function builder */
+export function fn() {
+    return new FunctionBuilder();
+}
+// ============================================================================
+// KSA Builder
+// ============================================================================
+export class KSABuilder {
+    _name;
+    _description = "";
+    _category = "skills";
+    _group;
+    _icon;
+    _functions = [];
+    constructor(name) {
+        this._name = name;
+    }
+    /** Set KSA description */
+    description(desc) {
+        this._description = desc;
+        return this;
+    }
+    /** Set KSA category */
+    category(cat) {
+        this._category = cat;
+        return this;
+    }
+    /** Set KSA group (subcategory) */
+    group(grp) {
+        this._group = grp;
+        return this;
+    }
+    /** Set KSA icon (MDI icon name) */
+    icon(ico) {
+        this._icon = ico;
+        return this;
+    }
+    /** Add a function to the KSA */
+    fn(name, builder) {
+        this._functions.push(builder.build(name));
+        return this;
+    }
+    /** Build the KSA definition */
+    build() {
+        return {
+            name: this._name,
+            description: this._description,
+            category: this._category,
+            group: this._group,
+            icon: this._icon,
+            functions: this._functions,
+        };
+    }
+}
+/** Create a KSA builder */
+export function defineKSA(name) {
+    return new KSABuilder(name);
+}
+// ============================================================================
+// Registry Builder
+// ============================================================================
+/** Create a registry from KSA definitions */
+export function createRegistry(...ksas) {
+    const registry = new Map();
+    for (const ksa of ksas) {
+        registry.set(ksa.name, ksa);
+    }
+    return registry;
+}
+/** Get a function from a registry */
+export function getFunction(registry, ksaName, fnName) {
+    const ksa = registry.get(ksaName);
+    if (!ksa)
+        return undefined;
+    return ksa.functions.find((f) => f.name === fnName);
+}

package/dist/sdk/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lakitu KSA SDK
+ *
+ * Type-safe SDK for defining KSAs (Knowledge, Skills, and Abilities).
+ * KSAs are capability modules that AI agents can use via code execution.
+ *
+ * @example
+ * ```typescript
+ * import { defineKSA, fn, service } from '@lakitu/sdk';
+ *
+ * // Define a KSA
+ * export const myKSA = defineKSA('myKsa')
+ *   .description('My custom KSA')
+ *   .category('skills')
+ *   .fn('doSomething', fn()
+ *     .description('Does something')
+ *     .param('input', { type: 'string', required: true })
+ *     .impl(service('services.MyService.internal.action')
+ *       .mapArgs(({ input }) => ({ data: input }))
+ *     )
+ *   )
+ *   .build();
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { ParamType, ParamDef, KSACategory, KSADef, KSADefinition, FunctionDef, Implementation, ServiceImpl, PrimitiveImpl, CompositeImpl, CompositeStep, StepContext, ConfigField, ConfigFieldOption, KSAConfig, ExecutionContext, ExecutionResult, KSARegistry, } from "./types";
+export { defineKSA, KSABuilder, fn, FunctionBuilder, service, ServiceBuilder, primitive, composite, CompositeBuilder, createRegistry, getFunction, } from "./builders";
+//# sourceMappingURL=index.d.ts.map

package/dist/sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,YAAY,EAEV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,MAAM,EACN,aAAa,EACb,WAAW,EAGX,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,WAAW,EAGX,WAAW,EACX,iBAAiB,EACjB,SAAS,EAGT,gBAAgB,EAChB,eAAe,EAGf,WAAW,GACZ,MAAM,SAAS,CAAC;AAMjB,OAAO,EAEL,SAAS,EACT,UAAU,EAGV,EAAE,EACF,eAAe,EAGf,OAAO,EACP,cAAc,EACd,SAAS,EACT,SAAS,EACT,gBAAgB,EAGhB,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/sdk/index.js

@@ -0,0 +1,38 @@
+/**
+ * Lakitu KSA SDK
+ *
+ * Type-safe SDK for defining KSAs (Knowledge, Skills, and Abilities).
+ * KSAs are capability modules that AI agents can use via code execution.
+ *
+ * @example
+ * ```typescript
+ * import { defineKSA, fn, service } from '@lakitu/sdk';
+ *
+ * // Define a KSA
+ * export const myKSA = defineKSA('myKsa')
+ *   .description('My custom KSA')
+ *   .category('skills')
+ *   .fn('doSomething', fn()
+ *     .description('Does something')
+ *     .param('input', { type: 'string', required: true })
+ *     .impl(service('services.MyService.internal.action')
+ *       .mapArgs(({ input }) => ({ data: input }))
+ *     )
+ *   )
+ *   .build();
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Builders
+// ============================================================================
+export { 
+// KSA builder
+defineKSA, KSABuilder, 
+// Function builder
+fn, FunctionBuilder, 
+// Implementation builders
+service, ServiceBuilder, primitive, composite, CompositeBuilder, 
+// Registry utilities
+createRegistry, getFunction, } from "./builders";

package/dist/sdk/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * KSA SDK Type Definitions
+ *
+ * Core types for the type-safe KSA builder system.
+ */
+export type ParamType = "string" | "number" | "boolean" | "array" | "object";
+export interface ParamDef<T = unknown> {
+    type: ParamType;
+    required?: boolean;
+    default?: T;
+    description?: string;
+    enum?: string[];
+}
+export type InferParamType<P extends ParamDef> = P["type"] extends "string" ? string : P["type"] extends "number" ? number : P["type"] extends "boolean" ? boolean : P["type"] extends "array" ? unknown[] : P["type"] extends "object" ? Record<string, unknown> : unknown;
+/** Service implementation - calls cloud Convex via gateway */
+export interface ServiceImpl<TArgs = unknown, TResult = unknown> {
+    type: "service";
+    path: string;
+    mapArgs?: (args: TArgs) => Record<string, unknown>;
+    mapResult?: (result: unknown) => TResult;
+}
+/** Primitive implementation - uses local capabilities */
+export interface PrimitiveImpl {
+    type: "primitive";
+    name: string;
+}
+/** Composite step for chaining operations */
+export interface CompositeStep {
+    call?: string;
+    args?: Record<string, unknown> | ((ctx: StepContext) => Record<string, unknown>);
+    as?: string;
+    return?: unknown | ((ctx: StepContext) => unknown);
+}
+export interface StepContext {
+    vars: Record<string, unknown>;
+    args: Record<string, unknown>;
+}
+/** Composite implementation - chains multiple operations */
+export interface CompositeImpl {
+    type: "composite";
+    steps: CompositeStep[];
+}
+export type Implementation = ServiceImpl | PrimitiveImpl | CompositeImpl;
+export interface FunctionDef<TArgs = Record<string, unknown>, TResult = unknown> {
+    name: string;
+    description: string;
+    params: Record<string, ParamDef>;
+    impl: Implementation;
+    returns?: {
+        type: string;
+        description?: string;
+    };
+    _argsType?: TArgs;
+    _resultType?: TResult;
+}
+export type KSACategory = "core" | "skills" | "deliverables";
+export interface KSADef {
+    name: string;
+    description: string;
+    category: KSACategory;
+    group?: string;
+    icon?: string;
+    functions: FunctionDef[];
+}
+export interface ConfigFieldOption {
+    value: string | number | boolean;
+    label: string;
+}
+export interface ConfigField {
+    type: "string" | "number" | "boolean" | "select" | "multiselect" | "textarea" | "array";
+    label: string;
+    description?: string;
+    placeholder?: string;
+    options?: ConfigFieldOption[];
+    min?: number;
+    max?: number;
+    default: unknown;
+}
+export interface KSAConfig {
+    configSchema?: Record<string, ConfigField>;
+    defaults?: Record<string, unknown>;
+}
+export interface KSADefinition extends KSADef, KSAConfig {
+    isBuiltIn: boolean;
+    userId?: string;
+    orgId?: string;
+    version?: number;
+}
+export interface ExecutionContext {
+    threadId?: string;
+    cardId?: string;
+    workspaceId?: string;
+    config?: Record<string, unknown>;
+}
+export interface ExecutionResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    duration?: number;
+}
+export interface KSARegistry {
+    ksas: Map<string, KSADef>;
+    getKSA(name: string): KSADef | undefined;
+    getFunction(ksaName: string, fnName: string): FunctionDef | undefined;
+    listKSAs(category?: KSACategory): KSADef[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sdk/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../sdk/types.ts"],"names":[],"mappings":"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"}

package/dist/sdk/types.js

@@ -0,0 +1,6 @@
+/**
+ * KSA SDK Type Definitions
+ *
+ * Core types for the type-safe KSA builder system.
+ */
+export {};

package/ksa/README.md

@@ -0,0 +1,263 @@
+# Lakitu KSAs (Knowledge, Skills, and Abilities)
+
+> **Why "KSA"?** The terms "tools" and "skills" are overloaded in AI agent codebases.
+> Every framework (AI SDK, MCP, Claude, OpenCode) uses them differently.
+> **KSA** is a distinct term that won't be confused with other implementations.
+
+## What is a KSA?
+
+A KSA is a comprehensive capability module that combines:
+
+- **Knowledge**: Documentation and context (like MCP descriptions)
+- **Skills**: Executable TypeScript functions (like tool implementations)
+- **Abilities**: What the agent can accomplish (like Claude skills guidance)
+
+KSAs are designed for **code execution** - the agent imports and calls them directly.
+
+## Quick Reference
+
+### System KSAs (Local Operations)
+
+| KSA | Functions | Import |
+|-----|-----------|--------|
+| **file** | `read`, `write`, `edit`, `glob`, `grep`, `ls` | `from './ksa/file'` |
+| **browser** | `open`, `screenshot`, `click`, `type`, `getText`, `getHtml` | `from './ksa/browser'` |
+| **beads** | `create`, `update`, `close`, `list`, `getReady`, `get` | `from './ksa/beads'` |
+| **pdf** | `generate` | `from './ksa/pdf'` |
+
+### Research KSAs (Gateway Operations)
+
+| KSA | Functions | Import |
+|-----|-----------|--------|
+| **web** | `search`, `scrape`, `news` | `from './ksa/web'` |
+| **news** | `search`, `trending`, `breakingNews`, `monitorBrand`, `analyzeSentiment` | `from './ksa/news'` |
+| **social** | `tiktokProfile`, `instagramProfile`, `twitterProfile`, `youtubeProfile`, `*Posts` | `from './ksa/social'` |
+| **companies** | `enrichDomain`, `searchCompanies`, `findSimilar`, `getTechStack` | `from './ksa/companies'` |
+| **email** | `send`, `sendText`, `sendHtml`, `sendWithAttachment`, `sendTemplate` | `from './ksa/email'` |
+
+## Usage
+
+The agent writes TypeScript that imports from KSAs:
+
+```typescript
+import { search, scrape } from './ksa/web';
+import { write } from './ksa/file';
+import { generate } from './ksa/pdf';
+
+// Research a topic
+const results = await search('AI news 2025');
+
+// Get detailed content
+const content = await scrape(results[0].url);
+
+// Save as PDF
+await generate(content.markdown, 'ai-report', 'AI News Report');
+```
+
+## How KSAs Differ From...
+
+| Concept | What It Is | How KSA Differs |
+|---------|------------|-----------------|
+| **AI SDK tool()** | JSON schema + execute function for tool calling | KSA is plain TypeScript, no JSON schema |
+| **MCP Tool** | Server-defined capability with protocol | KSA is local files, no protocol overhead |
+| **Claude Skill** | Prompt-based capability guidance | KSA includes actual executable code |
+| **Function Call** | LLM generates JSON to call function | KSA: LLM generates code that imports & calls |
+
+## KSA File Examples
+
+### Web Research
+
+```typescript
+import { search, scrape, news } from './ksa/web';
+
+// Search the web
+const results = await search('TypeScript best practices');
+for (const r of results) {
+  console.log(`${r.title}: ${r.url}`);
+}
+
+// Get content from a URL
+const content = await scrape('https://example.com/article');
+console.log(content.markdown);
+
+// Get recent news
+const articles = await news('AI', 5);
+```
+
+### File Operations
+
+```typescript
+import { read, write, edit, glob, grep } from './ksa/file';
+
+// Read a file
+const content = await read('/home/user/workspace/README.md');
+
+// Write a file
+await write('/home/user/workspace/output.txt', 'Hello, world!');
+
+// Edit a file (find and replace)
+await edit('/home/user/workspace/config.ts', 'debug: false', 'debug: true');
+
+// Find TypeScript files
+const tsFiles = await glob('**/*.ts');
+
+// Search for patterns
+const todos = await grep('TODO:');
+```
+
+### PDF Generation
+
+```typescript
+import { generate } from './ksa/pdf';
+
+await generate(`# Quarterly Report
+
+## Summary
+Key findings from this quarter...
+
+## Metrics
+- Revenue: $1.2M
+- Growth: 15%
+`, 'quarterly-report', 'Q4 2025 Report');
+
+// Creates /home/user/artifacts/quarterly-report.pdf
+```
+
+### Task Tracking
+
+```typescript
+import { create, update, close, list, getReady } from './ksa/beads';
+
+// Create a task
+const id = await create({
+  title: 'Implement search feature',
+  type: 'feature',
+  priority: 1,
+});
+
+// Update status
+await update(id, { status: 'in_progress' });
+
+// List open tasks
+const tasks = await list({ status: 'open' });
+
+// Get ready tasks (no blockers)
+const ready = await getReady();
+
+// Close when done
+await close(id, 'Search feature implemented and tested');
+```
+
+### Browser Automation
+
+```typescript
+import { open, screenshot, click, type, getText } from './ksa/browser';
+
+// Open a page
+await open('https://example.com');
+
+// Take a screenshot
+const { path } = await screenshot('homepage');
+
+// Interact with elements
+await click('button.login');
+await type('input[name="email"]', 'user@example.com');
+
+// Get page content
+const text = await getText();
+```
+
+## Working Directories
+
+| Path | Purpose |
+|------|---------|
+| `/home/user/workspace/` | Working directory for code and files |
+| `/home/user/artifacts/` | Persistent outputs (PDFs, screenshots) |
+| `/home/user/ksa/` | KSA modules (read-only) |
+
+## Adding New KSAs
+
+### Two Types of KSAs
+
+1. **Gateway KSAs** - Call Convex services via cloud gateway (research, data, external APIs)
+2. **Local KSAs** - Operate locally in sandbox (filesystem, bash, local binaries)
+
+### Quick Start
+
+1. Copy the appropriate template from `ksa/_templates/`:
+   - `gateway-ksa.template.ts` for Gateway KSAs
+   - `local-ksa.template.ts` for Local KSAs
+
+2. Create your KSA file:
+   ```bash
+   cp ksa/_templates/gateway-ksa.template.ts ksa/myservice.ts
+   ```
+
+3. Implement your functions:
+   - For gateway KSAs: use `callGateway()` from `./_shared/gateway`
+   - For local KSAs: use `fs`, `exec`, etc.
+
+4. Add to `ksa/index.ts`:
+   ```typescript
+   // Add export
+   export * as myservice from "./myservice";
+
+   // Add to registry
+   {
+     name: "myservice",
+     description: "What this KSA does",
+     category: "research",  // or "data", "create", "system", "ai"
+     functions: ["func1", "func2"],
+     importPath: "./ksa/myservice",
+   },
+   ```
+
+### Gateway KSA Example
+
+```typescript
+import { callGateway } from "./_shared/gateway";
+
+export async function getData(query: string) {
+  return callGateway("services.MyService.internal.call", {
+    endpoint: "/v1/data",
+    params: { q: query },
+  });
+}
+```
+
+### Local KSA Example
+
+```typescript
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+
+export async function runTool(arg: string) {
+  const { stdout } = await execAsync(`my-tool ${arg}`);
+  return stdout.trim();
+}
+```
+
+### Mapping Services to KSAs
+
+When creating KSAs from existing `convex/services/`:
+
+| Service | KSA | Category |
+|---------|-----|----------|
+| Valyu | web | research |
+| APITube | news | research |
+| ScrapeCreators | social | research |
+| TheCompanies | companies | data |
+| SendGrid | email | create |
+| DataForSEO | seo | research |
+| ScrapeDo | web | research |
+| WhatCMS | cms | data |
+
+### Best Practices
+
+1. **Type-first** - Define types based on service types, simplified for agent use
+2. **JSDoc everything** - The agent learns from your documentation
+3. **Include examples** - Show real usage in @example blocks
+4. **Handle errors gracefully** - Return null/empty instead of throwing when appropriate
+5. **Keep it focused** - Each KSA should do one thing well