> ## Documentation Index
> Fetch the complete documentation index at: https://game-narrative.docs.kitefrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs & Libraries

> Official SDKs for Python and TypeScript, plus the OpenAPI spec for any language.

# SDKs & Libraries

Official client libraries for integrating KiteFrost into your project: typed
interfaces and mapped error handling on top of the REST API. KiteFrost is a
**dev-time authoring** platform - the SDKs are built for authoring, auditing,
and exporting narrative content from your build pipeline and tooling, not for
per-utterance calls at game runtime.

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="python">
    Synchronous client for server-side integration and scripting.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="typescript">
    Zero-dependency, promise-based client for Node.js, Deno, and browsers.
  </Card>

  <Card title="REST API" icon="code" href="/api-reference">
    Use any HTTP client. OpenAPI 3.1 spec available for code generation in any language.
  </Card>
</CardGroup>

<Note>
  Authoring in a game engine? Export your finished narrative (Ink, Yarn Spinner, or universal JSON) from the Python/TypeScript SDK or the API, then load it with that engine's native runtime (the Ink runtime, Yarn Spinner packages, or a JSON `TextAsset`). No per-utterance cloud call at runtime.
</Note>

## Quick Comparison

SDKs are per-pack (`kitefrost-<pack>` / `@kitefrost/<pack>`, e.g.
`kitefrost-game-narrative`) - there is no single install for "all of
KiteFrost." Every per-pack package depends on a shared core
(`kitefrost-core` / `@kitefrost/core`) that owns auth, transport, and the
resources common to every pack (health, keys, projects, billing, events,
context, BYOK, webhooks). See your pack's own quickstart for the exact
package name.

| Feature                | Python                                                                                                             | TypeScript                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| **Install**            | `pip install kitefrost-game-narrative` (or `kitefrost-ttrpg-gm`)                                                   | `npm install @kitefrost/game-narrative` (or `@kitefrost/ttrpg-gm`)              |
| **Calling convention** | Synchronous (plain function calls)                                                                                 | Asynchronous (`Promise`, `async`/`await`)                                       |
| **Streaming**          | Not currently available                                                                                            | Not currently available                                                         |
| **Retry**              | One-shot re-auth on a 401; no automatic retry on 429/5xx - inspect `RateLimited.retry_after` and back off yourself | Same: one-shot re-auth on a 401 only; inspect `RateLimited.retryAfter`          |
| **Error handling**     | Typed exceptions (`KiteFrostError` subclasses)                                                                     | Typed classes (`KiteFrostError` subclasses)                                     |
| **Error telemetry**    | None sent automatically - see [Telemetry & Privacy](../core-concepts/telemetry)                                    | None sent automatically - see [Telemetry & Privacy](../core-concepts/telemetry) |
| **Dependencies**       | `httpx`                                                                                                            | None (native fetch)                                                             |
| **Min runtime**        | Python 3.10+                                                                                                       | Node 18+ / Deno                                                                 |

## Error Handling

Both SDKs expose typed exceptions/classes that map to HTTP status. Every one
carries a `feedback_id` (`fbk_...`) you can optionally reference when
contacting support - see [Telemetry & Privacy](../core-concepts/telemetry).

| Exception         | HTTP status | Description                                                               |
| ----------------- | ----------- | ------------------------------------------------------------------------- |
| `AuthError`       | 401 / 403   | Missing, invalid, or under-permissioned API key                           |
| `NotFoundError`   | 404         | Project, entity, or resource not found                                    |
| `ValidationError` | 422         | Malformed request payload                                                 |
| `RateLimited`     | 429         | Too many requests - check `retry_after` / `retryAfter`                    |
| `ServerError`     | 5xx         | Unexpected server error                                                   |
| `KiteFrostError`  | any         | Base class for the above - catch this to handle any SDK error generically |

See your pack's error catalog (if it has one) for full descriptions and resolution steps, or refer to the language-specific SDK docs for code examples:

* [Python error handling](python#error-handling)
* [TypeScript error handling](typescript#error-handling)

## Telemetry

The SDKs do not automatically report errors or usage today. See
[Telemetry & Privacy](../core-concepts/telemetry) for what the API itself
collects and how `feedback_id` works.