Metadata-Version: 2.4
Name: nees-core-sdk
Version: 0.2.0
Summary: Python client for the NEES API.
Author: Nainacore Emotional Tech
License: LicenseRef-Nainacore-SDK-Proprietary
Project-URL: Homepage, https://nees.cloud
Project-URL: Documentation, https://github.com/NEES-Anna/nees-python-sdk-developer-preview
Project-URL: Issues, https://github.com/NEES-Anna/nees-python-sdk-developer-preview/issues
Project-URL: Security, https://github.com/NEES-Anna/nees-python-sdk-developer-preview/blob/main/SECURITY.md
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 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.

```python
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:

```python
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)
```

```python
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:

```python
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.
