Type: explanation
Pulse is an industrial data platform. It ships as two products that share one data backbone:
clarity repo (Rust: Tauri + Warp).pulse_multi_agents repo (Python).Both products deploy edge/on-prem by default (air-gap capable). Pulse Copilot can also run as a managed cloud service pointed at an on-prem historian.
| Product | edge/on-prem | managed cloud |
|---|---|---|
| Pulse Historian | ✅ default | — |
| Pulse Copilot | ✅ bundled into the historian install | ✅ Docker/K8s service |
Where code behavior depends on whether — and where — the AI service runs, the dev docs use these topology names. They replace the retired [mode: historian | standalone | cloud-copilot] tags:
| Topology | (was) | What runs |
|---|---|---|
| Historian-only | [mode: historian] |
clarity binary; no AI service |
| AI bundled (edge) | [mode: standalone] |
clarity + pulse_multi_agents in one on-prem/edge install |
| AI separate (cloud) | [mode: cloud-copilot] |
pulse_multi_agents as a managed-cloud service against an on-prem clarity |
clarity (clarity:backend/src-tauri/src/) — the Pulse Historian binary
/api/admin/backup//elog/clarity.local for LAN discoverypulse_multi_agents (pulse_multi_agents/) — the Clarity AI engine behind Pulse Copilot
pulse_manager root orchestrator agent + 6 specialized sub-agentsSDKs (clarity repo)
SDK/python/clarity_sdk.py: Python ClarityDecoder + ClarityClientSDK/javascript/clarity-sdk.js: Browser/Node.js OptimizedClarityClientConnector (PI / MQTT) or HTTP client
→ POST /exactapi/write | /exactapi/write_fast | /exactapi/write_buffered
→ scope resolution: TAG_SCOPE_MAP (tagname→org/site/unit/grid) or explicit 4-tuple
→ Storage::store_data / store_data_mmap
→ binary mmap files in data/{org}/{site}/{unit}/{grid}/ (sealed days: zstd .bin.czst cold tier)
An hourly cold-tier sealer compresses day-files older than clarity.storage.seal.hot_days (default 0 — everything before today) into .bin.czst; reads fall back to a decompressing reader, writes unseal-then-reseal. See Storage Engine § Cold-tier compression.
Three write modes:
/exactapi/write): fsync on each batch, general-purpose/exactapi/write_fast): mmap, no fsync, target <100ms for 100k+ tags/exactapi/write_buffered): lock-free queue, 50ms flush interval, 200k capacity (config-driven), target <1ms per requestClient (browser / SDK / agent)
→ POST /exactapi/fast_query → JSON response
| POST /exactapi/fast_query_binary → binary format v1 (per-tag timestamps)
| POST /exactapi/fast_query_optimised → binary format v2 (shared timestamps + validity bitmaps)
→ QueryEngine: thread-safe mmap reads via DashMap column cache
→ optional AggregationPipeline (Mean/Sum/Min/Max/Count/Percentile/Histogram/LeastSquares/Rate/Scale/Score/filter)
Measured performance (field benchmark): a full 50,000 tags @ 1 Hz sustained with 0 dropped points on both an 8-core workstation and a 4-core cloud VM; bulk backfill reached 1.0–1.66 M points/s; everyday multi-tag reads return in tens-to-hundreds of ms. See Benchmarks.
Browser → POST /run_sse (SSE stream, Google ADK)
→ pulse_manager orchestrator
→ meta_data_agent → GET /exactapi/fast_query on the historian → CSV on disk
→ data_analysis_agent → RestrictedPython sandbox → statistical analysis
→ incident_agent → historian SQLite incidents → diagnostic summary
→ system_health_agent → open incident detection by unit+system
→ dashboard_creation_agent → section definitions + viz type recommendations
→ question_agent → operator diagnostic questions
→ streaming SSE tokens to browser
Every time-series collection is addressed by a 4-tuple: organization / site / unit / grid.
The TAG_SCOPE_MAP (clarity:backend/src-tauri/src/api/tag_resolver.rs) is a lazy-static in-memory map built at startup from the directory structure under data/. It maps tag names to their Arc<Scope>. When org/site/unit/grid are omitted from a write or query, tags are resolved through this map. The map is rebuilt after every create_collection or write_tag_mapping call, and warm-updated when tag metadata syncs.
Authorization: Bearer <JWT> (HS256). Documented exceptions (ADK proxy, /mqtt bridge, backup admin routes) are listed in the Security Model./login, valid 24h (or never-expires flag for service accounts)sub (email), role (admin/read-write/read-only), units_id, sites_id, orgs_idclarity Tauri binary on-premise (Windows primary, macOS supported); no AI serviceclarity.local for LAN accessHA_ENABLED=true activates active-passive replication with peer TCP on port 3031 and VIP failoverpapa_agent_app (PyInstaller agent binary) bundled in Tauri Assetslocalhost:8000pulse_multi_agents Docker image pushed to private registrySources: clarity@6800acc · pulse_multi_agents@1e67443
Last updated: 2026-07-17 from clarity@6800acc + pulse_multi_agents@1e67443