Reference#

The public surface of @kontourai/bearing: the bearing command, the package entry points, the HTTP read API, rank requests and their limits, and error codes. The README explains the behaviour behind each surface, and CONTEXT.md defines its vocabulary.

CLI#

bearing serve --catalog <file> [--host <host>] [--port <port>]
  [--max-concurrent-rank-requests <count>] [--max-rank-response-bytes <bytes>]
bearing --help

serve reads a catalog snapshot file, validates it, and serves it over the HTTP API. It prints the bound URL and stops on SIGINT or SIGTERM.

With no arguments, --help or -h prints usage. A usage error exits 2. A runtime failure, such as an invalid catalog file or a port in use, prints bearing: <message> and exits 1.

The CLI accepts only the options listed above, each at most once, in the --name <value> form. Anything else is a usage error that prints the usage and exits 2: an unknown command (Unknown command), an unrecognized or misspelled option such as --prot or --port=8080 (Unknown option), a stray positional argument (Unexpected argument), or a repeated option. A typo never falls back to a default.

Package entry points#

@kontourai/bearing is the offline core. It performs no file or network access.

The package also exports the schema-version constants (OBSERVATION_SCHEMA_VERSION, CATALOG_SCHEMA_VERSION, and the rank request and result versions), the rank limits, and the TypeScript types for every input and result.

@kontourai/bearing/node adds Node helpers:

HTTP API#

The handler serves one validated, immutable snapshot. Every path is under /v1. If the first path segment is anything else that starts with v, the response is 404 UNSUPPORTED_API_VERSION. That includes /v2 and also non-version paths such as /validate. Any other unknown path returns 404 NOT_FOUND.

<key> is the opaque key that /v1/models returns for each model, not the model id. It is a content hash of the model identity, so look it up from /v1/models first.

Every response from the handler carries these headers, including 304 responses and error responses:

• ETag: "bearing-<digest>"
• X-Bearing-Catalog-Digest and X-Bearing-Catalog-As-Of
• Access-Control-Allow-Origin: *
• Access-Control-Expose-Headers: ETag, X-Bearing-Catalog-As-Of, X-Bearing-Catalog-Digest, so browser clients can read those three headers
• Cache-Control: public, max-age=0, must-revalidate

The GET and HEAD endpoints honour If-None-Match. When it matches the snapshot's ETag (or is *), both GET and HEAD answer 304 Not Modified with no body.

Errors use one body shape:

{
  "schemaVersion": "bearing.api.error/v1",
  "error": { "code": "MODEL_NOT_FOUND", "message": "..." },
  "catalog": { "digest": "...", "asOf": "..." }
}

The Node server (bearing serve and startCatalogServer) answers a request it fails to handle with 500 INTERNAL_ERROR. That response comes from the server, not the handler, but it uses the same headers and error body, including the catalog field. If the failure happens after the response head was sent, the server closes the connection instead.

Bearing has no authentication or per-caller rate limiting. Put those at your ingress.

Rank requests#

rankCatalog, createCatalogRanker, and POST /v1/rank accept two message versions. The request's schemaVersion selects the result version: bearing.rank.request/v1 returns bearing.rank.result/v1, and bearing.rank.request/v2 returns bearing.rank.result/v2. Unknown keys are refused at every level. String fields must be non-empty and have no leading or trailing whitespace.

{
  "schemaVersion": "bearing.rank.request/v2",
  "task": { "family": "software-engineering", "suite": null },
  "inventory": [],
  "requirements": [],
  "preferences": [],
  "advisories": []
}

The nested fields:

• model is { id, revision, quantization }. revision and quantization are strings or null.
• execution must be a concrete execution profile, not null. It needs every one of runtime, adapter, effectiveContextTokens, toolSurface, hardware, and workflow:
  • runtime is { id, version }.
  • adapter is { id, version } or null.
  • effectiveContextTokens is an integer or null.
  • toolSurface is an array of strings.
  • hardware is { class, accelerator, memoryBytes } or null.
  • workflow is { id, version, condition } or null.
• aggregation is fact, mean, min, max, success-rate, or count.
• operator is eq, gte, or lte. value is a string, number, or boolean, and must be a number for gte and lte.
• direction is maximize or minimize. weight is a positive finite number.
• sourceClasses, when present, is a non-empty list of first-party and external, with no duplicates.
• Duplicate requirements or preferences are refused.

Rank request limits#

Validation applies these bounds before any evaluation, to v1 and v2 requests alike.

Errors#

Library functions throw BearingError. Its code identifies the failure and its path is a JSON path such as $.inventory[0].model; the message begins with that path.