feat: expose campus and core study data as assistant tools

[SebastianBoehler]

Summary

Expose two groups of StudyOS_Agent capabilities as assistant tools:

1. Public campus tools: Mensa menus and Tübingen campus/location search.
2. Private study tools: combined ILIAS/Moodle tasks and deadlines, the ALMA study planner, and richer term-aware academic status.

This issue is the first concrete implementation consumer of the shared data/action capability contract in #54. Public tools may be used by local and cloud providers. Authenticated university data must be fetched on-device and remain local-only by default.

Motivation

Latest main has one shared StudyOsToolSpec catalog and executor for cloud and local providers, but several live app capabilities are UI-only and core study workflows from tue-api-wrapper are still missing:

• CampusClient already loads Tübingen Mensa menus.
• MapSearchClient already searches bounded Tübingen locations.
• tue-api-wrapper has tested contracts for ILIAS tasks/assignment deadlines, Moodle calendar events, the ALMA study planner, and enrollment/exam status.

Adding these through one capability architecture gives the assistant useful, grounded data without routing student credentials through hosted infrastructure.

Dependencies and overlap

• Build on feat: StudyOS data and action capability contract #54; do not create a second parallel capability abstraction.
• Keep this tool/backend work independent from feat(campus): improve Mensa menu card visualization #42's Mensa UI changes. Reuse stable domain clients/models and resolve only incidental shared-file conflicts if they arise.
• Preserve Stabilize assistant tool execution, mail access, and chat performance #43's tool-loop, HTTP lifecycle, caching, bounded-output, and failure-handling constraints.
• Treat tue-api-wrapper as the request/parsing/contract reference. Reuse its fixtures and typed shapes where practical instead of inventing incompatible models.

Slice 1: public campus tools

get_mensa_options

Inputs:

• date (optional ISO date)
• canteen (optional ID or name filter)
• preference (optional: any, vegetarian, vegan)
• limit (optional, bounded)

Output:

• stable canteen/menu IDs where available
• canteen name, date, line, meal items, dietary markers, and student price
• source URL and freshness metadata
• explicit empty/unavailable/upstream-error states

Behavior:

• reuse CampusClient and shared model-level filtering/sorting
• bound results before returning data to the model
• use an explicit short TTL cache with manual refresh/invalidation
• never return raw upstream JSON

search_campus_locations

Inputs:

• query (required)
• limit (optional, capped at 8)

Output:

• stable result ID for follow-up actions
• display name/address and coordinates
• source and freshness metadata
• explicit empty/unavailable/upstream-error states

Behavior:

• reuse MapSearchClient and its Tübingen-bounded Nominatim request
• do not transmit device GPS position
• do not auto-open navigation; keep that as a separate future user-approved action using a returned result ID

Slice 2: private study tools

get_tasks

Inputs:

• sources (optional subset of ilias, moodle; defaults to both)
• limit (optional, capped at 50)

Output item contract:

• stable source-qualified ID
• source, courseTitle, title, itemType
• startAt, dueAt, status, and actionable when known
• local source URL/target for user navigation
• result-level freshness and partial-failure metadata

Data sources:

• ILIAS derived-task overview (IliasTaskItem: title, URL, type, start, end)
• Moodle actionable dashboard/calendar events (MoodleDashboardEvent)

Behavior:

• normalize dates to ISO-8601 with an explicit timezone when parsing is reliable
• preserve raw date hints separately when an exact timestamp cannot be established
• sort known due dates first, then undated tasks
• return successful sources when one portal fails and include a bounded per-source failure instead of failing the whole tool

get_deadlines

Inputs:

• days (optional, default 30, range 1–180)
• sources (optional subset of ilias, moodle; defaults to both)
• limit (optional, capped at 100)

Output item contract:

• source-qualified ID and source
• course, exercise/assignment title, requirement/status
• dueAt plus the original due hint
• source URL/target
• result-level window, freshness, and partial-failure metadata

Data sources:

• ILIAS course assignment traversal (IliasAssignmentDeadline / IliasExerciseAssignment)
• Moodle calendar action events within the requested time window (MoodleCalendarPage)

Behavior:

• filter only confirmed dated entries into the requested window
• do not turn heuristic mail deadline matches into confirmed portal deadlines
• deduplicate by source + canonical URL/ID + title + due time
• cap course traversal and assignment scans before tool output
• preserve portal attribution so the assistant never claims an ILIAS deadline came from Moodle or vice versa

get_study_planner

Inputs: none for the first version.

Output:

• planner title and source URL
• visible semesters (index, label, termLabel)
• bounded modules with number, title, semester column/span, earned/required credits, progress, detail URL, and expandability
• planner view-state flags and freshness metadata

Behavior:

• port/reuse the wrapper's AlmaStudyPlannerPage contract and parser fixtures
• return structured planner data, not raw HTML
• keep module detail expansion out of the first version

Extend get_academic_status

Keep the existing tool name. Expand its response so it distinguishes:

