@betterlu/agentlu 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# @betterlu/agentlu
+
+Client for the [agentlu](https://github.com/betterlu/agentlu) service API (`/v1`).
+
+You can also skip this package and use the OpenAI SDK:
+
+```ts
+import OpenAI from "openai";
+const client = new OpenAI({ baseURL: "http://localhost:8912/v1", apiKey });
+const r = await client.responses.create({ model: "fast", input: "hi" });
+```
+
+This client adds get-or-create registration, typed `run({ schema })`, and auto-retry on `409 thread_busy`.
+
+## Install
+
+```bash
+npm install @betterlu/agentlu
+```
+
+## Usage
+
+```ts
+import { AgentLu } from "@betterlu/agentlu";
+
+const alu = new AgentLu();
+await alu.register("my-app");
+
+const { data, response } = await alu.run({
+  agent: "fast",
+  input: "hi",
+});
+console.log(response.output_text);
+```
+
+Env: `AGENTLU_URL` (default `http://localhost:8912/v1`), `AGENTLU_API_KEY`.

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @betterlu/agentlu - client for the agentlu service API.
+ *
+ * You can also skip this package entirely:
+ *
+ *   new OpenAI({ baseURL: "http://localhost:8912/v1", apiKey })
+ *
+ * This client exists for the ergonomic bits OpenAI's SDK does not know about:
+ * get-or-create registration, typed `run({ schema })`, and auto-retry on
+ * `409 thread_busy`.
+ */
+export declare const DEFAULT_BASE_URL = "http://localhost:8912/v1";
+export declare class AgentLuError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(status: number, code: string, message: string, retryable: boolean);
+}
+export interface AgentLuOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+export interface RunOptions {
+    agent?: string;
+    model?: string;
+    input: string;
+    instructions?: string;
+    tools?: Array<string | {
+        type: string;
+        allowed_tools?: string[];
+    }>;
+    conversation?: string;
+    store?: boolean;
+    person?: string | null;
+    timeout_ms?: number;
+    include?: string[];
+    /** JSON Schema. When set, `data` on the result is the validated object. */
+    schema?: Record<string, unknown>;
+    schemaName?: string;
+}
+export interface ResponseObject {
+    id: string;
+    status: string;
+    output_text: string;
+    output_parsed?: unknown;
+    conversation?: {
+        id: string;
+    } | null;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    } | null;
+    agentlu?: {
+        session_url?: string | null;
+    };
+    [k: string]: unknown;
+}
+export declare class AgentLu {
+    readonly baseUrl: string;
+    apiKey: string | undefined;
+    private readonly fetchImpl;
+    constructor(opts?: AgentLuOptions);
+    /** Get-or-create a client by name. Caches the returned key on this instance. */
+    register(name: string, opts?: {
+        person?: string | null;
+        instructions?: string | null;
+    }): Promise<ResponseObject & {
+        api_key?: string;
+        name: string;
+    }>;
+    me(): Promise<unknown>;
+    /**
+     * One-shot helper. When `schema` is given, returns the validated object as
+     * `data` and throws `AgentLuError("schema_validation_failed")` if the server
+     * could not produce matching JSON.
+     */
+    run<T = unknown>(opts: RunOptions): Promise<{
+        data?: T;
+        response: ResponseObject;
+    }>;
+    readonly responses: {
+        create: (body: Record<string, unknown>) => Promise<ResponseObject>;
+        retrieve: (id: string) => Promise<ResponseObject>;
+        cancel: (id: string) => Promise<ResponseObject>;
+        list: (query?: {
+            limit?: number;
+            status?: string;
+        }) => Promise<{
+            object: string;
+            data: ResponseObject[];
+        }>;
+        stream: (body: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>>;
+    };
+    readonly threads: {
+        create: (body?: Record<string, unknown>) => Promise<unknown>;
+        retrieve: (id: string) => Promise<unknown>;
+        list: () => Promise<unknown>;
+        delete: (id: string) => Promise<unknown>;
+        messages: (id: string) => Promise<unknown>;
+    };
+    agents(): Promise<unknown>;
+    models(): Promise<unknown>;
+    tools(): Promise<unknown>;
+    health(): Promise<unknown>;
+    private request;
+    private raw;
+}

package/dist/index.js

@@ -0,0 +1,206 @@
+/**
+ * @betterlu/agentlu - client for the agentlu service API.
+ *
+ * You can also skip this package entirely:
+ *
+ *   new OpenAI({ baseURL: "http://localhost:8912/v1", apiKey })
+ *
+ * This client exists for the ergonomic bits OpenAI's SDK does not know about:
+ * get-or-create registration, typed `run({ schema })`, and auto-retry on
+ * `409 thread_busy`.
+ */
+export const DEFAULT_BASE_URL = "http://localhost:8912/v1";
+export class AgentLuError extends Error {
+    status;
+    code;
+    retryable;
+    constructor(status, code, message, retryable) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "AgentLuError";
+    }
+}
+function env(name) {
+    return typeof process !== "undefined" ? process.env[name] : undefined;
+}
+export class AgentLu {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? env("AGENTLU_URL") ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.apiKey = opts.apiKey ?? env("AGENTLU_API_KEY");
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** Get-or-create a client by name. Caches the returned key on this instance. */
+    async register(name, opts) {
+        const res = await this.request("POST", "/clients", { name, ...opts }, { auth: false });
+        if (res.api_key)
+            this.apiKey = res.api_key;
+        return res;
+    }
+    async me() {
+        return this.request("GET", "/me");
+    }
+    /**
+     * One-shot helper. When `schema` is given, returns the validated object as
+     * `data` and throws `AgentLuError("schema_validation_failed")` if the server
+     * could not produce matching JSON.
+     */
+    async run(opts) {
+        const body = {
+            input: opts.input,
+            agent: opts.agent,
+            model: opts.model,
+            instructions: opts.instructions,
+            tools: opts.tools,
+            conversation: opts.conversation,
+            store: opts.store,
+            person: opts.person,
+            timeout_ms: opts.timeout_ms,
+            include: opts.include,
+        };
+        if (opts.schema) {
+            body.text = {
+                format: {
+                    type: "json_schema",
+                    name: opts.schemaName ?? "Result",
+                    schema: opts.schema,
+                    strict: true,
+                },
+            };
+        }
+        const response = await this.responses.create(body);
+        if (response.status === "failed" && response.error) {
+            throw new AgentLuError(200, response.error.code, response.error.message, response.error.retryable);
+        }
+        return { data: response.output_parsed, response };
+    }
+    responses = {
+        create: (body) => this.request("POST", "/responses", body),
+        retrieve: (id) => this.request("GET", `/responses/${encodeURIComponent(id)}`),
+        cancel: (id) => this.request("POST", `/responses/${encodeURIComponent(id)}/cancel`),
+        list: (query) => {
+            const q = new URLSearchParams();
+            if (query?.limit)
+                q.set("limit", String(query.limit));
+            if (query?.status)
+                q.set("status", query.status);
+            const qs = q.toString();
+            return this.request("GET", `/responses${qs ? `?${qs}` : ""}`);
+        },
+        stream: async function* stream(body) {
+            const res = await this.raw("POST", "/responses", { ...body, stream: true });
+            if (!res.body)
+                throw new AgentLuError(0, "internal_error", "empty stream body", true);
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buf = "";
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buf += decoder.decode(value, { stream: true });
+                    const lines = buf.split("\n");
+                    buf = lines.pop() ?? "";
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (!trimmed.startsWith("data: "))
+                            continue;
+                        const payload = trimmed.slice(6);
+                        if (payload === "[DONE]")
+                            return;
+                        try {
+                            yield JSON.parse(payload);
+                        }
+                        catch {
+                            /* ignore malformed chunks */
+                        }
+                    }
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }.bind(this),
+    };
+    threads = {
+        create: (body = {}) => this.request("POST", "/threads", body),
+        retrieve: (id) => this.request("GET", `/threads/${encodeURIComponent(id)}`),
+        list: () => this.request("GET", "/threads"),
+        delete: (id) => this.request("DELETE", `/threads/${encodeURIComponent(id)}`),
+        messages: (id) => this.request("GET", `/threads/${encodeURIComponent(id)}/messages`),
+    };
+    async agents() {
+        return this.request("GET", "/agents", undefined, { auth: false });
+    }
+    async models() {
+        return this.request("GET", "/models", undefined, { auth: false });
+    }
+    async tools() {
+        return this.request("GET", "/tools", undefined, { auth: false });
+    }
+    async health() {
+        return this.request("GET", "/health", undefined, { auth: false });
+    }
+    async request(method, path, body, opts) {
+        // `409 thread_busy` is a correctness bound, not a rate limit. Retrying with
+        // a short backoff is almost always the right thing, so the SDK does it.
+        let last;
+        for (let attempt = 0; attempt < 4; attempt++) {
+            try {
+                const res = await this.raw(method, path, body, opts);
+                if (res.status === 204)
+                    return undefined;
+                const json = (await res.json());
+                return json;
+            }
+            catch (e) {
+                if (e instanceof AgentLuError && e.code === "thread_busy" && attempt < 3) {
+                    last = e;
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                throw e;
+            }
+        }
+        throw last ?? new AgentLuError(409, "thread_busy", "thread busy", true);
+    }
+    async raw(method, path, body, opts) {
+        const headers = {};
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (opts?.auth !== false && this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            let code = `http_${res.status}`;
+            let message = `HTTP ${res.status}`;
+            let retryable = res.status >= 500 || res.status === 409;
+            try {
+                const err = (await res.json());
+                if (err.error?.code)
+                    code = err.error.code;
+                if (err.error?.message)
+                    message = err.error.message;
+                if (typeof err.error?.retryable === "boolean")
+                    retryable = err.error.retryable;
+            }
+            catch {
+                /* keep defaults */
+            }
+            throw new AgentLuError(res.status, code, message, retryable);
+        }
+        return res;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@betterlu/agentlu",
+  "version": "1.0.0",
+  "description": "Client for the agentlu service API (/v1). Or just use the openai SDK pointed at http://localhost:8912/v1.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["agentlu", "openai", "responses", "llm", "agent"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/betterlu/agentlu.git",
+    "directory": "packages/sdk"
+  },
+  "license": "UNLICENSED"
+}