# NEES SDK v2

NEES is a developer-facing SDK for behavior-oriented AI orchestration.

It now exposes a real `NEES` class, runs a full local pipeline, supports optional remote execution, and includes trace and validation tooling.

## Installation

```bash
pip install .
```

## Quickstart

```python
from nees import NEES

nees = NEES(mode="local")

response = nees.process(Quick Start
from nees import NEES

# Initialize NEES (local mode by default)
nees = NEES()

response = nees.process(
    {
        "message": "I am stuck with this problem",
        "history": [],
        "session_id": "123"
    },
    enable_trace=True
)

print(response.text)
print(response.trace.summary)
🔄 Local vs Remote Mode

NEES supports two execution modes:

🟢 Local Mode (Default)
nees = NEES()
Runs full NEES pipeline locally
No external dependency
Maximum control and transparency
🌐 Remote Mode (Hosted NEES)
nees = NEES(mode="remote", api_key="your-api-key")
Uses hosted NEES backend
Useful for scaling and centralized control
Minimal local compute required
🧠 Architecture Overview

NEES acts as a control layer between user input and LLM.

Execution Flow:
User Input
   ↓
Intent Extraction
   ↓
Emotion Detection
   ↓
Memory Selection
   ↓
Behavior Mapping
   ↓
Decision Engine
   ↓
Structured LLM Input
   ↓
LLM
   ↓
Response + Trace
🔍 Trace & Explainability

Enable trace to inspect how NEES makes decisions:

response = nees.process(request, enable_trace=True)

print(response.trace)

Example trace:

{
  "intent": "problem_solving",
  "emotion": "frustration",
  "decision": {
    "mode": "solve",
    "tone": "direct",
    "verbosity": "short"
  }
}
🧪 Built-in Validation Demo

Run comparison between raw LLM and NEES-controlled output:

python -m nees.validation.runner

This demonstrates:

Behavior differences
Decision logic
Structured trace output
⚠️ Breaking Changes (v2.0.0)
# Old (v1)
from nees_gp_sdk import Client

# New (v2)
from nees import NEES
💡 What is NEES?

NEES (Neural Adaptive Intent Navigator) is an AI Behavior Control SDK that:

Understands user intent before generating responses
Adapts behavior based on emotional context
Uses decision logic instead of raw LLM prompting
Provides full traceability of AI reasoning
    {
        "message": "Hello",
        "history": [],
        "session_id": "123",
    },
    enable_trace=True,
)

print(response.text)
print(response.trace.summary)
```

## Modes

### Local mode

Runs the NEES pipeline inside the SDK:

- intent extraction
- emotion modulation
- memory selection
- decision engine
- behavior mapping
- local LLM adapter
- trace recording

```python
from nees import NEES

sdk = NEES(mode="local", llm="default")
response = sdk.process({"message": "I feel confused", "history": [], "session_id": "a1"}, enable_trace=True)
```

### Remote mode

Uses the migrated remote transport under `nees/client/transport.py`.

```python
from nees import NEES

sdk = NEES(mode="remote", api_key="your-api-key")
response = sdk.process({"message": "Hello", "history": [], "session_id": "r1"}, enable_trace=True)
```

## Validation Demo

```python
from nees.validation import run_demo

results = run_demo()
```

CLI:

```bash
python -m nees.validation.runner
```

## Response Shape

Every call returns an object with:

- `response.text`
- `response.trace`
- `response.trace.summary`
- `response.trace.steps` when `enable_trace=True`

## Architecture

Package layout:

```text
nees/
  __init__.py
  core.py
  orchestrator.py
  types.py
  intent/
  emotion/
  memory/
  decision/
  behavior/
  llm/
  trace/
  validation/
  client/
```

## Breaking Changes

- Main import is now `from nees import NEES`
- Main entry point is now `NEES.process(...)`
- Local orchestration is the default mode
- Remote transport is no longer the package identity
- Old `nees_gp_sdk.Client` examples are obsolete
