toposync-core 0.3.4__tar.gz

toposync_core-0.3.4/.dockerignore

@@ -0,0 +1,29 @@
+.git
+.gitignore
+.DS_Store
+
+.venv
+.toposync-data
+toposync-data
+
+node_modules
+**/node_modules
+.yarn
+.pnp.cjs
+.pnp.loader.mjs
+yarn.lock
+
+dist
+**/dist
+build
+**/build
+
+.ruff_cache
+__pycache__
+*.pyc
+.pytest_cache
+
+test-results
+playwright-report
+
+*.log

toposync_core-0.3.4/.env.example

@@ -0,0 +1,5 @@
+# Local dev ports for a second Toposync instance
+TOPOSYNC_BACKEND_PORT=8100
+TOPOSYNC_FRONTEND_PORT=5174
+TOPOSYNC_PROCESSING_PORT=9101
+TOPOSYNC_DATA_DIR=.toposync-data

toposync_core-0.3.4/.github/workflows/distribution-smoke.yml

@@ -0,0 +1,39 @@
+name: Distribution Smoke
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  distribution-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps chromium
+
+      - name: Run distribution smoke test
+        run: python scripts/test_distribution_install.py

toposync_core-0.3.4/.gitignore

@@ -0,0 +1,39 @@
+.DS_Store
+.env
+.venv
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+
+node_modules/
+yarn.lock
+.pnp.cjs
+.pnp.loader.mjs
+.yarn/
+dist/
+build/
+.parcel-cache/
+
+.toposync-data/
+.toposync-processor-data
+toposync-data/
+
+*.log
+
+*.ignore.md
+ignore/
+
+# Playwright
+test-results/
+playwright-report/
+yolo*.pt
+
+# Streaming extension engines are downloaded at runtime.
+extensions/streaming/src/toposync_ext_streaming/bin/mediamtx/**/mediamtx*
+extensions/streaming/src/toposync_ext_streaming/bin/ffmpeg/**/ffmpeg*
+
+# Vision model artifacts are provisioned locally and must not be committed.
+extensions/vision/models/
+
+*.temporary.*

toposync_core-0.3.4/.python-version

@@ -0,0 +1 @@
+3.12

toposync_core-0.3.4/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

toposync_core-0.3.4/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent notes for this repo
+
+- Commit message style (based on existing history):
+  - Prefer `feat: ...`, `fix: ...`, `docs: ...`, `test: ...`, `refactor: ...`, `i18n: ...`.
+  - Use an optional scope when it helps (`feat(pipelines): ...`).
+  - Keep the summary short, imperative, and without a trailing period.
+- Whenever you add a UI entry/option for the user, it must have clear value and make sense (don’t expose internal identifiers; generate them automatically).
+- Don’t delete code you don’t understand just for “cleanup”; if you think it might be parallel work (by the user or another agent), leave it in the working tree and simply don’t include it in the commit (e.g., `git add -p`).
+- If `toposync` is running, manual edits to `.toposync-data/config.json` are supported: the runtime reloads the file when it changes (mtime/size), and pipelines may be reconciled on the next orchestrator poll.
+- Still prefer editing via the wizard/API (validation/normalization, less chance of conflicts). If editing manually, keep JSON + schema valid (notably `pipeline.graph.schema_version`); invalid files are renamed to `config.corrupt-*` and replaced with defaults. Avoid concurrent edits with the running UI/service (last-write-wins).
+- TopoSync deve fornecer estruturas genéricas e empoderar extensões com recursos de base. Elas devem lidar com questões específicas de domínio, e não o TopoSync. Jamais aceite fazer "gambiarras" dentro do código do TopoSync para acomodar casos específicos de uma extensão.

toposync_core-0.3.4/Dockerfile

