🟠 FAROL — AI Agent for Offshore Operations Analytics

Ask in natural language. The agent picks the right analysis tool, Pandas computes over real data, and the answer comes back with exact figures — zero numeric hallucination. Multi-user: each account gets its own conversation memory and personalized shortcuts. Covered offshore domains: supply-vessel logistics (PSV/AHTS/OSRV), drilling rigs (progress & NPT), RPAS flight operations, weather and fleet maintenance — and the tool-calling architecture absorbs new domains (lifting ops, SIMOPS, metocean) as new deterministic tools.

🔗 Live demo: https://farol-9ed3.onrender.com (free tier — first load may take up to a minute while the instance wakes up)

The business problem

An offshore operation generates data all the time — vessel movements, drilling reports, drone flight logs, weather, maintenance — but the people making decisions (operations coordinators, logistics planners, contract inspectors) don't write SQL or open notebooks. Questions like "why did our abort rate go up on P-74?", "how much cargo did we move this quarter?" or "which rig is burning hours in NPT?" take hours to answer by hand.

FAROL answers them in seconds, in natural language, quoting the real numbers.

Why this is not "just a chatbot"

The architecture separates reasoning from computation:

Natural-language question
      │
      ▼
┌─────────────┐    picks the tool        ┌──────────────────┐
│ LLM (Claude) │ ───────────────────────▶│  Pandas engine    │
│ tool-calling │ ◀─────────────────────── │  (analytics.py)   │
└─────────────┘   deterministic numbers   └──────────────────┘
      │                                          │
      ▼                                          ▼
 Written answer                         CSVs: flights, weather,
 quoting the numbers                    maintenance (18 months)

The LLM never computes — it decides which analysis to run and writes up the result. Every number comes from Pandas. If no API key is configured, a local keyword router takes over and the demo stays 100% functional (offline mode).

Stack

Layer	Technology	Role
API	FastAPI + Pydantic	REST endpoints + validation
Auth & profiles	SQLite + PBKDF2 + session cookies (stdlib only)	Email login/signup, per-user question history driving personalization
Knowledge base	SQLite + fuzzy matching (difflib, stdlib)	Human-curated verified answers checked before the LLM; unanswered questions queued for future curation
Agent	Anthropic API (tool use)	Semantic routing + write-up, with per-user conversation memory
Analytics	Pandas	8 deterministic tools across 5 offshore domains
Data	Custom synthetic generator + real DJI logs (AirData CSV import)	3,100+ flights, 1,300+ vessel operations, 1,600+ daily drilling reports — with realistic physics (wind seasonality, battery degradation, gust × abort correlation, weather-driven vessel cancellations and rig NPT)
Reports	fpdf2	One-click PDF export of the full analysis (charts drawn with PDF primitives — no matplotlib)
Frontend	HTML + Chart.js (vanilla)	Four pages — animated login (/login), chat with history sidebar (/), dashboard (/painel), data & import (/dados) — PT/EN i18n, zero build step

Running

cd backend
pip install -r requirements.txt
python data_generator.py        # generates the data in /data
uvicorn main:app --reload       # opens http://localhost:8000

LLM mode (optional): export ANTHROPIC_API_KEY before starting the server. Without the key, the system runs in offline demo mode.

Pages: animated login at /login (create an account or use the one-click guest demo access), chat at /, dashboard at /painel, dataset & DJI log import at /dados. Interactive API docs: http://localhost:8000/docs

Example questions

• "How is vessel logistics doing?" → operations, cargo moved, average waiting, weather cancellations
• "What's the drilling progress?" → meters drilled, m/day and NPT per rig
• "Compare the platforms" → reliability ranking
• "Why are missions aborted on P-74?" → causes + abort × gust curve
• "How is fleet health?" → battery, cycles, cost and downtime per aircraft
• "What's the worst wind month in the Santos basin?" → weather time series
• "And on PCH-1?" → follow-up: the agent remembers the previous analysis and re-runs it for the new scope

The agent understands questions in Portuguese (pt-BR) — its target users are Brazilian offshore operations teams.

Engineering decisions

1. Tool-calling instead of pure RAG — for tabular data, retrieving text chunks is fragile; running deterministic functions is auditable.
2. Offline fallback — the demo never breaks in an interview for lack of a key/quota; graceful degradation via try/except in the agent.
3. Synthetic data with domain physics — abort rate rises with gusts > 22 kt (a real offshore RPAS operational limit), batteries degrade ~0.045%/cycle. The dataset tells a true story.
4. No frontend framework — plain HTML pages sharing one stylesheet keep the evaluation focus on the backend and the agent.
5. Imported data never fakes telemetry — fields the DJI log doesn't carry (gust, battery health) stay empty instead of being guessed, and real flights live in a separate CSV so the synthetic dataset is never mutated.
6. The PDF report bypasses the LLM — it is built straight from the Pandas tools, so it inherits the zero-hallucination guarantee.
7. Curated answers outrank the LLM — the agent checks a human-verified knowledge base first (fuzzy matching, high threshold); when nothing fits, it admits it and stores the question instead of improvising. That queue is the product's improvement backlog.

Roadmap

• Ingest real DJI logs (AirData CSV) — upload on the /dados page; deduplicated, reversible, kept apart from the synthetic dataset
• Conversation memory (follow-ups: "and on PCH-1?") — history follows the user's account in both LLM and offline modes
• Public deploy (Render) + CI with pytest — 75 tests covering analytics, offline router, memory, ingestion, the PDF report, auth and language detection
• Bilingual UI & agent (PT/EN) — header language toggle, and the agent auto-detects the question's language and answers in it (LLM, offline router and curated answers)
• Chat sidebar — quick actions, per-account clickable question history and one-click conversation reset
• Immersive entry — animated lighthouse login scene with a loading splash on sign-in
• PDF export of the analysis report — GET /api/report, embedding the user's chat Q&A
• Multi-user with email login — animated lighthouse login screen, PBKDF2 + session cookies, guest demo access
• Per-user personalization — chat shortcuts reordered by each user's most-used analyses
• Verified-answer knowledge base — human-curated answers matched before the LLM (badge "✓ resposta verificada" in the chat), backed by 1,080 bilingual (PT/EN) offshore Q&A extracted from two study PDFs (data/offshore_qa.json)
• Continuous-improvement queue — questions the agent can't answer are stored and listed on /dados, prioritized by recurrence
• Offshore-wide coverage — supply-vessel logistics and drilling-rig domains added as deterministic tools, with weather-correlated synthetic data
• Email verification & password reset — needs an SMTP provider
• More offshore domains as tools — lifting operations, SIMOPS windows, metocean forecasting, POB/helicopter logistics

---

Author: William Oliveira — senior offshore RPAS pilot (ANAC/DECEA/NR-34) transitioning into data & AI. GitHub: @TheDevOffshore · LinkedIn: wmdevoffshore

Data is 100% synthetic. No real operational information from any company was used.