TERRANOETIS

Getting started

Platform v3.0.0 Docs v3.0.0 ALL STEPS EXECUTED

Full description: Read the full narrative

Prerequisites

DependencyVersionWhy / evidence
Node.js≥ 20 (.nvmrc pins 20; this review ran Node 26.0.0)package.json engines: {"node": ">=20"}; npm ci/test/build executed successfully under Node 26
Python 3 + NumPy3.14.5 + numpy 2.4.2 observed; scipy optional (hurricane/landslide fall back when absent)local kernels spawn python3 server/kaggle/simRunner.ts:170-175
Redisoptionalhealth check reports redis PONG when present; server falls back to SQLite (see server/infrastructure/redis.ts:graceful degradation)
Cesium Ion tokenoptionalonly for Google Photorealistic 3D Tiles layer; everything else runs without it
Kaggle tokenoptionalonly for the 4 kernels pushed to Kaggle (flood, tsunami, volcano, landslide main runs); not needed for earthquake/wildfire/hurricane or analytical tools

Install and start

Commands

git clone https://github.com/sreyassanker/Terranoetis.git
cd Terranoetis
cp .env.example .env   # keys are optional; features degrade gracefully
npm install
npm run dev            # Vite :3000 + Express :3001 (proxy /api → :3001)

dev runs scripts/dev-prep.js then starts both servers concurrently package.json:16-29; the Vite proxy target and port come from vite.config.ts:73-88. To run only the API: npm run dev:server.

Verify the stack

Commands and the actual observed response

curl -s http://localhost:3001/api/health
# measured (fresh boot, no API keys beyond .env):
# {"status":"degraded","checks":{"db":"ok","gemini":"degraded","memory":"ok",
#  "reflex":"ok","forks":"ok","dream":"ok","entropy":"ok","discovery":"ok",
#  "pubsub":"ok","redis":"ok/PONG"},"uptime_ms":24305,"version":"3.1"}

npm run test:unit          # measured: 141 files, 1,653 tests, 22.85 s, 0 failures
npm run test:integration   # measured: 5 files, 49 tests, 5.66 s, 0 failures

“degraded” is the honest state with optional providers missing — e.g. gemini when no vision key is configured; the server still boots and serves. MEASURED — boot + health observed

First simulation (no credentials needed)

Submit → poll → fetch grid

curl -s -X POST http://localhost:3001/api/kaggle/simulate \
  -H 'Content-Type: application/json' -d '{
    "type":"earthquake_swarm","lat":36.1,"lon":139.7,"grid_size":128,
    "extent_km":100,"magnitude":7.2,"depth_km":15,"vs30":760 }'
# measured: {"jobId":"sim_44d5c7d7","status":"running",
#           "streamUrl":"/api/kaggle/simulate/sim_44d5c7d7/stream"}

curl -s http://localhost:3001/api/kaggle/simulate/sim_44d5c7d7   # status → complete 166 ms after submit (measured)
curl -s http://localhost:3001/api/kaggle/simulate/sim_44d5c7d7/results
curl -s -o pga.npy http://localhost:3001/api/kaggle/simulate/sim_44d5c7d7/grid/pga_cm_s2   # 200, 296,648 bytes (measured)

Wire payloads are validated client-side by a zod discriminated union before submission (bounds mirror the kernels’ own validity checks) src/services/kaggleSim.ts:28-240. The UI path is identical: ScenarioEditor builds the same request src/services/kaggleSim.ts:381-545 and useKaggleSimulation streams job status over SSE src/hooks/useKaggleSimulation.ts:136-159. Full contract: Simulation job API.

What works without any API keys

Feature availability without credentials (verified boot + code paths)
FeatureWithout keysEvidence
Analytical engine (150 tools)Runs; live-context enrichment falls back to honest NaN where data is unreachableserver/analytical-models/engine.ts:170-194
Earthquake / wildfire / hurricane simsRun locally via python3server/kaggle/simRunner.ts:126-175
Flood / tsunami / volcano / landslide simsDisabled until a Kaggle token exists at ~/.kaggle/kaggle.jsonserver/kaggle/simRunner.ts:Kaggle pipeline requires token docs/site/markdown/DEPLOYMENT.md:162-173
AI chat (agent/ask)Needs at least one LLM provider key; local GGUF fallback auto-launches if model downloadedserver/index.ts:789-817
Live-data routesKeyless feeds work (USGS, OpenSky public, EONET…); keyed ones 5xx/disableserver/apiMetadata.ts:82 entries
Sentinel / reflex / world model / memoryRun on keyless feeds or local stateserver/index.ts:14448-14488
Globe (dev)Works without Cesium Ion; photorealistic tiles offvite + src/rendering/photorealisticGlobe.ts

Orientation