marola-app

The marola product: a Scala 3 / Kyo pipeline that finds the beaches near you (OpenStreetMap), reads tomorrow's sea and weather (Open-Meteo), scores each hour for swimming, and has a local LLM write the answer while a second pass reviews it. It runs entirely on your machine with a free Ollama model; no cloud account is needed. The same jar is a CLI, an MCP tool server, a chat server (--serve-chat: /health and /ask over HTTP, for the map's chat widget), the benchmark runner and the writer of the boards the map shows.

It is one of the marola repos under the umbrella (MIP-0070), and its history before the split is marola's, filtered to these files.

Status: runs locally end to end as a CLI, an MCP server and a chat server; the image feeds marola.dev's boards and marola-ml's benchmark. There is no Telegram loop yet: the bot is Phase 1, and Telegram setup only prepares its credentials.

Try it

nix develop
just ollama-up                                   # an Ollama server with llama3.2
just run -- --summarize --lat -27.6733 --lon -48.47
just mcp-server                                  # the MCP tool server

Or the published image: docker run --rm --network host ghcr.io/marola-dev/marola-app:jvm --brief --lat -27.6733 --lon -48.47. Run it locally has every mode, and Architecture how the pipeline fits together.

To build and test:

just build && just test && just quality

just test first unpacks the marola-corpus release pinned in corpus.version. JDK 25 is required (Kyo).

Repo map

Path	What
core/	the pure pipeline, the shared HTTP/JSON helpers, the LlmClient / VisionClient / SightingStore traits
local/	the Ollama-backed implementations and the local-file sighting store
cli/	Main, AppConfig, the MCP and chat servers, the benchmark runner, the board writer
experiment/	the forecast experiment (MIP-0083): its schemas, its ground-truth points (ground-truth.json and its loader), the Open-Meteo forecast route and the cycle
oods/src/test/resources/	the OODS ingest's test fixtures (MIP-0056); its code lands here too
scripts/	the corpus fetch, the resources tarball, the site-data push, Scaladoc post-processing, test fixtures
docs/	this repo's design, library, development and reference pages, and its ADRs (docs/adr/)

Contracts

Consumes	the marola-corpus tag in corpus.version; compiled prompts from marola-ml, as bot PRs into core/src/main/resources/
Publishes	the image ghcr.io/marola-dev/marola-app (:jvm, :jvm-<sha>, :native) from every main push (ci.yml's jvm and native jobs); Scaladoc on the api-docs branch, force-pushed from every main push (one commit, the latest; ci.yml's api-docs job); on each v* tag, ml-resources-<tag>.tar.gz (the prompts, sea lore and benchmark questions marola-ml reads), via release.yml; coverage/ and smoke/ to marola-site's site-data branch; README.md and docs/ to docs.marola.dev
Pinned by	marola-site, marola-ml and marola-oods pin the image (tag + digest) in marola-image; marola-ml also pins the resources tarball in resources.version

Docs and AGENTS.md

• Design: the three modules, the module map, the pipeline, and why the map is deterministic while the chat is generative.
• Heuristics: the score's deductions, the jellyfish and whale heuristics, the water verdict, tides and sea lore.
• Integrations: each pluggable backend, where it lives, and what has been verified.
• Effects map: each module's purity and effect status, and where a signature hides an effect.
• Libraries: each library and pinned tool, why, its version, and what was weighed instead.
• Scala 3 and JDK review: what to adopt from Scala 3 and the JDK, and what to leave alone.
• Development: testing and fixtures, images and compose profiles, observability, the CI workflows, code review, releases, secrets and cost.
• Data sources: every external API the app calls, and on what terms.
• API reference: the Scaladoc trees, and marola-ml's pdoc.
• CLI reference: every flag and mode, the MCP tools, the chat server's endpoints.
• Configuration reference: every MAROLA_* variable, and choosing the embedder.
• Ground-truth points: the anemometers the forecast benchmark scores against, the strong-wind rule they must pass, and each candidate.
• Open-Meteo forecasts: how the benchmark reads IFS and GFS runs, and what was checked live.
• ADR-0001: why the build is three sbt modules, core, local and cli. ADR-0002: the forecast experiment as a fourth, experiment.
• AGENTS.md: what this repo is and where it differs from the umbrella's rules.

Gemini review

Request the reviewer marola-dev/gemini on a pull request (sidebar → Reviewers, or gh pr edit <N> --add-reviewer marola-dev/gemini). marola-gemini-bot posts one review with at most 10 inline comments tagged [high]/[medium]/[low], then pushes one commit with the fixes it is sure of. Request it again after new commits for a fresh review. It runs only when asked, reviews fork pull requests without pushing to them, and never edits .github/. .github/workflows/gemini.yml calls the devkit's gemini-review workflow.