advocaat

# ❓Advocaat

A small, type-safe client for asking AI questions about your data, powered by [TypeSafe](https://typesafe.ai/) Jev.

Get probabilities, choices, and scores in one request.

### Agent skill

[`skills/advocaat/SKILL.md`](./skills/advocaat/SKILL.md) teaches coding agents how to design questions and build with `ask`.

```sh
npx skills add pithings/advocaat
```

## Quick start

Install the package:

```sh
npx nypm i advocaat
```

Set your [TypeSafe](https://typesafe.ai/) API key:

```sh
export TYPESAFE_API_KEY="your-api-key"
```

Using Vercel instead? See [Vercel AI Gateway](#vercel-ai-gateway).

Ask several questions about the same data in one request:

```ts
import { ask } from "advocaat";

const issue = { title: "Checkout is down", body: "No one can pay." };

const { kind, security, severity } = await ask(issue, {
  kind: ask.choice`What kind of issue is this?`({ bug: "Something is broken", other: null }),
  security: ask.if`Does this issue describe a security vulnerability?`,
  severity: ask.score`How severe is this issue?`([
    "Cosmetic",
    "Workaround exists",
    "Blocks production",
  ]),
});

console.log(kind.choice); // "bug" | "other"
console.log(security); // true | false
console.log(severity.ratio); // 0...1
```

## Question types

Answers use the same keys as your questions. Mix any of these forms in one `ask` call:

| Want   | Use                    | Read      | Or, for the value alone |
| ------ | ---------------------- | --------- | ----------------------- |
| Yes/no | String or `ask.chance` | `.chance` | `ask.if` → `boolean`    |
| Option | `ask.choice`           | `.choice` | `ask.switch` → label    |
| Rating | `ask.score`            | `.ratio`  |                         |

The examples below reuse `ask` and `issue` from the quick start.