@@ -0,0 +1,25 @@
+FROM node:20-bookworm-slim AS node-build
+
+WORKDIR /app
+COPY . .
+
+RUN npm ci
+RUN npm run build:extensions
+RUN npm run build:frontend
+
+
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS runtime
+
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/app/.venv
+ENV PATH="/app/.venv/bin:$PATH"
+
+COPY --from=node-build /app /app
+
+RUN uv sync --frozen --no-dev --no-editable
+
+EXPOSE 8000
+VOLUME ["/data"]
+
+CMD ["toposync", "serve", "--host", "0.0.0.0", "--port", "8000", "--data-dir", "/data", "--frontend-dir", "/app/frontend/dist"]

toposync_core-0.3.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateus Calza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toposync_core-0.3.4/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: toposync-core
+Version: 0.3.4
+Summary: Toposync core runtime (Python backend + extension host).
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic>=2.8
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# Toposync
+
+A local-first platform (Python + React + ThreeJS) for a home automation “digital twin” — built on an **extensions runtime**.
+
+This repo’s main goal is to solve the “biggest knot”: **extensions with a Python backend + TypeScript frontend installable via wheel** (without requiring a build toolchain on the user’s machine).
+
+## Documentation
+
+- Index: `docs/README.md`
+- Self-hosting (production): `docs/SELF_HOSTING.md`
+- Running in dev: `docs/DEVELOPMENT.md`
+- Pipelines (DAG): `docs/PIPELINES.md`
+- Extensions (runtime): `docs/EXTENSIONS_RUNTIME.md`
+- TS contract / plugin API: `docs/PLUGIN_API.md`
+- Creating an extension: `docs/EXTENSION_AUTHORING.md`
+
+## Quickstart (dev)
+
+Prerequisites: `uv`, Python 3.11+, and Node 20+.
+
+```bash
+uv sync
+npm install
+npm run build:extensions
+npm run dev
+```
+
+Open `http://localhost:5173`.

toposync_core-0.3.4/docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  toposync:
+    image: toposync:local
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./toposync-data:/data
+    restart: unless-stopped

toposync_core-0.3.4/docs/ARCHITECTURE.md

@@ -0,0 +1,19 @@
+# Arquitetura
+
+## Base
+
+- **Backend (Python)**: host de extensões (entry points), event bus async (com prevenção/substituição), service registry e servidor de assets estáticos das extensões.
+- **Frontend (React/ThreeJS)**: host que consulta `/api/extensions` e carrega `remoteEntry.js` de cada extensão em runtime (Module Federation).
+- **Extensão = pacote Python**: `extension.json` + entry point + `static/remoteEntry.js` embutido no wheel.
+- **Contrato TS (host)**: extensões registram `element types` (objeto 3D + modais de ação/edição), `notification renderers`, `settings panels` e **temas** (ver `frontend/packages/plugin-api/index.d.ts`).
+
+## Estrutura do repo
+
+- `src/toposync`: backend core (FastAPI) + runtime de extensões
+- `frontend`: app host (React/Three + webpack)
+- `extensions/structural`: extensão “first‑party” (paredes/áreas: ferramentas 2D + render 3D)
+- `extensions/models`: extensão “first‑party” (importar GLB/GLTF + prévia 2D + render 3D)
+- `extensions/home_assistant`: extensão “first‑party” (scaffold: configurar servidores Home Assistant)
+- `extensions/cameras`: extensão “first‑party” (RTSP snapshots + processamento local/remoto + detecções)
+- `extensions/images`: extensão “first‑party” (importar imagens como sobreposição ou decalque)
+

toposync_core-0.3.4/docs/BUILD.md

