docs: audit and align 6 feature pages with AGENTS.md standards (batch 1)#826
Conversation
…821) Batch 1 of the documentation audit for docs/features/. Applied the full AGENTS.md conformance checklist to six foundational pages: - planning-mode.mdx: fixed icon (list-check), added sidebarTitle, added hero diagram with 5-color scheme, replaced Cursor/Windsurf comparison content with PraisonAI-centric Quick Start + Steps + AccordionGroup - output-styles.mdx: added sidebarTitle, hero Mermaid diagram, Quick Start with Steps, decision diagram, removed non-friendly imports (praisonaiagents.output.OutputStyle → OutputConfig) - guardrails.mdx: added sidebarTitle, fixed non-standard Mermaid color (#2E8B57 → #10B981), replaced non-friendly import (praisonaiagents.guardrails.LLMGuardrail → GuardrailConfig), added Steps, sequenceDiagram, AccordionGroup - hooks.mdx: added sidebarTitle, hero diagram, Steps (add_hook + HooksConfig patterns), replaced non-standard icon (link → webhook), AccordionGroup - skills.mdx: added sidebarTitle, hero diagram showing 3-level progressive loading, Steps, AccordionGroup, replaced non-friendly SkillManager direct import pattern with SkillsConfig - async.mdx: added sidebarTitle, fixed non-standard Mermaid colors (#2E8B57 → #189AB4), replaced old AgentTeam references with PraisonAIAgents, added Steps, AccordionGroup, sequenceDiagram Changes across all pages: - Frontmatter: added sidebarTitle; corrected icons per AGENTS.md §8 table - Hero Mermaid: all use 5-color palette (#8B0000 / #189AB4 / #10B981 / #F59E0B / #6366F1), #fff text, #7C90A0 stroke - Quick Start: 2-step <Steps> pattern (simple bool/string → Config class) - How It Works: sequence diagram or flow diagram per AGENTS.md §3 - Configuration Options: consolidated tables with type/default/description - Common Patterns: 2-3 copy-paste runnable examples - Best Practices: <AccordionGroup> with 4 accordions - Related: <CardGroup cols={2}> with 2 cards - No forbidden phrases remain in updated pages Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
|
Warning Review limit reached
More reviews will be available in 52 minutes and 38 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses rolling per-developer review limits. Reviews become available again as older review attempts age out of the rolling limit window. 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 |
![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 and simplifies several documentation files, including async agents, guardrails, hooks, output styles, planning mode, and agent skills, by adding clear Mermaid diagrams and updated Python code examples. The reviewer provided valuable feedback on the code snippets within the documentation, recommending defensive checks to prevent potential AttributeError exceptions when accessing output.raw or event_data.tool_name directly, as well as replacing the deprecated datetime.utcnow() with timezone-aware datetime.now(timezone.utc).
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.
| async def on_complete(output): | ||
| print(f"Task done: {output.raw[:100]}") |
There was a problem hiding this comment.
Accessing output.raw directly without verifying if output or output.raw is None can lead to an AttributeError if the task fails or returns empty. It is safer to add a defensive check.
async def on_complete(output):
if not output or not output.raw:
return
print(f"Task done: {output.raw[:100]}")
| def validate_length(output): | ||
| word_count = len(output.raw.split()) | ||
| if word_count < 100: | ||
| return False, f"Too short: {word_count} words (need 100+)" | ||
| return True, output |
There was a problem hiding this comment.
Accessing output.raw directly without verifying if output or output.raw is None can lead to an AttributeError if the task fails or returns empty. It is safer to add a defensive check.
def validate_length(output):
if not output or not output.raw:
return False, "Empty or invalid output"
word_count = len(output.raw.split())
if word_count < 100:
return False, f"Too short: {word_count} words (need 100+)"
return True, output
| def validate_json(output): | ||
| import json | ||
| try: | ||
| json.loads(output.raw) | ||
| return True, output | ||
| except json.JSONDecodeError as e: | ||
| return False, f"Invalid JSON: {e}" |
There was a problem hiding this comment.
Accessing output.raw directly without verifying if output or output.raw is None can lead to an AttributeError if the task fails or returns empty. It is safer to add a defensive check.
def validate_json(output):
if not output or not output.raw:
return False, "Empty or invalid output"
import json
try:
json.loads(output.raw)
return True, output
except json.JSONDecodeError as e:
return False, f"Invalid JSON: {e}"
| def check_accuracy(output): | ||
| if "estimate" in output.raw.lower() or "approximately" in output.raw.lower(): | ||
| return False, "Response must use exact values, not estimates" | ||
| return True, output |
There was a problem hiding this comment.
Accessing output.raw directly without verifying if output or output.raw is None can lead to an AttributeError if the task fails or returns empty. It is safer to add a defensive check.
def check_accuracy(output):
if not output or not output.raw:
return False, "Empty or invalid output"
if "estimate" in output.raw.lower() or "approximately" in output.raw.lower():
return False, "Response must use exact values, not estimates"
return True, output
| @add_hook('before_tool') | ||
| def security_filter(event_data): | ||
| if event_data.tool_name in BLOCKED_TOOLS: | ||
| return f"Tool '{event_data.tool_name}' is not allowed in this environment" |
There was a problem hiding this comment.
Accessing event_data.tool_name directly without verifying if event_data or event_data.tool_name is None can lead to an AttributeError. It is safer to add a defensive check.
@add_hook('before_tool')
def security_filter(event_data):
if not event_data or not event_data.tool_name:
return
if event_data.tool_name in BLOCKED_TOOLS:
return f"Tool '{event_data.tool_name}' is not allowed in this environment"
| import json | ||
| from datetime import datetime | ||
| from praisonaiagents import Agent | ||
| from praisonaiagents.errors import LLMError | ||
|
|
||
| def handle_llm_error(error): | ||
| """Agent-level error handler for LLM failures""" | ||
| print(f"LLM Error in agent: {error.agent_id}") | ||
| print(f"Model: {error.model_name}") | ||
| print(f"Retryable: {error.is_retryable}") | ||
|
|
||
| # Could implement custom error recovery here | ||
| if error.is_retryable and "rate limit" in error.message.lower(): | ||
| print("Rate limit detected - implement backoff strategy") | ||
| elif not error.is_retryable: | ||
| print("Fatal error - manual intervention required") | ||
|
|
||
| agent = Agent( | ||
| name="Error Aware Agent", | ||
| instructions="Process user requests", | ||
| on_error=handle_llm_error # Called when LLM errors occur | ||
| ) | ||
|
|
||
| # When _chat_completion raises LLMError, on_error is called first | ||
| try: | ||
| result = agent.start("Hello world") | ||
| except LLMError as e: | ||
| print(f"Error propagated after on_error hook: {e}") | ||
| ``` | ||
|
|
||
| ### Error Hook vs Agent Callback | ||
|
|
||
| | Type | Purpose | When Called | Scope | | ||
| |------|---------|-------------|-------| | ||
| | **HookEvent.ON_ERROR** | General error handling | Any error in hook system | All registered hooks | | ||
| | **agent.on_error** | LLM-specific errors | When `_chat_completion` fails | Single agent instance | | ||
|
|
||
| ```python | ||
| # Both can be used together | ||
| registry = HookRegistry() | ||
|
|
||
| @registry.on(HookEvent.ON_ERROR) | ||
| def global_error_handler(event_data): | ||
| """Handles all types of errors""" | ||
| print(f"Global error: {event_data.error}") | ||
| return HookResult.allow() | ||
| from praisonaiagents.hooks import add_hook | ||
|
|
||
| def llm_error_handler(error): | ||
| """Handles only LLM errors for this agent""" | ||
| print(f"LLM error: {error.message}") | ||
| @add_hook('before_tool') | ||
| def audit_before(event_data): | ||
| print(json.dumps({ | ||
| "ts": datetime.utcnow().isoformat(), | ||
| "event": "before_tool", | ||
| "tool": event_data.tool_name, | ||
| })) | ||
|
|
||
| @add_hook('after_tool') | ||
| def audit_after(event_data): | ||
| print(json.dumps({ | ||
| "ts": datetime.utcnow().isoformat(), | ||
| "event": "after_tool", | ||
| "tool": event_data.tool_name, | ||
| })) |
There was a problem hiding this comment.
Using datetime.utcnow() is deprecated in Python 3.12 and scheduled for removal in a future version. It is recommended to use timezone-aware datetime.now(timezone.utc) instead. Additionally, adding defensive checks for event_data prevents potential AttributeError exceptions.
import json
from datetime import datetime, timezone
from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook
@add_hook('before_tool')
def audit_before(event_data):
if not event_data or not event_data.tool_name:
return
print(json.dumps({
"ts": datetime.now(timezone.utc).isoformat(),
"event": "before_tool",
"tool": event_data.tool_name,
}))
@add_hook('after_tool')
def audit_after(event_data):
if not event_data or not event_data.tool_name:
return
print(json.dumps({
"ts": datetime.now(timezone.utc).isoformat(),
"event": "after_tool",
"tool": event_data.tool_name,
}))
| @registry.on(HookEvent.BEFORE_TOOL) | ||
| def file_guard(event_data) -> HookResult: | ||
| if event_data.tool_name.startswith("write_"): | ||
| print(f"Write operation: {event_data.tool_name}") | ||
| return HookResult.allow() |
There was a problem hiding this comment.
Accessing event_data.tool_name directly without verifying if event_data or event_data.tool_name is None can lead to an AttributeError. It is safer to add a defensive check.
@registry.on(HookEvent.BEFORE_TOOL)
def file_guard(event_data) -> HookResult:
if not event_data or not event_data.tool_name:
return HookResult.allow()
if event_data.tool_name.startswith("write_"):
print(f"Write operation: {event_data.tool_name}")
return HookResult.allow()
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
1 participant
Summary
Batch 1 of the documentation audit for docs/features/ as requested in #821.
Applied the full AGENTS.md conformance checklist to 6 foundational feature pages:
Pages Updated
planning-mode.mdxlist-check), addedsidebarTitle, PraisonAI-centric Quick Start with<Steps>, hero diagram with 5-color scheme, removed Cursor/Windsurf comparison tableoutput-styles.mdxsidebarTitle, hero Mermaid with decision diagram,<Steps>, removed non-friendly imports (OutputStyle→OutputConfig)guardrails.mdxsidebarTitle, fixed non-standard Mermaid color (#2E8B57→#10B981), replaced non-friendly import (LLMGuardrail→GuardrailConfig),<Steps>, sequence diagramhooks.mdxsidebarTitle, hero diagram,<Steps>withadd_hook+HooksConfigpatterns, fixed icon (link→webhook),<AccordionGroup>skills.mdxsidebarTitle, hero 3-level progressive loading diagram,<Steps>, replacedSkillManagerdirect import withSkillsConfigasync.mdxsidebarTitle, fixed non-standard colors (#2E8B57→#189AB4), replacedAgentTeamwithPraisonAIAgents,<Steps>,<AccordionGroup>, sequence diagramConformance Checklist Applied
sidebarTitleadded to all pages#8B0000/#189AB4/#10B981/#F59E0B/#6366F1,#ffftext,#7C90A0stroke<Steps>(simple → config)<AccordionGroup>(4 accordions each)<CardGroup cols={2}>(2 cards each)from praisonaiagents import ...)docs/concepts/pages toucheddocs.jsonunchanged and validNot Included in Batch 1
The remaining ~406 files in
docs/features/will be handled in subsequent batches per the suggestion in #821 ("PR per logical batch").Fixes #821
Generated with Claude Code