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.
