{"_id":"n-atlas","name":"n-atlas","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"n-atlas","version":"0.1.0","description":"Official-style developer SDK for N-ATLaS, Nigeria's sovereign multilingual LLM (Hausa, Igbo, Yoruba, Nigerian English) and its ASR models.","keywords":["n-atlas","natlas","nigeria","hausa","igbo","yoruba","llm","asr","speech-to-text","african-languages"],"license":"Apache-2.0","author":{"name":"OneDev Studioo"},"homepage":"https://natlas-docs.vercel.app","repository":{"type":"git","url":"git+https://github.com/Kambah123/N-ATLAS-Kit.git","directory":"packages/js-sdk"},"bugs":{"url":"https://github.com/Kambah123/N-ATLAS-Kit/issues"},"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"engines":{"node":">=20"},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsup","prepare":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","clean":"rm -rf dist coverage .turbo"},"devDependencies":{"@types/node":"^22.10.5","@vitest/coverage-v8":"^2.1.8","tsup":"^8.3.5","typescript":"^5.7.3","vitest":"^2.1.8"},"_id":"n-atlas@0.1.0","gitHead":"bbaea5957f97ac955ec4104e88708c30aeeecaf6","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-4sWLrtz+iIMiB3uQCJOM76+5841A+We1v+yJi4czXfMPJBwVEhAvXm9by7t1mhgM6iwscxp9M7b3+EOTsvkBfw==","shasum":"081b8a780695abab11d7d8c465b6526e12ab4c13","tarball":"https://registry.npmjs.org/n-atlas/-/n-atlas-0.1.0.tgz","fileCount":10,"unpackedSize":308803,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/n-atlas@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFpZVy6jVPbfKwAAza+WX/E0E5BQFtxJ4mxueOQ7BeJ/AiByUM96FVMZFDo/wBz0JTff/UUgOxUJs+tbMCF7FcgNrA=="}]},"_npmUser":{"name":"0xskamber","email":"sulaimanmusa399@gmail.com"},"directories":{},"maintainers":[{"name":"0xskamber","email":"sulaimanmusa399@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n-atlas_0.1.0_1790328551816_0.6223383359098458"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-25T09:29:11.626Z","0.1.0":"2026-09-25T09:29:12.132Z","modified":"2026-09-25T09:29:12.591Z"},"maintainers":[{"name":"0xskamber","email":"sulaimanmusa399@gmail.com"}],"description":"Official-style developer SDK for N-ATLaS, Nigeria's sovereign multilingual LLM (Hausa, Igbo, Yoruba, Nigerian English) and its ASR models.","homepage":"https://natlas-docs.vercel.app","keywords":["n-atlas","natlas","nigeria","hausa","igbo","yoruba","llm","asr","speech-to-text","african-languages"],"repository":{"type":"git","url":"git+https://github.com/Kambah123/N-ATLAS-Kit.git","directory":"packages/js-sdk"},"author":{"name":"OneDev Studioo"},"bugs":{"url":"https://github.com/Kambah123/N-ATLAS-Kit/issues"},"license":"Apache-2.0","readme":"# `n-atlas`\n\nJavaScript / TypeScript client for **N-ATLaS**, Nigeria's sovereign multilingual\nLLM — Hausa, Igbo, Yorùbá and Nigerian English — and its four ASR models.\n\nPart of [N-ATLAS Kit](https://github.com/Kambah123/N-ATLAS-Kit). The client talks\nto a [`/serve`](https://github.com/Kambah123/N-ATLAS-Kit/tree/main/serve)\ngateway (or any OpenAI-compatible endpoint serving the `NCAIR1` models). There\nis no public hosted API, and this package will not call any other vendor's model.\n\n---\n\n## Install\n\n```bash\nnpm install n-atlas      # or: pnpm add n-atlas / yarn add n-atlas\n```\n\nThat registry install works after the package is published. It is not on npm yet.\n\nNot on npm/PyPI yet? Install from GitHub. The repository must be public.\n\n```bash\npnpm add \"github:Kambah123/N-ATLAS-Kit#path:packages/js-sdk\"\n```\n\n`npm install` of the repository URL installs the private workspace root, not `n-atlas`. The `pnpm` command above is the one that selects `packages/js-sdk` and builds it.\n\nNode 20+ and modern browsers. ESM and CJS, built with tsup. The runtime\ndependency is `fetch` (global in Node 20+ and browsers). Reading a filesystem\npath uses Node's `fs` and is not available in the browser — pass a `Blob`,\n`File`, `ArrayBuffer`, or `Uint8Array` there instead.\n\n## Quickstart\n\n```ts\nimport { NAtlas } from 'n-atlas';\n\nconst natlas = new NAtlas({\n  baseURL: process.env.NATLAS_BASE_URL, // http://localhost:8080 or .../v1\n  apiKey: process.env.NATLAS_API_KEY,\n});\n\nconst reply = await natlas.chat({\n  messages: [{ role: 'user', content: 'Menene ake nufi da gwagwarmaya?' }],\n  language: 'ha',\n});\n\nfor await (const chunk of await natlas.chat({\n  messages: [{ role: 'user', content: 'Sannu!' }],\n  language: 'ha',\n  stream: true,\n})) {\n  process.stdout.write(chunk.delta);\n}\n\nawait natlas.transcribe({ audio: voiceNote, language: 'ha' });\nawait natlas.translate({ text: 'Good morning', from: 'en', to: 'yo' });\n```\n\n`baseURL` and `apiKey` fall back to `NATLAS_BASE_URL` and `NATLAS_API_KEY`.\nA trailing `/v1` is optional. `GET /health` is always on the host root, and it\ndoes not require a key (the client still sends one if you configured it).\n\n| Env var              | Meaning                                                 |\n| -------------------- | ------------------------------------------------------- |\n| `NATLAS_BASE_URL`    | Gateway origin, with or without `/v1`                   |\n| `NATLAS_API_KEY`     | Bearer token the gateway expects                        |\n| `NATLAS_BACKEND`     | `openai-compatible` (default) or `hf-endpoint`          |\n| `NATLAS_MODEL`       | Defaults to `NCAIR1/N-ATLaS`. Must start with `NCAIR1/` |\n| `NATLAS_TIMEOUT_MS`  | Milliseconds. Default `60000`                           |\n| `NATLAS_MAX_RETRIES` | Extra attempts for idempotent GETs. Default `2`         |\n\nConstructor fields use the same names as the TypeScript options: `baseURL`,\n`apiKey`, `backend`, `model`, `timeout` (milliseconds), `maxRetries`,\n`retryNonIdempotent`. A per-call `timeout` overrides the client. Pass\n`signal: AbortSignal` to cancel; an aborted call is never retried.\n\n## What you can call\n\n- `chat({ messages, language, stream, temperature, maxTokens, topP, stop, model })`\n  — non-streaming returns `{ content, role, finishReason, model, usage }`.\n  `stream: true` resolves to an async iterable of `{ delta }` once the gateway\n  accepts the request. HTTP errors reject that promise, before iteration.\n- `transcribe({ audio, language, filename, responseFormat })` — `language` is\n  required and selects the monolingual ASR model. Aliases such as `hausa`,\n  `Igbo`, `Yorùbá`, and `Nigerian English` are accepted. `audio` is a path\n  (Node), `Blob` / `File`, `Buffer`, `Uint8Array`, or `ArrayBuffer`.\n  `responseFormat` is `json` (default), `text`, or `verbose_json`.\n- `listModels()` — `GET /v1/models`.\n- `health()` — `GET /health`. A degraded gateway answers 503 with JSON. That\n  is returned with `ok: false`, not thrown.\n- `translate({ text, from, to })`, `summarize({ text, language })`, and\n  `detectLanguage(text)` ask N-ATLaS with an English prompt that names the\n  language. They are not a separate translation or detection model.\n  `detectLanguage` returns `language: null` when the reply is not a recognised\n  code — it does not guess.\n- `voiceChat({ audio, language })` transcribes, then chats. The result is\n  `{ transcript, reply, language, model }`. An empty transcript is an error.\n\n`language` on chat is forwarded for the gateway's logs and stripped before\nvLLM. You do not send `date_string`; the gateway injects that.\n\n## Errors\n\nEvery failure is an `NAtlasError`. Catch the subclass you care about:\n\n| Class             | When                                                                  |\n| ----------------- | --------------------------------------------------------------------- |\n| `AuthError`       | HTTP 401 or 403                                                       |\n| `RateLimitError`  | HTTP 429. `retryAfterMs` comes from `Retry-After` when present        |\n| `BadRequestError` | Other 4xx, including local validation (empty audio, unknown language) |\n| `ServerError`     | 5xx, or a 2xx body that is not the JSON the gateway promised          |\n| `NetworkError`    | DNS, connection, or other transport failure                           |\n| `TimeoutError`    | The configured timeout elapsed, or HTTP 408                           |\n| `AbortError`      | The supplied `AbortSignal` fired                                      |\n\nMessages never include the API key, the prompt, or a transcript.\n\n## Retries\n\n`listModels` and `health` retry on 408, 429, 500, 502, 503, 504, network\nerrors, and timeouts. Chat and transcription are POST and are **not** retried\nunless you pass `maxRetries` on that call or set `retryNonIdempotent: true`.\nA retry can run the model twice.\n\nBackoff is 200 ms × 2^attempt, capped at 8 seconds, plus up to 100 ms of\njitter. A numeric `Retry-After` on 429 replaces that delay.\n\n## Backends\n\n- `openai-compatible` — the `/serve` gateway. This is the default.\n- `hf-endpoint` — same request shapes, for an OpenAI-compatible Hugging Face\n  endpoint that serves `NCAIR1/N-ATLaS`.\n- `official` — reserved. Constructing the client throws until NCAIR publishes\n  an API. It does not fall back to another model.\n\n## Runnable examples\n\nFrom the repo root, after `pnpm --filter n-atlas build`:\n\n```bash\nnode examples/js/chat.mjs\nnode examples/js/stream.mjs\nnode examples/js/transcribe.mjs path/to/note.ogg\n```\n\nEach script exits with a message if `NATLAS_BASE_URL` or `NATLAS_API_KEY` is\nmissing. They never print a fabricated reply.\n\n## Development\n\n```bash\npnpm install\npnpm --filter n-atlas test\npnpm --filter n-atlas lint\npnpm --filter n-atlas typecheck\npnpm --filter n-atlas build\n```\n\n## Licence\n\nCode: **Apache-2.0**.\n\nThe models are **not** Apache-2.0 — they carry Awarri's Open-Source Research and\nInnovation License, which requires attribution and caps you at 1,000 active\nend-users per 30 days. See\n[`NOTICE`](https://github.com/Kambah123/N-ATLAS-Kit/blob/main/NOTICE).\n\n> N-ATLaS is an initiative of the Federal Ministry of Communications, Innovation\n> and Digital Economy, and powered by Awarri Technologies.\n","readmeFilename":"README.md","_rev":"1-2291dc9754103a39f04f3aa96794520b"}