toposync-core 0.7.2__tar.gz → 0.7.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. toposync_core-0.7.3/PKG-INFO +313 -0
  2. toposync_core-0.7.3/README.md +298 -0
  3. toposync_core-0.7.3/frontend/dist/156.js +2 -0
  4. toposync_core-0.7.3/frontend/dist/156.js.map +1 -0
  5. {toposync_core-0.7.2 → toposync_core-0.7.3}/pyproject.toml +3 -3
  6. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/__init__.py +1 -1
  7. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/app.py +7 -3
  8. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/notifications/runtime.py +22 -1
  9. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/notifications/store.py +73 -2
  10. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/recommendations.py +1 -1
  11. toposync_core-0.7.2/PKG-INFO +0 -45
  12. toposync_core-0.7.2/frontend/dist/156.js +0 -2
  13. toposync_core-0.7.2/frontend/dist/156.js.map +0 -1
  14. toposync_core-0.7.2/readme.md +0 -30
  15. {toposync_core-0.7.2 → toposync_core-0.7.3}/.gitignore +0 -0
  16. {toposync_core-0.7.2 → toposync_core-0.7.3}/LICENSE +0 -0
  17. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/2463b90d9a316e4e5294.woff2 +0 -0
  18. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/2582b0e4bcf85eceead0.ttf +0 -0
  19. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/277.js +0 -0
  20. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/277.js.LICENSE.txt +0 -0
  21. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/277.js.map +0 -0
  22. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/325.js +0 -0
  23. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/325.js.LICENSE.txt +0 -0
  24. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/325.js.map +0 -0
  25. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/451.js +0 -0
  26. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/451.js.LICENSE.txt +0 -0
  27. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/451.js.map +0 -0
  28. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/666.js +0 -0
  29. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/666.js.map +0 -0
  30. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/696.js +0 -0
  31. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/696.js.LICENSE.txt +0 -0
  32. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/696.js.map +0 -0
  33. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/771.js +0 -0
  34. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/771.js.map +0 -0
  35. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/favicon.png +0 -0
  36. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/index.html +0 -0
  37. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/main.js +0 -0
  38. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/main.js.map +0 -0
  39. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/toposync-icon-1024.png +0 -0
  40. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/toposync-icon-256.png +0 -0
  41. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/toposync-icon-512.png +0 -0
  42. {toposync_core-0.7.2 → toposync_core-0.7.3}/frontend/dist/toposync-symbol.svg +0 -0
  43. {toposync_core-0.7.2 → toposync_core-0.7.3}/hatch_build.py +0 -0
  44. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/__main__.py +0 -0
  45. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/cli.py +0 -0
  46. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/extensions/__init__.py +0 -0
  47. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/extensions/base.py +0 -0
  48. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/extensions/manager.py +0 -0
  49. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/extensions/manifest.py +0 -0
  50. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/processing_server.py +0 -0
  51. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/__init__.py +0 -0
  52. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/auth.py +0 -0
  53. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/config_store.py +0 -0
  54. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/device_store.py +0 -0
  55. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/event_bus.py +0 -0
  56. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/extension_management.py +0 -0
  57. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/notifications/__init__.py +0 -0
  58. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/notifications/events.py +0 -0
  59. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/__init__.py +0 -0
  60. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/builtins.py +0 -0
  61. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/compiler.py +0 -0
  62. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/distributed/__init__.py +0 -0
  63. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/distributed/orchestrator.py +0 -0
  64. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/distributed/plan.py +0 -0
  65. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/distributed/processing_server.py +0 -0
  66. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/distributed/transport.py +0 -0
  67. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/execution.py +0 -0
  68. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/execution_scheduler.py +0 -0
  69. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/images.py +0 -0
  70. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/migration_legacy_cameras.py +0 -0
  71. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/observability.py +0 -0
  72. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/operator_registry.py +0 -0
  73. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/operators_core.py +0 -0
  74. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/operators_distributed.py +0 -0
  75. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/operators_gates.py +0 -0
  76. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/operators_sinks.py +0 -0
  77. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/packet_contract.py +0 -0
  78. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/preview.py +0 -0
  79. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/python_dsl.py +0 -0
  80. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/runtime.py +0 -0
  81. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/safe_expression.py +0 -0
  82. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/shared_runtime.py +0 -0
  83. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/stats.py +0 -0
  84. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/step_snapshots.py +0 -0
  85. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/storage.py +0 -0
  86. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/telemetry.py +0 -0
  87. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/pipelines/templates.py +0 -0
  88. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/processing_diagnostics.py +0 -0
  89. {toposync_core-0.7.2 → toposync_core-0.7.3}/src/toposync/runtime/services.py +0 -0
