nees-core-sdk 0.1.0__tar.gz

nees_core_sdk-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+Nainacore SDK Proprietary License
+
+Copyright (c) 2026 Nainacore Emotional Tech. All rights reserved.
+
+Permission is granted to download, install, and use the NEES Python SDK solely
+for the purpose of accessing NEES services for which the user has valid
+authorization.
+
+This license applies only to the NEES Python SDK distribution. It does not grant
+any license, ownership right, or other right in the NEES Core Engine, NEES
+service-side software, governance implementation, policies, models, data,
+infrastructure, trademarks, patents, or other proprietary technology of
+Nainacore Emotional Tech.
+
+Except where applicable law expressly permits otherwise, you may not:
+- use the SDK to bypass authentication, authorization, usage limits, or service
+  protections;
+- use the SDK or service interfaces to obtain, reconstruct, or disclose
+  non-public service-side implementation details; or
+- represent this SDK or any modified version as an official Nainacore product.
+
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, AND NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY
+LAW, NAINACORE EMOTIONAL TECH SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM USE OF THE SDK.
+
+Use of NEES hosted services may also be subject to separate service terms.

nees_core_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+exclude tests/*
+recursive-exclude tests *
+global-exclude __pycache__
+global-exclude *.py[cod]

nees_core_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: nees-core-sdk
+Version: 0.1.0
+Summary: Python client for the NEES API.
+Author: Nainacore Emotional Tech
+License-Expression: LicenseRef-Nainacore-SDK-Proprietary
+Project-URL: Homepage, https://nees.cloud
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Dynamic: license-file
+
+# NEES Python SDK
+
+The NEES Python SDK is the official Python client for connecting applications to NEES governed AI runtime services.
+SDK v0.1 currently exposes only the authenticated chat capability.
+
+## Install
+
+```bash
+pip install nees-core-sdk
+```
+
+The PyPI distribution is `nees-core-sdk`; the Python import package is `nees`.
+
+Python 3.9 or newer is required.
+
+## Quickstart
+
+Trial API keys are currently issued manually by Nainacore.
+
+Windows PowerShell:
+
+```powershell
+$env:NEES_API_KEY="..."
+```
+
+Linux/macOS:
+
+```bash
+export NEES_API_KEY="..."
+```
+
+```python
+from nees import NEESClient
+
+client = NEESClient()
+result = client.chat("Reply with exactly: NEES SDK connected")
+print(result.reply)
+```
+
+To configure a different endpoint or timeout:
+
+```python
+client = NEESClient(api_key="...", base_url="https://api.nees.cloud", timeout=30)
+```
+
+The SDK requires HTTPS for remote endpoints. Plain HTTP is accepted only for localhost development.
+
+The SDK currently supports only `chat:invoke`.
+
+## Response boundary
+
+The SDK exposes a deliberately limited public response model: reply/session identifiers,
+request and trace identifiers, and selected public governance fields. Unrecognized API
+response fields are not surfaced by the SDK.
+
+## Errors
+
+Catch `NEESAPIError` for all API failures, or a specific exported subclass such as
+`NEESAuthenticationError`, `NEESAuthorizationError`, and `NEESRateLimitError`.
+
+## License
+
+The SDK is distributed under the Nainacore SDK Proprietary License included with this package.
+This license applies to the SDK only and does not grant rights in the NEES Core Engine or
+other service-side technology.

nees_core_sdk-0.1.0/README.md

@@ -0,0 +1,65 @@
+# NEES Python SDK
+
+The NEES Python SDK is the official Python client for connecting applications to NEES governed AI runtime services.
+SDK v0.1 currently exposes only the authenticated chat capability.
+
+## Install
+
+```bash
+pip install nees-core-sdk
+```
+
+The PyPI distribution is `nees-core-sdk`; the Python import package is `nees`.
+
+Python 3.9 or newer is required.
+
+## Quickstart
+
+Trial API keys are currently issued manually by Nainacore.
+
+Windows PowerShell:
+
+```powershell
+$env:NEES_API_KEY="..."
+```
+
+Linux/macOS:
+
+```bash
+export NEES_API_KEY="..."
+```
+
+```python
+from nees import NEESClient
+
+client = NEESClient()
+result = client.chat("Reply with exactly: NEES SDK connected")
+print(result.reply)
+```
+
+To configure a different endpoint or timeout:
+
+```python
+client = NEESClient(api_key="...", base_url="https://api.nees.cloud", timeout=30)
+```
+
+The SDK requires HTTPS for remote endpoints. Plain HTTP is accepted only for localhost development.
+
+The SDK currently supports only `chat:invoke`.
+
+## Response boundary
+
+The SDK exposes a deliberately limited public response model: reply/session identifiers,
+request and trace identifiers, and selected public governance fields. Unrecognized API
+response fields are not surfaced by the SDK.
+
+## Errors
+
+Catch `NEESAPIError` for all API failures, or a specific exported subclass such as
+`NEESAuthenticationError`, `NEESAuthorizationError`, and `NEESRateLimitError`.
+
+## License
+
+The SDK is distributed under the Nainacore SDK Proprietary License included with this package.
+This license applies to the SDK only and does not grant rights in the NEES Core Engine or
+other service-side technology.

nees_core_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nees-core-sdk"
+version = "0.1.0"
+description = "Python client for the NEES API."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Nainacore Emotional Tech" }]
+dependencies = ["requests>=2.31,<3"]
+license = "LicenseRef-Nainacore-SDK-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://nees.cloud"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+files = ["src"]
+disable_error_code = ["import-untyped"]

nees_core_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nees_core_sdk-0.1.0/src/nees/__init__.py

@@ -0,0 +1,38 @@
+"""Public Python client for the NEES API."""
+
+from .client import NEESClient
+from .errors import (
+    NEESAPIError,
+    NEESAuthenticationError,
+    NEESAuthorizationError,
+    NEESBadRequestError,
+    NEESConfigurationError,
+    NEESConflictError,
+    NEESConnectionError,
+    NEESNotFoundError,
+    NEESRateLimitError,
+    NEESServerError,
+    NEESTimeoutError,
+    NEESValidationError,
+)
+from .models import NEESChatResponse, NEESGovernanceResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "NEESClient",
+    "NEESChatResponse",
+    "NEESGovernanceResult",
+    "NEESAPIError",
+    "NEESAuthenticationError",
+    "NEESAuthorizationError",
+    "NEESBadRequestError",
+    "NEESConfigurationError",
+    "NEESConflictError",
+    "NEESConnectionError",
+    "NEESNotFoundError",
+    "NEESRateLimitError",
+    "NEESServerError",
+    "NEESTimeoutError",
+    "NEESValidationError",
+]

nees_core_sdk-0.1.0/src/nees/_http.py

@@ -0,0 +1,75 @@
+"""Private HTTP transport for the NEES SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+import requests
+
+from .errors import (
+    NEESAPIError,
+    NEESAuthenticationError,
+    NEESAuthorizationError,
+    NEESBadRequestError,
+    NEESConflictError,
+    NEESConnectionError,
+    NEESNotFoundError,
+    NEESRateLimitError,
+    NEESServerError,
+    NEESTimeoutError,
+    NEESValidationError,
+)
+
+_STATUS_ERRORS: Dict[int, Type[NEESAPIError]] = {
+    400: NEESBadRequestError,
+    401: NEESAuthenticationError,
+    403: NEESAuthorizationError,
+    404: NEESNotFoundError,
+    409: NEESConflictError,
+    422: NEESValidationError,
+    429: NEESRateLimitError,
+}
+
+
+def request_json(
+    session: requests.Session,
+    url: str,
+    headers: Dict[str, str],
+    payload: Dict[str, Any],
+    timeout: float,
+) -> Dict[str, Any]:
+    try:
+        response = session.post(url, headers=headers, json=payload, timeout=timeout)
+    except requests.Timeout as exc:
+        raise NEESTimeoutError("Request to NEES timed out.") from exc
+    except requests.RequestException as exc:
+        raise NEESConnectionError("Could not connect to the NEES API.") from exc
+    request_id = response.headers.get("X-Request-ID") or response.headers.get("X-Request-Id")
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if response.status_code >= 400:
+        error_type = _STATUS_ERRORS.get(
+            response.status_code, NEESServerError if response.status_code >= 500 else NEESAPIError
+        )
+        raise error_type(
+            _error_message(body, response.reason),
+            status_code=response.status_code,
+            request_id=request_id,
+        )
+    if not isinstance(body, dict):
+        raise NEESAPIError(
+            "NEES API returned malformed JSON.",
+            status_code=response.status_code,
+            request_id=request_id,
+        )
+    return body
+
+
+def _error_message(body: Any, fallback: str) -> str:
+    if isinstance(body, dict):
+        detail = body.get("detail") or body.get("message") or body.get("error")
+        if isinstance(detail, str) and detail.strip():
+            return detail.strip()
+    return fallback or "NEES API request failed."

nees_core_sdk-0.1.0/src/nees/client.py

@@ -0,0 +1,107 @@
+"""Synchronous NEES API client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+import requests
+
+from ._http import request_json
+from .errors import NEESConfigurationError
+from .models import NEESChatResponse, NEESGovernanceResult
+
+DEFAULT_BASE_URL = "https://api.nees.cloud"
+DEFAULT_TIMEOUT = 30.0
+_LOCAL_HTTP_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+class NEESClient:
+    """Synchronous client for the public NEES chat API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = (api_key if api_key is not None else os.getenv("NEES_API_KEY", "")).strip()
+        if not key:
+            raise NEESConfigurationError(
+                "An API key is required. Set NEES_API_KEY or pass api_key."
+            )
+        normalized_url = base_url.strip().rstrip("/")
+        self._validate_base_url(normalized_url)
+        if timeout <= 0:
+            raise NEESConfigurationError("timeout must be greater than zero.")
+        self._api_key = key
+        self.base_url = normalized_url
+        self.timeout = float(timeout)
+        self._session = requests.Session()
+
+    def __repr__(self) -> str:
+        return f"NEESClient(base_url={self.base_url!r}, timeout={self.timeout!r})"
+
+    def chat(
+        self, prompt: str, *, session_id: Optional[str] = None, user_id: Optional[str] = None
+    ) -> NEESChatResponse:
+        """Send a prompt to the NEES `/chat` endpoint."""
+        payload: Dict[str, Any] = {"prompt": prompt}
+        if session_id is not None:
+            payload["session_id"] = session_id
+        if user_id is not None:
+            payload["user_id"] = user_id
+        body = request_json(
+            self._session, f"{self.base_url}/chat", self._headers(), payload, self.timeout
+        )
+        return self._parse_chat_response(body)
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": "nees-python/0.1.0",
+            "Accept": "application/json",
+        }
+
+    @staticmethod
+    def _validate_base_url(base_url: str) -> None:
+        parsed = urlparse(base_url)
+        if parsed.scheme == "https" and parsed.netloc:
+            return
+        if parsed.scheme == "http" and parsed.hostname in _LOCAL_HTTP_HOSTS:
+            return
+        raise NEESConfigurationError(
+            "base_url must use HTTPS; HTTP is allowed only for localhost development."
+        )
+
+    @staticmethod
+    def _parse_chat_response(body: Dict[str, Any]) -> NEESChatResponse:
+        required = ("reply", "session_id", "request_id", "governance")
+        if any(field not in body for field in required) or not isinstance(body["governance"], dict):
+            raise NEESConfigurationError("NEES API returned an invalid chat response.")
+
+        governance = body["governance"]
+        status_value = (
+            governance.get("status")
+            if "status" in governance
+            else governance.get("policy_status")
+        )
+        return NEESChatResponse(
+            reply=str(body["reply"]),
+            session_id=str(body["session_id"]),
+            request_id=str(body["request_id"]),
+            trace_id=str(body["trace_id"]) if body.get("trace_id") is not None else None,
+            governance=NEESGovernanceResult(
+                decision=_optional_text(governance.get("decision")),
+                status=_optional_text(status_value),
+                reason=_optional_text(governance.get("reason")),
+            ),
+        )
+
+
+def _optional_text(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    return str(value)

nees_core_sdk-0.1.0/src/nees/errors.py

@@ -0,0 +1,60 @@
+"""Exceptions raised by the NEES SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class NEESAPIError(Exception):
+    """Base exception for safe API failures."""
+
+    def __init__(
+        self, message: str, *, status_code: Optional[int] = None, request_id: Optional[str] = None
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+
+
+class NEESConfigurationError(NEESAPIError):
+    pass
+
+
+class NEESBadRequestError(NEESAPIError):
+    pass
+
+
+class NEESAuthenticationError(NEESAPIError):
+    pass
+
+
+class NEESAuthorizationError(NEESAPIError):
+    pass
+
+
+class NEESNotFoundError(NEESAPIError):
+    pass
+
+
+class NEESConflictError(NEESAPIError):
+    pass
+
+
+class NEESValidationError(NEESAPIError):
+    pass
+
+
+class NEESRateLimitError(NEESAPIError):
+    pass
+
+
+class NEESServerError(NEESAPIError):
+    pass
+
+
+class NEESTimeoutError(NEESAPIError):
+    pass
+
+
+class NEESConnectionError(NEESAPIError):
+    pass

nees_core_sdk-0.1.0/src/nees/models.py

@@ -0,0 +1,24 @@
+"""Response models for the public NEES API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class NEESGovernanceResult:
+    """Public governance result safe for SDK consumers."""
+
+    decision: Optional[str] = None
+    status: Optional[str] = None
+    reason: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class NEESChatResponse:
+    reply: str
+    session_id: str
+    request_id: str
+    trace_id: Optional[str]
+    governance: NEESGovernanceResult

nees_core_sdk-0.1.0/src/nees_core_sdk.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: nees-core-sdk
+Version: 0.1.0
+Summary: Python client for the NEES API.
+Author: Nainacore Emotional Tech
+License-Expression: LicenseRef-Nainacore-SDK-Proprietary
+Project-URL: Homepage, https://nees.cloud
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Dynamic: license-file
+
+# NEES Python SDK
+
+The NEES Python SDK is the official Python client for connecting applications to NEES governed AI runtime services.
+SDK v0.1 currently exposes only the authenticated chat capability.
+
+## Install
+
+```bash
+pip install nees-core-sdk
+```
+
+The PyPI distribution is `nees-core-sdk`; the Python import package is `nees`.
+
+Python 3.9 or newer is required.
+
+## Quickstart
+
+Trial API keys are currently issued manually by Nainacore.
+
+Windows PowerShell:
+
+```powershell
+$env:NEES_API_KEY="..."
+```
+
+Linux/macOS:
+
+```bash
+export NEES_API_KEY="..."
+```
+
+```python
+from nees import NEESClient
+
+client = NEESClient()
+result = client.chat("Reply with exactly: NEES SDK connected")
+print(result.reply)
+```
+
+To configure a different endpoint or timeout:
+
+```python
+client = NEESClient(api_key="...", base_url="https://api.nees.cloud", timeout=30)
+```
+
+The SDK requires HTTPS for remote endpoints. Plain HTTP is accepted only for localhost development.
+
+The SDK currently supports only `chat:invoke`.
+
+## Response boundary
+
+The SDK exposes a deliberately limited public response model: reply/session identifiers,
+request and trace identifiers, and selected public governance fields. Unrecognized API
+response fields are not surfaced by the SDK.
+
+## Errors
+
+Catch `NEESAPIError` for all API failures, or a specific exported subclass such as
+`NEESAuthenticationError`, `NEESAuthorizationError`, and `NEESRateLimitError`.
+
+## License
+
+The SDK is distributed under the Nainacore SDK Proprietary License included with this package.
+This license applies to the SDK only and does not grant rights in the NEES Core Engine or
+other service-side technology.

nees_core_sdk-0.1.0/src/nees_core_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/nees/__init__.py
+src/nees/_http.py
+src/nees/client.py
+src/nees/errors.py
+src/nees/models.py
+src/nees_core_sdk.egg-info/PKG-INFO
+src/nees_core_sdk.egg-info/SOURCES.txt
+src/nees_core_sdk.egg-info/dependency_links.txt
+src/nees_core_sdk.egg-info/requires.txt
+src/nees_core_sdk.egg-info/top_level.txt

nees_core_sdk-0.1.0/src/nees_core_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nees_core_sdk-0.1.0/src/nees_core_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests<3,>=2.31

nees_core_sdk-0.1.0/src/nees_core_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+nees