Skip to content

docs: add draft for maps service - #2672

Open
TomCools wants to merge 11 commits into
TimefoldAI:mainfrom
TomCools:docs/map-service
Open

TomCools wants to merge 11 commits into
TimefoldAI:mainfrom
TomCools:docs/map-service

Conversation

@TomCools

Copy link
Copy Markdown
Contributor

@rsynek, need your help pulling this over the finish line.

  • I left a few open TODOs or QUESTION's in the doc. If you could have a look and elaborate please?
  • I find myself switching between "maps extension" and "maps service". I have my own opinion, but I value yours.

@rsynek rsynek left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @TomCools ! Sharing some initial feedback inline.

Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Several API references and behavioral claims are inaccurate, and an unresolved question remains.

9 open findings
What changed in this PR

Adds draft documentation for the maps extension and remote map service.

Changes:

  • Documents location enrichment, configuration, providers, named sets, and testing.
  • Adds cross-references and navigation.
File Description
model-enrichment.adoc Links to maps documentation.
map-service.adoc Adds the maps service guide.
nav.adoc Adds navigation entry.

🧠 Review effort: Balanced


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docs/src/modules/ROOT/nav.adoc
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/model-enrichment.adoc Outdated
Updated references to 'map service' to 'maps extension' for clarity. Modified fallback behavior description and corrected method calls for travel time retrieval.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@TomCools
TomCools marked this pull request as ready for review October 9, 2026 21:20
@TomCools
TomCools requested review from a team and a balanced review from Copilot October 9, 2026 21:20
@TomCools
TomCools requested a review from triceo as a code owner October 9, 2026 21:20
@TomCools
TomCools requested a review from rsynek October 9, 2026 21:20

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The guide contains malformed AsciiDoc and several inaccurate or deprecated API instructions.

1 open finding
9 resolved since last review
Previously missed (6)

In code that hasn't changed since last review

Low severity Clarify that map membership does not ensure reachability

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:66

Being present in the map does not guarantee reachability because two valid locations can belong to disconnected road components, so the text must not imply that checking locationsNotInMap eliminates every UNREACHABLE result.

Low severity Replace deprecated getDrivingTimeTo alias

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:70

This introduces the deprecated getDrivingTimeTo(...) alias even though Location marks it @Deprecated at service/maps/api/src/main/java/ai/timefold/solver/service/maps/api/model/Location.java:174-176, so use getTravelTimeTo(...) consistently.

This issue also appears in the following locations of the same file:

  • line 176
  • line 354
Low severity Clarify UniqueLocationAccumulator does not canonicalize locations

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:130

UniqueLocationAccumulator only detects equal-but-distinct instances and does not canonicalize model references, so presenting it as a way to share one Location can leave omitted instances without an injected matrix.

Low severity Distinguish TravelTimeMatrixEnricher from remote map service

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:143

TravelTimeMatrixEnricher is the built-in enricher while the map service is its optional remote backend, so calling the map service itself the enricher conflates the two concepts and contradicts the local Haversine path.

Low severity Document departure-time overload for traffic-enabled lookups

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:231

When traffic is enabled the scalar lookup reads only the first available timeframe (Location.java:99-108), so this configuration entry must direct users to the departure-time overload or the documented examples will silently ignore the other matrices.

Low severity Handle location set name when enriching traffic timeframes

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:305

This claim is not true when use-traffic=true because TravelTimeMatrixEnricher.enrichAllTimeframes() calls optionsSupplier.getOptions() without solverModel.getLocationSetName(), so either propagate the name in that path or document the limitation.

🧠 Review effort: Balanced

Comment thread docs/src/modules/ROOT/pages/running-timefold-solver/service/map-service.adoc Outdated
Copilot AI balanced review requested due to automatic review settings October 15, 2026 20:09
@TomCools
TomCools had a problem deploying to documentation (preview) October 15, 2026 20:09 — with GitHub Actions Failure

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Setup and matrix-usage guidance need corrections so readers can integrate maps support and use it correctly.

0 open findings

1 resolved since last review
Previously missed (4)

In code that hasn't changed since last review

Low severity Check route reachability beyond map membership

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:66

Locations on disconnected road networks can all be in the map while routes between them remain unreachable, so replace this guarantee with advice to check route reachability even when getLocationsNotInMap() is empty to avoid exceptions during scoring.

Low severity Add maps-enabled service dependency

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:80

The standard service parent includes timefold-solver-service without maps integration, so add the ai.timefold.solver:timefold-solver-service-with-maps dependency before this example to make the maps types and automatic enricher available.

Low severity Use departure-time traffic matrix lookups

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:231

With traffic enabled, the one-argument lookups shown above use the first available timeframe rather than the trip's departure time, so document the departure-time overloads here to prevent scoring trips against the wrong traffic matrix.

Low severity Clarify traffic mode uses per-timeframe matrices

docs/​src/​modules/​ROOT/​pages/​running-timefold-solver/​service/​map-service.adoc:302

With use-traffic=true, TravelTimeMatrixEnricher.enrichAllTimeframes() omits the model's location-set name from the request, so qualify this section to explain that traffic mode requests per-timeframe matrices instead of reusing the named set.

🧠 Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings October 15, 2026 20:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Setup instructions omit the maps dependency, and lookup and fallback guidance needs correction to prevent incorrect use.

5 open findings

🧠 Review effort: Balanced

Comment on lines +64 to +66
A model whose locations are all in the map never sees this, which is why
<<mapServiceUnreachableLocations>> matters: if you ignore the locations the map service could not
resolve, the failure surfaces much later, as an exception in the middle of scoring.
Comment on lines +79 to +80
To let the map extension build the matrix, your `@PlanningSolution` implements
`LocationsAwareSolverModel<Score_>` instead of the plain `SolverModel<Score_>`:
Comment on lines +230 to +231
|Take historical traffic into account, producing a travel time matrix per timeframe rather than a
single one.
Comment on lines +322 to +323
A solve that names a set which is not yet `COMPLETED` cannot use it to enrich locations; make sure
the set has finished processing before submitting solves that depend on it.
Comment on lines +341 to +344
Travel times involving those locations are `UNREACHABLE`, and the first `seconds()` call on one (e.g.
in a constraint, a shadow variable supplier or the output conversion) throws
`IllegalStateException`, aborting the solve with an error that points at the scoring code rather
than at the bad input that caused it.

This branch was successfully deployed

2 active deployments
documentation (preview) — b5292368 Deployed Oct 15, 2026 by TomCools via Build Documentation #803
internal — b5292368 Deployed Oct 15, 2026 by TomCools via approval_required #803
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants