[Docs] Add Scientific Writing example (CAJAL-4B LaTeX paper writer + multi-agent workflow)

[MervinPraison]

Summary

PraisonAI PR #1644 (merged) adds a brand-new Scientific Writing example set under examples/scientific_writing/ in the PraisonAI repo. This is a re-implementation of the previously-reverted CAJAL Scientific Writer feature (PR #1611 → revert #1641), now correctly placed as user-facing examples per AGENTS.md §4.1.

These examples are not currently documented in PraisonAIDocs and need a new documentation page (no existing page covers LaTeX/academic-paper generation or the CAJAL-4B HuggingFace model).

Action required: Create one new documentation page that walks the user through using PraisonAI to generate scientific/LaTeX papers, both single-agent and multi-agent (Python + YAML).

---

Source PR Reference

• PR: feat(examples): CAJAL scientific writing — re-implemented as examples (not core) PraisonAI#1644
• Merged commit: db430fe57dd168d66848360f89a20b6d0e684406
• Base branch: main
• Files added (3):
  • examples/scientific_writing/scientific_writer.py (85 lines) — single-agent
  • examples/scientific_writing/multi_agent_paper.py (73 lines) — 3-agent workflow
  • examples/scientific_writing/agents.yaml (40 lines) — YAML parity

---

Decision: New page vs. update existing

Option	Decision	Why
Update docs/examples/research-assistant.mdx	❌ No	Different scope: research-assistant is a web-search → gap-analysis → experiment-design pipeline. Scientific Writing is paper generation in LaTeX with a domain-specific model.
Update an existing recipe under docs/examples/agent-recipes/documents/	❌ No	Recipe pages are short single-task docs. This example showcases the agent-centric multi-agent + 3-way (Python/YAML/CLI) pattern and deserves a full case-study page.
Create new page docs/examples/scientific-writer.mdx	✅ Yes	Joins peer pages such as research-assistant.mdx, healthcare-diagnosis.mdx, medicine-protocol.mdx in the Examples → Examples group. ~200–300 lines like the others.

---

File to create

Path: docs/examples/scientific-writer.mdx

Frontmatter:

---
title: "Scientific Writer"
sidebarTitle: "Scientific Writer"
description: "Generate LaTeX-formatted academic papers with the CAJAL-4B model — single agent or multi-agent workflow"
icon: "graduation-cap"
---

Suggested icon alternatives: graduation-cap, microscope-circle, flask, book-open-cover. Pick whatever is consistent with peers in docs/examples/.

---

docs.json update required

Add the new page to the Examples → Examples group at docs.json line ~2145, right after research-assistant:

"docs/examples/research-assistant",
"docs/examples/scientific-writer",   // ← add this line
"docs/examples/quantum-optimiser"

⚠️ Per AGENTS.md §1.8, do not place this in docs/concepts/ or in any auto-generated section. The Examples → Examples group is the correct location.

---

Content the page MUST cover

Follow the AGENTS.md page-structure template (frontmatter → hero mermaid diagram → Quick Start <Steps> → How It Works → Configuration → Common Patterns → Best Practices → Related). Be agent-centric, beginner-friendly, and progressive.

Section 1 — Hero Mermaid diagram

Show the agent-centric flow. Use the standard color scheme (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1).

graph LR
    Topic[📝 Research Topic] --> Writer[🧪 Scientific Writer Agent]
    Writer --> LaTeX[📄 LaTeX Section]
    Writer --> Cite[📚 APA Citation]
    LaTeX --> Paper[📑 Final Paper]
    Cite --> Paper

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    class Topic input
    class Writer agent
    class LaTeX,Cite tool
    class Paper result

Loading

Section 2 — Setup

pip install "praisonaiagents[llm]"
export HUGGINGFACE_API_KEY="your-key"   # for CAJAL-4B via litellm
# Optional fallback: export OPENAI_API_KEY="your-key"

Section 3 — Quick Start (single agent, agent-centric)

The very first code block on the page must be a minimal agent-centric example so the user feels "is it really this easy?".

from praisonaiagents import Agent, tool


@tool
def format_latex_section(title: str, content: str) -> str:
    """Wrap prose in a LaTeX \\section{} block."""
    return f"\\section{{{title}}}\n{content}\n"


@tool
def format_citation(authors: str, year: int, title: str, venue: str) -> str:
    """Render an APA citation."""
    return f"{authors} ({year}). {title}. *{venue}*."


agent = Agent(
    name="Scientific Writer",
    instructions="You are a specialised scientific paper writer. Use LaTeX formatting and APA citations.",
    llm="huggingface/Agnuxo/CAJAL-4B-P2PCLAW",
    tools=[format_latex_section, format_citation],
)

