# wisp-ai

[![A WikiBonsai Project](https://img.shields.io/badge/%F0%9F%8E%8B-A%20WikiBonsai%20Project-brightgreen)](https://github.com/wikibonsai/wikibonsai)
[![NPM package](https://img.shields.io/npm/v/wisp-ai)](https://npmjs.org/package/wisp-ai)

<p align="center">
  <img src="./karpathy-ghost.jpg" width="55%"/>
</p>

> In folklore, will-o'-the-wisps are ghostly lights that appear over marshes and bogs at night. Some tales say they guide lost travelers to safety. Others warn they lure the unwary off the path and into the swamp. There's no way to tell just from their glow which one they'll be.
> 
> Follow the lights...But watch your step.

AI automation for markdown-based knowledge management.

👻🧚 Whisper with [wisps](https://x.com/karpathy/status/1973756330449236009) in your [🎋 WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.

## Install

```bash
yarn add wisp-ai
```

## Usage

```typescript
import { Wisp, seed } from 'wisp-ai';

// initialize
const wisp = new Wisp({
  provider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// seed a concept
const result = await seed(wisp, 'machine learning');
console.log(result.ancestors); // semantic ancestors
console.log(result.node);      // semantic node (attributes)
console.log(result.tree);      // semantic tree (outline)
```

### Providers

Supports `anthropic`, `openai`, and `xai`. Pass `model` to override the default:

```typescript
const wisp = new Wisp({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-5.4',
});
```

### Custom Prompts

Use the client directly for custom prompts:

```typescript
const result = await wisp.generate(
  'You are a helpful assistant.',
  'Explain quantum computing.',
);
```

### Markdown Formatting

Seed output formatting is configurable:

```typescript
const result = await seed(wisp, 'machine learning', {
  mkdn: {
    attrs: 'caml',           // 'caml' | 'yaml'
    case: 'lower',           // 'upper' | 'lower'
    text: '[[wikitext]]',    // 'regular' | '[[wikitext]]'
    indent: '2 spaces',      // '2 spaces' | '4 spaces' | '1 tab'
    whitespace: 'kabob-case', // 'white space' | 'snake_case' | 'kabob-case'
  },
});
```

## Development

```bash
yarn install
yarn build
yarn test
```