• selected/available term
• course enrollment vs exam registration
• status, attempt/category, schedule text, and detail URL when present
• current report/parser notice and refresh timestamp

Do not infer “passed”, “registered”, or “cancelled” from missing/ambiguous fields. Preserve the portal's original status alongside any normalized status.

Local authenticated integration

The Flutter app must perform ALMA/ILIAS/Moodle requests locally using credentials from existing secure profile storage.

• Never send the username/password to a hosted wrapper, cloud model, tool argument, prompt, result, trace, log, or URL.
• Port the proven Shibboleth/SAML handoff, parser contracts, and fixtures from tue-api-wrapper into focused Dart clients, or consume them from a shared pure-Dart wrapper package if one is available.
• Reuse a local authenticated session within one logical refresh where practical; inject/close HTTP clients deterministically.
• Detect login redirects/session expiry explicitly and return authenticationRequired rather than empty data.
• Keep portal clients/repositories separate from assistant serialization so UI, feed, and assistant can share the same capability.

Capability and tool architecture

1. Add/reuse typed capability results containing:
   • data
   • state (fresh, stale, empty, unavailable, permissionDenied, authenticationRequired, failed)
   • source(s)
   • fetchedAt and optional expiresAt
   • reliability and bounded per-source failures
2. Add policy metadata:
   • public tools: publicExternal, read-only, cloud/local allowed
   • study tools: privateLocal, read-only, local-only by default
3. Register tools in the shared catalog so schemas, descriptions, traces, and provider filtering have one source of truth.
4. Route execution through focused typed capability handlers rather than growing unrelated branches in StudyOsToolExecutor.
5. Serialize compact bounded JSON only at the tool boundary.
6. Inject clients/clocks so tests can use deterministic fakes; production must not silently fall back to mock data.

If #54 has not landed, implement only the smallest compatible contract subset and keep it easy for #54 to adopt without a second migration.

Cloud privacy enforcement

Cloud tool calls execute on-device, but their results are sent back to the configured cloud model. Labels alone are insufficient.

• cloudToolDefinitions must omit privateLocal tools by default.
• Local models may receive bounded private results on-device.
• A future explicit user opt-in may allow selected redacted private results to a configured cloud provider; that consent flow is out of scope here.
• Never place document bytes, attachments, cookies, auth headers, passwords, or full portal HTML in model context.

Caching and freshness

Use explicit per-capability caches, not hidden view futures:

• Mensa: short TTL keyed by date/filter inputs
• location search: short TTL keyed by normalized query
• tasks/deadlines: short authenticated TTL with manual refresh and logout invalidation
• study planner/academic status: longer TTL with manual refresh and logout invalidation

Never persist passwords, cookies, raw HTML, or attachment/document bytes in these caches. Consumers must be able to distinguish fresh, stale, empty, unavailable, and failed states.

Out of scope

• official-document listing/download
• automatic navigation/map opening
• campus seats, buildings, events, sports, TIMMS, Praxisportal, or Anny
• Moodle grades/messages/notifications beyond data needed for tasks/deadlines
• ALMA/ILIAS/Moodle write actions
• hosted credential storage/routing
• silent mock production data

Acceptance criteria

Shared/public

• Capability results include state, source, freshness, policy, and bounded failures.
• get_mensa_options and search_campus_locations are advertised/executable in cloud and local assistant paths.
• Inputs and output sizes are validated/capped.
• Mensa filtering/sorting reuses app behavior; campus search remains bounded to Tübingen and does not transmit GPS.
• HTTP clients are injected/reused or closed deterministically.
• Production uses live data only and fails explicitly.

Private study

• get_tasks, get_deadlines, and get_study_planner are available to the local assistant.
• get_academic_status returns the richer term-aware contract without breaking existing callers.
• ILIAS/Moodle partial failure returns usable results from the healthy source.
• Dates are normalized only when reliable; ambiguous hints are preserved without invention.
• Auth expiry is distinguishable from empty data.
• Private tool definitions are absent from cloud requests by default.
• Credentials/session data never enter prompts, tool arguments/results, traces, logs, caches, or remote wrapper calls.

Tests/docs

• Tests cover schemas, routing, provider filtering, result bounds, empty/stale/auth-required/failed states, partial portal failure, date windows, deduplication, and cache invalidation.
• Ported parsers have fixture tests based on the wrapper's known contracts.
• Cloud tests prove private tools are omitted while public tools remain available.
• Tool failures remain model-visible and do not abort unrelated calls.
• Relevant docs/tool inventory and privacy behavior are updated.

Validation

Run from flutter_app/:

dart format --output=none --set-exit-if-changed lib test
flutter analyze
flutter test
flutter build web --release

Suggested delivery order

This issue may be implemented as focused PRs sharing the same capability contracts:

1. capability result/policy/provider filtering + public tools
2. local ILIAS/Moodle session and parsers + get_tasks/get_deadlines
3. ALMA planner + richer academic status

Follow-up issues can cover public course discovery/seats/events/TIMMS and explicit-confirmation university actions.

[SebastianBoehler]

