NSP Python SDK Overview: Build Agents with nelieo-nsp - NSP

The nelieo-nsp package is the official Python SDK for NSP. It gives your agent a fully async, typed interface for every operation the daemon exposes: discovering tracked apps, reading live application state, executing actions with verification, and subscribing to real-time state change events over WebSocket. Instead of constructing raw HTTP calls or managing WebSocket connections yourself, you open an NSPClient, attach to an app by name, and work with plain Python objects.

What the SDK provides

The SDK is built around four main abstractions that you’ll use in every agent you write:

NSPClient — the top-level async context manager. It manages the HTTP connection pool, injects your API key on every request, and exposes attach(), list_apps(), get_state(), and watch().
Session (NSPSession) — a handle to one attached application. It caches state locally and provides typed accessors (get_str, get_int, get_bool), action execution with reversibility enforcement, and a watch() stream.
WebSocket streaming — session.watch() returns an async generator that yields a StateChangeNotification on every probe cycle that detects a change, so your agent reacts in real time without polling.
CLR and JVM helpers — session.clr and session.jvm expose runtime-specific methods for reading .NET fields, invoking managed methods, and reading JVM fields directly from live processes.

Quick start: a complete agent loop

The example below mirrors the gmail_agent function from the NSP quickstart. It attaches to Gmail, reads unread count and subject line, then sends a reply with post-action verification.

gmail_agent.py

import asyncio
import nelieo_nsp as nsp

async def gmail_agent():
    async with nsp.NSPClient() as client:
        # Attach to Gmail by name — no PID needed
        session = await client.attach("Gmail")

        # Read state with typed helpers
        unread = session.get_int("inbox.unread_count")
        print(f"You have {unread} unread emails")

        # Read the first email's subject and sender
        subject = session.get_str("inbox.emails[0].subject")
        sender = session.get_str("inbox.emails[0].from")
        print(f"Latest: '{subject}' from {sender}")

        # Execute an irreversible action with verification
        thread_id = session.get_str("inbox.emails[0].thread_id")
        result = await session.execute(
            "send_reply",
            parameters={
                "thread_id": thread_id,
                "body": "Thanks, I'll review this shortly.",
            },
            verify=True,
            verify_expression="inbox.emails[0].is_read == true",
        )

        print(f"Reply sent: {result.success} in {result.latency_ms}ms")

asyncio.run(gmail_agent())

You have 47 unread emails
Latest: 'Q3 Performance Report' from alice@example.com
Reply sent: True in 312ms

Features

Fully async — every network operation uses async/await via httpx and websockets. The SDK never blocks the event loop.
Typed models — SubstrateState, AppSummary, ActionResponse, and StateChangeNotification are Pydantic v2 models. Your editor autocompletes every field.
Attach by name — session = await client.attach("Gmail") finds the right process automatically. You never need to look up PIDs manually.
Reversibility enforcement — the SDK raises NSPIrreversibleNotConfirmedError before sending the request if you omit verify=True on a destructive action.
Real-time streaming — session.watch() yields events the moment the daemon detects a state change, without consuming your action rate limit.
CLR and JVM helpers — session.clr and session.jvm let you read .NET and Java fields and invoke methods directly from Python.

Explore the SDK

Installation

Install nelieo-nsp, configure your API key, and verify connectivity to the daemon.

NSPClient

Constructor parameters, all client methods, and authentication options.

Session

State accessors, action execution, refresh patterns, and wait helpers.

Streaming

Real-time WebSocket state events, sequence gaps, and reconnection handling.

CLR Helper

Read .NET fields, invoke managed methods, and handle raw return values.

JVM Helper

Read Java fields via JVMTI, invoke methods, and enumerate loaded classes.

Error Handling

Every exception the SDK raises, retry strategies, and a robust agent loop template.

​What the SDK provides

​Quick start: a complete agent loop

​Features

​Explore the SDK