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

pip install .

Quickstart

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

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.

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

from nees.validation import run_demo

results = run_demo()

CLI:

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:

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