# IDUN Guardian quickstart for coding agents

## Setup

- **Python:** [`idun-guardian-sdk`](https://pypi.org/project/idun-guardian-sdk/0.1.23/), imported as `idun_guardian_sdk`; entry point `GuardianClient`.
- **JavaScript/web:** `@iduntech/idun-guardian-sdk`; use the [public sample](https://github.com/iduntech/idun-sample-app-js) and [JS API reference](https://iduntech.github.io/idun-guardian-sdk-js/).

Python SDK 0.1.23 supports **Python 3.9–3.13**. An unpinned install on Python 3.14
can select an older SDK that lacks `GuardianClient`. Example with Python 3.13:

```sh
python3.13 -m venv .venv
.venv/bin/python -m pip install "idun-guardian-sdk==0.1.23"
.venv/bin/python -c 'from idun_guardian_sdk import GuardianClient'
```

## Account and environment

Python uses an account **API key**, called an **API token** in the SDK:

1. Log in to [Guardian Console](https://console.idunguardian.com).
2. Open **Account > Devices** and link your Guardian if needed.
3. Open [Account > API key](https://console.idunguardian.com/account/api-key).
4. Generate a key if none exists, then use the **Copy** button.

Creating a key requires a device linked to the account. The device can be offline.
Store the complete copied key locally. Give the agent its configuration location,
not the key in chat. A truncated copy can cause an authentication failure.

`GuardianClient()` reads `IDUN_API_TOKEN`. Set `export IDUN_API_TOKEN="YOUR_API_KEY"`
locally, or pass a local secret store value as `GuardianClient(api_token=token)`.

Authentication check; no Bluetooth connection is needed:

```python
from idun_guardian_sdk import GuardianClient

GuardianClient().get_user_info()
print("Authentication successful")
```

Python defaults: HTTP `https://api.idun.cloud`, WebSocket `wss://ws-api.idun.cloud`.
For another environment, set both `http_endpoint_url` and `ws_endpoint_url`; use its
account key and Console. The authentication example above uses production defaults.
JS sample: OAuth login needs IDUN-provided app IDs; use its authentication setup.
Browser BLE requires Chrome/Edge support; the sample covers Capacitor mobile setup.

## IDUN concepts and hardware

Bluetooth connects hardware; cloud HTTP handles accounts, exports, and reports;
cloud WebSocket uploads recording data and delivers live insights/predictions.
Console account linking is separate from Bluetooth. Cloud exports need no device.
Live data requires a recording session; subscribing alone does not start acquisition.
The Python SDK supports raw/filtered EEG, IMU, impedance, reports, and LSL integration.
Real-time predictions require IDUN enablement and are not enabled by default.

- Enable computer Bluetooth and grant Bluetooth access to the process running Python.
- Turn on Guardian and release any connection from another app or computer.
- `search_device()` matches names beginning with `IGE` (older examples: `IGEB`); multiple Guardians prompt for selection.
- On macOS, the discovery address is a Bluetooth UUID. It is not the cloud device ID.
- `get_device_mac_address()` reads the connected device's physical identity; `get_user_info()["device_id"]` is its linked cloud identity.
  Normalize letter case and colon/hyphen separators when comparing them.
- `connect_device()` and `disconnect_device()` are async; related BLE operations need one `asyncio` loop.

For fit, preparation, and impedance requirements, use the [Guardian user manual](https://docs.idunguardian.com/en/page-1c-igeb-quickstart).
A working data connection does not establish EEG signal quality.

## Python SDK 0.1.23 caveats

- For one app recording sequentially, use `start_recording()` directly and await it
  before starting the next recording. No cleanup override is needed.
  The SDK can end existing `ONGOING` and `NOT_STARTED` account recordings at startup;
  do not start while another client is recording on the same account.
- `get_recordings()` returns a dictionary containing `items` and `lastEvaluatedKey`,
  not a bare list. `recordingId` values in the list can be integers while the recording
  method returns a string. Compare their string forms when finding a session.
- Recording status includes `NOT_STARTED`, `ONGOING`, `PROCESSING`, `COMPLETED`,
  and `FAILED`. A completed capture and a downloadable cloud file are separate steps.
- `download_file()` takes a destination directory as `file_path`, chooses the filename,
  and returns `None`. EEG exports use `timestamp` and `ch1`. EEG is nominally 250 Hz.
- SDK output can include device/account identifiers. WebSocket diagnostics or download
  exceptions can include credentials or signed URLs. These are sensitive diagnostics.

## Documentation and support

- [Getting started, subscriptions, LSL, and reports](https://sdk-docs.idunguardian.com/getting-started.html)
- [API reference](https://sdk-docs.idunguardian.com/sdk.html)
- [Example scripts](https://sdk-docs.idunguardian.com/examples.html)
- [Data formats and analysis](https://sdk-docs.idunguardian.com/data-analysis.html)
- [Troubleshooting](https://sdk-docs.idunguardian.com/troubleshooting.html)
- [Offline EEG synchronization](https://github.com/iduntech/idn-sync-data) covers alignment of EDF/XDF/CSV data after acquisition.
- IDUN support: support@iduntechnologies.com