# Install

Node 22 or newer.

```sh
npm i @praecise/harness
```

Or start a new app from scratch:

```sh
npx @praecise/harness init my-app
cd my-app
npm install
```

Put one key in `.env` and you are running:

```sh
PRAECISE_API_KEY=...
```

That runs the app on Praecise Cloud, which decides what each rung of the ladder
runs on. There is nothing to choose and no model id to keep current.
`PRAECISE_GATEWAY_URL` sends that key to another address, where the cloud is
reached somewhere other than its public one.

To run on your own endpoints instead, describe them in `praecise.config.ts` and
put their keys in `.env`:

```ts
export default defineConfig({
  models: {
    house: {
      url: "https://models.internal",
      credential: "HOUSE_KEY",
      speaks: "chat",
      fast: "…", balanced: "…", best: "…",
      room: 200_000,
    },
  },
});
```

The first endpoint whose credential is present is the one that runs, and a
declared endpoint always beats the cloud. Naming a single model is fine — every
rung then runs on it. The framework knows no endpoint but Praecise Cloud by
name: a base URL and a model id belong to the app that chose them.

`room` is how much context that endpoint has, in tokens. Everything carried into
a request — the instructions, what was recalled, the conversation so far, and
what a tool handed back — is a share of it, so an endpoint with room to spare
uses it. Leave it out and a modest figure is assumed, which costs you nothing
except some of the conversation you could have carried.

An endpoint with needs of its own says so in the same three lines rather than in
a patched copy of the framework:

```ts
house: {
  url: "https://models.internal",
  credential: "HOUSE_KEY",
  credentialHeader: "x-house-key",
  headers: { "x-region": "eu" },
  body: { chat_template_kwargs: { enable_thinking: false } },
},
```

`credentialHeader` is for an endpoint that refuses `Authorization: Bearer` and
wants its own key header; the credential still comes from `credential`, so
nothing in your app has to read the secret in order to place it. `headers` are
sent with every request and applied last, so one of them beats anything else the
wire would send. `body` is for fields the endpoint's runtime names and the
protocol does not — merged underneath the request, so what was actually asked for
wins and `model` and the conversation can never be replaced from a config file.

An endpoint that serves one request at a time refuses everything queued behind
the one in flight, and crossing to a dearer model on that is paying more
precisely because the cheap one was busy. `limits: { retries: 4, retryDelay: 2000 }`
says how many times to ask the same endpoint again and how long to wait before the
first of them; the wait doubles, with jitter, and the defaults are 2 and 200 ms. An
endpoint that says how long to wait (`retry-after`) is waited on for that long, up
to thirty seconds.

Every request runs under a clock. A streamed answer is watched between frames
(`PRAECISE_WIRE_IDLE_MS`, 45000 by default) and a buffered one as a whole
(`PRAECISE_WIRE_TOTAL_MS`, 240000 by default); an endpoint that goes silent is
crossed to the next model.

Four more fields describe what an endpoint can do, and all are optional:

```ts
house: {
  url: "https://models.internal",
  credential: "HOUSE_KEY",
  speaks: "responses",
  thinking: "effort",
  levels: ["low", "medium", "high", "xhigh"],
  output: 32_000,
  embeds: "…",
  cache: false,
},
```

`levels` are the words the endpoint takes for depth, shallowest first; the default
is `low`, `medium`, `high`, and an endpoint with a level above `high` names it here.
`output` is the most tokens one reply may take. `embeds` is the model the endpoint
turns text into vectors with (see [Stores](#stores)). `cache: false` stops the
`messages` wire marking the instructions and the conversation for the endpoint to
keep between requests, for a gateway that refuses the marker.

An endpoint that says what it charges has its answers priced. `prices` is per
million tokens, per rung, in a currency the endpoint names:

```ts
house: {
  url: "https://models.internal",
  credential: "HOUSE_KEY",
  fast: "…", best: "…",
  prices: {
    currency: "USD",
    fast: { input: 1, output: 5 },
    best: { input: 5, output: 25, cachedRead: 0.5, cacheWrite: 6 },
  },
},
```

`answer.usage.cost` is then the cost by currency (`{ USD: 0.0095 }`), and a span
carries it as `praecise.usage.cost` and `praecise.usage.cost.currency`. Where
only some of the models that answered declared a price, `usage.unpricedTokens`
says how many tokens the figure leaves out. The framework ships no price list:
an endpoint with no `prices` is not priced at all.
