@betterlu/agentlu 1.7.1 → 1.8.0

package/README.md

@@ -10,7 +10,7 @@ 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 `runJson` / `runText`, use-case catalogs, background `wait`, client-side `timeoutMs`, and auto-retry on `409 thread_busy`.
+This client adds get-or-create registration, typed `runJson` / `runText`, use-case catalogs, the two `/v1` tiers (`llm.*` / `agent.*`), error classification (`err.kind`, `isUnavailable`), background `wait`, bulk uploads, client-side `timeoutMs`, and auto-retry on `409 thread_busy`.
 
 ## Install
 
@@ -33,6 +33,76 @@ const { data, response } = await alu.run({
 console.log(response.output_text);
 ```
 
+## Two tiers
+
+`/v1` has two documented tiers, and 1.8 exposes both as namespaces. Pick one and
+stay there (see the `agentlu-api` skill for the full contract):
+
+| | `alu.llm.*` (direct) | `alu.agent.*` (agent) |
+|---|---|---|
+| What runs | one profile-free provider call | profile + tool families + agent loop |
+| Session | none (`store: false`) | a real thread you can continue |
+| Tools | none | the closed family set (+ MCP for `api`) |
+| Use it for | extraction, classification, short answers | research, phone/browser work, context |
+
+```ts
+// Direct tier.
+const { text } = await alu.llm.text("Name three colours.");
+const { data } = await alu.llm.json<{ items: string[] }>(
+  { type: "object", properties: { items: { type: "array", items: { type: "string" } } }, required: ["items"] },
+  "two milk, one bread",
+);
+for await (const event of alu.llm.stream("Count to three")) console.log(event.type);
+
+// Agent tier (default agent `api`; pin fast/research/… or "<app>/<name>").
+const run = await alu.agent.run({ agent: "fast", input: "what changed in node 24?" });
+const done = await alu.agent.background({ input: "research this deeply" }, { timeoutMs: 600_000 });
+```
+
+`alu.run` / `runJson` / `runText` / `stream` remain the agent-tier aliases they
+always were - nothing breaks by upgrading.
+
+## Errors: `kind` and fail-open
+
+Every `AgentLuError` carries a coarse `kind`, and `isUnavailable(err)` is the
+predicate for "the service could not answer right now" (offline, 5xx,
+saturation, timeout, rate limit):
+
+```ts
+import { isUnavailable } from "@betterlu/agentlu";
+
+try {
+  await alu.llm.text(input);
+} catch (err) {
+  if (isUnavailable(err)) return fallbackAnswer();   // degrade gracefully
+  throw err;
+}
+```
+
+| `err.kind` | Meaning |
+|---|---|
+| `unavailable` | offline / upstream 5xx / saturated - retry or degrade |
+| `timeout` | the run or request hit its deadline |
+| `rate_limited` | HTTP 429 or a retryable 409 (`thread_busy`) - back off (the SDK already retries with jitter) |
+| `invalid_request` | the caller must fix the request (4xx) |
+| `schema` | structured output failed or never validated |
+| `incomplete` | the run finished without a complete answer |
+| `internal` | anything else, including a cancelled run and the `systemone_unconfigured` config boundary (never retried, so it surfaces instead of degrading) |
+
+## Bulk uploads and background runs
+
+```ts
+const files = await alu.uploadMany(photos, { concurrency: 4 });
+await alu.agent.run({ input: "catalog these", fileIds: files.map((f) => f.id) });
+
+const finished = await alu.useCase("myapp-long").runBackground({ input }, { intervalMs: 2_000 });
+```
+
+`uploadMany` preserves input order and bounds parallelism (default 3).
+`runBackground` = enqueue (`background: true`) + `responses.wait`; it resolves
+with the terminal Response row (check `status`; a failed run is not an
+exception there).
+
 ## JSON results
 
 `runJson` returns only a completed response with the server-provided `output_parsed` value. It preserves JSON `null`, `false`, `0`, and empty arrays. A missing parsed value, failed response, incomplete response, cancellation, or queued response throws an SDK error instead of parsing `output_text`. `background: true` is rejected by this helper; use raw `run` when polling is intended.
@@ -75,7 +145,55 @@ const { data } = await mealEnricher.runJson<{ meal: string }>({ input: "two eggs
 
 Set a field on `run` or `runJson` to override its registered default. `strict: false` still requires parsed JSON but does not require that value to match the schema.
 
-Do **not** put `maxOutputTokens` on client defaults — the server ignores it. Pass `max_output_tokens` (or `maxOutputTokens`) on the run.
+`priority` declares the use-case tier and opts the client into its defaults
+(`instant` = fast models/45s/2k/1 attempt, `standard` = 3 min/2 attempts, `deep`
+= strongest/10 min/8k/3 attempts). A client with no declared priority keeps the
+pre-tier envelope, so adding it is always a deliberate change:
+
+```ts
+const parse = alu.useCase("myapp-parse", {
+  app: "myapp",
+  priority: "instant",
+  use_case_profile: { outputKind: "json_schema" },
+  defaults: { agent: "api", store: false, tools: [] },
+});
+```
+
+`maxOutputTokens` on client defaults is honored for defaults written from this
+release on: a value stored earlier stays inert until the client re-declares its
+defaults (or the console edits them). Prefer a request-level `maxOutputTokens`
+when you only need it for one call.
+
+### App-owned agents
+
+An app can declare its own agents at registration and call them as
+`agent: "<app>/<name>"` from any client of the same app. The declaration's
+instructions become the agent's profile body (caller `instructions` are
+appended below them), and `tools` limits the families it may use.
+
+`app` is slugified to the address grammar (`NestLu` → `nestlu`, `my app` →
+`my-app`), and the server enforces the naming convention that keeps apps from
+overwriting each other: the declaring client's name must own the app (`nestlu`
+or `nestlu-...`). Any other declaration - or an address that can never parse -
+is refused with a `warnings` entry on the registration response; the
+registration itself still succeeds and the stored agents stay untouched. An
+explicit request `agent`/`model` always wins over a client-default app agent:
+
+```ts
+const chat = alu.useCase("nestlu-chat", {
+  app: "nestlu",
+  agents: [
+    {
+      name: "chat",
+      instructions: "You are the NestLu baby shopping-list assistant …", // the old pi/agents/nestlu.md body
+      tools: ["hublu", "web_search", "fetch_content"],
+      model: "MiniMax-M3",
+      temperature: 0.3,
+    },
+  ],
+});
+await chat.run({ agent: "nestlu/chat", input: "还缺什么？" });
+```
 
 Several use-cases sharing one client: