@agenttool/sdk 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# agenttool
+
+TypeScript SDK for [agenttool.dev](https://agenttool.dev) — memory and tools for AI agents.
+
+```bash
+npm install agenttool
+```
+
+```typescript
+import { AgentTool } from "agenttool";
+
+const at = new AgentTool(); // reads AT_API_KEY from env
+
+// Memory
+await at.memory.store("learned something new");
+const results = await at.memory.search("what did I learn?");
+const mem = await at.memory.get("mem-id");
+const usage = await at.memory.usage();
+
+// Tools
+const hits = await at.tools.search("latest AI news");
+const page = await at.tools.scrape("https://example.com");
+const out = await at.tools.execute("print(1 + 1)");
+
+// Verify
+const v = await at.verify.check("The Earth is round");
+
+// Economy
+const wallet = await at.economy.createWallet({ name: "my-wallet" });
+```
+
+Set your key: `export AT_API_KEY=your-key-here`

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Main AgentTool client — the single entry point.
+ */
+import { EconomyClient } from "./economy.js";
+import { MemoryClient } from "./memory.js";
+import { ToolsClient } from "./tools.js";
+import { VerifyClient } from "./verify.js";
+/**
+ * Unified client for the agenttool.dev platform.
+ *
+ * @example
+ * ```ts
+ * import { AgentTool } from "agenttool";
+ *
+ * const at = new AgentTool();                    // reads AT_API_KEY from env
+ * await at.memory.store("just a string");        // store a memory
+ * const results = await at.memory.search("q");   // semantic search
+ * const hits = await at.tools.search("AI news"); // web search
+ * const page = await at.tools.scrape("https://x.com"); // scrape
+ * const out = await at.tools.execute("print(42)");      // sandbox
+ * const v = await at.verify.check("claim");             // verify
+ * const w = await at.economy.createWallet({ name: "w" }); // wallet
+ * ```
+ */
+export declare class AgentTool {
+    private readonly http;
+    private _memory;
+    private _tools;
+    private _verify;
+    private _economy;
+    /**
+     * Create a new AgentTool client.
+     *
+     * @param options - Optional api_key, base_url, timeout.
+     */
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+        timeout?: number;
+    });
+    /** Access the Memory API. */
+    get memory(): MemoryClient;
+    /** Access the Tools API (search, scrape, execute). */
+    get tools(): ToolsClient;
+    /** Access the Verify API. */
+    get verify(): VerifyClient;
+    /** Access the Economy/Wallet API. */
+    get economy(): EconomyClient;
+    toString(): string;
+}

package/dist/client.js

@@ -0,0 +1,76 @@
+/**
+ * Main AgentTool client — the single entry point.
+ */
+import { AgentToolError } from "./errors.js";
+import { EconomyClient } from "./economy.js";
+import { MemoryClient } from "./memory.js";
+import { ToolsClient } from "./tools.js";
+import { VerifyClient } from "./verify.js";
+/**
+ * Unified client for the agenttool.dev platform.
+ *
+ * @example
+ * ```ts
+ * import { AgentTool } from "agenttool";
+ *
+ * const at = new AgentTool();                    // reads AT_API_KEY from env
+ * await at.memory.store("just a string");        // store a memory
+ * const results = await at.memory.search("q");   // semantic search
+ * const hits = await at.tools.search("AI news"); // web search
+ * const page = await at.tools.scrape("https://x.com"); // scrape
+ * const out = await at.tools.execute("print(42)");      // sandbox
+ * const v = await at.verify.check("claim");             // verify
+ * const w = await at.economy.createWallet({ name: "w" }); // wallet
+ * ```
+ */
+export class AgentTool {
+    http;
+    _memory;
+    _tools;
+    _verify;
+    _economy;
+    /**
+     * Create a new AgentTool client.
+     *
+     * @param options - Optional api_key, base_url, timeout.
+     */
+    constructor(options) {
+        const resolvedKey = options?.apiKey ?? (typeof process !== "undefined" ? process.env.AT_API_KEY : undefined);
+        if (!resolvedKey) {
+            throw new AgentToolError("No API key provided.", {
+                hint: "Pass apiKey in options or set the AT_API_KEY environment variable.",
+            });
+        }
+        this.http = {
+            baseUrl: (options?.baseUrl ?? "https://api.agenttool.dev").replace(/\/+$/, ""),
+            headers: {
+                Authorization: `Bearer ${resolvedKey}`,
+                "Content-Type": "application/json",
+            },
+            timeout: (options?.timeout ?? 30) * 1000, // seconds → ms
+        };
+    }
+    /** Access the Memory API. */
+    get memory() {
+        this._memory ??= new MemoryClient(this.http);
+        return this._memory;
+    }
+    /** Access the Tools API (search, scrape, execute). */
+    get tools() {
+        this._tools ??= new ToolsClient(this.http);
+        return this._tools;
+    }
+    /** Access the Verify API. */
+    get verify() {
+        this._verify ??= new VerifyClient(this.http);
+        return this._verify;
+    }
+    /** Access the Economy/Wallet API. */
+    get economy() {
+        this._economy ??= new EconomyClient(this.http);
+        return this._economy;
+    }
+    toString() {
+        return `AgentTool(baseUrl=${JSON.stringify(this.http.baseUrl)})`;
+    }
+}

