nees-sdk 3.0.0rc1__tar.gz

nees_sdk-3.0.0rc1/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_sdk-3.0.0rc1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include SECURITY.md
+exclude tests/*
+recursive-exclude tests *
+global-exclude __pycache__
+global-exclude *.py[cod]

nees_sdk-3.0.0rc1/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: nees-sdk
+Version: 3.0.0rc1
+Summary: Python SDK for the NEES AI Governance Platform
+Author: Nainacore Emotional Tech
+License-Expression: LicenseRef-Nainacore-SDK-Proprietary
+Project-URL: Homepage, https://nees.cloud
+Keywords: ai,governance,agents,safety,runtime,nees
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# NEES Python SDK
+
+`nees-sdk` is the developer-facing Python SDK for the **NEES AI Governance Platform**.
+
+NEES is designed to sit between AI intent and real-world execution. It evaluates governance facts
+such as authority, policy, scope, approvals, limits, relationships, and execution state before an
+action is allowed to proceed, and it records evidence and receipts after execution.
+
+```text
+AI application / agent / SaaS
+            |
+            v
+        nees-sdk
+            |
+            v
+      api.nees.cloud
+            |
+            v
+ NEES Governance Platform
+            |
+            v
+        NEES Core
+```
+
+The SDK does not perform your application's physical side effects. Your trusted host application or
+effect adapter performs the action only after the NEES lifecycle has reached the appropriate
+execution boundary.
+
+## Release
+
+Current release candidate: **3.0.0rc1**
+
+Python: **3.11+**
+
+## Install
+
+```bash
+pip install nees-sdk
+```
+
+The standard PyPI package is hosted-first and does **not** require the private NEES Core package.
+
+## Hosted quick start
+
+A hosted integration needs:
+
+- a NEES Deployment base URL;
+- a runtime API credential issued for the intended NEES environment.
+
+Use environment variables for credentials:
+
+```bash
+NEES_BASE_URL=https://api.nees.cloud
+NEES_API_KEY=your-runtime-api-key
+NEES_HTTP_TIMEOUT_SECONDS=10
+```
+
+Then connect:
+
+```python
+from nees import NEESHTTPClient
+
+client = NEESHTTPClient.from_env()
+
+print(client.health())
+print(client.list_actions())
+```
+
+Or construct the client explicitly:
+
+```python
+from nees import NEESHTTPClient
+
+client = NEESHTTPClient.connect(
+    "https://api.nees.cloud",
+    "your-runtime-api-key",
+)
+```
+
+Remote endpoints must use HTTPS. Plain HTTP is accepted only for localhost development.
+
+## Where the runtime API key comes from
+
+A NEES runtime credential belongs to a configured organization/project/runtime/environment. In a
+hosted deployment, credentials are issued through the NEES Control Plane or customer onboarding
+surface. The credential identifies the runtime environment server-side; callers do not submit
+tenant or owner identity as governance authority.
+
+Treat the credential as a secret. Do not commit it, place it in prompts or tool arguments, expose it
+to browser-side code, or write it to logs.
+
+## First governance check
+
+This example registers a non-side-effect action and submits an informational governance assessment.
+It is suitable as a first connectivity/governance proof because it does not perform a physical
+external effect.
+
+```python
+from nees import (
+    ActionDefinition,
+    ActionRequest,
+    GovernanceAssessment,
+    IntentClass,
+    NEESHTTPClient,
+)
+
+client = NEESHTTPClient.from_env()
+
+client.register_action(
+    ActionDefinition(
+        action_ref="quickstart.inspect",
+        name="Quickstart inspection",
+        kind="internal",
+        resource="quickstart",
+        operation="inspect",
+        side_effect=False,
+    )
+)
+
+decision = client.submit(
+    ActionRequest(
+        "quickstart.inspect",
+        "quickstart-001",
+        {"source": "sdk-quickstart"},
+    ),
+    GovernanceAssessment(
+        action_ref="quickstart.inspect",
+        intent=IntentClass.INFORMATIONAL,
+        resource_ref="quickstart",
+        requested_operation="inspect",
+        resource_operation_requested=False,
+        scope_ref="quickstart:first-check",
+        actor="developer",
+        principal="developer",
+        requested_capability="inspect",
+        resource_type="quickstart",
+    ),
+)
+
+print(decision.to_dict())
+print([event.kind for event in client.evidence(decision.operation_id)])
+print(client.receipt(decision.operation_id))
+```
+
+The repository also contains `examples/first_governance_check.py`.
+
+## Governance lifecycle
+
+For executable side-effecting actions, the important lifecycle is:
+
+1. Register an action.
+2. Establish trusted governance configuration through the appropriate administrative boundary.
+3. Submit an `ActionRequest` and `GovernanceAssessment`.
+4. Inspect the governance decision.
+5. Qualify an allowed executable decision.
+6. Redeem the issued start permit.
+7. Perform the physical effect in the trusted host application.
+8. Report the result as succeeded, failed, or uncertain.
+9. Reconcile uncertain outcomes when the external result becomes known.
+10. Inspect evidence and the final receipt.
+
+**An allow decision is not the same as performing an external effect.** Decision, qualification,
+permit redemption, effect execution, reporting, and reconciliation are separate boundaries.
+
+Example runtime flow:
+
+```python
+decision = client.submit(request, assessment)
+
+if decision.is_allowed:
+    qualification = client.qualify(decision.operation_id)
+    client.start(qualification)
+
+    # Your trusted application performs the real external effect here.
+
+    client.report(
+        decision.operation_id,
+        qualification.qualification_id,
+        "succeeded",
+        {"provider_reference": "example-123"},
+    )
+
+events = client.evidence(decision.operation_id)
+receipt = client.receipt(decision.operation_id)
+```
+
+## Governance requests
+
+The hosted client also supports continuation workflows for governance requests:
+
+```python
+client.answer_clarification(request_id, {"answer": "..."})
+
+client.decide_approval(
+    request_id,
+    approved=True,
+    approver_ref="trusted-approver",
+    expires_at=expires_at,
+)
+
+client.resume(request_id)
+client.cancel_governance_request(request_id, "no longer required")
+```
+
+Approvals and authority must come from trusted application/control-plane flows. Model output or
+caller-supplied text does not create governance authority by itself.
+
+## Result types
+
+The SDK returns small typed public result objects such as:
+
+- `DecisionResult`
+- `QualificationResult`
+- `OperationResult`
+- `EvidenceEvent`
+- `ReceiptResult`
+
+Normal governance outcomes are returned as results. Transport, authentication, invalid-request,
+lifecycle, governance-denied, rate-limit, not-found, and backend failures use the SDK exception
+hierarchy rooted at `NEESError`.
+
+## CLI
+
+The package installs the `nees` command:
+
+```bash
+nees health
+nees actions
+nees operation <operation-id>
+nees evidence <operation-id>
+nees receipt <operation-id>
+```
+
+The CLI reads `NEES_BASE_URL` and `NEES_API_KEY`, or accepts `--base-url` and `--api-key`.
+
+## Integration options across the NEES Governance Platform
+
+The Python SDK is one integration path. The broader NEES Governance Platform is designed to support
+multiple integration styles, including:
+
+- Python SDK;
+- direct REST/HTTP integration;
+- NEES Gateway;
+- REST/OpenAPI connectors;
+- MCP governance gateway;
+- framework adapters for agent/application ecosystems.
+
+Those surfaces all converge on the NEES governance lifecycle rather than implementing separate policy
+engines.
+
+## Embedded / customer-managed mode
+
+The repository also contains `NEESClient` for trusted embedded or customer-managed deployments that
+have separately licensed/provided access to NEES Core.
+
+That mode can use SQLite or PostgreSQL directly and is intentionally **not** a dependency of the
+standard public PyPI installation.
+
+Hosted users should use `NEESHTTPClient`.
+
+## Security
+
+- Never commit runtime API keys or database credentials.
+- Never expose runtime API keys in browser JavaScript, mobile bundles, prompts, or model/tool inputs.
+- Use environment variables or a managed secret store.
+- Remote NEES endpoints should use HTTPS.
+- Revoke or rotate a credential immediately if exposure is suspected.
+
+See `SECURITY.md` in the source distribution for the vulnerability-reporting policy.
+
+## Product information
+
+NEES is developed by **Nainacore Emotional Tech**.
+
+Product website: https://nees.cloud
+
+This SDK is distributed under the Nainacore SDK Proprietary License. NEES Core, service-side
+governance implementation, infrastructure, policies, models, and other proprietary technology are
+not included in this SDK distribution.

nees_sdk-3.0.0rc1/README.md

@@ -0,0 +1,279 @@
+# NEES Python SDK
+
+`nees-sdk` is the developer-facing Python SDK for the **NEES AI Governance Platform**.
+
+NEES is designed to sit between AI intent and real-world execution. It evaluates governance facts
+such as authority, policy, scope, approvals, limits, relationships, and execution state before an
+action is allowed to proceed, and it records evidence and receipts after execution.
+
+```text
+AI application / agent / SaaS
+            |
+            v
+        nees-sdk
+            |
+            v
+      api.nees.cloud
+            |
+            v
+ NEES Governance Platform
+            |
+            v
+        NEES Core
+```
+
+The SDK does not perform your application's physical side effects. Your trusted host application or
+effect adapter performs the action only after the NEES lifecycle has reached the appropriate
+execution boundary.
+
+## Release
+
+Current release candidate: **3.0.0rc1**
+
+Python: **3.11+**
+
+## Install
+
+```bash
+pip install nees-sdk
+```
+
+The standard PyPI package is hosted-first and does **not** require the private NEES Core package.
+
+## Hosted quick start
+
+A hosted integration needs:
+
+- a NEES Deployment base URL;
+- a runtime API credential issued for the intended NEES environment.
+
+Use environment variables for credentials:
+
+```bash
+NEES_BASE_URL=https://api.nees.cloud
+NEES_API_KEY=your-runtime-api-key
+NEES_HTTP_TIMEOUT_SECONDS=10
+```
+
+Then connect:
+
+```python
+from nees import NEESHTTPClient
+
+client = NEESHTTPClient.from_env()
+
+print(client.health())
+print(client.list_actions())
+```
+
+Or construct the client explicitly:
+
+```python
+from nees import NEESHTTPClient
+
+client = NEESHTTPClient.connect(
+    "https://api.nees.cloud",
+    "your-runtime-api-key",
+)
+```
+
+Remote endpoints must use HTTPS. Plain HTTP is accepted only for localhost development.
+
+## Where the runtime API key comes from
+
+A NEES runtime credential belongs to a configured organization/project/runtime/environment. In a
+hosted deployment, credentials are issued through the NEES Control Plane or customer onboarding
+surface. The credential identifies the runtime environment server-side; callers do not submit
+tenant or owner identity as governance authority.
+
+Treat the credential as a secret. Do not commit it, place it in prompts or tool arguments, expose it
+to browser-side code, or write it to logs.
+
+## First governance check
+
+This example registers a non-side-effect action and submits an informational governance assessment.
+It is suitable as a first connectivity/governance proof because it does not perform a physical
+external effect.
+
+```python
+from nees import (
+    ActionDefinition,
+    ActionRequest,
+    GovernanceAssessment,
+    IntentClass,
+    NEESHTTPClient,
+)
+
+client = NEESHTTPClient.from_env()
+
+client.register_action(
+    ActionDefinition(
+        action_ref="quickstart.inspect",
+        name="Quickstart inspection",
+        kind="internal",
+        resource="quickstart",
+        operation="inspect",
+        side_effect=False,
+    )
+)
+
+decision = client.submit(
+    ActionRequest(
+        "quickstart.inspect",
+        "quickstart-001",
+        {"source": "sdk-quickstart"},
+    ),
+    GovernanceAssessment(
+        action_ref="quickstart.inspect",
+        intent=IntentClass.INFORMATIONAL,
+        resource_ref="quickstart",
+        requested_operation="inspect",
+        resource_operation_requested=False,
+        scope_ref="quickstart:first-check",
+        actor="developer",
+        principal="developer",
+        requested_capability="inspect",
+        resource_type="quickstart",
+    ),
+)
+
+print(decision.to_dict())
+print([event.kind for event in client.evidence(decision.operation_id)])
+print(client.receipt(decision.operation_id))
+```
+
+The repository also contains `examples/first_governance_check.py`.
+
+## Governance lifecycle
+
+For executable side-effecting actions, the important lifecycle is:
+
+1. Register an action.
+2. Establish trusted governance configuration through the appropriate administrative boundary.
+3. Submit an `ActionRequest` and `GovernanceAssessment`.
+4. Inspect the governance decision.
+5. Qualify an allowed executable decision.
+6. Redeem the issued start permit.
+7. Perform the physical effect in the trusted host application.
+8. Report the result as succeeded, failed, or uncertain.
+9. Reconcile uncertain outcomes when the external result becomes known.
+10. Inspect evidence and the final receipt.
+
+**An allow decision is not the same as performing an external effect.** Decision, qualification,
+permit redemption, effect execution, reporting, and reconciliation are separate boundaries.
+
+Example runtime flow:
+
+```python
+decision = client.submit(request, assessment)
+
+if decision.is_allowed:
+    qualification = client.qualify(decision.operation_id)
+    client.start(qualification)
+
+    # Your trusted application performs the real external effect here.
+
+    client.report(
+        decision.operation_id,
+        qualification.qualification_id,
+        "succeeded",
+        {"provider_reference": "example-123"},
+    )
+
+events = client.evidence(decision.operation_id)
+receipt = client.receipt(decision.operation_id)
+```
+
+## Governance requests
+
+The hosted client also supports continuation workflows for governance requests:
+
+```python
+client.answer_clarification(request_id, {"answer": "..."})
+
+client.decide_approval(
+    request_id,
+    approved=True,
+    approver_ref="trusted-approver",
+    expires_at=expires_at,
+)
+
+client.resume(request_id)
+client.cancel_governance_request(request_id, "no longer required")
+```
+
+Approvals and authority must come from trusted application/control-plane flows. Model output or
+caller-supplied text does not create governance authority by itself.
+
+## Result types
+
+The SDK returns small typed public result objects such as:
+
+- `DecisionResult`
+- `QualificationResult`
+- `OperationResult`
+- `EvidenceEvent`
+- `ReceiptResult`
+
+Normal governance outcomes are returned as results. Transport, authentication, invalid-request,
+lifecycle, governance-denied, rate-limit, not-found, and backend failures use the SDK exception
+hierarchy rooted at `NEESError`.
+
+## CLI
+
+The package installs the `nees` command:
+
+```bash
+nees health
+nees actions
+nees operation <operation-id>
+nees evidence <operation-id>
+nees receipt <operation-id>
+```
+
+The CLI reads `NEES_BASE_URL` and `NEES_API_KEY`, or accepts `--base-url` and `--api-key`.
+
+## Integration options across the NEES Governance Platform
+
+The Python SDK is one integration path. The broader NEES Governance Platform is designed to support
+multiple integration styles, including:
+
+- Python SDK;
+- direct REST/HTTP integration;
+- NEES Gateway;
+- REST/OpenAPI connectors;
+- MCP governance gateway;
+- framework adapters for agent/application ecosystems.
+
+Those surfaces all converge on the NEES governance lifecycle rather than implementing separate policy
+engines.
+
+## Embedded / customer-managed mode
+
+The repository also contains `NEESClient` for trusted embedded or customer-managed deployments that
+have separately licensed/provided access to NEES Core.
+
+That mode can use SQLite or PostgreSQL directly and is intentionally **not** a dependency of the
+standard public PyPI installation.
+
+Hosted users should use `NEESHTTPClient`.
+
+## Security
+
+- Never commit runtime API keys or database credentials.
+- Never expose runtime API keys in browser JavaScript, mobile bundles, prompts, or model/tool inputs.
+- Use environment variables or a managed secret store.
+- Remote NEES endpoints should use HTTPS.
+- Revoke or rotate a credential immediately if exposure is suspected.
+
+See `SECURITY.md` in the source distribution for the vulnerability-reporting policy.
+
+## Product information
+
+NEES is developed by **Nainacore Emotional Tech**.
+
+Product website: https://nees.cloud
+
+This SDK is distributed under the Nainacore SDK Proprietary License. NEES Core, service-side
+governance implementation, infrastructure, policies, models, and other proprietary technology are
+not included in this SDK distribution.

nees_sdk-3.0.0rc1/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report suspected security vulnerabilities privately to Nainacore Emotional Tech through the
+security contact published on the official NEES website at https://nees.cloud.
+
+Do not publish API keys, credentials, database connection strings, access tokens, customer data,
+private deployment details, or exploit steps in public channels.
+
+## Credential safety
+
+NEES runtime API keys are secrets.
+
+- Store them in environment variables or a managed secret store.
+- Do not commit them to source control.
+- Do not expose them in browser-side JavaScript, mobile bundles, logs, prompts, or model/tool arguments.
+- Rotate or revoke a credential immediately if exposure is suspected.
+
+## Supported release line
+
+Security fixes are applied to the current supported NEES SDK release line. Pre-release versions such
+as 3.0.0rc1 are release candidates and may change before the final 3.0.0 release.
+
+## Scope
+
+This repository contains the developer-facing Python SDK. NEES Core and service-side governance
+implementation are separate proprietary components and are not part of this SDK distribution.

nees_sdk-3.0.0rc1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nees-sdk"
+version = "3.0.0rc1"
+description = "Python SDK for the NEES AI Governance Platform"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Nainacore Emotional Tech" }]
+license = "LicenseRef-Nainacore-SDK-Proprietary"
+license-files = ["LICENSE"]
+keywords = ["ai", "governance", "agents", "safety", "runtime", "nees"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["build>=1.0", "pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[project.scripts]
+nees = "nees.cli:main"
+
+[project.urls]
+Homepage = "https://nees.cloud"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.setuptools.package-data]
+nees = ["py.typed"]

nees_sdk-3.0.0rc1/setup.cfg

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