From db430fe57dd168d66848360f89a20b6d0e684406 Mon Sep 17 00:00:00 2001 From: praisonai-bot Date: Sat, 9 May 2026 22:53:27 +0100 Subject: [PATCH] feat(examples): add scientific writing examples (CAJAL re-implementation) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-implements the CAJAL / scientific-paper functionality that was reverted from the core SDK (PR #1611 / revert #1641) as proper examples per AGENTS.md: - examples/scientific_writing/scientific_writer.py Single-agent pattern: regular Agent + @tool functions, no subclass. Uses the CAJAL-4B HuggingFace model via litellm. - examples/scientific_writing/multi_agent_paper.py Multi-agent workflow: Literature Reviewer -> Methodologist -> Writer composed with AgentTeam + sequential Tasks (no custom Agent classes). - examples/scientific_writing/agents.yaml YAML parity for the multi-agent workflow (AGENTS.md §7 '3-way' rule). Why this location: - AGENTS.md §4.1: core SDK has no heavy domain implementations. - AGENTS.md §4.4: compose specialised Agents + tools, don't subclass Agent. - AGENTS.md §6.1: domain-specific behaviour belongs in @tool functions. - Wrapper / praisonai-tools were alternatives; examples/ keeps it discoverable and avoids bloating either package. --- examples/scientific_writing/agents.yaml | 40 +++++++++ .../scientific_writing/multi_agent_paper.py | 73 ++++++++++++++++ .../scientific_writing/scientific_writer.py | 85 +++++++++++++++++++ 3 files changed, 198 insertions(+) create mode 100644 examples/scientific_writing/agents.yaml create mode 100644 examples/scientific_writing/multi_agent_paper.py create mode 100644 examples/scientific_writing/scientific_writer.py diff --git a/examples/scientific_writing/agents.yaml b/examples/scientific_writing/agents.yaml new file mode 100644 index 000000000..cbbf4487f --- /dev/null +++ b/examples/scientific_writing/agents.yaml @@ -0,0 +1,40 @@ +# Scientific paper workflow — YAML equivalent of multi_agent_paper.py +# Run with: +# praisonai agents run --file 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." diff --git a/examples/scientific_writing/multi_agent_paper.py b/examples/scientific_writing/multi_agent_paper.py new file mode 100644 index 000000000..fca878011 --- /dev/null +++ b/examples/scientific_writing/multi_agent_paper.py @@ -0,0 +1,73 @@ +"""Multi-agent scientific paper workflow (Researcher -> Methodologist -> Writer). + +Demonstrates the agent-centric pattern from AGENTS.md: compose specialised +Agents with ``AgentTeam`` + sequential ``Task``s instead of creating custom +Agent subclasses. The writer uses the CAJAL-4B HuggingFace model; the +reviewer and methodologist use general-purpose LLMs. + +Usage: + python examples/scientific_writing/multi_agent_paper.py +""" +from praisonaiagents import Agent, AgentTeam, Task + +from scientific_writer import ( # noqa: E402 — example imports a sibling file + build_scientific_writer, + format_citation, + format_latex_section, +) + + +literature_reviewer = Agent( + name="Literature Reviewer", + instructions=( + "You are an expert at surveying academic literature. " + "Produce a concise literature review with 5-8 key citations in APA." + ), + tools=[format_citation], +) + +methodology_designer = Agent( + name="Methodology Designer", + instructions=( + "You design rigorous research methodologies. " + "Output a clear, reproducible methods section." + ), + tools=[format_latex_section], +) + +scientific_writer = build_scientific_writer() + + +def run(topic: str) -> str: + """Run the 3-agent workflow for a given research ``topic``.""" + 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 research methodology for: {topic}", + agent=methodology_designer, + expected_output="LaTeX methods section.", + ) + t3 = Task( + name="write_paper", + description=( + f"Combine the literature review and methodology into a full " + f"scientific paper on: {topic}. Use LaTeX formatting." + ), + agent=scientific_writer, + expected_output="Complete LaTeX paper.", + ) + team = AgentTeam( + agents=[literature_reviewer, methodology_designer, scientific_writer], + tasks=[t1, t2, t3], + ) + return team.start() + + +if __name__ == "__main__": + result = run("Transformer architectures for protein folding prediction") + print(result) diff --git a/examples/scientific_writing/scientific_writer.py b/examples/scientific_writing/scientific_writer.py new file mode 100644 index 000000000..de8438bfa --- /dev/null +++ b/examples/scientific_writing/scientific_writer.py @@ -0,0 +1,85 @@ +"""Scientific Paper Writer — single-agent example using the CAJAL model. + +CAJAL (``Agnuxo/CAJAL-4B-P2PCLAW``) is a 4B-parameter HuggingFace model +specialised for LaTeX-formatted academic writing. This example shows how +to use it with a regular ``Agent`` and ``@tool`` functions — no new Agent +subclass is needed. Run 3 ways: Python (this file), CLI, or YAML. + +Requirements: + pip install "praisonaiagents[llm]" # for litellm / HuggingFace + export HUGGINGFACE_API_KEY=... # or run a local inference server + +Usage: + python examples/scientific_writing/scientific_writer.py +""" +from praisonaiagents import Agent, tool + + +@tool +def format_latex_section(title: str, content: str) -> str: + """Wrap prose content in a LaTeX ``\\section{}`` block. + + Args: + title: Section heading (e.g. ``"Introduction"``). + content: The body text. + + Returns: + LaTeX-formatted section string. + """ + return f"\\section{{{title}}}\n{content}\n" + + +@tool +def format_citation(authors: str, year: int, title: str, venue: str) -> str: + """Render a single APA-style citation line. + + Args: + authors: ``"Smith, J. & Jones, A."`` + year: Publication year. + title: Paper title. + venue: Journal / conference name. + + Returns: + One APA-formatted citation string. + """ + return f"{authors} ({year}). {title}. *{venue}*." + + +SCIENTIFIC_INSTRUCTIONS = """You are a specialised scientific paper writer. + +Produce high-quality academic content with: +- Clear structure (Abstract, Introduction, Methodology, Results, Discussion, + Conclusion, References) +- Rigorous methodology and precise language +- Proper APA citations and LaTeX formatting +- Honest limitations and future work sections + +Use ``format_latex_section`` to wrap each section in LaTeX, and +``format_citation`` to build the References list. +""" + + +def build_scientific_writer( + model: str = "huggingface/Agnuxo/CAJAL-4B-P2PCLAW", +) -> Agent: + """Construct a scientific-writing Agent. + + Override ``model`` for any HuggingFace / local / API model — the default + targets the CAJAL-4B checkpoint for LaTeX-style academic output. + """ + return Agent( + name="Scientific Writer", + instructions=SCIENTIFIC_INSTRUCTIONS, + llm=model, + tools=[format_latex_section, format_citation], + ) + + +if __name__ == "__main__": + agent = build_scientific_writer() + paper = agent.start( + "Write a short scientific paper (Abstract + Introduction + Conclusion) " + "on 'Climate change effects on coral reef biodiversity'. " + "Use LaTeX formatting and include at least 3 APA citations." + ) + print(paper)