[docs] Architectural drift: `home.mdx` marketing snippet vs `Agent` reflection surface

[Dhivya-Bharathy]

Docs: docs/home.mdx — “Self-Reflection & Reasoning” accordion
SDK: praisonaiagents.agent.agent.Agent + ReflectionConfig
Kind: Documentation — invalid constructor kwargs on Agent

---

1. Executive summary

Field	Content
Symptom	Marketing code shows Agent(..., self_reflect=True, reasoning=True, max_reflect=3). Current Agent.__init__ rejects self_reflect and max_reflect; reasoning is not a documented top-level Agent kwarg in the same sense as this snippet implies.
Root cause	Legacy reflection parameters were consolidated into reflection= / ReflectionConfig (see Agent docstring). Public marketing page still shows pre-consolidation API.
Impact	First-touch users copy from homepage and immediately hit TypeError — highest visibility failure mode.
Fix	PraisonAIDocs — rewrite snippet to reflection=True or reflection=ReflectionConfig(max_iterations=3, ...). Clarify relationship to output / reasoning_steps if “reasoning” is meant as CoT display (different subsystem).

---

2. Architecture — reflection subsystem on Agent

2.1 Public constructor contract

File: praisonaiagents/agent/agent.py

        reflection: Optional[Union[bool, str, 'ReflectionConfig']] = None,

Docstring consolidation map (excerpt):

            - self_reflect, max_reflect, min_reflect, reflect_llm → reflection=

So self_reflect, max_reflect, etc. are not independent Agent kwargs; they flow through reflection=.

2.2 ReflectionConfig shape

File: praisonaiagents/config/feature_configs.py

@dataclass
class ReflectionConfig:
    ...
    min_iterations: int = 1
    max_iterations: int = 3
    llm: Optional[str] = None
    prompt: Optional[str] = None

Note: max_iterations on config — docs/marketing used max_reflect=3 naming; align prose to ReflectionConfig field names or use reflection=True shorthand.

flowchart LR
  subgraph Legacy["home.mdx (today)"]
    L1["self_reflect="]
    L2["max_reflect="]
    L3["reasoning="]
  end
  subgraph Modern["Agent public API"]
    R1["reflection=True"]
    R2["reflection=ReflectionConfig(...)"]
  end
  Legacy -->|kwargs| X["TypeError"]
  R1 --> OK["Valid"]
  R2 --> OK

Loading

---

3. “Reasoning” naming — avoid conflation

The homepage text mixes self-reflection loops with “chain-of-thought” reasoning.

In Agent, verbose / reasoning display is primarily an output= concern (reasoning_steps, etc.), not the same parameter as reflection= (post-hoc self-critique iterations).

Suggested doc architecture:

flowchart TB
  subgraph Reflection["reflection= / ReflectionConfig"]
    R["Post-response critique iterations"]
  end
  subgraph Output["output= / OutputConfig"]
    O["Inline reasoning_steps / stream / verbose"]
  end
  HomeSnippet["home.mdx snippet"] --> Fix1["Use reflection= for self_reflect/max_reflect story"]
  HomeText["home.mdx prose"] --> Fix2["Separate bullets: reflection vs output reasoning"]

Loading

---

4. Doc inventory — failing block

File: docs/home.mdx — “🧠 Self-Reflection & Reasoning” accordion (~L83–90)

agent = Agent(
    name="analyst",
    self_reflect=True,
    reasoning=True,
    max_reflect=3
)

---

5. Reproduction

from praisonaiagents import Agent
Agent(name="a", instructions="x", self_reflect=True, reasoning=True, max_reflect=3)
# TypeError: Agent.__init__() got an unexpected keyword argument 'self_reflect'

---

6. Suggested replacement (illustrative — verify product wording)

Minimal:

from praisonaiagents import Agent

agent = Agent(
    name="analyst",
    instructions="You analyze data carefully.",
    reflection=True,
)

With iteration cap:

from praisonaiagents import Agent, ReflectionConfig

agent = Agent(
    name="analyst",
    instructions="You analyze data carefully.",
    reflection=ReflectionConfig(max_iterations=3),
)

If CoT display is required in the same accordion, add a second small snippet using output= / preset, with a sentence explaining it is not the same as reflection=.

---

7. Acceptance criteria

• No self_reflect=, max_reflect= on Agent in home.mdx unless reintroduced in SDK (then version-gate).
• reasoning=True removed or mapped to a real parameter (output=…) with explicit explanation.
• Copy-paste of the accordion snippet constructs Agent without TypeError on documented praisonaiagents.

---

8. References

• praisonaiagents/agent/agent.py — reflection= param + consolidation note
• praisonaiagents/config/feature_configs.py — ReflectionConfig
• docs/concepts/reflection.mdx (if present) — cross-link for long-form

---

9. Suggested labels

documentation, bug, homepage, reflection, dx

[MervinPraison]

👋 Thanks for opening this issue, @Dhivya-Bharathy!

A maintainer will review this shortly. In the meantime:

• Make sure you've included steps to reproduce (for bugs)
• Check existing issues for duplicates
• Review the documentation for related guides

[MervinPraison]

@claude validate and fix it

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-204-20260422-0445 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-204-20260422-0445?quick_pull=1&title=Issue%20%23204%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23204%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

✅ Documentation architectural drift fixed

I've successfully validated and fixed the issue reported in #204.

What was fixed:

Problem: The "Self-Reflection & Reasoning" section in docs/home.mdx contained invalid legacy reflection API parameters:

• self_reflect=True ❌ (Invalid parameter)
• reasoning=True ❌ (Not a top-level Agent parameter)
• max_reflect=3 ❌ (Invalid parameter)

This caused immediate TypeError: Agent.__init__() got an unexpected keyword argument 'self_reflect' for users copying from the homepage.

Solution: Updated to use the current consolidated reflection API:

from praisonaiagents import Agent, ReflectionConfig

# Simple reflection
agent = Agent(
    name="analyst",
    instructions="You analyze data carefully.",
    reflection=True          # ✅ Valid
)

# Advanced reflection with custom iterations  
agent = Agent(
    name="analyst",
    instructions="You analyze data carefully.", 
    reflection=ReflectionConfig(max_iterations=3)  # ✅ Valid
)

Changes made:

• Set up git identity and auth
• Read AGENTS.md for documentation standards
• Examined current docs/home.mdx to locate problematic snippet
• Read SDK source code to understand correct Agent reflection API
• Validated the issue by reproducing the TypeError
• Updated documentation with correct reflection syntax
• Committed and pushed changes
• Created pull request

Verification:

✅ Both examples tested and confirmed to work without TypeError
✅ Follows current Agent API from praisonaiagents/agent/agent.py:537 and ReflectionConfig from feature_configs.py:388
✅ Includes proper imports and working instructions parameter

Pull Request: #216

The fix ensures first-touch users can successfully copy-paste from the homepage without hitting the highest visibility failure mode (TypeError on construction).

---

Job Run | Branch: claude/issue-204-20260422-0445