docs: Document ChannelConfigSchema fields and praisonai doctor validation changes#467
Conversation
…tion changes (fixes #463) - Add comprehensive Channel Configuration Reference table to gateway.mdx - Document all 10 ChannelConfigSchema fields with exact types and defaults from PR #1772 - Add Bot Config Checks section to doctor-cli.mdx with common error messages and fixes - Clarify channel-key vs platform distinction across multiple doc files - Document routes vs routing field naming and interchangeability - Add regression fix reference for Unknown channel errors from multi-channel onboard - Include YAML allowed_users example alongside existing Python examples 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Mervin Praison <MervinPraison@users.noreply.github.com>
|
Warning Review limit reached
More reviews will be available in 52 minutes and 33 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Review Summary by QodoDocument ChannelConfigSchema fields and bot validation behavior
WalkthroughsDescription• Document ChannelConfigSchema fields with comprehensive reference table • Add Bot Config Checks section explaining validation errors and fixes • Clarify channel-key vs platform distinction across documentation • Include YAML examples and regression fix references for multi-channel setup Diagramflowchart LR
A["ChannelConfigSchema<br/>Documentation"] --> B["gateway.mdx<br/>Reference Table"]
A --> C["doctor-cli.mdx<br/>Validation Checks"]
A --> D["Cross-doc Updates<br/>Clarifications"]
B --> E["10 Fields Documented<br/>with Types & Defaults"]
C --> F["Error Messages<br/>& Troubleshooting"]
D --> G["channel-key vs platform<br/>distinction"]
File Changes1. docs/best-practices/bot-security.mdx
|
Code Review by Qodo
1.
|
There was a problem hiding this comment.
Pull request overview
This PR documents the ChannelConfigSchema field additions (platform, allowed_users, routes) and the updated praisonai doctor validation behavior introduced by PraisonAI PR #1772, which fixed a regression where onboard-generated multi-channel YAML was rejected by the doctor CLI.
Changes:
- Added a Channel Configuration Reference table and routing alias note in
gateway.mdx. - Added a Bot Config Checks subsection with error/cause/fix table in
doctor-cli.mdx. - Cross-doc clarifications in
bot-routing.mdx,messaging-bots.mdx,onboard.mdx, and a YAMLallowed_usersexample inbot-security.mdx.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/features/gateway.mdx | New ChannelConfigSchema field reference table and routes alias note. |
| docs/cli/doctor-cli.mdx | New "Bot Config Checks" subsection documenting validation errors. |
| docs/features/bot-routing.mdx | Note clarifying routes vs routing field naming. |
| docs/features/messaging-bots.mdx | Channel-key-vs-platform explanation alongside multi-bot example. |
| docs/features/onboard.mdx | Reference to PR #1772 in the doctor troubleshooting accordion. |
| docs/best-practices/bot-security.mdx | YAML allowed_users example next to existing Python examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to explain multi-bot configurations, custom channel keys, and the platform field, as well as the praisonai doctor validation behavior. The review feedback points out some inaccuracies in the documentation: specifically, routes: is not actually validated by ChannelConfigSchema (it is parsed directly from the raw configuration), and the documented error message for unknown channels does not match the actual error message raised in the codebase.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| icon: "route" | ||
| --- | ||
|
|
||
| `routes:` is the canonical schema field name (validated by `ChannelConfigSchema`). Some examples elsewhere in the docs use `routing:` as a friendlier alias — both work in YAML, but `routes:` matches what `praisonai doctor` validates against. |
There was a problem hiding this comment.
The statement that routes: is validated by ChannelConfigSchema is incorrect. ChannelConfigSchema in praisonai/bots/_config_schema.py does not define routes or routing fields. They are parsed directly from the raw configuration dictionary in the gateway server. To avoid confusing users, we should refer to routes: as the preferred field name rather than a validated schema field.
routes: is the preferred field name for configuring context-to-agent routing. Some examples elsewhere in the docs use routing: as an alias — both work in YAML, but routes: is the recommended field name.
| | `channel` | Channel messages | Announcements | | ||
| | `default` | Fallback for unmatched | General agent | | ||
|
|
||
| The same map is accepted under the `routes:` field on each channel block — `routing:` and `routes:` are interchangeable in YAML. `routes:` is the canonical schema field; `routing:` is kept as a friendlier alias in examples. |
There was a problem hiding this comment.
Similarly, routes: is not a field in ChannelConfigSchema and is not validated as a schema field. It is parsed directly from the raw configuration dictionary. We should adjust this description to avoid calling it a 'canonical schema field'.
The same map is accepted under the routes: field on each channel block — routing: and routes: are interchangeable in YAML. routes: is the preferred field; routing: is kept as an alias in examples.
|
|
||
| | Error | Cause | Fix | | ||
| |-------|-------|-----| | ||
| | `Unknown channel 'X' (platform 'Y'). Supported platforms: agentmail, discord, email, slack, telegram, whatsapp` | Channel key is a custom id (e.g. `telegram_cfo`) but no `platform:` field is set, or the resolved platform isn't supported. | Add `platform: telegram` (or whichever) to the channel block. | |
There was a problem hiding this comment.
The documented error message Unknown channel 'X' (platform 'Y'). Supported platforms: ... does not match the actual error message raised in praisonai/bots/_config_schema.py (which is Unknown channel '{name}'. Supported: ...). To ensure users can search for and find the exact error message, we should update this to match the codebase.
| Unknown channel X. Supported: agentmail, discord, email, slack, telegram, whatsapp | Channel key is a custom id (e.g. telegram_cfo) but no platform: field is set, or the resolved platform isn't supported. | Add platform: telegram (or whichever) to the channel block. |
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| ### Bot Config Checks | ||
|
|
||
| `praisonai doctor` validates `bot.yaml` against `BotYamlSchema` for every bot-related check (`bot_tokens`, `bot_config`, `bot_security`, `multi_channel_tokens`). Common failures and fixes: | ||
|
|
||
| | Error | Cause | Fix | | ||
| |-------|-------|-----| | ||
| | `Unknown channel 'X' (platform 'Y'). Supported platforms: agentmail, discord, email, slack, telegram, whatsapp` | Channel key is a custom id (e.g. `telegram_cfo`) but no `platform:` field is set, or the resolved platform isn't supported. | Add `platform: telegram` (or whichever) to the channel block. | | ||
| | `No channels configured` | `channels:` block is empty. | Add at least one channel. Re-run `praisonai onboard` to regenerate. | | ||
| | `Invalid mode 'X'` | Unknown transport mode. | Use one of `poll`, `ws`, `webhook`, `hybrid`. | |
There was a problem hiding this comment.
4. Platform docs contradict schema 🐞 Bug ≡ Correctness
docs/cli/doctor-cli.mdx documents bot.yaml validation that resolves a channel’s platform from channel.platform and shows an error Unknown channel 'X' (platform 'Y')..., but this repo’s BotYamlSchema validates only the channel key and ChannelConfigSchema has no platform field. Users following the doc’s remediation (adding platform:) will still fail praisonai doctor on custom channel keys (e.g. telegram_cfo).
Agent Prompt
## Issue description
The new doctor docs describe bot.yaml validation behavior (and an exact error string) that is not implemented by the current schema code in this repo. Specifically, the docs claim:
- custom channel keys are accepted when `platform:` is set
- the error format includes `(platform 'Y')`
But the current BotYamlSchema rejects non-platform channel keys and cannot resolve `platform` because ChannelConfigSchema doesn’t define it.
## Issue Context
This inconsistency is user-facing and will cause `praisonai doctor` troubleshooting guidance to fail.
## Fix Focus Areas
- docs/cli/doctor-cli.mdx[48-60]
- praisonai/bots/_config_schema.py[24-112]
## What to change
Choose one:
1) **Update the mirrored schema/validation code in this repo** to match the documented behavior (add `platform` to `ChannelConfigSchema`, resolve platform in `validate_channels_exist`, and update the raised error string), OR
2) **Adjust the docs** to match the current schema behavior (remove `platform:` remediation, and update the error message examples to the actual strings emitted, including the `Invalid bot.yaml configuration:` wrapper).
After the change, ensure the documented error strings match the code exactly.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
|
@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above first. Review areas:
|
|
@claude You are the FINAL architecture reviewer. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding. Phase 1: Review per AGENTS.md
Phase 2: FIX Valid Issues Phase 3: Final Verdict |
|
Claude finished @MervinPraison's task —— View job Final Architecture Review Completed ✅Phase 1: Review per AGENTS.md
Phase 2: Fix Valid Issues
Phase 3: Final Verdict
Issues FixedAll major issues raised by reviewers have been addressed: 1. Schema vs Implementation Mismatch (Qodo #2, Gemini)
2. Error Message Mismatch (Qodo #4, Gemini)
3. Gateway Field Documentation (Qodo #3)
4. Routing Validation Claims (Qodo #6, Gemini)
5. Missing Function Reference (Qodo #1)
6. Style Rule Compliance (Qodo #5)
Changes Made
Final Verdict: ✅ APPROVEThe PR now accurately documents:
All documentation now matches the SDK ground truth as required by AGENTS.md. The PR is ready for merge. |
- Update gateway.mdx to document actual gateway runtime fields vs schema fields - Fix doctor-cli.mdx error messages to match actual BotYamlSchema validation - Correct bot-routing.mdx routing field validation claims - Clarify messaging-bots.mdx gateway vs bot.yaml channel key differences - Add warning distinguishing schema validation from runtime behavior Addresses reviewer feedback from Qodo, Gemini, CodeRabbit, and Copilot 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
Review complete. I read the prior reviewer context and did a full pass over all 6 changed files. 1) Bloat check
2) Security
3) Performance
4) Tests
5) Backward compatibility
6) Code quality
7) Specific improvements (optional)
channels:
telegram_cfo:
platform: telegram
token: ${TELEGRAM_CFO_BOT_TOKEN}
routes:
default: cfo
No blocking issues found from this review. |
Fixes #463
Summary
This PR documents the ChannelConfigSchema field changes and praisonai doctor validation behavior introduced in PraisonAI PR #1772. The changes address the regression fix that followed PR #1757 (multi-Telegram onboard) where custom channel keys like
telegram_cfowere being rejected by doctor validation even though they were generated by the onboard wizard itself.Changes Made
1. Channel Configuration Reference (gateway.mdx)
platform,allowed_users, androutesfields from PR #17722. Bot Config Validation (doctor-cli.mdx)
Unknown channel 'X' (platform 'Y')3. Cross-Documentation Updates
routesvsroutingfield namingallowed_usersexample alongside Python examplesValidation
🤖 Generated with Claude Code