natlas 0.1.0__py3-none-any.whl

natlas/__init__.py

@@ -0,0 +1,111 @@
+"""``natlas`` — the Python SDK for N-ATLaS, Nigeria's sovereign multilingual LLM.
+
+Every inference path talks to ``NCAIR1/N-ATLaS`` or an ``NCAIR1`` ASR model.
+Point :class:`NAtlas` at a ``/serve`` gateway (``NATLAS_BASE_URL`` +
+``NATLAS_API_KEY``). There is no public hosted API, and this package will
+not call any other vendor's model.
+
+Sync and async clients share one API surface, both built on ``httpx``.
+"""
+
+from __future__ import annotations
+
+from natlas.async_client import AsyncNAtlas as AsyncNAtlas
+from natlas.client import NAtlas as NAtlas
+from natlas.constants import (
+    ASR_MAX_SEGMENT_SECONDS as ASR_MAX_SEGMENT_SECONDS,
+)
+from natlas.constants import (
+    ASR_MODEL_IDS as ASR_MODEL_IDS,
+)
+from natlas.constants import (
+    ASR_SAMPLE_RATE as ASR_SAMPLE_RATE,
+)
+from natlas.constants import (
+    ATTRIBUTION as ATTRIBUTION,
+)
+from natlas.constants import (
+    BACKENDS as BACKENDS,
+)
+from natlas.constants import (
+    LANGUAGE_NAMES as LANGUAGE_NAMES,
+)
+from natlas.constants import (
+    LANGUAGES as LANGUAGES,
+)
+from natlas.constants import (
+    LLM_CONTEXT_TOKENS as LLM_CONTEXT_TOKENS,
+)
+from natlas.constants import (
+    LLM_MODEL_ID as LLM_MODEL_ID,
+)
+from natlas.constants import (
+    Backend as Backend,
+)
+from natlas.constants import (
+    Language as Language,
+)
+from natlas.constants import (
+    is_language as is_language,
+)
+from natlas.errors import AbortError as AbortError
+from natlas.errors import AuthError as AuthError
+from natlas.errors import BadRequestError as BadRequestError
+from natlas.errors import NAtlasError as NAtlasError
+from natlas.errors import NetworkError as NetworkError
+from natlas.errors import RateLimitError as RateLimitError
+from natlas.errors import ServerError as ServerError
+from natlas.errors import TimeoutError as TimeoutError
+from natlas.languages import language_from_model_text as language_from_model_text
+from natlas.languages import normalise_language as normalise_language
+from natlas.models import ChatResult as ChatResult
+from natlas.models import ChatStreamChunk as ChatStreamChunk
+from natlas.models import HealthStatus as HealthStatus
+from natlas.models import LanguageDetection as LanguageDetection
+from natlas.models import ModelInfo as ModelInfo
+from natlas.models import ModelList as ModelList
+from natlas.models import Summary as Summary
+from natlas.models import Transcription as Transcription
+from natlas.models import Translation as Translation
+from natlas.models import Usage as Usage
+from natlas.models import VoiceChatResult as VoiceChatResult
+from natlas.version import __version__ as __version__
+
+__all__ = [
+    "ASR_MAX_SEGMENT_SECONDS",
+    "ASR_MODEL_IDS",
+    "ASR_SAMPLE_RATE",
+    "ATTRIBUTION",
+    "BACKENDS",
+    "LANGUAGES",
+    "LANGUAGE_NAMES",
+    "LLM_CONTEXT_TOKENS",
+    "LLM_MODEL_ID",
+    "AbortError",
+    "AsyncNAtlas",
+    "AuthError",
+    "Backend",
+    "BadRequestError",
+    "ChatResult",
+    "ChatStreamChunk",
+    "HealthStatus",
+    "Language",
+    "LanguageDetection",
+    "ModelInfo",
+    "ModelList",
+    "NAtlas",
+    "NAtlasError",
+    "NetworkError",
+    "RateLimitError",
+    "ServerError",
+    "Summary",
+    "TimeoutError",
+    "Transcription",
+    "Translation",
+    "Usage",
+    "VoiceChatResult",
+    "__version__",
+    "is_language",
+    "language_from_model_text",
+    "normalise_language",
+]

natlas/async_client.py