@@ -0,0 +1,103 @@
+# Build (produção / distribuição)
+
+## Backend (core)
+
+Gera wheel/sdist do core:
+
+```bash
+uv build
+```
+
+Isso gera o pacote `toposync-core`.
+
+Durante o build, o hook do core garante que o frontend host entre no artefato. Se `frontend/dist` ainda não existir, ele tenta gerar esse bundle com:
+
+```bash
+npm run build:frontend
+```
+
+O wheel/sdist final já sai com a UI host embutida dentro do pacote Python.
+
+## Produto (bundle padrão)
+
+Gera o wheel do pacote instalável por usuário final:
+
+```bash
+uv build packages/toposync
+```
+
+Isso gera o pacote `toposync`, que depende de `toposync-core` + extensões padrão.
+
+Para gerar o bundle opcional de streaming:
+
+```bash
+uv build packages/toposync-streaming
+```
+
+Isso gera o pacote `toposync-streaming`, que depende do bundle padrão `toposync` + `toposync-ext-streaming`.
+
+## Bundles alternativos de aceleração
+
+Para gerar os bundles first-party de aceleração opcional:
+
+```bash
+uv build packages/toposync-vision-cuda
+uv build packages/toposync-vision-directml
+```
+
+Eles geram respectivamente `toposync-vision-cuda` e `toposync-vision-directml`.
+
+## Frontend host (override opcional)
+
+Se você quiser rebuildar manualmente o bundle do host antes do `uv build`:
+
+```bash
+npm run build:frontend
+```
+
+## Extensões (wheel com assets)
+
+1) Build do bundle JS da extensão (gera `static/` dentro do pacote Python):
+
+```bash
+npm run build:extensions
+```
+
+2) Build do wheel da extensão:
+
+```bash
+uv build extensions/structural
+uv build extensions/models
+uv build extensions/home_assistant
+uv build extensions/cameras
+uv build extensions/images
+uv build extensions/streaming
+```
+
+Isso gera `extensions/<ext>/dist/*.whl`. Usuário final instala só o wheel (sem Node) e o app carrega o frontend prebuilt.
+
+Para validar que cada wheel leva seus assets de runtime (`extension.json`, `static/`, manifests, dados e licenças) e que a `vision` não embute pesos ONNX publicáveis, rode:
+
+```bash
+python scripts/check_extension_wheels.py
+```
+
+## Smoke test de distribuição
+
+Para validar o fluxo de release fora do monorepo, rode:
+
+```bash
+python scripts/test_distribution_install.py
+```
+
+Esse smoke test:
+
+- rebuilda o frontend host e as UIs das extensões padrão
+- gera um wheelhouse local com `toposync-core`, `toposync` e as extensões padrão
+- cria um venv limpo fora do checkout
+- instala `toposync` com `pip` a partir dos wheels gerados
+- sobe `toposync serve` usando apenas o ambiente instalado
+- valida `/api/extensions`
+- roda Playwright contra a UI host embutida para confirmar carregamento dos remotes
+
+A CI executa esse mesmo fluxo no workflow [`.github/workflows/distribution-smoke.yml`](/Users/c/Projects/toposync-2/.github/workflows/distribution-smoke.yml).

toposync_core-0.3.4/docs/DATA.md

@@ -0,0 +1,15 @@
+# Persistência (local‑first)
+
+- O backend salva a configuração em um único arquivo: `<data_dir>/config.json`
+- Arquivos auxiliares do usuário ficam em: `<data_dir>/files/`
+- Para definir o diretório explicitamente use `TOPOSYNC_DATA_DIR=/caminho/para/dados` (ou `toposync serve --data-dir ...`)
+- Dica (dev): `uv run toposync serve --data-dir .toposync-data` (pasta ignorada pelo git)
+- Default por SO:
+  - Linux: `$XDG_DATA_HOME/toposync` ou `~/.local/share/toposync`
+  - macOS: `~/Library/Application Support/Toposync`
+  - Windows: `%APPDATA%/Toposync`
+
+Se bater dúvida sobre *qual* diretório está em uso, chame `GET /api/system/paths`.
+
+O frontend lê/salva a composição via `GET/PUT /api/composition`. Versões antigas usavam `localStorage` (`toposync.composition.v1`) e o app tenta migrar automaticamente quando o backend está vazio.
+

toposync_core-0.3.4/docs/DEVELOPMENT.md

