Skip to content

EvoSpikeNet SDK & Frontend API Key Configuration

[!NOTE] For the latest implementation status, please refer to Functional Implementation Status (Remaining Functionality).

Implementation notes (artifacts): See docs/implementation/ARTIFACT_MANIFESTS.md for the artifact_manifest.json output by the training script and recommended CLI flags.

This document details how to set up API keys for EvoSpikeNet's SDK and frontend to access the API.

  • EVOSPIKENET_API_KEY — Set a single API key. Setting this environment variable on the backend or SDK execution process automatically uses the SDK's authentication header X-API-Key.
  • EVOSPIKENET_API_KEYS — You can set multiple keys separated by commas. The SDK uses the first key of this variable as the default.

Example for Linux/macOS:

export EVOSPIKENET_API_KEY=dev-key-1
# or
export EVOSPIKENET_API_KEYS=dev-key-1,dev-key-2

For Docker Compose, add environment variables to docker-compose.yml.

Distributed brain + ASR/Whisper configuration (added on 2026-04-20)

In a distributed node environment, there is no need to add methods on the SDK side; ASR routes are controlled using server-side environment variables.

  • VIDEO_ANALYSIS_ASR_BACKEND=asr_fallback|whisper_real
  • VIDEO_ANALYSIS_WHISPER_MODEL=tiny|base|small|...
  • VIDEO_ANALYSIS_WHISPER_DEVICE=cpu|cuda
  • VIDEO_ANALYSIS_ASR_PREPROCESS=1|0

Example using docker-compose.distributed.yml:

VIDEO_ANALYSIS_ASR_BACKEND=whisper_real \
VIDEO_ANALYSIS_WHISPER_MODEL=base \
docker compose -f docker-compose.distributed.yml up -d

The SDK client uses EvoSpikeNetAPIClient(base_url=...) as before, Switch the destination node (e.g. http://localhost:8001) and execute.

Usage example with SDK (Python)

If you use evospikenet.sdk.EvoSpikeNetAPIClient directly, you can provide the api_key in the constructor (recommended).

<!-- from evospikenet.sdk import EvoSpikeNetAPIClient -->

client = EvoSpikeNetAPIClient(base_url='http://api:8000', api_key='dev-key-1')
# Or if you use an environment variable, you don't have to pass api_key to the constructor.
client = EvoSpikeNetAPIClient(base_url='http://api:8000')

For SDK multipart uploads and file operations, add X-API-Key to the header within the SDK.

Frontend (Dash) server-side API calls

To the frontend of this repository, we added a common helper frontend/pages/api_client.py to call the API on the server side.

  • Read keys from EVOSPIKENET_API_KEY / EVOSPIKENET_API_KEYS on startup.
  • Calling set_api_key(key) to change the API key at runtime updates the session header in the server process.

To apply an API key from the frontend UI: 1. Added Runtime API Key field to the frontend Settings page. 2. After entering the key and pressing Apply API Key, api_client.set_api_key() will be called in the Dash server and subsequent server-side API calls will use the new X-API-Key. 3. It is also saved as security.api_key in config/settings.json (for convenience for development purposes).

Note: This save is in plain text. Consider key management (such as Vault) in production environments.

Front-end browser-side API calls

  • The Dash front end of this repository is designed to make API calls on the server side. If you want to access the API directly from the browser, you need to send the X-API-Key from the browser-side JavaScript. If you plan to implement this, please design in CORS and browser safety.

Local procedure sample

  1. Set environment variables and start Docker:
export EVOSPIKENET_API_KEY=dev-key-1
docker compose up --build
  1. Or, after launching the app, enter the API key on the Dash Settings page and press Apply API Key.

Troubleshooting

  • If the API returns 401 Missing API key:
  • Make sure X-API-Key is set on both the server side (backend) and frontend (Dash server).

  • Please set EVOSPIKENET_API_KEYS in docker-compose.yml and restart the API container.

  • If the list of frontends remains empty:

  • Check the Dash server-side logs to see if the X-API-Key header is added when calling the API.

Reference: Existing changes

  • Implemented get/post/download/delete/set_api_key/get_api_key in frontend/pages/api_client.py.
  • Several frontend pages have been updated to use api_client.
  • Added runtime API key input field and apply button to frontend/pages/settings.py.

AEG-Comm communication optimization settings ⭐ NEW (2026-01-23)

AEG-Comm is a function that optimizes communication in distributed brain simulation. Configuration can be done through the SDK.

Environment variable settings```bash

AEG-Comm enable

export EVOSPIKENET_AEG_COMM_ENABLED=true

Energy threshold setting

export EVOSPIKENET_AEG_ENERGY_THRESHOLD=10.0

Important modality settings (comma separated)

export EVOSPIKENET_AEG_CRITICAL_MODALITIES=force,safety,text

Force change threshold

export EVOSPIKENET_AEG_FORCE_CHANGE_THRESHOLD=10.0 

### Configuration example with SDK```python
<!-- TODO: update or remove - import fail<!-- Remember: Automatic conversion not possible — please fix manually -->eNetAPIClient -->

client = EvoSpikeNetAPIClient()

# AEG-Comm settings
config_result = client.set_aeg_comm_config(
    node_id="brain_node_1",
    enable_comm=True,
    energy_threshold=10.0,
    critical_modalities=["force", "safety", "text"],
    force_change_threshold=10.0
)

# Communication statistics acquisition
stats = client.get_communication_stats(node_id="brain_node_1")
print(f"通信削減率: {stats['reduction_rate']}%")

Distributed brain simulation settings

To enable AEG-Comm when running a distributed brain simulation, add the following to the configuration file:

# config/settings.yaml
distributed_brain:
  enable_aeg_comm: true
  aeg_config:
    energy_threshold: 10.0
    critical_modalities: ["force", "safety"]
    force_change_threshold: 10.0

We recommend adding this document to your README or integrating it into your operating instructions.