toposync_core-0.7.3/PKG-INFO ADDED
@@ -0,0 +1,313 @@
1
+ Metadata-Version: 2.4
2
+ Name: toposync-core
3
+ Version: 0.7.3
4
+ Summary: Toposync core runtime (Python backend + extension host).
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: fastapi>=0.115
9
+ Requires-Dist: packaging>=24.0
10
+ Requires-Dist: pillow<13,>=10
11
+ Requires-Dist: pydantic>=2.8
12
+ Requires-Dist: python-multipart>=0.0.9
13
+ Requires-Dist: uvicorn>=0.30
14
+ Description-Content-Type: text/markdown
15
+
16
+ <p align="center">
17
+ <img src="frontend/src/assets/toposync-symbol.svg" alt="Toposync" width="96" />
18
+ </p>
19
+
20
+ # Toposync
21
+
22
+ [Português (Brasil)](README.pt-BR.md)
23
+
24
+ **Toposync** is an **alpha-stage, local-first platform** for spatial home automation, camera intelligence, and 2D/3D home visualization, optionally integrated with Home Assistant.
25
+
26
+ The goal is to turn a smart home into a visual and interpretable environment: cameras, areas, devices, automations, notifications, and events can exist inside a 2D/3D map of the home.
27
+
28
+ Toposync is not meant to be just another camera dashboard, and not just another automation panel. The goal is to create a local spatial layer where you can answer questions such as:
29
+
30
+ - what happened?
31
+ - where did it happen?
32
+ - which camera saw it?
33
+ - which area of the home was affected?
34
+ - which automation should react?
35
+ - which history is worth keeping?
36
+
37
+ > Toposync is currently in **alpha early access**. It can already be tested by early adopters, advanced home automation users, Home Assistant users, IP camera users, RTSP/ONVIF users, homelab enthusiasts, and people interested in local computer vision.
38
+
39
+ > **Important notice:** Toposync can provide additional layers of visualization, automation, and situational awareness, but it does **not** replace certified security systems, dedicated sensors, human supervision, or protective equipment. Do not rely on it yet for safety-critical automation, unattended security monitoring, emergency workflows, access control, or any automation where failure could cause harm, property damage, privacy exposure, or loss of essential service.
40
+
41
+ ## Alpha early access
42
+
43
+ This stage is primarily about **bug hunting, integration validation, and real-world testing**.
44
+
45
+ There are many possible combinations of cameras, devices, brands, protocols, networks, GPUs, operating systems, Home Assistant installations, browsers, apps, and streaming modes. Community testing is essential to validate all of this.
46
+
47
+ You can help by:
48
+
49
+ - testing Toposync in different contained environments, while following the safety guidance in [SECURITY.md](SECURITY.md);
50
+ - opening issues for bugs you find;
51
+ - sharing sanitized logs, camera models, protocols, and usage scenarios;
52
+ - suggesting UX, documentation, and installation improvements;
53
+ - validating Home Assistant, RTSP, ONVIF, PTZ, streaming, and hardware integrations;
54
+ - contributing code, documentation, pipelines, and examples;
55
+ - preparing future third-party extensions;
56
+ - supporting development through [GitHub Sponsors](https://github.com/sponsors/mateuscalza).
57
+
58
+ > **Security issues:** do not publish vulnerability details in public issues. Follow [SECURITY.md](SECURITY.md) and use private GitHub vulnerability reporting or a private GitHub Security Advisory when available.
59
+
60
+ ## What can you build with Toposync?
61
+
62
+ | Use case | What it enables | Status |
63
+ | --- | --- | --- |
64
+ | **2D/3D home view** | Visualize your home, rooms, areas, devices, cameras, and entities in a spatial model. | **Ready for testing** |
65
+ | **Visual home automation** | See lights, cameras, sensors, and devices inside the home representation, with visual states such as active lights, selected entities, or active items. | **Ready for testing** |
66
+ | **Events on the map** | Turn camera detections into events positioned in real areas of the home. Instead of only knowing that something was detected, see where it happened. | **Ready for testing** |
67
+ | **Real-world tracking** | Track objects, people, or events over time and associate their paths with areas of the home. | **Ready for testing** |
68
+ | **Front-of-house awareness** | Detect people, vehicles, or deliveries stopped near the gate, driveway, sidewalk, or entrance. | **Ready for testing** |
69
+ | **Relevant stopped objects** | Create rules for things that actually stopped in an area, instead of reacting to every fast movement. | **Ready for testing** |
70
+ | **Sensitive areas** | Add an extra awareness layer around places such as pools, gates, garages, backyards, or restricted areas. | **Ready for testing** |
71
+ | **Pets near sensitive areas** | Combine detection, areas, and notifications to notice relevant situations involving pets near places such as pools, streets, or gates. | **Ready for testing** |
72
+ | **Spatial 360 view** | Project camera images into the 2D/3D model, creating a visualization inspired by car 360 camera systems. | **Early experiment** |
73
+ | **Multi-brand cameras** | Bring RTSP/ONVIF cameras from different brands into a single local interface. | **Ready for testing** |
74
+ | **Centralized local AI** | Run models and pipelines on a local machine such as a mini PC, server, NAS, or GPU desktop. | **Ready for testing** |
75
+ | **Idle hardware as an AI server** | Use an existing machine to process cameras and automations when it is available. | **Ready for testing** |
76
+ | **Common cameras with local intelligence** | Use simple cameras as image sources and concentrate intelligence in a more flexible local platform. | **Ready for testing** |
77
+ | **Detection beyond the camera** | Use more advanced models and pipelines than the built-in AI of each camera, including distant objects or specific visual conditions. | **Ready for testing, advanced** |
78
+ | **Local AI pipelines** | Combine camera input, detection, tracking, filters, areas, notifications, and actions in customizable flows. | **Ready for testing** |
79
+ | **Rules by area** | The same detection can mean different things depending on the area. A person on the sidewalk may be normal; the same person in the backyard at another time may trigger an alert. | **Ready for testing** |
80
+ | **Context-aware notifications** | Receive notifications with location, event type, area, associated image, and object state. | **Ready for testing** |
81
+ | **Deliveries and doorbells** | Detect delivery people, packages, or people near the entrance, even before someone rings the doorbell. | **Ready for testing** |
82
+ | **Rich timelines** | Store interpreted events with time, area, object, image, and context, making it easier to find occurrences without watching hours of video. | **Ready for testing** |
83
+ | **Event-based history** | Store events, captures, crops, and metadata instead of relying only on continuous recording. | **Ready for testing** |
84
+ | **More efficient long-term history** | Because events can store relevant images, crops, and metadata, useful history can be kept for longer while using less storage. | **Ready for testing** |
85
+ | **Contextual control** | When viewing a camera, stream, or area, access related devices such as lights, gates, locks, sirens, outlets, or entities. | **Ready for testing** |
86
+ | **Spatial smart lighting** | Use event positions to trigger nearby lights, create path-based automations, or visualize which areas are lit in 3D. | **Ready for testing** |
87
+ | **Optional Home Assistant integration** | Use Toposync independently, or integrate it with Home Assistant to visualize entities, states, automations, and devices in the home space. | **Ready for testing** |
88
+ | **Home Assistant as an output** | Turn visual events into Home Assistant notifications, states, binary sensors, and automations. | **Ready for testing** |
89
+ | **ONVIF, RTSP, and PTZ** | Discover cameras, test connections, capture snapshots, use RTSP sources, and control PTZ cameras when supported. | **Ready for testing** |
90
+ | **Local streaming** | Publish streams for dashboards, browsers, integrations, and local use while keeping the logic inside your own environment. | **Ready for testing, optional** |
91
+ | **Picture-in-Picture and TV** | Bring streams and events into an app/TV experience designed with Picture-in-Picture in mind. | **Coming soon** |
92
+ | **Android and iOS app** | Access the 3D map, streams, notifications, and settings on mobile devices. | **Coming soon** |
93
+ | **Android TV and Apple TV** | Use streams, events, and visualizations on large screens, focused on home monitoring. | **Coming soon** |
94
+ | **Custom models** | Test custom models to detect objects, situations, or patterns specific to your environment. | **Ready for testing, advanced** |
95
+ | **Segmentation and smart crops** | Use AI to filter, crop, or highlight relevant objects and regions in an image. | **Ready for testing, advanced** |
96
+ | **Distributed compute** | Run heavy processing on another machine in the network, separating the main instance from the AI workload. | **Ready for testing, advanced** |
97
+ | **Local-first privacy** | Run on your own infrastructure without depending on cloud processing for images from your home. | **Ready for testing** |
98
+ | **Extensions and experimentation** | Toposync is designed as an extensible platform for new integrations, 3D elements, pipelines, models, and ways to visualize the home. | **Ready for testing, advanced** |
99
+ | **Third-party extensions** | The architecture opens the door for community extensions with their own backend and UI. | **In preparation** |
100
+
101
+ ## Who is this alpha for?
102
+
103
+ Toposync is not yet a polished end-user solution with a frictionless setup. At this stage, it is best suited for:
104
+
105
+ - advanced Home Assistant users;
106
+ - people already using IP cameras, RTSP, or ONVIF;
107
+ - homelab enthusiasts;
108
+ - home automation makers;
109
+ - developers interested in local computer vision;
110
+ - home automation content creators;
111
+ - small integrators who want to test new ideas;
112
+ - people comfortable with alpha software and technical troubleshooting.
113
+
114
+ If you enjoy testing early, opening issues, validating real hardware, and helping shape an open source platform, this is the right time to participate.
115
+
116
+ ## Installation
117
+
118
+ Toposync supports multiple installation paths depending on the environment:
119
+
120
+ - Home Assistant add-on;
121
+ - Docker/self-hosting;
122
+ - Python/uv installation;
123
+ - processing servers;
124
+ - development environment;
125
+ - mobile/TV app in a future release.
126
+
127
+ For a direct Python install, Python 3.12 is recommended:
128
+
129
+ ```bash
130
+ uv venv .venv --python 3.12
131
+ source .venv/bin/activate
132
+ uv pip install toposync
133
+ toposync serve
134
+ ```
135
+
136
+ Open:
137
+
138
+ ```text
139
+ http://127.0.0.1:8000/
140
+ ```
141
+
142
+ On Windows PowerShell:
143
+
144
+ ```powershell
145
+ uv venv .venv --python 3.12
146
+ .venv\Scripts\Activate.ps1
147
+ uv pip install toposync
148
+ toposync serve
149
+ ```
150
+
151
+ Optional upgrades:
152
+
153
+ ```bash
154
+ uv pip install toposync-streaming
155
+ uv pip install toposync-vision-cuda
156
+ uv pip install toposync-vision-directml
157
+ ```
158
+
159
+ Use CUDA for NVIDIA hosts and DirectML for Windows GPU acceleration. Streaming is optional because it brings additional media-runtime requirements.
160
+
161
+ Start with the installation guides:
162
+
163
+ - [Choose your installation](docs-site/docs/installation/choose-your-installation.mdx)
164
+ - [Python on Linux and macOS](docs-site/docs/installation/python-linux-macos.mdx)
165
+ - [Python on Windows](docs-site/docs/installation/python-windows.mdx)
166
+ - [Docker CPU](docs-site/docs/installation/docker-cpu.mdx)
167
+ - [Docker CUDA](docs-site/docs/installation/docker-cuda.mdx)
168
+ - [Home Assistant add-on](docs-site/docs/installation/home-assistant-addon.mdx)
169
+ - [Processing servers](docs-site/docs/installation/processing-server-linux-macos.mdx)
170
+ - [Compatibility](docs-site/docs/installation/architecture-support.mdx)
171
+
172
+ ## Home Assistant
173
+
174
+ Toposync can run as a Home Assistant add-on with sidebar ingress, supervised execution, direct-port access when enabled, and internal access to the Home Assistant Core API.
175
+
176
+ Use the dedicated add-on repository:
177
+
178
+ ```text
179
+ https://github.com/toposync/toposync-homeassistant-addon
180
+ ```
181
+
182
+ Start with [Home Assistant add-on installation](docs-site/docs/installation/home-assistant-addon.mdx). For Raspberry Pi and HAOS, treat the add-on as a lightweight origin server and delegate heavy vision or multi-camera processing to a processing server when needed.
183
+
184
+ ## Development
185
+
186
+ Prerequisites:
187
+
188
+ - Python 3.12;
189
+ - `uv`;
190
+ - Node 20 or newer;
191
+ - npm.
192
+
193
+ From the repository root:
194
+
195
+ ```bash
196
+ uv sync
197
+ npm install
198
+ npm run build:extensions
199
+ TOPOSYNC_AUTH_MODE=bypass npm run dev
200
+ ```
201
+
202
+ Open:
203
+
204
+ ```text
205
+ http://127.0.0.1:5173/
206
+ ```
207
+
208
+ The default development data directory is `.toposync-data`.
209
+
210
+ See [Development setup](docs-site/docs/developers/development-setup.mdx) for the full local workflow.
211
+
212
+ ## Repository map
213
+
214
+ - `src/toposync`: core backend, API, extension manager, pipeline runtime, processing server.
215
+ - `frontend`: React/ThreeJS frontend host.
216
+ - `packages/plugin-api`: public TypeScript contract for frontend extensions.
217
+ - `packages/toposync`: default Python product bundle.
218
+ - `packages/toposync-streaming`: streaming bundle.
219
+ - `packages/toposync-vision-cuda`: NVIDIA CUDA upgrade bundle.
220
+ - `packages/toposync-vision-directml`: Windows DirectML upgrade bundle.
221
+ - `extensions`: first-party extension packages.
222
+ - `docs-site`: Docusaurus documentation site.
223
+ - `integrations/home_assistant`: Home Assistant integration and add-on related assets.
224
+ - `scripts`: distribution, validation, and service helper scripts.
225
+
226
+ ## Documentation
227
+
228
+ Documentation lives in `docs-site`.
229
+
230
+ Useful starting points:
231
+
232
+ - [Installation](docs-site/docs/installation/choose-your-installation.mdx)
233
+ - [Compatibility](docs-site/docs/installation/architecture-support.mdx)
234
+ - [Architecture](docs-site/docs/developers/architecture.mdx)
235
+ - [Extension authoring](docs-site/docs/developers/extension-authoring.mdx)
236
+ - [Plugin API](docs-site/docs/developers/plugin-api.mdx)
237
+ - [Pipelines](docs-site/docs/developers/pipelines.mdx)
238
+ - [Visual identity](docs-site/docs/developers/visual-identity.mdx)
239
+ - [Release process](docs-site/docs/developers/release-process.mdx)
240
+
241
+ Build the documentation site locally:
242
+
243
+ ```bash
244
+ npm run docs:start
245
+ npm run docs:build
246
+ ```
247
+
248
+ ## How to contribute
249
+
250
+ Contributions are welcome, especially during the alpha.
251
+
252
+ You can help with:
253
+
254
+ - bug reports;
255
+ - tests with different cameras and hardware;
256
+ - validation of RTSP, ONVIF, PTZ, and streaming;
257
+ - documentation improvements;
258
+ - UX suggestions;
259
+ - pipeline examples;
260
+ - code fixes;
261
+ - future extensions;
262
+ - translations;
263
+ - responsible sharing with the home automation community.
264
+
265
+ When opening an issue, try to include:
266
+
267
+ - operating system;
268
+ - installation method;
269
+ - camera or device model, when applicable;
270
+ - relevant logs;
271
+ - screenshots or short videos, when useful;
272
+ - steps to reproduce;
273
+ - expected behavior and observed behavior.
274
+
275
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
276
+
277
+ For security vulnerabilities, do not use public issues. See [SECURITY.md](SECURITY.md).
278
+
279
+ ## Support the project
280
+
281
+ Toposync is an early-stage open source project, with no mandatory cloud and no active commercial product at this moment. Development involves backend, frontend, computer vision, streaming, apps, Home Assistant, documentation, testing, and support for many different environments.
282
+
283
+ If you want to support development:
284
+
285
+ - test and share feedback;
286
+ - contribute code or documentation;
287
+ - share it with people who care about local home automation;
288
+ - support the maintainer through [GitHub Sponsors](https://github.com/sponsors/mateuscalza).
289
+
290
+ ## Project status
291
+
292
+ Toposync is in **alpha early access**.
293
+
294
+ This means:
295
+
296
+ - some parts already work and can be tested;
297
+ - some features are advanced and require manual configuration;
298
+ - some areas are still experimental;
299
+ - the mobile/TV app will be released soon;
300
+ - installation and documentation are still being organized;
301
+ - bugs are expected;
302
+ - community feedback is essential.
303
+
304
+ Use it, test it, break it, report it, and help improve it.
305
+
306
+ ## Support and security
307
+
308
+ - Community support: [SUPPORT.md](SUPPORT.md)
309
+ - Security policy: [SECURITY.md](SECURITY.md)
310
+
311
+ ## License
312
+
313
+ Toposync is released under the [MIT License](LICENSE).
toposync_core-0.7.3/README.md ADDED
@@ -0,0 +1,298 @@
1
+ <p align="center">
2
+ <img src="frontend/src/assets/toposync-symbol.svg" alt="Toposync" width="96" />
3
+ </p>
4
+
5
+ # Toposync
6
+
7
+ [Português (Brasil)](README.pt-BR.md)
8
+
9
+ **Toposync** is an **alpha-stage, local-first platform** for spatial home automation, camera intelligence, and 2D/3D home visualization, optionally integrated with Home Assistant.
10
+
11
+ The goal is to turn a smart home into a visual and interpretable environment: cameras, areas, devices, automations, notifications, and events can exist inside a 2D/3D map of the home.
12
+
13
+ Toposync is not meant to be just another camera dashboard, and not just another automation panel. The goal is to create a local spatial layer where you can answer questions such as:
14
+
15
+ - what happened?
16
+ - where did it happen?
17
+ - which camera saw it?
18
+ - which area of the home was affected?
19
+ - which automation should react?
20
+ - which history is worth keeping?
21
+
22
+ > Toposync is currently in **alpha early access**. It can already be tested by early adopters, advanced home automation users, Home Assistant users, IP camera users, RTSP/ONVIF users, homelab enthusiasts, and people interested in local computer vision.
23
+
24
+ > **Important notice:** Toposync can provide additional layers of visualization, automation, and situational awareness, but it does **not** replace certified security systems, dedicated sensors, human supervision, or protective equipment. Do not rely on it yet for safety-critical automation, unattended security monitoring, emergency workflows, access control, or any automation where failure could cause harm, property damage, privacy exposure, or loss of essential service.
25
+
26
+ ## Alpha early access
27
+
28
+ This stage is primarily about **bug hunting, integration validation, and real-world testing**.
29
+
30
+ There are many possible combinations of cameras, devices, brands, protocols, networks, GPUs, operating systems, Home Assistant installations, browsers, apps, and streaming modes. Community testing is essential to validate all of this.
31
+
32
+ You can help by:
33
+
34
+ - testing Toposync in different contained environments, while following the safety guidance in [SECURITY.md](SECURITY.md);
35
+ - opening issues for bugs you find;
36
+ - sharing sanitized logs, camera models, protocols, and usage scenarios;
37
+ - suggesting UX, documentation, and installation improvements;
38
+ - validating Home Assistant, RTSP, ONVIF, PTZ, streaming, and hardware integrations;
39
+ - contributing code, documentation, pipelines, and examples;
40
+ - preparing future third-party extensions;
41
+ - supporting development through [GitHub Sponsors](https://github.com/sponsors/mateuscalza).
42
+
43
+ > **Security issues:** do not publish vulnerability details in public issues. Follow [SECURITY.md](SECURITY.md) and use private GitHub vulnerability reporting or a private GitHub Security Advisory when available.
44
+
45
+ ## What can you build with Toposync?
46
+
47
+ | Use case | What it enables | Status |
48
+ | --- | --- | --- |
49
+ | **2D/3D home view** | Visualize your home, rooms, areas, devices, cameras, and entities in a spatial model. | **Ready for testing** |
50
+ | **Visual home automation** | See lights, cameras, sensors, and devices inside the home representation, with visual states such as active lights, selected entities, or active items. | **Ready for testing** |
51
+ | **Events on the map** | Turn camera detections into events positioned in real areas of the home. Instead of only knowing that something was detected, see where it happened. | **Ready for testing** |
52
+ | **Real-world tracking** | Track objects, people, or events over time and associate their paths with areas of the home. | **Ready for testing** |
53
+ | **Front-of-house awareness** | Detect people, vehicles, or deliveries stopped near the gate, driveway, sidewalk, or entrance. | **Ready for testing** |
54
+ | **Relevant stopped objects** | Create rules for things that actually stopped in an area, instead of reacting to every fast movement. | **Ready for testing** |
55
+ | **Sensitive areas** | Add an extra awareness layer around places such as pools, gates, garages, backyards, or restricted areas. | **Ready for testing** |
56
+ | **Pets near sensitive areas** | Combine detection, areas, and notifications to notice relevant situations involving pets near places such as pools, streets, or gates. | **Ready for testing** |
57
+ | **Spatial 360 view** | Project camera images into the 2D/3D model, creating a visualization inspired by car 360 camera systems. | **Early experiment** |
58
+ | **Multi-brand cameras** | Bring RTSP/ONVIF cameras from different brands into a single local interface. | **Ready for testing** |
59
+ | **Centralized local AI** | Run models and pipelines on a local machine such as a mini PC, server, NAS, or GPU desktop. | **Ready for testing** |
60
+ | **Idle hardware as an AI server** | Use an existing machine to process cameras and automations when it is available. | **Ready for testing** |
61
+ | **Common cameras with local intelligence** | Use simple cameras as image sources and concentrate intelligence in a more flexible local platform. | **Ready for testing** |
62
+ | **Detection beyond the camera** | Use more advanced models and pipelines than the built-in AI of each camera, including distant objects or specific visual conditions. | **Ready for testing, advanced** |
63
+ | **Local AI pipelines** | Combine camera input, detection, tracking, filters, areas, notifications, and actions in customizable flows. | **Ready for testing** |
64
+ | **Rules by area** | The same detection can mean different things depending on the area. A person on the sidewalk may be normal; the same person in the backyard at another time may trigger an alert. | **Ready for testing** |
65
+ | **Context-aware notifications** | Receive notifications with location, event type, area, associated image, and object state. | **Ready for testing** |
66
+ | **Deliveries and doorbells** | Detect delivery people, packages, or people near the entrance, even before someone rings the doorbell. | **Ready for testing** |
67
+ | **Rich timelines** | Store interpreted events with time, area, object, image, and context, making it easier to find occurrences without watching hours of video. | **Ready for testing** |
68
+ | **Event-based history** | Store events, captures, crops, and metadata instead of relying only on continuous recording. | **Ready for testing** |
69
+ | **More efficient long-term history** | Because events can store relevant images, crops, and metadata, useful history can be kept for longer while using less storage. | **Ready for testing** |
70
+ | **Contextual control** | When viewing a camera, stream, or area, access related devices such as lights, gates, locks, sirens, outlets, or entities. | **Ready for testing** |
71
+ | **Spatial smart lighting** | Use event positions to trigger nearby lights, create path-based automations, or visualize which areas are lit in 3D. | **Ready for testing** |
72
+ | **Optional Home Assistant integration** | Use Toposync independently, or integrate it with Home Assistant to visualize entities, states, automations, and devices in the home space. | **Ready for testing** |
73
+ | **Home Assistant as an output** | Turn visual events into Home Assistant notifications, states, binary sensors, and automations. | **Ready for testing** |
74
+ | **ONVIF, RTSP, and PTZ** | Discover cameras, test connections, capture snapshots, use RTSP sources, and control PTZ cameras when supported. | **Ready for testing** |
75
+ | **Local streaming** | Publish streams for dashboards, browsers, integrations, and local use while keeping the logic inside your own environment. | **Ready for testing, optional** |
76
+ | **Picture-in-Picture and TV** | Bring streams and events into an app/TV experience designed with Picture-in-Picture in mind. | **Coming soon** |
77
+ | **Android and iOS app** | Access the 3D map, streams, notifications, and settings on mobile devices. | **Coming soon** |
78
+ | **Android TV and Apple TV** | Use streams, events, and visualizations on large screens, focused on home monitoring. | **Coming soon** |
79
+ | **Custom models** | Test custom models to detect objects, situations, or patterns specific to your environment. | **Ready for testing, advanced** |
80
+ | **Segmentation and smart crops** | Use AI to filter, crop, or highlight relevant objects and regions in an image. | **Ready for testing, advanced** |
81
+ | **Distributed compute** | Run heavy processing on another machine in the network, separating the main instance from the AI workload. | **Ready for testing, advanced** |
82
+ | **Local-first privacy** | Run on your own infrastructure without depending on cloud processing for images from your home. | **Ready for testing** |
83
+ | **Extensions and experimentation** | Toposync is designed as an extensible platform for new integrations, 3D elements, pipelines, models, and ways to visualize the home. | **Ready for testing, advanced** |
84
+ | **Third-party extensions** | The architecture opens the door for community extensions with their own backend and UI. | **In preparation** |
85
+
86
+ ## Who is this alpha for?
87
+
88
+ Toposync is not yet a polished end-user solution with a frictionless setup. At this stage, it is best suited for:
89
+
90
+ - advanced Home Assistant users;
91
+ - people already using IP cameras, RTSP, or ONVIF;
92
+ - homelab enthusiasts;
93
+ - home automation makers;
94
+ - developers interested in local computer vision;
95
+ - home automation content creators;
96
+ - small integrators who want to test new ideas;
97
+ - people comfortable with alpha software and technical troubleshooting.
98
+
99
+ If you enjoy testing early, opening issues, validating real hardware, and helping shape an open source platform, this is the right time to participate.
100
+
101
+ ## Installation
102
+
103
+ Toposync supports multiple installation paths depending on the environment:
104
+
105
+ - Home Assistant add-on;
106
+ - Docker/self-hosting;
107
+ - Python/uv installation;
108
+ - processing servers;
109
+ - development environment;
110
+ - mobile/TV app in a future release.
111
+
112
+ For a direct Python install, Python 3.12 is recommended:
113
+
114
+ ```bash
115
+ uv venv .venv --python 3.12
116
+ source .venv/bin/activate
117
+ uv pip install toposync
118
+ toposync serve
119
+ ```
120
+
121
+ Open:
122
+
123
+ ```text
124
+ http://127.0.0.1:8000/
125
+ ```
126
+
127
+ On Windows PowerShell:
128
+
129
+ ```powershell
130
+ uv venv .venv --python 3.12
131
+ .venv\Scripts\Activate.ps1
132
+ uv pip install toposync
133
+ toposync serve
134
+ ```
135
+
136
+ Optional upgrades:
137
+
138
+ ```bash
139
+ uv pip install toposync-streaming
140
+ uv pip install toposync-vision-cuda
141
+ uv pip install toposync-vision-directml
142
+ ```
143
+
144
+ Use CUDA for NVIDIA hosts and DirectML for Windows GPU acceleration. Streaming is optional because it brings additional media-runtime requirements.
145
+
146
+ Start with the installation guides:
147
+
148
+ - [Choose your installation](docs-site/docs/installation/choose-your-installation.mdx)
149
+ - [Python on Linux and macOS](docs-site/docs/installation/python-linux-macos.mdx)
150
+ - [Python on Windows](docs-site/docs/installation/python-windows.mdx)
151
+ - [Docker CPU](docs-site/docs/installation/docker-cpu.mdx)
152
+ - [Docker CUDA](docs-site/docs/installation/docker-cuda.mdx)
153
+ - [Home Assistant add-on](docs-site/docs/installation/home-assistant-addon.mdx)
154
+ - [Processing servers](docs-site/docs/installation/processing-server-linux-macos.mdx)
155
+ - [Compatibility](docs-site/docs/installation/architecture-support.mdx)
156
+
157
+ ## Home Assistant
158
+
159
+ Toposync can run as a Home Assistant add-on with sidebar ingress, supervised execution, direct-port access when enabled, and internal access to the Home Assistant Core API.
160
+
161
+ Use the dedicated add-on repository:
162
+
163
+ ```text
164
+ https://github.com/toposync/toposync-homeassistant-addon
165
+ ```
166
+
167
+ Start with [Home Assistant add-on installation](docs-site/docs/installation/home-assistant-addon.mdx). For Raspberry Pi and HAOS, treat the add-on as a lightweight origin server and delegate heavy vision or multi-camera processing to a processing server when needed.
168
+
169
+ ## Development
170
+
171
+ Prerequisites:
172
+
173
+ - Python 3.12;
174
+ - `uv`;
175
+ - Node 20 or newer;
176
+ - npm.
177
+
178
+ From the repository root:
179
+
180
+ ```bash
181
+ uv sync
182
+ npm install
183
+ npm run build:extensions
184
+ TOPOSYNC_AUTH_MODE=bypass npm run dev
185
+ ```
186
+
187
+ Open:
188
+
189
+ ```text
190
+ http://127.0.0.1:5173/
191
+ ```
192
+
193
+ The default development data directory is `.toposync-data`.
194
+
195
+ See [Development setup](docs-site/docs/developers/development-setup.mdx) for the full local workflow.
196
+
197
+ ## Repository map
198
+
199
+ - `src/toposync`: core backend, API, extension manager, pipeline runtime, processing server.
200
+ - `frontend`: React/ThreeJS frontend host.
201
+ - `packages/plugin-api`: public TypeScript contract for frontend extensions.
202
+ - `packages/toposync`: default Python product bundle.
203
+ - `packages/toposync-streaming`: streaming bundle.
204
+ - `packages/toposync-vision-cuda`: NVIDIA CUDA upgrade bundle.
205
+ - `packages/toposync-vision-directml`: Windows DirectML upgrade bundle.
206
+ - `extensions`: first-party extension packages.
207
+ - `docs-site`: Docusaurus documentation site.
208
+ - `integrations/home_assistant`: Home Assistant integration and add-on related assets.
209
+ - `scripts`: distribution, validation, and service helper scripts.
210
+
211
+ ## Documentation
212
+
213
+ Documentation lives in `docs-site`.
214
+
215
+ Useful starting points:
216
+
217
+ - [Installation](docs-site/docs/installation/choose-your-installation.mdx)
218
+ - [Compatibility](docs-site/docs/installation/architecture-support.mdx)
219
+ - [Architecture](docs-site/docs/developers/architecture.mdx)
220
+ - [Extension authoring](docs-site/docs/developers/extension-authoring.mdx)
221
+ - [Plugin API](docs-site/docs/developers/plugin-api.mdx)
222
+ - [Pipelines](docs-site/docs/developers/pipelines.mdx)
223
+ - [Visual identity](docs-site/docs/developers/visual-identity.mdx)
224
+ - [Release process](docs-site/docs/developers/release-process.mdx)
225
+
226
+ Build the documentation site locally:
227
+
228
+ ```bash
229
+ npm run docs:start
230
+ npm run docs:build
231
+ ```
232
+
233
+ ## How to contribute
234
+
235
+ Contributions are welcome, especially during the alpha.
236
+
237
+ You can help with:
238
+
239
+ - bug reports;
240
+ - tests with different cameras and hardware;
241
+ - validation of RTSP, ONVIF, PTZ, and streaming;
242
+ - documentation improvements;
243
+ - UX suggestions;
244
+ - pipeline examples;
245
+ - code fixes;
246
+ - future extensions;
247
+ - translations;
248
+ - responsible sharing with the home automation community.
249
+
250
+ When opening an issue, try to include:
251
+
252
+ - operating system;
253
+ - installation method;
254
+ - camera or device model, when applicable;
255
+ - relevant logs;
256
+ - screenshots or short videos, when useful;
257
+ - steps to reproduce;
258
+ - expected behavior and observed behavior.
259
+
260
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
261
+
262
+ For security vulnerabilities, do not use public issues. See [SECURITY.md](SECURITY.md).
263
+
264
+ ## Support the project
265
+
266
+ Toposync is an early-stage open source project, with no mandatory cloud and no active commercial product at this moment. Development involves backend, frontend, computer vision, streaming, apps, Home Assistant, documentation, testing, and support for many different environments.
267
+
268
+ If you want to support development:
269
+
270
+ - test and share feedback;
271
+ - contribute code or documentation;
272
+ - share it with people who care about local home automation;
273
+ - support the maintainer through [GitHub Sponsors](https://github.com/sponsors/mateuscalza).
274
+
275
+ ## Project status
276
+
277
+ Toposync is in **alpha early access**.
278
+
279
+ This means:
280
+
281
+ - some parts already work and can be tested;
282
+ - some features are advanced and require manual configuration;
283
+ - some areas are still experimental;
284
+ - the mobile/TV app will be released soon;
285
+ - installation and documentation are still being organized;
286
+ - bugs are expected;
287
+ - community feedback is essential.
288
+
289
+ Use it, test it, break it, report it, and help improve it.
290
+
291
+ ## Support and security
292
+
293
+ - Community support: [SUPPORT.md](SUPPORT.md)
294
+ - Security policy: [SECURITY.md](SECURITY.md)
295
+
296
+ ## License
297
+
298
+ Toposync is released under the [MIT License](LICENSE).