Skip to content

Environment variable operation policy (EvoSpikeNet)

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

This document defines the meaning of operationally important environment variables used in the EvoSpikeNet repository and recommends settings for each environment (CI/development/staging/production).

Purpose: - Prevent misuse of mocks/stubs - Clarify data sources (mock vs real) and prevent deceptive data from being mixed into production - Provide consistent operational procedures between CI and production

Target environment variable

EVOSPIKENET_ALLOW_STUBS

  • Description: Flag to explicitly allow in-process stub/mock implementations (e.g. in-memory Zenoh stubs, CARLA mocks, etc.).
  • Received values: 0|1, false|true, no|yes, off|on (case does not matter)
  • Default: 0 (disabled)
  • Behavior: If 1, the code is allowed to "start successfully with mocks" when dependent libraries are not present. If 0, mocks are not allowed and many integration points will fail on connection failure.
  • Enforced block: When EVOSPIKENET_ENV/ENV is prod|production|staging, setting EVOSPIKENET_ALLOW_STUBS=1 fails closed at startup.
  • CI (unit tests): 1 (for using stubs in unit tests)
  • Development local: 1 (permitted for development efficiency)
  • Staging: 0 (disallowing is recommended to perform verification close to actual production)
  • Production: 0 (must be disabled)

Operation caution

  • Please check the pre-deployment checklist that EVOSPIKENET_ALLOW_STUBS is 0 before the production image/production deployment.
  • Enabling 1 incorrectly in production hides the absence of dependent services and poses a significant operational risk.

EVOSPIKENET_ALLOW_ROS_STUBS

  • Description: Explicitly allow ROS2 mock routes (embodied PLA robot interface).
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: Allowed only outside prod|production|staging when unset.
  • Behavior:
  • 1: allow mock routes (dev/CI use).
  • In prod|production|staging, 1 fails closed at startup.
  • CI (unit tests): 1
  • Development local: 1
  • Staging: 0
  • Production: 0

EVOSPIKENET_DATA_STRICT_REAL

  • Description: Flag to enforce strictness of data provenance. If 1, a component that receives data with source_type of mock will throw an exception/handle it as an error.
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: 0 (disabled)
  • CI (unit test): 0 (unit test uses mock data)
  • Development local: 0 (Local development uses mocks a lot)
  • Staging: 1 (recommended for verifying production approximation)
  • Production: 1 (required. Prevents mock inclusion)

Operation caution

  • Enabling EVOSPIKENET_DATA_STRICT_REAL=1 may cause test jobs to fail, so it is recommended to run "mock permission job" and "strict real data verification job" separately in the CI test matrix.

EVOSPIKENET_FAIL_ON_COMM_FALLBACK

  • Description: Controls behavior when real Zenoh backend is not available in the communication layer.
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: 0 (disabled)
  • Operation:
  • 1: Disables communication fallback (SDK relay / in-memory stub) and stops exception with fail-closed.
  • 0: Allow fallback under the condition of EVOSPIKENET_ALLOW_STUBS.
  • CI (Unit Test): 0
  • Development local: 0
  • Staging: 1
  • Production: 1

EVOSPIKENET_ALLOW_COMPAT_FALLBACKS

  • Description: Allow synthetic fallback responses for the compatibility API (/datasets, /images, /audio, /state, /training).
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: 1 in development environment, 0 when determining production/staging.
  • Behavior: If 0, return 503 and compat_fallback_disabled.
  • CI (Unit Test): 1
  • Development local: 1
  • Staging: 0
  • Production: 0

EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS

  • Description: Allow placeholder response when video analysis cannot generate a transcript/narrative.
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: 1 in development environment, 0 when determining production/staging.
  • Operation:
  • 1: Returns a transcript/narrative synthetic response.
  • 0: The job is terminated as failed (fail-closed).
  • CI (Unit Test): 1
  • Development local: 1
  • Staging: 0
  • Production: 0

VIDEO_ANALYSIS_FAIL_CLOSED

  • Description: Controls whether video analysis backends may fall back.
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: 1 in prod|production|release|staging|stage via EVOSPIKENET_PROFILE/EVOSPIKENET_ENV/ENV, otherwise 0.
  • Behavior:
  • 1: raise on missing real backends (fail-closed).
  • 0: allow stub/fallback selection.

Operation caution

  • Validate real backend dependencies and model placement before production rollout.
  • Use the video analysis /diagnostics endpoint to inspect fallback usage when available.

EVOSPIKENET_ALLOW_DUMMY_SERVICES

  • Description: Allows an alternative dummy service implementation to be activated on import failure.
  • Received values: 0|1, false|true, no|yes, off|on
  • Default: 1 in development environment, 0 when determining production/staging.
  • Behavior: If 0, the dummy implementation does not return a synthetic response and raises an exception.
  • CI (Unit Test): 1
  • Development local: 1
  • Staging: 0
  • Production: 0

