seam-studio 0.1.0__tar.gz

seam_studio-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+recursive-include seam_studio/data *.yaml
+recursive-include seam_studio/static *

seam_studio-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: seam-studio
+Version: 0.1.0
+Summary: SEAM Studio - unified RF-visual scene authoring, RF material assignment, and Sionna RT digital-twin simulation workbench
+Author-email: Jaewoo Lee <doni04164@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/jaewoo4200/SEAM
+Project-URL: Issues, https://github.com/jaewoo4200/SEAM/issues
+Project-URL: Documentation, https://jaewoo4200.github.io/SEAM/
+Keywords: sionna,ray-tracing,digital-twin,RF,6G,ISAC,radio-propagation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Communications
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.111
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: pydantic>=2.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: trimesh>=4.4
+Requires-Dist: scipy>=1.11
+Requires-Dist: rtree>=1.2
+Requires-Dist: shapely>=2.0
+Requires-Dist: mapbox-earcut>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10.3
+Requires-Dist: ddgs>=9.0
+Requires-Dist: sionna-rt>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Provides-Extra: sionna
+Requires-Dist: sionna-rt>=2.0; extra == "sionna"
+Provides-Extra: results
+Requires-Dist: duckdb>=1.0; extra == "results"
+Requires-Dist: pyarrow>=16; extra == "results"
+Requires-Dist: zarr>=2.18; extra == "results"
+
+# SEAM Studio
+
+**Unified RF–visual scene authoring, RF material assignment, and
+[Sionna RT](https://github.com/NVlabs/sionna-rt) digital-twin simulation — in one
+local workbench.**
+
+SEAM Studio pairs a FastAPI backend with a bundled React/three.js frontend:
+author a 3D scene, bind ITU/custom RF materials to its surfaces (by hand,
+by rules, or with a local-LLM agent), then ray-trace paths, radio maps,
+UE/UAV trajectories, Doppler, beamforming and handover — all persisted as
+reproducible result sets.
+
+## Install
+
+```bash
+pip install seam-studio
+```
+
+This installs the real ray-tracing engine (`sionna-rt`, Dr.Jit/Mitsuba) by
+default — no GPU required (an LLVM CPU backend is used when CUDA is absent),
+and the app falls back to its deterministic Mock engine if the import fails.
+
+## Quickstart
+
+```bash
+seam-studio            # starts on http://127.0.0.1:8000 and opens the browser
+```
+
+The first run creates a **Sample Demo** project (toy urban scene with a
+rooftop TX, street RX, car and pedestrian actors) under `~/.seam/projects`,
+so you can press **Simulate paths** immediately.
+
+```
+seam-studio --port 9000            # different port
+seam-studio --project-root D:\twins  # keep projects elsewhere
+seam-studio --no-browser
+```
+
+## Highlights
+
+- **Scene → RF binding**: import Mitsuba XML / scene bundles / OpenStreetMap
+  extrusions; assign RF materials per surface with validation and provenance.
+- **Simulation**: paths, planar & mesh radio maps, multi-TX SINR/RSRP/RSRQ,
+  MIMO beamforming, UE/UAV trajectories with per-step handover (3GPP A3),
+  Doppler spectrograms, ML ground-truth dataset export (NPZ).
+- **AI assist**: local LLM/VLM material suggestion agent (Ollama / LM Studio),
+  natural-language assignment rules, validation explains.
+- **Reproducibility**: every run persisted with config snapshots + content
+  hashes; measurement import and calibration against real logs.
+
+## Links
+
+- Repository & docs: <https://github.com/jaewoo4200/SEAM>
+- Website: <https://jaewoo4200.github.io/SEAM/>
+
+Apache-2.0 © Jaewoo Lee

seam_studio-0.1.0/README.md

@@ -0,0 +1,56 @@
+# SEAM Studio
+
+**Unified RF–visual scene authoring, RF material assignment, and
+[Sionna RT](https://github.com/NVlabs/sionna-rt) digital-twin simulation — in one
+local workbench.**
+
+SEAM Studio pairs a FastAPI backend with a bundled React/three.js frontend:
+author a 3D scene, bind ITU/custom RF materials to its surfaces (by hand,
+by rules, or with a local-LLM agent), then ray-trace paths, radio maps,
+UE/UAV trajectories, Doppler, beamforming and handover — all persisted as
+reproducible result sets.
+
+## Install
+
+```bash
+pip install seam-studio
+```
+
+This installs the real ray-tracing engine (`sionna-rt`, Dr.Jit/Mitsuba) by
+default — no GPU required (an LLVM CPU backend is used when CUDA is absent),
+and the app falls back to its deterministic Mock engine if the import fails.
+
+## Quickstart
+
+```bash
+seam-studio            # starts on http://127.0.0.1:8000 and opens the browser
+```
+
+The first run creates a **Sample Demo** project (toy urban scene with a
+rooftop TX, street RX, car and pedestrian actors) under `~/.seam/projects`,
+so you can press **Simulate paths** immediately.
+
+```
+seam-studio --port 9000            # different port
+seam-studio --project-root D:\twins  # keep projects elsewhere
+seam-studio --no-browser
+```
+
+## Highlights
+
+- **Scene → RF binding**: import Mitsuba XML / scene bundles / OpenStreetMap
+  extrusions; assign RF materials per surface with validation and provenance.
+- **Simulation**: paths, planar & mesh radio maps, multi-TX SINR/RSRP/RSRQ,
+  MIMO beamforming, UE/UAV trajectories with per-step handover (3GPP A3),
+  Doppler spectrograms, ML ground-truth dataset export (NPZ).
+- **AI assist**: local LLM/VLM material suggestion agent (Ollama / LM Studio),
+  natural-language assignment rules, validation explains.
+- **Reproducibility**: every run persisted with config snapshots + content
+  hashes; measurement import and calibration against real logs.
+
+## Links
+
+- Repository & docs: <https://github.com/jaewoo4200/SEAM>
+- Website: <https://jaewoo4200.github.io/SEAM/>
+
+Apache-2.0 © Jaewoo Lee

seam_studio-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+# >=77 for PEP 639 SPDX license expressions (CI installs from a clean env).
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# The pip-installable app: `pip install seam-studio` → `seam-studio` serves
+# the backend + the bundled frontend. ("seam" itself is taken on PyPI.)
+name = "seam-studio"
+version = "0.1.0"
+description = "SEAM Studio - unified RF-visual scene authoring, RF material assignment, and Sionna RT digital-twin simulation workbench"
+readme = "README.md"
+requires-python = ">=3.11"
+# SPDX expression (the license text lives at the repo root; a ../LICENSE file
+# reference breaks modern setuptools, which forbids paths outside the project).
+license = "Apache-2.0"
+authors = [{ name = "Jaewoo Lee", email = "doni04164@gmail.com" }]
+keywords = ["sionna", "ray-tracing", "digital-twin", "RF", "6G", "ISAC", "radio-propagation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Telecommunications Industry",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Communications",
+]
+dependencies = [
+    "fastapi>=0.111",
+    "python-multipart>=0.0.9",
+    "uvicorn[standard]>=0.30",
+    "pydantic>=2.7",
+    "numpy>=1.26",
+    "trimesh>=4.4",
+    # Scene import (Mitsuba XML -> GLB) uses trimesh geometry ops that
+    # require scipy at runtime.
+    "scipy>=1.11",
+    # trimesh ray casting (terrain-following trajectories) needs an R-tree.
+    "rtree>=1.2",
+    # OpenStreetMap import: extrude building footprints (shapely polygons) via
+    # trimesh, which needs an FSF-approved triangulation engine at runtime.
+    "shapely>=2.0",
+    "mapbox-earcut>=1.0",
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+    "pillow>=10.3",
+    # SEAM-Agent web/image evidence retrieval (DuckDuckGo, keyless). Only used
+    # when the user opts into online evidence; import stays lazy.
+    "ddgs>=9.0",
+    # The real ray-tracing engine, installed by default so `pip install
+    # seam-studio` matches `pip install sionna` expectations (Dr.Jit/Mitsuba
+    # ship an LLVM CPU backend, so no GPU is required to install or run).
+    # The app still degrades gracefully to the Mock backend if the import
+    # fails at runtime (HANDOFF rule: never break when Sionna is missing).
+    "sionna-rt>=2.0",
+]
+
+[project.scripts]
+seam-studio = "seam_studio.cli:main"
+
+[project.urls]
+Repository = "https://github.com/jaewoo4200/SEAM"
+Issues = "https://github.com/jaewoo4200/SEAM/issues"
+Documentation = "https://jaewoo4200.github.io/SEAM/"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.2"]
+# Back-compat alias from when sionna-rt was opt-in; it is a base dependency
+# now, so this extra is a no-op kept so `pip install "seam-studio[sionna]"`
+# instructions keep working.
+sionna = ["sionna-rt>=2.0"]
+# Future columnar result schemas (paths.parquet, radio_map.parquet, cir.zarr).
+results = ["duckdb>=1.0", "pyarrow>=16", "zarr>=2.18"]
+
+[tool.setuptools.packages.find]
+include = ["seam_studio*"]
+
+[tool.setuptools.package-data]
+# default_rf_materials.yaml + the frontend bundle copied in by
+# scripts/build_wheel.py (seam_studio/static is gitignored; wheels carry it).
+seam_studio = ["data/*.yaml", "static/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

seam_studio-0.1.0/seam_studio/api/agent.py

@@ -0,0 +1,149 @@
+"""SEAM-Agent endpoints (retrieval-augmented RF material authoring).
+
+POST /projects/{id}/agent/material-assignment/start          spawn a job
+                                                             (409 while one is
+                                                             already running)
+GET  /projects/{id}/agent/material-assignment/{jid}/trace    activity trace
+                                                             (memory, or disk
+                                                             after a restart)
+POST /projects/{id}/agent/material-assignment/{jid}/cancel   cooperative stop
+POST /projects/{id}/agent/material-assignment/{jid}/apply    bake accepted
+                                                             segments (undo
+                                                             via segmentation
+                                                             /undo)
+
+The trace is the user-visible "thinking": bounded steps, search queries,
+evidence cards, live progress/ETA and segment proposals - never raw
+chain-of-thought.
+"""
+
+from fastapi import APIRouter, HTTPException
+
+from seam_studio.api.deps import get_store, load_scene_or_404
+from seam_studio.schemas.seam_agent import (
+    AgentApplyRequest,
+    AgentApplyResponse,
+    AgentCancelResponse,
+    AgentStartRequest,
+    AgentStartResponse,
+    AgentTrace,
+)
+from seam_studio.services import seam_agent
+from seam_studio.services.material_segmentation import SegmentationError
+
+router = APIRouter(tags=["agent"])
+
+
+@router.post(
+    "/projects/{project_id}/agent/material-assignment/start",
+    response_model=AgentStartResponse,
+)
+def agent_start(project_id: str, request: AgentStartRequest) -> AgentStartResponse:
+    store = get_store()
+    scene = load_scene_or_404(store, project_id)
+    project_dir = store.resolve(project_id)
+    if scene.prim_by_id(request.prim_id) is None:
+        raise HTTPException(status_code=404, detail=f"prim not found: {request.prim_id}")
+    b = request.budget
+    budget = seam_agent.AgentBudget(
+        max_web_searches=b.max_web_searches if b else 6,
+        max_image_searches=b.max_image_searches if b else 4,
+        max_vlm_calls=b.max_vlm_calls if b else 40,
+        max_refine_calls=b.max_refine_calls if b else 3,
+        max_runtime_sec=b.max_runtime_sec if b else 600,
+    )
+    try:
+        job_id = seam_agent.start_job(
+            project_dir,
+            scene,
+            request.prim_id,
+            [v.model_dump() for v in request.views],
+            request.user_hint,
+            request.allow_web,
+            request.model,
+            budget,
+        )
+    except seam_agent.AgentBusyError as exc:
+        # One job per project (and a small global cap): multi-building runs
+        # are sequential by design — the FE queues and retries.
+        raise HTTPException(status_code=409, detail=str(exc))
+    return AgentStartResponse(job_id=job_id)
+
+
+@router.get(
+    "/projects/{project_id}/agent/material-assignment/{job_id}/trace",
+    response_model=AgentTrace,
+)
+def agent_trace(project_id: str, job_id: str) -> AgentTrace:
+    store = get_store()
+    load_scene_or_404(store, project_id)
+    project_dir = store.resolve(project_id)
+    # Live jobs from memory; finished jobs rehydrate from ai/agent/<id>/ so
+    # traces stay reviewable after a backend restart.
+    job = seam_agent.resolve_job(project_dir, job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"unknown job: {job_id}")
+    return AgentTrace(
+        status=job.status,  # type: ignore[arg-type]
+        detail=job.detail or None,
+        steps=job.steps,  # type: ignore[arg-type]
+        evidence=job.evidence,  # type: ignore[arg-type]
+        segments=job.segments,  # type: ignore[arg-type]
+        progress=(job.progress or None),  # type: ignore[arg-type]
+        views=job.view_assets,  # type: ignore[arg-type]
+    )
+
+
+@router.post(
+    "/projects/{project_id}/agent/material-assignment/{job_id}/cancel",
+    response_model=AgentCancelResponse,
+)
+def agent_cancel(project_id: str, job_id: str) -> AgentCancelResponse:
+    store = get_store()
+    load_scene_or_404(store, project_id)
+    accepted = seam_agent.cancel_job(job_id)
+    return AgentCancelResponse(status="accepted" if accepted else "not_running")
+
+
+@router.post(
+    "/projects/{project_id}/agent/material-assignment/{job_id}/apply",
+    response_model=AgentApplyResponse,
+)
+def agent_apply(
+    project_id: str, job_id: str, request: AgentApplyRequest
+) -> AgentApplyResponse:
+    store = get_store()
+    scene = load_scene_or_404(store, project_id)
+    project_dir = store.resolve(project_id)
+    job = seam_agent.resolve_job(project_dir, job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"unknown job: {job_id}")
+    # GLB + scene JSON must move together; same per-project write lock as the
+    # segmentation apply/undo routes.
+    from seam_studio.services.material_segmentation import project_write_lock
+
+    with project_write_lock(project_dir):
+        try:
+            scene, info = seam_agent.apply_segments(
+                project_dir, scene, job, request.segment_ids
+            )
+        except SegmentationError as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
+        store.save_scene(project_id, scene)
+    store.append_provenance(
+        project_id,
+        {
+            "type": "seam_agent_apply",
+            "job_id": job_id,
+            "prim_id": job.prim_id,
+            "segment_ids": request.segment_ids,
+            "added_prim_ids": info["added_prim_ids"],
+            "backup_glb": info["backup_glb"],
+        },
+    )
+    return AgentApplyResponse(
+        added_prim_ids=info["added_prim_ids"],
+        removed_prim_id=info["removed_prim_id"],
+        backup_glb=info["backup_glb"],
+        batch_id=info["batch_id"],
+    )