Praecise Harness v1.1.0 Get started

Documentation · Getting started

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). 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.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.