agent.start(
    "Write a short paper (Abstract + Introduction + Conclusion) on "
    "'Climate change effects on coral reef biodiversity'."
)

💡 Tip callout: swap llm="huggingface/Agnuxo/CAJAL-4B-P2PCLAW" for any other model (e.g. gpt-4o-mini) to use a general-purpose LLM if HuggingFace access is unavailable.

Section 4 — Multi-agent workflow (Literature Reviewer → Methodology Designer → Writer)

Use a sequence diagram to show the agent collaboration:

sequenceDiagram
    participant User
    participant Reviewer as Literature Reviewer
    participant Designer as Methodology Designer
    participant Writer as Scientific Writer

    User->>Reviewer: Topic
    Reviewer-->>Designer: Literature review (APA)
    Designer-->>Writer: Methods (LaTeX)
    Writer-->>User: Complete LaTeX paper

Loading

Then show the Python multi-agent code, copied/adapted from examples/scientific_writing/multi_agent_paper.py:

from praisonaiagents import Agent, AgentTeam, Task

literature_reviewer = Agent(
    name="Literature Reviewer",
    instructions="Survey academic literature. Produce 5–8 APA citations.",
    tools=[format_citation],
)

methodology_designer = Agent(
    name="Methodology Designer",
    instructions="Design a reproducible research methodology.",
    tools=[format_latex_section],
)

scientific_writer = Agent(
    name="Scientific Writer",
    instructions="Assemble the final paper. Use LaTeX + APA.",
    llm="huggingface/Agnuxo/CAJAL-4B-P2PCLAW",
    tools=[format_latex_section, format_citation],
)

topic = "Transformer architectures for protein folding prediction"

t1 = Task(name="review_literature", description=f"Review literature on: {topic}",
          agent=literature_reviewer, expected_output="APA literature review.")
t2 = Task(name="design_methodology", description=f"Design methodology for: {topic}",
          agent=methodology_designer, expected_output="LaTeX methods section.")
t3 = Task(name="write_paper",
          description=f"Combine review + methodology into a full paper on: {topic}.",
          agent=scientific_writer, expected_output="Complete LaTeX paper.")

team = AgentTeam(
    agents=[literature_reviewer, methodology_designer, scientific_writer],
    tasks=[t1, t2, t3],
)
print(team.start())

Section 5 — Run with YAML (3-way parity)

Use <Tabs> or <CodeGroup> to show YAML alternative. Copy verbatim from examples/scientific_writing/agents.yaml:

framework: praisonai
topic: "Climate change effects on coral reef biodiversity"

roles:
  literature_reviewer:
    role: "Literature Reviewer"
    goal: "Survey recent academic work on {topic} and produce an APA review."
    backstory: "Expert in academic literature surveying and citation hygiene."
    llm: "gpt-4o-mini"
    tasks:
      review_literature:
        description: "Produce a concise literature review with 5-8 APA citations."
        expected_output: "APA-formatted literature review."

  methodology_designer:
    role: "Methodology Designer"
    goal: "Design a reproducible research methodology for {topic}."
    backstory: "Specialises in rigorous experimental design."
    llm: "gpt-4o-mini"
    tasks:
      design_methodology:
        description: "Write a reproducible methods section in LaTeX."
        expected_output: "LaTeX methods section."

  scientific_writer:
    role: "Scientific Writer"
    goal: "Assemble the final LaTeX paper on {topic}."
    backstory: >-
      Specialised in LaTeX-formatted academic papers, fine-tuned on
      scientific literature (CAJAL-4B checkpoint).
    llm: "huggingface/Agnuxo/CAJAL-4B-P2PCLAW"
    tasks:
      write_paper:
        description: >-
          Combine the literature review and methodology into a full
          scientific paper on {topic}. Use LaTeX formatting.
        expected_output: "Complete LaTeX paper."

Run command:

praisonai agents run --file agents.yaml

Section 6 — Decision diagram: which option to choose?

Per AGENTS.md §6.1, when multiple options exist on one page, include a "which to choose" mermaid diagram so non-developers don't get confused:

graph TB
    Q{Need full paper<br/>with literature + methods?}
    Q -->|No, just one section| Single[Single Agent<br/>scientific_writer.py]
    Q -->|Yes| Q2{Prefer code<br/>or config file?}
    Q2 -->|Python code| Multi[Multi-Agent<br/>multi_agent_paper.py]
    Q2 -->|YAML config| YAML[YAML workflow<br/>agents.yaml]

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef option fill:#189AB4,stroke:#7C90A0,color:#fff
    class Q,Q2 question
    class Single,Multi,YAML option