@@ -0,0 +1,119 @@
+# Rodar em dev
+
+Pré‑requisitos: `uv`, Python 3.11+ e Node 20+.
+
+## 1) Python (deps + extensões do repo em editable)
+
+```bash
+uv sync
+```
+
+## 2) Node (workspaces)
+
+```bash
+npm install
+```
+
+## 3) Build das UIs das extensões (gera `static/remoteEntry.js` nos pacotes Python)
+
+Atalho:
+
+```bash
+npm run build:extensions
+```
+
+Ou individual:
+
+```bash
+npm --workspace @toposync/extension-structural-ui run build
+npm --workspace @toposync/extension-models-ui run build
+npm --workspace @toposync/extension-home-assistant-ui run build
+npm --workspace @toposync/extension-cameras-ui run build
+npm --workspace @toposync/extension-images-ui run build
+```
+
+## 4) Rodar backend + frontend
+
+Separado:
+
+```bash
+uv run python -m toposync serve --data-dir .toposync-data
+npm --workspace @toposync/frontend run dev
+```
+
+Atalho (um comando):
+
+```bash
+npm run dev
+```
+
+Abra `http://localhost:5173`.
+
+## Rodar 2 instâncias em paralelo (sem conflito)
+
+As portas padrão continuam:
+
+- backend: `8000`
+- frontend: `5173`
+- processing server (quando usado): `9001`
+
+Você pode sobrescrever por ambiente:
+
+- `TOPOSYNC_BACKEND_PORT`
+- `TOPOSYNC_FRONTEND_PORT`
+- `TOPOSYNC_PROCESSING_PORT`
+- `TOPOSYNC_DATA_DIR` (recomendado quando rodar duas instâncias)
+- `TOPOSYNC_AUTH_MODE` (`enforced` padrão, `bypass` para dev/curl/e2e)
+- `TOPOSYNC_AUTH_COOKIE_SECURE` (`auto` padrão; force `true` quando rodar atrás de HTTPS/reverse proxy)
+
+`npm run dev` lê automaticamente variáveis de `.env` (ou de `TOPOSYNC_ENV_FILE`, se definido).
+
+Exemplo usando o template:
+
+```bash
+cp .env.example .env
+npm run dev
+```
+
+Para rodar sem autenticação local em dev:
+
+```bash
+TOPOSYNC_AUTH_MODE=bypass npm run dev
+```
+
+Exemplo de segunda instância local:
+
+```bash
+TOPOSYNC_BACKEND_PORT=8100 \
+TOPOSYNC_FRONTEND_PORT=5174 \
+TOPOSYNC_DATA_DIR=.toposync-data-2 \
+npm run dev
+```
+
+Nesse caso, abra `http://localhost:5174`.
+
+## Quando rodar o quê (atalho mental)
+
+- Alterou código Python do core ou da extensão → reinicie `uv run python -m toposync serve` (use o mesmo `--data-dir`, se estiver usando)
+- Alterou UI do host → o `webpack-dev-server` recarrega (HMR)
+- Alterou UI de uma extensão → rode `npm --workspace <ext-ui> run build` (ou use `--watch`) e dê refresh
+
+## Testes E2E (Playwright)
+
+1) Instalar deps Node:
+
+```bash
+npm install
+```
+
+2) Instalar o browser do Playwright (1x):
+
+```bash
+npx playwright install chromium
+```
+
+3) Rodar:
+
+```bash
+npm run test:e2e
+```

toposync_core-0.3.4/docs/EXTENSIONS_FIRST_PARTY.md

