3D-RAMS

3D-RAMS is a hackathon AgentCore agent that turns rough site-visit intent into an inspectable 3D pre-visit review pack.

Demo Video

Pitch deck:

3D-RAMS pitch deck

Quickstart

Start from the hosted entry point:

https://dev-chunteng.d1nxhx6zr27p5p.amplifyapp.com/

AgentVerse Agent: https://agentverse.ai/agents/details/agent1q2ujkw4l89efcfkfj597zlnh2jl5cqe89pgxteemqxpw0uwr0ggvy8c5u9t/profile

Send the prompt, review the confirmation card, then enter Confirm launch.

Recommended ASIO/FieldBrief prompt:

Start a new 3D-RAMS report, not an iteration of any existing case. Site location: 8 Albert Embankment, London SE1 7SP. Area scope: 2000m radius. Goal/task: generic site trip safety pre-visit review pack. Please prepare a non-certified pre-visit RAMS-style review pack and ask me to confirm the intake before launch.

A fresh hosted supervisor workflow currently takes about 4-5 minutes. For demos, reviews, and quick teammate orientation, open one of these already generated public-demo reports first:

Case	Input style	What it demonstrates
case_2e6720b4c5fb	Full address: 8 Albert Embankment	Address-led Lambeth / Thames-side site context using the cached public fixture report path.
case_d1bbfcb4b0de	Postcode: N7 7AJ	Emirates Stadium / Ashburton Grove postcode intake with derived coordinate context.
case_foxglove_local_876c3fe4	Coordinates: 54.9712, -2.1013	Foxglove Farm Solar Site coordinate-led PV inspection context.
case_fec98aaddca0	Address and postcode: Harringay / N4 4QP	Harringay postcode/address intake with derived coordinate context.

Problem Statement

Site teams preparing for unfamiliar rural, development, or infrastructure visits have to combine maps, terrain, access routes, planning records, document evidence, and risk notes before they can form a useful briefing. 3D-RAMS explores whether an agent can turn that fragmented digital work into an inspectable 3D pre-visit pack with evidence, annotations, trace, confidence labels, and a visible safety boundary.

Read the full problem statement in docs/problem-statement.md.

Architecture At A Glance

The supervisor workflow starts from the ASI:ONE entry point or our own FieldBrief pnale, where the user's site request is turned into a resolved location and review area. The supervisor then creates an investigation plan covering the target area, required sources, and expected report structure.

Specialist subagents are dispatched for geospatial context, planning and document review, hazard/RAMS scoping, and open-web intelligence. These agents use defined project tools, source loaders, cached fixtures, APIs, and Tavily search where relevant.

Each subagent returns evidence packets containing facts, references, confidence labels, and trace metadata. The supervisor performs a reasoning pass over that evidence, checks relevance against the report structure, and produces structured JSON with references and inference notes. The frontend renders this as an interactive report with a 3D scene, evidence, references, trace, and review status.

Human-in-the-loop review closes the workflow: users can inspect the evidence, trace, and review status, then provide feedback that identifies gaps, corrects weak assumptions, and guides the next improvement cycle.

3D-RAMS uses AWS AgentCore as the agent runtime framework. The project is developed and packaged with the AgentCore CLI, following the service's recommended runtime, harness, packaging, and deployment patterns as closely as practical for a hackathon demo.

The team also used Alive24/shea-symphony, developed by a teammate, to coordinate development work. Shea Symphony provides automated orchestration around Issue Contracts, Agentic Review, Guided Human Review, and Agentic Merging; the active project board is visible at Capitano00 Project 1, view 6.

Local Demo Workflow

