@partython/brain

Lightweight JavaScript SDK for the Partython AI brain — embed conversational, sales-aware AI in your app or backend in minutes.

npm install @partython/brain

Quick start

import { Brain } from '@partython/brain';

const brain = new Brain({ apiKey: process.env.PARTYTHON_API_KEY });

const result = await brain.respond({
  channel: 'web',
  channel_user_id: 'user-abc',
  message_text: "I'm planning a 5-year-old's birthday with 12 guests — any unicorn theme ideas?",
});

console.log(result.response);
// → "A unicorn theme for a 5-year-old with 12 guests — fun! Let me show you our Mystical Unicorn Bundle..."

API

new Brain(options)

| Option | Type | Default | Description | |----------|-----------|---------------------------------|-----------------------------------| | apiKey | string | (required) | Your pk_live_... API key | | baseURL | string | https://brain.partython.com | Override for self-hosted | | timeout | number | 30000 | Per-call timeout in ms | | fetch | function | global fetch | Custom fetch impl (testing) |

brain.respond(args)

| Field | Required | Description | |------------------|----------|----------------------------------------------------| | channel | ✓ | 'web' | 'whatsapp' | 'sms' | 'api' ... | | channel_user_id | ✓ | Stable id for the conversation participant | | message_text | ✓ | The customer's message | | metadata | | Pass-through metadata kept in audit trace | | dedup_key | | Idempotency key (webhook event id) | | has_image | | Hint for the smart router |

Returns Promise<RespondResult>.

Errors

import { BrainAuthError, BrainRateLimitError } from '@partython/brain';

try {
  await brain.respond({...});
} catch (err) {
  if (err instanceof BrainRateLimitError) {
    // back off — retry-after info is in err.body
  } else if (err instanceof BrainAuthError) {
    // key invalid or revoked
  }
}

| Error class | When it fires | |-------------------------|-----------------------------------------------------| | BrainAuthError | 401 / 403 — key invalid, revoked, or no scope | | BrainRateLimitError | 429 — per-key per-minute limit hit | | BrainNotFoundError | 404 — tenant misconfigured | | BrainServerError | 5xx upstream | | BrainNetworkError | Network or timeout |

Versioning

Major version bumps signal breaking changes. We follow semver strictly.

License

MIT