npm package: @lotd/word-orb
Description: Trusted language infrastructure for AI agents. 170K words, 47 languages, ethics built in. Kelly Certified.
Author: Lesson of the Day PBC
Latest version: 1.0.0

# @lotd/word-orb

Trusted language infrastructure for AI agents, robotics, and teaching platforms.
170,000+ words. 47 languages. Ethics built in. Kelly Certified.

[![npm](https://img.shields.io/npm/v/@lotd/word-orb)](https://www.npmjs.com/package/@lotd/word-orb)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Why Word Orb?

Every AI agent needs language it can trust. Word Orb gives your agent:

- **Definitions** — accurate, etymology-backed, not hallucinated
- **47-language translations** — native script + phonetic pronunciation
- **Age-appropriate tones** — kid-safe (5-12), teen, adult, and elder (65+) variants
- **Ethics compliance** — gender equity analysis, inclusive alternatives, AI identity honesty
- **Kelly Certification** — the gold standard for how agents should speak

## Install

```bash
npm install @lotd/word-orb
```

## Quick Start

```js
const { WordOrb } = require('@lotd/word-orb');

const orb = new WordOrb({ apiKey: 'wo_your_api_key' });

// Look up any word
const result = await orb.word('serendipity');
console.log(result.def);       // Full definition
console.log(result.ipa);       // /ˌsɛɹ.ən.ˈdɪp.ɪ.ti/
console.log(result.etym);      // Etymology
console.log(result.langs);     // 47-language translations
console.log(result.kelly_says); // Kelly's personal insight
```

### Get a free API key

```js
const { key } = await orb.signup('you@example.com');
// Returns: wo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
// 50 free lookups per day, upgrade anytime
```

### MCP Integration (one line)

Add to your Claude Desktop `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "word-orb": {
      "url": "https://word-orb-api.nicoletterankin.workers.dev/mcp"
    }
  }
}
```

## API Reference

### `new WordOrb(options?)`

Create a client instance.

| Option    | Type     | Default | Description |
|-----------|----------|---------|-------------|
| `apiKey`  | `string` | —       | Your `wo_` API key ([get one free](https://word-orb-api.nicoletterankin.workers.dev/pricing)) |
| `baseUrl` | `string` | `https://word-orb-api.nicoletterankin.workers.dev` | API base URL |

---

### `orb.word(word)` → `Promise<WordResult>`

Look up any word. Returns definition, pronunciation (IPA), part of speech, etymology, translations across 47 languages, age-appropriate tones, Kelly's insight, and connections to related words.

```js
const data = await orb.word('courage');
```

**Response:**
```js
{
  word: 'courage',
  ipa: '/ˈkɜːrɪdʒ/',
  pos: 'noun',
  def: 'Courage is the ability to face fear, danger, or difficulty...',
  etym: 'From Old French "corage," meaning "heart, spirit," from Latin "cor" (heart)...',
  kelly_says: 'Courage isn\'t about not being afraid...',
  langs: {
    es: 'coraje',
    fr: 'courage',
    de: 'Mut',
    zh: '勇气',
    ja: '勇気',
    // ... 42 more languages
  },
  tones: {
    child: 'Courage is when you feel scared but you do the brave thing anyway...',
    teen: 'The ability to act in the face of fear...',
    adult: 'The capacity to confront fear, pain, danger, uncertainty...'
  },
  _source: 'd1',
  _tier: 'free'
}
```

---

### `orb.words()` → `Promise<WordListResult>`

Get the full word library listing with basic metadata.

```js
const { count, words } = await orb.words();
console.log(`${count} words available`);
// words: [{ word: 'aardvark', ipa: '...', pos: 'noun', lookups: 42 }, ...]
```

---

### `orb.audit(email, words)` → `Promise<AuditResult>`

Run a **free** Kelly Certified compliance audit on your agent's vocabulary. Returns a detailed report showing ethics flags, missing age-tone variants, AI identity cautions, and an overall compliance grade.

```js
const report = await orb.audit('cto@robotics.co', [
  'understand', 'feel', 'believe', 'help', 'teach', 'love'
]);

console.log(report.grade);            // 'B+'
console.log(report.compliance_score); // 82
console.log(report.findings);         // [{ word: 'feel', category: 'ai_identity', ... }]
console.log(report.gaps);             // { no_ethics_review: [...], ... }
```

---

### `orb.feedback(word, vote, correction?)` → `Promise<{ ok: boolean }>`

Submit vocabulary feedback. Help improve Word Orb's definitions.

```js
await orb.feedback('serendipity', 1);                    // upvote
await orb.feedback('irregardless', -1, 'Not a word!');   // downvote + correction
```

---

### `orb.signup(email)` → `Promise<SignupResult>`

Create a free API key instantly. 50 lookups per day.

```js
const { key, tier, daily_limit, quickstart } = await orb.signup('dev@company.com');
// key: 'wo_abc123...'
// tier: 'free'
// daily_limit: 50
// quickstart: { curl: '...', javascript: '...', python: '...' }
```

---

### `orb.me()` → `Promise<KeyStatus>`

Check your API key usage, tier, and remaining calls.

```js
const status = await orb.me();
console.log(status.tier);            // 'starter'
console.log(status.calls_today);     // 127
console.log(status.remaining_today); // 4873
console.log(status.daily_limit);     // 5000
```

---

### `orb.health()` → `Promise<HealthResult>`

Check service health and system status.

```js
const health = await orb.health();
// { status: 'healthy', checks: { kv: 'ok', d1: 'ok (162250 words)', ... } }
```

---

### `orb.stats()` → `Promise<StatsResult>`

Get database size and usage statistics.

```js
const stats = await orb.stats();
console.log(stats.d1_words);    // 162250
console.log(stats.active_keys); // 5
```

## Pricing

| Tier | Price | API Calls/Day | Best For |
|------|-------|---------------|----------|
| **Free** | $0 | 50 | Prototyping, evaluation |
| **Starter** | $49/mo | 5,000 | Side projects, small apps |
| **Growth** | $149/mo | 50,000 | Production agents, teams |
| **Enterprise** | $499/mo | Unlimited | Scale, SLA, priority support |

[Get your API key →](https://word-orb-api.nicoletterankin.workers.dev/pricing)

## Error Handling

```js
const { WordOrb } = require('@lotd/word-orb');
const orb = new WordOrb({ apiKey: 'wo_your_key' });

try {
  const result = await orb.word('nonexistent');
} catch (err) {
  if (err.status === 401) {
    console.error('Invalid API key');
  } else if (err.status === 429) {
    console.error('Rate limit reached — upgrade at /pricing');
  } else if (err.status === 404) {
    console.error('Word not found');
  } else {
    console.error('API error:', err.message);
  }
}
```

## TypeScript

Full TypeScript definitions included — import types directly:

```ts
import { WordOrb, WordResult, AuditResult, KeyStatus } from '@lotd/word-orb';

const orb = new WordOrb({ apiKey: process.env.WORD_ORB_KEY });
const result: WordResult = await orb.word('ephemeral');
```

## Links

- [Pricing & Signup](https://word-orb-api.nicoletterankin.workers.dev/pricing)
- [The Daily Lesson](https://thedailylesson.com) — Word Orb in production
- [MCP Server](https://word-orb-api.nicoletterankin.workers.dev/mcp) — for Claude, GPT, and agent frameworks
- [Smithery](https://smithery.ai/servers/lotdpbc/word-orb) — install via Smithery

## About

Built by [Lesson of the Day PBC](https://lotdpbc.com). Kelly Certified language for a world where AI agents speak responsibly.

## License

MIT