NEES Python SDK v0.2.0

nees-core-sdk is the synchronous Python client for NEES Core V2's supported public application-integration contracts. It is application-neutral: the SDK does not include product adapters, policy machinery, administrative controls, or Core internals.

Install with pip install nees-core-sdk (Python 3.9+), then set NEES_API_KEY or pass api_key=. Remote endpoints must use HTTPS; HTTP is accepted only for localhost development.

from nees import NEESClient

client = NEESClient()
reply = client.chat("Hello", session_id="session-123", user_id="user-123")
print(reply.reply)

SDK v0.2.0 supports API-key-scoped chat, session-memory read/reset, safe chat evidence, Core-owned governed action submit/resume/evidence, and the complete application-owned external-action lifecycle. Use get_external_action() and get_external_action_evidence() for lifecycle status and evidence.

For Core-owned actions, submit through the configured application action reference and resume only when Core requests clarification or supplies an approval continuation:

action = client.submit_action("my-app.safe-operation.v1", session_id="s-1")
if action.execution_paused:
    action = client.resume_action(action.action_id, clarifications={"context": "current"})
evidence = client.get_action_evidence(action.action_id)

from nees import ActionProposal, NEESClient

client = NEESClient()
proposal = ActionProposal("send_message", "recipient:example", {"body": "Hello"})
action = client.submit_external_action("my-app.message.v1", session_id="s-1", proposal=proposal)

# ALLOW is not permission to perform the effect. Redeem the exact permit first.
started = client.start_external_action(
    action.action_id, permit_ref=action.permit_ref, session_id="s-1", proposal=proposal
)
if started.execution_authorized:
    # The application performs its own external effect here.
    client.report_external_result(
        action.action_id, permit_ref=action.permit_ref, session_id="s-1",
        status="succeeded", observed_result="Application completed the effect."
    )
evidence = client.get_external_action_evidence(action.action_id)

Session memory is available only when the API key has the corresponding public capability:

history = client.get_session_memory("s-1")
client.reset_session_memory("s-1")

Use resume_external_action() or resume_action() only to supply clarifications and a Core-issued approval reference when required. The SDK does not accept client assertions of authority, policy, approval, trust, or execution authorization. start_external_action() is the explicit authorization boundary; the SDK never executes application business logic.

Responses are typed, immutable, and intentionally limited to public-safe fields. Unknown and private server fields are ignored. Catch NEESAPIError or a specific exported subclass such as NEESAuthenticationError, NEESConflictError, or NEESRateLimitError.

The SDK does not expose API-key administration, service administration, policy or authority stores, raw diagnostics, replay/simulation, database/runtime controls, or private audit data.