This is already a strong vertical-slice spec. I checked current main and the related issues/PRs; there is no exact duplicate, but a few decisions and overlap corrections would make it implementation-ready.

Dependency / overlap map

• Architectural gate: feat: StudyOS data and action capability contract #54 owns the generic capability result/privacy/freshness contract. No implementation of that contract exists on main yet, so either feat: StudyOS data and action capability contract #54 should land first or this issue must explicitly define the smallest CapabilityResult<T> slice that feat: StudyOS data and action capability contract #54 will adopt.
• Mensa integration: coordinate with issue Improve Mensa menu card visualization and actions #41 / open PR feat(campus): improve Mensa menu card visualization #42. That PR adds cross-canteen date sorting and action metadata, but it does not currently own dietary filtering. It is also conflicting at the moment, so it should not be treated as a hard dependency without rebasing.
• Cache integration: open PR Cache mail and verify local model downloads #47 is the direct overlap, because it adds a static six-hour CampusClient cache and forceRefresh. Reuse/revise that cache rather than introducing a second cache in the tool adapter.
• Existing map foundation: closed Add Maps and Navigation page with location-aware assistant action #22 / merged feat(app): add maps navigation page #23 already introduced MapSearchClient and bounded Nominatim search. feat: expose campus and core study data as assistant tools #60 is distinct because the model can initiate the search, but it should reuse that client/result model.
• Existing reliability foundation: merged PR Fix assistant tool-loop resilience #44 already delivered bounded multi-round calls and per-tool failure recovery for Stabilize assistant tool execution, mail access, and chat performance #43. Preserve this as a regression criterion rather than reimplementing it.

Clarifications needed before implementation

1. Contract ownership: should feat: expose campus and core study data as assistant tools #60 wait for feat: StudyOS data and action capability contract #54, or is its first PR allowed to land the minimal generic capability envelope? If the latter, please make that contract an explicit deliverable of feat: expose campus and core study data as assistant tools #60 and have feat: StudyOS data and action capability contract #54 reference it.
2. Mensa date semantics: should omitted date mean “today in Europe/Berlin”? Is a supplied date an exact calendar-day filter, and should a valid day with no menus return state: empty while malformed dates return a validation failure?
3. Filtering and bounds: should canteen match a stable ID or a case-insensitive exact name only? What are the default/max limit, and does it count flattened menu entries (recommended) or canteens?
4. Location identity: MapLocation currently discards Nominatim identity fields. Should the returned ID prefer osm_type:osm_id (portable/stable enough for follow-up actions), with place_id only as a provider-local/session fallback? Nominatim explicitly warns that place_id is not stable across installations/reimports.
5. Refresh ownership: is refresh only an app/UI cache invalidation, or should get_mensa_options expose refresh: true? The current input schema and “manual refresh” behavior do not yet connect.
6. Failure JSON: choose one vocabulary (failed vs upstream_error) and specify one exact JSON envelope for success, empty, unavailable, validation failure, timeout, and upstream failure. The focused handlers should return that bounded envelope rather than leak raw exception strings.
7. Provider parity: “local and cloud” should mean the shared Dart catalog/executor boundary. Adding duplicate native Swift/Android Mensa or map tools would be a much larger, separate scope unless native structured-tool parity is explicitly intended.

Suggested scope boundary

Keep this issue to two public, read-only capabilities and their focused adapters. Reuse the existing HTTP clients and model-level transformations; do not add navigation actions, native platform tool implementations, authenticated university data, generic map autocomplete, or broader #54 consumers. One issue can track the slice, while the contract (if needed), Mensa adapter, and map adapter may land as small reviewable PRs.

Acceptance-criteria additions / corrections

• The exact bounded JSON envelope is contract-tested for fresh, stale, empty, unavailable, and failed, including sanitized failure detail.
• Mensa tests pin Europe/Berlin date behavior, malformed dates, exact-day empty results, canteen matching, dietary mapping (any -> existing noPreference), and whether limit counts flattened meals.
• Map results preserve an explicit follow-up ID and document its stability/lifetime; parser tests cover OSM IDs and fallback identity.
• Nominatim calls remain user-triggered, bounded, cached for repeated queries, attributed, and rate-limited to the public-service policy (maximum one request/second per application), with an identifiable User-Agent and a replaceable endpoint/provider. See the official usage policy.
• Neither request path transmits device location, profile/memory data, credentials, cookies, authorization headers, or unrelated world state.
• Client ownership is explicit: injected clients are not accidentally closed, owned clients are closed deterministically, and timeouts are bounded.
• Existing Fix assistant tool-loop resilience #44 behavior is preserved: one failed call becomes a model-visible failed result/trace without aborting sibling calls.
• Catalog/schema/executor tests prove parity at the shared Dart boundary; native Swift/Android tool duplication is out of scope.
• The docs criterion names the concrete target (for example, a tool inventory in flutter_app/README.md) so completion is verifiable.

Once the seven decisions above are answered—especially #54 ownership, date semantics, identity, and cache ownership—I’d consider this ready for implementation.