RAG_V2_NER_BACKEND / RAG_V2_NER_MODEL

  • Description: NER backend and model used by the RAG v2 preprocessing pipeline.
  • Accepted values:
  • RAG_V2_NER_BACKEND: transformers|regex
  • RAG_V2_NER_MODEL: Transformers NER model name (for example tner/roberta-large-japanese-char-luw-ner)
  • Defaults:
  • RAG_V2_NER_BACKEND=transformers
  • RAG_V2_NER_MODEL=tner/roberta-large-japanese-char-luw-ner
  • Behavior:
  • In production-like environments (production/staging), transformer initialization failure is fail-closed.
  • In non-production, the system may fall back to regex extraction.

RAG_V2_PREPROCESSING_WARMUP / RAG_V2_PREPROCESSING_WARMUP_STRICT

  • Description: Warm up RAG v2 preprocessing components (Sudachi / NER / QueryExpander) at startup and validate readiness before serving requests.
  • Accepted values: 0|1, false|true, no|yes, off|on
  • Defaults:
  • RAG_V2_PREPROCESSING_WARMUP=1
  • RAG_V2_PREPROCESSING_WARMUP_STRICT: 1 in production-like environments, 0 otherwise
  • Behavior:
  • When strict mode is enabled, insufficient preprocessing readiness causes fail-closed startup.

RAG_V2_SUDACHI_VERSION / RAG_V2_SUDACHI_DICT_VERSION / RAG_V2_SUDACHI_DICT_DIST_NAMES

  • Description: Expected Sudachi versions and candidate dictionary distribution names for version validation.
  • Defaults:
  • RAG_V2_SUDACHI_VERSION=0.7.5
  • RAG_V2_SUDACHI_DICT_VERSION=20240716
  • RAG_V2_SUDACHI_DICT_DIST_NAMES=sudachidict_small,sudachipy-dict-small
  • Behavior:
  • In production-like environments, version mismatch is fail-closed.
  • In non-production, the mismatch is logged as a warning and startup may continue.

RAG_V2_QUERY_EXPANDER_BACKEND / RAG_V2_QUERY_EXPANDER_STRICT / RAG_V2_QUERY_EXPANDER_LM_BACKEND

  • Description: QueryExpander execution backend and strictness policy.
  • Accepted values:
  • RAG_V2_QUERY_EXPANDER_BACKEND: rule|llm|hybrid
  • RAG_V2_QUERY_EXPANDER_STRICT: 0|1 and equivalent boolean forms
  • RAG_V2_QUERY_EXPANDER_LM_BACKEND: backend name, default evospikenet_lm
  • Defaults:
  • RAG_V2_QUERY_EXPANDER_BACKEND=rule
  • RAG_V2_QUERY_EXPANDER_STRICT: 1 in production-like environments, 0 otherwise
  • Behavior:
  • llm/hybrid modes require JSON output in the form {"expansions": [...]}.
  • In strict mode, invalid JSON or inference failure raises an exception.

RAG_V2_QUERY_EXPANDER_QUALITY_GUARD / RAG_V2_QUERY_EXPANDER_MIN_DIVERSITY / RAG_V2_QUERY_EXPANDER_MAX_REDUNDANCY / RAG_V2_QUERY_EXPANDER_GUARD_HISTORY_SIZE

  • Description: Query expansion quality guard thresholds and history retention settings.
  • Defaults:
  • RAG_V2_QUERY_EXPANDER_QUALITY_GUARD=1
  • RAG_V2_QUERY_EXPANDER_MIN_DIVERSITY=0.35
  • RAG_V2_QUERY_EXPANDER_MAX_REDUNDANCY=0.7
  • RAG_V2_QUERY_EXPANDER_GUARD_HISTORY_SIZE=20
  • Behavior:
  • When output quality is below threshold, llm/hybrid automatically falls back to deterministic rule expansion.
  • Guard history is stored in a ring buffer and includes query_hash plus a quality snapshot per event.
  • Monitoring is available through GET /api/v2/rag/preprocessing/health and POST /api/v2/rag/search debug output.

EVOSPIKENET_PTP_DEVICE

  • Description: PTP hardware clock device path for EEG time sync (e.g., /dev/ptp0).
  • Received values: device path string
  • Default: Auto-detect from /dev/ptp0..3 if unset.

Operation caution

  • When the device is missing, time sync falls back to NTP.

EVOSPIKENET_PTP_NTP_SAMPLES

  • Description: Number of NTP samples used when falling back from PTP.
  • Received values: 1-10
  • Default: 3

EVOSPIKENET_MTLS_REQUIRED / EVOSPIKENET_ALLOWED_CERTS / EVOSPIKENET_ALLOWED_CERT_FINGERPRINTS

  • Description: Control mTLS enforcement and allowed client certificates.
  • Received values:
  • EVOSPIKENET_MTLS_REQUIRED: 0|1, false|true, no|yes, off|on
  • EVOSPIKENET_ALLOWED_CERTS: comma-separated PEM strings
  • EVOSPIKENET_ALLOWED_CERT_FINGERPRINTS: comma-separated SHA256 fingerprints

