mskit-simu 0.6.1__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.
- mskit_simu-0.6.1/LICENSE +21 -0
- mskit_simu-0.6.1/PKG-INFO +316 -0
- mskit_simu-0.6.1/README.md +272 -0
- mskit_simu-0.6.1/mskit/__init__.py +33 -0
- mskit_simu-0.6.1/mskit/_cli.py +8 -0
- mskit_simu-0.6.1/mskit/cli.py +354 -0
- mskit_simu-0.6.1/mskit/dem.py +231 -0
- mskit_simu-0.6.1/mskit/sims/__init__.py +1 -0
- mskit_simu-0.6.1/mskit/sims/agent.py +236 -0
- mskit_simu-0.6.1/mskit/sims/flow.py +103 -0
- mskit_simu-0.6.1/mskit/sims/projectile.py +146 -0
- mskit_simu-0.6.1/mskit/sims/random_walk.py +141 -0
- mskit_simu-0.6.1/mskit/simu/__init__.py +4 -0
- mskit_simu-0.6.1/mskit/simu/intent.py +275 -0
- mskit_simu-0.6.1/mskit/simu/simu.py +921 -0
- mskit_simu-0.6.1/mskit/traffic/__init__.py +14 -0
- mskit_simu-0.6.1/mskit/traffic/openctv.py +341 -0
- mskit_simu-0.6.1/mskit/traffic/opentraffic.py +402 -0
- mskit_simu-0.6.1/mskit/traffic/router.py +353 -0
- mskit_simu-0.6.1/mskit/traffic/utd19.py +461 -0
- mskit_simu-0.6.1/mskit_simu.egg-info/PKG-INFO +316 -0
- mskit_simu-0.6.1/mskit_simu.egg-info/SOURCES.txt +26 -0
- mskit_simu-0.6.1/mskit_simu.egg-info/dependency_links.txt +1 -0
- mskit_simu-0.6.1/mskit_simu.egg-info/entry_points.txt +3 -0
- mskit_simu-0.6.1/mskit_simu.egg-info/requires.txt +21 -0
- mskit_simu-0.6.1/mskit_simu.egg-info/top_level.txt +1 -0
- mskit_simu-0.6.1/pyproject.toml +57 -0
- mskit_simu-0.6.1/setup.cfg +4 -0
mskit_simu-0.6.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MegaBites AI Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mskit-simu
|
|
3
|
+
Version: 0.6.1
|
|
4
|
+
Summary: Mini Simulation Kit — terrain + traffic simulations powered by Simu AI, OpenCTV, JAXA AW3D30
|
|
5
|
+
Author: MegaBites AI Team
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/OnyxNeol/MSKit
|
|
8
|
+
Project-URL: Repository, https://github.com/OnyxNeol/MSKit
|
|
9
|
+
Project-URL: Dataset, https://huggingface.co/datasets/MegaBites-AI/AW3D30-DEM-Tiles
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/OnyxNeol/MSKit/issues
|
|
11
|
+
Project-URL: Simu Model, https://huggingface.co/HuggingFaceTB/SmolLM2-360M-Instruct
|
|
12
|
+
Keywords: simulation,terrain,dem,elevation,ai,gis,jaxa,aw3d30,traffic,opentraffic,utd19,openctv,cameras,smollm2,llm,natural language
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
24
|
+
Requires-Python: >=3.9
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: numpy>=1.24
|
|
28
|
+
Requires-Dist: requests>=2.28
|
|
29
|
+
Requires-Dist: huggingface_hub>=0.20
|
|
30
|
+
Provides-Extra: llm
|
|
31
|
+
Requires-Dist: transformers>=4.40; extra == "llm"
|
|
32
|
+
Requires-Dist: torch>=2.0; extra == "llm"
|
|
33
|
+
Requires-Dist: accelerate>=0.27; extra == "llm"
|
|
34
|
+
Requires-Dist: sentencepiece>=0.1.99; extra == "llm"
|
|
35
|
+
Provides-Extra: gguf
|
|
36
|
+
Requires-Dist: llama-cpp-python>=0.2; extra == "gguf"
|
|
37
|
+
Provides-Extra: viz
|
|
38
|
+
Requires-Dist: matplotlib>=3.7; extra == "viz"
|
|
39
|
+
Provides-Extra: tiff
|
|
40
|
+
Requires-Dist: tifffile>=2023.1; extra == "tiff"
|
|
41
|
+
Provides-Extra: all
|
|
42
|
+
Requires-Dist: mskit-simu[gguf,llm,tiff,viz]; extra == "all"
|
|
43
|
+
Dynamic: license-file
|
|
44
|
+
|
|
45
|
+
# MSKit — Mini Simulation Kit
|
|
46
|
+
|
|
47
|
+
[](https://pypi.org/project/mskit/)
|
|
48
|
+
[](https://huggingface.co/datasets/MegaBites-AI/AW3D30-DEM-Tiles)
|
|
49
|
+
[](LICENSE)
|
|
50
|
+
[](https://python.org)
|
|
51
|
+
|
|
52
|
+
A lightweight Python library for **terrain-based simulations** powered by real-world elevation, live traffic, open camera feeds, and an embedded AI assistant named **Simu**.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## ✨ Features
|
|
57
|
+
|
|
58
|
+
| Module | What it does |
|
|
59
|
+
|---|---|
|
|
60
|
+
| **DEMLoader** | Streams JAXA AW3D30 30m elevation tiles lazily from HuggingFace |
|
|
61
|
+
| **TrafficRouter** | Auto-selects OpenTraffic → UTD19 → synthetic fallback |
|
|
62
|
+
| **OpenCTV** | Aggregates free public traffic camera feeds (Singapore, London, Sydney, Oregon) |
|
|
63
|
+
| **Simu** | Embedded AI assistant — understands plain English, runs the right sim |
|
|
64
|
+
| **CLI** (`mskit`) | Full interactive terminal with all features in one place |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 🚀 Install
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Core (terrain + traffic + cameras + rule-based Simu)
|
|
72
|
+
pip install mskit
|
|
73
|
+
|
|
74
|
+
# With AI brain (SmolLM2-360M, ~700 MB downloaded once)
|
|
75
|
+
pip install mskit[llm]
|
|
76
|
+
|
|
77
|
+
# With GGUF support (your own .gguf model)
|
|
78
|
+
pip install mskit[gguf]
|
|
79
|
+
|
|
80
|
+
# Everything
|
|
81
|
+
pip install mskit[all]
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 🖥️ CLI — One command to rule them all
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
mskit # full interactive mode
|
|
90
|
+
mskit --brain untrained --mode custom # skip both prompts
|
|
91
|
+
mskit --brain huggingface --mode everything # SmolLM2 + run all 6 sims
|
|
92
|
+
mskit --lat 51.5074 --lon -0.1278 # start in London
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Startup flow
|
|
96
|
+
|
|
97
|
+
When you run `mskit`, Simu guides you through two steps:
|
|
98
|
+
|
|
99
|
+
**Step 1 — Choose AI Brain:**
|
|
100
|
+
```
|
|
101
|
+
╔══════════════════════════════════════════════════════════════╗
|
|
102
|
+
║ 🤖 Simu — Step 1: Choose Your AI Brain ║
|
|
103
|
+
╠══════════════════════════════════════════════════════════════╣
|
|
104
|
+
║ 1. untrained — Rule-based parser. Instant, no download. ║
|
|
105
|
+
║ 2. huggingface — SmolLM2-360M-Instruct ★ recommended ★ ║
|
|
106
|
+
║ 3. custom — HF repo ID / local folder / .gguf file ║
|
|
107
|
+
╚══════════════════════════════════════════════════════════════╝
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Step 2 — Choose Simulation Mode:**
|
|
111
|
+
```
|
|
112
|
+
╔══════════════════════════════════════════════════════════════╗
|
|
113
|
+
║ 🎮 Simu — Step 2: Choose Simulation Mode ║
|
|
114
|
+
╠══════════════════════════════════════════════════════════════╣
|
|
115
|
+
║ 1. random — Simu surprises you with a random sim ║
|
|
116
|
+
║ 2. custom — You describe exactly what you want ║
|
|
117
|
+
║ 3. everything — Run all 6 simulations at once ║
|
|
118
|
+
╚══════════════════════════════════════════════════════════════╝
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### CLI commands
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
<natural language> Run a simulation (Simu handles it)
|
|
125
|
+
cameras List cameras near current location
|
|
126
|
+
cameras <city/lat,lon> Cameras near a specific place
|
|
127
|
+
cameras sources Show all camera sources
|
|
128
|
+
camera snap <id> Refresh snapshot URL for a camera
|
|
129
|
+
location <city/lat,lon> Change default location
|
|
130
|
+
location Show current location
|
|
131
|
+
switch brain Re-pick AI brain
|
|
132
|
+
switch sim Re-pick simulation mode
|
|
133
|
+
history Show session sim history
|
|
134
|
+
help Full command reference
|
|
135
|
+
quit Exit
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 🐍 Python API
|
|
141
|
+
|
|
142
|
+
### Simu — AI Assistant
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
from mskit import Simu, DEMLoader, TrafficRouter
|
|
146
|
+
|
|
147
|
+
loader = DEMLoader()
|
|
148
|
+
router = TrafficRouter(loader)
|
|
149
|
+
|
|
150
|
+
# Interactive startup (brain + sim mode prompts)
|
|
151
|
+
simu = Simu(dem_loader=loader, traffic_router=router)
|
|
152
|
+
|
|
153
|
+
# Skip prompts programmatically
|
|
154
|
+
simu = Simu(
|
|
155
|
+
dem_loader=loader,
|
|
156
|
+
traffic_router=router,
|
|
157
|
+
auto_select="huggingface", # or "untrained" / "custom"
|
|
158
|
+
auto_simmode="custom", # or "random" / "everything"
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
# Chat in plain English
|
|
162
|
+
result = simu.chat("Run a random walk in Tokyo for 1000 steps")
|
|
163
|
+
result = simu.chat("Shoot a projectile from Mount Fuji east at 45° 80 m/s")
|
|
164
|
+
result = simu.chat("What's the traffic like in London?")
|
|
165
|
+
result = simu.chat("Simulate water flow in Zurich")
|
|
166
|
+
result = simu.chat("Navigate an agent from 35.6,139.7 to 35.65,139.75")
|
|
167
|
+
|
|
168
|
+
# Run all 6 simulations at once
|
|
169
|
+
results = simu.run_all("Tokyo")
|
|
170
|
+
|
|
171
|
+
# Switch brain/mode mid-session
|
|
172
|
+
simu.switch_brain()
|
|
173
|
+
simu.switch_sim_mode()
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Custom brain (your own model)
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
# HuggingFace repo
|
|
180
|
+
simu = Simu(auto_select="custom",
|
|
181
|
+
custom_model="mistralai/Mistral-7B-Instruct-v0.3")
|
|
182
|
+
|
|
183
|
+
# Local transformers folder
|
|
184
|
+
simu = Simu(auto_select="custom",
|
|
185
|
+
custom_model="/home/user/my-finetuned-model/")
|
|
186
|
+
|
|
187
|
+
# GGUF file via llama.cpp (pip install mskit[gguf])
|
|
188
|
+
simu = Simu(auto_select="custom",
|
|
189
|
+
custom_model="/home/user/mistral-7b-q4.gguf")
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### OpenCTV — Traffic Cameras
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
from mskit import OpenCTV
|
|
196
|
+
|
|
197
|
+
ctv = OpenCTV()
|
|
198
|
+
|
|
199
|
+
# Sources available — all free, no API key needed
|
|
200
|
+
print(ctv.sources)
|
|
201
|
+
# ['singapore', 'london_tfl', 'sydney_rms', 'portland_or']
|
|
202
|
+
|
|
203
|
+
# Find cameras near a location
|
|
204
|
+
cams = ctv.cameras_near(1.3521, 103.8198, radius_km=2) # Singapore
|
|
205
|
+
cams = ctv.cameras_near(51.5074, -0.1278, radius_km=1) # London
|
|
206
|
+
|
|
207
|
+
# Get snapshot URL
|
|
208
|
+
cam = cams[0]
|
|
209
|
+
print(cam.image_url) # live JPEG URL
|
|
210
|
+
fresh = ctv.snapshot(cam) # refresh URL
|
|
211
|
+
|
|
212
|
+
# Structured reading near a point
|
|
213
|
+
reading = ctv.reading_at(1.3521, 103.8198)
|
|
214
|
+
print(reading.cameras_used) # 4
|
|
215
|
+
print(reading.image_url) # nearest camera snapshot
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Traffic (flow data)
|
|
219
|
+
|
|
220
|
+
```python
|
|
221
|
+
from mskit import DEMLoader, TrafficRouter
|
|
222
|
+
|
|
223
|
+
router = TrafficRouter(DEMLoader())
|
|
224
|
+
info = router.traffic_at(51.5074, -0.1278) # London
|
|
225
|
+
print(info.speed_kmh) # 42.3
|
|
226
|
+
print(info.congestion_level) # "moderate"
|
|
227
|
+
print(info.source) # "utd19" or "osrm" or "synthetic"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Simulations (direct API)
|
|
231
|
+
|
|
232
|
+
```python
|
|
233
|
+
from mskit import DEMLoader, RandomWalk, Projectile, WaterFlow, TerrainAgent
|
|
234
|
+
|
|
235
|
+
loader = DEMLoader()
|
|
236
|
+
|
|
237
|
+
# Slope-biased random walk
|
|
238
|
+
rw = RandomWalk(loader, lat=35.68, lon=139.69, slope_bias=0.6)
|
|
239
|
+
path = rw.run(steps=500)
|
|
240
|
+
|
|
241
|
+
# Ballistic trajectory over real terrain
|
|
242
|
+
proj = Projectile(loader, lat=35.36, lon=138.73,
|
|
243
|
+
elevation_deg=45, azimuth_deg=90, speed_ms=80)
|
|
244
|
+
traj = proj.run()
|
|
245
|
+
|
|
246
|
+
# D8 water runoff routing
|
|
247
|
+
wf = WaterFlow(loader, patch_km=10)
|
|
248
|
+
flow = wf.run(lat=47.38, lon=8.54)
|
|
249
|
+
|
|
250
|
+
# RL agent navigation episode
|
|
251
|
+
agent = TerrainAgent(loader, 35.68, 139.69, 35.73, 139.74)
|
|
252
|
+
episode = agent.generate_episode(max_steps=300)
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## 📡 Traffic Sources — Priority Order
|
|
258
|
+
|
|
259
|
+
| Priority | Source | Coverage | Data |
|
|
260
|
+
|---|---|---|---|
|
|
261
|
+
| 1st | **OpenTraffic / OSRM** | Global road network | Live speeds, routing |
|
|
262
|
+
| 2nd | **UTD19 (ETH Zurich)** | 40 cities, 23,541 detectors | Flow, occupancy, speed |
|
|
263
|
+
| 3rd | **Synthetic** | Everywhere | Slope + time-of-day estimate |
|
|
264
|
+
|
|
265
|
+
## 📷 Camera Sources (OpenCTV)
|
|
266
|
+
|
|
267
|
+
| Source | Region | Cameras | Refresh | Key needed |
|
|
268
|
+
|---|---|---|---|---|
|
|
269
|
+
| `singapore` | Singapore | 87 | 20 s | ❌ None |
|
|
270
|
+
| `london_tfl` | London, UK | 900+ | ~30 s | ❌ None (optional for rate limits) |
|
|
271
|
+
| `sydney_rms` | Sydney, AU | 100+ | 1 min | ❌ None |
|
|
272
|
+
| `portland_or` | Oregon, US | 200+ | 2 min | ❌ None |
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## 🗂 Project Structure
|
|
277
|
+
|
|
278
|
+
```
|
|
279
|
+
mskit/
|
|
280
|
+
├── mskit/
|
|
281
|
+
│ ├── __init__.py # top-level exports
|
|
282
|
+
│ ├── cli.py # unified CLI (mskit command)
|
|
283
|
+
│ ├── dem.py # DEMTile + DEMLoader (AW3D30)
|
|
284
|
+
│ ├── sims/
|
|
285
|
+
│ │ ├── random_walk.py # slope-biased walk
|
|
286
|
+
│ │ ├── projectile.py # ballistic trajectory
|
|
287
|
+
│ │ ├── flow.py # D8 water runoff
|
|
288
|
+
│ │ └── agent.py # RL terrain agent
|
|
289
|
+
│ ├── traffic/
|
|
290
|
+
│ │ ├── opentraffic.py # OSRM routing layer
|
|
291
|
+
│ │ ├── utd19.py # ETH Zurich loop detectors
|
|
292
|
+
│ │ ├── router.py # unified TrafficRouter
|
|
293
|
+
│ │ └── openctv.py # OpenCTV camera feeds
|
|
294
|
+
│ └── simu/
|
|
295
|
+
│ ├── intent.py # rule-based NLU intent parser
|
|
296
|
+
│ └── simu.py # Simu AI assistant
|
|
297
|
+
├── pyproject.toml
|
|
298
|
+
└── README.md
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## 🤗 Dataset
|
|
304
|
+
|
|
305
|
+
Elevation tiles are streamed lazily from:
|
|
306
|
+
**[MegaBites-AI/AW3D30-DEM-Tiles](https://huggingface.co/datasets/MegaBites-AI/AW3D30-DEM-Tiles)**
|
|
307
|
+
|
|
308
|
+
- JAXA AW3D30 global 30m DSM/DEM
|
|
309
|
+
- HiRISE tiles for select regions
|
|
310
|
+
- MSKit wheel + source files
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## 📄 License
|
|
315
|
+
|
|
316
|
+
MIT © MegaBites AI Team
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
# MSKit — Mini Simulation Kit
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/mskit/)
|
|
4
|
+
[](https://huggingface.co/datasets/MegaBites-AI/AW3D30-DEM-Tiles)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://python.org)
|
|
7
|
+
|
|
8
|
+
A lightweight Python library for **terrain-based simulations** powered by real-world elevation, live traffic, open camera feeds, and an embedded AI assistant named **Simu**.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## ✨ Features
|
|
13
|
+
|
|
14
|
+
| Module | What it does |
|
|
15
|
+
|---|---|
|
|
16
|
+
| **DEMLoader** | Streams JAXA AW3D30 30m elevation tiles lazily from HuggingFace |
|
|
17
|
+
| **TrafficRouter** | Auto-selects OpenTraffic → UTD19 → synthetic fallback |
|
|
18
|
+
| **OpenCTV** | Aggregates free public traffic camera feeds (Singapore, London, Sydney, Oregon) |
|
|
19
|
+
| **Simu** | Embedded AI assistant — understands plain English, runs the right sim |
|
|
20
|
+
| **CLI** (`mskit`) | Full interactive terminal with all features in one place |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 🚀 Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# Core (terrain + traffic + cameras + rule-based Simu)
|
|
28
|
+
pip install mskit
|
|
29
|
+
|
|
30
|
+
# With AI brain (SmolLM2-360M, ~700 MB downloaded once)
|
|
31
|
+
pip install mskit[llm]
|
|
32
|
+
|
|
33
|
+
# With GGUF support (your own .gguf model)
|
|
34
|
+
pip install mskit[gguf]
|
|
35
|
+
|
|
36
|
+
# Everything
|
|
37
|
+
pip install mskit[all]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 🖥️ CLI — One command to rule them all
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
mskit # full interactive mode
|
|
46
|
+
mskit --brain untrained --mode custom # skip both prompts
|
|
47
|
+
mskit --brain huggingface --mode everything # SmolLM2 + run all 6 sims
|
|
48
|
+
mskit --lat 51.5074 --lon -0.1278 # start in London
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Startup flow
|
|
52
|
+
|
|
53
|
+
When you run `mskit`, Simu guides you through two steps:
|
|
54
|
+
|
|
55
|
+
**Step 1 — Choose AI Brain:**
|
|
56
|
+
```
|
|
57
|
+
╔══════════════════════════════════════════════════════════════╗
|
|
58
|
+
║ 🤖 Simu — Step 1: Choose Your AI Brain ║
|
|
59
|
+
╠══════════════════════════════════════════════════════════════╣
|
|
60
|
+
║ 1. untrained — Rule-based parser. Instant, no download. ║
|
|
61
|
+
║ 2. huggingface — SmolLM2-360M-Instruct ★ recommended ★ ║
|
|
62
|
+
║ 3. custom — HF repo ID / local folder / .gguf file ║
|
|
63
|
+
╚══════════════════════════════════════════════════════════════╝
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**Step 2 — Choose Simulation Mode:**
|
|
67
|
+
```
|
|
68
|
+
╔══════════════════════════════════════════════════════════════╗
|
|
69
|
+
║ 🎮 Simu — Step 2: Choose Simulation Mode ║
|
|
70
|
+
╠══════════════════════════════════════════════════════════════╣
|
|
71
|
+
║ 1. random — Simu surprises you with a random sim ║
|
|
72
|
+
║ 2. custom — You describe exactly what you want ║
|
|
73
|
+
║ 3. everything — Run all 6 simulations at once ║
|
|
74
|
+
╚══════════════════════════════════════════════════════════════╝
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### CLI commands
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
<natural language> Run a simulation (Simu handles it)
|
|
81
|
+
cameras List cameras near current location
|
|
82
|
+
cameras <city/lat,lon> Cameras near a specific place
|
|
83
|
+
cameras sources Show all camera sources
|
|
84
|
+
camera snap <id> Refresh snapshot URL for a camera
|
|
85
|
+
location <city/lat,lon> Change default location
|
|
86
|
+
location Show current location
|
|
87
|
+
switch brain Re-pick AI brain
|
|
88
|
+
switch sim Re-pick simulation mode
|
|
89
|
+
history Show session sim history
|
|
90
|
+
help Full command reference
|
|
91
|
+
quit Exit
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 🐍 Python API
|
|
97
|
+
|
|
98
|
+
### Simu — AI Assistant
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from mskit import Simu, DEMLoader, TrafficRouter
|
|
102
|
+
|
|
103
|
+
loader = DEMLoader()
|
|
104
|
+
router = TrafficRouter(loader)
|
|
105
|
+
|
|
106
|
+
# Interactive startup (brain + sim mode prompts)
|
|
107
|
+
simu = Simu(dem_loader=loader, traffic_router=router)
|
|
108
|
+
|
|
109
|
+
# Skip prompts programmatically
|
|
110
|
+
simu = Simu(
|
|
111
|
+
dem_loader=loader,
|
|
112
|
+
traffic_router=router,
|
|
113
|
+
auto_select="huggingface", # or "untrained" / "custom"
|
|
114
|
+
auto_simmode="custom", # or "random" / "everything"
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
# Chat in plain English
|
|
118
|
+
result = simu.chat("Run a random walk in Tokyo for 1000 steps")
|
|
119
|
+
result = simu.chat("Shoot a projectile from Mount Fuji east at 45° 80 m/s")
|
|
120
|
+
result = simu.chat("What's the traffic like in London?")
|
|
121
|
+
result = simu.chat("Simulate water flow in Zurich")
|
|
122
|
+
result = simu.chat("Navigate an agent from 35.6,139.7 to 35.65,139.75")
|
|
123
|
+
|
|
124
|
+
# Run all 6 simulations at once
|
|
125
|
+
results = simu.run_all("Tokyo")
|
|
126
|
+
|
|
127
|
+
# Switch brain/mode mid-session
|
|
128
|
+
simu.switch_brain()
|
|
129
|
+
simu.switch_sim_mode()
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Custom brain (your own model)
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
# HuggingFace repo
|
|
136
|
+
simu = Simu(auto_select="custom",
|
|
137
|
+
custom_model="mistralai/Mistral-7B-Instruct-v0.3")
|
|
138
|
+
|
|
139
|
+
# Local transformers folder
|
|
140
|
+
simu = Simu(auto_select="custom",
|
|
141
|
+
custom_model="/home/user/my-finetuned-model/")
|
|
142
|
+
|
|
143
|
+
# GGUF file via llama.cpp (pip install mskit[gguf])
|
|
144
|
+
simu = Simu(auto_select="custom",
|
|
145
|
+
custom_model="/home/user/mistral-7b-q4.gguf")
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### OpenCTV — Traffic Cameras
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
from mskit import OpenCTV
|
|
152
|
+
|
|
153
|
+
ctv = OpenCTV()
|
|
154
|
+
|
|
155
|
+
# Sources available — all free, no API key needed
|
|
156
|
+
print(ctv.sources)
|
|
157
|
+
# ['singapore', 'london_tfl', 'sydney_rms', 'portland_or']
|
|
158
|
+
|
|
159
|
+
# Find cameras near a location
|
|
160
|
+
cams = ctv.cameras_near(1.3521, 103.8198, radius_km=2) # Singapore
|
|
161
|
+
cams = ctv.cameras_near(51.5074, -0.1278, radius_km=1) # London
|
|
162
|
+
|
|
163
|
+
# Get snapshot URL
|
|
164
|
+
cam = cams[0]
|
|
165
|
+
print(cam.image_url) # live JPEG URL
|
|
166
|
+
fresh = ctv.snapshot(cam) # refresh URL
|
|
167
|
+
|
|
168
|
+
# Structured reading near a point
|
|
169
|
+
reading = ctv.reading_at(1.3521, 103.8198)
|
|
170
|
+
print(reading.cameras_used) # 4
|
|
171
|
+
print(reading.image_url) # nearest camera snapshot
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Traffic (flow data)
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
from mskit import DEMLoader, TrafficRouter
|
|
178
|
+
|
|
179
|
+
router = TrafficRouter(DEMLoader())
|
|
180
|
+
info = router.traffic_at(51.5074, -0.1278) # London
|
|
181
|
+
print(info.speed_kmh) # 42.3
|
|
182
|
+
print(info.congestion_level) # "moderate"
|
|
183
|
+
print(info.source) # "utd19" or "osrm" or "synthetic"
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Simulations (direct API)
|
|
187
|
+
|
|
188
|
+
```python
|
|
189
|
+
from mskit import DEMLoader, RandomWalk, Projectile, WaterFlow, TerrainAgent
|
|
190
|
+
|
|
191
|
+
loader = DEMLoader()
|
|
192
|
+
|
|
193
|
+
# Slope-biased random walk
|
|
194
|
+
rw = RandomWalk(loader, lat=35.68, lon=139.69, slope_bias=0.6)
|
|
195
|
+
path = rw.run(steps=500)
|
|
196
|
+
|
|
197
|
+
# Ballistic trajectory over real terrain
|
|
198
|
+
proj = Projectile(loader, lat=35.36, lon=138.73,
|
|
199
|
+
elevation_deg=45, azimuth_deg=90, speed_ms=80)
|
|
200
|
+
traj = proj.run()
|
|
201
|
+
|
|
202
|
+
# D8 water runoff routing
|
|
203
|
+
wf = WaterFlow(loader, patch_km=10)
|
|
204
|
+
flow = wf.run(lat=47.38, lon=8.54)
|
|
205
|
+
|
|
206
|
+
# RL agent navigation episode
|
|
207
|
+
agent = TerrainAgent(loader, 35.68, 139.69, 35.73, 139.74)
|
|
208
|
+
episode = agent.generate_episode(max_steps=300)
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 📡 Traffic Sources — Priority Order
|
|
214
|
+
|
|
215
|
+
| Priority | Source | Coverage | Data |
|
|
216
|
+
|---|---|---|---|
|
|
217
|
+
| 1st | **OpenTraffic / OSRM** | Global road network | Live speeds, routing |
|
|
218
|
+
| 2nd | **UTD19 (ETH Zurich)** | 40 cities, 23,541 detectors | Flow, occupancy, speed |
|
|
219
|
+
| 3rd | **Synthetic** | Everywhere | Slope + time-of-day estimate |
|
|
220
|
+
|
|
221
|
+
## 📷 Camera Sources (OpenCTV)
|
|
222
|
+
|
|
223
|
+
| Source | Region | Cameras | Refresh | Key needed |
|
|
224
|
+
|---|---|---|---|---|
|
|
225
|
+
| `singapore` | Singapore | 87 | 20 s | ❌ None |
|
|
226
|
+
| `london_tfl` | London, UK | 900+ | ~30 s | ❌ None (optional for rate limits) |
|
|
227
|
+
| `sydney_rms` | Sydney, AU | 100+ | 1 min | ❌ None |
|
|
228
|
+
| `portland_or` | Oregon, US | 200+ | 2 min | ❌ None |
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## 🗂 Project Structure
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
mskit/
|
|
236
|
+
├── mskit/
|
|
237
|
+
│ ├── __init__.py # top-level exports
|
|
238
|
+
│ ├── cli.py # unified CLI (mskit command)
|
|
239
|
+
│ ├── dem.py # DEMTile + DEMLoader (AW3D30)
|
|
240
|
+
│ ├── sims/
|
|
241
|
+
│ │ ├── random_walk.py # slope-biased walk
|
|
242
|
+
│ │ ├── projectile.py # ballistic trajectory
|
|
243
|
+
│ │ ├── flow.py # D8 water runoff
|
|
244
|
+
│ │ └── agent.py # RL terrain agent
|
|
245
|
+
│ ├── traffic/
|
|
246
|
+
│ │ ├── opentraffic.py # OSRM routing layer
|
|
247
|
+
│ │ ├── utd19.py # ETH Zurich loop detectors
|
|
248
|
+
│ │ ├── router.py # unified TrafficRouter
|
|
249
|
+
│ │ └── openctv.py # OpenCTV camera feeds
|
|
250
|
+
│ └── simu/
|
|
251
|
+
│ ├── intent.py # rule-based NLU intent parser
|
|
252
|
+
│ └── simu.py # Simu AI assistant
|
|
253
|
+
├── pyproject.toml
|
|
254
|
+
└── README.md
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## 🤗 Dataset
|
|
260
|
+
|
|
261
|
+
Elevation tiles are streamed lazily from:
|
|
262
|
+
**[MegaBites-AI/AW3D30-DEM-Tiles](https://huggingface.co/datasets/MegaBites-AI/AW3D30-DEM-Tiles)**
|
|
263
|
+
|
|
264
|
+
- JAXA AW3D30 global 30m DSM/DEM
|
|
265
|
+
- HiRISE tiles for select regions
|
|
266
|
+
- MSKit wheel + source files
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## 📄 License
|
|
271
|
+
|
|
272
|
+
MIT © MegaBites AI Team
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""
|
|
2
|
+
MSKit — Mini Simulation Kit
|
|
3
|
+
============================
|
|
4
|
+
Terrain-based simulations powered by real-world data:
|
|
5
|
+
* JAXA AW3D30 30m elevation (global, lazy-streamed from HuggingFace)
|
|
6
|
+
* OpenTraffic / OSRM — live road speeds, global
|
|
7
|
+
* UTD19 — 40 cities, 23 541 loop detectors (ETH Zurich)
|
|
8
|
+
* OpenCTV — free public traffic cameras (SG, London, NYC)
|
|
9
|
+
* Simu — built-in AI assistant (SmolLM2-360M, open-source)
|
|
10
|
+
|
|
11
|
+
Dataset : https://huggingface.co/datasets/MegaBites-AI/AW3D30-DEM-Tiles
|
|
12
|
+
GitHub : https://github.com/MegaBites-AI/MSKit
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from .dem import DEMTile, DEMLoader
|
|
16
|
+
from .sims.random_walk import RandomWalk
|
|
17
|
+
from .sims.projectile import Projectile
|
|
18
|
+
from .sims.flow import WaterFlow
|
|
19
|
+
from .sims.agent import TerrainAgent
|
|
20
|
+
from .traffic import OpenTrafficLayer, UTD19Layer, TrafficRouter, OpenCTVLayer
|
|
21
|
+
from .simu import Simu
|
|
22
|
+
|
|
23
|
+
__version__ = "0.6.0"
|
|
24
|
+
__author__ = "MegaBites AI Team"
|
|
25
|
+
__dataset__ = "MegaBites-AI/AW3D30-DEM-Tiles"
|
|
26
|
+
__github__ = "https://github.com/MegaBites-AI/MSKit"
|
|
27
|
+
|
|
28
|
+
__all__ = [
|
|
29
|
+
"DEMTile", "DEMLoader",
|
|
30
|
+
"RandomWalk", "Projectile", "WaterFlow", "TerrainAgent",
|
|
31
|
+
"OpenTrafficLayer", "UTD19Layer", "TrafficRouter", "OpenCTVLayer",
|
|
32
|
+
"Simu",
|
|
33
|
+
]
|