1. User enters a coordinate, confirms an entry-agent intake, or explicitly selects the cached public Lambeth data pack.
2. The AgentCore runtime resolves live-enabled source context, an explicit fixture pack, or synthetic fallback.
3. The agent loads live Planning Data geospatial context when enabled, or cached-public, synthetic, or fallback geospatial features.
4. The agent builds a Cesium scene configuration.
5. The agent loads cached-public or synthetic planning/context notes.
6. The agent extracts candidate hazard notes.
7. The agent creates 3D annotations.
8. The agent generates a RAMS-style briefing.
9. A safety gate blocks certified RAMS, work approval, and emergency guidance claims.
10. The UI shows the 3D scene, briefing, evidence register, trace, and architecture visualizer.

Current Progress Snapshot

Current dev-chunteng has the ASIO-shaped confirm-before-launch flow working end to end in the repo contract:

• @3d-rams and FieldBrief can collect site, area, and goal, then show a confirmation card before supervisor launch.
• Confirmed launches produce a caseId; hosted ASIO replies can append a full report link when PUBLIC_FRONTEND_BASE_URL is set.
• Case report pages can open by caseId for the current public-demo flow. Real ASIO identity-bound lookup is still a future hardening step.
• Report iteration and versioning are represented in the entry contract; authorized iteration should use the previous report as the base instead of regenerating from scratch.
• The report UI now surfaces status, review gate, data-quality summary, risk cards grounded in structuredReport.findings, source disclosure in Evidence/Trace, and the terrain-backed Cesium scene.
• Source paths include live-enabled geospatial/city/planning/open-web adapters with cached or synthetic fallbacks, plus an independent review loop and safety boundary.

Real vs Mocked

Component	Demo1 Status	Notes
Agent workflow	Real Python code	Tool sequence, evidence, trace, safety gate, deterministic fallback, and response shape are implemented.
Entry intake	Real AgentCore entry runtime plus ASIO adapter	asi_one_entry_agent owns clarification, confirmation, launch, status, and report lookup. FieldBrief simulates this path for development.
Public data pack	Cached public fixture	fixtures/public-lambeth-thames includes source metadata for a Lambeth / Thames public-data pack anchored on 8 Albert Embankment.
Live model briefing	Optional hosted gateway path	Uses the OpenAI-compatible gateway when ENABLE_LIVE_MODEL=true and gateway credentials are configured; deterministic briefing remains the fallback.
3D viewer	Real React/Vite + CesiumJS UI	Uses a token-free Cesium canvas plus local scene overlay and annotations.
Geospatial features	Live-enabled with cached/synthetic fallback	FieldBrief live defaults do not request a fixture pack; explicit fixture mode uses cached public-source metadata, and synthetic fallback uses fixtures/geospatial_features.json.
Planning/open-web/context notes	Live-enabled with cached/synthetic fallback	Planning/city/open-web paths are bounded and source-labelled; disabled or failed live calls degrade into visible caveats instead of hidden claims.
Report store and lookup	Demo-live when configured	caseId reports can be persisted and opened from a hosted report link. Current public-demo lookup can bypass ASIO identity; real ASIO-issued identity artifacts remain future work.
AWS / hosted	Partially live when configured	AgentCore runtimes, Harnesses, signed proxy, DynamoDB report store, and the OpenAI-compatible model gateway can be configured; no-AWS remains the fallback baseline.
Google Maps / Earth / 3D Tiles	Not used	Kept out of Demo1 to avoid key, cost, licensing, and freshness risk.

For contribution expectations, safety boundaries, and handoff checklist, see CONTRIBUTING.md.

For AgentCore invocation shape and validation behavior, see docs/api-contract.md.

For the AgentVerse entry-agent and AWS AgentCore adapter boundary, see docs/agentverse-agentcore-adapter-contract.md and ADR 0004.

For the imported ASI:ONE / AgentVerse proof of concept runtime and @3d-rams hosted adapter shape, see docs/agentverse-asi-one-runtime.md.

For source-connected hosted frontend deployment through Amplify, see docs/amplify-hosting.md and ADR 0006. Amplify hosts the React/Vite frontend only; AgentCore runtimes, Harnesses, and signed proxy secrets stay outside frontend source control.