package/dist/economy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Economy client for the wallet/economy API.
+ */
+import type { CreateWalletOptions, Wallet } from "./types.js";
+import type { HttpConfig } from "./memory.js";
+/**
+ * Client for the economy/wallet API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * const wallet = await at.economy.createWallet({ name: "my-wallet" });
+ * console.log(wallet.id, wallet.balance);
+ * ```
+ */
+export declare class EconomyClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpConfig);
+    /**
+     * Create a new wallet.
+     *
+     * @param options - Wallet creation options (name required).
+     * @returns The created Wallet object.
+     */
+    createWallet(options: CreateWalletOptions): Promise<Wallet>;
+}

package/dist/economy.js

@@ -0,0 +1,51 @@
+/**
+ * Economy client for the wallet/economy API.
+ */
+import { AgentToolError } from "./errors.js";
+/**
+ * Client for the economy/wallet API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * const wallet = await at.economy.createWallet({ name: "my-wallet" });
+ * console.log(wallet.id, wallet.balance);
+ * ```
+ */
+export class EconomyClient {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a new wallet.
+     *
+     * @param options - Wallet creation options (name required).
+     * @returns The created Wallet object.
+     */
+    async createWallet(options) {
+        const body = { name: options.name };
+        const url = `${this.http.baseUrl}/v1/wallets`;
+        const resp = await globalThis.fetch(url, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            let detail;
+            try {
+                const json = (await resp.json());
+                detail = json.detail ?? resp.statusText;
+            }
+            catch {
+                detail = resp.statusText;
+            }
+            throw new AgentToolError(`Economy API error (${resp.status}): ${detail}`, {
+                hint: "Check your API key and request parameters.",
+            });
+        }
+        return (await resp.json());
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Exceptions for the AgentTool SDK.
+ */
+/**
+ * Base error for all AgentTool SDK operations.
+ *
+ * @example
+ * ```ts
+ * throw new AgentToolError("something broke", { hint: "try again" });
+ * ```
+ */
+export declare class AgentToolError extends Error {
+    /** Human-readable error description. */
+    readonly message: string;
+    /** Actionable suggestion for fixing the error. */
+    readonly hint: string | undefined;
+    constructor(message: string, options?: {
+        hint?: string;
+    });
+    toString(): string;
+}

package/dist/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Exceptions for the AgentTool SDK.
+ */
+/**
+ * Base error for all AgentTool SDK operations.
+ *
+ * @example
+ * ```ts
+ * throw new AgentToolError("something broke", { hint: "try again" });
+ * ```
+ */
+export class AgentToolError extends Error {
+    /** Human-readable error description. */
+    message;
+    /** Actionable suggestion for fixing the error. */
+    hint;
+    constructor(message, options) {
+        super(message);
+        this.name = "AgentToolError";
+        this.message = message;
+        this.hint = options?.hint;
+    }
+    toString() {
+        if (this.hint) {
+            return `${this.message} (hint: ${this.hint})`;
+        }
+        return this.message;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AgentTool SDK — memory and tools for AI agents.
+ *
+ * @example
+ * ```ts
+ * import { AgentTool } from "agenttool";
+ *
+ * const at = new AgentTool();
+ * await at.memory.store("just a string");
+ * ```
+ */
+export { AgentTool } from "./client.js";
+export { AgentToolError } from "./errors.js";
+export type { CreateWalletOptions, ExecuteResult, Memory, ScrapeResult, SearchMemoryOptions, SearchResponse, SearchResult, StoreOptions, UsageStats, VerifyResult, Wallet, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * AgentTool SDK — memory and tools for AI agents.
+ *
+ * @example
+ * ```ts
+ * import { AgentTool } from "agenttool";
+ *
+ * const at = new AgentTool();
+ * await at.memory.store("just a string");
+ * ```
+ */
+export { AgentTool } from "./client.js";
+export { AgentToolError } from "./errors.js";

package/dist/memory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Memory client for the agent-memory API.
+ */
+import type { Memory, SearchMemoryOptions, StoreOptions, UsageStats } from "./types.js";
+/** @internal Shared HTTP config passed from the main client. */
+export interface HttpConfig {
+    baseUrl: string;
+    headers: Record<string, string>;
+    timeout: number;
+}
+/**
+ * Client for the agent-memory API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * at.memory.store("just a string");
+ * const results = at.memory.search("what did I learn?");
+ * ```
+ */
+export declare class MemoryClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpConfig);
+    /**
+     * Store a memory. Only `content` is required.
+     *
+     * @param content - The memory content string.
+     * @param options - Optional type, agent_id, key, metadata, importance.
+     * @returns The created Memory object.
+     */
+    store(content: string, options?: StoreOptions): Promise<Memory>;
+    /**
+     * Semantic search over stored memories.
+     *
+     * @param query - Natural-language search query.
+     * @param options - Optional limit, type, agent_id.
+     * @returns List of matching Memory objects.
+     */
+    search(query: string, options?: SearchMemoryOptions): Promise<Memory[]>;
+    /**
+     * Retrieve a single memory by ID.
+     *
+     * @param memoryId - The memory's unique identifier.
+     * @returns The Memory object.
+     */
+    get(memoryId: string): Promise<Memory>;
+    /**
+     * Get usage statistics.
+     *
+     * @returns UsageStats with current counters.
+     */
+    usage(): Promise<UsageStats>;
+    private post;
+    private fetch;
+}

package/dist/memory.js

@@ -0,0 +1,112 @@
+/**
+ * Memory client for the agent-memory API.
+ */
+import { AgentToolError } from "./errors.js";
+/**
+ * Client for the agent-memory API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * at.memory.store("just a string");
+ * const results = at.memory.search("what did I learn?");
+ * ```
+ */
+export class MemoryClient {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Store a memory. Only `content` is required.
+     *
+     * @param content - The memory content string.
+     * @param options - Optional type, agent_id, key, metadata, importance.
+     * @returns The created Memory object.
+     */
+    async store(content, options) {
+        const body = {
+            content,
+            type: options?.type ?? "semantic",
+            importance: options?.importance ?? 0.5,
+        };
+        if (options?.agent_id !== undefined)
+            body.agent_id = options.agent_id;
+        if (options?.key !== undefined)
+            body.key = options.key;
+        if (options?.metadata !== undefined)
+            body.metadata = options.metadata;
+        const resp = await this.post("/v1/memories", body);
+        return resp;
+    }
+    /**
+     * Semantic search over stored memories.
+     *
+     * @param query - Natural-language search query.
+     * @param options - Optional limit, type, agent_id.
+     * @returns List of matching Memory objects.
+     */
+    async search(query, options) {
+        const body = {
+            query,
+            limit: options?.limit ?? 10,
+        };
+        if (options?.type !== undefined)
+            body.type = options.type;
+        if (options?.agent_id !== undefined)
+            body.agent_id = options.agent_id;
+        const data = await this.post("/v1/memories/search", body);
+        const results = Array.isArray(data) ? data : data.results ?? [];
+        return results;
+    }
+    /**
+     * Retrieve a single memory by ID.
+     *
+     * @param memoryId - The memory's unique identifier.
+     * @returns The Memory object.
+     */
+    async get(memoryId) {
+        const resp = await this.fetch("GET", `/v1/memories/${memoryId}`);
+        return resp;
+    }
+    /**
+     * Get usage statistics.
+     *
+     * @returns UsageStats with current counters.
+     */
+    async usage() {
+        const resp = await this.fetch("GET", "/v1/usage");
+        return resp;
+    }
+    // --- internal ---
+    async post(path, body) {
+        return this.fetch("POST", path, body);
+    }
+    async fetch(method, path, body) {
+        const url = `${this.http.baseUrl}${path}`;
+        const init = {
+            method,
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        const resp = await globalThis.fetch(url, init);
+        if (resp.status >= 400) {
+            let detail;
+            try {
+                const json = (await resp.json());
+                detail = json.detail ?? resp.statusText;
+            }
+            catch {
+                detail = resp.statusText;
+            }
+            throw new AgentToolError(`Memory API error (${resp.status}): ${detail}`, {
+                hint: "Check your API key and request parameters.",
+            });
+        }
+        return resp.json();
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tools client for the agent-tools API.
+ */
+import type { ExecuteResult, ScrapeResult, SearchResponse } from "./types.js";
+import type { HttpConfig } from "./memory.js";
+/**
+ * Client for the agent-tools API (search, scrape, execute).
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * const results = at.tools.search("latest AI news");
+ * const page = at.tools.scrape("https://example.com");
+ * const out = at.tools.execute("print(42)");
+ * ```
+ */
+export declare class ToolsClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpConfig);
+    /**
+     * Web search.
+     *
+     * @param query - Search query string.
+     * @param options - Optional num_results.
+     * @returns SearchResponse with results, cached flag, and duration.
+     */
+    search(query: string, options?: {
+        num_results?: number;
+    }): Promise<SearchResponse>;
+    /**
+     * Scrape a URL and return its content.
+     *
+     * @param url - The URL to scrape.
+     * @returns ScrapeResult with the page content.
+     */
+    scrape(url: string): Promise<ScrapeResult>;
+    /**
+     * Execute code in a sandbox.
+     *
+     * @param code - Source code to execute.
+     * @param options - Optional language (default: "python").
+     * @returns ExecuteResult with stdout, stderr, exit_code, duration_ms.
+     */
+    execute(code: string, options?: {
+        language?: string;
+    }): Promise<ExecuteResult>;
+    private post;
+}

package/dist/tools.js

@@ -0,0 +1,94 @@
+/**
+ * Tools client for the agent-tools API.
+ */
+import { AgentToolError } from "./errors.js";
+/**
+ * Client for the agent-tools API (search, scrape, execute).
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * const results = at.tools.search("latest AI news");
+ * const page = at.tools.scrape("https://example.com");
+ * const out = at.tools.execute("print(42)");
+ * ```
+ */
+export class ToolsClient {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Web search.
+     *
+     * @param query - Search query string.
+     * @param options - Optional num_results.
+     * @returns SearchResponse with results, cached flag, and duration.
+     */
+    async search(query, options) {
+        const body = {
+            query,
+            num_results: options?.num_results ?? 5,
+        };
+        const data = (await this.post("/v1/search", body));
+        // Normalize: API may return results at top level or nested
+        const results = Array.isArray(data)
+            ? data
+            : (data.results ?? []);
+        return {
+            results: results,
+            cached: data.cached ?? false,
+            duration_ms: data.duration_ms ?? 0,
+        };
+    }
+    /**
+     * Scrape a URL and return its content.
+     *
+     * @param url - The URL to scrape.
+     * @returns ScrapeResult with the page content.
+     */
+    async scrape(url) {
+        const data = await this.post("/v1/scrape", { url });
+        return data;
+    }
+    /**
+     * Execute code in a sandbox.
+     *
+     * @param code - Source code to execute.
+     * @param options - Optional language (default: "python").
+     * @returns ExecuteResult with stdout, stderr, exit_code, duration_ms.
+     */
+    async execute(code, options) {
+        const body = {
+            code,
+            language: options?.language ?? "python",
+        };
+        const data = await this.post("/v1/execute", body);
+        return data;
+    }
+    // --- internal ---
+    async post(path, body) {
+        const url = `${this.http.baseUrl}${path}`;
+        const resp = await globalThis.fetch(url, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            let detail;
+            try {
+                const json = (await resp.json());
+                detail = json.detail ?? resp.statusText;
+            }
+            catch {
+                detail = resp.statusText;
+            }
+            throw new AgentToolError(`Tools API error (${resp.status}): ${detail}`, {
+                hint: "Check your API key and request parameters.",
+            });
+        }
+        return resp.json();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Data types for the AgentTool SDK.
+ */
+/** A stored memory. */
+export interface Memory {
+    id: string;
+    content: string;
+    type: string;
+    agent_id?: string;
+    key?: string;
+    metadata: Record<string, unknown>;
+    importance: number;
+    score?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/** Options for storing a memory. */
+export interface StoreOptions {
+    type?: string;
+    agent_id?: string;
+    key?: string;
+    metadata?: Record<string, unknown>;
+    importance?: number;
+}
+/** Options for searching memories. */
+export interface SearchMemoryOptions {
+    limit?: number;
+    type?: string;
+    agent_id?: string;
+}
+/** API usage statistics. */
+export interface UsageStats {
+    writes: number;
+    reads: number;
+    searches: number;
+    total_memories: number;
+    plan: string;
+}
+/** A web search result. */
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    date?: string;
+}
+/** Response from the search endpoint. */
+export interface SearchResponse {
+    results: SearchResult[];
+    cached: boolean;
+    duration_ms: number;
+}
+/** Result of scraping a URL. */
+export interface ScrapeResult {
+    url: string;
+    content: string;
+    status_code: number;
+    [key: string]: unknown;
+}
+/** Result of sandboxed code execution. */
+export interface ExecuteResult {
+    stdout: string;
+    stderr: string;
+    exit_code: number;
+    duration_ms: number;
+}
+/** Result of a verification request. */
+export interface VerifyResult {
+    verdict: string;
+    confidence: number;
+    sources: string[];
+    evidence: string;
+    caveats: string[];
+}
+/** A wallet object. */
+export interface Wallet {
+    id: string;
+    name: string;
+    balance: number;
+    api_key: string;
+}
+/** Options for creating a wallet. */
+export interface CreateWalletOptions {
+    name: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Data types for the AgentTool SDK.
+ */
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Verify client for the verification API.
+ */
+import type { VerifyResult } from "./types.js";
+import type { HttpConfig } from "./memory.js";
+/**
+ * Client for the verify API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * const result = await at.verify.check("The Earth is round");
+ * console.log(result.verdict, result.confidence);
+ * ```
+ */
+export declare class VerifyClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpConfig);
+    /**
+     * Verify a claim.
+     *
+     * @param claim - The statement to verify.
+     * @param options - Optional sources array.
+     * @returns VerifyResult with verdict, confidence, sources, evidence, caveats.
+     */
+    check(claim: string, options?: {
+        sources?: string[];
+    }): Promise<VerifyResult>;
+}

package/dist/verify.js

@@ -0,0 +1,54 @@
+/**
+ * Verify client for the verification API.
+ */
+import { AgentToolError } from "./errors.js";
+/**
+ * Client for the verify API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ * const result = await at.verify.check("The Earth is round");
+ * console.log(result.verdict, result.confidence);
+ * ```
+ */
+export class VerifyClient {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Verify a claim.
+     *
+     * @param claim - The statement to verify.
+     * @param options - Optional sources array.
+     * @returns VerifyResult with verdict, confidence, sources, evidence, caveats.
+     */
+    async check(claim, options) {
+        const body = { claim };
+        if (options?.sources !== undefined)
+            body.sources = options.sources;
+        const url = `${this.http.baseUrl}/v1/verify`;
+        const resp = await globalThis.fetch(url, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            let detail;
+            try {
+                const json = (await resp.json());
+                detail = json.detail ?? resp.statusText;
+            }
+            catch {
+                detail = resp.statusText;
+            }
+            throw new AgentToolError(`Verify API error (${resp.status}): ${detail}`, {
+                hint: "Check your API key and request parameters.",
+            });
+        }
+        return (await resp.json());
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@agenttool/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for agenttool.dev — memory and tools for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "typescript": "^5.7.0"
+  }
+}