Operation caution

  • TLS termination proxies must forward headers in this order: X-Forwarded-Client-Cert -> X-SSL-Client-Cert -> X-Client-Cert
  • Include verification status headers: X-SSL-Client-Verify or X-Client-Verify.

EVOSPIKENET_ALERT_SLACK_WEBHOOK_URL / EVOSPIKENET_ALERT_SMTP_* / EVOSPIKENET_ALERT_PAGERDUTY_ROUTING_KEY

  • Description: Alert notification channels (Slack/SMTP/PagerDuty).
  • Received values:
  • Slack: EVOSPIKENET_ALERT_SLACK_WEBHOOK_URL
  • SMTP: EVOSPIKENET_ALERT_SMTP_HOST, EVOSPIKENET_ALERT_SMTP_USER, EVOSPIKENET_ALERT_SMTP_PASS, EVOSPIKENET_ALERT_EMAIL_TO
  • PagerDuty: EVOSPIKENET_ALERT_PAGERDUTY_ROUTING_KEY

Operation caution

  • If none are set, alerts are recorded in logs only.

Configuration example (.env)

# Example: For production
EVOSPIKENET_ALLOW_STUBS=0
EVOSPIKENET_DATA_STRICT_REAL=1
EVOSPIKENET_FAIL_ON_COMM_FALLBACK=1
EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=0
EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=0
EVOSPIKENET_ALLOW_DUMMY_SERVICES=0

# Example: CI/Development
EVOSPIKENET_ALLOW_STUBS=1
EVOSPIKENET_DATA_STRICT_REAL=0
EVOSPIKENET_FAIL_ON_COMM_FALLBACK=0
EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=1
EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=1
EVOSPIKENET_ALLOW_DUMMY_SERVICES=1

Configuration example with Docker Compose

services:
  api:
    environment:
      - EVOSPIKENET_ALLOW_STUBS=0
      - EVOSPIKENET_DATA_STRICT_REAL=1
      - EVOSPIKENET_FAIL_ON_COMM_FALLBACK=1
      - EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=0
      - EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=0
      - EVOSPIKENET_ALLOW_DUMMY_SERVICES=0
  • Before production deployment:
  • Check that EVOSPIKENET_ALLOW_STUBS is 0
  • Check that EVOSPIKENET_DATA_STRICT_REAL is 1
  • Check that EVOSPIKENET_FAIL_ON_COMM_FALLBACK is 1
  • Check that EVOSPIKENET_ALLOW_COMPAT_FALLBACKS is 0
  • Check that EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS is 0
  • Check that EVOSPIKENET_ALLOW_DUMMY_SERVICES is 0
  • Run smoke tests to ensure successful connections to external dependencies (DB, API, CARLA, etc.)
  • future_apps/smart_city_infrastructure/src/urban_data_api.py — Uses EVOSPIKENET_DATA_STRICT_REAL
  • future_apps/climate_change_prediction/src/climate_data_api.py — Uses EVOSPIKENET_DATA_STRICT_REAL
  • future_apps/brain_machine_interface/src/services/distributed_connector.py — Uses EVOSPIKENET_ALLOW_STUBS (allow in-memory stub)
  • EvoSpikeNet-Core/evospikenet/communication.py — Uses EVOSPIKENET_FAIL_ON_COMM_FALLBACK
  • EvoSpikeNet-Core/evospikenet/api_modules/future_apps_compat_api.py — Uses EVOSPIKENET_ALLOW_COMPAT_FALLBACKS
  • EvoSpikeNet-Core/evospikenet/video_scene_service.py — Uses EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS
  • EvoSpikeNet-Core/evospikenet/services/__init__.py — Uses EVOSPIKENET_ALLOW_DUMMY_SERVICES

Audit method

  • See how settings are used across repositories:
grep -R "EVOSPIKENET_ALLOW_STUBS\|EVOSPIKENET_ALLOW_ROS_STUBS\|EVOSPIKENET_DATA_STRICT_REAL\|EVOSPIKENET_FAIL_ON_COMM_FALLBACK\|EVOSPIKENET_ALLOW_COMPAT_FALLBACKS\|EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS\|EVOSPIKENET_ALLOW_DUMMY_SERVICES\|VIDEO_ANALYSIS_FAIL_CLOSED\|EVOSPIKENET_PTP_DEVICE\|EVOSPIKENET_PTP_NTP_SAMPLES\|EVOSPIKENET_MTLS_REQUIRED\|EVOSPIKENET_ALLOWED_CERTS\|EVOSPIKENET_ALLOWED_CERT_FINGERPRINTS\|EVOSPIKENET_ALERT_SLACK_WEBHOOK_URL\|EVOSPIKENET_ALERT_SMTP_HOST\|EVOSPIKENET_ALERT_SMTP_USER\|EVOSPIKENET_ALERT_SMTP_PASS\|EVOSPIKENET_ALERT_EMAIL_TO\|EVOSPIKENET_ALERT_PAGERDUTY_ROUTING_KEY" -n || true

In closing: This policy is a minimum guideline to improve security and operational health. Tailor it to your organization's operational rules and CI/CD policies.