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.

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

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:

NEES_BASE_URL=https://api.nees.cloud
NEES_API_KEY=your-runtime-api-key
NEES_HTTP_TIMEOUT_SECONDS=10

Then connect:

from nees import NEESHTTPClient

client = NEESHTTPClient.from_env()

print(client.health())
print(client.list_actions())

Or construct the client explicitly:

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.

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:

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:

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:

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.