SDKs

Node & Python SDKs

The official SDKs wrap the v1 REST API with typed methods, automatic retries, and convenience helpers for polling and streaming runs. Both mirror the same surface.

Install#

npm install @loopllama/sdk

Initialize#

Construct a client with your API key. Read it from the environment rather than hard-coding it.

import { LoopLlama } from "@loopllama/sdk";

const ll = new LoopLlama({
  apiKey: process.env.LOOPLLAMA_API_KEY,
  // baseUrl defaults to https://api.loopllama.ai/v1
});

Workflows#

Create, list, and retrieve workflows. Pass a crew to override the default planner→writer pipeline.

// Create
const workflow = await ll.workflows.create({
  name: "Spec reviewer",
  crew: [
    { role: "researcher", systemPrompt: "Extract key claims and open questions." },
    { role: "writer", systemPrompt: "Draft a one-page summary with a Risks section." },
  ],
});

// List
const workflows = await ll.workflows.list();

// Retrieve
const wf = await ll.workflows.get(workflow.id);

Runs#

Trigger a run, then either poll for the result or stream live progress.

Trigger and poll

poll() handles the retrieve loop for you, resolving once the run reaches completed or failed.

const run = await ll.runs.create(workflow.id, {
  input: "Summarize the attached spec and propose 3 risks.",
});

const result = await ll.runs.poll(run.id);

if (result.status === "completed") {
  console.log(result.output);
} else {
  console.error(result.error);
}

Stream live progress

Iterate over events() to observe each step as it starts and finishes — useful for surfacing progress in a UI.

for await (const ev of ll.runs.events(run.id)) {
  console.log(`[step ${ev.order}] ${ev.role}: ${ev.status}`);
}

Error handling#

SDK methods raise a typed LoopLlamaError carrying the HTTP status and the API error message. See Errors for the full list of codes.

import { LoopLlama, LoopLlamaError } from "@loopllama/sdk";

try {
  await ll.runs.create(workflowId, { input: "" });
} catch (err) {
  if (err instanceof LoopLlamaError) {
    console.error(err.status, err.message); // 400 "String must contain at least 1 character(s)"
  }
}

Prefer raw HTTP?

The SDKs are a thin layer over the REST API — every method maps to an endpoint in the API reference. You can call the API directly from any language with an HTTP client.

Resources#

Node: @loopllama/sdk on npm.
Python: loopllama on PyPI.