> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelieo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing the nelieo-nsp Python SDK on Your System

> Install nelieo-nsp, verify your Python environment, configure API credentials, and confirm the daemon connection with a quick health check.

Before you write your first agent, you need to install the `nelieo-nsp` package, point it at a running NSP daemon, and confirm the connection works. This page walks you through every step.

## Requirements

| Requirement | Minimum Version |
| ----------- | --------------- |
| Python      | 3.11            |
| pip         | 23.0+           |
| NSP Daemon  | 1.0.0+          |

Verify your Python version before installing:

```bash theme={null}
python --version
# Python 3.11.9  ← must be 3.11 or higher
```

## Install the Package

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install nelieo-nsp
    ```
  </Tab>

  <Tab title="pip (pinned version)">
    ```bash theme={null}
    pip install "nelieo-nsp==1.0.0"
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv add nelieo-nsp
    ```
  </Tab>
</Tabs>

<Tip>
  Use a virtual environment to keep your project's dependencies isolated. Create one with `python -m venv .venv` and activate it with `source .venv/bin/activate` (macOS/Linux) or `.venv\Scripts\activate` (Windows) before running `pip install`.
</Tip>

## Dependencies

All dependencies are installed automatically. You do not need to install any of these separately:

| Package      | Version | Purpose                    |
| ------------ | ------- | -------------------------- |
| `httpx`      | ≥ 0.27  | Async HTTP client          |
| `pydantic`   | ≥ 2.7   | Data validation and models |
| `websockets` | ≥ 13.0  | WebSocket streaming        |
| `loguru`     | ≥ 0.7   | Structured logging         |

## Verify the Installation

After installing, confirm the package is importable and check the version:

```python theme={null}
import nelieo_nsp as nsp
print(nsp.__version__)  # 1.0.0
```

## Configure Environment Variables

The SDK reads three environment variables. Set them in your shell or in a `.env` file:

```bash theme={null}
# Required — your NSP API key
# Pass api_key= to NSPClient directly if you prefer not to use env vars
export NSP_API_KEY=sk_nsp_your_key_here

# Optional — override daemon host (default: 127.0.0.1)
export NSP_HOST=127.0.0.1

# Optional — override daemon port (default: 7842)
export NSP_PORT=7842
```

To generate an API key, run the following command on the machine where the daemon is installed:

```bash theme={null}
axon-daemon.exe keygen
```

## Quick Connection Test

Run this script to verify that the daemon is reachable and confirm which apps are currently tracked:

```python theme={null}
import asyncio
import nelieo_nsp as nsp

async def test():
    async with nsp.NSPClient() as client:
        # health() returns a dict with daemon version and uptime
        info = await client.health()
        print(f"Daemon version : {info['version']}")
        print(f"Uptime         : {info['uptime_seconds']}s")

        apps = await client.list_apps()
        print(f"Tracked apps   : {len(apps)}")
        for app in apps:
            print(f"  {app.app_name:25s}  pid={app.pid:6d}"
                  f"  runtime={app.runtime:6s}  conf={app.confidence:.2f}")

asyncio.run(test())
```

Expected output when the daemon is running and has detected apps:

```
Daemon version : 1.0.0
Uptime         : 3842s
Tracked apps   : 2
  Gmail                      pid= 12847  runtime=v8      conf=0.97
  Mission Planner            pid=  8821  runtime=clr     conf=0.95
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="NSPConnectionError: Failed to connect">
    The daemon is not running or is not listening on the configured host and port. Start it with:

    ```bash theme={null}
    axon-daemon.exe run
    ```

    If you changed the default port, make sure `NSP_PORT` matches `AXON_SERVER__PORT` in your daemon configuration.
  </Accordion>

  <Accordion title="NSPAuthError: Invalid or missing key">
    Your API key is missing, expired, or incorrect. Generate a fresh key:

    ```bash theme={null}
    axon-daemon.exe keygen
    ```

    Then set `NSP_API_KEY` in your environment or pass `api_key="sk_nsp_..."` directly to `NSPClient`.
  </Accordion>

  <Accordion title="NSPNotFoundError: App not found">
    The app you requested is not tracked yet. Use `await client.list_apps()` to see what the daemon currently sees. If you are targeting a Chrome tab, make sure Chrome was launched with `--remote-debugging-port=9222`.
  </Accordion>

  <Accordion title="ImportError or ModuleNotFoundError">
    You are likely running the wrong Python interpreter. Confirm you are using Python 3.11+ and that `nelieo-nsp` was installed into the active environment:

    ```bash theme={null}
    python --version            # must be 3.11+
    pip show nelieo-nsp         # confirms package is installed
    pip install --upgrade nelieo-nsp
    ```
  </Accordion>
</AccordionGroup>