Loading

Section 7 — Configuration / Tools table

Tool	Purpose	Inputs
format_latex_section	Wrap prose in \section{}	title: str, content: str
format_citation	Build APA citation line	authors: str, year: int, title: str, venue: str

Section 8 — Best Practices (<AccordionGroup>)

Cover at least:

• Choosing the right model (CAJAL-4B for LaTeX-fluent output vs. general-purpose gpt-4o-mini when HF access is unavailable)
• Adding more @tool functions (e.g. format_equation, format_table, format_figure_caption) to extend the writer
• Splitting long papers across multiple agents/tasks (one task per section)
• HuggingFace API key vs. local inference server for CAJAL-4B

Section 9 — Related (<CardGroup cols={2}>)

Link to:

• /docs/examples/research-assistant — multi-agent research workflow
• /docs/concepts/agents — Agent fundamentals
• /docs/concepts/tasks (or equivalent) — Task and AgentTeam
• /docs/features/yaml-config (or equivalent) — YAML configuration

---

Constraints & rules to follow (from AGENTS.md)

• ✅ Place the new page in docs/examples/ (Examples tab). NOT docs/concepts/ (humans only) and NOT docs/js/ or docs/rust/ (auto-generated).
• ✅ Use simple imports from praisonaiagents import Agent, AgentTeam, Task, tool — no submodule imports.
• ✅ Lead with an agent-centric example before any tool/config detail.
• ✅ Hero diagram with the standard color scheme + white text on coloured fills.
• ✅ Use Mintlify components: <Steps>, <AccordionGroup>, <CardGroup>, <Tabs>, <Note>/<Tip>/<Warning>.
• ✅ One-sentence section intros. No "In this section…", "As you can see…", "It's important to note…".
• ✅ Every code example must run as-is — include all imports.
• ✅ Validate docs.json is still valid JSON after the addition.
• ❌ Do not duplicate or rewrite docs/examples/research-assistant.mdx.
• ❌ Do not document any feature that is not actually present in the three source files of the PR.

---

Acceptance criteria

• New file docs/examples/scientific-writer.mdx exists with all sections above.
• Frontmatter complete (title, sidebarTitle, description, icon).
• Hero mermaid diagram present with standard colours.
• Single-agent Quick Start runs as-is.
• Multi-agent example matches multi_agent_paper.py.
• YAML example matches agents.yaml byte-for-byte (preserved verbatim).
• Decision diagram for picking single vs multi vs YAML included.
• docs.json updated — page added to Examples → Examples group, valid JSON, builds without errors.
• Related cards link to existing pages only (no broken links).
• No content placed in docs/concepts/, docs/js/, or docs/rust/.

---

Triggered by PR MervinPraison/PraisonAI#1644 merge on 2026-05-09. Another agent will pick up this issue and create the documentation page.

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

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

---

✅ Scientific Writer Documentation Created

I've successfully implemented the Scientific Writer documentation based on PR #1644.

Completed Tasks:

• Set up git identity and auth
• Read AGENTS.md guidelines
• Access PraisonAI source examples
• Create docs/examples/scientific-writer.mdx
• Update docs.json navigation
• Commit and push changes
• Create PR

📋 What Was Created

New documentation page: docs/examples/scientific-writer.mdx

🎯 Key Features

• Agent-centric Quick Start with CAJAL-4B model for LaTeX academic writing
• Three workflow patterns: Single-agent, multi-agent Python, and YAML config
• Tool functions: format_latex_section() and format_citation() for LaTeX/APA formatting
• Decision diagram to help users choose the right approach
• Hero Mermaid diagram with standard color scheme (#8B0000, #189AB4, #10B981, etc.)
• Best practices covering model selection, tool extension, and API setup

📚 Content Structure

Following AGENTS.md guidelines:

• Hero diagram → Quick Start → Multi-agent workflow → YAML config
• Configuration options table → Decision diagram → Best practices
• Related cards linking to research-assistant, agents concepts, tasks, and YAML reference

🔗 Navigation Update

Added to docs.json in Examples → Examples group, placed after research-assistant as specified in the issue.

🚀 Pull Request Created

PR #340: docs: Add Scientific Writer documentation

The documentation is ready for review and covers all requirements from the issue:

• CAJAL-4B HuggingFace model integration
• Single-agent and multi-agent workflows
• YAML configuration parity
• Copy-paste runnable code examples
• Proper placement in docs.json navigation
  | Branch: claude/issue-339-20260509-2157