> ## Documentation Index
> Fetch the complete documentation index at: https://mulerouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Library usage

> Use @mulerouter/core to embed MuleRouter calls directly in a TypeScript program

The CLI is a thin layer over [`@mulerouter/core`](https://www.npmjs.com/package/@mulerouter/core).
The same package is published independently — install it when you want to call
MuleRouter from a Node.js, Bun, or TypeScript application without shelling out.

```bash theme={null}
npm install @mulerouter/core
```

The package has zero runtime dependencies and ships with full TypeScript
types.

## Minimal example

```ts theme={null}
import {
  APIClient,
  createAndPollTask,
  loadConfig,
  processImageParams,
  registry,
} from "@mulerouter/core";

const config = loadConfig({ site: "mulerouter" });
const client = new APIClient(config);

const endpoint = registry.get("alibaba/wan2.6-t2i", "generation");
if (!endpoint) throw new Error("endpoint not registered");

const body = processImageParams({
  prompt: "A blooming cherry tree at dusk",
  size: "1280*1280",
});

const result = await createAndPollTask({
  client,
  endpointPath: endpoint.apiPath,
  requestBody: body,
  resultKey: endpoint.resultKey,
});

if (result.status === "succeeded") {
  console.log(result.results); // string[] of asset URLs
} else {
  console.error(result.status, result.error);
}
```

## Public API surface

```ts theme={null}
import {
  // Config
  loadConfig,
  getConfigHelp,
  loadEnvFile,

  // HTTP client
  APIClient,

  // Model registry
  registry,
  ModelRegistry,
  registerEndpoint,

  // Tasks
  createAndPollTask,
  pollTask,
  parseTaskResponse,
  isSuccessStatus,
  isTerminalStatus,

  // Image helpers
  processImageParams,
  isImageParam,
  validateImagePath,

  // Utilities
  toCliFlag,
  VERSION,
} from "@mulerouter/core";

import type {
  Site,           // "mulerouter" | "mulerun"
  InputType,      // "text" | "image" | "video" | "audio"
  OutputType,     // "image" | "video" | "text" | "audio"
  ModelParameter,
  ModelEndpoint,
  Config,
  APIResponse,
  TaskStatus,
  TaskResult,
} from "@mulerouter/core";
```

## Key functions

### `loadConfig(options?)`

Resolves `apiKey`, `baseUrl`, `site`, plus default timeout (`120_000` ms) and
retry budget (`3`). Same priority chain as the CLI:
arguments → environment variables → `.env`.

### `new APIClient(config)`

A small `fetch`-based client with:

* Bearer-token auth via the configured API key
* Automatic JSON encoding
* Exponential-backoff retry on transient failures (5xx, network errors)
* `post(path, body)` and `get(path)` returning `APIResponse`

### `createAndPollTask({...})`

Submits a `POST` to `endpointPath` and polls every `interval` ms (default
20 000) until the task reaches a terminal state or `maxWait` (default
900 000 ms) elapses. Set `verbose: true` to log per-poll status lines to
stderr.

### `pollTask({...})`

Same poller, against an already-created task identified by `taskPath` and
`taskId`.

### `processImageParams(body)`

Walks a request body, finds any image-shaped parameter, and converts local
file paths to base64 data URIs. Idempotent for URLs and `data:` URIs.

### `registry`

Singleton catalog of every endpoint that has been imported. The registry is
populated as a side effect of importing `@mulerouter/core` (which loads
`models/index.ts` and every provider module). Useful methods:

| Method                               | Returns                                  |
| ------------------------------------ | ---------------------------------------- |
| `registry.get(modelId, action)`      | A single `ModelEndpoint` or `undefined`  |
| `registry.findByModelId(modelId)`    | Every action registered under that model |
| `registry.listAll()`                 | Everything                               |
| `registry.listForSite("mulerun")`    | Filtered by site                         |
| `registry.listByProvider("alibaba")` | Filtered by provider                     |
| `registry.listByOutputType("video")` | Filtered by output type                  |
| `registry.listByTag("SOTA")`         | Filtered by tag                          |
| `registry.getProviders()`            | Sorted unique provider names             |

## Status helpers

```ts theme={null}
import { isSuccessStatus, isTerminalStatus } from "@mulerouter/core";

isSuccessStatus(result.status);   // succeeded | completed
isTerminalStatus(result.status);  // success states + failed
```

## Naming convention

In code, model parameter names use `snake_case` (matching the wire format).
The CLI converts to `kebab-case` for flags via `toCliFlag(name)` — useful if
you are building tooling that mirrors the CLI's UX.

```ts theme={null}
import { toCliFlag } from "@mulerouter/core";

toCliFlag("negative_prompt");  // "negative-prompt"
toCliFlag("aspect_ratio");     // "aspect-ratio"
```

## Versioning

The CLI and core packages are released in lockstep. The version string is
exported as `VERSION` and is what the CLI prints for `mulerouter --version`.