Revised 18 October 2026 · v1.0.0 · what changed

Code: github.com/herrrickshaw/ship2shore_rag

Watch the walkthrough

Watch on YouTube: youtu.be/VeQHhoIb9F0

What it is for

ship2shore_rag is a search tool for maritime knowledge. It collects open sources (arXiv papers, Wikipedia, UK MAIB and US NTSB accident reports, plus any PDF or Word file you add), splits them into passages, and finds the passages that best match a question. Every result names its source, so you can check it.

It runs in two ways. On shore it uses Postgres with the pgvector add-on. On a vessel it uses one SQLite file, with no server and no internet. Both use the same search method: meaning-based search combined with keyword search, then a reranking step. Writing a final answer with Claude is optional. Without a key, the tool simply shows you the ranked passages.

The repository also has an operations module (vessel, crew, logbook, maintenance, fuel and incident records). This post covers the search side only.

Who it is for

• Ship officers and superintendents who want to look up past incidents and definitions offline
• Researchers and students studying maritime accidents, freight and regulation
• Engineers who want a working example of offline hybrid search (RAG) with citations

What you need

Get the code and an AI assistant

You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:

git clone https://github.com/herrrickshaw/ship2shore_rag.git
cd ship2shore_rag
claude      # or: gemini

Install

1. Clone the repo and create a virtual environment.

   git clone https://github.com/herrrickshaw/ship2shore_rag.git
   cd ship2shore_rag
   python3 -m venv .venv
   source .venv/bin/activate

2. Install the dependencies. This is the full list in requirements.txt, so it takes a few minutes.

   pip install -r requirements.txt

3. Copy the settings file. For offline use, edit .env so it contains the two lines shown.

   cp .env.example .env
   # in .env set:
   # STORAGE_BACKEND=sqlite
   # SQLITE_PATH=snapshots/ship2shore.sqlite3

4. Optional, shore side only: install Postgres and pgvector, then create the schema. Skip this if you only want to search the snapshot.

   brew install postgresql@17 pgvector
   # start Postgres on port 5433 and run createdb as in the README, then:
   python3 cli.py init-db

Quick start: commands and what you should see

Ask a question and get ranked passages only (no API key).

python3 cli.py ask "What are the main causes of engine room fires on cargo ships?" --no-generate

A numbered Sources list, each with a title, URL and a short excerpt. In the demo the top hits were NTSB and arXiv items about an engine failure and an engine room fire, plus a Wikipedia page on container ships. The demo author noted these were only loosely related, because the corpus is small.

Ask a definition question and limit the number of results.

python3 cli.py ask "What is a bill of lading and what does it do?" --no-generate --top-k 3

Three passages. The first two came from the Wikipedia article on the bill of lading and the third from the article on charterparties.

Build a hazard brief for a job.

python3 cli.py hazard-brief "Hot work welding in engine room near fuel oil tanks" --top-k 3

A list of similar past incidents and guidance, each with a link. In the demo it returned an NTSB engine failure report and the Dali bridge contact report. It is retrieval only, not a risk score.

Measure retrieval quality on the 17 test questions in eval/queries.yaml.

python3 cli.py eval

Two summary lines. Rerank off: recall@5 = 0.76 and MRR = 0.706. Rerank on: recall@5 = 0.82 and MRR = 0.824. Questions that found nothing are listed as MISS.

Ways to use it

Sample prompts for your AI assistant

Copy, paste and edit the parts in [brackets].

• Read README.md and ARCHITECTURE.md in this repo and explain in plain English how a question becomes a list of cited passages.
• Set this repo up to run offline from snapshots/ship2shore.sqlite3 and run one question with --no-generate. Tell me each command before you run it.
• I have a folder of [my PDF reports]. Show me how to ingest them with --source file and then ask a question about [topic].
• Run cli.py eval and explain recall@5 and MRR to me as if I had never seen them. Which questions missed, and why might they have?
• Add three questions about [my topic] to eval/queries.yaml with the source I expect each to find, then re-run the eval.
• What would break if I put this on a ship with no internet? List what needs to be downloaded first.

Limits and honest caveats

Sources: the ship2shore_rag README, ARCHITECTURE.md, requirements.txt, .env.example and snapshots/README.md, and the demo run of 18 October 2026.

About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.