To run the full local verification stack before sharing changes in Codespaces/Linux/macOS:

bash scripts/check-demo.sh

On a fresh Codespace or local clone, install dependencies as part of the check:

bash scripts/check-demo.sh --install

On Windows PowerShell:

powershell -ExecutionPolicy Bypass -File scripts/check-demo.ps1

On a fresh Windows clone:

powershell -ExecutionPolicy Bypass -File scripts/check-demo.ps1 -Install

The check runs AgentCore package tests, deterministic evaluation, frontend production build, and a no-AWS HTTP runtime smoke against AgentCore and the frontend preview.

For hosted AgentCore + ASI/ASI:ONE parity after cloud resources are deployed, run:

RAMS_HOSTED_ENTRY_URL=https://<signed-proxy-domain>/invoke \
python3 scripts/hosted-agentcore-asio-smoke.py

That hosted smoke starts at asi_one_entry_agent, verifies supervisor launch, report-store write, identity-bound lookup, authorized/denied material references, and emits only redacted public-safe output.

OpenAI-Compatible Live Model Mode

The app defaults to deterministic fallback unless the AgentCore runtime is started with the OpenAI-compatible gateway enabled.

Keep gateway URLs and API keys in hosted secrets or a local untracked .env. Do not commit real credentials, signed URLs, runtime ARNs, account IDs, or private session details.

Recommended local settings:

ENABLE_LIVE_MODEL=true
RAMS_LLM_PROVIDER=openai
ENTRY_AGENT_PROVIDER=openai
ENTRY_INTAKE_PROVIDER=openai
ENTRY_INTAKE_FALLBACK=disabled
OPENAI_BASE_URL=https://<gateway-host>/v1
OPENAI_API_KEY=<local-or-hosted-secret>
OPENAI_MODEL=gpt-5.4-mini

Default public-source context:

OSM_USER_AGENT="3D-RAMS-Demo/0.1 (+https://github.com/Capitano00/3D-RAMS)"

Bounded Overpass context is enabled by default for confirmed coordinates. Nominatim geocoding is also enabled by default for missing-coordinate public demo text; set ENABLE_LIVE_NOMINATIM_GEOCODING=false to keep location text out of public geocoding.

Run a low-volume smoke test:

python3 scripts/openai-gateway-smoke.py

The UI shows whether FieldBrief is using the OpenAI-compatible entry path. Legacy Bedrock provider settings remain explicit opt-in only; bedrock-agentcore names still refer to AWS AgentCore service/package plumbing.

Local Developer Quickstart

AgentCore runtime:

agentcore dev --runtime rams_supervisor_runtime --skip-deploy --no-browser --no-traces --logs --port 8080

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

Health check:

curl http://localhost:8080/ping

AgentCore invocation:

curl -X POST http://localhost:8080/invocations ^
  -H "Content-Type: application/json" ^
  -d "{\"input\":{\"latitude\":52.2053,\"longitude\":-1.6022}}"

AWS / Hosted Path

Demo1 trace and response objects are shaped to map naturally to an AWS implementation:

• ASI/ASI:ONE or AgentVerse as the product entry surface.
• A signed proxy as a transport bridge to the asi_one_entry_agent runtime.
• AgentCore asi_one_entry_agent for intake, clarification, confirmation, and delivery summary.
• AgentCore rams_supervisor_runtime for orchestration, evidence, trace, report assembly, and report lookup.
• OpenAI-compatible hosted gateway for the live model-assisted briefing step.
• DynamoDB for versioned project state and rollback records.
• S3 for evidence packs, exported briefings, screenshots, and source documents.
• CloudWatch for trace, latency, cost, and failure visibility.
• Guardrails for unsafe claim and policy filtering.

Safety Boundary

This project does not produce certified RAMS, emergency response instructions, work approval, or competent-person replacement. It produces an inspectable pre-visit review pack for human review.