Methods

These are the methods on the npm package @owctopus/sdk. Create a client, then call decide. getExecution and list read runs that the Owctopus API stored.

The package is TypeScript, ESM only, and has no runtime dependencies. It runs on Node 18 or newer. Import it from your backend. Do not ship the key in a browser.

npm install @owctopus/sdk

new Owctopus(options?)

Creates the client. One key is required: an Owctopus key, an OpenAI key, or both.

import { Owctopus } from "@owctopus/sdk";

const owctopus = new Owctopus({
  apiKey: process.env.OWCTOPUS_API_KEY,
  openaiApiKey: process.env.OPENAI_API_KEY,
  baseUrl: "http://localhost:3000",
});

If you pass apiKey, the client does not read OPENAI_API_KEY. Pass openaiApiKey as well when you want OpenAI. The constructor throws when neither key is set. Keys are not written into results or error messages.

decide(input)

Runs one decision. An Owctopus key sends POST /v1/executions. The API looks up a stored condition for this decision, context, and option list. A match returns that choice and does not call AI. No match calls AI, then stores the choice as the condition for the next time. Both count as one decision. OpenAI is called from this process only when the client has no Owctopus key, and that path does not store a condition.

const result = await owctopus.decide({
  decision: "shipping_method",
  context: { cartValue: 4500, customerType: "premium", urgency: "high" },
  options: [
    { id: "standard", nextAction: "ship_standard" },
    { id: "express", nextAction: "ship_express" },
    { id: "same_day", nextAction: "ship_same_day" },
  ],
});

if (result.status === "decided" && result.option) {
  // result.option is "standard", "express", or "same_day"
}

On the OpenAI path the client picks a model before it sends the request:

• A model other than "auto" is used as written.
• A name containing fraud, risk, credit, compliance, legal, or security uses gpt-4o. So does a context larger than 8,000 bytes, or more than six options.
• One to three options and a context under 1,500 bytes uses gpt-4o-mini.
• Everything else uses the balanced model, which is also gpt-4o-mini unless you change models.

Option attributes are not sent to the model. The user message includes the decision name, the context, and the option ids. If the reply does not name one of those ids, status is needs_review and option is null.

An OpenAI result uses an executionId that starts with local_. result.learning.stored is false, and condition.updates is empty. Saving that record, and showing how a condition later changes, is not part of this call yet.

What decide() returns

Both paths return the same result shape. OpenAI fills openai and learning. The Owctopus API does not.

getExecution(executionId)

Reads one stored run with GET /v1/executions/:id. This needs an Owctopus API key. An id from an OpenAI-only decide() is not in the database, so this call will not find it.

const again = await owctopus.getExecution(result.executionId);

list(query?)

Reads recent runs with GET /v1/executions. This needs an Owctopus API key. The response is { data: DecisionResult[] }.

const recent = await owctopus.list({
  decision: "shipping_method",
  status: "decided",
  limit: 20,
});

selectModel(input, models?)

Returns the model decide() would use for this input. It does not call the network. The result is { tier, model, reason }. tier is fast, balanced, or careful.

import { selectModel } from "@owctopus/sdk";

const choice = selectModel({
  decision: "shipping_method",
  context: { cartValue: 4500 },
  options: ["standard", "express", "same_day"],
});
// choice.model is "gpt-4o-mini"

Errors

A failed call throws OwctopusError. Check error.code, error.status, and error.requestId. error.executionId is set when the Owctopus API stored the run before it failed. The client retries 408, 429, and 503 up to three times with the same idempotency key. A timeout is not retried.

import { AuthenticationError, OwctopusError, ValidationError } from "@owctopus/sdk";

try {
  await owctopus.decide({
    decision: "shipping_method",
    context: { cartValue: 4500 },
    options: ["standard", "express"],
  });
} catch (error) {
  if (error instanceof ValidationError) {
    // error.code is OPTIONS_REQUIRED when OpenAI was called with no options
  } else if (error instanceof AuthenticationError) {
    // the Owctopus key was rejected
  } else if (error instanceof OwctopusError) {
    // error.code, error.status, error.requestId
  }
}