feat(manifest): ovos.intent.list honours include_definitions

[goldyfruit]

Why

A client that wants to show what can be said asks ovos.intent.list for one language and then ovos.intent.describe once per intent to get the sentences. On the hub that is ~70 template intents, so ~70 round trips per language over the satellite session, against a runtime that wedges under about ten rapid requests. The platform contract (infra-manifests docs/thalovant-platform/contracts.md, "Hub intent inventory") already allows for the shortcut:

A runtime that honours {"include_definitions": true} on ovos.intent.list attaches each row's definition; clients use it when present and describe row by row when absent.

The Python SDK (0.4.36, intents.py) and the ported SDKs send the flag and take the fast path when definition is on the row; today no runtime attaches it, so every client falls back to the per-intent describes.

What

ovos_core/intent_services/manifest.py, IntentManifest._on_list:

• {"include_definitions": true} in the message data attaches definition to each result row: the stored registration payload, the same object ovos.intent.describe returns as definitions[i].definition for that registration. A template row brings its samples (slots in braces), a keyword row its keyword sets.
• Default reply unchanged: without the flag (or with it false) the row is the plain §10.1 quintuple plus enabled, byte-for-byte as before.
• The existing filters compose with it: lang is folded through standardize_lang, skill_id filters as before, and session_id still draws from the session's effective pool (§11.2), so a satellite's own re-registration wins and carries the satellite's payload.

Also documented the two manifest queries (ovos.intent.list / ovos.intent.describe and their responses) in docs/bus-events.md, which did not list them.

Tests

test/unittests/test_intent_manifest.py, new TestIntentListDefinitions on the fake bus:

• default reply carries no definition; include_definitions=False equals the default reply
• the attached definition equals what ovos.intent.describe returns for the same registration
• keyword and template registrations of one intent each carry their own payload
• the lang filter folds de-de to the stored de-DE and leaves the English rows out
• no lang covers every row
• with session_id, the satellite's registration wins and its payload is the satellite's; the inherited default keyword registration keeps its own

What ran locally

Venv with Python 3.12, pip install -e . (base dependencies, pre-releases allowed) + pytest:

• test/unittests/test_intent_manifest.py: 26 passed (19 on dev); 5 of the 7 new tests fail against the previous handler, the two "default unchanged" ones pass on both, as intended.
• test/unittests/test_intent_service.py + test_intent_service_extended.py (they construct the manifest too): 61 passed.
• Whole test/unittests: 336 passed, 3 failed. The 3 failures (test_skill_manager.py::TestDeferredLoadingConfigFlag) fail identically on unmodified dev in this environment (handler-list assertions against the installed ovos-workshop), unrelated to this change.
• flake8 (max 120): the changed files are clean; the one finding is upstream's pre-existing _key continuation indent.

Not run: the OVOS reusable workflows (build tests with the mycroft,plugins,skills-essential,test extras, ovoscope, license/opm checks) do not execute in this fork (only CodeQL runs here), so there is no CI signal beyond the local runs above.

Rollout: the runtime image needs a rebuild and a rollout

Merging this does not change the hub. The runtime image (thalovant-api/runtime-images/ovos-core-session-blacklists) installs a vendored ovos_core-3.2.1a1-py3-none-any.whl built from the coordinated upstream heads (OpenVoiceOS#808, OpenVoiceOS#844, OpenVoiceOS#846), pinned by sha256 in tests/test_runtime_image_patches.py; this fork's dev is 2.6.3a1 + #1. _on_list is identical on this fork, in that wheel, and on upstream dev (3.2.7a1), so the hunk applies cleanly to whichever source the next wheel is cut from. For it to take effect: rebuild the runtime wheel with this change, rebuild the image, then roll the runtime group (ovos-core-rtg-<group> restart; the hub's agent-bus client backs off up to 60 s after a restart). Until then clients keep taking the per-intent describe path, which still works.

Changelog

CHANGELOG.md is the generated file from the release workflow (update_changelog: true, regenerated from merged PR titles); the conventional title of this PR is the entry, as with #1.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added documentation for Intent Service events covering intent listing and registration descriptions.
  • Intent listings can optionally include each intent’s stored definition, including its sentences, in a single response.
  • Added language filtering while preserving registration details and session-specific intent pools.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 270f03fd-4897-4e05-8706-f83544b7aecc

📥 Commits

Reviewing files that changed from the base of the PR and between 3d82255 and b7ee788.

📒 Files selected for processing (3)

• docs/bus-events.md
• ovos_core/intent_services/manifest.py
• test/unittests/test_intent_manifest.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The intent list handler now accepts an optional include_definitions flag. Enabled responses include each intent's stored registration payload. Documentation and tests cover filtering, payload isolation, language handling, and session precedence.

Changes

Intent list definitions

Layer / File(s)	Summary
Optional definitions in intent-list responses ovos_core/intent_services/manifest.py, test/unittests/test_intent_manifest.py, docs/bus-events.md	ovos.intent.list accepts include_definitions. Enabled responses include each registration payload in definition. Tests cover default omission, filtering, payload preservation, language normalization, all-language queries, and session-effective registrations. Documentation describes the list and describe events.

Estimated code review effort: 2 (Simple) | ~15 minutes

Merge Risk: ⚪ Minimal · up to b7ee7

Intent listing now optionally returns each registration definition while preserving existing responses by default. The documented behavior and coverage indicate no remaining merge-blocking risk.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant IntentManifest
  participant SessionEffectivePool
  Client->>IntentManifest: Request ovos.intent.list with include_definitions
  IntentManifest->>SessionEffectivePool: Read matching registrations
  SessionEffectivePool-->>IntentManifest: Return registration rows and payloads
  IntentManifest-->>Client: Return rows with definition fields

Loading

Suggested reviewers: jarbasal

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding support for include_definitions in ovos.intent.list.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 5.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch intent-list-definitions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}