@@ -0,0 +1,413 @@
+"""Asynchronous client for an N-ATLaS gateway."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
+from typing import Literal, overload
+
+import httpx
+
+from natlas.errors import BadRequestError, NAtlasError
+from natlas.languages import normalise_language
+from natlas.models import (
+    ChatResult,
+    ChatStreamChunk,
+    HealthStatus,
+    LanguageDetection,
+    ModelList,
+    Summary,
+    Transcription,
+    Translation,
+    VoiceChatResult,
+)
+from natlas.transport import AsyncTransport
+from natlas.wire import (
+    SSE_DONE,
+    AudioInput,
+    Settings,
+    assert_response_format,
+    build_chat_body,
+    default_rng,
+    detect_messages,
+    detection_from,
+    load_audio,
+    parse_chat_chunk,
+    parse_chat_result,
+    parse_health,
+    parse_model_list,
+    parse_sse_line,
+    parse_transcription,
+    require_retries,
+    require_timeout,
+    resolve_settings,
+    summarize_messages,
+    summary_from,
+    translate_messages,
+    translation_from,
+    voice_messages,
+    voice_result,
+)
+
+
+async def _default_sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+async def _aiter(response: httpx.Response) -> AsyncIterator[ChatStreamChunk]:
+    try:
+        async for line in response.aiter_lines():
+            parsed = parse_sse_line(line)
+            if parsed is SSE_DONE:
+                return
+            if parsed is None:
+                continue
+            yield parse_chat_chunk(parsed)
+    finally:
+        await response.aclose()
+
+
+class AsyncNAtlas:
+    """Asynchronous client. Use it as an async context manager.
+
+    .. code-block:: python
+
+        async with AsyncNAtlas() as natlas:
+            async for chunk in await natlas.chat(messages=[...], stream=True):
+                print(chunk.delta, end="")
+
+    ``timeout`` is seconds. See :class:`natlas.client.NAtlas` for configuration.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        backend: str | None = None,
+        model: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        retry_non_idempotent: bool = False,
+        http_client: httpx.AsyncClient | None = None,
+        sleep: Callable[[float], Awaitable[None]] | None = None,
+        rng: Callable[[], float] | None = None,
+    ) -> None:
+        self._settings: Settings = resolve_settings(
+            base_url=base_url,
+            api_key=api_key,
+            backend=backend,
+            model=model,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_non_idempotent=retry_non_idempotent,
+        )
+        self._owns_client = http_client is None
+        self._client = http_client if http_client is not None else httpx.AsyncClient()
+        self._closed = False
+        self._http = AsyncTransport(
+            self._client,
+            self._settings,
+            sleep or _default_sleep,
+            rng or default_rng,
+        )
+
+    async def __aenter__(self) -> AsyncNAtlas:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._owns_client:
+            await self._client.aclose()
+
+    @overload
+    async def chat(
+        self,
+        *,
+        messages: Sequence[Mapping[str, object]],
+        stream: Literal[True],
+        language: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        model: str | None = None,
+        stop: str | Sequence[str] | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> AsyncIterator[ChatStreamChunk]: ...
+
+    @overload
+    async def chat(
+        self,
+        *,
+        messages: Sequence[Mapping[str, object]],
+        stream: Literal[False] = False,
+        language: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        model: str | None = None,
+        stop: str | Sequence[str] | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> ChatResult: ...
+
+    async def chat(
+        self,
+        *,
+        messages: Sequence[Mapping[str, object]],
+        stream: bool = False,
+        language: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        model: str | None = None,
+        stop: str | Sequence[str] | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> ChatResult | AsyncIterator[ChatStreamChunk]:
+        """Chat with N-ATLaS. ``stream=True`` resolves to an async iterator of deltas."""
+        self._ensure_open()
+        body = build_chat_body(
+            messages=messages,
+            stream=stream,
+            language=language,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            model=model or self._settings.model,
+            stop=stop,
+            default_model=self._settings.model,
+        )
+        url = f"{self._settings.api_base}/chat/completions"
+        timeout_s = _optional_timeout(timeout)
+        retries = _optional_retries(max_retries)
+        if stream:
+            response = await self._http.open_stream(
+                url, json_body=body, timeout=timeout_s, max_retries=retries
+            )
+            return _aiter(response)
+        payload, _status = await self._http.request_json(
+            "POST",
+            url,
+            idempotent=False,
+            json_body=body,
+            timeout=timeout_s,
+            max_retries=retries,
+        )
+        return parse_chat_result(payload)
+
+    async def list_models(
+        self,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> ModelList:
+        """``GET /v1/models``."""
+        self._ensure_open()
+        payload, _status = await self._http.request_json(
+            "GET",
+            f"{self._settings.api_base}/models",
+            idempotent=True,
+            timeout=_optional_timeout(timeout),
+            max_retries=_optional_retries(max_retries),
+        )
+        return parse_model_list(payload)
+
+    async def health(
+        self,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> HealthStatus:
+        """``GET /health``. A 503 degraded body is returned with ``ok=False``."""
+        self._ensure_open()
+        payload, status = await self._http.request_json(
+            "GET",
+            self._settings.health_url,
+            idempotent=True,
+            timeout=_optional_timeout(timeout),
+            max_retries=_optional_retries(max_retries),
+            ok_statuses=frozenset({503}),
+        )
+        return parse_health(payload, status)
+
+    async def transcribe(
+        self,
+        *,
+        audio: AudioInput,
+        language: str,
+        filename: str | None = None,
+        response_format: str = "json",
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> Transcription:
+        """Transcribe audio. ``language`` selects the NCAIR1 ASR model."""
+        self._ensure_open()
+        lang = normalise_language(language)
+        fmt = assert_response_format(response_format)
+        name, data, content_type = load_audio(audio, filename)
+        url = f"{self._settings.api_base}/audio/transcriptions"
+        files = {"file": (name, data, content_type)}
+        form = {"language": lang, "response_format": fmt}
+        timeout_s = _optional_timeout(timeout)
+        retries = _optional_retries(max_retries)
+        if fmt == "text":
+            text = await self._http.request_text(
+                "POST",
+                url,
+                idempotent=False,
+                data=form,
+                files=files,
+                timeout=timeout_s,
+                max_retries=retries,
+            )
+            return parse_transcription(text, lang)
+        payload, _status = await self._http.request_json(
+            "POST",
+            url,
+            idempotent=False,
+            data=form,
+            files=files,
+            timeout=timeout_s,
+            max_retries=retries,
+        )
+        return parse_transcription(payload, lang)
+
+    async def translate(
+        self,
+        *,
+        text: str,
+        from_: str,
+        to: str,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> Translation:
+        """Translate between Hausa, Igbo, Yoruba, and Nigerian English via N-ATLaS."""
+        messages, source, target = translate_messages(text, from_, to)
+        result = await self._complete(
+            messages,
+            language=target,
+            temperature=0.2 if temperature is None else temperature,
+            max_tokens=1024 if max_tokens is None else max_tokens,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        return translation_from(result, source, target)
+
+    async def summarize(
+        self,
+        *,
+        text: str,
+        language: str,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> Summary:
+        """Summarise text in one of the four languages. The summary is the model's."""
+        messages, target = summarize_messages(text, language)
+        result = await self._complete(
+            messages,
+            language=target,
+            temperature=0.3 if temperature is None else temperature,
+            max_tokens=512 if max_tokens is None else max_tokens,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        return summary_from(result, target)
+
+    async def detect_language(
+        self,
+        text: str,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> LanguageDetection:
+        """Ask N-ATLaS which of the four languages ``text`` is in."""
+        result = await self._complete(
+            detect_messages(text),
+            language=None,
+            temperature=0,
+            max_tokens=16,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        return detection_from(result)
+
+    async def voice_chat(
+        self,
+        *,
+        audio: AudioInput,
+        language: str,
+        filename: str | None = None,
+        instruction: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> VoiceChatResult:
+        """Transcribe a voice note, then ask N-ATLaS to reply."""
+        lang = normalise_language(language)
+        heard = await self.transcribe(
+            audio=audio,
+            language=lang,
+            filename=filename,
+            response_format="json",
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        if not heard.text.strip():
+            raise BadRequestError("The transcription was empty, so there is nothing to reply to.")
+        result = await self._complete(
+            voice_messages(heard.text, lang, instruction),
+            language=lang,
+            temperature=0.3 if temperature is None else temperature,
+            max_tokens=512 if max_tokens is None else max_tokens,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        return voice_result(heard.text, result, lang)
+
+    async def _complete(
+        self,
+        messages: Sequence[Mapping[str, object]],
+        *,
+        language: str | None,
+        temperature: float | None,
+        max_tokens: int | None,
+        timeout: float | None,
+        max_retries: int | None,
+    ) -> ChatResult:
+        return await self.chat(
+            messages=messages,
+            stream=False,
+            language=language,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise NAtlasError("This client is closed.")
+
+
+def _optional_timeout(value: float | None) -> float | None:
+    if value is None:
+        return None
+    return require_timeout(value, "timeout")
+
+
+def _optional_retries(value: int | None) -> int | None:
+    if value is None:
+        return None
+    return require_retries(value, "max_retries")

natlas/backends/__init__.py

@@ -0,0 +1,20 @@
+"""Backend adapters.
+
+``openai-compatible`` and ``hf-endpoint`` speak the same wire protocol as
+``/serve``. ``official`` and ``local`` are reserved and raise, rather than
+pretending a public NCAIR API or an in-process model exists.
+"""
+
+from __future__ import annotations
+
+from natlas.backends.hf_endpoint import resolve_hf_endpoint_base
+from natlas.backends.local import local_backend_unavailable
+from natlas.backends.official import official_backend_unavailable
+from natlas.backends.openai_compatible import resolve_openai_compatible_base
+
+__all__ = [
+    "local_backend_unavailable",
+    "official_backend_unavailable",
+    "resolve_hf_endpoint_base",
+    "resolve_openai_compatible_base",
+]

natlas/backends/hf_endpoint.py

@@ -0,0 +1,14 @@
+"""A Hugging Face Inference Endpoint running N-ATLaS under vLLM.
+
+It speaks the same OpenAI-compatible protocol as ``/serve``. Point
+``base_url`` at that endpoint. Speech routes exist only when the endpoint
+is the N-ATLAS Kit gateway.
+"""
+
+from __future__ import annotations
+
+from natlas.backends.openai_compatible import (
+    resolve_openai_compatible_base as resolve_hf_endpoint_base,
+)
+
+__all__ = ["resolve_hf_endpoint_base"]

natlas/backends/local.py

@@ -0,0 +1,13 @@
+"""In-process weights are a later milestone. This build only speaks HTTP."""
+
+from __future__ import annotations
+
+from natlas.errors import NAtlasError
+
+
+def local_backend_unavailable() -> None:
+    raise NAtlasError(
+        "The local transformers backend is not implemented in this version. "
+        "Point base_url at a /serve gateway. Loading NCAIR1 weights in-process "
+        "needs a GPU and is not part of the HTTP client."
+    )

natlas/backends/official.py

@@ -0,0 +1,13 @@
+"""There is no public NCAIR API yet. Fail loudly rather than invent one."""
+
+from __future__ import annotations
+
+from natlas.errors import NAtlasError
+
+
+def official_backend_unavailable() -> None:
+    raise NAtlasError(
+        "The official NCAIR API is not public yet. Use backend "
+        '"openai-compatible" and point base_url at a /serve gateway '
+        "(see serve/README.md)."
+    )

natlas/backends/openai_compatible.py

@@ -0,0 +1,26 @@
+"""URL rules for the ``/serve`` gateway and any OpenAI-compatible N-ATLaS endpoint."""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+from natlas.errors import BadRequestError
+
+
+def resolve_openai_compatible_base(base_url: str) -> tuple[str, str]:
+    """Return ``(api_base, health_url)``.
+
+    Both of these are accepted:
+
+    * ``http://localhost:8080``
+    * ``http://localhost:8080/v1``
+
+    ``/health`` is never under ``/v1``. A trailing slash is ignored.
+    """
+    parsed = urlsplit(base_url.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise BadRequestError(f"base_url must be an http(s) URL, got {base_url!r}.")
+    trimmed = base_url.strip().rstrip("/")
+    api_base = trimmed if trimmed.endswith("/v1") else f"{trimmed}/v1"
+    root = api_base[: -len("/v1")]
+    return api_base, f"{root}/health"