@@ -0,0 +1,31 @@
+# Extensões inclusas no repo
+
+## `extensions/structural`
+
+- Paredes/áreas: ferramentas 2D + render 3D.
+
+## `extensions/models`
+
+- Importar GLB/GLTF + prévia 2D + render 3D.
+- Faz upload para o backend via `POST /api/files/upload` (salva em `<data_dir>/files/<dir>/...`).
+- Gera uma prévia PNG top‑down no browser (WebGL) e também salva em `/files`.
+- Cria um elemento `com.toposync.models.gltf` com metadados de escala (para 2D ↔ 3D baterem).
+
+## `extensions/home_assistant`
+
+- Scaffold: configurar servidores Home Assistant.
+- Elemento “Home Assistant item” com visualizações especiais (luminária, vento climatizado e **modelo 3D**).
+
+## `extensions/cameras`
+
+- RTSP snapshots, ingestão e operadores de pré/pós-processamento para pipelines de câmera.
+
+## `extensions/images`
+
+- Importar imagens como sobreposição ou decalque.
+
+## `extensions/vision`
+
+- Detecção, rastreamento, segmentação de instâncias e pose por tarefa pública.
+- Runtime oficial first-party baseado em ONNX Runtime.
+- Caminho padrão do produto: ONNX Runtime CPU; aceleração é opcional e explícita.

toposync_core-0.3.4/docs/EXTENSIONS_RUNTIME.md

@@ -0,0 +1,72 @@
+# Extensões (runtime)
+
+## 1) Descoberta no backend (entry points)
+
+Cada extensão declara um entry point em `toposync.extensions`. O core descobre tudo via `importlib.metadata.entry_points()` e instancia o plugin.
+
+Exemplo (`extensions/structural/pyproject.toml`):
+
+```toml
+[project.entry-points."toposync.extensions"]
+structural = "toposync_ext_structural.plugin:StructuralExtension"
+```
+
+## 2) Manifesto (`extension.json`)
+
+O core lê `extension.json` via `importlib.resources` dentro do pacote da extensão. Esse manifesto é o contrato mínimo e é versionado por `schema_version`.
+
+Exemplo:
+
+```json
+{
+  "schema_version": 1,
+  "id": "com.suaorg.minha_ext",
+  "name": "Minha Extensão",
+  "version": "0.1.0",
+  "requires_core_version": ">=0.3,<0.4",
+  "requires_extensions": ["com.toposync.cameras>=0.1.0"],
+  "frontend": {
+    "kind": "module-federation",
+    "remote_entry": "remoteEntry.js",
+    "scope": "minha_ext",
+    "module": "./activate"
+  }
+}
+```
+
+Campos de compatibilidade:
+
+- `requires_core_version`: specifier PEP 440 avaliado contra a versão atual do `toposync-core`
+- `requires_extensions`: lista de ids de extensão obrigatórios, opcionalmente com specifier de versão no formato `com.suaorg.outra_ext>=1.2`
+
+O loader valida esses requisitos antes do `setup()`. Extensões incompatíveis são ignoradas e registradas em log.
+
+## 3) Servir assets estáticos
+
+Como o bundle do frontend está dentro do wheel, o backend expõe:
+
+- `/extensions/<extension_id>/<path>`
+
+E o endpoint `/api/extensions` retorna, para cada extensão, um `frontend.remote_entry_url` já pronto (relativo, para funcionar atrás de proxy).
+
+## 4) Carregamento no frontend (runtime)
+
+O host faz:
+
+1) `GET /api/extensions`
+2) para cada extensão com `frontend.kind = "module-federation"`:
+   - injeta o script `remoteEntry.js`
+   - inicializa o share scope (`__webpack_init_sharing__`)
+   - chama `container.get("./activate")`
+   - executa `activate(host)`
+
+Ou seja: instalar o wheel = instalar backend + UI prebuilt, e o host “puxa” isso automaticamente.
+
+## Backend: hooks e serviços (base)
+
+O core expõe (para evoluir):
+
+- `EventBus`: pipeline async com prioridade e `EventOutcome` (stop propagation, prevent default, override payload/result)
+- `ServiceRegistry`: registry simples para desacoplar extensões por ID
+
+Ponto de partida de evento (exemplo atual): `device.action_requested`.