NAVIX

AI-powered maritime procurement, chartering, voyage planning, and decision intelligence platform.

This repository now includes a working foundation for the first three NAVIX modules described in the product docs:

• 01 Data Fabric
• 02 Maritime Knowledge Platform
• 03 Market Intelligence Engine

The implementation is intentionally simple and deterministic so we can validate the decision pipeline before adding deeper optimization, risk, and workflow layers.

What Was Built

01 Data Fabric

• Reads raw maritime source files from data/raw
• Validates required fields
• Normalizes units and casing
• Deduplicates records
• Writes curated JSON outputs to data/curated

02 Maritime Knowledge Platform

• Loads canonical entities for ports, vessels, routes, and market observations
• Acts as the shared domain access layer for downstream modules
• Provides feasibility checks for vessel-to-port compatibility

03 Market Intelligence Engine

• Forecasts route and vessel-class freight movement
• Produces trend, confidence, volatility, and procurement signal
• Returns explainable reasoning for the generated signal

Project Structure

data/
  raw/                  # sample freight, port, vessel, and route datasets
  curated/              # generated normalized outputs
src/navix/
  data_fabric/          # ingestion, validation, normalization
  domain/               # canonical maritime entities and repository
  market_intelligence/  # interpretable forecast and signal logic
  pipeline.py           # end-to-end runner for the first 3 modules
tests/

Sample Data Included

The foundation includes local sample datasets for:

• Freight market observations
• Port constraints and congestion
• Vessel specifications and availability
• Trade routes

These datasets are enough to run the first three modules together without depending on external APIs yet.

Run The Pipeline

python run_navix.py

The command will:

1. Ingest and curate the raw source data
2. Load the maritime knowledge platform
3. Forecast the AUSTRALIA -> INDIA_EAST / PANAMAX market
4. Return a JSON summary including feasible vessels for Paradip

Run Tests

pytest

Notes

• The attached markdown documents remain the product and architecture references.
• This code treats those documents as design guidance, not executable instructions.

Live Collection And Port Master

The repository now includes a source-aware collection layer and the initial Port Master Database implementation.

• navix.collectors fetches public, live data from Paradip Port Authority, Open-Meteo Marine, and Frankfurter FX. Every row includes source URL and UTC fetch time and is saved as an immutable-looking snapshot in data/collected.
• supabase/migrations/20260902_port_master.sql creates ports, terminals, berths, source_records, and collection-run tables. It includes RLS so the public UI only reads the derived port-master data, not raw source payloads.
• ui/port-master is a dependency-free graph browser. Open it through any local static server to explore Port -> Terminal -> Berth relationships.

Run a live collection locally:

python run_collectors.py

Then apply the SQL migration in the Supabase SQL editor, set the environment variables below, and collect plus upload:

$env:SUPABASE_URL = "https://YOUR_PROJECT.supabase.co"
$env:SUPABASE_SERVICE_ROLE_KEY = "YOUR_SERVER_ONLY_SERVICE_ROLE_KEY"
python run_collect_and_upload.py

Never put the service-role key in the browser or commit it to the repository. The service_role key is required because source ingestion writes through RLS. The uploader automatically loads a .env file in the project root; shell environment variables take precedence over it.

To connect the graph UI, copy ui/port-master/config.example.js to config.js, provide the project URL and browser-safe anon key, and serve ui/port-master through a static web server. The UI falls back to the checked-in example data when no Supabase configuration is present.

Feed Coverage And Boundaries

Data class	Current connector	Status
Port and berths	Paradip Port Authority published berth table	Live public collector
Weather	Open-Meteo Marine	Live public API collector
USD/INR	Frankfurter / ECB reference rate	Live public API collector
Freight, vessel registry, AIS, congestion, coal/bunker, PMI/GDP	Provider adapter boundary	Requires licensed/authenticated provider or a customer data feed

Freight benchmarks, AIS positions, and global vessel particulars should not be scraped from consumer websites: terms, rate limits, and licensing frequently prohibit it, and the results are not reliable enough for chartering decisions. Add a permitted provider token or a licensed CSV/API feed at the collector boundary, retaining the same provenance fields used by the public collectors.

One-Time Training Seeds

Run the following once to collect real historical weather and USD/INR data, upload those source records to Supabase, and generate separate synthetic port/weather/macro scenarios:

python run_bootstrap_training_data.py

The generated scenarios are marked synthetic: true, retain the IDs of their real source records, and are suitable for workflow and compatibility testing. They are deliberately excluded from freight-price model targets. A trained freight model requires at least 100 real observed freight records from a licensed Baltic Exchange or route-rate provider. The Command Center therefore refuses production freight forecasts until that threshold is reached; data/raw/freight_market.csv remains a demo-only input for the original foundation runner.

Major Port Registry

The Port Master collects the Ministry's 12 currently operating major port authorities and displays them in the graph. The Ministry reports 14 major ports in total, but its current authority list identifies only 12 as operating; the two remaining ports are not inferred. Paradip has detailed berth records from its authority website, while the other operating ports are marked pending until their own official infrastructure sources are ingested.

Command Center Server

Start the integrated local server:

python run_server.py

Open http://127.0.0.1:8000 for the connected Port Master graph. The server also exposes GET /api/command-center, POST /api/forecast, and POST /api/compatibility. It reads Supabase when credentials are configured and falls back to the latest collected snapshot when the database is unavailable.

POST /api/admin/refresh performs a live collection and Supabase upload. It requires the X-NAVIX-ADMIN-TOKEN header to equal NAVIX_ADMIN_TOKEN. Set NAVIX_REFRESH_MINUTES to enable periodic in-process refreshes. For a production deployment, run this application behind a managed WSGI server and move scheduled collection to a dedicated job/worker so multiple web instances do not run the same refresh concurrently.