upd code

.gitignore

@@ -0,0 +1,16 @@
+templates/**/*.wav
+templates/**/*.mp4
+templates/**/*.gif
+templates/**/*.webm
+templates/**/*.mov
+templates/**/*.pdf*.ttf
+templates/**/*.pdf
+templates/**/*?
+*.woff
+*.woff2
+*.png
+*.jpg
+
+.DS_Store
+
+**/__pycache__/*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Qianli Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ProjectPageAgent/__init__.py

@@ -0,0 +1,7 @@
+"""
+ProjectPageAgent: A multi-agent system for generating project pages from research papers.
+Based on Paper2Poster architecture, adapted for project page generation.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Paper2ProjectPage Team" 

ProjectPageAgent/content_planner.py

@@ -0,0 +1,509 @@
+"""
+Content planner for project page generation.
+Plans the structure and content organization for the project page.
+"""
+
+import json
+import yaml
+import os
+from jinja2 import Environment, StrictUndefined
+from camel.models import ModelFactory
+from camel.agents import ChatAgent
+from utils.wei_utils import  account_token
+from utils.src.utils import get_json_from_response
+from camel.messages import BaseMessage
+from rich import print
+from rich.pretty import Pretty
+import base64
+from camel.messages import BaseMessage
+from camel.models import ModelFactory
+
+def filter_references(md_content: str) -> str:
+  
+    lines = md_content.splitlines()
+    result_lines = []
+    for line in lines:
+        if line.strip().lower().startswith("## references"):
+            break  
+        result_lines.append(line)
+    return "\n".join(result_lines)
+
+class ProjectPageContentPlanner:
+    """Plans the content structure and organization for project pages."""
+    
+    def __init__(self, agent_config, args):
+        self.agent_config = agent_config
+        self.args = args
+        self.planner_agent = self._create_planner_agent()      
+        self.reviewer_agent = self._create_reviewer_agent()   
+        os.makedirs('project_contents', exist_ok=True)
+        
+    def _create_planner_agent(self):
+        """Create the content planning (generation) agent."""
+        model_type = str(self.agent_config['model_type'])
+        
+        # Get API key from environment variables
+        api_key = None
+        if self.args.model_name_t in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+            api_key = os.environ.get('OPENAI_API_KEY')
+        elif self.args.model_name_t in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+            api_key = os.environ.get('GEMINI_API_KEY')
+        elif self.args.model_name_t in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+            api_key = os.environ.get('QWEN_API_KEY')
+        elif self.args.model_name_t.startswith('openrouter_'):
+            api_key = os.environ.get('OPENROUTER_API_KEY')
+        elif self.args.model_name_t in ['zhipuai']:
+            api_key = os.environ.get('ZHIPUAI_API_KEY')
+        
+        if model_type.startswith('vllm_qwen') or 'vllm' in model_type.lower():
+            model = ModelFactory.create(
+                model_platform=self.agent_config['model_platform'],
+                model_type=self.agent_config['model_type'],
+                model_config_dict=self.agent_config['model_config'],
+                url=self.agent_config.get('url', None),
+                api_key=api_key,
+            )
+        else:
+            model = ModelFactory.create(
+                model_platform=self.agent_config['model_platform'],
+                model_type=self.agent_config['model_type'],
+                model_config_dict=self.agent_config['model_config'],
+                api_key=api_key,
+            )
+
+        
+        system_message = """You are a helpful academic expert and web developer, who is specialized in generating a paper project page, from given research paper's contents and figures."""
+        
+        return ChatAgent(
+            system_message=system_message,
+            model=model,
+            message_window_size=10,
+            token_limit=self.agent_config.get('token_limit', None)
+        )
+
+    def _create_reviewer_agent(self):
+       
+        model_type = str(self.agent_config['model_type'])
+        
+        # Get API key from environment variables
+        api_key = None
+        if self.args.model_name_t in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+            api_key = os.environ.get('OPENAI_API_KEY')
+        elif self.args.model_name_t in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+            api_key = os.environ.get('GEMINI_API_KEY')
+        elif self.args.model_name_t in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+            api_key = os.environ.get('QWEN_API_KEY')
+        elif self.args.model_name_t.startswith('openrouter_'):
+            api_key = os.environ.get('OPENROUTER_API_KEY')
+        elif self.args.model_name_t in ['zhipuai']:
+            api_key = os.environ.get('ZHIPUAI_API_KEY')
+        
+        if model_type.startswith('vllm_qwen') or 'vllm' in model_type.lower():
+            model = ModelFactory.create(
+                model_platform=self.agent_config['model_platform'],
+                model_type=self.agent_config['model_type'],
+                model_config_dict=self.agent_config['model_config'],
+                url=self.agent_config.get('url', None),
+                api_key=api_key,
+            )
+        else:
+            model = ModelFactory.create(
+                model_platform=self.agent_config['model_platform'],
+                model_type=self.agent_config['model_type'],
+                model_config_dict=self.agent_config['model_config'],
+                api_key=api_key,
+            )
+        
+        reviewer_system = (
+            "You are a precise, constructive reviewer of generated project pages. "
+        )
+        return ChatAgent(
+            system_message=reviewer_system,
+            model=model,
+            message_window_size=10,
+            token_limit=self.agent_config.get('token_limit', None)
+        )
+
+    def _render_generation_prompt(self, paper_content, figures, text_page_content, template_str):
+      
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(template_str)
+        jinja_args = {
+            'paper_content': paper_content,
+            'figures': json.dumps(figures, indent=2),
+            'project_page_content': json.dumps(text_page_content, indent=2),
+        }
+        return template.render(**jinja_args)
+
+    def _build_reviewer_prompt(self, paper_content, figures, text_page_content, generated_json):
+       
+        with open('utils/prompt_templates/page_templates/full_content_review.yaml', 'r') as f:
+            planner_config = yaml.safe_load(f)
+        
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(planner_config["template"])
+        
+        jinja_args = {
+            'paper_content': paper_content,
+            'figures': json.dumps(figures['images'], indent=2),
+            'tables': json.dumps(figures['tables'], indent=2),
+            "generated_content": generated_json
+        }
+        
+        prompt = template.render(**jinja_args)
+
+        return prompt
+
+    def _build_revision_prompt(self, review_json):
+        with open('utils/prompt_templates/page_templates/full_content_revise.yaml', 'r') as f:
+            planner_config = yaml.safe_load(f)
+        
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(planner_config["template"])
+        
+        jinja_args = {
+            "review_content": json.dumps(review_json, indent=2)
+        }
+        
+        prompt = template.render(**jinja_args)
+
+        return prompt
+
+    def _build_revision_prompt_with_resume(self, review_json, current_content, figures):
+        with open('utils/prompt_templates/page_templates/full_content_revise_with_resume.yaml', 'r') as f:
+            planner_config = yaml.safe_load(f)
+
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(planner_config["template"])
+
+        print(review_json)
+
+        jinja_args = {
+            "review_content": json.dumps(review_json, indent=2),
+            "figures": json.dumps(figures, indent=2),
+            "current_content": current_content
+        }
+
+        prompt = template.render(**jinja_args)
+
+        return prompt
+
+    def full_content_generation(
+        self,
+        args,
+        paper_content,
+        figures,
+        generated_section,
+        text_page_content,
+    ):
+        """
+        Plan + Generate -> Review -> Revise 
+        
+        Args:
+            paper_content: parsed paper content
+            figures: list/dict of figures
+            generated_section: format_instructions / schema hints
+            text_page_content: initial text-only page structure
+        
+        Returns:
+            tuple: (final_generated_content_json, input_token_total, output_token_total)
+        """
+        if args.resume in ['parse_pdf','generate_content']:
+
+            print("full content generation start")
+
+            with open('utils/prompt_templates/page_templates/full_content_generation.yaml', 'r') as f:
+                planner_config = yaml.safe_load(f)
+            
+            jinja_env = Environment(undefined=StrictUndefined)
+            template = jinja_env.from_string(planner_config["template"])
+            
+            jinja_args = {
+                'paper_content': paper_content,
+                'figures': json.dumps(figures, indent=2),
+                'project_page_content': json.dumps(text_page_content, indent=2)
+            }
+            
+            prompt = template.render(**jinja_args)
+            
+            self.planner_agent.reset()
+            response = self.planner_agent.step(prompt)
+            
+            gen_in_tok, gen_out_tok = account_token(response)
+
+            current_output = get_json_from_response(response.msgs[0].content)
+
+            first_path = f'project_contents/{self.args.paper_name}_generated_full_content.v0.json'
+            with open(first_path, 'w', encoding='utf-8') as f:
+                json.dump(current_output, f, ensure_ascii=False, indent=2)
+            print(f"  - Initial generation saved: {first_path}")
+
+            total_in_tok, total_out_tok = gen_in_tok, gen_out_tok
+        else:
+            print("Skipping initial full content generation, loading existing content.")
+            with open(f'project_contents/{self.args.paper_name}_generated_full_content.v0.json', 'r', encoding='utf-8') as f:
+                current_output = json.load(f)
+            total_in_tok, total_out_tok = 0, 0
+
+        for it in range(0, args.full_content_check_times):
+            # check
+            self.reviewer_agent.reset()
+
+            review_prompt = self._build_reviewer_prompt(
+                paper_content=paper_content,
+                figures=figures,
+                text_page_content=text_page_content,
+                generated_json=current_output
+            )
+            review_resp = self.reviewer_agent.step(review_prompt)
+            rin, rout = account_token(review_resp)
+
+            review_json = get_json_from_response(review_resp.msgs[0].content)
+
+            review_path = f'project_contents/{self.args.paper_name}_review.iter{it}.json'
+            with open(review_path, 'w', encoding='utf-8') as f:
+                json.dump(review_json, f, ensure_ascii=False, indent=2)
+            print(f"  - Review saved: {review_path}")
+
+            total_in_tok += rin
+            total_out_tok += rout
+
+            if args.resume != 'full_content_check':
+                revision_prompt = self._build_revision_prompt(
+                    review_json=review_json
+                )
+
+            else:
+                revision_prompt = self._build_revision_prompt_with_resume(
+                    review_json=review_json,
+                    current_content=current_output,
+                    figures=figures
+                )
+            rev_resp = self.planner_agent.step(revision_prompt)
+            rin2, rout2 = account_token(rev_resp)
+
+            revised_output = get_json_from_response(rev_resp.msgs[0].content)
+
+            out_path = f'project_contents/{self.args.paper_name}_generated_full_content.v{it+1}.json'
+            with open(out_path, 'w', encoding='utf-8') as f:
+                json.dump(revised_output, f, ensure_ascii=False, indent=2)
+            print(f"  - Revised generation saved: {out_path}")
+
+            total_in_tok += rin2
+            total_out_tok += rout2
+            current_output = revised_output
+        if self.args.human_input == '1':
+            print('-'*50)
+            print(Pretty(current_output, expand_all=True))
+            print('-'*50)
+            user_feedback = input('The above is the final generated full content! If you are satisfied with the generated content, enter yes\n If not, enter your feedback.\n')
+            while user_feedback.lower() != 'yes':
+                message = BaseMessage.make_assistant_message(
+                    role_name='User',
+                    content='human feedback'+user_feedback +"The above is human feedback. Please make modifications based on this feedback and the original content.The output format is as specified above."
+                )
+                response = self.planner_agent.step(message)
+                current_output = get_json_from_response(response.msgs[0].content)
+                print('-'*50)
+                print(Pretty(current_output, expand_all=True))
+                print('-'*50)
+                user_feedback = input('The above is the final generated full content! If you are satisfied with the generated content, enter yes. \n If not, enter your feedback.\n')
+                in_tok, out_tok = account_token(response)
+                total_in_tok += in_tok
+                total_out_tok += out_tok
+            
+        # 4) 最终保存（保持你原有的命名）
+        final_path = f'project_contents/{self.args.paper_name}_generated_full_content.json'
+        with open(final_path, 'w', encoding='utf-8') as f:
+            json.dump(current_output, f, ensure_ascii=False, indent=2)
+        print(f"full content generation completed. Tokens: {total_in_tok} -> {total_out_tok}")
+        print(f"  - Final content: {final_path}")
+
+        return current_output, total_in_tok, total_out_tok
+
+    def section_generation(self, paper_content, figures):
+        """
+        Plan the content structure for the project page.
+        
+        Args:
+            paper_content: Parsed paper content
+            
+        Returns:
+            dict: project page content
+        """
+        
+        # Load planning prompt template
+        
+        with open('utils/prompt_templates/page_templates/section_generation.yaml', 'r') as f:
+            planner_config = yaml.safe_load(f)
+        
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(planner_config["template"])
+
+        json_format_example = """
+```json
+{{
+    "Introduction": "Brief overview of the paper's main topic and objectives.",
+    "Methodology": "Description of the methods used in the research.",
+    "Results": "Summary of the key findings and results."
+}}
+```
+"""
+        
+        # Prepare template arguments
+        jinja_args = {
+            'paper_content': paper_content,
+            'json_format_example': json.dumps(paper_content, indent=2)
+        }
+        
+        prompt = template.render(**jinja_args)
+        
+        # Generate content plan
+        self.planner_agent.reset()
+        response = self.planner_agent.step(prompt)
+        input_token, output_token = account_token(response)
+        generated_section = get_json_from_response(response.msgs[0].content)
+        
+        if self.args.human_input == '1':
+            print('-'*50)
+            print(Pretty(generated_section, expand_all=True))
+            print('-'*50)
+            user_feedback = input('The above is the generated section! If you are satisfied with the generated section, enter yes. \nIf not, enter your feedback.\n')
+            while user_feedback.lower() != 'yes':
+                message = BaseMessage.make_assistant_message(
+                    role_name='User',
+                    content='human feedback'+user_feedback +"The above is human feedback. Please make modifications based on this feedback and the original content.The output format is as specified above."
+                )
+                response = self.planner_agent.step(message)
+                generated_section = get_json_from_response(response.msgs[0].content)
+                print('-'*50)
+                print(Pretty(generated_section, expand_all=True))
+                print('-'*50)
+                user_feedback = input('The above is the generated section! If you are satisfied with the generated section, enter yes. \nIf not, enter your feedback.\n')
+                in_tok, out_tok = account_token(response)
+                input_token += in_tok
+                output_token += out_tok
+
+        print(f"section planning completed. Tokens: {input_token} -> {output_token}")
+
+        def create_dynamic_page_dict(sections: dict[str, str]) -> dict[str, str]:
+            poster_dict = {
+                "title": "Title of the paper",
+                "authors": "Authors of the paper, Each author must be accompanied by the superscript number(s) of their corresponding affiliation(s).",
+                "affiliation": "Affiliation of the authors, each affiliation must be accompanied by the corresponding superscript number.",
+            }
+
+            poster_dict.update(sections)
+            return poster_dict
+
+        generated_section = create_dynamic_page_dict(generated_section)
+
+        # Save generated content
+        # print(self.agent_config)
+        generated_path = f'project_contents/{self.args.paper_name}_generated_section.json'
+        with open(generated_path, 'w') as f:
+            json.dump(generated_section, f, indent=4)
+        
+        print(f"  - Generated section plan: {generated_path}")
+        
+        return generated_section, input_token, output_token
+
+    def text_content_generation(self, paper_content, figures, generated_section):
+        """
+        Plan the content structure for the project page.
+        
+        Args:
+            paper_content: Parsed paper content
+            
+        Returns:
+            dict: project page content
+        """
+
+        # Delete tags in figures
+        figures_ = {}
+        figures_['images'] = [{k: v for k, v in value.items() if k != 'tag'} for value in figures['images'].values()]
+        figures_['tables'] = [{k: v for k, v in value.items() if k != 'tag'} for value in figures['tables'].values()]
+
+        # Load planning prompt template
+        with open('utils/prompt_templates/page_templates/text_content_generation.yaml', 'r') as f:
+            planner_config = yaml.safe_load(f)
+        
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(planner_config["template"])
+        
+        # Prepare template arguments
+        jinja_args = {
+            'paper_content': paper_content,
+            'figures': json.dumps(figures_, indent=2),
+            'format_instructions': json.dumps(generated_section, indent=2)
+        }
+        
+        prompt = template.render(**jinja_args)
+        
+        # Generate content plan
+        self.planner_agent.reset()
+        response = self.planner_agent.step(prompt)
+        input_token, output_token = account_token(response)
+        
+        generated_text_content = get_json_from_response(response.msgs[0].content)
+        
+        print(f"text content generation completed. Tokens: {input_token} -> {output_token}")
+
+        # Save generated content
+        generated_path = f'project_contents/{self.args.paper_name}_generated_text_content.json'
+        with open(generated_path, 'w') as f:
+            json.dump(generated_text_content, f, indent=4)
+        
+        print(f"  - Generated text content: {generated_path}")
+        
+        return generated_text_content, input_token, output_token
+
+    def filter_raw_content(self, paper_content, figures):
+        paper_content = filter_references(paper_content)
+        # Load planning prompt template
+        with open('utils/prompt_templates/page_templates/filter_figures.yaml', 'r') as f:
+            planner_config = yaml.safe_load(f)
+        
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(planner_config["template"])
+        
+        # Prepare template arguments
+        jinja_args = {
+            'paper_content': paper_content,
+            'figures': json.dumps(figures, indent=2),
+        }
+        
+        prompt = template.render(**jinja_args)
+        
+        # Generate filtered figures
+        self.planner_agent.reset()
+        response = self.planner_agent.step(prompt)
+        input_token, output_token = account_token(response)
+        filtered_figures = get_json_from_response(response.msgs[0].content)
+        #print(filtered_figures)
+
+        def remove_items_without_section(data: dict) -> dict:
+            
+            for key in ["images", "tables"]:
+                if key in data and isinstance(data[key], dict):
+                    data[key] = {
+                        k: v for k, v in data[key].items()
+                        if v.get("original_section") is not None
+                    }
+            return data
+
+        filtered_figures = remove_items_without_section(filtered_figures)
+        
+        print(f"filtered figures generation completed. Tokens: {input_token} -> {output_token}")
+
+        # Save generated filtered figures
+        generated_path = f'project_contents/{self.args.paper_name}_generated_filtered_figures.json'
+        with open(generated_path, 'w') as f:
+            json.dump(filtered_figures, f, indent=4)
+        
+        print(f"  - Generated filtered figures: {generated_path}")
+        
+        return paper_content, filtered_figures, input_token, output_token
+
+
+        

ProjectPageAgent/css_checker.py

@@ -0,0 +1,111 @@
+import re
+from collections import OrderedDict
+from ProjectPageAgent.html_finder import HtmlFinder
+import os
+
+
+
+_LINK_CSS_RE = re.compile(
+    r'''(?isx)
+    <link[^>]*?                 
+    href\s*=\s*                 
+    (?:
+        "([^"]+?\.css(?:\?[^"]*)?)" |
+        '([^']+?\.css(?:\?[^']*)?)' |
+        ([^\s"'=<>`]+?\.css(?:\?[^\s"'=<>`]*)?)
+    )
+    [^>]*?>
+    '''
+)
+
+
+_IMPORT_CSS_RE = re.compile(
+    r'''(?isx)
+    @import
+    \s+(?:url\()?
+    \s*
+    (?:
+        "([^"]+?\.css(?:\?[^"]*)?)" |
+        '([^']+?\.css(?:\?[^']*)?)' |
+        ([^'")\s;]+?\.css(?:\?[^'")\s;]+)?)
+    )        
+    \s*
+    \)?
+    '''
+)
+
+
+def _first_nonempty(groups_list):
+    out = []
+    for groups in groups_list:
+        for g in groups:
+            if g:
+                out.append(g)
+                break
+    return out
+
+def extract_css_paths(html: str):
+
+    links = _first_nonempty(_LINK_CSS_RE.findall(html))
+    imports = _first_nonempty(_IMPORT_CSS_RE.findall(html))
+    seen = OrderedDict()
+    for u in links + imports:
+        u = u.strip()
+        if u and u not in seen:
+            seen[u] = True
+    return list(seen.keys())
+
+def check_css(generated_html: str, template_html: str):
+    generated_css = extract_css_paths(generated_html)
+    template_css = extract_css_paths(template_html)
+    print(f'num of css in generated page: {len(generated_css)}')
+    print(f'num of css in template page: {len(template_css)}')
+    template_css_name = {css.strip().split('/')[-1]: css for css in template_css}
+    
+    errors = {}
+    for css in generated_css:
+        if css.startswith('http'):
+            continue
+        if css not in template_css:
+            match = template_css_name.get(css.strip().split('/')[-1], None)
+            if match is not None:
+                errors[css] = match
+            else:
+                print(f"[⚠️ Warning] Missing CSS match for {css}")
+    
+    new_html = generated_html
+    for css, new_css in errors.items():
+        if new_css:
+            new_html = new_html.replace(css, new_css)
+    
+    return new_html
+
+
+
+
+
+if __name__ == "__main__":
+
+    templates_root = '/home/jimu/Project_resources/project_page/page_assets/'
+    html_finder = HtmlFinder(specific_name='index.html')
+
+    count = 0
+    for page in os.listdir('generated_FastVGGT'):
+        print(page)
+        count += 1
+        with open(html_finder.find_html(os.path.join('generated_FastVGGT', page)), 'r') as f:
+            generated_html = f.read()
+
+        with open(html_finder.find_html(os.path.join(templates_root, page)), 'r') as f:
+            template_html = f.read()
+
+
+        _ = check_css(generated_html, template_html, page)
+    print(count)
+
+
+
+
+
+
+

ProjectPageAgent/html_finder.py

@@ -0,0 +1,32 @@
+import os
+
+
+class HtmlFinder(object):
+    def __init__(self, specific_name=None):
+        self.queue = []
+        self.specific_name = specific_name
+
+    def find_html(self, path):
+        try:
+            if not os.path.isdir(path):
+                return
+            if self.queue:
+                del self.queue[0]
+            for dir in os.listdir(path):
+                dir_path = os.path.join(path, dir)
+                if os.path.isdir(dir_path):
+                    self.queue.append(dir_path)
+                elif self.specific_name is not None and dir_path.endswith(self.specific_name):
+                    return dir_path
+                elif dir_path.endswith(".html"):
+                    html_path = dir_path
+                    return html_path
+                else: continue
+            html_path = self.find_html(self.queue[0])
+            if html_path is not None:
+                return html_path
+        except Exception as e:
+            print(f"Error appears when finding {path}, error: {str(e)}")
+
+    def reset_queue(self):
+        self.queue = []

ProjectPageAgent/html_generator.py

@@ -0,0 +1,633 @@
+"""
+HTML generator for project page generation.
+Generates the final HTML project page from planned content.
+"""
+
+import json
+import yaml
+import os
+import io
+import re
+import json
+import yaml
+from pathlib import Path
+from urllib.parse import urlparse
+from datetime import datetime
+from jinja2 import Environment, StrictUndefined
+from camel.models import ModelFactory
+from camel.agents import ChatAgent
+from utils.wei_utils import get_agent_config, account_token
+from utils.src.utils import get_json_from_response, extract_html_code_block
+from ProjectPageAgent.css_checker import check_css 
+from utils.src.utils import run_sync_screenshots
+from PIL import Image
+from camel.messages import BaseMessage
+
+
+from camel.models import ModelFactory
+
+def to_url(input_path_or_url: str) -> str:
+    parsed = urlparse(input_path_or_url)
+    if parsed.scheme in ("http", "https", "file"):
+        return input_path_or_url
+    p = Path(input_path_or_url).expanduser().resolve()
+    if not p.exists():
+        raise FileNotFoundError(f"Input not found: {p}")
+    return p.as_uri()  # file://...
+
+
+def crop_image_to_max_size(image_path, max_bytes=8*1024*1024, output_path=None):
+    img = Image.open(image_path)
+    img_format = img.format
+    if output_path is None:
+        output_path = image_path
+
+    buffer = io.BytesIO()
+    img.save(buffer, format=img_format)
+    size = buffer.getbuffer().nbytes
+
+    if size <= max_bytes:
+        img.save(output_path, format=img_format)
+        return output_path
+
+    width, height = img.size
+    scale = max_bytes / size
+    new_height = max(int(height * scale), 1)  
+    img_cropped = img.crop((0, 0, width, new_height))  
+    img_cropped.save(output_path, format=img_format)
+
+    return output_path
+class ProjectPageHTMLGenerator:
+    """Generates HTML project pages from planned content."""
+    
+    def __init__(self, agent_config,args):
+        self.agent_config = agent_config
+        self.args = args
+        self.html_agent = self._create_html_agent()
+        self.review_agent = self._create_review_agent()
+        self.table_agent = self._create_table_agent()
+        self.long_agent = self._create_long_agent()
+        
+        # self.client = OpenAI(api_key=api_key,base_url=api_url)
+        
+    def _create_html_agent(self):
+        """Create the HTML generation agent."""
+        model_type = str(self.agent_config['model_type'])
+        
+        # Get API key from environment variables
+        api_key = None
+        if self.args.model_name_t in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+            api_key = os.environ.get('OPENAI_API_KEY')
+        elif self.args.model_name_t in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+            api_key = os.environ.get('GEMINI_API_KEY')
+        elif self.args.model_name_t in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+            api_key = os.environ.get('QWEN_API_KEY')
+        elif self.args.model_name_t.startswith('openrouter_'):
+            api_key = os.environ.get('OPENROUTER_API_KEY')
+        elif self.args.model_name_t in ['zhipuai']:
+            api_key = os.environ.get('ZHIPUAI_API_KEY')
+        
+        if model_type.startswith('vllm_qwen') or 'vllm' in model_type.lower():
+            model = ModelFactory.create(
+                model_platform=self.agent_config['model_platform'],
+                model_type=self.agent_config['model_type'],
+                model_config_dict=self.agent_config['model_config'],
+                url=self.agent_config.get('url', None),
+                api_key=api_key,
+            )
+        else:
+            model = ModelFactory.create(
+                model_platform=self.agent_config['model_platform'],
+                model_type=self.agent_config['model_type'],
+                model_config_dict=self.agent_config['model_config'],
+                api_key=api_key,
+            )
+        
+        system_message = """You are an expert web developer specializing in creating professional project pages for research papers. 
+        You have extensive experience in HTML5, CSS3, responsive design, and academic content presentation. 
+        Your goal is to create engaging, well-structured, and visually appealing project pages."""
+        
+        return ChatAgent(
+            system_message=system_message,
+            model=model,
+            message_window_size=10
+        )
+    def _create_review_agent(self):
+        with open('utils/prompt_templates/page_templates/html_review.yaml', 'r') as f:
+            prompt_config = yaml.safe_load(f)
+
+        jinja_env = Environment(undefined=StrictUndefined)
+        system_message_template = jinja_env.from_string(prompt_config["system_prompt"])
+
+        system_message = system_message_template.render()
+
+        model_type = self.args.model_name_v
+        
+        # Get API key from environment variables
+        api_key = None
+        if self.args.model_name_v in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+            api_key = os.environ.get('OPENAI_API_KEY')
+        elif self.args.model_name_v in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+            api_key = os.environ.get('GEMINI_API_KEY')
+        elif self.args.model_name_v in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+            api_key = os.environ.get('QWEN_API_KEY')
+        elif self.args.model_name_v.startswith('openrouter_'):
+            api_key = os.environ.get('OPENROUTER_API_KEY')
+        elif self.args.model_name_v in ['zhipuai']:
+            api_key = os.environ.get('ZHIPUAI_API_KEY')
+        
+        config = get_agent_config(model_type)
+        model = ModelFactory.create(
+            model_platform=config['model_platform'],
+            model_type=config['model_type'],
+            model_config_dict=config['model_config'],
+            url=config.get('url', None),
+            api_key=api_key,
+        )
+
+        return ChatAgent(
+            system_message=system_message, 
+            model=model,
+            message_window_size=10
+        )
+
+
+    def _create_table_agent(self):
+        
+        model_type = self.args.model_name_v
+        
+        # Get API key from environment variables
+        api_key = None
+        if self.args.model_name_v in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+            api_key = os.environ.get('OPENAI_API_KEY')
+        elif self.args.model_name_v in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+            api_key = os.environ.get('GEMINI_API_KEY')
+        elif self.args.model_name_v in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+            api_key = os.environ.get('QWEN_API_KEY')
+        elif self.args.model_name_v.startswith('openrouter_'):
+            api_key = os.environ.get('OPENROUTER_API_KEY')
+        elif self.args.model_name_v in ['zhipuai']:
+            api_key = os.environ.get('ZHIPUAI_API_KEY')
+      
+        vlm_config = get_agent_config(model_type)
+        vlm_model = ModelFactory.create(
+            model_platform=vlm_config['model_platform'],
+            model_type=vlm_config['model_type'],
+            model_config_dict=vlm_config['model_config'],
+            url=vlm_config.get('url', None),
+            api_key=api_key,
+        )
+        return ChatAgent(
+            system_message=None,
+            model=vlm_model,
+            message_window_size=10,
+        )
+    def _create_long_agent(self):
+        model_type = self.args.model_name_t
+        
+        # Get API key from environment variables
+        api_key = None
+        if self.args.model_name_t in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+            api_key = os.environ.get('OPENAI_API_KEY')
+        elif self.args.model_name_t in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+            api_key = os.environ.get('GEMINI_API_KEY')
+        elif self.args.model_name_t in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+            api_key = os.environ.get('QWEN_API_KEY')
+        elif self.args.model_name_t.startswith('openrouter_'):
+            api_key = os.environ.get('OPENROUTER_API_KEY')
+        elif self.args.model_name_t in ['zhipuai']:
+            api_key = os.environ.get('ZHIPUAI_API_KEY')
+        
+        long_config = get_agent_config(model_type)
+        long_model = ModelFactory.create(
+            model_platform=long_config['model_platform'],
+            model_type=long_config['model_type'],
+            model_config_dict=long_config['model_config'],
+            url=long_config.get('url', None),
+            api_key=api_key,
+        )
+       
+        return ChatAgent(
+            system_message=None,
+            model=long_model,
+            message_window_size=10,
+            token_limit=long_config.get('token_limit', None)
+        )
+    def render_html_to_png(self, iter, html_content, project_output_dir) -> str:
+
+        import time
+        tmp_html = Path(project_output_dir) / f"index_iter{iter}.html"
+        tmp_html.write_text(html_content, encoding="utf-8")
+        url = tmp_html.resolve().as_uri()
+
+        image_path = str(Path(project_output_dir) / f"page_iter{iter}.png")
+
+        run_sync_screenshots(url, image_path)
+        return image_path
+
+    def get_revision_suggestions(self, image_path: str, html_path) -> str:
+        
+        def crop_image_max_width(img, max_width=1280):
+            width, height = img.size
+            if width > max_width:
+                img = img.crop((0, 0, max_width, height))  # (left, top, right, bottom)
+            return img
+        img = Image.open(image_path)
+        img = crop_image_max_width(img, max_width=1280)
+        img.save(image_path,format='PNG')
+        crop_image_to_max_size(image_path=image_path,output_path=image_path)
+        img =Image.open(image_path)
+        
+        message = BaseMessage.make_user_message(
+                role_name="User",
+                content = '\nHere is the image of the generated project page.',
+                image_list=[img]
+        )
+        response = self.review_agent.step(message)
+
+        return get_json_from_response(response.msgs[0].content.strip())
+    
+
+    def modify_html_table(self, html_content: str,html_dir: str):
+
+        
+        in_tokens, out_tokens = 0, 0
+        print("Starting table modification...")
+        def replace_tables_in_html(html_content, table_html_map, paper_name):
+  
+            pattern = rf'<img[^>]*src="(assets/{paper_name}-table-\d+\.png)"[^>]*>'
+            
+            def repl(match):
+                img_path = match.group(1)  # e.g. assets/MambaFusion-table-10.png
+                if img_path in table_html_map:
+                    return table_html_map[img_path]
+                return match.group(0)  
+            
+            return re.sub(pattern, repl, html_content)
+
+        # ============ step 1 extract table ============
+        
+        pattern = rf"assets/{self.args.paper_name}-table-\d+\.png"
+        with open(os.path.join(self.args.output_dir,self.args.paper_name, html_dir,'index_no_modify_table.html'), 'r', encoding='utf-8') as f:
+            html_content = f.read()
+        matches = re.findall(pattern, html_content)
+
+        if matches is None:
+            print("No table images found, skipping modification.")
+            return None, 0, 0
+        
+     
+        model_type = self.args.model_name_v
+        print(f"Starting table modification phase 1: Table Extraction with {model_type}...")
+        
+        with open('utils/prompt_templates/page_templates/extract_table.yaml', 'r') as f:
+            table_extraction_config = yaml.safe_load(f)
+        content = table_extraction_config["system_prompt"]
+
+        init_message = BaseMessage.make_user_message(
+            role_name="User",
+            content=content
+        )
+        response = self.table_agent.step(init_message)
+        in_tok , out_tok = account_token(response)
+        in_tokens += in_tok
+        out_tokens += out_tok
+        # Step 2
+        table_html_map = {}
+
+        matches = list(set(matches))
+        for match in matches:
+            img_path =os.path.join(self.args.output_dir,self.args.paper_name, html_dir,match)
+            print(f"Processing table image: {img_path}")
+            img = Image.open(img_path)
+            msg = BaseMessage.make_user_message(
+                role_name="User",
+                content=f'''Here is table image: {match}
+            Please output its HTML table (<table>...</table>) with an inline <style>...</style> block.
+            Only return pure HTML , nothing else.
+            ''',
+                image_list=[img]
+            )
+            response = self.table_agent.step(msg)
+            in_tok , out_tok = account_token(response)
+            in_tokens += in_tok
+            out_tokens += out_tok
+            print(f'in:{in_tok},out:{out_tok}')
+            _output_html = response.msgs[0].content.strip()
+            table_html_map[match] = _output_html
+            tabel_dir = os.path.join(self.args.output_dir,self.args.paper_name, html_dir)
+            os.makedirs(f'{tabel_dir}/table_html', exist_ok=True)
+            
+            with open(f'{tabel_dir}/table_html/{match.replace("/", "_")}.html', 'w', encoding='utf-8') as f:
+                f.write(table_html_map[match])
+
+        # ============ 阶段 2：HTML Merge ============
+   
+        self.table_agent.reset()
+        img_path =os.path.join(self.args.output_dir,self.args.paper_name, html_dir,'page_final_no_modify_table.png')
+        img = Image.open(img_path)
+        with open('utils/prompt_templates/page_templates/color_suggestion.yaml','r') as f:
+            prompt_config = yaml.safe_load(f)
+
+        jinja_env = Environment(undefined=StrictUndefined)
+        init_prompt_template = jinja_env.from_string(prompt_config["system_prompt"])
+
+        init_prompt = init_prompt_template.render()
+
+        msg = BaseMessage.make_user_message(
+            role_name="User",
+            content=init_prompt, 
+            image_list=[img]
+        )
+
+        color_response = self.table_agent.step(msg)
+        color_suggestion = color_response.msgs[0].content.strip()
+        in_tok , out_tok = account_token(color_response)
+        in_tokens += in_tok
+        out_tokens += out_tok
+
+      
+        print(f"Starting table modification phase 2: HTML Merging with {model_type}...")
+        
+
+        tables_str = "\n\n".join(
+            [f"Table extracted for {fname}:\n{html}" for fname, html in table_html_map.items()]
+        )
+        with open("utils/prompt_templates/page_templates/merge_html_table.yaml",'r') as f:
+            prompt_config = yaml.safe_load(f)
+        
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(prompt_config["template"])
+
+        jinja_args = {
+            'html_content': html_content,
+            'color_suggestion': color_suggestion,
+            'tables_str': tables_str
+        }
+
+        prompt = template.render(**jinja_args)
+
+        final_message = BaseMessage.make_user_message(
+            role_name = "User",
+            content = prompt
+        )
+
+        for i in range(3):
+            self.long_agent.reset()
+            response = self.long_agent.step(final_message)
+            in_tok, out_tok = account_token(response)
+            in_tokens += in_tok
+            out_tokens += out_tok
+            output_html = response.msgs[0].content.strip()
+            print(f'in:{in_tok},out:{out_tok}')
+            exteact_html_code = extract_html_code_block(output_html)
+            if exteact_html_code is not None:
+                break
+            print(f"html format is not correct, regenerate {i} turn")
+        
+        return exteact_html_code, in_tokens, out_tokens
+
+
+    def modify_html_from_human_feedback(self, html_content: str, user_feedback: str):
+        """
+        Modify HTML based on human feedback using the HTML agent.
+        
+        Args:
+            html_content: Original HTML content
+            user_feedback: Feedback from human reviewers
+            
+        Returns:
+            str: Modified HTML content
+        """
+        in_tokens, out_tokens = 0, 0
+        print("Starting HTML modification based on human feedback...")
+        with open('utils/prompt_templates/page_templates/modify_html_from_human_feedback.yaml', 'r') as f:
+            modifier_config = yaml.safe_load(f)
+
+        jinja_env = Environment(undefined=StrictUndefined)
+        template = jinja_env.from_string(modifier_config["template"])
+
+        jinja_args = {
+            'generated_html': html_content,
+            'user_feedback': user_feedback
+        }
+
+        prompt = template.render(**jinja_args)
+        for i in range(3):
+            self.html_agent.reset()
+            response = self.html_agent.step(prompt)
+            in_tok, out_tok = account_token(response)
+            in_tokens += in_tok
+            out_tokens += out_tok
+            print(f'input_token: {in_tok}, output_token: {out_tok}')
+            modified_html = extract_html_code_block(response.msgs[0].content)
+
+            if modified_html is not None:
+                break
+            print(f"html format is not correct, regenerate {i} turn")
+        
+        return modified_html, in_tokens, out_tokens
+    
+
+    def generate_complete_html(self, args, generated_content, html_dir, html_template=None):
+        """
+        Generate complete HTML by combining all sections, then render to PNG,
+        send to OpenAI API for feedback, and regenerate HTML with suggestions.
+        """
+        
+        # Create output directory for this specific project
+        project_output_dir = f"{args.output_dir}/{args.paper_name}"
+        html_path = os.path.join(project_output_dir, html_dir)
+        if args.resume != 'html_check':
+            with open('utils/prompt_templates/page_templates/html_generation.yaml', 'r') as f:
+                generator_config = yaml.safe_load(f)
+
+            jinja_env = Environment(undefined=StrictUndefined)
+            template = jinja_env.from_string(generator_config["template"])
+
+            jinja_args = {
+                'generated_content': json.dumps(generated_content, indent=2),
+                'html_template': html_template,
+            }
+
+            prompt = template.render(**jinja_args)
+            for i in range(3):
+                self.html_agent.reset()
+                # print(self.html_agent)
+                
+                response = self.html_agent.step(prompt)
+                # print(response.msgs[0].content)
+                input_token, output_token = account_token(response)
+                print(f'input_token: {input_token}, output_token: {output_token}')
+                #print(input_token, output_token)
+                html_content = extract_html_code_block(response.msgs[0].content)
+
+                if html_content is not None:
+                    break
+                print(f"html format is not correct, regenerate {i} turn")
+            
+
+            # check css paths
+            html_content = check_css(html_content, html_template)
+
+            with open(os.path.join(html_path, 'index_init.html'),'w') as f:
+                f.write(html_content)
+
+            print(f"Initial HTML generation completed. Tokens: {input_token} -> {output_token}")
+
+        else: 
+            with open(os.path.join(html_path, 'index_init.html'), 'r', encoding='utf-8') as f:
+                html_content = f.read()
+        
+        revised_html = html_content
+        
+        for i in range(self.args.html_check_times):
+            if i==0:
+                print("starting html check and revision...")
+   
+            image_path = self.render_html_to_png(i, revised_html, html_path)
+
+            suggestions = self.get_revision_suggestions(image_path,os.path.join(html_path,f'index_iter{i}.html'))
+            # print(f"Revision suggestions from {self.args.model_name_v}:\n", suggestions)
+            
+            review_path = f'project_contents/{args.paper_name}_html_review_iter{i}.json'
+            with open(review_path, 'w') as f:
+                json.dump(suggestions, f, indent=4)
+
+            self.html_agent.reset()
+            with open('utils/prompt_templates/page_templates/html_modify_from_suggestion.yaml', 'r') as f:
+                regenerator_config = yaml.safe_load(f)
+
+            jinja_env = Environment(undefined=StrictUndefined)
+            _template = jinja_env.from_string(regenerator_config["template"])
+
+            _jinja_args = {
+                'existing_html': revised_html,
+                'suggestions': suggestions
+            }
+
+            revision_prompt = _template.render(**_jinja_args)
+
+            # print(revision_prompt)
+            revised_response = self.html_agent.step(revision_prompt)
+            # print(revised_response.msgs[0].content)
+            revised_html = extract_html_code_block(revised_response.msgs[0].content)
+
+            print("Revised HTML generation completed.")
+            input_token, output_token = account_token(revised_response)
+            print(f'in:{input_token}, out:{output_token}')
+
+        return revised_html, input_token, output_token
+
+    
+    def save_html_file(self, html_content, args, html_dir, output_dir="generated_project_pages"):
+        """
+        Save the generated HTML to a file.
+        
+        Args:
+            html_content: Generated HTML content
+            args: Command line arguments
+            output_dir: Output directory for the HTML file
+            
+        Returns:html_check
+            str: Path to the saved HTML file
+        """
+        os.makedirs(output_dir, exist_ok=True)
+        
+        # Create output directory for this specific project
+        project_output_dir = f"{output_dir}/{args.paper_name}"
+        os.makedirs(project_output_dir, exist_ok=True)
+        
+        # Save HTML file
+        html_file_path = f"{project_output_dir}/{html_dir}/index.html"
+        with open(html_file_path, 'w', encoding='utf-8') as f:
+            f.write(html_content)
+        
+        print(f"HTML project page saved to: {html_file_path}")
+        
+        return html_file_path
+    
+    def create_assets_directory(self, args, html_dir, output_dir="generated_project_pages"):
+        """
+        Create assets directory and copy images/tables.
+        
+        Args:
+            args: Command line arguments
+            output_dir: Output directory
+            
+        Returns:
+            str: Path to the assets directory
+        """
+        project_output_dir = f"{output_dir}/{args.paper_name}"
+        assets_dir = os.path.join(project_output_dir, html_dir, "assets")
+        os.makedirs(assets_dir, exist_ok=True)
+        
+        # Copy images and tables from the extracted assets
+        source_assets_dir = f"generated_project_pages/images_and_tables/{args.paper_name}"
+        if os.path.exists(source_assets_dir):
+            import shutil
+            for file in os.listdir(source_assets_dir):
+                if file.endswith(('.png', '.jpg', '.jpeg', '.gif')):
+                    src_path = os.path.join(source_assets_dir, file)
+                    dst_path = os.path.join(assets_dir, file)
+                    shutil.copy2(src_path, dst_path)
+        
+        print(f"Assets directory created at: {assets_dir}")
+        return assets_dir
+    
+    def generate_metadata(self, generated_content, args):
+        """
+        Generate metadata for the project page.
+        
+        Args:
+            generated_content: Generated content
+            args: Command line arguments
+            
+        Returns:
+            dict: Metadata for the project page
+        """
+        metadata = {
+            'title': generated_content.get('meta', {}).get('poster_title', 'Research Project'),
+            'description': generated_content.get('meta', {}).get('abstract', '')[:160],
+            'authors': generated_content.get('meta', {}).get('authors', ''),
+            'affiliations': generated_content.get('meta', {}).get('affiliations', ''),
+            'keywords': [],
+            'generated_by': f"Paper2ProjectPage ({args.model_name_t}_{args.model_name_v})",
+            'generation_date': str(datetime.now())
+        }
+        
+        # Extract keywords from content
+        content_text = json.dumps(generated_content, ensure_ascii=False)
+        # Simple keyword extraction (can be improved)
+        words = content_text.lower().split()
+        word_freq = {}
+        for word in words:
+            if len(word) > 4 and word.isalpha():
+                word_freq[word] = word_freq.get(word, 0) + 1
+        
+        # Get top 10 most frequent words as keywords
+        sorted_words = sorted(word_freq.items(), key=lambda x: x[1], reverse=True)
+        metadata['keywords'] = [word for word, freq in sorted_words[:10]]
+        
+        return metadata
+    
+    def save_metadata(self, metadata, args, output_dir="generated_project_pages"):
+        """
+        Save metadata to a JSON file.
+        
+        Args:
+            metadata: Generated metadata
+            args: Command line arguments
+            output_dir: Output directory
+            
+        Returns:
+            str: Path to the saved metadata file
+        """
+        project_output_dir = f"{output_dir}/{args.paper_name}"
+        metadata_file_path = f"{project_output_dir}/metadata.json"
+        
+        with open(metadata_file_path, 'w', encoding='utf-8') as f:
+            json.dump(metadata, f, indent=4, ensure_ascii=False)
+        
+        print(f"Metadata saved to: {metadata_file_path}")
+        return metadata_file_path 

ProjectPageAgent/main_pipline.py

@@ -0,0 +1,379 @@
+"""
+Main pipeline for Paper2ProjectPage.
+Integrates all modules to generate project pages from research papers.
+"""
+
+import argparse
+import json
+import os
+import time
+from dotenv import load_dotenv
+from pathlib import Path
+import shutil
+from ProjectPageAgent.parse_paper import parse_paper_for_project_page, save_parsed_content
+from ProjectPageAgent.html_finder import HtmlFinder
+from ProjectPageAgent.content_planner import ProjectPageContentPlanner
+from ProjectPageAgent.html_generator import ProjectPageHTMLGenerator,to_url
+from utils.wei_utils import get_agent_config
+from ProjectPageAgent.content_planner import filter_references
+from utils.src.utils import run_sync_screenshots
+
+load_dotenv()
+
+def matching(requirement):
+    weight = {
+        "background_color": 1.0,
+        "has_hero_section": 0.75,
+        "Page density": 0.85,
+        "image_layout": 0.65,
+        "title_color": 0.6,
+        "has_navigation": 0.7
+    }
+    with open('tags.json', 'r') as f:
+        template_tags = json.load(f)
+
+    points = {}
+    for name, tag in template_tags.items():
+        for feature, value in tag.items():
+            if requirement[feature] == value:
+                if name not in points.keys():
+                    points[name] = weight[feature]
+                else:
+                    points[name] += weight[feature]
+    sorted_points = sorted(points.items(), key=lambda x: x[1], reverse=True)
+    return [template[0] for template in sorted_points[0:3]]
+
+def copy_static_files(template_file_path, template_root_dir, output_dir, paper_name):
+    
+    print(f"Detecting Static files: {template_file_path}")
+    os.makedirs(output_dir, exist_ok=True)
+        
+    # Create output directory for this specific project
+    project_output_dir = f"{output_dir}/{paper_name}"
+    os.makedirs(project_output_dir, exist_ok=True)
+    
+    # template_dir = os.path.dirname(template_file_path)
+    static_dir = os.path.join(project_output_dir, 'static')
+    os.makedirs(static_dir, exist_ok=True)
+    
+
+    html_relative_path = os.path.relpath(template_file_path, template_root_dir)
+
+    # template_static_dir = os.path.join(template_dir, 'static')
+    if os.path.exists(template_root_dir) and os.path.isdir(template_root_dir):
+        print(f"Found template dir: {template_root_dir}")
+        try:
+            shutil.copytree(template_root_dir, project_output_dir, dirs_exist_ok=True)
+            os.remove(os.path.join(project_output_dir, html_relative_path))
+            print(f"Copied template to: {project_output_dir}")
+        except Exception as e:
+            print(f"Failed to copy static files: {e}")
+
+    try:
+        with open(template_file_path, 'r', encoding='utf-8') as f:
+            html_content = f.read()
+    except Exception as e:
+        print(f"Failed to read template file: {e}")
+        return
+    
+    return static_dir
+
+def main():
+    """Main pipeline for generating project pages from research papers."""
+    parser = argparse.ArgumentParser(description='Paper2ProjectPage Generation Pipeline')
+    parser.add_argument('--paper_path', type=str, required=True, help='Path to the research paper PDF')
+    parser.add_argument('--model_name_t', type=str, default='4o', help='Text model name')
+    parser.add_argument('--model_name_v', type=str, default='4o', help='Vision model name')
+    parser.add_argument('--template_root', type=str, default="project_templates", help='Directory containing all templates')
+    parser.add_argument('--template_dir', type=str, help='Directory of chosen template')
+    parser.add_argument('--template_file', type=str, help='Path to a specific template file to use')
+    parser.add_argument('--output_dir', type=str, default='generated_project_pages', help='Output directory for generated pages')
+    parser.add_argument('--style_preference', type=str, default=None, help='Path to style preference JSON file')
+    parser.add_argument('--tmp_dir', type=str, default='tmp', help='Temporary directory')
+    parser.add_argument('--full_content_check_times', type=int, default='0', help='Temporary directory')
+    parser.add_argument('--background_color', type=str, choices=['light', 'dark'], required=True,
+                        help='Background color of generated project page')
+    parser.add_argument('--has_navigation', type=str, choices=['yes', 'no'], required=True,
+                        help='Is the generated project page has navigation')
+    parser.add_argument('--has_hero_section', type=str, choices=['yes', 'no'], required=True,
+                        help='Is the generated project page has hero section')
+    parser.add_argument('--title_color', type=str, choices=['pure', 'colorful'], required=True,
+                        help="Is the title's color of the project page is pure or colorful")
+    parser.add_argument('--page_density', type=str, choices=['spacious', 'compact'], required=True,
+                        help="The overall spacing tightness—amount of white space vs. information density")
+    parser.add_argument('--image_layout', type=str, choices=['rotation', 'parallelism'], required=True,
+                        help="The dominant arrangement style for images.")
+    parser.add_argument('--html_check_times', type=int, default='1', help='Temporary directory')
+    parser.add_argument(
+        '--resume',
+        type=str,
+        choices=['parse_pdf', 'generate_content','full_content_check', 'generate_html', 'html_check','modify_table','html_feedback'],
+        default='parse_pdf',
+        help="From which step to resume: 'parse_pdf', 'generate_content','full_content_check', 'generate_html', 'html_check','modify_table','html_feedback'",
+    )
+    parser.add_argument('--human_input', type=str, default='1',choices=['0','1'] ,help='Human input for feedback')
+    
+    args = parser.parse_args()
+
+    if not args.template_dir:
+        template_requirement = {
+            "background_color": args.background_color,
+            "has_hero_section": args.has_hero_section,
+            "Page density": args.page_density,
+            "image_layout": args.image_layout,
+            "has_navigation": args.has_navigation,
+            "title_color": args.title_color
+        }
+        matched_template = matching(template_requirement)
+        print('Below is names of the most matching 3 templates:')
+        print('           '.join(matched_template))
+        template_name = input('Please choose one from them, you can just input the name of your favorite template')
+        while template_name not in matched_template:
+            template_name = input('Please input the correct name of your favorite template!!')
+        args.template_dir = os.path.join(args.template_root, template_name)
+
+    # Extract html path from root path
+    if not args.template_file:
+        html_finder_ = HtmlFinder()
+        args.template_file = html_finder_.find_html(args.template_dir)
+
+    # Extract paper name from path
+    paper_name = args.paper_path.split('/')[-1].replace('.pdf', '') if '/' in args.paper_path else args.paper_path.replace('.pdf', '')
+    args.paper_name = paper_name
+    
+    print(f"Starting Paper2ProjectPage generation for: {paper_name}")
+    print(f"Paper path: {args.paper_path}")
+    print(f"Models: {args.model_name_t} (text), {args.model_name_v} (vision)")
+    
+    start_time = time.time()
+    total_input_tokens_t = 0
+    total_output_tokens_t = 0
+    total_input_tokens_v = 0
+    total_output_tokens_v = 0
+    
+    # Create temporary directory
+    os.makedirs(args.tmp_dir, exist_ok=True)
+    
+    try:
+        # Get agent configurations
+        agent_config_t = get_agent_config(args.model_name_t)
+        agent_config_v = get_agent_config(args.model_name_v)
+        
+        # Step 1: Parse the research paper
+        print("\n" + "="*50)
+        print("STEP 1: Parsing Research Paper")
+        print("="*50)
+
+        raw_content_path = f'project_contents/{args.paper_name}_raw_content.json'
+        if not os.path.exists(raw_content_path):
+            print(f"Raw content does not exist at {raw_content_path}")
+
+
+            input_token, output_token, raw_result, images, tables = parse_paper_for_project_page(args, agent_config_t)
+            total_input_tokens_t += input_token
+            total_output_tokens_t += output_token
+            
+            # Save parsed content
+            raw_content_path, token_log_path = save_parsed_content(args, raw_result, images, tables, input_token, output_token)
+            
+            # Load parsed content
+            with open(raw_content_path, 'r') as f:
+                paper_content = json.load(f)
+        else:
+            print(f"Loading existing raw content from {raw_content_path}")
+            with open(raw_content_path, 'r') as f:
+                paper_content = json.load(f)
+            # Load images and tables from the saved content
+            images = paper_content.get('images', [])
+            tables = paper_content.get('tables', [])
+            token_log_path = raw_content_path.replace('_raw_content.json', '_parse_log.json')
+
+        images = paper_content.get('images', [])
+        tables = paper_content.get('tables', [])
+        figures = {
+            'images': images,
+            'tables': tables
+        }
+        paper_content = paper_content.get('markdown_content', "")
+    
+        
+        print("\n" + "="*50)
+        print("STEP 2: Generate project page content")
+        print("="*50)
+
+        planner = ProjectPageContentPlanner(agent_config_t, args)
+        figures_path = f'project_contents/{args.paper_name}_generated_filtered_figures.json'
+        generated_section_path = f'project_contents/{args.paper_name}_generated_section.json'
+        text_page_content_path = f'project_contents/{args.paper_name}_generated_text_content.json'
+        generated_content_path = f'project_contents/{args.paper_name}_generated_full_content.json'
+        if args.resume in ['parse_pdf','generate_content','full_content_check']:
+
+            if args.resume != 'full_content_check':
+
+                paper_content, figures, input_token, output_token = planner.filter_raw_content(paper_content, figures)
+                total_input_tokens_t += input_token
+                total_output_tokens_t += output_token
+                
+                generated_section, input_token, output_token = planner.section_generation(paper_content, figures)
+                total_input_tokens_t += input_token
+                total_output_tokens_t += output_token
+
+                text_page_content, input_token, output_token = planner.text_content_generation(paper_content, figures, generated_section)
+                total_input_tokens_t += input_token
+                total_output_tokens_t += output_token
+
+            else :
+                print("Skipping content generation: filter_raw_content, section_generation, text_content_generation")
+                print("Loading existing content from previous steps.")
+                paper_content = filter_references(paper_content)
+                with open(figures_path, 'r') as f:
+                    figures = json.load(f)
+                with open(generated_section_path, 'r') as f:
+                    generated_section = json.load(f)        
+                with open(text_page_content_path, 'r') as f:
+                    text_page_content = json.load(f)
+
+            generated_content, input_token, output_token = planner.full_content_generation(args, paper_content, figures, generated_section, text_page_content)
+            total_input_tokens_t += input_token
+            total_output_tokens_t += output_token
+
+            print("\n" + "="*50)
+            print("STEP 2.5: Copying Static Files")
+            print("="*50)
+            static_dir = copy_static_files(args.template_file, args.template_dir, args.output_dir, args.paper_name)
+            
+        else:
+            print("Page content is already generated, loading existing content.")
+            
+            paper_content = filter_references(paper_content)
+            with open(generated_section_path, 'r') as f:
+                generated_section = json.load(f)        
+            with open(text_page_content_path, 'r') as f:
+                text_page_content = json.load(f)        
+            with open(generated_content_path, 'r') as f:
+                generated_content = json.load(f)
+
+            static_dir = copy_static_files(args.template_file, args.template_dir, args.output_dir, args.paper_name)
+            # static_dir = os.path.join(args.output_dir, args.paper_name, 'static')
+        # Step 3: Generate HTML project page
+        print("\n" + "="*50)
+        print("STEP 3: Generating HTML Project Page")
+        print("="*50)
+        html_relative_path = os.path.relpath(args.template_file, args.template_dir)
+        html_dir = '/'.join(html_relative_path.strip().split('/')[:-1])
+        html_generator = ProjectPageHTMLGenerator(agent_config_t,args)
+        with open(args.template_file, 'r', encoding='utf-8') as file:
+                html_template = file.read()
+        # Generate HTML
+        if args.resume != 'modify_table' and args.resume != 'html_feedback':
+            
+            # Create assets directory and copy images
+            assets_dir = html_generator.create_assets_directory(args, html_dir, args.output_dir)
+            # Generate complete HTML
+            html_content, input_token, output_token = html_generator.generate_complete_html(
+                args, generated_content, html_dir, html_template
+            )
+            total_input_tokens_t += input_token
+            total_output_tokens_t += output_token
+            
+            # Save HTML file
+            html_file_path = os.path.join(args.output_dir, args.paper_name, html_dir, 'index_no_modify_table.html')
+            with open(html_file_path,'w') as file:
+                file.write(html_content)
+            run_sync_screenshots(to_url(html_file_path), os.path.join(args.output_dir,args.paper_name, html_dir,'page_final_no_modify_table.png'))
+
+        else:
+            print(f"skip generate_html and html_check, load html from {os.path.join(args.output_dir,args.paper_name, html_dir,'index.html')}")
+            assets_dir = os.path.join(args.output_dir, args.paper_name, html_dir,'assets')
+            with open(os.path.join(args.output_dir,args.paper_name, html_dir,'index_no_modify_table.html'),'r') as file:
+                html_content = file.read()
+        
+        if args.resume != 'html_feedback':
+            html_content ,input_token,output_token = html_generator.modify_html_table(html_content,html_dir)
+            total_input_tokens_t += input_token
+            total_output_tokens_t += output_token
+            html_file_path = os.path.join(args.output_dir, args.paper_name, html_dir, 'index_modify_table.html')
+            with open(html_file_path,'w') as file:
+                file.write(html_content)
+            # html_file_path = html_generator.save_html_file(html_content, args, html_dir,args.output_dir)
+        else:
+            print("skipping modify_table,go to html_feedback")
+            html_file_path = os.path.join(args.output_dir, args.paper_name, html_dir, 'index_modify_table.html')
+            with open(html_file_path,'r') as file:
+                html_content = file.read()
+
+        print('-'*50)
+        run_sync_screenshots(to_url(html_file_path), os.path.join(args.output_dir, args.paper_name, html_dir,'page_final.png'))
+        if args.human_input == '1':
+            human_feedback = input('Please view the final html in index.html,and image in page_final.png,If there are no problems, enter yes and press Enter.\n  If there are any problems, please give me feedback directly.\n')
+            while human_feedback.lower() != 'yes':
+
+                html_content ,input_token,output_token = html_generator.modify_html_from_human_feedback(html_content,human_feedback)
+                total_input_tokens_t += input_token
+                total_output_tokens_t += output_token
+                with open(os.path.join(args.output_dir, args.paper_name, html_dir, 'index.html'),'w') as file:
+                    file.write(html_content)
+                run_sync_screenshots(to_url(os.path.join(args.output_dir, args.paper_name, html_dir, 'index.html')), os.path.join(args.output_dir, args.paper_name, html_dir,'page_final.png'))
+                print('-'*50)
+                human_feedback = input('Please view the final html in index.html,and image in page_final.png,If there are no problems, enter yes and press Enter. \n  If there are any problems, please give me feedback directly.\n')
+            
+        html_file_path = html_generator.save_html_file(html_content, args, html_dir,args.output_dir)
+
+        # Generate and save metadata
+        metadata = html_generator.generate_metadata(generated_content, args)
+        metadata_path = html_generator.save_metadata(metadata, args, args.output_dir)
+        
+        # Step 4: Finalize and save logs
+        print("\n" + "="*50)
+        print("STEP 4: Finalizing Generation")
+        print("="*50)
+        
+        end_time = time.time()
+        time_taken = end_time - start_time
+        
+        # Save generation log
+        log_data = {
+            'paper_name': paper_name,
+            'paper_path': args.paper_path,
+            'models': {
+                'text_model': args.model_name_t,
+                'vision_model': args.model_name_v
+            },
+            'token_usage': {
+                'text_input_tokens': total_input_tokens_t,
+                'text_output_tokens': total_output_tokens_t,
+                'vision_input_tokens': total_input_tokens_v,
+                'vision_output_tokens': total_output_tokens_v
+            },
+            'generation_time': time_taken,
+            'output_files': {
+                'html_file': html_file_path,
+                'assets_dir': assets_dir,
+                'static_dir': static_dir,
+                'metadata_file': metadata_path
+            },
+            'content_files': {
+                'raw_content': raw_content_path,
+                'token_log': token_log_path
+            }
+        }
+        
+        log_path = f"{args.output_dir}/{args.paper_name}/generation_log.json"
+        with open(log_path, 'w') as f:
+            json.dump(log_data, f, indent=4)
+        
+        print(f"\n✅ Paper2ProjectPage generation completed successfully!")
+        print(f"📁 Output directory: {args.output_dir}/{args.paper_name}")
+        print(f"🌐 HTML file: {html_file_path}")
+        print(f"📊 Assets directory: {assets_dir}")
+        print(f"🎨 Static directory: {static_dir}")
+        print(f"📋 Metadata file: {metadata_path}")
+        print(f"⏱️  Total time: {time_taken:.2f} seconds")
+        print(f"🔢 Token usage - Text: {total_input_tokens_t}→{total_output_tokens_t}, Vision: {total_input_tokens_v}→{total_output_tokens_v}")
+        
+    except Exception as e:
+        print(f"\n❌ Error during generation: {str(e)}")
+        raise
+
+if __name__ == '__main__':
+    main() 

ProjectPageAgent/parse_paper.py

@@ -0,0 +1,88 @@
+"""
+Paper parsing module for ProjectPageAgent.
+Reuses the parsing capabilities from Paper2Poster.
+"""
+
+from ProjectPageAgent.parse_raw import parse_raw, gen_image_and_table
+from utils.wei_utils import get_agent_config
+import json
+import os
+import argparse
+
+def parse_paper_for_project_page(args, agent_config_t, version=2):
+    """
+    Parse a research paper PDF and extract content for project page generation.
+    
+    Args:
+        args: Command line arguments
+        agent_config_t: Text model configuration
+        version: Parser version to use
+    
+    Returns:
+        tuple: (input_tokens, output_tokens, raw_result, images, tables)
+    """
+    print("Step 1: Parsing the research paper...")
+    
+    # Add poster_path and poster_name attributes to args for compatibility with parse_raw
+    if not hasattr(args, 'poster_path'):
+        args.poster_path = args.paper_path
+    
+    if not hasattr(args, 'poster_name'):
+        args.poster_name = args.paper_name
+    
+    # Parse the raw paper content
+    input_token, output_token, raw_result = parse_raw(args, agent_config_t, version=version)
+    
+    # Extract images and tables
+    _, _, images, tables = gen_image_and_table(args, raw_result)
+    
+    print(f"Parsing completed. Tokens: {input_token} -> {output_token}")
+    print(f"Extracted {len(images)} images and {len(tables)} tables")
+    
+    return input_token, output_token, raw_result, images, tables
+
+def save_parsed_content(args, raw_result, images, tables, input_token, output_token):
+    """
+    Save parsed content to files for later use.
+    
+    Args:
+        args: Command line arguments
+        raw_result: Parsed raw content
+        images: Extracted images
+        tables: Extracted tables
+        input_token: Input token count
+        output_token: Output token count
+    """
+    # Save raw content
+    os.makedirs('project_contents', exist_ok=True)
+    raw_content_path = f'project_contents/{args.paper_name}_raw_content.json'
+    
+    # Convert raw_result to JSON format if needed
+    if hasattr(raw_result, 'document'):
+        # Extract text content from docling result
+        raw_markdown = raw_result.document.export_to_markdown()
+        content_json = {
+            'markdown_content': raw_markdown,
+            'images': images,
+            'tables': tables
+        }
+    else:
+        content_json = raw_result
+    
+    with open(raw_content_path, 'w') as f:
+        json.dump(content_json, f, indent=4)
+    
+    # Save token usage
+    token_log = {
+        'parse_input_tokens': input_token,
+        'parse_output_tokens': output_token,
+        'total_images': len(images),
+        'total_tables': len(tables)
+    }
+    
+    token_log_path = f'project_contents/{args.paper_name}_parse_log.json'
+    with open(token_log_path, 'w') as f:
+        json.dump(token_log, f, indent=4)
+    
+    print(f"Parsed content saved to {raw_content_path}")
+    return raw_content_path, token_log_path 

ProjectPageAgent/parse_raw.py

@@ -0,0 +1,256 @@
+from dotenv import load_dotenv
+from utils.src.utils import get_json_from_response
+from utils.src.model_utils import parse_pdf
+import json
+import random
+import os
+
+from camel.models import ModelFactory
+from camel.agents import ChatAgent
+from tenacity import retry, stop_after_attempt
+from docling_core.types.doc import ImageRefMode, PictureItem, TableItem
+
+from docling.datamodel.base_models import InputFormat
+from docling.datamodel.pipeline_options import PdfPipelineOptions
+from docling.document_converter import DocumentConverter, PdfFormatOption
+
+from pathlib import Path
+
+import PIL
+
+from marker.models import create_model_dict
+
+from utils.wei_utils import *
+
+from utils.pptx_utils import *
+from utils.critic_utils import *
+import torch
+from jinja2 import Template
+import re
+import argparse
+
+load_dotenv()
+IMAGE_RESOLUTION_SCALE = 5.0
+
+pipeline_options = PdfPipelineOptions()
+pipeline_options.images_scale = IMAGE_RESOLUTION_SCALE
+pipeline_options.generate_page_images = True
+pipeline_options.generate_picture_images = True
+
+doc_converter = DocumentConverter(
+    format_options={
+        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
+    }
+)
+
+@retry(stop=stop_after_attempt(5))
+def parse_raw(args, actor_config, version=1):
+    raw_source = args.poster_path
+    markdown_clean_pattern = re.compile(r"<!--[\s\S]*?-->")
+
+    raw_result = doc_converter.convert(raw_source)
+
+    raw_markdown = raw_result.document.export_to_markdown()
+    text_content = markdown_clean_pattern.sub("", raw_markdown)
+
+    if len(text_content) < 500:
+        print('\nParsing with docling failed, using marker instead\n')
+        parser_model = create_model_dict(device='cuda', dtype=torch.float16)
+        text_content, rendered = parse_pdf(raw_source, model_lst=parser_model, save_file=False)
+
+    if version == 1:
+        template = Template(open("utils/prompts/gen_page_raw_content.txt").read())
+    elif version == 2:
+        template = Template(open("utils/prompts/gen_page_raw_content_v2.txt").read())
+
+    # Get API key from environment variables
+    api_key = None
+    if args.model_name_t in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+        api_key = os.environ.get('OPENAI_API_KEY')
+    elif args.model_name_t in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+        api_key = os.environ.get('GEMINI_API_KEY')
+    elif args.model_name_t in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+        api_key = os.environ.get('QWEN_API_KEY')
+    elif args.model_name_t.startswith('openrouter_'):
+        api_key = os.environ.get('OPENROUTER_API_KEY')
+    elif args.model_name_t in ['zhipuai']:
+        api_key = os.environ.get('ZHIPUAI_API_KEY')
+
+    if args.model_name_t.startswith('vllm_qwen'):
+        actor_model = ModelFactory.create(
+            model_platform=actor_config['model_platform'],
+            model_type=actor_config['model_type'],
+            model_config_dict=actor_config['model_config'],
+            url=actor_config['url'],
+            api_key=api_key,
+        )
+    else:
+        actor_model = ModelFactory.create(
+            model_platform=actor_config['model_platform'],
+            model_type=actor_config['model_type'],
+            model_config_dict=actor_config['model_config'],
+            api_key=api_key,
+        )
+
+    actor_sys_msg = 'You are the author of the paper, and you will create a poster for the paper.'
+
+    actor_agent = ChatAgent(
+        system_message=actor_sys_msg,
+        model=actor_model,
+        message_window_size=10,
+        token_limit=actor_config.get('token_limit', None)
+    )
+
+    while True:
+        prompt = template.render(
+            markdown_document=text_content, 
+        )
+        actor_agent.reset()
+        response = actor_agent.step(prompt)
+        input_token, output_token = account_token(response)
+
+        content_json = get_json_from_response(response.msgs[0].content)
+
+        if len(content_json) > 0:
+            break
+        print('Error: Empty response, retrying...')
+        if args.model_name_t.startswith('vllm_qwen'):
+            text_content = text_content[:80000]
+
+    if len(content_json['sections']) > 9:
+        # First 2 sections + randomly select 5 sections + last 2 sections
+        selected_sections = content_json['sections'][:2] + random.sample(content_json['sections'][2:-2], 5) + content_json['sections'][-2:]
+        content_json['sections'] = selected_sections
+
+    has_title = False
+
+    for section in content_json['sections']:
+        if type(section) != dict or not 'title' in section or not 'content' in section:
+            print(f"Ouch! The response is invalid, the LLM is not following the format :(")
+            print('Trying again...')
+            raise
+        if 'title' in section['title'].lower():
+            has_title = True
+
+    if not has_title:
+        print('Ouch! The response is invalid, the LLM is not following the format :(')
+        raise
+
+    os.makedirs('contents', exist_ok=True)
+    json.dump(content_json, open(f'contents/{args.poster_name}_raw_content.json', 'w'), indent=4)
+    return input_token, output_token, raw_result
+
+
+def gen_image_and_table(args, conv_res):
+    input_token, output_token = 0, 0
+    raw_source = args.poster_path
+
+    output_dir = Path(f'generated_project_pages/images_and_tables/{args.poster_name}')
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    doc_filename = args.poster_name
+
+    # Save page images
+    for page_no, page in conv_res.document.pages.items():
+        page_no = page.page_no
+        page_image_filename = output_dir / f"{doc_filename}-{page_no}.png"
+        with page_image_filename.open("wb") as fp:
+            page.image.pil_image.save(fp, format="PNG")
+
+    # Save images of figures and tables
+    table_counter = 0
+    picture_counter = 0
+    for element, _level in conv_res.document.iterate_items():
+        if isinstance(element, TableItem):
+            table_counter += 1
+            element_image_filename = (
+                output_dir / f"{doc_filename}-table-{table_counter}.png"
+            )
+            with element_image_filename.open("wb") as fp:
+                element.get_image(conv_res.document).save(fp, "PNG")
+
+        if isinstance(element, PictureItem):
+            picture_counter += 1
+            element_image_filename = (
+                output_dir / f"{doc_filename}-picture-{picture_counter}.png"
+            )
+            with element_image_filename.open("wb") as fp:
+                element.get_image(conv_res.document).save(fp, "PNG")
+
+    # Save markdown with embedded pictures
+    md_filename = output_dir / f"{doc_filename}-with-images.md"
+    conv_res.document.save_as_markdown(md_filename, image_mode=ImageRefMode.EMBEDDED)
+
+    # Save markdown with externally referenced pictures
+    md_filename = output_dir / f"{doc_filename}-with-image-refs.md"
+    conv_res.document.save_as_markdown(md_filename, image_mode=ImageRefMode.REFERENCED)
+
+    # Save HTML with externally referenced pictures
+    html_filename = output_dir / f"{doc_filename}-with-image-refs.html"
+    conv_res.document.save_as_html(html_filename, image_mode=ImageRefMode.REFERENCED)
+
+    tables = {}
+
+    table_index = 1
+    for table in conv_res.document.tables:
+        caption = table.caption_text(conv_res.document)
+        if len(caption) > 0:
+            table_img_path = f'generated_project_pages/images_and_tables/{args.poster_name}/{args.poster_name}-table-{table_index}.png'
+            assests_table_path = f'assets/{args.poster_name}-table-{table_index}.png'
+            table_img = PIL.Image.open(table_img_path)
+            tables[str(table_index)] = {
+                'caption': caption,
+                'table_path': assests_table_path,
+                # 'assests_table_path': assests_table_path,
+                'width': table_img.width,
+                'height': table_img.height,
+                'figure_size': table_img.width * table_img.height,
+                'figure_aspect': table_img.width / table_img.height,
+            }
+
+        table_index += 1
+
+    images = {}
+    image_index = 1
+    for image in conv_res.document.pictures:
+        caption = image.caption_text(conv_res.document)
+        if len(caption) > 0:
+            image_img_path = f'generated_project_pages/images_and_tables/{args.poster_name}/{args.poster_name}-picture-{image_index}.png'
+            assests_image_path = f'assets/{args.poster_name}-picture-{image_index}.png'
+            image_img = PIL.Image.open(image_img_path)
+            images[str(image_index)] = {
+                'caption': caption,
+                'image_path': assests_image_path,
+                # 'assests_image_path': assests_image_path,
+                'width': image_img.width,
+                'height': image_img.height,
+                'figure_size': image_img.width * image_img.height,
+                'figure_aspect': image_img.width / image_img.height,
+            }
+        image_index += 1
+
+    json.dump(images, open(f'generated_project_pages/images_and_tables/{args.poster_name}_images.json', 'w'), indent=4)
+    json.dump(tables, open(f'generated_project_pages/images_and_tables/{args.poster_name}_tables.json', 'w'), indent=4)
+
+    return input_token, output_token, images, tables
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--poster_name', type=str, default=None)
+    parser.add_argument('--model_name', type=str, default='4o')
+    parser.add_argument('--poster_path', type=str, required=True)
+    parser.add_argument('--index', type=int, default=0)
+    args = parser.parse_args()
+
+    agent_config = get_agent_config(args.model_name)
+
+    if args.poster_name is None:
+        args.poster_name = args.poster_path.split('/')[-1].replace('.pdf', '').replace(' ', '_')
+
+    # Parse raw content
+    input_token, output_token = parse_raw(args, agent_config)
+
+    # Generate images and tables
+    _, _ = gen_image_and_table(args)
+
+    print(f'Token consumption: {input_token} -> {output_token}')

ProjectPageAgent/template_analyzer.py

@@ -0,0 +1,436 @@
+"""
+Template analyzer for project page generation.
+Analyzes existing project page templates to understand structure and style.
+"""
+
+import os
+import json
+import re
+from bs4 import BeautifulSoup
+from pathlib import Path
+import yaml
+from jinja2 import Environment, StrictUndefined
+
+class ProjectPageTemplateAnalyzer:
+    """Analyzes project page templates to extract structure and styling patterns."""
+    
+    def __init__(self, template_dir="project_templates"):
+        self.template_dir = Path(template_dir)
+        self.template_dir.mkdir(exist_ok=True)
+        self.templates = {}
+        self.common_patterns = {}
+        
+    def analyze_html_template(self, html_file_path):
+        """
+        Analyze an HTML template file to extract structure and styling.
+        
+        Args:
+            html_file_path: Path to the HTML template file
+            
+        Returns:
+            dict: Analysis results including structure, styling, and patterns
+        """
+        try:
+            with open(html_file_path, 'r', encoding='utf-8') as f:
+                html_content = f.read()
+            
+            soup = BeautifulSoup(html_content, 'html.parser')
+            
+            analysis = {
+                'file_path': html_file_path,
+                'structure': self._extract_structure(soup),
+                'styling': self._extract_styling(soup),
+                'sections': self._extract_sections(soup),
+                'components': self._extract_components(soup),
+                'meta_info': self._extract_meta_info(soup)
+            }
+            
+            return analysis
+            
+        except Exception as e:
+            print(f"Error analyzing template {html_file_path}: {e}")
+            return None
+    
+    def _extract_structure(self, soup):
+        """Extract the overall structure of the HTML document."""
+        structure = {
+            'doctype': soup.find('!DOCTYPE') is not None,
+            'html_lang': soup.html.get('lang', 'en') if soup.html else 'en',
+            'head_sections': [],
+            'body_sections': [],
+            'main_content': None,
+            'navigation': None,
+            'footer': None
+        }
+        
+        # Extract head sections
+        if soup.head:
+            for tag in soup.head.find_all(['meta', 'link', 'script', 'title']):
+                structure['head_sections'].append({
+                    'tag': tag.name,
+                    'attrs': dict(tag.attrs)
+                })
+        
+        # Extract body structure
+        if soup.body:
+            for section in soup.body.find_all(['header', 'nav', 'main', 'section', 'article', 'aside', 'footer']):
+                structure['body_sections'].append({
+                    'tag': section.name,
+                    'id': section.get('id', ''),
+                    'class': section.get('class', []),
+                    'content_type': self._identify_content_type(section)
+                })
+        
+        return structure
+    
+    def _extract_styling(self, soup):
+        """Extract CSS styling information."""
+        styling = {
+            'inline_styles': [],
+            'external_css': [],
+            'color_scheme': [],
+            'typography': {},
+            'layout': {}
+        }
+        
+        # Extract inline styles
+        for tag in soup.find_all(style=True):
+            styling['inline_styles'].append({
+                'tag': tag.name,
+                'style': tag.get('style', '')
+            })
+        
+        # Extract external CSS links
+        for link in soup.find_all('link', rel='stylesheet'):
+            styling['external_css'].append(link.get('href', ''))
+        
+        # Extract color information
+        color_pattern = re.compile(r'#[0-9a-fA-F]{3,6}|rgb\([^)]+\)|rgba\([^)]+\)')
+        for tag in soup.find_all(style=True):
+            colors = color_pattern.findall(tag.get('style', ''))
+            styling['color_scheme'].extend(colors)
+        
+        # Extract typography patterns
+        for tag in soup.find_all(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p']):
+            font_size = re.search(r'font-size:\s*([^;]+)', tag.get('style', ''))
+            if font_size:
+                styling['typography'][tag.name] = font_size.group(1)
+        
+        return styling
+    
+    def _extract_sections(self, soup):
+        """Extract content sections and their organization."""
+        sections = []
+        
+        for section in soup.find_all(['section', 'article', 'div'], class_=True):
+            section_info = {
+                'tag': section.name,
+                'id': section.get('id', ''),
+                'classes': section.get('class', []),
+                'content': self._extract_section_content(section),
+                'images': self._extract_images(section),
+                'tables': self._extract_tables(section)
+            }
+            sections.append(section_info)
+        
+        return sections
+    
+    def _extract_components(self, soup):
+        """Extract reusable components and their patterns."""
+        components = {
+            'navigation': self._extract_navigation(soup),
+            'hero_section': self._extract_hero_section(soup),
+            'content_blocks': self._extract_content_blocks(soup),
+            'image_galleries': self._extract_image_galleries(soup),
+            'contact_forms': self._extract_contact_forms(soup)
+        }
+        
+        return components
+    
+    def _extract_meta_info(self, soup):
+        """Extract meta information and SEO elements."""
+        meta_info = {
+            'title': soup.title.string if soup.title else '',
+            'meta_tags': [],
+            'open_graph': {},
+            'twitter_cards': {}
+        }
+        
+        for meta in soup.find_all('meta'):
+            meta_info['meta_tags'].append({
+                'name': meta.get('name', ''),
+                'content': meta.get('content', ''),
+                'property': meta.get('property', '')
+            })
+            
+            # Extract Open Graph tags
+            if meta.get('property', '').startswith('og:'):
+                meta_info['open_graph'][meta.get('property')] = meta.get('content', '')
+            
+            # Extract Twitter Card tags
+            if meta.get('name', '').startswith('twitter:'):
+                meta_info['twitter_cards'][meta.get('name')] = meta.get('content', '')
+        
+        return meta_info
+    
+    def _identify_content_type(self, element):
+        """Identify the type of content in an element."""
+        text = element.get_text().lower()
+        
+        if any(word in text for word in ['abstract', 'summary', 'overview']):
+            return 'abstract'
+        elif any(word in text for word in ['introduction', 'background']):
+            return 'introduction'
+        elif any(word in text for word in ['method', 'approach', 'methodology']):
+            return 'methodology'
+        elif any(word in text for word in ['result', 'experiment', 'evaluation']):
+            return 'results'
+        elif any(word in text for word in ['conclusion', 'discussion', 'future']):
+            return 'conclusion'
+        elif any(word in text for word in ['contact', 'author', 'team']):
+            return 'contact'
+        else:
+            return 'general'
+    
+    def _extract_section_content(self, element):
+        """Extract text content from a section."""
+        content = {
+            'headings': [],
+            'paragraphs': [],
+            'lists': [],
+            'code_blocks': []
+        }
+        
+        for heading in element.find_all(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']):
+            content['headings'].append({
+                'level': int(heading.name[1]),
+                'text': heading.get_text().strip()
+            })
+        
+        for p in element.find_all('p'):
+            content['paragraphs'].append(p.get_text().strip())
+        
+        for ul in element.find_all(['ul', 'ol']):
+            items = [li.get_text().strip() for li in ul.find_all('li')]
+            content['lists'].append({
+                'type': ul.name,
+                'items': items
+            })
+        
+        for code in element.find_all(['code', 'pre']):
+            content['code_blocks'].append({
+                'type': code.name,
+                'content': code.get_text().strip()
+            })
+        
+        return content
+    
+    def _extract_images(self, element):
+        """Extract image information from an element."""
+        images = []
+        for img in element.find_all('img'):
+            images.append({
+                'src': img.get('src', ''),
+                'alt': img.get('alt', ''),
+                'title': img.get('title', ''),
+                'class': img.get('class', [])
+            })
+        return images
+    
+    def _extract_tables(self, element):
+        """Extract table information from an element."""
+        tables = []
+        for table in element.find_all('table'):
+            table_info = {
+                'class': table.get('class', []),
+                'headers': [],
+                'rows': []
+            }
+            
+            # Extract headers
+            for th in table.find_all('th'):
+                table_info['headers'].append(th.get_text().strip())
+            
+            # Extract rows
+            for tr in table.find_all('tr'):
+                row = [td.get_text().strip() for td in tr.find_all('td')]
+                if row:
+                    table_info['rows'].append(row)
+            
+            tables.append(table_info)
+        
+        return tables
+    
+    def _extract_navigation(self, soup):
+        """Extract navigation structure."""
+        nav = soup.find('nav')
+        if nav:
+            return {
+                'links': [a.get('href', '') for a in nav.find_all('a')],
+                'texts': [a.get_text().strip() for a in nav.find_all('a')],
+                'structure': self._extract_nav_structure(nav)
+            }
+        return None
+    
+    def _extract_nav_structure(self, nav_element):
+        """Extract the hierarchical structure of navigation."""
+        structure = []
+        for item in nav_element.find_all(['a', 'li'], recursive=False):
+            if item.name == 'a':
+                structure.append({
+                    'type': 'link',
+                    'text': item.get_text().strip(),
+                    'href': item.get('href', '')
+                })
+            elif item.name == 'li':
+                sub_items = []
+                for sub_item in item.find_all('a'):
+                    sub_items.append({
+                        'text': sub_item.get_text().strip(),
+                        'href': sub_item.get('href', '')
+                    })
+                structure.append({
+                    'type': 'group',
+                    'items': sub_items
+                })
+        return structure
+    
+    def _extract_hero_section(self, soup):
+        """Extract hero section information."""
+        hero = soup.find(['header', 'section'], class_=re.compile(r'hero|banner|intro'))
+        if hero:
+            return {
+                'title': hero.find(['h1', 'h2']).get_text().strip() if hero.find(['h1', 'h2']) else '',
+                'subtitle': hero.find(['h2', 'h3', 'p']).get_text().strip() if hero.find(['h2', 'h3', 'p']) else '',
+                'background_image': hero.find('img').get('src', '') if hero.find('img') else '',
+                'cta_buttons': [a.get_text().strip() for a in hero.find_all('a', class_=re.compile(r'btn|button'))]
+            }
+        return None
+    
+    def _extract_content_blocks(self, soup):
+        """Extract content block patterns."""
+        blocks = []
+        for block in soup.find_all(['div', 'section'], class_=re.compile(r'content|block|section')):
+            blocks.append({
+                'classes': block.get('class', []),
+                'content_type': self._identify_content_type(block),
+                'has_images': bool(block.find('img')),
+                'has_tables': bool(block.find('table')),
+                'has_code': bool(block.find(['code', 'pre']))
+            })
+        return blocks
+    
+    def _extract_image_galleries(self, soup):
+        """Extract image gallery patterns."""
+        galleries = []
+        for gallery in soup.find_all(['div', 'section'], class_=re.compile(r'gallery|carousel|slider')):
+            images = gallery.find_all('img')
+            galleries.append({
+                'image_count': len(images),
+                'layout': 'grid' if 'grid' in str(gallery.get('class', [])) else 'carousel',
+                'images': [img.get('src', '') for img in images]
+            })
+        return galleries
+    
+    def _extract_contact_forms(self, soup):
+        """Extract contact form patterns."""
+        forms = []
+        for form in soup.find_all('form'):
+            form_info = {
+                'action': form.get('action', ''),
+                'method': form.get('method', 'get'),
+                'fields': []
+            }
+            
+            for input_field in form.find_all(['input', 'textarea', 'select']):
+                form_info['fields'].append({
+                    'type': input_field.get('type', input_field.name),
+                    'name': input_field.get('name', ''),
+                    'placeholder': input_field.get('placeholder', ''),
+                    'required': input_field.get('required') is not None
+                })
+            
+            forms.append(form_info)
+        
+        return forms
+    
+    def analyze_multiple_templates(self, template_files):
+        """
+        Analyze multiple template files and find common patterns.
+        
+        Args:
+            template_files: List of template file paths
+            
+        Returns:
+            dict: Analysis results with common patterns
+        """
+        all_analyses = []
+        
+        for template_file in template_files:
+            analysis = self.analyze_html_template(template_file)
+            if analysis:
+                all_analyses.append(analysis)
+        
+        # Find common patterns
+        common_patterns = self._find_common_patterns(all_analyses)
+        
+        return {
+            'individual_analyses': all_analyses,
+            'common_patterns': common_patterns
+        }
+    
+    def _find_common_patterns(self, analyses):
+        """Find common patterns across multiple template analyses."""
+        patterns = {
+            'common_sections': [],
+            'common_styles': [],
+            'common_components': [],
+            'color_schemes': [],
+            'layout_patterns': []
+        }
+        
+        # Analyze common sections
+        all_sections = []
+        for analysis in analyses:
+            all_sections.extend(analysis['sections'])
+        
+        section_types = {}
+        for section in all_sections:
+            content_type = section.get('content_type', 'unknown')
+            if content_type not in section_types:
+                section_types[content_type] = 0
+            section_types[content_type] += 1
+        
+        patterns['common_sections'] = [
+            section_type for section_type, count in section_types.items()
+            if count > len(analyses) * 0.5  # Appears in more than 50% of templates
+        ]
+        
+        # Analyze common styles
+        all_colors = []
+        for analysis in analyses:
+            all_colors.extend(analysis['styling']['color_scheme'])
+        
+        color_counts = {}
+        for color in all_colors:
+            if color not in color_counts:
+                color_counts[color] = 0
+            color_counts[color] += 1
+        
+        patterns['color_schemes'] = [
+            color for color, count in color_counts.items()
+            if count > len(analyses) * 0.3  # Appears in more than 30% of templates
+        ]
+        
+        return patterns
+    
+    def save_analysis(self, analysis, output_path):
+        """Save analysis results to a JSON file."""
+        try:
+            with open(output_path, 'w') as f:
+                json.dump(analysis, f, indent=2)
+            print(f"Analysis saved to {output_path}")
+            return True
+        except Exception as e:
+            print(f"Error saving analysis: {e}")
+            return False 

app.py

@@ -0,0 +1,1671 @@
+
+import gradio as gr
+import os
+import json
+from pathlib import Path
+import base64
+import re
+from threading import Thread
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+import socket
+from dotenv import load_dotenv
+from ProjectPageAgent.parse_paper import parse_paper_for_project_page, save_parsed_content
+from ProjectPageAgent.html_finder import HtmlFinder
+from ProjectPageAgent.content_planner import ProjectPageContentPlanner
+from ProjectPageAgent.html_generator import ProjectPageHTMLGenerator, to_url
+from utils.wei_utils import get_agent_config
+import os
+import subprocess
+
+from ProjectPageAgent.content_planner import filter_references
+from utils.src.utils import run_sync_screenshots
+from ProjectPageAgent.main_pipline import matching, copy_static_files
+
+load_dotenv()
+
+subprocess.run(["playwright", "install", "chromium"], check=True)
+
+
+def get_agent_config_with_keys(model_type, openai_api_key="", gemini_api_key="", 
+                              qwen_api_key="", zhipuai_api_key="", openrouter_api_key=""):
+    """
+    Get agent configuration with user-provided API keys.
+    Falls back to environment variables if user keys are not provided.
+    Note: This function sets environment variables but does NOT restore them.
+    The environment variables will remain set for the duration of the application.
+    """
+    # Set environment variables with user-provided keys
+    api_keys = {
+        'OPENAI_API_KEY': openai_api_key,
+        'GEMINI_API_KEY': gemini_api_key, 
+        'QWEN_API_KEY': qwen_api_key,
+        'ZHIPUAI_API_KEY': zhipuai_api_key,
+        'OPENROUTER_API_KEY': openrouter_api_key
+    }
+    
+    # Set new API keys in environment
+    for key, value in api_keys.items():
+        if value and value.strip():
+            os.environ[key] = value
+    
+    # Get agent config with the new API keys
+    config = get_agent_config(model_type)
+    return config
+
+def validate_api_keys(model_name_t, model_name_v, openai_api_key, gemini_api_key, 
+                     qwen_api_key, zhipuai_api_key, openrouter_api_key):
+    """
+    Validate that required API keys are provided for the selected models.
+    """
+    errors = []
+    
+    # Check text model requirements
+    if model_name_t in ['4o', '4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'o1', 'o3', 'o3-mini']:
+        if not openai_api_key or not openai_api_key.strip():
+            errors.append("OpenAI API key is required for GPT models")
+    elif model_name_t in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+        if not gemini_api_key or not gemini_api_key.strip():
+            errors.append("Gemini API key is required for Gemini models")
+    elif model_name_t in ['qwen', 'qwen-plus', 'qwen-max', 'qwen-long']:
+        if not qwen_api_key or not qwen_api_key.strip():
+            errors.append("Qwen API key is required for Qwen models")
+    elif model_name_t.startswith('openrouter_'):
+        if not openrouter_api_key or not openrouter_api_key.strip():
+            errors.append("OpenRouter API key is required for OpenRouter models")
+    
+    # Check vision model requirements
+    if model_name_v in ['4o', '4o-mini']:
+        if not openai_api_key or not openai_api_key.strip():
+            errors.append("OpenAI API key is required for GPT vision models")
+    elif model_name_v in ['gemini', 'gemini-2.5-pro', 'gemini-2.5-flash']:
+        if not gemini_api_key or not gemini_api_key.strip():
+            errors.append("Gemini API key is required for Gemini vision models")
+    elif model_name_v in ['qwen-vl-max', 'qwen-2.5-vl-72b']:
+        if not qwen_api_key or not qwen_api_key.strip():
+            errors.append("Qwen API key is required for Qwen vision models")
+    elif model_name_v.startswith('openrouter_'):
+        if not openrouter_api_key or not openrouter_api_key.strip():
+            errors.append("OpenRouter API key is required for OpenRouter vision models")
+    
+    return errors
+
+# Global Variables
+current_html_dir = None
+preview_server = None
+preview_port = None
+template_preview_servers = []
+
+class CustomHTTPRequestHandler(SimpleHTTPRequestHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, directory=current_html_dir, **kwargs)
+    
+    def log_message(self, format, *args):
+        pass
+
+def find_free_port(start_port=8000, max_attempts=100):
+    for port in range(start_port, start_port + max_attempts):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(('', port))
+                return port
+        except OSError:
+            continue
+    raise RuntimeError(f"Could not find available port")
+
+def start_preview_server(html_dir):
+    global current_html_dir, preview_server, preview_port
+    stop_preview_server()
+    current_html_dir = html_dir
+    preview_port = find_free_port()
+    preview_server = HTTPServer(('0.0.0.0', preview_port), CustomHTTPRequestHandler)
+    server_thread = Thread(target=preview_server.serve_forever, daemon=True)
+    server_thread.start()
+    return preview_port
+
+def stop_preview_server():
+    global preview_server, preview_port
+    if preview_server:
+        preview_server.shutdown()
+        preview_server = None
+        preview_port = None
+
+def start_ephemeral_server_for_dir(html_dir):
+    port = find_free_port()
+    class _TempHandler(SimpleHTTPRequestHandler):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, directory=html_dir, **kwargs)
+        def log_message(self, format, *args):
+            pass
+    srv = HTTPServer(('0.0.0.0', port), _TempHandler)
+    t = Thread(target=srv.serve_forever, daemon=True)
+    t.start()
+    template_preview_servers.append((srv, port))
+    return port
+
+def stop_all_template_preview_servers():
+    global template_preview_servers
+    for srv, _ in template_preview_servers:
+        try:
+            srv.shutdown()
+        except Exception:
+            pass
+    template_preview_servers = []
+
+class GenerationArgs:
+    def __init__(self, paper_path, model_name_t, model_name_v, template_root, 
+                 template_dir, template_file, output_dir, style_preference, tmp_dir,
+                 full_content_check_times, background_color, has_navigation, 
+                 has_hero_section, title_color, page_density, image_layout, 
+                 html_check_times, resume, human_input):
+        self.paper_path = paper_path
+        self.model_name_t = model_name_t
+        self.model_name_v = model_name_v
+        self.template_root = template_root
+        self.template_dir = template_dir
+        self.template_file = template_file
+        self.output_dir = output_dir
+        self.style_preference = style_preference
+        self.tmp_dir = tmp_dir
+        self.full_content_check_times = full_content_check_times
+        self.background_color = background_color
+        self.has_navigation = has_navigation
+        self.has_hero_section = has_hero_section
+        self.title_color = title_color
+        self.page_density = page_density
+        self.image_layout = image_layout
+        self.html_check_times = html_check_times
+        self.resume = resume
+        self.human_input = human_input
+        self.paper_name = None
+
+# ==================== Formatting Functions ====================
+
+def format_section_to_markdown(section_data):
+    """
+    Convert Section JSON to beautifully formatted Markdown
+    
+    Args:
+        section_data: Section JSON data
+    
+    Returns:
+        str: Formatted Markdown string
+    """
+    if not section_data:
+        return "No data available"
+    
+    md_lines = []
+    
+    # Title
+    md_lines.append("# 📄 Paper Page Structure Preview\n")
+    
+    # Basic Information
+    if "title" in section_data:
+        md_lines.append(f"## 📌 Title\n**{section_data['title']}**\n")
+    
+    if "authors" in section_data:
+        md_lines.append(f"## 👥 Authors\n{section_data['authors']}\n")
+    
+    if "affiliation" in section_data:
+        md_lines.append(f"## 🏛️ Affiliation\n{section_data['affiliation']}\n")
+    
+    # Other Sections
+    md_lines.append("## 📑 Page Sections\n")
+    
+    section_count = 0
+    for key, value in section_data.items():
+        if key in ["title", "authors", "affiliation"]:
+            continue
+        
+        section_count += 1
+        
+        # Section Title
+        section_title = key.replace("_", " ").title()
+        md_lines.append(f"### {section_count}. {section_title}\n")
+        
+        # Section Content
+        if isinstance(value, dict):
+            # If dictionary, process recursively
+            for sub_key, sub_value in value.items():
+                sub_title = sub_key.replace("_", " ").title()
+                md_lines.append(f"**{sub_title}**: {sub_value}\n")
+        elif isinstance(value, list):
+            # If list
+            for item in value:
+                if isinstance(item, str):
+                    md_lines.append(f"- {item}\n")
+                elif isinstance(item, dict):
+                    for k, v in item.items():
+                        md_lines.append(f"- **{k}**: {v}\n")
+        else:
+            # Simple value
+            md_lines.append(f"{value}\n")
+        
+        md_lines.append("")  # Empty line
+    
+    # Add Statistics
+    md_lines.append("---\n")
+    md_lines.append(f"**📊 Total {section_count} sections**\n")
+    
+    return "\n".join(md_lines)
+
+
+def format_full_content_to_markdown(content_data, figures=None):
+    """
+    Convert Full Content JSON to beautifully formatted Markdown
+    
+    Args:
+        content_data: Full Content JSON data
+        figures: Images and tables data (optional)
+    
+    Returns:
+        str: Formatted Markdown string
+    """
+    if not content_data:
+        return "No data available"
+    
+    md_lines = []
+    
+    # Title
+    md_lines.append("# 📄 Full Content Preview\n")
+    
+    # Basic Information
+    if "title" in content_data:
+        md_lines.append(f"# {content_data['title']}\n")
+    
+    if "authors" in content_data:
+        md_lines.append(f"**Authors**: {content_data['authors']}\n")
+    
+    if "affiliation" in content_data:
+        md_lines.append(f"**Affiliation**: {content_data['affiliation']}\n")
+    
+    md_lines.append("---\n")
+    
+    # Process Each Section
+    section_count = 0
+    image_count = 0
+    table_count = 0
+    
+    for key, value in content_data.items():
+        if key in ["title", "authors", "affiliation"]:
+            continue
+        
+        section_count += 1
+        
+        # Section Title
+        section_title = key.replace("_", " ").title()
+        md_lines.append(f"## {section_count}. {section_title}\n")
+        
+        # Process Content
+        if isinstance(value, dict):
+            # Process dictionary type content
+            for sub_key, sub_value in value.items():
+                if sub_key.lower() in ['content', 'description', 'text']:
+                    # Main text content
+                    md_lines.append(f"{sub_value}\n")
+                elif sub_key.lower() in ['image', 'figure', 'img']:
+                    # Image
+                    image_count += 1
+                    if isinstance(sub_value, dict):
+                        caption = sub_value.get('caption', f'Figure {image_count}')
+                        path = sub_value.get('path', '')
+                        md_lines.append(f"\n**🖼️ {caption}**\n")
+                        if path:
+                            md_lines.append(f"*Image path: `{path}`*\n")
+                    else:
+                        md_lines.append(f"\n**🖼️ Figure {image_count}**: {sub_value}\n")
+                elif sub_key.lower() in ['table']:
+                    # Table
+                    table_count += 1
+                    md_lines.append(f"\n**📊 Table {table_count}**\n")
+                    if isinstance(sub_value, dict):
+                        caption = sub_value.get('caption', f'Table {table_count}')
+                        md_lines.append(f"*{caption}*\n")
+                    else:
+                        md_lines.append(f"{sub_value}\n")
+                elif sub_key.lower() in ['code']:
+                    # Code block
+                    md_lines.append(f"\n```\n{sub_value}\n```\n")
+                else:
+                    # Other subtitles
+                    sub_title = sub_key.replace("_", " ").title()
+                    md_lines.append(f"\n### {sub_title}\n")
+                    md_lines.append(f"{sub_value}\n")
+        
+        elif isinstance(value, list):
+            # Process list type content
+            for idx, item in enumerate(value):
+                if isinstance(item, dict):
+                    # Dictionary items in list
+                    if 'title' in item or 'name' in item:
+                        item_title = item.get('title', item.get('name', f'Item {idx+1}'))
+                        md_lines.append(f"\n### {item_title}\n")
+                    
+                    for k, v in item.items():
+                        if k not in ['title', 'name']:
+                            if k.lower() in ['content', 'description', 'text']:
+                                md_lines.append(f"{v}\n")
+                            elif k.lower() in ['image', 'figure']:
+                                image_count += 1
+                                md_lines.append(f"\n**🖼️ Figure {image_count}**: {v}\n")
+                            elif k.lower() == 'table':
+                                table_count += 1
+                                md_lines.append(f"\n**📊 Table {table_count}**: {v}\n")
+                            else:
+                                k_title = k.replace("_", " ").title()
+                                md_lines.append(f"**{k_title}**: {v}\n")
+                else:
+                    # Simple list item
+                    md_lines.append(f"- {item}\n")
+        
+        else:
+            # Simple text value
+            md_lines.append(f"{value}\n")
+        
+        md_lines.append("")  # Empty line between sections
+    
+    # Add Statistics
+    md_lines.append("\n---\n")
+    stats = []
+    stats.append(f"📊 **Statistics**")
+    stats.append(f"- Sections: {section_count}")
+    if image_count > 0:
+        stats.append(f"- Images: {image_count}")
+    if table_count > 0:
+        stats.append(f"- Tables: {table_count}")
+    
+    # If figures data is provided, add more information
+    if figures:
+        if 'images' in figures and figures['images']:
+            stats.append(f"- Available images: {len(figures['images'])}")
+        if 'tables' in figures and figures['tables']:
+            stats.append(f"- Available tables: {len(figures['tables'])}")
+    
+    md_lines.append("\n".join(stats))
+    md_lines.append("\n")
+    
+    return "\n".join(md_lines)
+
+# ==================== Global State Management ====================
+
+class GenerationState:
+    def __init__(self):
+        self.reset()
+    
+    def reset(self):
+        self.args = None
+        self.paper_content = None
+        self.figures = None
+        self.generated_section = None
+        self.text_page_content = None
+        self.generated_content = None
+        self.html_content = None
+        self.html_file_path = None
+        self.html_dir = None
+        self.planner = None
+        self.html_generator = None
+        self.agent_config_t = None
+        self.total_input_tokens_t = 0
+        self.total_output_tokens_t = 0
+        self.current_stage = "init"
+        self.preview_url = None
+
+state = GenerationState()
+
+def create_project_zip(project_dir, output_dir, paper_name):
+    """
+    Create project archive
+    
+    Args:
+        project_dir: Project directory path
+        output_dir: Output directory
+        paper_name: Paper name
+    
+    Returns:
+        str: Archive path, None if failed
+    """
+    import zipfile
+    
+    zip_filename = f"{paper_name}_project_page.zip"
+    zip_path = os.path.join(output_dir, zip_filename)
+    
+    print(f"Creating project archive: {zip_path}")
+    
+    try:
+        with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Traverse project directory, add all files
+            for root, dirs, files in os.walk(project_dir):
+                for file in files:
+                    file_path = os.path.join(root, file)
+                    # Calculate relative path
+                    arcname = os.path.relpath(file_path, output_dir)
+                    zipf.write(file_path, arcname)
+                    
+        print(f"Archive created successfully: {zip_path}")
+        
+        # Get archive size
+        zip_size = os.path.getsize(zip_path)
+        zip_size_mb = zip_size / (1024 * 1024)
+        print(f"Archive size: {zip_size_mb:.2f} MB")
+        
+        return zip_path
+        
+    except Exception as e:
+        print(f"Archive creation failed: {e}")
+        return None
+
+def start_generation(pdf_file, model_name_t, model_name_v, template_root, 
+                    template_dir, template_file, output_dir, style_preference, 
+                    tmp_dir, full_content_check_times, background_color, 
+                    has_navigation, has_hero_section, title_color, page_density, 
+                    image_layout, html_check_times, resume, human_input, 
+                    template_choice_value, openai_api_key, gemini_api_key, 
+                    qwen_api_key, zhipuai_api_key, openrouter_api_key):
+    """Start generation process"""
+    if pdf_file is None:
+        return "❌ Please upload a PDF file", gr.update(visible=False), "", "", gr.update(), gr.update(), ""
+    
+    # Validate API keys
+    validation_errors = validate_api_keys(
+        model_name_t, model_name_v, openai_api_key, gemini_api_key, 
+        qwen_api_key, zhipuai_api_key, openrouter_api_key
+    )
+    
+    if validation_errors:
+        error_msg = "❌ API Key Validation Failed:\n" + "\n".join(f"• {error}" for error in validation_errors)
+        return error_msg, gr.update(visible=False), "", "", gr.update(), gr.update(), ""
+    
+    state.reset()
+    
+    # Handle template selection
+    if not (template_dir and str(template_dir).strip()):
+        if not template_choice_value:
+            stop_all_template_preview_servers()
+            template_requirement = {
+                "background_color": background_color,
+                "has_hero_section": has_hero_section,
+                "Page density": page_density,
+                "image_layout": image_layout,
+                "has_navigation": has_navigation,
+                "title_color": title_color
+            }
+            try:
+                matched = matching(template_requirement)
+            except Exception as e:
+                return f"❌ Template recommendation failed: {e}", gr.update(visible=False), "", "", gr.update(choices=[], value=None), gr.update(visible=False, value=""), ""
+            
+            html_finder_ = HtmlFinder()
+            with open('templates/template_link.json','r') as f:
+                template_link = json.load(f)
+            previews = []
+            for name in matched:
+                t_dir = os.path.join(template_root, name)
+                try:
+                    html_path = html_finder_.find_html(t_dir)
+                    if not os.path.exists(html_path):
+                        continue
+                    html_dir = os.path.dirname(os.path.abspath(html_path))
+                    filename = os.path.basename(html_path)
+                    port = start_ephemeral_server_for_dir(html_dir)
+                    url = template_link[name]
+                    previews.append((name, html_path, url))
+                except Exception:
+                    continue
+            
+            if not previews:
+                return "❌ No previewable templates found", gr.update(visible=False), "", "", gr.update(choices=[], value=None), gr.update(visible=False, value=""), ""
+            
+            md_lines = ["### 🔍 Please select a template to preview before clicking **Start Generation**", ""]
+            for name, _, url in previews:
+                md_lines.append(f"- **{name}** → [{url}]({url})")
+            md = "\n".join(md_lines)
+            
+            return "Recommended 3 templates, please select one to continue", gr.update(visible=False), "", "", gr.update(choices=[n for n, _, _ in previews], value=None), gr.update(visible=True, value=md), ""
+        
+        template_dir = os.path.join(template_root, template_choice_value)
+    
+    # Create arguments object
+    args = GenerationArgs(
+        paper_path=pdf_file.name,
+        model_name_t=model_name_t,
+        model_name_v=model_name_v,
+        template_root=template_root,
+        template_dir=template_dir,
+        template_file=template_file,
+        output_dir=output_dir,
+        style_preference=style_preference,
+        tmp_dir=tmp_dir,
+        full_content_check_times=full_content_check_times,
+        background_color=background_color,
+        has_navigation=has_navigation,
+        has_hero_section=has_hero_section,
+        title_color=title_color,
+        page_density=page_density,
+        image_layout=image_layout,
+        html_check_times=html_check_times,
+        resume=resume,
+        human_input=human_input
+    )
+    
+    if not args.template_dir:
+        return "❌ Please select a template", gr.update(visible=False), "", "", gr.update(), gr.update(), ""
+    
+    if not args.template_file:
+        html_finder_ = HtmlFinder()
+        args.template_file = html_finder_.find_html(args.template_dir)
+    
+    paper_name = args.paper_path.split('/')[-1].replace('.pdf', '') if '/' in args.paper_path else args.paper_path.replace('.pdf', '')
+    args.paper_name = paper_name
+    
+    os.makedirs(args.tmp_dir, exist_ok=True)
+    
+    try:
+        # Initialization
+        agent_config_t = get_agent_config_with_keys(
+            args.model_name_t, openai_api_key, gemini_api_key, 
+            qwen_api_key, zhipuai_api_key, openrouter_api_key
+        )
+        state.agent_config_t = agent_config_t
+        state.args = args
+        
+        # Step 1: Parse PDF
+        print("="*50)
+        print("STEP 1: Parsing Research Paper")
+        print("="*50)
+        
+        raw_content_path = f'project_contents/{args.paper_name}_raw_content.json'
+        if not os.path.exists(raw_content_path):
+            agent_config_v = get_agent_config_with_keys(
+                args.model_name_v, openai_api_key, gemini_api_key, 
+                qwen_api_key, zhipuai_api_key, openrouter_api_key
+            )
+            input_token, output_token, raw_result, images, tables = parse_paper_for_project_page(args, agent_config_t)
+            state.total_input_tokens_t += input_token
+            state.total_output_tokens_t += output_token
+            raw_content_path, _ = save_parsed_content(args, raw_result, images, tables, input_token, output_token)
+        
+        with open(raw_content_path, 'r') as f:
+            paper_content = json.load(f)
+        
+        images = paper_content.get('images', [])
+        tables = paper_content.get('tables', [])
+        figures = {'images': images, 'tables': tables}
+        paper_content = paper_content.get('markdown_content', "")
+        
+        state.paper_content = paper_content
+        state.figures = figures
+        
+        # Step 2: Filter content
+        print("="*50)
+        print("STEP 2: Filtering Content")
+        print("="*50)
+        
+        planner = ProjectPageContentPlanner(agent_config_t, args)
+        state.planner = planner
+        
+        paper_content, figures, input_token, output_token = planner.filter_raw_content(paper_content, figures)
+        state.total_input_tokens_t += input_token
+        state.total_output_tokens_t += output_token
+        state.paper_content = paper_content
+        state.figures = figures
+        
+        # Step 3: Generate Section
+        print("="*50)
+        print("STEP 3: Generating Sections")
+        print("="*50)
+        
+        state.current_stage = "section"
+        
+        generated_section, input_token, output_token = generate_section_initial()
+        state.total_input_tokens_t += input_token
+        state.total_output_tokens_t += output_token
+        
+        # Use Markdown formatting
+        section_display_md = format_section_to_markdown(generated_section)
+        section_display_json = json.dumps(generated_section, indent=2, ensure_ascii=False)
+        
+        return (
+            f"✅ Section generation completed, please review and provide feedback\n\nTokens: {input_token} → {output_token}",
+            gr.update(visible=True),  # feedback_section
+            section_display_md,       # Markdown format
+            section_display_json,     # JSON format (hidden)
+            gr.update(),
+            gr.update(visible=False, value=""),
+            ""
+        )
+        
+    except Exception as e:
+        import traceback
+        error_msg = f"❌ Generation failed: {str(e)}\n{traceback.format_exc()}"
+        return error_msg, gr.update(visible=False), "", "", gr.update(), gr.update(), ""
+
+def generate_section_initial():
+    """Generate initial Section"""
+    import yaml
+    from jinja2 import Environment, StrictUndefined
+    from utils.wei_utils import account_token
+    from utils.src.utils import get_json_from_response
+    
+    with open('utils/prompt_templates/page_templates/section_generation.yaml', 'r') as f:
+        planner_config = yaml.safe_load(f)
+    
+    jinja_env = Environment(undefined=StrictUndefined)
+    template = jinja_env.from_string(planner_config["template"])
+    
+    jinja_args = {
+        'paper_content': state.paper_content,
+        'json_format_example': json.dumps(state.paper_content, indent=2)
+    }
+    
+    prompt = template.render(**jinja_args)
+    
+    state.planner.planner_agent.reset()
+    response = state.planner.planner_agent.step(prompt)
+    input_token, output_token = account_token(response)
+    generated_section = get_json_from_response(response.msgs[0].content)
+    
+    def create_dynamic_page_dict(sections):
+        poster_dict = {
+            "title": "Title of the paper",
+            "authors": "Authors of the paper",
+            "affiliation": "Affiliation of the authors",
+        }
+        poster_dict.update(sections)
+        return poster_dict
+    
+    generated_section = create_dynamic_page_dict(generated_section)
+    state.generated_section = generated_section
+    
+    generated_path = f'project_contents/{state.args.paper_name}_generated_section.json'
+    with open(generated_path, 'w') as f:
+        json.dump(generated_section, f, indent=4)
+    
+    return generated_section, input_token, output_token
+
+def submit_section_feedback(feedback_text):
+    """Submit Section feedback"""
+    if not feedback_text or feedback_text.strip().lower() == 'yes':
+        # User satisfied, proceed to next stage
+        result = proceed_to_text_content()
+        status, fc_section_visible, fc_display_visible, fc_display_md, fc_display_json, fc_feedback_visible = result
+        return (
+            status,
+            "",  # section_display_md clear
+            "",  # section_display_json clear
+            "",  # section_feedback_input clear
+            gr.update(visible=False),  # feedback_section hide
+            fc_section_visible,  # feedback_full_content show
+            fc_display_visible,  # full_content_display_md show
+            fc_display_md,  # full_content_display_md content
+            fc_display_json,  # full_content_display_json content
+            fc_feedback_visible  # full_content_feedback_input show
+        )
+    
+    # User provides feedback, modify Section
+    from camel.messages import BaseMessage
+    from utils.wei_utils import account_token
+    from utils.src.utils import get_json_from_response
+    
+    message = BaseMessage.make_assistant_message(
+        role_name='User',
+        content=f'human feedback: {feedback_text}\n\nPlease make modifications based on this feedback. Output format as specified above.'
+    )
+    response = state.planner.planner_agent.step(message)
+    input_token, output_token = account_token(response)
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    
+    generated_section = get_json_from_response(response.msgs[0].content)
+    state.generated_section = generated_section
+    
+    generated_path = f'project_contents/{state.args.paper_name}_generated_section.json'
+    with open(generated_path, 'w') as f:
+        json.dump(generated_section, f, indent=4)
+    
+    # Use Markdown formatting
+    section_display_md = format_section_to_markdown(generated_section)
+    section_display_json = json.dumps(generated_section, indent=2, ensure_ascii=False)
+    
+    return (
+        f"✅ Section updated, please continue reviewing\n\nTokens: {input_token} → {output_token}",
+        section_display_md,  # Markdown format
+        section_display_json,  # JSON format
+        "",  # Clear input box
+        gr.update(visible=True),  # feedback_section keep visible
+        gr.update(visible=False),  # feedback_full_content keep hidden
+        gr.update(visible=False),  # full_content_display_md keep hidden
+        "",  # full_content_display_md content
+        "",  # full_content_display_json content
+        gr.update(visible=False)  # full_content_feedback_input keep hidden
+    )
+
+def proceed_to_text_content():
+    """Enter Text Content generation stage"""
+    print("="*50)
+    print("STEP 4: Generating Text Content")
+    print("="*50)
+    
+    text_page_content, input_token, output_token = state.planner.text_content_generation(
+        state.paper_content, state.figures, state.generated_section
+    )
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    state.text_page_content = text_page_content
+    
+    # Enter Full Content stage
+    return proceed_to_full_content()
+
+def proceed_to_full_content():
+    """Enter Full Content generation stage"""
+    print("="*50)
+    print("STEP 5: Generating Full Content")
+    print("="*50)
+    
+    state.current_stage = "full_content"
+    
+    generated_content, input_token, output_token = generate_full_content_initial()
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    
+    # Use Markdown formatting
+    content_display_md = format_full_content_to_markdown(generated_content, state.figures)
+    content_display_json = json.dumps(generated_content, indent=2, ensure_ascii=False)
+    
+    return (
+        f"✅ Full Content generation completed, please review and provide feedback\n\nTokens: {input_token} → {output_token}",
+        gr.update(visible=True),   # feedback_full_content show
+        gr.update(visible=True),   # full_content_display_md show
+        content_display_md,        # Markdown format
+        content_display_json,      # JSON format
+        gr.update(visible=True)    # full_content_feedback_input show
+    )
+
+def generate_full_content_initial():
+    """Generate initial Full Content"""
+    import yaml
+    from jinja2 import Environment, StrictUndefined
+    from utils.wei_utils import account_token
+    from utils.src.utils import get_json_from_response
+    
+    with open('utils/prompt_templates/page_templates/full_content_generation.yaml', 'r') as f:
+        planner_config = yaml.safe_load(f)
+    
+    jinja_env = Environment(undefined=StrictUndefined)
+    template = jinja_env.from_string(planner_config["template"])
+    
+    jinja_args = {
+        'paper_content': state.paper_content,
+        'figures': json.dumps(state.figures, indent=2),
+        'project_page_content': json.dumps(state.text_page_content, indent=2)
+    }
+    
+    prompt = template.render(**jinja_args)
+    
+    state.planner.planner_agent.reset()
+    response = state.planner.planner_agent.step(prompt)
+    input_token, output_token = account_token(response)
+    generated_content = get_json_from_response(response.msgs[0].content)
+    
+    state.generated_content = generated_content
+    
+    first_path = f'project_contents/{state.args.paper_name}_generated_full_content.v0.json'
+    with open(first_path, 'w', encoding='utf-8') as f:
+        json.dump(generated_content, f, ensure_ascii=False, indent=2)
+    
+    return generated_content, input_token, output_token
+
+def submit_full_content_feedback(feedback_text):
+    """Submit Full Content feedback"""
+    if not feedback_text or feedback_text.strip().lower() == 'yes':
+        # User satisfied, proceed to HTML generation
+        result = proceed_to_html_generation()
+        status, html_feedback_visible, preview_info, preview_url, open_btn_visible = result
+        return (
+            status,
+            "",  # full_content_display_md clear
+            "",  # full_content_display_json clear
+            "",  # full_content_feedback_input clear
+            gr.update(visible=False),  # feedback_full_content hide
+            html_feedback_visible,  # feedback_html show
+            preview_info,  # preview_info_display
+            preview_url,  # preview_url_state
+            open_btn_visible  # open_preview_btn show
+        )
+    
+    # User provides feedback
+    from camel.messages import BaseMessage
+    from utils.wei_utils import account_token
+    from utils.src.utils import get_json_from_response
+    
+    message = BaseMessage.make_assistant_message(
+        role_name='User',
+        content=f'human feedback: {feedback_text}\n\nPlease make modifications based on this feedback. Output format as specified above.'
+    )
+    response = state.planner.planner_agent.step(message)
+    input_token, output_token = account_token(response)
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    
+    generated_content = get_json_from_response(response.msgs[0].content)
+    state.generated_content = generated_content
+    
+    final_path = f'project_contents/{state.args.paper_name}_generated_full_content.json'
+    with open(final_path, 'w', encoding='utf-8') as f:
+        json.dump(generated_content, f, ensure_ascii=False, indent=2)
+    
+    # Use Markdown formatting
+    content_display_md = format_full_content_to_markdown(generated_content, state.figures)
+    content_display_json = json.dumps(generated_content, indent=2, ensure_ascii=False)
+    
+    return (
+        f"✅ Full Content updated, please continue reviewing\n\nTokens: {input_token} → {output_token}",
+        content_display_md,  # Markdown format
+        content_display_json,  # JSON format
+        "",  # Clear input box
+        gr.update(visible=True),  # feedback_full_content keep visible
+        gr.update(visible=False),  # feedback_html keep hidden
+        "",  # preview_info_display
+        "",  # preview_url_state
+        gr.update(visible=False)  # open_preview_btn keep hidden
+    )
+
+def proceed_to_html_generation():
+    """Enter HTML generation stage"""
+    print("="*50)
+    print("STEP 6: Generating HTML")
+    print("="*50)
+    
+    state.current_stage = "html"
+    
+    # Copy static files
+    static_dir = copy_static_files(
+        state.args.template_file, 
+        state.args.template_dir, 
+        state.args.output_dir, 
+        state.args.paper_name
+    )
+    
+    # Generate HTML
+    html_relative_path = os.path.relpath(state.args.template_file, state.args.template_dir)
+    html_dir = '/'.join(html_relative_path.strip().split('/')[:-1])
+    state.html_dir = html_dir
+    
+    html_generator = ProjectPageHTMLGenerator(state.agent_config_t, state.args)
+    state.html_generator = html_generator
+    
+    with open(state.args.template_file, 'r', encoding='utf-8') as file:
+        html_template = file.read()
+    
+    # Create assets directory
+    assets_dir = html_generator.create_assets_directory(state.args, html_dir, state.args.output_dir)
+    
+    # Generate HTML
+    html_content, input_token, output_token = html_generator.generate_complete_html(
+        state.args, state.generated_content, html_dir, html_template
+    )
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    
+    # Save HTML (before table modification)
+    html_dir_path = os.path.join(state.args.output_dir, state.args.paper_name, html_dir)
+    os.makedirs(html_dir_path, exist_ok=True)
+    
+    html_file_path_no_modify = os.path.join(html_dir_path, 'index_no_modify_table.html')
+    with open(html_file_path_no_modify, 'w', encoding='utf-8') as file:
+        file.write(html_content)
+    
+    # Generate screenshot (before table modification)
+    screenshot_path_no_modify = os.path.join(html_dir_path, 'page_final_no_modify_table.png')
+    run_sync_screenshots(to_url(html_file_path_no_modify), screenshot_path_no_modify)
+    
+    # Modify tables
+    html_content, input_token, output_token = html_generator.modify_html_table(html_content, html_dir)
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    
+    state.html_content = html_content
+    
+    # Save HTML (after table modification)
+    html_file_path = os.path.join(html_dir_path, 'index.html')
+    with open(html_file_path, 'w', encoding='utf-8') as file:
+        file.write(html_content)
+    
+    state.html_file_path = html_file_path
+    
+    # Generate screenshot (after table modification)
+    run_sync_screenshots(
+        to_url(html_file_path), 
+        os.path.join(html_dir_path, 'page_final.png')
+    )
+    
+    # Start preview server
+    html_full_dir = os.path.dirname(os.path.abspath(html_file_path))
+    port = start_preview_server(html_full_dir)
+    preview_url = f"http://localhost:{port}/index.html"
+    state.preview_url = preview_url
+    
+    # Create preview info display
+    preview_info = f"""
+### 🌐 HTML Generation Completed
+
+**Preview URL**: {preview_url}
+
+**Instructions**:
+1. Click the **"🌐 Open Preview in New Tab"** button below to view the generated webpage
+2. Carefully review the page in the new tab
+3. If satisfied, enter **'yes'** in the feedback box and submit
+4. If modifications are needed, provide detailed feedback and submit
+
+**Token Usage**: {input_token} → {output_token}
+"""
+    
+    return (
+        f"✅ HTML generation completed\n\nTokens: {input_token} → {output_token}",
+        gr.update(visible=True),   # feedback_html show
+        preview_info,              # preview_info_display
+        preview_url,               # preview_url_state
+        gr.update(visible=True)    # open_preview_btn show
+    )
+
+def submit_html_feedback(feedback_text):
+    """Submit HTML feedback"""
+    if not feedback_text or feedback_text.strip().lower() == 'yes':
+        # User satisfied, complete generation
+        result = finalize_generation()
+        status, html_file = result
+        return (
+            status,
+            "",  # preview_info_display clear
+            "",  # html_feedback_input clear
+            gr.update(visible=False),  # feedback_html hide
+            gr.update(visible=False),  # open_preview_btn hide
+            html_file  # html_file_output
+        )
+    
+    # User provides feedback
+    html_content, input_token, output_token = state.html_generator.modify_html_from_human_feedback(
+        state.html_content, feedback_text
+    )
+    state.total_input_tokens_t += input_token
+    state.total_output_tokens_t += output_token
+    state.html_content = html_content
+    
+    # Save updated HTML
+    html_dir_path = os.path.dirname(state.html_file_path)
+    
+    # Save as temporary version (for possible feedback iteration)
+    import time
+    timestamp = int(time.time())
+    html_file_feedback = os.path.join(html_dir_path, f'index_feedback_{timestamp}.html')
+    with open(html_file_feedback, 'w', encoding='utf-8') as file:
+        file.write(html_content)
+    
+    # Also update main file
+    with open(state.html_file_path, 'w', encoding='utf-8') as file:
+        file.write(html_content)
+    
+    # Regenerate screenshot
+    screenshot_path = os.path.join(html_dir_path, 'page_final.png')
+    try:
+        run_sync_screenshots(to_url(state.html_file_path), screenshot_path)
+    except Exception as e:
+        print(f"Screenshot generation failed: {e}")
+    
+    # Update preview info
+    preview_info = f"""
+### 🌐 HTML Updated
+
+**Preview URL**: {state.preview_url}
+
+**Instructions**:
+1. Click the **"🌐 Open Preview in New Tab"** button below to view the updated webpage
+2. **Refresh the browser** to see the latest version
+3. If satisfied, enter **'yes'** in the feedback box and submit
+4. If further modifications are needed, continue providing feedback
+
+**Token Usage**: {input_token} → {output_token}
+"""
+    
+    return (
+        f"✅ HTML updated, please refresh the preview page\n\nTokens: {input_token} → {output_token}",
+        preview_info,              # preview_info_display
+        "",  # Clear input box
+        gr.update(visible=True),   # feedback_html keep visible
+        gr.update(visible=True),   # open_preview_btn keep visible
+        None  # html_file_output no download yet
+    )
+
+def finalize_generation():
+    """Complete generation and save final results"""
+    import time
+    
+    # Ensure final HTML is saved
+    html_dir_path = os.path.dirname(state.html_file_path)
+    
+    # Save final version
+    final_html_path = os.path.join(html_dir_path, 'index_final.html')
+    with open(final_html_path, 'w', encoding='utf-8') as file:
+        file.write(state.html_content)
+    
+    # Also update main file
+    with open(state.html_file_path, 'w', encoding='utf-8') as file:
+        file.write(state.html_content)
+    
+    # Save metadata
+    metadata = state.html_generator.generate_metadata(state.generated_content, state.args)
+    metadata_path = state.html_generator.save_metadata(metadata, state.args, state.args.output_dir)
+    
+    # Create README file
+    readme_path = os.path.join(state.args.output_dir, state.args.paper_name, 'README.md')
+    readme_content = f"""# {state.args.paper_name} - Project Page
+
+## 📄 Project Information
+
+- **Paper Name**: {state.args.paper_name}
+- **Generation Time**: {time.strftime('%Y-%m-%d %H:%M:%S')}
+- **Text Model**: {state.args.model_name_t}
+- **Vision Model**: {state.args.model_name_v}
+
+## 🚀 Usage
+
+1. Extract this archive to any directory
+2. Open `index.html` to view the project page
+3. All resources (CSS, images, etc.) are included
+
+## 📁 File Structure
+
+- `index.html` - Main page file
+- `index_final.html` - Final confirmed version
+- `assets/` - Image and table resources
+- `css/` or `styles/` - Style files
+- `js/` or `scripts/` - JavaScript files
+- `metadata.json` - Page metadata
+- `generation_log.json` - Generation log
+
+## 💡 Tips
+
+- Recommended browsers: Chrome, Firefox, Safari, Edge
+- For web deployment, simply upload the entire folder
+- Feel free to modify HTML and CSS for customization
+
+---
+Generated by Paper2ProjectPage
+"""
+    
+    with open(readme_path, 'w', encoding='utf-8') as f:
+        f.write(readme_content)
+    
+    # Save generation log
+    log_data = {
+        'paper_name': state.args.paper_name,
+        'paper_path': state.args.paper_path,
+        'models': {
+            'text_model': state.args.model_name_t,
+            'vision_model': state.args.model_name_v
+        },
+        'token_usage': {
+            'text_input_tokens': state.total_input_tokens_t,
+            'text_output_tokens': state.total_output_tokens_t
+        },
+        'output_files': {
+            'html_file': state.html_file_path,
+            'final_html_file': final_html_path,
+            'metadata_file': metadata_path,
+            'readme_file': readme_path
+        },
+        'timestamp': time.strftime('%Y-%m-%d %H:%M:%S')
+    }
+    
+    log_path = f"{state.args.output_dir}/{state.args.paper_name}/generation_log.json"
+    with open(log_path, 'w') as f:
+        json.dump(log_data, f, indent=4, ensure_ascii=False)
+    
+    # Create project archive
+    project_dir = os.path.join(state.args.output_dir, state.args.paper_name)
+    zip_path = create_project_zip(project_dir, state.args.output_dir, state.args.paper_name)
+    
+    if zip_path and os.path.exists(zip_path):
+        # Get archive size
+        zip_size = os.path.getsize(zip_path)
+        zip_size_mb = zip_size / (1024 * 1024)
+        zip_filename = os.path.basename(zip_path)
+        
+        success_msg = f"""
+✅ Project page generation completed!
+
+📁 Output directory: {state.args.output_dir}/{state.args.paper_name}
+🌐 HTML file: {state.html_file_path}
+🌐 Final version: {final_html_path}
+📋 Metadata: {metadata_path}
+📖 README: {readme_path}
+📊 Log file: {log_path}
+📦 Archive: {zip_filename} ({zip_size_mb:.2f} MB)
+🔢 Total token usage: {state.total_input_tokens_t} → {state.total_output_tokens_t}
+
+🎉 All feedback completed, page successfully generated!
+Click the button below to download the complete project archive (including HTML, CSS, images, README, and all resources).
+"""
+        
+        return (
+            success_msg,
+            zip_path  # Return archive for download
+        )
+        
+    else:
+        error_msg = f"""
+⚠️ Project page generated, but archive creation failed!
+
+📁 Output directory: {state.args.output_dir}/{state.args.paper_name}
+🌐 HTML file: {state.html_file_path}
+📋 Metadata: {metadata_path}
+
+You can manually retrieve all files from the output directory {project_dir}.
+"""
+        return (
+            error_msg,
+            state.html_file_path  # Return HTML file
+        )
+
+# ==================== Gradio Interface ====================
+
+# Custom CSS for better English font rendering
+custom_css = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
+* {
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif !important;
+}
+
+code, pre, .code {
+    font-family: 'JetBrains Mono', 'Courier New', Consolas, Monaco, monospace !important;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-weight: 600 !important;
+    letter-spacing: -0.02em !important;
+}
+
+.markdown-text {
+    line-height: 1.7 !important;
+    font-size: 15px !important;
+}
+
+.gr-button {
+    font-weight: 500 !important;
+    letter-spacing: 0.01em !important;
+}
+
+.gr-input, .gr-textarea {
+    font-size: 14px !important;
+    line-height: 1.6 !important;
+}
+
+.gr-box {
+    border-radius: 8px !important;
+}
+
+/* Better spacing for English content */
+.gr-markdown p {
+    margin-bottom: 0.8em !important;
+}
+
+.gr-markdown ul, .gr-markdown ol {
+    margin-left: 1.2em !important;
+}
+
+.gr-markdown li {
+    margin-bottom: 0.4em !important;
+}
+"""
+
+with gr.Blocks(title="Paper2ProjectPage Generator", theme=gr.themes.Soft(), css=custom_css) as demo:
+    
+    gr.Markdown("""
+    # 📄 AutoPage Generator with Interactive Feedback
+    
+    Upload your research paper PDF and generate beautiful project pages through multi-round interactive feedback
+    """)
+    
+    with gr.Row():
+        with gr.Column(scale=1):
+            # PDF Upload
+            pdf_input = gr.File(
+                label="📎 Upload PDF Paper",
+                file_types=[".pdf"],
+                type="filepath"
+            )
+            
+            gr.Markdown("### 🔑 API Keys Configuration")
+            gr.Markdown("""
+            **⚠️ Security Notice**: Your API keys are only stored in memory during the session and are never saved to disk.
+            
+            **📋 How to get API keys:**
+            - **OpenAI**: Get your API key from [OpenAI Platform](https://platform.openai.com/api-keys)
+            - **Gemini**: Get your API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
+            - **Qwen**: Get your API key from [DashScope](https://dashscope.console.aliyun.com/apiKey)
+            - **ZhipuAI**: Get your API key from [ZhipuAI Console](https://open.bigmodel.cn/usercenter/apikeys)
+            - **OpenRouter**: Get your API key from [OpenRouter](https://openrouter.ai/keys)
+            
+            **🚀 For HuggingFace Spaces**: You can also set these as environment variables in your Space settings.
+            """)
+            
+            with gr.Row():
+                openai_api_key = gr.Textbox(
+                    label="OpenAI API Key",
+                    value=os.getenv("OPENAI_API_KEY", ""),
+                    type="password",
+                    placeholder="sk-...",
+                    info="Required for GPT models"
+                )
+                gemini_api_key = gr.Textbox(
+                    label="Gemini API Key", 
+                    value=os.getenv("GEMINI_API_KEY", ""),
+                    type="password",
+                    placeholder="AI...",
+                    info="Required for Gemini models"
+                )
+            
+            with gr.Row():
+                qwen_api_key = gr.Textbox(
+                    label="Qwen API Key",
+                    value=os.getenv("QWEN_API_KEY", ""),
+                    type="password", 
+                    placeholder="sk-...",
+                    info="Required for Qwen models"
+                )
+                zhipuai_api_key = gr.Textbox(
+                    label="ZhipuAI API Key",
+                    value=os.getenv("ZHIPUAI_API_KEY", ""),
+                    type="password",
+                    placeholder="...",
+                    info="Required for GLM models"
+                )
+            
+            openrouter_api_key = gr.Textbox(
+                label="OpenRouter API Key",
+                value=os.getenv("OPENROUTER_API_KEY", ""),
+                type="password",
+                placeholder="sk-or-...",
+                info="Required for OpenRouter models"
+            )
+            
+            gr.Markdown("### 🤖 Model Configuration")
+            
+            # Text Model Options
+            text_model_options = [
+                ("GPT-4o", "4o"),
+                ("GPT-4o Mini", "4o-mini"),
+                ("GPT-4.1", "gpt-4.1"),
+                ("GPT-4.1 Mini", "gpt-4.1-mini"),
+                ("O1", "o1"),
+                ("O3", "o3"),
+                ("O3 Mini", "o3-mini"),
+                ("Gemini 2.5 Pro", "gemini"),
+                ("Gemini 2.5 Pro (Alt)", "gemini-2.5-pro"),
+                ("Gemini 2.5 Flash", "gemini-2.5-flash"),
+                ("Qwen", "qwen"),
+                ("Qwen Plus", "qwen-plus"),
+                ("Qwen Max", "qwen-max"),
+                ("Qwen Long", "qwen-long"),
+                ("OpenRouter Qwen Plus", "openrouter_qwen-plus"),
+                ("OpenRouter GPT-4o Mini", "openrouter_gpt-4o-mini"),
+                ("OpenRouter Gemini 2.5 Flash", "openrouter_gemini-2.5-flash"),
+                ("OpenRouter O3", "openrouter_openai/o3"),
+                ("OpenRouter Claude Sonnet 4.5", "openrouter_claude-sonnet-4.5"),
+            ]
+            
+            # Vision Model Options
+            vision_model_options = [
+                ("GPT-4o", "4o"),
+                ("GPT-4o Mini", "4o-mini"),
+                ("Gemini 2.5 Pro", "gemini"),
+                ("Gemini 2.5 Pro (Alt)", "gemini-2.5-pro"),
+                ("Gemini 2.5 Flash", "gemini-2.5-flash"),
+                ("Qwen VL Max", "qwen-vl-max"),
+                ("Qwen 2.5 VL 72B", "qwen-2.5-vl-72b"),
+                ("OpenRouter Qwen VL 72B", "openrouter_qwen_vl_72b"),
+                ("OpenRouter Qwen VL 7B", "openrouter_qwen_vl_7b"),
+                ("OpenRouter Qwen VL Max", "openrouter_qwen-vl-max"),
+                ("OpenRouter Gemini 2.5 Flash", "openrouter_gemini-2.5-flash"),
+            ]
+            
+            with gr.Row():
+                model_name_t = gr.Dropdown(
+                    label="Text Model",
+                    choices=text_model_options,
+                    value="gemini",
+                    info="Select model for text processing"
+                )
+                model_name_v = gr.Dropdown(
+                    label="Vision Model", 
+                    choices=vision_model_options,
+                    value="gemini",
+                    info="Select model for vision processing"
+                )
+            
+            gr.Markdown("### 📁 Path Configuration")
+            template_root = gr.Textbox(
+                label="Template Root",
+                value="templates",
+                info="Root directory for templates"
+            )
+            template_dir = gr.Textbox(
+                label="Template Directory",
+                value="",
+                info="Selected template directory (optional)"
+            )
+            template_file = gr.Textbox(
+                label="Template File",
+                value="",
+                info="Specific template file path (optional)"
+            )
+            template_choice = gr.Radio(
+                label="Recommended Templates",
+                choices=[],
+                value=None,
+                info="Select from recommended templates",
+                visible=True
+            )
+            output_dir = gr.Textbox(
+                label="Output Directory",
+                value="generated_project_pages",
+                info="Directory for output files"
+            )
+            style_preference = gr.Textbox(
+                label="Style Preference JSON",
+                value="",
+                info="Style preference JSON file path (optional)"
+            )
+            tmp_dir = gr.Textbox(
+                label="Temporary Directory",
+                value="tmp",
+                info="Directory for temporary files"
+            )
+
+            template_preview_links = gr.Markdown(
+                label="Template Preview Links",
+                value="",
+                visible=False
+            )
+            
+            # ===== Hidden parameters with default values =====
+            resume = gr.Radio(
+                label="Resume From Step",
+                choices=['parse_pdf', 'generate_content','full_content_check', 'generate_html', 'html_check','modify_table','html_feedback'],
+                value='parse_pdf',
+                visible=False
+            )
+
+            human_input = gr.Radio(
+                label="Enable Human Feedback",
+                choices=[0, 1],
+                value=1,
+                visible=False
+            )
+            
+        with gr.Column(scale=1):
+            gr.Markdown("### 🎨 Style Configuration")
+            
+            background_color = gr.Radio(
+                label="Background Color",
+                choices=["light", "dark"],
+                value="light",
+                info="Background color theme"
+            )
+            
+            has_navigation = gr.Radio(
+                label="Has Navigation",
+                choices=["yes", "no"],
+                value="yes",
+                info="Include navigation bar"
+            )
+            
+            has_hero_section = gr.Radio(
+                label="Has Hero Section",
+                choices=["yes", "no"],
+                value="yes",
+                info="Include hero/header section"
+            )
+            
+            title_color = gr.Radio(
+                label="Title Color",
+                choices=["pure", "colorful"],
+                value="pure",
+                info="Title color style"
+            )
+            
+            page_density = gr.Radio(
+                label="Page Density",
+                choices=["spacious", "compact"],
+                value="spacious",
+                info="Page spacing density"
+            )
+            
+            image_layout = gr.Radio(
+                label="Image Layout",
+                choices=["rotation", "parallelism"],
+                value="parallelism",
+                info="Image layout style"
+            )
+            
+            gr.Markdown("### ⚙️ Advanced Options")
+            
+            full_content_check_times = gr.Number(
+                label="Full Content Check Times",
+                value=1,
+                precision=0,
+                info="Number of full content validation checks"
+            )
+            
+            html_check_times = gr.Number(
+                label="HTML Check Times",
+                value=1,
+                precision=0,
+                info="Number of HTML validation checks"
+            )
+    
+    # Start Generation Button
+    start_btn = gr.Button("🚀 Start Generation", variant="primary", size="lg")
+    
+    # Status Output
+    status_output = gr.Textbox(
+        label="📊 Generation Status",
+        lines=5,
+        interactive=False
+    )
+    
+    # Section Feedback Area
+    with gr.Group(visible=False) as feedback_section:
+        gr.Markdown("### 📝 Section Generation Results")
+        gr.Markdown("Please review the generated section structure. If satisfied, enter **'yes'**, otherwise provide modification feedback:")
+        
+        with gr.Tabs():
+            with gr.Tab("📖 Preview (Markdown)"):
+                section_display_md = gr.Markdown(
+                    label="Section Preview",
+                    value=""
+                )
+            with gr.Tab("📋 Raw Data (JSON)"):
+                section_display_json = gr.Code(
+                    label="Section JSON",
+                    language="json",
+                    value="",
+                    lines=15
+                )
+        
+        section_feedback_input = gr.TextArea(
+            label="Your Feedback",
+            placeholder="Enter 'yes' to continue, or provide modification feedback...",
+            lines=3
+        )
+        section_submit_btn = gr.Button("Submit Feedback", variant="primary")
+    
+    # Full Content Feedback Area
+    with gr.Group(visible=False) as feedback_full_content:
+        gr.Markdown("### 📄 Full Content Generation Results")
+        gr.Markdown("Please review the generated full content. If satisfied, enter **'yes'**, otherwise provide modification feedback:")
+        
+        with gr.Tabs():
+            with gr.Tab("📖 Preview (Markdown)"):
+                full_content_display_md = gr.Markdown(
+                    label="Full Content Preview",
+                    value=""
+                )
+            with gr.Tab("📋 Raw Data (JSON)"):
+                full_content_display_json = gr.Code(
+                    label="Full Content JSON",
+                    language="json",
+                    value="",
+                    lines=15
+                )
+        
+        full_content_feedback_input = gr.TextArea(
+            label="Your Feedback",
+            placeholder="Enter 'yes' to continue, or provide modification feedback...",
+            lines=3
+        )
+        full_content_submit_btn = gr.Button("Submit Feedback", variant="primary")
+    
+    # HTML Feedback Area
+    with gr.Group(visible=False) as feedback_html:
+        gr.Markdown("### 🌐 HTML Generation Results")
+        
+        # Preview Info Display
+        preview_info_display = gr.Markdown(
+            value="",
+            label="Preview Information"
+        )
+        
+        # Preview URL (hidden state for JS)
+        preview_url_state = gr.Textbox(visible=False)
+        
+        # Open Preview in New Tab Button
+        open_preview_btn = gr.Button(
+            "🌐 Open Preview in New Tab",
+            variant="secondary",
+            size="lg",
+            visible=False
+        )
+        
+        gr.Markdown("---")
+        
+        # Feedback Input Area
+        html_feedback_input = gr.TextArea(
+            label="Your Feedback",
+            placeholder="Enter 'yes' to finalize, or provide modification feedback...",
+            lines=3
+        )
+        html_submit_btn = gr.Button("Submit Feedback", variant="primary")
+    
+    # Final Output
+    html_file_output = gr.File(
+        label="📥 Download Project Archive",
+        interactive=False
+    )
+    
+    gr.Markdown("""
+    ---
+    ### 💡 User Guide
+    
+    1. **Upload PDF**: Select your research paper PDF file
+    2. **Configure Parameters**: Adjust model, path, and style settings as needed
+    3. **Start Generation**: Click the "Start Generation" button
+    4. **Three-Stage Feedback**:
+       - 📝 **Section Feedback**: Review the generated page structure (Markdown preview + JSON data), provide feedback or enter 'yes' to continue
+       - 📄 **Full Content Feedback**: Review the generated complete content (Markdown preview + JSON data), provide feedback or enter 'yes' to continue
+       - 🌐 **HTML Feedback**: View the generated webpage in a new tab, provide feedback or enter 'yes' to finalize
+    5. **Download Results**: Download the complete project archive after completion
+    
+    ⚠️ **Tips**: 
+    - Each stage supports multiple rounds of feedback until you're satisfied
+    - Section and Full Content stages offer **Markdown preview** and **JSON raw data** viewing options
+    - Markdown preview is more visually appealing, JSON data shows complete structure
+    - HTML stage requires clicking "Open Preview in New Tab" to view the full page in browser
+    - Enter 'yes' to indicate satisfaction and proceed to the next stage
+    - The final ZIP download includes the complete project folder with all resources
+    """)
+    
+    # Bind Events
+    start_btn.click(
+        fn=start_generation,
+        inputs=[
+            pdf_input, model_name_t, model_name_v, template_root,
+            template_dir, template_file, output_dir, style_preference,
+            tmp_dir, full_content_check_times, background_color,
+            has_navigation, has_hero_section, title_color, page_density,
+            image_layout, html_check_times, resume, human_input,
+            template_choice, openai_api_key, gemini_api_key, 
+            qwen_api_key, zhipuai_api_key, openrouter_api_key
+        ],
+        outputs=[
+            status_output,
+            feedback_section,
+            section_display_md,
+            section_display_json,
+            template_choice,
+            template_preview_links,
+            section_feedback_input
+        ]
+    )
+    
+    section_submit_btn.click(
+        fn=submit_section_feedback,
+        inputs=[section_feedback_input],
+        outputs=[
+            status_output,
+            section_display_md,
+            section_display_json,
+            section_feedback_input,
+            feedback_section,
+            feedback_full_content,
+            full_content_display_md,
+            full_content_display_md,
+            full_content_display_json,
+            full_content_feedback_input
+        ]
+    )
+    
+    full_content_submit_btn.click(
+        fn=submit_full_content_feedback,
+        inputs=[full_content_feedback_input],
+        outputs=[
+            status_output,
+            full_content_display_md,
+            full_content_display_json,
+            full_content_feedback_input,
+            feedback_full_content,
+            feedback_html,
+            preview_info_display,
+            preview_url_state,
+            open_preview_btn
+        ]
+    )
+    
+    html_submit_btn.click(
+        fn=submit_html_feedback,
+        inputs=[html_feedback_input],
+        outputs=[
+            status_output,
+            preview_info_display,
+            html_feedback_input,
+            feedback_html,
+            open_preview_btn,
+            html_file_output
+        ]
+    )
+    
+    # Open Preview Button - Use JavaScript to open in new tab
+    open_preview_btn.click(
+        fn=None,
+        inputs=[preview_url_state],
+        outputs=None,
+        js="(url) => window.open(url, '_blank')"
+    )
+
+# Launch Application
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )

camel/__init__.py

@@ -0,0 +1,25 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from camel.logger import disable_logging, enable_logging, set_log_level
+
+__version__ = '0.2.19'
+
+__all__ = [
+    '__version__',
+    'camel',
+    'disable_logging',
+    'enable_logging',
+    'set_log_level',
+]

camel/agents/__init__.py

@@ -0,0 +1,44 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from .base import BaseAgent
+from .chat_agent import ChatAgent
+from .critic_agent import CriticAgent
+from .embodied_agent import EmbodiedAgent
+from .knowledge_graph_agent import KnowledgeGraphAgent
+from .role_assignment_agent import RoleAssignmentAgent
+from .search_agent import SearchAgent
+from .task_agent import (
+    TaskCreationAgent,
+    TaskPlannerAgent,
+    TaskPrioritizationAgent,
+    TaskSpecifyAgent,
+)
+from .tool_agents.base import BaseToolAgent
+from .tool_agents.hugging_face_tool_agent import HuggingFaceToolAgent
+
+__all__ = [
+    'BaseAgent',
+    'ChatAgent',
+    'TaskSpecifyAgent',
+    'TaskPlannerAgent',
+    'TaskCreationAgent',
+    'TaskPrioritizationAgent',
+    'CriticAgent',
+    'BaseToolAgent',
+    'HuggingFaceToolAgent',
+    'EmbodiedAgent',
+    'RoleAssignmentAgent',
+    'SearchAgent',
+    'KnowledgeGraphAgent',
+]

camel/agents/base.py

@@ -0,0 +1,29 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseAgent(ABC):
+    r"""An abstract base class for all CAMEL agents."""
+
+    @abstractmethod
+    def reset(self, *args: Any, **kwargs: Any) -> Any:
+        r"""Resets the agent to its initial state."""
+        pass
+
+    @abstractmethod
+    def step(self, *args: Any, **kwargs: Any) -> Any:
+        r"""Performs a single step of the agent."""
+        pass

camel/agents/chat_agent.py

@@ -0,0 +1,1539 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from __future__ import annotations
+
+import json
+import logging
+import re
+import uuid
+from collections import defaultdict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
+
+from openai.types.chat import ChatCompletionMessageToolCall
+from openai.types.chat.chat_completion_message_tool_call import Function
+from pydantic import BaseModel, ValidationError
+
+from camel.agents.base import BaseAgent
+from camel.memories import (
+    AgentMemory,
+    ChatHistoryMemory,
+    MemoryRecord,
+    ScoreBasedContextCreator,
+)
+from camel.messages import BaseMessage, FunctionCallingMessage, OpenAIMessage
+from camel.models import (
+    BaseModelBackend,
+    ModelFactory,
+    ModelManager,
+    ModelProcessingError,
+)
+from camel.responses import ChatAgentResponse
+from camel.types import (
+    ChatCompletion,
+    ChatCompletionChunk,
+    ModelPlatformType,
+    ModelType,
+    OpenAIBackendRole,
+    RoleType,
+)
+from camel.utils import (
+    func_string_to_callable,
+    generate_prompt_for_structured_output,
+    get_model_encoding,
+    get_pydantic_object_schema,
+    json_to_function_code,
+)
+
+if TYPE_CHECKING:
+    from openai import Stream
+
+    from camel.terminators import ResponseTerminator
+    from camel.toolkits import FunctionTool
+
+
+logger = logging.getLogger(__name__)
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+class FunctionCallingRecord(BaseModel):
+    r"""Historical records of functions called in the conversation.
+
+    Attributes:
+        func_name (str): The name of the function being called.
+        args (Dict[str, Any]): The dictionary of arguments passed to
+            the function.
+        result (Any): The execution result of calling this function.
+        tool_call_id (str): The ID of the tool call, if available.
+    """
+
+    func_name: str
+    args: Dict[str, Any]
+    result: Any
+    tool_call_id: str
+
+    def __str__(self) -> str:
+        r"""Overridden version of the string function.
+
+        Returns:
+            str: Modified string to represent the function calling.
+        """
+        return (
+            f"Function Execution: {self.func_name}\n"
+            f"\tArgs: {self.args}\n"
+            f"\tResult: {self.result}\n"
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        r"""Returns the function calling record as a dictionary.
+
+        Returns:
+            dict[str, Any]: The function calling record as a dictionary.
+        """
+        return self.model_dump()
+
+
+@track_agent(name="ChatAgent")
+class ChatAgent(BaseAgent):
+    r"""Class for managing conversations of CAMEL Chat Agents.
+
+    Args:
+        system_message (Union[BaseMessage, str], optional): The system message
+            for the chat agent.
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`ModelPlatformType.DEFAULT`
+            with `ModelType.DEFAULT`)
+        memory (AgentMemory, optional): The agent memory for managing chat
+            messages. If `None`, a :obj:`ChatHistoryMemory` will be used.
+            (default: :obj:`None`)
+        message_window_size (int, optional): The maximum number of previous
+            messages to include in the context window. If `None`, no windowing
+            is performed. (default: :obj:`None`)
+        token_limit (int, optional): The maximum number of tokens in a context.
+            The context will be automatically pruned to fulfill the limitation.
+            If `None`, it will be set according to the backend model.
+            (default: :obj:`None`)
+        output_language (str, optional): The language to be output by the
+            agent. (default: :obj:`None`)
+        tools (Optional[List[Union[FunctionTool, Callable]]], optional): List
+            of available :obj:`FunctionTool` or :obj:`Callable`. (default:
+            :obj:`None`)
+        external_tools (Optional[List[Union[FunctionTool, Callable]]],
+            optional): List of external tools (:obj:`FunctionTool` or or
+            :obj:`Callable`) bind to one chat agent. When these tools are
+            called, the agent will directly return the request instead of
+            processing it. (default: :obj:`None`)
+        response_terminators (List[ResponseTerminator], optional): List of
+            :obj:`ResponseTerminator` bind to one chat agent.
+            (default: :obj:`None`)
+        scheduling_strategy (str): name of function that defines how to select
+            the next model in ModelManager. (default: :str:`round_robin`)
+        single_iteration (bool): Whether to let the agent perform only one
+            model calling at each step. (default: :obj:`False`)
+    """
+
+    def __init__(
+        self,
+        system_message: Optional[Union[BaseMessage, str]] = None,
+        model: Optional[
+            Union[BaseModelBackend, List[BaseModelBackend]]
+        ] = None,
+        memory: Optional[AgentMemory] = None,
+        message_window_size: Optional[int] = None,
+        token_limit: Optional[int] = None,
+        output_language: Optional[str] = None,
+        tools: Optional[List[Union[FunctionTool, Callable]]] = None,
+        external_tools: Optional[List[Union[FunctionTool, Callable]]] = None,
+        response_terminators: Optional[List[ResponseTerminator]] = None,
+        scheduling_strategy: str = "round_robin",
+        single_iteration: bool = False,
+    ) -> None:
+        # Initialize the system message, converting string to BaseMessage if needed
+        if isinstance(system_message, str):
+            system_message = BaseMessage.make_assistant_message(
+                role_name='Assistant', content=system_message
+            )
+
+        self.orig_sys_message: Optional[BaseMessage] = system_message
+        self._system_message: Optional[BaseMessage] = system_message
+        self.role_name: str = (
+            getattr(system_message, 'role_name', None) or "assistant"
+        )
+        self.role_type: RoleType = (
+            getattr(system_message, 'role_type', None) or RoleType.ASSISTANT
+        )
+        self.model_backend = ModelManager(
+            model
+            if model is not None
+            else ModelFactory.create(
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
+            ),
+            scheduling_strategy=scheduling_strategy,
+        )
+        self.model_type = self.model_backend.model_type
+
+        # Initialize tools
+        self.tools: List[FunctionTool] = (
+            self._initialize_tools(tools) if tools else []
+        )
+        self.external_tools: List[FunctionTool] = (
+            self._initialize_tools(external_tools) if external_tools else []
+        )
+        self.external_tool_names: List[str] = [
+            tool.get_function_name() for tool in self.external_tools
+        ]
+        self.all_tools = self.tools + self.external_tools or []
+
+        # Create tool dictionaries and configure backend tools if necessary
+        self.tool_dict = {
+            tool.get_function_name(): tool for tool in self.all_tools
+        }
+
+        # If the user set tools from `ChatAgent`, it will override the
+        # configured tools in `BaseModelBackend`.
+        if self.all_tools:
+            logger.warning(
+                "Overriding the configured tools in `BaseModelBackend` with the tools from `ChatAgent`."
+            )
+            tool_schema_list = [
+                tool.get_openai_tool_schema() for tool in self.all_tools
+            ]
+            self.model_backend.model_config_dict['tools'] = tool_schema_list
+
+        self.model_token_limit = token_limit or self.model_backend.token_limit
+        context_creator = ScoreBasedContextCreator(
+            self.model_backend.token_counter,
+            self.model_token_limit,
+        )
+        self.memory: AgentMemory = memory or ChatHistoryMemory(
+            context_creator, window_size=message_window_size
+        )
+
+        self.output_language: Optional[str] = output_language
+        if self.output_language is not None:
+            self.set_output_language(self.output_language)
+
+        self.terminated: bool = False
+        self.response_terminators = response_terminators or []
+        self.init_messages()
+        self.tool_prompt_added = False
+        self.single_iteration = single_iteration
+
+    def _initialize_tools(
+        self, tools: List[Union[FunctionTool, Callable]]
+    ) -> List[FunctionTool]:
+        r"""Helper method to initialize tools as FunctionTool instances."""
+        from camel.toolkits import FunctionTool
+
+        func_tools = []
+        for tool in tools:
+            if not isinstance(tool, FunctionTool):
+                tool = FunctionTool(tool)
+            func_tools.append(tool)
+        return func_tools
+
+    def add_tool(
+        self, tool: Union[FunctionTool, Callable], is_external: bool = False
+    ) -> None:
+        r"""Add a tool to the agent, specifying if it's an external tool."""
+        # Initialize the tool
+        initialized_tool = self._initialize_tools([tool])
+
+        # Update tools or external tools based on is_external flag
+        if is_external:
+            self.external_tools = self.external_tools + initialized_tool
+            self.external_tool_names.extend(
+                tool.get_function_name() for tool in initialized_tool
+            )
+        else:
+            self.tools = self.tools + initialized_tool
+
+        # Rebuild all_tools, and tool_dict
+        self.all_tools = self.tools + self.external_tools
+        self.tool_dict = {
+            tool.get_function_name(): tool for tool in self.all_tools
+        }
+
+        tool_schema_list = [
+            tool.get_openai_tool_schema() for tool in self.all_tools
+        ]
+        self.model_backend.model_config_dict['tools'] = tool_schema_list
+
+    def remove_tool(self, tool_name: str, is_external: bool = False) -> bool:
+        r"""Remove a tool by name, specifying if it's an external tool."""
+        tool_list = self.external_tools if is_external else self.tools
+        if not tool_list:
+            return False
+
+        for tool in tool_list:
+            if tool.get_function_name() == tool_name:
+                tool_list.remove(tool)
+                if is_external:
+                    self.external_tool_names.remove(tool_name)
+                # Reinitialize the tool dictionary
+                self.all_tools = (self.tools or []) + (
+                    self.external_tools or []
+                )
+                self.tool_dict = {
+                    tool.get_function_name(): tool for tool in self.all_tools
+                }
+                tool_schema_list = [
+                    tool.get_openai_tool_schema() for tool in self.all_tools
+                ]
+                self.model_backend.model_config_dict['tools'] = (
+                    tool_schema_list
+                )
+                return True
+        return False
+
+    def list_tools(self) -> dict:
+        r"""List all tools, separated into normal and external tools."""
+        normal_tools = [
+            tool.get_function_name() for tool in (self.tools or [])
+        ]
+        external_tools = [
+            tool.get_function_name() for tool in (self.external_tools or [])
+        ]
+
+        return {"normal_tools": normal_tools, "external_tools": external_tools}
+
+    # ruff: noqa: E501
+    def _generate_tool_prompt(self, tool_schema_list: List[Dict]) -> str:
+        r"""Generates a tool prompt based on the provided tool schema list.
+
+        Args:
+            tool_schema_list (List[Dict]): A list of dictionaries, each
+                containing a tool schema.
+
+        Returns:
+            str: A string representing the tool prompt.
+        """
+        tool_prompts = []
+
+        for tool in tool_schema_list:
+            tool_info = tool['function']
+            tool_name = tool_info['name']
+            tool_description = tool_info['description']
+            tool_json = json.dumps(tool_info, indent=4)
+
+            prompt = f"Use the function '{tool_name}' to '{tool_description}':\n{tool_json}\n"
+            tool_prompts.append(prompt)
+
+        tool_prompt_str = "\n".join(tool_prompts)
+
+        final_prompt = f"""
+    You have access to the following functions:
+
+    {tool_prompt_str}
+
+    If you choose to call a function ONLY reply in the following format with no
+    prefix or suffix:
+
+    <function=example_function_name>{{"example_name": "example_value"}}</function>
+
+    Reminder:
+    - Function calls MUST follow the specified format, start with <function= and end with </function>
+    - Required parameters MUST be specified
+    - Only call one function at a time
+    - Put the entire function call reply on one line
+    - If there is no function call available, answer the question like normal 
+      with your current knowledge and do not tell the user about function calls
+    """
+        return final_prompt
+
+    def _parse_tool_response(self, response: str):
+        r"""Parses the tool response to extract the function name and
+        arguments.
+
+        Args:
+            response (str): The response from the model containing the
+                function call.
+
+        Returns:
+            Optional[Dict[str, Any]]: The parsed function name and arguments
+                if found, otherwise :obj:`None`.
+        """
+        function_regex = r"<function=(\w+)>(.*?)</function>"
+        match = re.search(function_regex, response)
+
+        if match:
+            function_name, args_string = match.groups()
+            try:
+                args = json.loads(args_string)
+                return {"function": function_name, "arguments": args}
+            except json.JSONDecodeError as error:
+                logger.error(f"Error parsing function arguments: {error}")
+                return None
+        return None
+
+    def reset(self):
+        r"""Resets the :obj:`ChatAgent` to its initial state."""
+        self.terminated = False
+        self.init_messages()
+        for terminator in self.response_terminators:
+            terminator.reset()
+
+    @property
+    def system_message(self) -> Optional[BaseMessage]:
+        r"""The getter method for the property :obj:`system_message`.
+
+        Returns:
+            Optional[BaseMessage]: The system message of this agent if set,
+                else :obj:`None`.
+        """
+        return self._system_message
+
+    @system_message.setter
+    def system_message(self, message: BaseMessage) -> None:
+        r"""The setter method for the property :obj:`system_message`.
+
+        Args:
+            message (BaseMessage): The message to be set as the
+                new system message of this agent.
+        """
+        self._system_message = message
+
+    def is_tools_added(self) -> bool:
+        r"""Whether tool calling is enabled for this agent.
+
+        Returns:
+            bool: Whether tool calling is enabled for this agent, determined
+                by whether the dictionary of tools is empty.
+        """
+        return len(self.tool_dict) > 0
+
+    def update_memory(
+        self, message: BaseMessage, role: OpenAIBackendRole
+    ) -> None:
+        r"""Updates the agent memory with a new message.
+
+        Args:
+            message (BaseMessage): The new message to add to the stored
+                messages.
+            role (OpenAIBackendRole): The backend role type.
+        """
+        self.memory.write_record(
+            MemoryRecord(message=message, role_at_backend=role)
+        )
+
+    def set_output_language(self, output_language: str) -> BaseMessage:
+        r"""Sets the output language for the system message. This method
+        updates the output language for the system message. The output
+        language determines the language in which the output text should be
+        generated.
+
+        Args:
+            output_language (str): The desired output language.
+
+        Returns:
+            BaseMessage: The updated system message object.
+        """
+        self.output_language = output_language
+        language_prompt = (
+            "\nRegardless of the input language, "
+            f"you must output text in {output_language}."
+        )
+        if self.orig_sys_message is not None:
+            content = self.orig_sys_message.content + language_prompt
+            self._system_message = self.orig_sys_message.create_new_instance(
+                content
+            )
+        else:
+            self._system_message = BaseMessage.make_assistant_message(
+                role_name="Assistant",
+                content=language_prompt,
+            )
+
+        system_record = MemoryRecord(
+            message=self._system_message,
+            role_at_backend=OpenAIBackendRole.SYSTEM,
+        )
+        self.memory.clear()
+        self.memory.write_record(system_record)
+        return self._system_message
+
+    def get_info(
+        self,
+        session_id: Optional[str],
+        usage: Optional[Dict[str, int]],
+        termination_reasons: List[str],
+        num_tokens: int,
+        tool_calls: List[FunctionCallingRecord],
+        external_tool_request: Optional[ChatCompletionMessageToolCall] = None,
+    ) -> Dict[str, Any]:
+        r"""Returns a dictionary containing information about the chat session.
+
+        Args:
+            session_id (str, optional): The ID of the chat session.
+            usage (Dict[str, int], optional): Information about the usage of
+                the LLM.
+            termination_reasons (List[str]): The reasons for the termination
+                of the chat session.
+            num_tokens (int): The number of tokens used in the chat session.
+            tool_calls (List[FunctionCallingRecord]): The list of function
+                calling records, containing the information of called tools.
+            external_tool_request
+                (Optional[ChatCompletionMessageToolCall], optional):
+                The tool calling request of external tools from the model.
+                These requests are directly returned to the user instead of
+                being processed by the agent automatically.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, Any]: The chat session information.
+        """
+        return {
+            "id": session_id,
+            "usage": usage,
+            "termination_reasons": termination_reasons,
+            "num_tokens": num_tokens,
+            "tool_calls": tool_calls,
+            "external_tool_request": external_tool_request,
+        }
+
+    def init_messages(self) -> None:
+        r"""Initializes the stored messages list with the current system
+        message.
+        """
+        if self._system_message is not None:
+            system_record = MemoryRecord(
+                message=self._system_message,
+                role_at_backend=OpenAIBackendRole.SYSTEM,
+            )
+            self.memory.clear()
+            self.memory.write_record(system_record)
+        else:
+            self.memory.clear()
+
+    def record_message(self, message: BaseMessage) -> None:
+        r"""Records the externally provided message into the agent memory as if
+        it were an answer of the :obj:`ChatAgent` from the backend. Currently,
+        the choice of the critic is submitted with this method.
+
+        Args:
+            message (BaseMessage): An external message to be recorded in the
+                memory.
+        """
+        self.update_memory(message, OpenAIBackendRole.ASSISTANT)
+
+    def step(
+        self,
+        input_message: Union[BaseMessage, str],
+        response_format: Optional[Type[BaseModel]] = None,
+    ) -> ChatAgentResponse:
+        r"""Executes a single step in the chat session, generating a response
+        to the input message.
+
+        Args:
+            input_message (Union[BaseMessage, str]): The input message for the
+                agent. If provided as a BaseMessage, the `role` is adjusted to
+                `user` to indicate an external message.
+            response_format (Optional[Type[BaseModel]], optional): A Pydantic
+                model defining the expected structure of the response. Used to
+                generate a structured response if provided. (default:
+                :obj:`None`)
+
+        Returns:
+            ChatAgentResponse: Contains output messages, a termination status
+                flag, and session information.
+        """
+
+        if (
+            self.model_backend.model_config_dict.get("response_format")
+            and response_format
+        ):
+            raise ValueError(
+                "The `response_format` parameter cannot be set both in "
+                "the model configuration and in the ChatAgent step."
+            )
+
+        self.original_model_dict = self.model_backend.model_config_dict
+        model_response_format_modified = False
+        if (
+            response_format
+            and self.model_type.support_native_structured_output
+        ):
+            self.model_backend.model_config_dict = (
+                self.original_model_dict.copy()
+            )
+            self.model_backend.model_config_dict["response_format"] = (
+                response_format
+            )
+            model_response_format_modified = True
+
+        # Convert input message to BaseMessage if necessary
+        if isinstance(input_message, str):
+            input_message = BaseMessage.make_user_message(
+                role_name='User', content=input_message
+            )
+
+        # Handle tool prompt injection if needed
+        if (
+            self.is_tools_added()
+            and not self.model_type.support_native_tool_calling
+            and not self.tool_prompt_added
+        ):
+            self._inject_tool_prompt()
+
+        # Add user input to memory
+        self.update_memory(input_message, OpenAIBackendRole.USER)
+
+        try:
+            return self._handle_step(response_format, self.single_iteration)
+        finally:
+            if model_response_format_modified:
+                # Reset model config back to original state
+                self.model_backend.model_config_dict = self.original_model_dict
+
+    def _inject_tool_prompt(self) -> None:
+        r"""Generate and add the tool prompt to memory."""
+        tool_prompt = self._generate_tool_prompt(
+            self.model_backend.model_config_dict["tools"]
+        )
+        tool_msg = BaseMessage.make_assistant_message(
+            role_name="Assistant", content=tool_prompt
+        )
+        self.update_memory(tool_msg, OpenAIBackendRole.SYSTEM)
+        self.tool_prompt_added = True
+
+    def _handle_step(
+        self,
+        response_format: Optional[Type[BaseModel]],
+        single_step: bool,
+    ) -> ChatAgentResponse:
+        r"""Handles a single or multi-step interaction."""
+
+        if (
+            self.model_backend.model_config_dict.get("tool_choice")
+            == "required"
+            and not single_step
+        ):
+            raise ValueError(
+                "`tool_choice` cannot be set to `required` for multi-step"
+                " mode. To proceed, set `single_iteration` to `True`."
+            )
+
+        # Record function calls made during the session
+        tool_call_records: List[FunctionCallingRecord] = []
+
+        external_tool_request = None
+
+        while True:
+            try:
+                openai_messages, num_tokens = self.memory.get_context()
+            except RuntimeError as e:
+                self.model_backend.model_config_dict = self.original_model_dict
+                return self._step_token_exceed(
+                    e.args[1], tool_call_records, "max_tokens_exceeded"
+                )
+
+            # Prompt engineering approach for structured output for non-native tool calling models
+            inject_prompt_for_structured_output = (
+                response_format
+                and not self.model_type.support_native_structured_output
+            )
+
+            if inject_prompt_for_structured_output:
+                # update last openai message
+                usr_msg = openai_messages.pop()
+                usr_msg["content"] = generate_prompt_for_structured_output(
+                    response_format,
+                    usr_msg["content"],  # type: ignore [arg-type]
+                )
+                openai_messages.append(usr_msg)
+
+            # Process model response
+            (
+                response,
+                output_messages,
+                finish_reasons,
+                usage_dict,
+                response_id,
+            ) = self._step_model_response(openai_messages, num_tokens)
+
+            # Try to parse structured output to return a Pydantic object
+            if inject_prompt_for_structured_output and isinstance(
+                response, ChatCompletion
+            ):
+                content = response.choices[0].message.content
+                try:
+                    json_content = json.loads(str(content))
+                    output_messages[0].parsed = response_format(**json_content)  # type: ignore [assignment, misc]
+                except json.JSONDecodeError as e:
+                    logger.error(
+                        f"Failed in parsing the output into JSON: {e}"
+                    )
+                    output_messages[0].parsed = None
+                except ValidationError as e:
+                    logger.warning(
+                        "Successfully generating JSON response, "
+                        "but failed in parsing it into Pydantic object :"
+                        f"{e}, return the JSON response in parsed field"
+                    )
+                    output_messages[0].parsed = json_content
+
+            # Finalize on standard response in multi-step mode
+            if self._is_standard_response(response):
+                break
+
+            # Handle tool requests
+            tool_request = self._extract_tool_call(response)
+            if isinstance(response, ChatCompletion) and tool_request:
+                response.choices[0].message.tool_calls = [tool_request]
+                tool_call_records.append(
+                    self._step_tool_call_and_update(response)
+                )
+
+                if tool_request.function.name in self.external_tool_names:
+                    external_tool_request = tool_request
+                    info = self._step_get_info(
+                        output_messages,
+                        finish_reasons,
+                        usage_dict,
+                        response_id,
+                        tool_call_records,
+                        num_tokens,
+                        tool_request,
+                    )
+                    self._log_final_output(output_messages)
+                    self.model_backend.model_config_dict = (
+                        self.original_model_dict
+                    )
+                    return ChatAgentResponse(
+                        msgs=output_messages,
+                        terminated=self.terminated,
+                        info=info,
+                    )
+
+            # Single-step mode ends after one iteration
+            if single_step:
+                break
+
+        # Optional structured output via function calling
+        if (
+            response_format
+            and not inject_prompt_for_structured_output
+            and self.model_type
+            not in {
+                "gpt-4o",
+                "gpt-4o-mini",
+            }
+        ):
+            (
+                output_messages,
+                finish_reasons,
+                usage_dict,
+                response_id,
+                tool_call,
+                num_tokens,
+            ) = self._structure_output_with_function(response_format)
+            tool_call_records.append(tool_call)
+
+        # Final info and response
+        info = self._step_get_info(
+            output_messages,
+            finish_reasons,
+            usage_dict,
+            response_id,
+            tool_call_records,
+            num_tokens,
+            external_tool_request,
+        )
+        self._log_final_output(output_messages)
+        self.model_backend.model_config_dict = self.original_model_dict
+        return ChatAgentResponse(
+            msgs=output_messages, terminated=self.terminated, info=info
+        )
+
+    def _extract_tool_call(
+        self, response: Any
+    ) -> Optional[ChatCompletionMessageToolCall]:
+        r"""Extract the tool call from the model response, if present.
+
+        Args:
+            response (Any): The model's response object.
+
+        Returns:
+            Optional[ChatCompletionMessageToolCall]: The parsed tool call if
+                present, otherwise None.
+        """
+        # Check if the response contains tool calls
+        if (
+            self.is_tools_added()
+            and not self.model_type.support_native_tool_calling
+            and "</function>" in response.choices[0].message.content
+        ):
+            parsed_content = self._parse_tool_response(
+                response.choices[0].message.content
+            )
+            if parsed_content:
+                return ChatCompletionMessageToolCall(
+                    id=str(uuid.uuid4()),
+                    function=Function(
+                        arguments=str(parsed_content["arguments"]).replace(
+                            "'", '"'
+                        ),
+                        name=str(parsed_content["function"]),
+                    ),
+                    type="function",
+                )
+        elif (
+            self.is_tools_added()
+            and self.model_type.support_native_tool_calling
+            and response.choices[0].message.tool_calls
+        ):
+            return response.choices[0].message.tool_calls[0]
+
+        # No tool call found
+        return None
+
+    def _is_standard_response(self, response: Any) -> bool:
+        r"""Determine if the provided response is a standard reply without
+        tool calls.
+
+        Args:
+            response (Any): The response object to evaluate.
+
+        Returns:
+            bool: `True` if the response is a standard reply, `False`
+                otherwise.
+        """
+        if not self.is_tools_added():
+            return True
+
+        if not isinstance(response, ChatCompletion):
+            return True
+
+        if self.model_type.support_native_tool_calling:
+            return not response.choices[0].message.tool_calls
+
+        return "</function>" not in str(
+            response.choices[0].message.content or ""
+        )
+
+    def _log_final_output(self, output_messages: List[BaseMessage]) -> None:
+        r"""Log final messages or warnings about multiple responses."""
+        if len(output_messages) == 1:
+            self.record_message(output_messages[0])
+        else:
+            logger.warning(
+                "Multiple messages returned in `step()`. Record "
+                "selected message manually using `record_message()`."
+            )
+
+    async def step_async(
+        self,
+        input_message: Union[BaseMessage, str],
+        response_format: Optional[Type[BaseModel]] = None,
+    ) -> ChatAgentResponse:
+        r"""Performs a single step in the chat session by generating a response
+        to the input message. This agent step can call async function calls.
+
+        Args:
+            input_message (Union[BaseMessage, str]): The input message to the
+                agent. For BaseMessage input, its `role` field that specifies
+                the role at backend may be either `user` or `assistant` but it
+                will be set to `user` anyway since for the self agent any
+                incoming message is external. For str input, the `role_name`
+                would be `User`.
+            response_format (Optional[Type[BaseModel]], optional): A pydantic
+                model class that includes value types and field descriptions
+                used to generate a structured response by LLM. This schema
+                helps in defining the expected output format. (default:
+                :obj:`None`)
+
+        Returns:
+            ChatAgentResponse: A struct containing the output messages,
+                a boolean indicating whether the chat session has terminated,
+                and information about the chat session.
+        """
+        if isinstance(input_message, str):
+            input_message = BaseMessage.make_user_message(
+                role_name='User', content=input_message
+            )
+
+        self.update_memory(input_message, OpenAIBackendRole.USER)
+
+        tool_call_records: List[FunctionCallingRecord] = []
+        while True:
+            try:
+                openai_messages, num_tokens = self.memory.get_context()
+            except RuntimeError as e:
+                return self._step_token_exceed(
+                    e.args[1], tool_call_records, "max_tokens_exceeded"
+                )
+
+            (
+                response,
+                output_messages,
+                finish_reasons,
+                usage_dict,
+                response_id,
+            ) = self._step_model_response(openai_messages, num_tokens)
+
+            if (
+                not self.is_tools_added()
+                or not isinstance(response, ChatCompletion)
+                or not response.choices[0].message.tool_calls
+            ):
+                break
+
+            # Check for external tool call
+            external_tool_request = response.choices[0].message.tool_calls[0]
+            if external_tool_request.function.name in self.external_tool_names:
+                # if model calls an external tool, directly return the request
+                info = self._step_get_info(
+                    output_messages,
+                    finish_reasons,
+                    usage_dict,
+                    response_id,
+                    tool_call_records,
+                    num_tokens,
+                    external_tool_request,
+                )
+                return ChatAgentResponse(
+                    msgs=output_messages, terminated=self.terminated, info=info
+                )
+
+            # Normal function calling
+            tool_call_records.append(
+                await self._step_tool_call_and_update_async(response)
+            )
+
+        if (
+            response_format is not None
+            and self.model_type.support_native_tool_calling
+        ):
+            (
+                output_messages,
+                finish_reasons,
+                usage_dict,
+                response_id,
+                tool_call_record,
+                num_tokens,
+            ) = self._structure_output_with_function(response_format)
+            tool_call_records.append(tool_call_record)
+
+        info = self._step_get_info(
+            output_messages,
+            finish_reasons,
+            usage_dict,
+            response_id,
+            tool_call_records,
+            num_tokens,
+        )
+
+        if len(output_messages) == 1:
+            # Auto record if the output result is a single message
+            self.record_message(output_messages[0])
+        else:
+            logger.warning(
+                "Multiple messages returned in `step()`, message won't be "
+                "recorded automatically. Please call `record_message()` to "
+                "record the selected message manually."
+            )
+
+        return ChatAgentResponse(
+            msgs=output_messages, terminated=self.terminated, info=info
+        )
+
+    def _step_tool_call_and_update(
+        self, response: ChatCompletion
+    ) -> FunctionCallingRecord:
+        r"""Processes a function call within the chat completion response,
+        records the function call in the provided list of tool calls and
+        updates the memory of the current agent.
+
+        Args:
+            response (ChatCompletion): The response object from the chat
+                completion.
+
+        Returns:
+            FunctionCallingRecord: The record of calling the function.
+        """
+
+        # Perform function calling
+        func_assistant_msg, func_result_msg, tool_call_record = (
+            self._step_tool_call(response)
+        )
+
+        # Update the messages
+        self.update_memory(func_assistant_msg, OpenAIBackendRole.ASSISTANT)
+        self.update_memory(func_result_msg, OpenAIBackendRole.FUNCTION)
+
+        return tool_call_record
+
+    async def _step_tool_call_and_update_async(
+        self, response: ChatCompletion
+    ) -> FunctionCallingRecord:
+        (
+            func_assistant_msg,
+            func_result_msg,
+            func_record,
+        ) = await self.step_tool_call_async(response)
+
+        self.update_memory(func_assistant_msg, OpenAIBackendRole.ASSISTANT)
+        self.update_memory(func_result_msg, OpenAIBackendRole.FUNCTION)
+
+        return func_record
+
+    def _structure_output_with_function(
+        self, response_format: Type[BaseModel]
+    ) -> Tuple[
+        List[BaseMessage],
+        List[str],
+        Dict[str, int],
+        str,
+        FunctionCallingRecord,
+        int,
+    ]:
+        r"""Internal function of structuring the output of the agent based on
+        the given output schema.
+
+        Args:
+            response_format (Type[BaseModel]): The output schema to use for
+                structuring the output.
+
+        Returns:
+            Tuple[List[BaseMessage], List[str], Dict[str, int], str,
+                FunctionCallingRecord, int]:
+                A tuple containing the output messages, finish reasons, usage
+                dictionary, response ID, function calling record, and number of
+                tokens.
+        """
+        from camel.toolkits import FunctionTool
+
+        schema_json = get_pydantic_object_schema(response_format)
+        func_str = json_to_function_code(schema_json)
+        func_callable = func_string_to_callable(func_str)
+        func = FunctionTool(func_callable)
+
+        original_model_dict = self.model_backend.model_config_dict
+
+        # Replace the original tools with the structuring function
+        self.tool_dict = {func.get_function_name(): func}
+        self.model_backend.model_config_dict = original_model_dict.copy()
+        self.model_backend.model_config_dict["tools"] = [
+            func.get_openai_tool_schema()
+        ]
+        self.model_backend.model_config_dict["tool_choice"] = "required"
+
+        openai_messages, num_tokens = self.memory.get_context()
+        (
+            response,
+            output_messages,
+            finish_reasons,
+            usage_dict,
+            response_id,
+        ) = self._step_model_response(openai_messages, num_tokens)
+
+        if isinstance(response, ChatCompletion):
+            tool_call_record = self._step_tool_call_and_update(response)
+        else:
+            raise ValueError(
+                "Structured output is not supported for stream responses."
+            )
+
+        for base_message_item in output_messages:
+            base_message_item.content = json.dumps(tool_call_record.result)
+
+        # Recover the original tools
+        self.model_backend.model_config_dict = original_model_dict
+
+        return (
+            output_messages,
+            finish_reasons,
+            usage_dict,
+            response_id,
+            tool_call_record,
+            num_tokens,
+        )
+
+    def _step_model_response(
+        self,
+        openai_messages: List[OpenAIMessage],
+        num_tokens: int,
+    ) -> tuple[
+        Union[ChatCompletion, Stream],
+        List[BaseMessage],
+        List[str],
+        Dict[str, int],
+        str,
+    ]:
+        r"""Internal function for agent step model response."""
+
+        response = None
+        # Obtain the model's response
+        for _ in range(len(self.model_backend.models)):
+            try:
+                response = self.model_backend.run(openai_messages)
+                break
+            except Exception as exc:
+                logger.error(
+                    f"An error occurred while running model "
+                    f"{self.model_backend.model_type}, "
+                    f"index: {self.model_backend.current_model_index}",
+                    exc_info=exc,
+                )
+                continue
+        if not response:
+            raise ModelProcessingError(
+                "Unable to process messages: none of the provided models "
+                "run succesfully."
+            )
+
+        logger.info(
+            f"Model {self.model_backend.model_type}, "
+            f"index {self.model_backend.current_model_index}, "
+            f"processed these messages: {openai_messages}"
+        )
+
+        if isinstance(response, ChatCompletion):
+            output_messages, finish_reasons, usage_dict, response_id = (
+                self.handle_batch_response(response)
+            )
+        else:
+            output_messages, finish_reasons, usage_dict, response_id = (
+                self.handle_stream_response(response, num_tokens)
+            )
+        return (
+            response,
+            output_messages,
+            finish_reasons,
+            usage_dict,
+            response_id,
+        )
+
+    def _step_get_info(
+        self,
+        output_messages: List[BaseMessage],
+        finish_reasons: List[str],
+        usage_dict: Dict[str, int],
+        response_id: str,
+        tool_calls: List[FunctionCallingRecord],
+        num_tokens: int,
+        external_tool_request: Optional[ChatCompletionMessageToolCall] = None,
+    ) -> Dict[str, Any]:
+        r"""Process the output of a chat step and gather information about the
+        step.
+
+        This method checks for termination conditions, updates the agent's
+        state, and collects information about the chat step, including tool
+        calls and termination reasons.
+
+        Args:
+            output_messages (List[BaseMessage]): The messages generated in
+                this step.
+            finish_reasons (List[str]): The reasons for finishing the
+                generation for each message.
+            usage_dict (Dict[str, int]): Dictionary containing token usage
+                information.
+            response_id (str): The ID of the response from the model.
+            tool_calls (List[FunctionCallingRecord]): Records of function calls
+                made during this step.
+            num_tokens (int): The number of tokens used in this step.
+            external_tool_request (Optional[ChatCompletionMessageToolCall]):
+                Any external tool request made during this step.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, Any]: A dictionary containing information about the chat
+                step, including termination status, reasons, and tool call
+                information.
+
+        Note:
+            This method iterates over all response terminators and checks if
+            any of them signal termination. If a terminator signals
+            termination, the agent's state is updated accordingly, and the
+            termination reason is recorded.
+        """
+        termination = [
+            terminator.is_terminated(output_messages)
+            for terminator in self.response_terminators
+        ]
+        # Terminate the agent if any of the terminator terminates
+        self.terminated, termination_reason = next(
+            (
+                (terminated, termination_reason)
+                for terminated, termination_reason in termination
+                if terminated
+            ),
+            (False, None),
+        )
+        # For now only retain the first termination reason
+        if self.terminated and termination_reason is not None:
+            finish_reasons = [termination_reason] * len(finish_reasons)
+
+        info = self.get_info(
+            response_id,
+            usage_dict,
+            finish_reasons,
+            num_tokens,
+            tool_calls,
+            external_tool_request,
+        )
+        return info
+
+    def handle_batch_response(
+        self, response: ChatCompletion
+    ) -> Tuple[List[BaseMessage], List[str], Dict[str, int], str]:
+        r"""Process a batch response from the model and extract the necessary
+        information.
+
+        Args:
+            response (dict): Model response.
+
+        Returns:
+            tuple: A tuple of list of output `ChatMessage`, list of
+                finish reasons, usage dictionary, and response id.
+        """
+        output_messages: List[BaseMessage] = []
+        for choice in response.choices:
+            chat_message = BaseMessage(
+                role_name=self.role_name,
+                role_type=self.role_type,
+                meta_dict=dict(),
+                content=choice.message.content or "",
+                parsed=getattr(choice.message, 'parsed', None),
+            )
+            # Process log probabilities and append to the message meta information
+            if choice.logprobs is not None:
+                tokens_logprobs = choice.logprobs.content
+
+                if tokens_logprobs is not None:
+                    # Extract and structure logprob information
+                    logprobs_info = [
+                        {
+                            "token": token_logprob.token,
+                            "logprob": token_logprob.logprob,
+                            "top_logprobs": [
+                                (top_logprob.token, top_logprob.logprob)
+                                for top_logprob in token_logprob.top_logprobs
+                            ],
+                        }
+                        for token_logprob in tokens_logprobs
+                    ]
+                # Ensure meta_dict exists before adding logprobs info
+                if chat_message.meta_dict is None:
+                    chat_message.meta_dict = {}
+                chat_message.meta_dict["logprobs_info"] = logprobs_info
+            # Append the processed chat message to output
+            output_messages.append(chat_message)
+
+        finish_reasons = [
+            str(choice.finish_reason) for choice in response.choices
+        ]
+        usage = (
+            self._safe_model_dump(response.usage)
+            if response.usage is not None
+            else {}
+        )
+        return (
+            output_messages,
+            finish_reasons,
+            usage,
+            response.id,
+        )
+
+    def _safe_model_dump(self, obj) -> dict:
+        r"""Safely dump a Pydantic model to a dictionary.
+
+        This method attempts to use the `model_dump` method if available,
+        otherwise it falls back to the `dict` method.
+
+        Args:
+            obj: The Pydantic model instance to be dumped.
+
+        Returns:
+            dict: A dictionary representation of the Pydantic model.
+        """
+        # Check if the `model_dump` method exists (Pydantic v2)
+        if hasattr(obj, 'model_dump'):
+            return obj.model_dump()
+        # Fallback to `dict()` method (Pydantic v1)
+        elif hasattr(obj, 'dict'):
+            return obj.dict()
+        else:
+            raise TypeError("The object is not a Pydantic model")
+
+    def handle_stream_response(
+        self,
+        response: Stream[ChatCompletionChunk],
+        prompt_tokens: int,
+    ) -> Tuple[List[BaseMessage], List[str], Dict[str, int], str]:
+        r"""Process a stream response from the model and extract the necessary
+        information.
+
+        Args:
+            response (dict): Model response.
+            prompt_tokens (int): Number of input prompt tokens.
+
+        Returns:
+            tuple: A tuple of list of output `ChatMessage`, list of
+                finish reasons, usage dictionary, and response id.
+        """
+        content_dict: defaultdict = defaultdict(lambda: "")
+        finish_reasons_dict: defaultdict = defaultdict(lambda: "")
+        output_messages: List[BaseMessage] = []
+        response_id: str = ""
+        # All choices in one response share one role
+        for chunk in response:
+            response_id = chunk.id
+            for choice in chunk.choices:
+                index = choice.index
+                delta = choice.delta
+                if delta.content is not None:
+                    # When response has not been stopped
+                    # Notice that only the first chunk_dict has the "role"
+                    content_dict[index] += delta.content
+                if choice.finish_reason:
+                    finish_reasons_dict[index] = choice.finish_reason
+                    chat_message = BaseMessage(
+                        role_name=self.role_name,
+                        role_type=self.role_type,
+                        meta_dict=dict(),
+                        content=content_dict[index],
+                    )
+                    output_messages.append(chat_message)
+        finish_reasons = [
+            finish_reasons_dict[i] for i in range(len(finish_reasons_dict))
+        ]
+        usage_dict = self.get_usage_dict(output_messages, prompt_tokens)
+        return output_messages, finish_reasons, usage_dict, response_id
+
+    def _step_token_exceed(
+        self,
+        num_tokens: int,
+        tool_calls: List[FunctionCallingRecord],
+        termination_reason: str,
+    ) -> ChatAgentResponse:
+        r"""Return trivial response containing number of tokens and information
+        of called functions when the number of tokens exceeds.
+
+        Args:
+            num_tokens (int): Number of tokens in the messages.
+            tool_calls (List[FunctionCallingRecord]): List of information
+                objects of functions called in the current step.
+            termination_reason (str): String of termination reason.
+
+        Returns:
+            ChatAgentResponse: The struct containing trivial outputs and
+                information about token number and called functions.
+        """
+        self.terminated = True
+        output_messages: List[BaseMessage] = []
+
+        info = self.get_info(
+            None,
+            None,
+            [termination_reason],
+            num_tokens,
+            tool_calls,
+        )
+
+        return ChatAgentResponse(
+            msgs=output_messages,
+            terminated=self.terminated,
+            info=info,
+        )
+
+    def _step_tool_call(
+        self,
+        response: ChatCompletion,
+    ) -> Tuple[
+        FunctionCallingMessage, FunctionCallingMessage, FunctionCallingRecord
+    ]:
+        r"""Execute the function with arguments following the model's response.
+
+        Args:
+            response (Dict[str, Any]): The response obtained by calling the
+                model.
+
+        Returns:
+            tuple: A tuple consisting of two obj:`FunctionCallingMessage`,
+                one about the arguments and the other about the execution
+                result, and a struct for logging information about this
+                function call.
+        """
+        choice = response.choices[0]
+        if choice.message.tool_calls is None:
+            raise RuntimeError("Tool call is None")
+        func_name = choice.message.tool_calls[0].function.name
+
+        arguments_str = choice.message.tool_calls[0].function.arguments
+        args = self._safe_json_loads(arguments_str)
+
+        tool = self.tool_dict[func_name]
+        result = tool(**args)
+        tool_call_id = choice.message.tool_calls[0].id
+
+        assist_msg = FunctionCallingMessage(
+            role_name=self.role_name,
+            role_type=self.role_type,
+            meta_dict=None,
+            content="",
+            func_name=func_name,
+            args=args,
+            tool_call_id=tool_call_id,
+        )
+        func_msg = FunctionCallingMessage(
+            role_name=self.role_name,
+            role_type=self.role_type,
+            meta_dict=None,
+            content="",
+            func_name=func_name,
+            result=result,
+            tool_call_id=tool_call_id,
+        )
+
+        # Record information about this function call
+        func_record = FunctionCallingRecord(
+            func_name=func_name,
+            args=args,
+            result=result,
+            tool_call_id=tool_call_id,
+        )
+        return assist_msg, func_msg, func_record
+
+    def _safe_json_loads(self, arguments_str):
+        # Replace Python types with their JSON equivalents
+        arguments_str = arguments_str.replace("None", "null")
+        arguments_str = arguments_str.replace("True", "true")
+        arguments_str = arguments_str.replace("False", "false")
+
+        # Attempt to parse the corrected string
+        try:
+            return json.loads(arguments_str)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON format: {e}")
+
+    async def step_tool_call_async(
+        self,
+        response: ChatCompletion,
+    ) -> Tuple[
+        FunctionCallingMessage, FunctionCallingMessage, FunctionCallingRecord
+    ]:
+        r"""Execute the async function with arguments following the model's
+        response.
+
+        Args:
+            response (Dict[str, Any]): The response obtained by calling the
+                model.
+
+        Returns:
+            tuple: A tuple consisting of two obj:`FunctionCallingMessage`,
+                one about the arguments and the other about the execution
+                result, and a struct for logging information about this
+                function call.
+        """
+        # Note that when function calling is enabled, `n` is set to 1.
+        choice = response.choices[0]
+        if choice.message.tool_calls is None:
+            raise RuntimeError("Tool call is None")
+        func_name = choice.message.tool_calls[0].function.name
+
+        args = json.loads(choice.message.tool_calls[0].function.arguments)
+        tool = self.tool_dict[func_name]
+        result = await tool(**args)
+        tool_call_id = choice.message.tool_calls[0].id
+
+        assist_msg = FunctionCallingMessage(
+            role_name=self.role_name,
+            role_type=self.role_type,
+            meta_dict=None,
+            content="",
+            func_name=func_name,
+            args=args,
+            tool_call_id=tool_call_id,
+        )
+        func_msg = FunctionCallingMessage(
+            role_name=self.role_name,
+            role_type=self.role_type,
+            meta_dict=None,
+            content="",
+            func_name=func_name,
+            result=result,
+            tool_call_id=tool_call_id,
+        )
+
+        # Record information about this function call
+        func_record = FunctionCallingRecord(
+            func_name=func_name,
+            args=args,
+            result=result,
+            tool_call_id=tool_call_id,
+        )
+        return assist_msg, func_msg, func_record
+
+    def get_usage_dict(
+        self, output_messages: List[BaseMessage], prompt_tokens: int
+    ) -> Dict[str, int]:
+        r"""Get usage dictionary when using the stream mode.
+
+        Args:
+            output_messages (list): List of output messages.
+            prompt_tokens (int): Number of input prompt tokens.
+
+        Returns:
+            dict: Usage dictionary.
+        """
+        encoding = get_model_encoding(self.model_type.value_for_tiktoken)
+        completion_tokens = 0
+        for message in output_messages:
+            completion_tokens += len(encoding.encode(message.content))
+        usage_dict = dict(
+            completion_tokens=completion_tokens,
+            prompt_tokens=prompt_tokens,
+            total_tokens=completion_tokens + prompt_tokens,
+        )
+        return usage_dict
+
+    def add_model_scheduling_strategy(self, name: str, strategy_fn: Callable):
+        r"""Add a scheduling strategy method provided by user to ModelManger.
+
+        Args:
+            name (str): The name of the strategy.
+            strategy_fn (Callable): The scheduling strategy function.
+        """
+        self.model_backend.add_strategy(name, strategy_fn)
+
+    def __repr__(self) -> str:
+        r"""Returns a string representation of the :obj:`ChatAgent`.
+
+        Returns:
+            str: The string representation of the :obj:`ChatAgent`.
+        """
+        return (
+            f"ChatAgent({self.role_name}, {self.role_type}, {self.model_type})"
+        )

camel/agents/critic_agent.py

@@ -0,0 +1,202 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import random
+import warnings
+from typing import Any, Dict, Optional, Sequence
+
+from colorama import Fore
+
+from camel.agents.chat_agent import ChatAgent
+from camel.memories import AgentMemory
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.responses import ChatAgentResponse
+from camel.utils import get_first_int, print_text_animated
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+@track_agent(name="CriticAgent")
+class CriticAgent(ChatAgent):
+    r"""A class for the critic agent that assists in selecting an option.
+
+    Args:
+        system_message (BaseMessage): The system message for the critic
+            agent.
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        message_window_size (int, optional): The maximum number of previous
+            messages to include in the context window. If `None`, no windowing
+            is performed. (default: :obj:`6`)
+        retry_attempts (int, optional): The number of retry attempts if the
+            critic fails to return a valid option. (default: :obj:`2`)
+        verbose (bool, optional): Whether to print the critic's messages.
+        logger_color (Any): The color of the menu options displayed to the
+            user. (default: :obj:`Fore.MAGENTA`)
+    """
+
+    def __init__(
+        self,
+        system_message: BaseMessage,
+        model: Optional[BaseModelBackend] = None,
+        memory: Optional[AgentMemory] = None,
+        message_window_size: int = 6,
+        retry_attempts: int = 2,
+        verbose: bool = False,
+        logger_color: Any = Fore.MAGENTA,
+    ) -> None:
+        super().__init__(
+            system_message,
+            model=model,
+            memory=memory,
+            message_window_size=message_window_size,
+        )
+        self.options_dict: Dict[str, str] = dict()
+        self.retry_attempts = retry_attempts
+        self.verbose = verbose
+        self.logger_color = logger_color
+
+    def flatten_options(self, messages: Sequence[BaseMessage]) -> str:
+        r"""Flattens the options to the critic.
+
+        Args:
+            messages (Sequence[BaseMessage]): A list of `BaseMessage` objects.
+
+        Returns:
+            str: A string containing the flattened options to the critic.
+        """
+        options = [message.content for message in messages]
+        flatten_options = (
+            f"> Proposals from "
+            f"{messages[0].role_name} ({messages[0].role_type}). "
+            "Please choose an option:\n"
+        )
+        for index, option in enumerate(options):
+            flatten_options += f"Option {index + 1}:\n{option}\n\n"
+            self.options_dict[str(index + 1)] = option
+        format = (
+            f"Please first enter your choice ([1-{len(self.options_dict)}]) "
+            "and then your explanation and comparison: "
+        )
+        return flatten_options + format
+
+    def get_option(self, input_message: BaseMessage) -> str:
+        r"""Gets the option selected by the critic.
+
+        Args:
+            input_message (BaseMessage): A `BaseMessage` object representing
+                the input message.
+
+        Returns:
+            str: The option selected by the critic.
+        """
+        # TODO: Add support for editing options by the critic.
+        msg_content = input_message.content
+        i = 0
+        while i < self.retry_attempts:
+            critic_response = self.step(input_message)
+
+            if critic_response.msgs is None or len(critic_response.msgs) == 0:
+                raise RuntimeError("Got None critic messages.")
+            if critic_response.terminated:
+                raise RuntimeError("Critic step failed.")
+
+            critic_msg = critic_response.msg
+            if self.verbose:
+                print_text_animated(
+                    self.logger_color + "\n> Critic response: "
+                    f"\x1b[3m{critic_msg.content}\x1b[0m\n"
+                )
+            choice = self.parse_critic(critic_msg)
+
+            if choice in self.options_dict:
+                return self.options_dict[choice]
+            else:
+                input_message = BaseMessage(
+                    role_name=input_message.role_name,
+                    role_type=input_message.role_type,
+                    meta_dict=input_message.meta_dict,
+                    content="> Invalid choice. Please choose again.\n"
+                    + msg_content,
+                )
+                i += 1
+        warnings.warn(
+            "Critic failed to get a valid option. "
+            f"After {self.retry_attempts} attempts. "
+            "Returning a random option."
+        )
+        return random.choice(list(self.options_dict.values()))
+
+    def parse_critic(self, critic_msg: BaseMessage) -> Optional[str]:
+        r"""Parses the critic's message and extracts the choice.
+
+        Args:
+            critic_msg (BaseMessage): A `BaseMessage` object representing the
+                critic's response.
+
+        Returns:
+            Optional[str]: The critic's choice as a string, or None if the
+                message could not be parsed.
+        """
+        choice = str(get_first_int(critic_msg.content))
+        return choice
+
+    def reduce_step(
+        self,
+        input_messages: Sequence[BaseMessage],
+    ) -> ChatAgentResponse:
+        r"""Performs one step of the conversation by flattening options to the
+        critic, getting the option, and parsing the choice.
+
+        Args:
+            input_messages (Sequence[BaseMessage]): A list of BaseMessage
+                objects.
+
+        Returns:
+            ChatAgentResponse: A `ChatAgentResponse` object includes the
+                critic's choice.
+        """
+        meta_chat_message = BaseMessage(
+            role_name=input_messages[0].role_name,
+            role_type=input_messages[0].role_type,
+            meta_dict=input_messages[0].meta_dict,
+            content="",
+        )
+
+        flatten_options = self.flatten_options(input_messages)
+        if self.verbose:
+            print_text_animated(
+                self.logger_color + f"\x1b[3m{flatten_options}\x1b[0m\n"
+            )
+        input_msg = meta_chat_message.create_new_instance(flatten_options)
+
+        option = self.get_option(input_msg)
+        output_msg = meta_chat_message.create_new_instance(option)
+
+        # TODO: The return `info` can be improved.
+        return ChatAgentResponse(
+            msgs=[output_msg],
+            terminated=False,
+            info={},
+        )

camel/agents/deductive_reasoner_agent.py

@@ -0,0 +1,303 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import re
+from typing import Dict, List, Optional, Union
+
+from camel.agents.chat_agent import ChatAgent
+from camel.logger import get_logger
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.prompts import TextPrompt
+from camel.types import RoleType
+
+logger = get_logger(__name__)
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+@track_agent(name="DeductiveReasonerAgent")
+class DeductiveReasonerAgent(ChatAgent):
+    r"""An agent responsible for deductive reasoning. Model of deductive
+    reasoning:
+        - L: A ⊕ C -> q * B
+        - A represents the known starting state.
+        - B represents the known target state.
+        - C represents the conditions required to transition from A to B.
+        - Q represents the quality or effectiveness of the transition from
+        A to B.
+        - L represents the path or process from A to B.
+
+    Args:
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+    """
+
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+    ) -> None:
+        system_message = BaseMessage(
+            role_name="Insight Agent",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You assign roles based on tasks.",
+        )
+        super().__init__(system_message, model=model)
+
+    def deduce_conditions_and_quality(
+        self,
+        starting_state: str,
+        target_state: str,
+        role_descriptions_dict: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Union[List[str], Dict[str, str]]]:
+        r"""Derives the conditions and quality from the starting state and the
+        target state based on the model of the deductive reasoning and the
+        knowledge base. It can optionally consider the roles involved in the
+        scenario, which allows tailoring the output more closely to the AI
+        agent's environment.
+
+        Args:
+            starting_state (str): The initial or starting state from which
+                conditions are deduced.
+            target_state (str): The target state of the task.
+            role_descriptions_dict (Optional[Dict[str, str]], optional): The
+                descriptions of the roles. (default: :obj:`None`)
+            role_descriptions_dict (Optional[Dict[str, str]], optional): A
+                dictionary describing the roles involved in the scenario. This
+                is optional and can be used to provide a context for the
+                CAMEL's role-playing, enabling the generation of more relevant
+                and tailored conditions and quality assessments. This could be
+                generated using a `RoleAssignmentAgent()` or defined manually
+                by the user.
+
+        Returns:
+            Dict[str, Union[List[str], Dict[str, str]]]: A dictionary with the
+                extracted data from the message. The dictionary contains three
+                keys:
+                - 'conditions': A list where each key is a condition ID and
+                    each value is the corresponding condition text.
+                - 'labels': A list of label strings extracted from the message.
+                - 'quality': A string of quality assessment strings extracted
+                    from the message.
+        """
+        self.reset()
+
+        deduce_prompt = """You are a deductive reasoner. You are tasked to 
+        complete the TASK based on the THOUGHT OF DEDUCTIVE REASONING, the 
+        STARTING STATE A and the TARGET STATE B. You are given the CONTEXT 
+        CONTENT to help you complete the TASK.
+Your answer MUST strictly adhere to the structure of ANSWER TEMPLATE, ONLY 
+fill in the BLANKs, and DO NOT alter or modify any other part of the template
+
+===== MODELING OF DEDUCTIVE REASONING =====
+You are tasked with understanding a mathematical model based on the components 
+${A, B, C, Q, L}$. In this model: ``L: A ⊕ C -> q * B``.
+- $A$ represents the known starting state.
+- $B$ represents the known target state.
+- $C$ represents the conditions required to transition from $A$ to $B$.
+- $Q$ represents the quality or effectiveness of the transition from $A$ to 
+$B$.
+- $L$ represents the path or process from $A$ to $B$.
+
+===== THOUGHT OF DEDUCTIVE REASONING =====
+1. Define the Parameters of A and B:
+    - Characterization: Before delving into transitions, thoroughly understand 
+    the nature and boundaries of both $A$ and $B$. This includes the type, 
+    properties, constraints, and possible interactions between the two.
+    - Contrast and Compare: Highlight the similarities and differences between 
+    $A$ and $B$. This comparative analysis will give an insight into what 
+    needs changing and what remains constant.
+2. Historical & Empirical Analysis:
+    - Previous Transitions according to the Knowledge Base of GPT: (if 
+    applicable) Extract conditions and patterns from the historical instances 
+    where a similar transition from a state comparable to $A$ moved towards 
+    $B$.
+    - Scientific Principles: (if applicable) Consider the underlying 
+    scientific principles governing or related to the states and their 
+    transition. For example, if $A$ and $B$ are physical states, laws of 
+    physics might apply.
+3. Logical Deduction of Conditions ($C$):
+    - Direct Path Analysis: What are the immediate and direct conditions 
+    required to move from $A$ to $B$?
+    - Intermediate States: Are there states between $A$ and $B$ that must be 
+    traversed or can be used to make the transition smoother or more 
+    efficient? If yes, what is the content?
+    - Constraints & Limitations: Identify potential barriers or restrictions 
+    in moving from $A$ to $B$. These can be external (e.g., environmental 
+    factors) or internal (properties of $A$ or $B$).
+    - Resource and Information Analysis: What resources and information are 
+    required for the transition? This could be time, entity, factor, code 
+    language, software platform, unknowns, etc.
+    - External Influences: Consider socio-economic, political, or 
+    environmental factors (if applicable) that could influence the transition 
+    conditions.
+    - Creative/Heuristic Reasoning: Open your mind to multiple possible $C$'s, 
+    no matter how unconventional they might seem. Utilize analogies, 
+    metaphors, or brainstorming techniques to envision possible conditions or 
+    paths from $A$ to $B$.
+    - The conditions $C$ should be multiple but in one sentence. And each 
+    condition should be concerned with one aspect/entity.
+4. Entity/Label Recognition of Conditions ($C$):
+    - Identify and categorize entities of Conditions ($C$) such as the names, 
+    locations, dates, specific technical terms or contextual parameters that 
+    might be associated with events, innovations post-2022.
+    - The output of the entities/labels will be used as tags or labels for 
+    semantic similarity searches. The entities/labels may be the words, or 
+    phrases, each of them should contain valuable, high information entropy 
+    information, and should be independent.
+    - Ensure that the identified entities are formatted in a manner suitable 
+    for database indexing and retrieval. Organize the entities into 
+    categories, and combine the category with its instance into a continuous 
+    phrase, without using colons or other separators.
+    - Format these entities for database indexing: output the category rather 
+    than its instance/content into a continuous phrase. For example, instead 
+    of "Jan. 02", identify it as "Event time".
+5. Quality Assessment ($Q$):
+    - Efficiency: How efficient is the transition from $A$ to $B$, which 
+    measures the resources used versus the desired outcome?
+    - Effectiveness: Did the transition achieve the desired outcome or was the 
+    target state achieved as intended?
+    - Safety & Risks: Assess any risks associated with the transition and the 
+    measures to mitigate them.
+    - Feedback Mechanisms: Incorporate feedback loops to continuously monitor 
+    and adjust the quality of transition, making it more adaptive.
+6. Iterative Evaluation:
+    - Test & Refine: Based on the initially deduced conditions and assessed 
+    quality, iterate the process to refine and optimize the transition. This 
+    might involve tweaking conditions, employing different paths, or changing 
+    resources.
+    - Feedback Integration: Use feedback to make improvements and increase the 
+    quality of the transition.
+7. Real-world scenarios often present challenges that may not be captured by 
+models and frameworks. While using the model, maintain an adaptive mindset:
+    - Scenario Exploration: Continuously imagine various possible scenarios, 
+    both positive and negative, to prepare for unexpected events.
+    - Flexibility: Be prepared to modify conditions ($C$) or alter the path/
+    process ($L$) if unforeseen challenges arise.
+    - Feedback Integration: Rapidly integrate feedback from actual 
+    implementations to adjust the model's application, ensuring relevancy and 
+    effectiveness.
+
+===== TASK =====
+Given the starting state $A$ and the target state $B$, assuming that a path 
+$L$ always exists between $A$ and $B$, how can one deduce or identify the 
+necessary conditions $C$ and the quality $Q$ of the transition?
+
+===== STARTING STATE $A$ =====
+{starting_state}
+
+===== TARGET STATE $B$ =====
+{target_state}
+
+{role_with_description_prompt}
+===== ANSWER TEMPLATE =====
+- Characterization and comparison of $A$ and $B$:\n<BLANK>
+- Historical & Empirical Analysis:\n<BLANK>/None
+- Logical Deduction of Conditions ($C$) (multiple conditions can be deduced):
+    condition <NUM>:
+        <BLANK>.
+- Entity/Label Recognition of Conditions:\n[<BLANK>, <BLANK>, ...] (include 
+square brackets)
+- Quality Assessment ($Q$) (do not use symbols):
+    <BLANK>.
+- Iterative Evaluation:\n<BLANK>/None"""
+
+        if role_descriptions_dict is not None:
+            role_names = role_descriptions_dict.keys()
+            role_with_description_prompt = (
+                "===== ROLES WITH DESCRIPTIONS =====\n"
+                + "\n".join(
+                    f"{role_name}:\n{role_descriptions_dict[role_name]}\n"
+                    for role_name in role_names
+                )
+                + "\n\n"
+            )
+        else:
+            role_with_description_prompt = ""
+        deduce_prompt = TextPrompt(deduce_prompt)
+
+        deduce = deduce_prompt.format(
+            starting_state=starting_state,
+            target_state=target_state,
+            role_with_description_prompt=role_with_description_prompt,
+        )
+
+        conditions_and_quality_generation_msg = BaseMessage.make_user_message(
+            role_name="Deductive Reasoner", content=deduce
+        )
+
+        response = self.step(
+            input_message=conditions_and_quality_generation_msg
+        )
+
+        if response.terminated:
+            raise RuntimeError(
+                "Deduction failed. Error:\n" + f"{response.info}"
+            )
+        msg: BaseMessage = response.msg
+        logger.info(f"Message content:\n{msg.content}")
+
+        # Extract the conditions from the message
+        conditions_dict = {
+            f"condition {i}": cdt.replace("<", "")
+            .replace(">", "")
+            .strip()
+            .strip('\n')
+            for i, cdt in re.findall(
+                r"condition (\d+):\s*(.+?)(?=condition \d+|- Entity)",
+                msg.content,
+                re.DOTALL,
+            )
+        }
+
+        # Extract the labels from the message
+        labels = [
+            label.strip().strip('\n').strip("\"'")
+            for label in re.findall(
+                r"Entity/Label Recognition of Conditions:\n\[(.+?)\]",
+                msg.content,
+                re.DOTALL,
+            )[0].split(",")
+        ]
+
+        # Extract the quality from the message
+        quality = next(
+            q.strip().strip('\n')
+            for q in re.findall(
+                r"Quality Assessment \(\$Q\$\) \(do not use symbols\):"
+                r"\n(.+?)- Iterative",
+                msg.content,
+                re.DOTALL,
+            )
+        )
+
+        # Convert them into JSON format
+        conditions_and_quality_json: Dict[
+            str, Union[List[str], Dict[str, str]]
+        ] = {}
+        conditions_and_quality_json["conditions"] = conditions_dict
+        conditions_and_quality_json["labels"] = labels
+        conditions_and_quality_json["evaluate_quality"] = quality
+
+        return conditions_and_quality_json

camel/agents/embodied_agent.py

@@ -0,0 +1,201 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from typing import Any, List, Optional
+
+from colorama import Fore
+
+from camel.agents.chat_agent import ChatAgent
+from camel.agents.tool_agents.base import BaseToolAgent
+from camel.interpreters import (
+    BaseInterpreter,
+    InternalPythonInterpreter,
+    SubprocessInterpreter,
+)
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.responses import ChatAgentResponse
+from camel.utils import print_text_animated
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+@track_agent(name="EmbodiedAgent")
+class EmbodiedAgent(ChatAgent):
+    r"""Class for managing conversations of CAMEL Embodied Agents.
+
+    Args:
+        system_message (BaseMessage): The system message for the chat agent.
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        message_window_size (int, optional): The maximum number of previous
+            messages to include in the context window. If `None`, no windowing
+            is performed. (default: :obj:`None`)
+        tool_agents (List[BaseToolAgent], optional): The tools agents to use in
+            the embodied agent. (default: :obj:`None`)
+        code_interpreter (BaseInterpreter, optional): The code interpreter to
+            execute codes. If `code_interpreter` and `tool_agent` are both
+            `None`, default to `SubProcessInterpreter`. If `code_interpreter`
+            is `None` and `tool_agents` is not `None`, default to
+            `InternalPythonInterpreter`.  (default: :obj:`None`)
+        verbose (bool, optional): Whether to print the critic's messages.
+        logger_color (Any): The color of the logger displayed to the user.
+            (default: :obj:`Fore.MAGENTA`)
+    """
+
+    def __init__(
+        self,
+        system_message: BaseMessage,
+        model: Optional[BaseModelBackend] = None,
+        message_window_size: Optional[int] = None,
+        tool_agents: Optional[List[BaseToolAgent]] = None,
+        code_interpreter: Optional[BaseInterpreter] = None,
+        verbose: bool = False,
+        logger_color: Any = Fore.MAGENTA,
+    ) -> None:
+        self.tool_agents = tool_agents
+        self.code_interpreter: BaseInterpreter
+        if code_interpreter is not None:
+            self.code_interpreter = code_interpreter
+        elif self.tool_agents:
+            self.code_interpreter = InternalPythonInterpreter()
+        else:
+            self.code_interpreter = SubprocessInterpreter()
+
+        if self.tool_agents:
+            system_message = self._set_tool_agents(system_message)
+        self.verbose = verbose
+        self.logger_color = logger_color
+        super().__init__(
+            system_message=system_message,
+            model=model,
+            message_window_size=message_window_size,
+        )
+
+    def _set_tool_agents(self, system_message: BaseMessage) -> BaseMessage:
+        action_space_prompt = self._get_tool_agents_prompt()
+        result_message = system_message.create_new_instance(
+            content=system_message.content.format(
+                action_space=action_space_prompt
+            )
+        )
+        if self.tool_agents is not None:
+            self.code_interpreter.update_action_space(
+                {tool.name: tool for tool in self.tool_agents}
+            )
+        return result_message
+
+    def _get_tool_agents_prompt(self) -> str:
+        r"""Returns the action space prompt.
+
+        Returns:
+            str: The action space prompt.
+        """
+        if self.tool_agents is not None:
+            return "\n".join(
+                [
+                    f"*** {tool.name} ***:\n {tool.description}"
+                    for tool in self.tool_agents
+                ]
+            )
+        else:
+            return ""
+
+    def get_tool_agent_names(self) -> List[str]:
+        r"""Returns the names of tool agents.
+
+        Returns:
+            List[str]: The names of tool agents.
+        """
+        if self.tool_agents is not None:
+            return [tool.name for tool in self.tool_agents]
+        else:
+            return []
+
+    # ruff: noqa: E501
+    def step(self, input_message: BaseMessage) -> ChatAgentResponse:  # type: ignore[override]
+        r"""Performs a step in the conversation.
+
+        Args:
+            input_message (BaseMessage): The input message.
+
+        Returns:
+            ChatAgentResponse: A struct containing the output messages,
+                a boolean indicating whether the chat session has terminated,
+                and information about the chat session.
+        """
+        response = super().step(input_message)
+
+        if response.msgs is None or len(response.msgs) == 0:
+            raise RuntimeError("Got None output messages.")
+        if response.terminated:
+            raise RuntimeError(f"{self.__class__.__name__} step failed.")
+
+        # NOTE: Only single output messages are supported
+        explanations, codes = response.msg.extract_text_and_code_prompts()
+
+        if self.verbose:
+            for explanation, code in zip(explanations, codes):
+                print_text_animated(
+                    self.logger_color + f"> Explanation:\n{explanation}"
+                )
+                print_text_animated(self.logger_color + f"> Code:\n{code}")
+
+            if len(explanations) > len(codes):
+                print_text_animated(
+                    self.logger_color + f"> Explanation:\n{explanations[-1]}"
+                )
+
+        content = response.msg.content
+
+        if codes is not None:
+            try:
+                content = "\n> Executed Results:\n"
+                for block_idx, code in enumerate(codes):
+                    executed_output = self.code_interpreter.run(
+                        code, code.code_type
+                    )
+                    content += (
+                        f"Executing code block {block_idx}: {{\n"
+                        + executed_output
+                        + "}\n"
+                    )
+            except InterruptedError as e:
+                content = (
+                    f"\n> Running code fail: {e}\n"
+                    "Please regenerate the code."
+                )
+
+        # TODO: Handle errors
+        content = input_message.content + f"\n> Embodied Actions:\n{content}"
+        message = BaseMessage(
+            input_message.role_name,
+            input_message.role_type,
+            input_message.meta_dict,
+            content,
+        )
+        return ChatAgentResponse(
+            msgs=[message],
+            terminated=response.terminated,
+            info=response.info,
+        )

camel/agents/knowledge_graph_agent.py

@@ -0,0 +1,259 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from typing import TYPE_CHECKING, Optional, Union
+
+if TYPE_CHECKING:
+    from unstructured.documents.elements import Element
+
+from camel.agents import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.prompts import TextPrompt
+from camel.storages.graph_storages.graph_element import (
+    GraphElement,
+    Node,
+    Relationship,
+)
+from camel.types import RoleType
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+text_prompt = """
+You are tasked with extracting nodes and relationships from given content and 
+structures them into Node and Relationship objects. Here's the outline of what 
+you needs to do:
+
+Content Extraction:
+You should be able to process input content and identify entities mentioned 
+within it.
+Entities can be any noun phrases or concepts that represent distinct entities 
+in the context of the given content.
+
+Node Extraction:
+For each identified entity, you should create a Node object.
+Each Node object should have a unique identifier (id) and a type (type).
+Additional properties associated with the node can also be extracted and 
+stored.
+
+Relationship Extraction:
+You should identify relationships between entities mentioned in the content.
+For each relationship, create a Relationship object.
+A Relationship object should have a subject (subj) and an object (obj) which 
+are Node objects representing the entities involved in the relationship.
+Each relationship should also have a type (type), and additional properties if 
+applicable.
+
+Output Formatting:
+The extracted nodes and relationships should be formatted as instances of the 
+provided Node and Relationship classes.
+Ensure that the extracted data adheres to the structure defined by the classes.
+Output the structured data in a format that can be easily validated against 
+the provided code.
+
+Instructions for you:
+Read the provided content thoroughly.
+Identify distinct entities mentioned in the content and categorize them as 
+nodes.
+Determine relationships between these entities and represent them as directed 
+relationships.
+Provide the extracted nodes and relationships in the specified format below.
+Example for you:
+
+Example Content:
+"John works at XYZ Corporation. He is a software engineer. The company is 
+located in New York City."
+
+Expected Output:
+
+Nodes:
+
+Node(id='John', type='Person')
+Node(id='XYZ Corporation', type='Organization')
+Node(id='New York City', type='Location')
+
+Relationships:
+
+Relationship(subj=Node(id='John', type='Person'), obj=Node(id='XYZ 
+Corporation', type='Organization'), type='WorksAt')
+Relationship(subj=Node(id='John', type='Person'), obj=Node(id='New York City', 
+type='Location'), type='ResidesIn')
+
+===== TASK =====
+Please extracts nodes and relationships from given content and structures them 
+into Node and Relationship objects. 
+
+{task}
+"""
+
+
+@track_agent(name="KnowledgeGraphAgent")
+class KnowledgeGraphAgent(ChatAgent):
+    r"""An agent that can extract node and relationship information for
+    different entities from given `Element` content.
+
+    Attributes:
+        task_prompt (TextPrompt): A prompt for the agent to extract node and
+            relationship information for different entities.
+    """
+
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+    ) -> None:
+        r"""Initialize the `KnowledgeGraphAgent`.
+
+        Args:
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        """
+        system_message = BaseMessage(
+            role_name="Graphify",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="Your mission is to transform unstructured content "
+            "into structured graph data. Extract nodes and relationships with "
+            "precision, and let the connections unfold. Your graphs will "
+            "illuminate the hidden connections within the chaos of "
+            "information.",
+        )
+        super().__init__(system_message, model=model)
+
+    def run(
+        self,
+        element: "Element",
+        parse_graph_elements: bool = False,
+    ) -> Union[str, GraphElement]:
+        r"""Run the agent to extract node and relationship information.
+
+        Args:
+            element (Element): The input element.
+            parse_graph_elements (bool, optional): Whether to parse into
+                `GraphElement`. Defaults to `False`.
+
+        Returns:
+            Union[str, GraphElement]: The extracted node and relationship
+                information. If `parse_graph_elements` is `True` then return
+                `GraphElement`, else return `str`.
+        """
+        self.reset()
+        self.element = element
+
+        knowledge_graph_prompt = TextPrompt(text_prompt)
+        knowledge_graph_generation = knowledge_graph_prompt.format(
+            task=str(element)
+        )
+
+        knowledge_graph_generation_msg = BaseMessage.make_user_message(
+            role_name="Graphify", content=knowledge_graph_generation
+        )
+
+        response = self.step(input_message=knowledge_graph_generation_msg)
+
+        content = response.msg.content
+
+        if parse_graph_elements:
+            content = self._parse_graph_elements(content)
+
+        return content
+
+    def _validate_node(self, node: Node) -> bool:
+        r"""Validate if the object is a valid Node.
+
+        Args:
+            node (Node): Object to be validated.
+
+        Returns:
+            bool: True if the object is a valid Node, False otherwise.
+        """
+        return (
+            isinstance(node, Node)
+            and isinstance(node.id, (str, int))
+            and isinstance(node.type, str)
+        )
+
+    def _validate_relationship(self, relationship: Relationship) -> bool:
+        r"""Validate if the object is a valid Relationship.
+
+        Args:
+            relationship (Relationship): Object to be validated.
+
+        Returns:
+            bool: True if the object is a valid Relationship, False otherwise.
+        """
+        return (
+            isinstance(relationship, Relationship)
+            and self._validate_node(relationship.subj)
+            and self._validate_node(relationship.obj)
+            and isinstance(relationship.type, str)
+        )
+
+    def _parse_graph_elements(self, input_string: str) -> GraphElement:
+        r"""Parses graph elements from given content.
+
+        Args:
+            input_string (str): The input content.
+
+        Returns:
+            GraphElement: The parsed graph elements.
+        """
+        import re
+
+        # Regular expressions to extract nodes and relationships
+        node_pattern = r"Node\(id='(.*?)', type='(.*?)'\)"
+        rel_pattern = (
+            r"Relationship\(subj=Node\(id='(.*?)', type='(.*?)'\), "
+            r"obj=Node\(id='(.*?)', type='(.*?)'\), type='(.*?)'\)"
+        )
+
+        nodes = {}
+        relationships = []
+
+        # Extract nodes
+        for match in re.finditer(node_pattern, input_string):
+            id, type = match.groups()
+            properties = {'source': 'agent_created'}
+            if id not in nodes:
+                node = Node(id=id, type=type, properties=properties)
+                if self._validate_node(node):
+                    nodes[id] = node
+
+        # Extract relationships
+        for match in re.finditer(rel_pattern, input_string):
+            subj_id, subj_type, obj_id, obj_type, rel_type = match.groups()
+            properties = {'source': 'agent_created'}
+            if subj_id in nodes and obj_id in nodes:
+                subj = nodes[subj_id]
+                obj = nodes[obj_id]
+                relationship = Relationship(
+                    subj=subj, obj=obj, type=rel_type, properties=properties
+                )
+                if self._validate_relationship(relationship):
+                    relationships.append(relationship)
+
+        return GraphElement(
+            nodes=list(nodes.values()),
+            relationships=relationships,
+            source=self.element,
+        )

camel/agents/multi_hop_generator_agent.py

@@ -0,0 +1,117 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import textwrap
+from typing import Any
+
+from pydantic import ConfigDict
+
+from camel.agents.programmed_agent_instruction import (
+    ProgrammableChatAgent,
+    ProgrammedAgentInstructionResult,
+    programmable_capability,
+)
+from camel.datagen.source2synth.models import (
+    ContextPrompt,
+    MultiHopQA,
+)
+from camel.messages import BaseMessage
+
+
+class MultiHopGeneratorAgent(ProgrammableChatAgent):
+    r"""An agent specialized in generating multi-hop question-answer pairs.
+
+    This agent is designed to create complex questions that require multiple
+    steps of reasoning to answer. It analyzes context to identify related
+    facts and generates questions that require connecting these facts
+    logically.
+
+    Attributes:
+        model_config (ConfigDict): Configuration for model behavior.
+        system_message (BaseMessage): System message defining agent's role and
+            instructions.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def __init__(self, **kwargs: Any) -> None:
+        r"""Initialize the MultiHopGeneratorAgent.
+
+        Args:
+            **kwargs (Any): Additional keyword arguments to pass to parent
+                class.
+        """
+        super().__init__(**kwargs)
+
+        system_text: str = textwrap.dedent(
+            """\
+            You are an expert at generating 
+            multi-hop question-answer pairs.
+            For each context, you should:
+            1. Identify multiple related facts or pieces of information
+            2. Create questions that require reasoning across these multiple pieces
+            3. Ensure the reasoning chain is clear and logical
+            4. Generate questions that require at least 2-3 steps of reasoning
+            5. Include the reasoning steps in the answer
+
+            Give your response with this information:
+            Question: [Complex question requiring multiple reasoning steps]
+            Reasoning Steps:
+            1. [First reasoning step]
+            2. [Second reasoning step]
+            3. [Final reasoning step]
+            Answer: [Final answer]
+            Supporting Facts: [List of relevant text segments used]
+            """  # noqa: E501
+        )
+        self.system_message = BaseMessage.make_assistant_message(
+            role_name='Assistant', content=system_text
+        )
+
+    @programmable_capability
+    def generate_multi_hop_qa(
+        self, context: str
+    ) -> ProgrammedAgentInstructionResult[MultiHopQA]:
+        r"""Generate a multi-hop question-answer pair from given context.
+
+        Args:
+            context (str): The input text context to generate QA from.
+
+        Returns:
+            ProgrammedAgentInstructionResult[MultiHopQA]: Result containing the
+                generated question, reasoning steps, answer, and supporting
+                facts.
+
+        Raises:
+            RuntimeError: If the agent fails to generate a response.
+        """
+        context_prompt = ContextPrompt(
+            main_context=context, related_contexts=None
+        )
+
+        user_message = BaseMessage.make_user_message(
+            content=context_prompt.model_dump_json(), role_name="User"
+        )
+        response = self.step(
+            input_message=user_message, response_format=MultiHopQA
+        )
+        value = MultiHopQA.model_validate_json(response.msgs[0].content)
+
+        if response.msgs:
+            return ProgrammedAgentInstructionResult(
+                user_message=user_message,
+                agent_message=response.msgs[0],
+                value=value,
+            )
+        raise RuntimeError("No response from agent")

camel/agents/programmed_agent_instruction.py

@@ -0,0 +1,203 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import abc
+import threading
+from enum import Enum
+from functools import wraps
+from typing import Any, Callable, Generic, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+from camel.agents import ChatAgent
+from camel.messages import BaseMessage
+
+T = TypeVar('T')
+
+
+class ProgrammableAgentRequirement(Enum):
+    r"""Requirements for programmable agent state.
+
+    Defines the possible requirements that can be used to repair the state
+    of a programmable agent.
+
+    Attributes:
+        LAST_MESSAGE_NOT_USER (str): Requires that the last message in the
+            conversation was not from the user.
+    """
+
+    LAST_MESSAGE_NOT_USER = "LAST_MESSAGE_NOT_USER"
+
+
+class ProgrammedAgentInstructionResult(BaseModel, Generic[T]):
+    r"""Result of a programmable agent instruction execution.
+
+    Contains the messages exchanged during execution and the computed value.
+    The value type is specified by the generic type parameter T.
+
+    Attributes:
+        user_message (BaseMessage): The message sent by the user.
+        agent_message (BaseMessage): The message sent by the agent.
+        value (T): The computed result value of type T.
+    """
+
+    user_message: BaseMessage
+    agent_message: BaseMessage
+    value: T
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class AbstractProgrammableAgent(abc.ABC):
+    r"""Abstract class for a programmable agent.
+
+    A programmable agent is an agent that can be programmed to perform a
+    specific function or task. This class defines the interface for a
+    programmable agent.
+
+    These methods should be implemented in order to ensure the agent supports
+    the necessary guarantees to enable a programming interface while
+    maintaining compatibility in a multi-agent system.
+
+    A programmable agent is responsible for providing and maintaining a
+    programming interface for its functionality.
+    """
+
+    @abc.abstractmethod
+    def run_atomic(
+        self, callback: Callable[[], ProgrammedAgentInstructionResult[T]]
+    ) -> ProgrammedAgentInstructionResult[T]:
+        r"""Run an atomic operation on the agent.
+
+        An atomic operation is an operation that is guaranteed to
+        be executed without interruption by any other operation.
+
+        Args:
+            callback (Callable[[], ProgrammedAgentInstructionResult[T]]): The
+                operation to execute atomically.
+
+        Returns:
+            ProgrammedAgentInstructionResult[T]: The result of the operation.
+
+        Raises:
+            RuntimeError: If an operation is already in progress.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def repair_state(self, requirement: ProgrammableAgentRequirement) -> None:
+        r"""Repair the state of the agent.
+
+        Agents may have other non-atomic interfaces, such as a user interface,
+        or chat between other agents. This method should restore the agent to
+        a state where it can perform operations according to the specified
+        requirement.
+
+        Args:
+            requirement (ProgrammableAgentRequirement): The requirement to
+                repair the state for.
+        """
+        raise NotImplementedError
+
+
+def programmable_capability(
+    func: Callable[..., ProgrammedAgentInstructionResult[T]],
+) -> Callable[..., ProgrammedAgentInstructionResult[T]]:
+    r"""Decorator for programmable agent capabilities.
+
+    This decorator ensures that the decorated method is executed atomically
+    and maintains the agent's state guarantees.
+
+    Args:
+        func (Callable[..., ProgrammedAgentInstructionResult[T]]): The method
+            to decorate.
+
+    Returns:
+        Callable[..., ProgrammedAgentInstructionResult[T]]: The decorated
+            method that ensures atomic execution.
+    """
+
+    @wraps(func)
+    def wrapper(
+        self, *args: Any, **kwargs: Any
+    ) -> ProgrammedAgentInstructionResult[T]:
+        return self.run_atomic(lambda: func(self, *args, **kwargs))
+
+    return wrapper
+
+
+class ProgrammableChatAgent(ChatAgent, AbstractProgrammableAgent):
+    r"""A chat agent that can be programmed to perform specific tasks.
+
+    Provides a default implementation of atomic execution using threading locks
+    and basic state tracking for message roles. Implementing classes need to
+    provide specific repair logic for their use cases.
+
+    Attributes:
+        _operation_lock (threading.Lock): Lock for ensuring atomic operations.
+        _last_message_role (Optional[str]): Role of the last message in the
+            conversation.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        r"""Initialize the ProgrammableChatAgent.
+
+        Args:
+            **kwargs (Any): Additional keyword arguments to pass to parent
+                class.
+        """
+        super().__init__(**kwargs)
+        self._operation_lock = threading.Lock()
+        self._last_message_role: Optional[str] = None
+
+    def run_atomic(
+        self, callback: Callable[[], ProgrammedAgentInstructionResult[T]]
+    ) -> ProgrammedAgentInstructionResult[T]:
+        r"""Run an atomic operation on the agent.
+
+        Ensures thread-safe execution of the callback function by using a lock.
+
+        Args:
+            callback (Callable[[], ProgrammedAgentInstructionResult[T]]): The
+                operation to execute atomically.
+
+        Returns:
+            ProgrammedAgentInstructionResult[T]: The result of the operation.
+
+        Raises:
+            RuntimeError: If an operation is already in progress.
+        """
+        if not self._operation_lock.acquire(blocking=False):
+            raise RuntimeError("Operation already in progress")
+
+        try:
+            result = callback()
+            self._last_message_role = result.agent_message.role_name
+            return result
+        finally:
+            self._operation_lock.release()
+
+    def repair_state(self, requirement: ProgrammableAgentRequirement) -> None:
+        r"""Repair the state of the agent.
+
+        Implements basic state repair for message role requirements.
+
+        Args:
+            requirement (ProgrammableAgentRequirement): The requirement to
+                repair the state for.
+        """
+        if requirement == ProgrammableAgentRequirement.LAST_MESSAGE_NOT_USER:
+            if self._last_message_role == "user":
+                raise NotImplementedError(
+                    "Must implement repair for LAST_MESSAGE_NOT_USER"
+                )

camel/agents/role_assignment_agent.py

@@ -0,0 +1,141 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import re
+from typing import Dict, Optional, Union
+
+from camel.agents.chat_agent import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.prompts import TextPrompt
+from camel.types import RoleType
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+@track_agent(name="RoleAssignmentAgent")
+class RoleAssignmentAgent(ChatAgent):
+    r"""An agent that generates role names based on the task prompt.
+
+    Args:
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+
+    Attributes:
+        role_assignment_prompt (TextPrompt): A prompt for the agent to generate
+        role names.
+    """
+
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+    ) -> None:
+        system_message = BaseMessage(
+            role_name="Role Assigner",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You assign roles based on tasks.",
+        )
+        super().__init__(system_message, model=model)
+
+    def run(
+        self,
+        task_prompt: Union[str, TextPrompt],
+        num_roles: int = 2,
+    ) -> Dict[str, str]:
+        r"""Generate role names based on the input task prompt.
+
+        Args:
+            task_prompt (Union[str, TextPrompt]): The prompt
+                for the task based on which the roles are to be generated.
+            num_roles (int, optional): The number of roles to generate.
+                (default: :obj:`2`)
+
+        Returns:
+            Dict[str, str]: A dictionary mapping role names to their
+                descriptions.
+        """
+        self.reset()
+
+        expert_prompt = "===== ANSWER PROMPT =====\n" + "\n".join(
+            f"Domain expert {i + 1}: <BLANK>\n"
+            f"Associated competencies, characteristics, duties "
+            f"and workflows: <BLANK>. End."
+            for i in range(num_roles or 0)
+        )
+        role_assignment_generation_prompt = TextPrompt(
+            "You are a role assignment agent, and you're in charge of "
+            + "recruiting {num_roles} experts for the following task."
+            + "\n==== TASK =====\n {task}\n\n"
+            + "Identify the domain experts you'd recruit and detail their "
+            + "associated competencies, characteristics, duties and workflows "
+            + "to complete the task.\n "
+            + "Your answer MUST adhere to the format of ANSWER PROMPT, and "
+            + "ONLY answer the BLANKs.\n"
+            + expert_prompt
+        )
+        role_assignment_generation = role_assignment_generation_prompt.format(
+            num_roles=num_roles, task=task_prompt
+        )
+
+        role_assignment_generation_msg = BaseMessage.make_user_message(
+            role_name="Role Assigner", content=role_assignment_generation
+        )
+
+        response = self.step(input_message=role_assignment_generation_msg)
+
+        msg = response.msg  # type: BaseMessage
+        terminated = response.terminated
+
+        # Distribute the output completions into role names and descriptions
+        role_names = [
+            desc.replace("<|", "").replace("|>", "")
+            for desc in re.findall(
+                r"Domain expert \d: (.+?)\nAssociated competencies,",
+                msg.content,
+                re.DOTALL,
+            )
+        ]
+        role_descriptions = [
+            desc.replace("<|", "").replace("|>", "")
+            for desc in re.findall(
+                r"Associated competencies, characteristics, "
+                r"duties and workflows: (.+?) End.",
+                msg.content,
+                re.DOTALL,
+            )
+        ]
+
+        if len(role_names) != num_roles or len(role_descriptions) != num_roles:
+            raise RuntimeError(
+                "Got None or insufficient information of roles."
+            )
+        if terminated:
+            raise RuntimeError("Role assignment failed.")
+
+        role_descriptions_dict = {
+            role_name: description
+            for role_name, description in zip(role_names, role_descriptions)
+        }
+
+        return role_descriptions_dict

camel/agents/search_agent.py

@@ -0,0 +1,133 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from typing import Optional
+
+from camel.agents.chat_agent import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.prompts import TextPrompt
+from camel.types import RoleType
+from camel.utils import create_chunks
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+@track_agent(name="SearchAgent")
+class SearchAgent(ChatAgent):
+    r"""An agent that summarizes text based on a query and evaluates the
+    relevance of an answer.
+
+    Args:
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+    """
+
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+    ) -> None:
+        system_message = BaseMessage(
+            role_name="Assistant",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You are a helpful assistant.",
+        )
+        super().__init__(system_message, model=model)
+
+    def summarize_text(self, text: str, query: str) -> str:
+        r"""Summarize the information from the text, base on the query.
+
+        Args:
+            text (str): Text to summarize.
+            query (str): What information you want.
+
+        Returns:
+            str: Strings with information.
+        """
+        self.reset()
+
+        summary_prompt = TextPrompt(
+            '''Gather information from this text that relative to the
+            question, but do not directly answer the question.\nquestion:
+            {query}\ntext '''
+        )
+        summary_prompt = summary_prompt.format(query=query)
+        # Max length of each chunk
+        max_len = 3000
+        results = ""
+        chunks = create_chunks(text, max_len)
+        # Summarize
+        for i, chunk in enumerate(chunks, start=1):
+            prompt = summary_prompt + str(i) + ": " + chunk
+            user_msg = BaseMessage.make_user_message(
+                role_name="User",
+                content=prompt,
+            )
+            result = self.step(user_msg).msg.content
+            results += result + "\n"
+
+        # Final summarization
+        final_prompt = TextPrompt(
+            '''Here are some summarized texts which split from one text. Using
+            the information to answer the question. If can't find the answer,
+            you must answer "I can not find the answer to the query" and
+            explain why.\n Query:\n{query}.\n\nText:\n'''
+        )
+        final_prompt = final_prompt.format(query=query)
+        prompt = final_prompt + results
+
+        user_msg = BaseMessage.make_user_message(
+            role_name="User",
+            content=prompt,
+        )
+        response = self.step(user_msg).msg.content
+
+        return response
+
+    def continue_search(self, query: str, answer: str) -> bool:
+        r"""Ask whether to continue search or not based on the provided answer.
+
+        Args:
+            query (str): The question.
+            answer (str): The answer to the question.
+
+        Returns:
+            bool: `True` if the user want to continue search, `False`
+            otherwise.
+        """
+        prompt = TextPrompt(
+            "Do you think the ANSWER can answer the QUERY? "
+            "Use only 'yes' or 'no' to answer.\n"
+            "===== QUERY =====\n{query}\n\n"
+            "===== ANSWER =====\n{answer}"
+        )
+        prompt = prompt.format(query=query, answer=answer)
+        user_msg = BaseMessage.make_user_message(
+            role_name="User",
+            content=prompt,
+        )
+        response = self.step(user_msg).msg.content
+        if "yes" in str(response).lower():
+            return False
+        return True

camel/agents/task_agent.py

@@ -0,0 +1,410 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from typing import Any, Dict, List, Optional, Union
+
+from camel.agents.chat_agent import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import BaseModelBackend
+from camel.prompts import PromptTemplateGenerator, TextPrompt
+from camel.types import RoleType, TaskType
+from camel.utils import get_task_list
+
+# AgentOps decorator setting
+try:
+    import os
+
+    if os.getenv("AGENTOPS_API_KEY") is not None:
+        from agentops import track_agent
+    else:
+        raise ImportError
+except (ImportError, AttributeError):
+    from camel.utils import track_agent
+
+
+@track_agent(name="TaskSpecifyAgent")
+class TaskSpecifyAgent(ChatAgent):
+    r"""An agent that specifies a given task prompt by prompting the user to
+    provide more details.
+
+    Attributes:
+        DEFAULT_WORD_LIMIT (int): The default word limit for the task prompt.
+        task_specify_prompt (TextPrompt): The prompt for specifying the task.
+
+    Args:
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        task_type (TaskType, optional): The type of task for which to generate
+            a prompt. (default: :obj:`TaskType.AI_SOCIETY`)
+        task_specify_prompt (Union[str, TextPrompt], optional): The prompt for
+            specifying the task. (default: :obj:`None`)
+        word_limit (int, optional): The word limit for the task prompt.
+            (default: :obj:`50`)
+        output_language (str, optional): The language to be output by the
+            agent. (default: :obj:`None`)
+    """
+
+    DEFAULT_WORD_LIMIT = 50
+
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+        task_type: TaskType = TaskType.AI_SOCIETY,
+        task_specify_prompt: Optional[Union[str, TextPrompt]] = None,
+        word_limit: int = DEFAULT_WORD_LIMIT,
+        output_language: Optional[str] = None,
+    ) -> None:
+        self.task_specify_prompt: Union[str, TextPrompt]
+        if task_specify_prompt is None:
+            task_specify_prompt_template = (
+                PromptTemplateGenerator().get_task_specify_prompt(task_type)
+            )
+
+            self.task_specify_prompt = task_specify_prompt_template.format(
+                word_limit=word_limit
+            )
+        else:
+            self.task_specify_prompt = TextPrompt(task_specify_prompt)
+
+        system_message = BaseMessage(
+            role_name="Task Specifier",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You can make a task more specific.",
+        )
+
+        super().__init__(
+            system_message,
+            model=model,
+            output_language=output_language,
+        )
+
+    def run(
+        self,
+        task_prompt: Union[str, TextPrompt],
+        meta_dict: Optional[Dict[str, Any]] = None,
+    ) -> TextPrompt:
+        r"""Specify the given task prompt by providing more details.
+
+        Args:
+            task_prompt (Union[str, TextPrompt]): The original task
+                prompt.
+            meta_dict (Dict[str, Any], optional): A dictionary containing
+                additional information to include in the prompt.
+                (default: :obj:`None`)
+
+        Returns:
+            TextPrompt: The specified task prompt.
+        """
+        self.reset()
+        task_specify_prompt = self.task_specify_prompt.format(task=task_prompt)
+
+        if meta_dict is not None:
+            task_specify_prompt = task_specify_prompt.format(**meta_dict)
+        task_msg = BaseMessage.make_user_message(
+            role_name="Task Specifier", content=task_specify_prompt
+        )
+        specifier_response = self.step(task_msg)
+
+        if specifier_response.terminated:
+            raise RuntimeError("Task specification failed.")
+        if len(specifier_response.msgs) == 0:
+            raise RuntimeError("Got no specification message.")
+
+        specified_task_msg = specifier_response.msgs[0]
+
+        return TextPrompt(specified_task_msg.content)
+
+
+@track_agent(name="TaskPlannerAgent")
+class TaskPlannerAgent(ChatAgent):
+    r"""An agent that helps divide a task into subtasks based on the input
+    task prompt.
+
+    Attributes:
+        task_planner_prompt (TextPrompt): A prompt for the agent to divide
+            the task into subtasks.
+
+    Args:
+        model (BaseModelBackend, optional): The model backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        output_language (str, optional): The language to be output by the
+            agent. (default: :obj:`None`)
+    """
+
+    def __init__(
+        self,
+        model: Optional[BaseModelBackend] = None,
+        output_language: Optional[str] = None,
+    ) -> None:
+        self.task_planner_prompt = TextPrompt(
+            "Divide this task into subtasks: {task}. Be concise."
+        )
+        system_message = BaseMessage(
+            role_name="Task Planner",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You are a helpful task planner.",
+        )
+
+        super().__init__(
+            system_message,
+            model=model,
+            output_language=output_language,
+        )
+
+    def run(
+        self,
+        task_prompt: Union[str, TextPrompt],
+    ) -> TextPrompt:
+        r"""Generate subtasks based on the input task prompt.
+
+        Args:
+            task_prompt (Union[str, TextPrompt]): The prompt for the task to
+                be divided into subtasks.
+
+        Returns:
+            TextPrompt: A prompt for the subtasks generated by the agent.
+        """
+        # TODO: Maybe include roles information.
+        self.reset()
+        task_planner_prompt = self.task_planner_prompt.format(task=task_prompt)
+
+        task_msg = BaseMessage.make_user_message(
+            role_name="Task Planner", content=task_planner_prompt
+        )
+
+        task_response = self.step(task_msg)
+
+        if task_response.terminated:
+            raise RuntimeError("Task planning failed.")
+        if len(task_response.msgs) == 0:
+            raise RuntimeError("Got no task planning message.")
+
+        sub_tasks_msg = task_response.msgs[0]
+        return TextPrompt(sub_tasks_msg.content)
+
+
+@track_agent(name="TaskCreationAgent")
+class TaskCreationAgent(ChatAgent):
+    r"""An agent that helps create new tasks based on the objective
+    and last completed task. Compared to :obj:`TaskPlannerAgent`,
+    it's still a task planner, but it has more context information
+    like last task and incomplete task list. Modified from
+    `BabyAGI <https://github.com/yoheinakajima/babyagi>`_.
+
+    Attributes:
+        task_creation_prompt (TextPrompt): A prompt for the agent to
+            create new tasks.
+
+    Args:
+        role_name (str): The role name of the Agent to create the task.
+        objective (Union[str, TextPrompt]): The objective of the Agent to
+            perform the task.
+        model (BaseModelBackend, optional): The LLM backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        output_language (str, optional): The language to be output by the
+            agent. (default: :obj:`None`)
+        message_window_size (int, optional): The maximum number of previous
+            messages to include in the context window. If `None`, no windowing
+            is performed. (default: :obj:`None`)
+        max_task_num (int, optional): The maximum number of planned
+            tasks in one round. (default: :obj:3)
+    """
+
+    def __init__(
+        self,
+        role_name: str,
+        objective: Union[str, TextPrompt],
+        model: Optional[BaseModelBackend] = None,
+        output_language: Optional[str] = None,
+        message_window_size: Optional[int] = None,
+        max_task_num: Optional[int] = 3,
+    ) -> None:
+        task_creation_prompt = TextPrompt(
+            """Create new a task with the following objective: {objective}.
+Never forget you are a Task Creator of {role_name}.
+You must instruct me based on my expertise and your needs to solve the task.
+You should consider past solved tasks and in-progress tasks: {task_list}.
+The new created tasks must not overlap with these past tasks.
+The result must be a numbered list in the format:
+
+    #. First Task
+    #. Second Task
+    #. Third Task
+
+You can only give me up to {max_task_num} tasks at a time. \
+Each task should be concise, concrete and doable for a {role_name}.
+You should make task plan and not ask me questions.
+If you think no new tasks are needed right now, write "No tasks to add."
+Now start to give me new tasks one by one. No more than three tasks.
+Be concrete.
+"""
+        )
+
+        self.task_creation_prompt = task_creation_prompt.format(
+            objective=objective, role_name=role_name, max_task_num=max_task_num
+        )
+        self.objective = objective
+
+        system_message = BaseMessage(
+            role_name="Task Creator",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You are a helpful task creator.",
+        )
+
+        super().__init__(
+            system_message,
+            model=model,
+            output_language=output_language,
+            message_window_size=message_window_size,
+        )
+
+    def run(
+        self,
+        task_list: List[str],
+    ) -> List[str]:
+        r"""Generate subtasks based on the previous task results and
+        incomplete task list.
+
+        Args:
+            task_list (List[str]): The completed or in-progress
+                tasks which should not overlap with new created tasks.
+
+        Returns:
+            List[str]: The new task list generated by the Agent.
+        """
+
+        if len(task_list) > 0:
+            task_creation_prompt = self.task_creation_prompt.format(
+                task_list=task_list
+            )
+        else:
+            task_creation_prompt = self.task_creation_prompt.format(
+                task_list=""
+            )
+
+        task_msg = BaseMessage.make_user_message(
+            role_name="Task Creator", content=task_creation_prompt
+        )
+        task_response = self.step(task_msg)
+
+        if task_response.terminated:
+            raise RuntimeError("Task creation failed.")
+        if len(task_response.msgs) == 0:
+            raise RuntimeError("Got no task creation message.")
+
+        sub_tasks_msg = task_response.msgs[0]
+        return get_task_list(sub_tasks_msg.content)
+
+
+@track_agent(name="TaskPrioritizationAgent")
+class TaskPrioritizationAgent(ChatAgent):
+    r"""An agent that helps re-prioritize the task list and
+    returns numbered prioritized list. Modified from
+    `BabyAGI <https://github.com/yoheinakajima/babyagi>`_.
+
+    Attributes:
+        task_prioritization_prompt (TextPrompt): A prompt for the agent to
+            prioritize tasks.
+
+    Args:
+        objective (Union[str, TextPrompt]): The objective of the Agent to
+            perform the task.
+        model (BaseModelBackend, optional): The LLM backend to use for
+            generating responses. (default: :obj:`OpenAIModel` with
+            `GPT_4O_MINI`)
+        output_language (str, optional): The language to be output by the
+            agent. (default: :obj:`None`)
+        message_window_size (int, optional): The maximum number of previous
+            messages to include in the context window. If `None`, no windowing
+            is performed. (default: :obj:`None`)
+    """
+
+    def __init__(
+        self,
+        objective: Union[str, TextPrompt],
+        model: Optional[BaseModelBackend] = None,
+        output_language: Optional[str] = None,
+        message_window_size: Optional[int] = None,
+    ) -> None:
+        task_prioritization_prompt = TextPrompt(
+            """Prioritize the following tasks : {task_list}.
+Consider the ultimate objective of you: {objective}.
+Tasks should be sorted from highest to lowest priority, where higher-priority \
+tasks are those that act as pre-requisites or are more essential for meeting \
+the objective. Return one task per line in your response.
+Do not remove or modify any tasks.
+The result must be a numbered list in the format:
+
+    #. First task
+    #. Second task
+
+The entries must be consecutively numbered, starting with 1.
+The number of each entry must be followed by a period.
+Do not include any headers before your ranked list or follow your list \
+with any other output."""
+        )
+
+        self.task_prioritization_prompt = task_prioritization_prompt.format(
+            objective=objective
+        )
+        self.objective = objective
+
+        system_message = BaseMessage(
+            role_name="Task Prioritizer",
+            role_type=RoleType.ASSISTANT,
+            meta_dict=None,
+            content="You are a helpful task prioritizer.",
+        )
+
+        super().__init__(
+            system_message,
+            model=model,
+            output_language=output_language,
+            message_window_size=message_window_size,
+        )
+
+    def run(
+        self,
+        task_list: List[str],
+    ) -> List[str]:
+        r"""Prioritize the task list given the agent objective.
+
+        Args:
+            task_list (List[str]): The unprioritized tasks of agent.
+
+        Returns:
+            List[str]: The new prioritized task list generated by the Agent.
+        """
+        task_prioritization_prompt = self.task_prioritization_prompt.format(
+            task_list=task_list
+        )
+
+        task_msg = BaseMessage.make_user_message(
+            role_name="Task Prioritizer", content=task_prioritization_prompt
+        )
+
+        task_response = self.step(task_msg)
+
+        if task_response.terminated:
+            raise RuntimeError("Task prioritization failed.")
+        if len(task_response.msgs) == 0:
+            raise RuntimeError("Got no task prioritization message.")
+
+        sub_tasks_msg = task_response.msgs[0]
+        return get_task_list(sub_tasks_msg.content)

camel/agents/tool_agents/__init__.py

@@ -0,0 +1,20 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from .base import BaseToolAgent
+from .hugging_face_tool_agent import HuggingFaceToolAgent
+
+__all__ = [
+    'BaseToolAgent',
+    'HuggingFaceToolAgent',
+]

camel/agents/tool_agents/base.py

@@ -0,0 +1,39 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from camel.agents import BaseAgent
+
+
+class BaseToolAgent(BaseAgent):
+    r"""Creates a :obj:`BaseToolAgent` object with the specified name and
+        description.
+
+    Args:
+        name (str): The name of the tool agent.
+        description (str): The description of the tool agent.
+    """
+
+    def __init__(self, name: str, description: str) -> None:
+        self.name = name
+        self.description = description
+
+    def reset(self) -> None:
+        r"""Resets the agent to its initial state."""
+        pass
+
+    def step(self) -> None:
+        r"""Performs a single step of the agent."""
+        pass
+
+    def __str__(self) -> str:
+        return f"{self.name}: {self.description}"

camel/agents/tool_agents/hugging_face_tool_agent.py

@@ -0,0 +1,206 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from typing import Any, Optional
+
+from camel.agents.tool_agents.base import BaseToolAgent
+
+
+# flake8: noqa :E501
+class HuggingFaceToolAgent(BaseToolAgent):
+    r"""Tool agent for calling HuggingFace models. This agent is a wrapper
+        around agents from the `transformers` library. For more information
+        about the available models, please see the `transformers` documentation
+        at https://huggingface.co/docs/transformers/transformers_agents.
+
+    Args:
+        name (str): The name of the agent.
+        *args (Any): Additional positional arguments to pass to the underlying
+            Agent class.
+        remote (bool, optional): Flag indicating whether to run the agent
+            remotely. (default: :obj:`True`)
+        **kwargs (Any): Additional keyword arguments to pass to the underlying
+            Agent class.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *args: Any,
+        remote: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        try:
+            # TODO: Support other tool agents
+            import transformers
+            from packaging import version
+
+            if version.parse(transformers.__version__) < version.parse(
+                "4.31.0"
+            ):
+                raise ValueError(
+                    "The version of \"transformers\" package should >= 4.31.0"
+                )
+
+            from transformers.tools import OpenAiAgent
+            from transformers.tools.agent_types import AgentImage
+        except (ImportError, ValueError):
+            raise ValueError(
+                "Could not import transformers tool agents. "
+                "Please setup the environment with "
+                "pip install huggingface_hub==0.14.1 transformers==4.31.0 diffusers accelerate==0.20.3 datasets torch soundfile sentencepiece opencv-python"
+            )
+        self.agent_image_type = AgentImage
+        self.agent = OpenAiAgent(*args, **kwargs)
+        description = f"""The `{name}` is a tool agent that can perform a variety of tasks including:
+- Document question answering: given a document (such as a PDF) in image format, answer a question on this document
+- Text question answering: given a long text and a question, answer the question in the text
+- Unconditional image captioning: Caption the image!
+- Image question answering: given an image, answer a question on this image
+- Image segmentation: given an image and a prompt, output the segmentation mask of that prompt
+- Speech to text: given an audio recording of a person talking, transcribe the speech into text
+- Text to speech: convert text to speech
+- Zero-shot text classification: given a text and a list of labels, identify to which label the text corresponds the most
+- Text summarization: summarize a long text in one or a few sentences
+- Translation: translate the text into a given language
+- Text downloading: to download a text from a web URL
+- Text to image: generate an image according to a prompt, leveraging stable diffusion
+- Image transformation: modify an image given an initial image and a prompt, leveraging instruct pix2pix stable diffusion
+- Text to video: generate a small video according to a prompt
+
+Here are some python code examples of what you can do with this agent:
+
+Single execution (step) mode, the single execution method is when using the step() method of the agent:
+```
+# Text to image
+rivers_and_lakes_image = {name}.step("Draw me a picture of rivers and lakes.")
+rivers_and_lakes_image.save("./rivers_and_lakes_image.png")
+
+# Text to image -> Image transformation
+sea_add_island_image = {name}.step("Draw me a picture of the sea then transform the picture to add an island")
+sea_add_island_image.save("./sea_add_island_image.png")
+
+# If you'd like to keep a state across executions or to pass non-text objects to the agent, 
+# you can do so by specifying variables that you would like the agent to use. For example,
+# you could generate the first image of rivers and lakes, and ask the model to update that picture to add an island by doing the following:
+picture = {name}.step("Generate a picture of rivers and lakes.")
+picture.save("./picture.png")
+updated_picture = {name}.step("Transform the image in `picture` to add an island to it.", picture=picture)
+updated_picture.save("./updated_picture.png")
+
+capybara_sea_image = {name}.step("Draw me a picture of the `prompt`", prompt="a capybara swimming in the sea")
+capybara_sea_image.save("./capybara_sea_image.png")
+
+# Document question answering
+answer = {name}.step(
+    "In the following `document`, where will the TRRF Scientific Advisory Council Meeting take place?",
+    document=document,
+)
+print(answer)
+
+
+# Text to image
+boat_image = {name}.step("Generate an image of a boat in the water")
+boat_image.save("./boat_image.png")
+
+# Unconditional image captioning
+boat_image_caption = {name}.step("Can you caption the `boat_image`?", boat_image=boat_image)
+print(boat_image_caption)
+
+# Text to image -> Unconditional image captioning -> Text to speech
+boat_audio = {name}.step("Can you generate an image of a boat? Please read out loud the contents of the image afterwards")
+
+# Text downloading
+document = {name}.step("Download the text from http://hf.co")
+print(document)
+
+# Text summarization
+summary = {name}.step("Summarize the following text: `document`", document=document)
+print(summary)
+
+# Text downloading -> Text summarization -> Text to speech
+audio = {name}.step("Read out loud the summary of http://hf.co")
+```
+
+Chat-based execution (chat), the agent also has a chat-based approach, using the chat() method:
+```
+# Clean the chat history
+{name}.reset()
+
+# Text to image
+capybara_image = {name}.chat("Show me an an image of a capybara")
+capybara_image.save("./capybara_image.png")
+
+# Image transformation
+transformed_capybara_image = {name}.chat("Transform the image so that it snows")
+transformed_capybara_image.save("./transformed_capybara_image.png")
+
+# Image segmentation
+segmented_transformed_capybara_image = {name}.chat("Show me a mask of the snowy capybaras")
+segmented_transformed_capybara_image.save("./segmented_transformed_capybara_image.png")
+```
+"""
+        super(HuggingFaceToolAgent, self).__init__(name, description)
+        self.remote = remote
+
+    def reset(self) -> None:
+        r"""Resets the chat history of the agent."""
+        self.agent.prepare_for_new_chat()
+
+    def step(
+        self,
+        *args: Any,
+        remote: Optional[bool] = None,
+        **kwargs: Any,
+    ) -> Any:
+        r"""Runs the agent in single execution mode.
+
+        Args:
+            *args (Any): Positional arguments to pass to the agent.
+            remote (bool, optional): Flag indicating whether to run the agent
+                remotely. Overrides the default setting. (default: :obj:`None`)
+            **kwargs (Any): Keyword arguments to pass to the agent.
+
+        Returns:
+            str: The response from the agent.
+        """
+        if remote is None:
+            remote = self.remote
+        agent_output = self.agent.run(*args, remote=remote, **kwargs)
+        if isinstance(agent_output, self.agent_image_type):
+            agent_output = agent_output.to_raw()
+        return agent_output
+
+    def chat(
+        self,
+        *args: Any,
+        remote: Optional[bool] = None,
+        **kwargs: Any,
+    ) -> Any:
+        r"""Runs the agent in a chat conversation mode.
+
+        Args:
+            *args (Any): Positional arguments to pass to the agent.
+            remote (bool, optional): Flag indicating whether to run the agent
+                remotely. Overrides the default setting. (default: :obj:`None`)
+            **kwargs (Any): Keyword arguments to pass to the agent.
+
+        Returns:
+            str: The response from the agent.
+        """
+        if remote is None:
+            remote = self.remote
+        agent_output = self.agent.chat(*args, remote=remote, **kwargs)
+        if isinstance(agent_output, self.agent_image_type):
+            agent_output = agent_output.to_raw()
+        return agent_output

camel/benchmarks/__init__.py

@@ -0,0 +1,30 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from .apibank import APIBankBenchmark
+from .apibench import APIBenchBenchmark
+from .base import BaseBenchmark
+from .gaia import DefaultGAIARetriever, GAIABenchmark
+from .nexus import NexusBenchmark
+from .ragbench import RAGBenchBenchmark
+
+__all__ = [
+    "BaseBenchmark",
+    "GAIABenchmark",
+    "DefaultGAIARetriever",
+    "NexusBenchmark",
+    "APIBenchBenchmark",
+    "APIBankBenchmark",
+    "RAGBenchBenchmark",
+]

camel/benchmarks/apibank.py

@@ -0,0 +1,565 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import json
+import logging
+import os
+import random
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+import numpy as np
+from rouge import Rouge
+from tqdm import tqdm
+
+from camel.agents import ChatAgent
+from camel.benchmarks.base import BaseBenchmark
+from camel.messages import BaseMessage
+from camel.utils import download_github_subdirectory
+
+logger = logging.getLogger(__name__)
+
+# Add current folder to sys.path to enable relative import
+current_folder = os.getcwd()
+if current_folder not in sys.path:
+    sys.path.append(current_folder)
+
+
+def process_messages(
+    chat_history: List[Dict[str, Any]],
+    prompt: str,
+) -> List[Dict[str, str]]:
+    """
+    Processes chat history into a structured format for further use.
+
+    Args:
+        chat_history (List[Dict[str, Any]):
+            A list of dictionaries representing the chat history.
+        prompt (str): A propmt to be set as the system message.
+
+    Returns:
+        List[Dict[str, str]]: A list of dictionaries representing
+            the processed messages, where each dictionary has:
+        - 'role': The role of the message ('system', 'user', or 'assistant').
+        - 'content': The content of the message, including formatted
+            API responses when applicable.
+    """
+    messages = [{'role': 'system', 'content': prompt}]
+    for item in chat_history:
+        role_map = {'User': 'user', 'AI': 'assistant', 'API': 'system'}
+        chat_role = role_map.get(
+            item['role'], 'unknown'
+        )  # default role to 'unknown'
+        if item['role'] == 'API':
+            chat_content = '[{}({})] Response: {}'.format(
+                item['api_name'],
+                ', '.join(
+                    [
+                        '{}=\'{}\''.format(k, v)
+                        for k, v in item['param_dict'].items()
+                    ]
+                ),
+                str(item['result']['output']),
+            )
+        else:
+            chat_content = item['text']
+        messages.append({'role': chat_role, 'content': chat_content})
+    return messages
+
+
+class APIBankBenchmark(BaseBenchmark):
+    r"""API-Bank Benchmark adapted from `API-Bank:
+    A Comprehensive Benchmark for Tool-Augmented LLMs`
+    <https://github.com/AlibabaResearch/DAMO-ConvAI/tree/main/api-bank>.
+
+    Args:
+        save_to (str): The file to save the results.
+        processes (int, optional): The number of processes to use.
+            (default: :obj:`1`)
+    """
+
+    def __init__(
+        self,
+        save_to: str,
+        processes: int = 1,
+    ):
+        r"""Initialize the APIBank benchmark.
+
+        Args:
+            save_to (str): The file to save the results.
+            processes (int, optional): The number of processes to use for
+                parallel processing. (default: :obj:`1`)
+        """
+        # Predefine data_dir for better import management
+        super().__init__("apibank", "api_bank", save_to, processes)
+        self._data: Dict[str, List[APIBankSample]] = dict()  # type: ignore[assignment]
+
+    def download(self):
+        r"""Download APIBank dataset and code from Github."""
+
+        repo = "AlibabaResearch/DAMO-ConvAI"
+        subdir = "api-bank"
+        data_dir = self.data_dir
+
+        download_github_subdirectory(repo, subdir, data_dir)
+
+        sys.path.insert(0, self.data_dir)
+        logger.info("Download completed.")
+
+    def load(self, level: str, force_download: bool = False):  # type: ignore[override]
+        r"""Load the APIBank Benchmark dataset.
+
+        Args:
+            level (str): Level to run benchmark on.
+            force_download (bool, optional): Whether to
+                force download the data.
+        """
+        if force_download:
+            logger.info("Force downloading data.")
+            self.download()
+
+        if level == "level-1":
+            file_path = Path("api_bank/lv1-lv2-samples/level-1-given-desc")
+        elif level == 'level-2':
+            file_path = Path("api_bank/lv1-lv2-samples/level-2-toolsearcher")
+        jsonl_files = [
+            f for f in os.listdir(file_path) if f.endswith('.jsonl')
+        ]
+        for file in tqdm(jsonl_files, desc="Processing files"):
+            history = []
+            with open(file_path / file, 'r') as f:
+                for line in f:
+                    history.append(json.loads(line))
+                samples = APIBankSample.from_chat_history(history)
+                self._data[file.rsplit('.', 1)[0]] = samples
+
+        # Change import to relative import in the downloaded python files
+        def process_files(folder_path, replacements):
+            r"""Replace absolute imports in downloaded files with
+            relative import."""
+            for file in os.listdir(folder_path):
+                if file.endswith(".py"):
+                    file_path = os.path.join(folder_path, file)
+                    try:
+                        with open(file_path, "r", encoding="utf-8") as file:
+                            content = file.read()
+
+                        original_content = content
+
+                        for pattern, replacement in replacements:
+                            content = re.sub(pattern, replacement, content)
+
+                        if content != original_content:
+                            with open(
+                                file_path, "w", encoding="utf-8"
+                            ) as file:
+                                file.write(content)
+                            logger.info(f"Updated file: {file_path}")
+
+                    except Exception as e:
+                        logger.info(f"Error processing file {file_path}: {e}")
+
+        api_bank_folder = "api_bank"
+        apis_folder = os.path.join(api_bank_folder, "apis")
+
+        apis_replacements = [
+            (r"from apis.api", "from .api"),
+            (r"from apis import", "from .api import"),
+        ]
+
+        api_bank_replacements = [
+            (r"from apis", "from .apis"),
+            (r"from api_call_extraction", "from .api_call_extraction"),
+            (r"f'{basename}", r"f'api_bank.{basename}"),
+        ]
+
+        process_files(apis_folder, apis_replacements)
+        process_files(api_bank_folder, api_bank_replacements)
+
+    def run(  # type: ignore[override, return]
+        self,
+        agent: ChatAgent,
+        level: Literal["level-1", "level-2"],
+        api_test_enabled=True,
+        randomize: bool = False,
+        subset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        r"""Run the benchmark.
+
+        Args:
+            agent (ChatAgent): The agent to run the
+                benchmark.
+            level (Literal['level-1', 'level-2']):
+                The level to run the benchmark on.
+            randomize (bool, optional): Whether to
+                randomize the data.
+            api_test_enabled (bool): Whether to test
+            API calling (`True`) or response (`False`)
+                (default: :obj:`False`)
+            subset (Optional[int], optional):
+            The subset of data to run.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, Any]: The results of the benchmark.
+        """
+        logger.info(f"Running APIBench benchmark on {level}.")
+        self.load(level)
+        datas = self._data
+
+        # Shuffle and subset data if necessary
+        if randomize:
+            randomized_items = list(datas.items())
+            random.shuffle(randomized_items)
+            datas = dict(randomized_items)
+        if subset:
+            datas = dict(list(datas.items())[:subset])
+
+        logger.info(f"Number of tasks: {len(datas)}")
+
+        # Initialize results storage
+        self._results = []
+
+        # The following code are adapted from the evaluator
+        # from the original repo:
+        tool_search_enabled = level == "level-2"
+        dialog_test_enabled = not api_test_enabled
+        total_api_calls, correct_api_calls, rougel_scores = 0, 0, []
+
+        with open(self.save_to, "w") as f:
+            for test in tqdm(datas, desc="Running"):
+                samples = self._data[test]
+                evaluator = Evaluator(samples)  # type: ignore[arg-type]
+
+                for sample_id in evaluator.get_all_sample_ids():
+                    # Process sample and generate response
+                    sample = evaluator.dataset[sample_id]
+
+                    if (
+                        sample.ground_truth['role'] == 'API'
+                        and api_test_enabled
+                    ):
+                        if tool_search_enabled:
+                            _, chat_history = evaluator.get_model_input(
+                                sample_id
+                            )
+                            api_descriptions = evaluator.get_api_description(
+                                'ToolSearcher'
+                            )
+                        else:
+                            api_descriptions, chat_history = (
+                                evaluator.get_model_input(sample_id)
+                            )
+                        messages = process_messages(
+                            chat_history, API_CALL_PROMPT + api_descriptions
+                        )
+                        model_output = agent_call(messages, agent)
+                        api_call = get_api_call(model_output)
+
+                        # Evaluate API call
+                        if api_call:
+                            try:
+                                correct, model_output_result = (
+                                    evaluator.evaluate(sample_id, api_call)
+                                )
+                            except AssertionError as e:
+                                if 'The API name is not correct.' not in str(
+                                    e
+                                ):
+                                    raise e
+                                logging.info('AssertionError: {}'.format(e))
+                                correct = False
+                        else:
+                            model_output_result = 'No API call found'
+                            correct = False
+                        if correct:
+                            correct_api_calls += 1
+                            logging.info(
+                                'Correct API call: {} Ground truth: {}'.format(
+                                    api_call, sample.ground_truth
+                                )
+                            )
+                        else:
+                            logging.info(
+                                'Incorrect model output: {} Result: {} \
+                                Ground truth: {} File: {} Sample ID: {} \
+                                Messages: {}'.format(
+                                    model_output.replace('\n', ' '),
+                                    model_output_result,
+                                    sample.ground_truth,
+                                    test,
+                                    sample_id,
+                                    messages[1:],
+                                )
+                            )
+                        total_api_calls += 1
+                        self._results.append(
+                            {
+                                'Role': 'API',
+                                'Model_output': model_output,
+                                'Model_output_result': model_output_result,
+                                'Ground_truth': sample.ground_truth,
+                                'Test': test,
+                                'Correct': correct,
+                            }
+                        )
+                        f.write(json.dumps(self._results[-1], indent=2) + "\n")
+
+                    elif (
+                        sample.ground_truth['role'] == 'AI'
+                        and dialog_test_enabled
+                    ):
+                        # Process sample and generate response
+                        api_descriptions, chat_history = (
+                            evaluator.get_model_input(sample_id)
+                        )
+
+                        messages = process_messages(
+                            chat_history, RESPONSE_PROMPT + api_descriptions
+                        )
+                        model_output = agent_call(messages, agent)
+
+                        # Evaluate model response
+                        if model_output:
+                            score = evaluator.evaluate(sample_id, model_output)
+                        else:
+                            score = 0
+                        rougel_scores.append(score)
+                        if score < 0.2:
+                            logging.info(
+                                'Low score: {} Score: {} Ground truth: {} \
+                                Test: {} Sample ID: {} \
+                                Messages: {}'.format(
+                                    model_output.replace('\n', ' '),
+                                    score,
+                                    sample.ground_truth,
+                                    test,
+                                    sample_id,
+                                    messages[1:],
+                                )
+                            )
+
+                        self._results.append(
+                            {
+                                'Role': 'AI',
+                                'Model_output': model_output,
+                                'Score': score,
+                                'Ground_truth': sample.ground_truth,
+                                'Test': test,
+                            }
+                        )
+                        f.write(json.dumps(self._results[-1], indent=2) + "\n")
+
+                    f.flush()
+
+        if api_test_enabled:
+            return {
+                'total': total_api_calls,
+                'correct': correct_api_calls,
+                "accuracy": correct_api_calls / total_api_calls
+                if total_api_calls
+                else 0,
+            }
+        elif dialog_test_enabled:
+            return {'Dialog_score': np.mean(rougel_scores)}
+
+
+# The following code are migrated from the original repo:
+# https://github.com/AlibabaResearch/DAMO-ConvAI/tree/main/api-bank
+def agent_call(messages: List[Dict], agent: ChatAgent):
+    r"""Add messages to agent memory and get response."""
+    for i, msg in enumerate(messages):
+        if msg['role'] == 'user':
+            message = BaseMessage.make_user_message(
+                role_name="CAMEL User", content=msg['content']
+            )
+        elif msg['role'] == 'assistant':
+            message = BaseMessage.make_assistant_message(
+                role_name="CAMEL Assistant", content=msg['content']
+            )
+        elif msg['role'] == 'system':
+            message = BaseMessage.make_assistant_message(
+                role_name="System", content=msg['content']
+            )
+        else:
+            raise ValueError(f"Unrecognized role: {msg['role']}")
+
+        if i == len(messages) - 1:
+            break
+        agent.record_message(message)
+
+    response = agent.step(message)
+    model_output = response.msgs[0].content
+    agent.reset()
+    return model_output
+
+
+def calculate_rouge_l_score(reference, hypothesis):
+    r"""Calculate rouge l score between hypothesis and reference."""
+    rouge = Rouge()
+    scores = rouge.get_scores(hypothesis, reference)
+    rouge_l_score = scores[0]['rouge-l']['f']
+    return rouge_l_score
+
+
+def get_api_call(model_output):
+    r"""Parse api call from model output."""
+    api_call_pattern = r"\[(\w+)\((.*)\)\]"
+    api_call_pattern = re.compile(api_call_pattern)
+    match = api_call_pattern.search(model_output)
+    if match:
+        return match.group(0)
+    else:
+        return None
+
+
+class APIBankSample:
+    r"""APIBank sample used to load the datasets."""
+
+    def __init__(self, chat_history, apis, ground_truth):
+        self.chat_history = chat_history
+        self.apis = apis
+        self.ground_truth = ground_truth
+
+    def __repr__(self):
+        return 'Sample(chat_history={}, apis={}, ground_truth={})'.format(
+            self.chat_history, self.apis, self.ground_truth
+        )
+
+    @classmethod
+    def from_chat_history(cls, chat_history):
+        apis = set()
+        api_positions = []
+        for i, item in enumerate(chat_history):
+            if item['role'] == 'API':
+                apis.add(item['api_name'])
+                api_positions.append(i)
+
+        samples = []
+        for i in api_positions:
+            sample = cls(chat_history[:i], apis, chat_history[i])
+            samples.append(sample)
+            sample = cls(chat_history[: i + 1], apis, chat_history[i + 1])
+            samples.append(sample)
+
+        return samples
+
+
+class Evaluator:
+    r"""Evaluator for APIBank benchmark."""
+
+    def __init__(self, samples: List[APIBankSample]):
+        # Place holder for import as the import
+        # only works after the files have been downloaded
+        try:
+            from api_bank.tool_manager import (  # type: ignore[import-not-found]
+                ToolManager,
+            )
+        except Exception as e:
+            logger.info(f"{e}, Module will be imported after download.")
+        self.dataset = samples
+        self.sample_ids = list(range(len(self.dataset)))
+        os.chdir("api_bank")
+        self.tool_manager = ToolManager("apis")
+        os.chdir("..")
+
+    def get_all_sample_ids(self):
+        return self.sample_ids
+
+    def get_api_description(self, api_name):
+        return self.tool_manager.get_api_description(api_name)
+
+    def get_model_input(self, sample_id: int):
+        sample = self.dataset[sample_id]
+        apis = sample.apis
+        chat_history = sample.chat_history
+        api_descriptions = []
+        for api_name in apis:
+            api_descriptions.append(
+                self.tool_manager.get_api_description(api_name)
+            )
+        api_description = '\n'.join(api_descriptions)
+        return api_description, chat_history
+
+    def evaluate(self, sample_id, model_output):
+        try:
+            from api_bank.api_call_extraction import (  # type: ignore[import-not-found]
+                parse_api_call,
+            )
+        except Exception as e:
+            logger.info(f"{e}, Module will be imported after download.")
+        sample = self.dataset[sample_id]
+        ground_truth = sample.ground_truth
+        if ground_truth['role'] == 'API':
+            api_name, param_dict = parse_api_call(model_output)
+            if api_name != ground_truth['api_name']:
+                return False, 'API Name Mismatch: {} vs {}'.format(
+                    api_name, ground_truth['api_name']
+                )
+            try:
+                result = self.tool_manager.api_call(api_name, **param_dict)
+            except Exception as e:
+                return False, str(e)
+            api = self.tool_manager.init_tool(api_name)
+            try:
+                correct = api.check_api_call_correctness(
+                    result, ground_truth['result']
+                )
+            except KeyError:
+                correct = False
+                result = 'KeyError' + str(result)
+            return correct, result
+        elif ground_truth['role'] == 'AI':
+            score = calculate_rouge_l_score(ground_truth['text'], model_output)
+            return round(score, 4)
+
+
+API_CALL_PROMPT = '''
+Based on the given API description and the existing \
+conversation history 1..t, please generate the API request \
+that the AI should call in step t+1 and output it in the \
+format of [ApiName(key1='value1', key2='value2', ...)], \
+replace the ApiName with the actual API name, and \
+replace the key and value with the actual parameters. \
+Your output should start with a square bracket "[" \
+and end with a square bracket "]". Do not output any \
+other explanation or prompt or the result of the API call in your output. 
+This year is 2023.
+Input: 
+User: [User's utterence]
+AI: [AI's utterence]
+
+Expected output:
+[ApiName(key1='value1', key2='value2', ...)]
+
+API descriptions:
+'''
+
+RESPONSE_PROMPT = '''
+Based on the given API description and the existing \
+conversation history 1..t, please generate the next \
+dialog that the AI should response after the API call t.
+This year is 2023.
+Input: 
+User: [User's utterence]
+AI: [AI's utterence]
+[ApiName(key1='value1', key2='value2', …)]
+
+Expected output:
+AI: [AI's utterence]
+
+API descriptions:
+'''

camel/benchmarks/apibench.py

@@ -0,0 +1,500 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import json
+import logging
+import random
+from pathlib import Path
+from typing import Any, Dict, Literal, Optional
+
+import tree_sitter_python as tspython
+from tqdm import tqdm
+from tree_sitter import Language, Parser
+
+from camel.agents import ChatAgent
+from camel.benchmarks.base import BaseBenchmark
+from camel.messages import BaseMessage
+from camel.utils import download_github_subdirectory
+
+logger = logging.getLogger(__name__)
+
+
+# Mapping of dataset names to file names
+# 'Oracle' retriver used here which means all the full
+# API documentation will be included in the prompt
+dataset_mapping = {
+    "huggingface": {
+        "api": "huggingface_api.jsonl",
+        "eval": "huggingface_eval.json",
+        "train": "huggingface_train.json",
+        "questions": "questions_huggingface_oracle.jsonl",
+    },
+    "tensorflowhub": {
+        "api": "tensorflowhub_api.jsonl",
+        "eval": "tensorflow_eval.json",
+        "train": "tensorflow_train.json",
+        "questions": "questions_tensorflowhub_oracle.jsonl",
+    },
+    "torchhub": {
+        "api": "torchhub_api.jsonl",
+        "eval": "torchhub_eval.json",
+        "train": "torchhub_train.json",
+        "questions": "questions_torchhub_oracle.jsonl",
+    },
+}
+
+
+# This function is migrated from the original repo:
+# https://github.com/ShishirPatil/gorilla
+def encode_question(question: str, dataset_name: str) -> str:
+    r"""Encode multiple prompt instructions into a single string."""
+
+    if dataset_name == "torchhub":
+        domains = "1. $DOMAIN is inferred from the task description and \
+        should include one of {Classification, Semantic Segmentation, \
+        Object Detection, Audio Separation, Video Classification, \
+        Text-to-Speech}."
+    elif dataset_name == "huggingface":
+        domains = "1. $DOMAIN should include one of {Multimodal Feature \
+            Extraction, Multimodal Text-to-Image, Multimodal \
+            Image-to-Text, Multimodal Text-to-Video, \
+            Multimodal Visual Question Answering, Multimodal Document \
+            Question Answer, Multimodal Graph Machine Learning, \
+            Computer Vision Depth Estimation, Computer Vision Image \
+            Classification, Computer Vision Object Detection, \
+            Computer Vision Image Segmentation, Computer Vision \
+            Image-to-Image, Computer Vision Unconditional \
+            Image Generation, Computer Vision Video Classification, \
+            Computer Vision Zero-Shor Image Classification, \
+            Natural Language Processing Text Classification, \
+            Natural Language Processing Token Classification, \
+            Natural Language Processing Table Question Answering, \
+            Natural Language Processing Question Answering, \
+            Natural Language Processing, Zero-Shot Classification \
+            Natural Language Processing Translation, Natural Language \
+            Processing Summarization, Natural Language Processing \
+            Conversational, Natural Language Processing Text \
+            Generation, Natural Language Processing Fill-Mask, \
+            Natural Language Processing Text2Text Generation, \
+            Natural Language Processing Sentence Similarity, \
+            Audio Text-to-Speech, Audio Automatic Speech Recognition, \
+            Audio Audio-to-Audio, Audio Audio Classification, \
+            Audio Voice Activity Detection, Tabular Tabular \
+            Classification, Tabular Tabular Regression, \
+            Reinforcement Learning Reinforcement Learning, \
+            Reinforcement Learning Robotics }"
+    elif dataset_name == "tensorflowhub":
+        domains = "1. $DOMAIN is inferred from the task description \
+        and should include one of {text-sequence-alignment, \
+        text-embedding, text-language-model, text-preprocessing, \
+        text-classification, text-generation, text-question-answering, \
+        text-retrieval-question-answering, text-segmentation, \
+        text-to-mel, image-classification, image-feature-vector, \
+        image-object-detection, image-segmentation, \
+        image-generator, image-pose-detection, image-rnn-agent, \
+        image-augmentation, image-classifier, image-style-transfer, \
+        image-aesthetic-quality, image-depth-estimation, \
+        image-super-resolution, image-deblurring, image-extrapolation, \
+        image-text-recognition, image-dehazing, image-deraining, \
+        image-enhancemenmt, image-classification-logits, \
+        image-frame-interpolation, image-text-detection, image-denoising, \
+        image-others, video-classification, video-feature-extraction, \
+        video-generation, video-audio-text, video-text, \
+        audio-embedding, audio-event-classification, audio-command-detection, \
+        audio-paralinguists-classification, audio-speech-to-text, \
+        audio-speech-synthesis, audio-synthesis, audio-pitch-extraction}"
+    else:
+        logger.info("Error: API name is not supported.")
+
+    prompt = (
+        question
+        + "\nWrite a python program in 1 to 2 lines to call API in "
+        + dataset_name
+        + ".\n\nThe answer should follow the format: <<<domain>>> $DOMAIN, \
+        <<<api_call>>>: $API_CALL, <<<api_provider>>>: $API_PROVIDER, \
+        <<<explanation>>>: $EXPLANATION, <<<code>>>: $CODE}. \
+        Here are the requirements:\n"
+        + domains
+        + "\n2. The $API_CALL should have only 1 line of code \
+        that calls api.\n 3. The $API_PROVIDER should be the \
+        programming framework used.\n4. $EXPLANATION should be \
+        a step-by-step explanation.\n5. The $CODE is the python code.\n6. \
+        Do not repeat the format in your answer."
+    )
+    return prompt
+
+
+class APIBenchBenchmark(BaseBenchmark):
+    r"""APIBench Benchmark adopted from `Gorilla: Large Language Model
+    Connected with Massive APIs`
+    <https://huggingface.co/datasets/gorilla-llm/APIBench>.
+
+    Args:
+        data_dir (str): The directory to save the data.
+        save_to (str): The file to save the results.
+        processes (int, optional): The number of processes to use.
+            (default: :obj:`1`)
+    """
+
+    # TODO: Integrate retriever (pending)
+
+    def __init__(
+        self,
+        data_dir: str,
+        save_to: str,
+        processes: int = 1,
+    ):
+        r"""Initialize the APIBench benchmark.
+
+        Args:
+            data_dir (str): The directory to save the data.
+            save_to (str): The file to save the results.
+            processes (int, optional): The number of processes to use for
+                parallel processing. (default: :obj:`1`)
+        """
+        super().__init__("apibench", data_dir, save_to, processes)
+
+    def download(self):
+        r"""Download the APIBench dataset."""
+        from huggingface_hub import snapshot_download
+
+        snapshot_download(
+            repo_id="gorilla-llm/APIBench",
+            repo_type="dataset",
+            local_dir=self.data_dir,
+            local_dir_use_symlinks=True,
+        )
+
+        repo = "ShishirPatil/gorilla"
+        subdir = "/gorilla/eval/eval-data/questions"
+        data_dir = self.data_dir
+
+        download_github_subdirectory(repo, subdir, data_dir)
+
+    def load(self, dataset_name: str, force_download: bool = False):  # type: ignore[override]
+        r"""Load the APIBench Benchmark dataset.
+
+        Args:
+            dataset_name (str): Name of the specific dataset to be loaded.
+            force_download (bool, optional): Whether to force
+                download the data. (default: :obj:`False`)
+        """
+
+        if force_download:
+            logger.info("Force downloading data.")
+            self.download()
+
+        def load_json_lines(file_path: Path):
+            r"""Helper function to load JSON lines from a file."""
+            try:
+                with open(file_path, "r") as f:
+                    return [json.loads(line) for line in f]
+            except FileNotFoundError:
+                raise FileNotFoundError(f"File not found: {file_path}")
+            except json.JSONDecodeError as e:
+                raise ValueError(
+                    f"Error decoding JSON in file {file_path}: {e}"
+                )
+
+        dataset_path = self.data_dir / dataset_name
+        if not dataset_path.exists():
+            raise FileNotFoundError(
+                f"Dataset directory does not exist: {dataset_path}"
+            )
+
+        for label in ['api', 'eval', 'questions']:
+            file_name = dataset_mapping[dataset_name][label]
+            file_path = (
+                dataset_path / file_name
+                if label == 'questions'
+                else self.data_dir / file_name
+            )
+
+            # Load data based on label type
+            if label in ['api', 'questions', 'eval']:
+                data = load_json_lines(file_path)
+
+                if label == 'eval':
+                    # Extract 'api_data' specifically for eval label
+                    data = [item['api_data'] for item in data]
+
+                self._data[label] = data
+            else:
+                raise ValueError(f"Unknown label: {label}")
+
+        ast_database = []
+        for data in self._data['api']:
+            ast_tree = ast_parse(data['api_call'])
+            ast_database.append(ast_tree)
+        self._data['ast'] = ast_database
+
+    def run(  # type: ignore[override]
+        self,
+        agent: ChatAgent,
+        dataset_name: Literal["huggingface", "tensorflowhub", "torchhub"],
+        randomize: bool = False,
+        subset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        r"""Run the benchmark.
+
+        Args:
+            agent (ChatAgent): The agent to run the
+                benchmark.
+            dataset_name (Literal["huggingface",
+                "tensorflowhub", "torchhub"]):
+                The dataset to run the benchmark.
+            randomize (bool, optional): Whether to randomize the data.
+                (default: :obj:`False`)
+            subset (Optional[int], optional): The subset of data to run.
+                (default: :obj:`None`)
+        """
+
+        if dataset_name not in dataset_mapping:
+            raise ValueError(f"Invalid value for dataset: {dataset_name}.")
+
+        logger.info(f"Running APIBench benchmark on {dataset_name}.")
+        self.load(dataset_name)
+        datas = self._data['questions']
+
+        # Shuffle and subset data if necessary
+        if randomize:
+            random.shuffle(datas)
+        if subset:
+            datas = datas[:subset]
+
+        logger.info(f"Number of tasks: {len(datas)}")
+
+        # Initialize results storage
+        self._results = []
+
+        with open(self.save_to, "w") as f:
+            for question in tqdm(datas, desc="Running"):
+                prompt = encode_question(question["text"], dataset_name)
+                msg = BaseMessage.make_user_message(
+                    role_name="User", content=prompt
+                )
+                try:
+                    # Generate response
+                    responses = agent.step(msg)
+                    response = responses.msgs[0].content
+                    api_database = self._data['api']
+                    qa_pairs = self._data['eval']
+                    ast_database = self._data['ast']
+                    question_id = question['question_id']
+
+                    # Evaluate response
+                    error, correct, hallucination = evaluate_response(
+                        response,
+                        question_id,
+                        dataset_name,
+                        api_database,
+                        qa_pairs,
+                        ast_database,
+                    )
+                    self._results.append(
+                        {
+                            "question": question,
+                            "agent_response": response,
+                            "correct": correct,
+                            "hallucination": hallucination,
+                            "error": str(error) if error else None,
+                        }
+                    )
+                except Exception as e:
+                    logger.warning(
+                        f"Error in processing task: {question}: {e}"
+                    )
+                    self._results.append(
+                        {
+                            "question": question,
+                            "agent_response": None,
+                            "correct": False,
+                            "hallucination": False,
+                            "error": str(e),
+                        }
+                    )
+
+                agent.reset()
+
+                f.write(json.dumps(self._results[-1], indent=2) + "\n")
+                f.flush()
+
+        total = len(self._results)
+        correct = sum(r["correct"] for r in self.results)
+        hallucination = sum(r["hallucination"] for r in self.results)
+
+        return {
+            "total": total,
+            "correct": correct,
+            "hallucination": hallucination,
+            "accuracy": correct / total if total else "N/A",
+            "hallucination rate": hallucination / total if total else "N/A",
+        }
+
+
+# This code is modified from the
+# evaluators in the original repo
+# https://github.com/ShishirPatil/gorilla
+# Get all the subtrees given a root_node
+def get_all_sub_trees(root_node):
+    node_stack = []
+    sub_tree_sexp_list = []
+    depth = 1
+    # text = root_node.text
+    node_stack.append([root_node, depth])
+    while len(node_stack) != 0:
+        cur_node, cur_depth = node_stack.pop()
+        if cur_node.child_count > 0:
+            sub_tree_sexp_list.append(
+                [
+                    str(cur_node),
+                    cur_depth,
+                    cur_node,
+                    cur_node.children[0].text,
+                ]
+            )
+        else:
+            sub_tree_sexp_list.append(
+                [str(cur_node), cur_depth, cur_node, None]
+            )
+        for child_node in cur_node.children:
+            if len(child_node.children) != 0:
+                depth = cur_depth + 1
+                node_stack.append([child_node, depth])
+    return sub_tree_sexp_list
+
+
+# Parse the program into AST trees
+def ast_parse(candidate):
+    PY_LANGUAGE = Language(tspython.language())
+    parser = Parser(PY_LANGUAGE)
+
+    candidate_tree = parser.parse(bytes(candidate, "utf8")).root_node
+    return candidate_tree
+
+
+# Get all the arguments in the ast tree
+def get_args(node, dataset_name):
+    if node.child_count == 0:
+        return []
+    args_list = []
+    if dataset_name == "huggingface":
+        for child in node.children[0].children[0].children[1].children:
+            if "=" in child.text.decode():
+                args_list.append(child.children[2].text)
+            elif (
+                child.text.decode() != "("
+                and child.text.decode() != ")"
+                and child.text.decode() != ","
+            ):
+                args_list.append(child.text)
+    elif dataset_name == "tensorflowhub":
+        for child in node.children[0].children[0].children[1].children:
+            if (
+                'model=' in child.text.decode()
+                or 'model =' in child.text.decode()
+            ):
+                args_list.append(child.children[2].text)
+            elif (
+                child.text.decode() != "("
+                and child.text.decode() != ")"
+                and child.text.decode() != ","
+            ):
+                args_list.append(child.text)
+    elif dataset_name == "torchhub":
+        for child in node.children[0].children[0].children[1].children:
+            if (
+                "repo_or_dir" in child.text.decode()
+                or "model" in child.text.decode()
+            ):
+                args_list.append(child.children[2].text)
+    return args_list
+
+
+# Check if there is an api match
+def ast_check(candidate_subtree_list, base_tree_list, dataset_name):
+    for idx, base_tree in enumerate(base_tree_list):
+        if base_tree.children[0].children[0].child_count == 0:
+            continue
+        api_name = base_tree.children[0].children[0].children[0].text
+        for candidate_tree in candidate_subtree_list:
+            if candidate_tree[3] == api_name:
+                break
+        # Now we have a sub-tree
+        candidate_tree = candidate_tree[2]
+        args_list = get_args(base_tree, dataset_name)
+        if len(args_list) == 0:
+            continue
+        ast_match = True
+        for arg in args_list:
+            if (
+                arg.decode().lstrip("'").rstrip("'")
+                not in candidate_tree.text.decode()
+            ):
+                ast_match = False
+                break
+        if ast_match:
+            return idx
+    return -1
+
+
+def evaluate_response(
+    response, question_id, dataset_name, api_database, qa_pairs, ast_database
+):
+    try:
+        # Index the "api_call" domain
+        output = response.split("api_call")
+        if len(output) == 1:
+            api_call = output[0]
+        else:
+            # Parse the output
+            output = output[1].split("api_provider")[0]
+            if ":" not in output:
+                start = 0
+            else:
+                start = output.index(":")
+            if ")" not in output:
+                end = -2
+            else:
+                end = output.rindex(")")
+            api_call = output[start + 2 : end + 1]
+
+        try:
+            ast_tree = ast_parse(api_call)
+        except Exception as parse_error:
+            print(f"Error parsing api_call: {api_call}, error: {parse_error}")
+            return parse_error, False, False
+        # Search for a subtree
+        ast_subtree_list = get_all_sub_trees(ast_tree)
+        # Check which ast tree is matching
+        database_index = ast_check(
+            ast_subtree_list, ast_database, dataset_name
+        )
+        # We cannot index this ast in our database
+        if database_index == -1:
+            halluncination = True
+            correct = False
+        # We index our reference api_call
+        ref_api_call = api_database[database_index]
+        # Check for functionality
+        if ref_api_call['domain'] == qa_pairs[question_id - 1]['domain']:
+            correct = True
+            halluncination = False
+        else:
+            return None, False, False
+    except Exception as e:
+        print(f'Error parsing response: {response}, error: {e}')
+        return e, False, False
+
+    return None, correct, halluncination

camel/benchmarks/base.py

@@ -0,0 +1,152 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+from camel.agents import ChatAgent
+
+logger = logging.getLogger(__name__)
+
+
+class BaseBenchmark(ABC):
+    r"""Base class for benchmarks.
+
+    Attributes:
+        name (str): Name of the benchmark.
+        data_dir (str): Path to the data directory.
+        save_to (str): Path to save the results.
+        processes (int): Number of processes to use for parallel
+            processing. :(default: :obj:`1`)
+    """
+
+    def __init__(
+        self, name: str, data_dir: str, save_to: str, processes: int = 1
+    ):
+        r"""Initialize the benchmark.
+
+        Args:
+            name (str): Name of the benchmark.
+            data_dir (str): Path to the data directory.
+            save_to (str): Path to save the results.
+            processes (int): Number of processes to use for parallel
+                processing. :(default: :obj:`1`)
+
+        """
+        self.name = name
+        self.data_dir = Path(data_dir)
+        self.processes = processes
+        self.save_to = save_to
+        if not self.data_dir.exists():
+            logger.info(
+                f"Data directory {data_dir} does not exist. Creating it."
+            )
+            self.data_dir.mkdir(parents=True, exist_ok=True)
+        if not self.data_dir.is_dir():
+            raise NotADirectoryError(
+                f"Data directory {data_dir} is not a directory"
+            )
+        self._data: Dict[str, List[Dict[str, Any]]] = dict()
+        self._results: List[Dict[str, Any]] = []
+
+    @abstractmethod
+    def download(self) -> "BaseBenchmark":
+        r"""Download the benchmark data.
+
+        Returns:
+            BaseBenchmark: The benchmark instance.
+        """
+        pass
+
+    @abstractmethod
+    def load(self, force_download: bool = False) -> "BaseBenchmark":
+        r"""Load the benchmark data.
+
+        Args:
+            force_download (bool): Whether to force download the data.
+
+        Returns:
+            BaseBenchmark: The benchmark instance.
+        """
+        pass
+
+    @property
+    def train(self) -> List[Dict[str, Any]]:
+        r"""Get the training data.
+
+        Returns:
+            List[Dict[str, Any]]: The training data.
+        """
+        if not self._data:
+            logger.info("Data not loaded. Loading data.")
+            self.load()
+        return self._data["train"]
+
+    @property
+    def valid(self) -> List[Dict[str, Any]]:
+        r"""Get the validation data.
+
+        Returns:
+            List[Dict[str, Any]]: The validation data.
+        """
+        if not self._data:
+            logger.info("Data not loaded. Loading data.")
+            self.load()
+        return self._data["valid"]
+
+    @property
+    def test(self) -> List[Dict[str, Any]]:
+        r"""Get the test data.
+
+        Returns:
+            List[Dict[str, Any]]: The test data.
+        """
+        if not self._data:
+            logger.info("Data not loaded. Loading data.")
+            self.load()
+        return self._data["test"]
+
+    @abstractmethod
+    def run(
+        self,
+        agent: ChatAgent,
+        on: Literal["train", "valid", "test"],
+        randomize: bool = False,
+        subset: Optional[int] = None,
+        *args,
+        **kwargs,
+    ) -> "BaseBenchmark":
+        r"""Run the benchmark.
+
+        Args:
+            agent (ChatAgent): The chat agent.
+            on (str): The data split to run the benchmark on.
+            randomize (bool): Whether to randomize the data.
+            subset (int): The subset of the data to run the benchmark on.
+
+        Returns:
+            BaseBenchmark: The benchmark instance.
+        """
+        pass
+
+    @property
+    def results(self) -> List[Dict[str, Any]]:
+        r"""Get the results.
+
+        Returns:
+            List[Dict[str, Any]]: The results.
+        """
+        return self._results

camel/benchmarks/gaia.py

@@ -0,0 +1,478 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import json
+import logging
+import os
+import random
+import re
+import string
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional, Protocol, Union
+
+from tqdm import tqdm
+
+from camel.agents import ChatAgent
+from camel.benchmarks.base import BaseBenchmark
+from camel.messages import BaseMessage
+from camel.retrievers.auto_retriever import AutoRetriever
+
+logger = logging.getLogger(__name__)
+
+
+class RetrieverProtocol(Protocol):
+    r"""Protocol for the retriever class. Any retriever class implementing
+    this protocol can be used in the benchmark class.
+    """
+
+    def retrieve(
+        self, query: str, contents: List[str], **kwargs: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        r"""Retrieve the relevant content for the query.
+
+        Args:
+            query (str): The query to retrieve the content for.
+            contents (List[str]): The list of contents to search in.
+            **kwargs (Dict[str, Any]): Additional keyword arguments.
+
+        Returns:
+            Dict[str, Any]: The relevant content for the query.
+        """
+        ...
+
+    def reset(self, **kwargs) -> bool:
+        r"""Reset the retriever.
+        Some benchmarks may require resetting the retriever
+        after each query.
+
+        Args:
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            bool: True if the reset was successful, False otherwise.
+        """
+        ...
+
+
+class DefaultGAIARetriever(AutoRetriever):
+    r"""Default retriever for the GAIA benchmark.
+    This retriever uses AutoRetriever in camel to retrieve the content based on
+    the query.
+    """
+
+    def retrieve(
+        self, query: str, contents: List[str], **kwargs: Any
+    ) -> Dict[str, Any]:
+        r"""Retrieve the content based on the query.
+
+        Args:
+            query (str): The query to search for.
+            contents (List[str]): The list of contents to search from.
+            **kwargs (Any): The keyword arguments to pass to the
+                retriever.
+
+        Returns:
+            Dict[str, Any]: The retrieved content.
+        """
+        return self.run_vector_retriever(query, contents, **kwargs)  # type: ignore[arg-type]
+
+    def reset(self, **kwargs: Any) -> bool:
+        r"""Reset the retriever.
+
+        Args:
+            **kwargs (Any): The keyword arguments to pass to the
+                retriever.
+
+        Returns:
+            bool: Whether the reset was successful.
+        """
+        path = Path(self.vector_storage_local_path or os.getcwd())
+        task_id = str(kwargs.get("task_id", uuid.uuid4()))
+        retriever_dir = path / task_id
+        if not retriever_dir.exists():
+            try:
+                retriever_dir.mkdir(parents=True)
+            except Exception as e:
+                logger.error(
+                    "Error in creating directory: " + f"{retriever_dir}: {e!s}"
+                )
+                return False
+        self.vector_storage_local_path = str(retriever_dir)
+        return True
+
+
+class GAIABenchmark(BaseBenchmark):
+    r"""GAIA Benchmark adapted from `"GAIA: a benchmark for General AI
+    Assistants"
+    <https://huggingface.co/datasets/gaia-benchmark/GAIA>`_.
+
+    Args:
+        data_dir (str): The directory to save the data.
+        save_to (str): The file to save the results.
+        retriever (Optional[RetrieverProtocol]): The retriever to use.
+            (default: :obj:`None`)
+        processes (int, optional): The number of processes to use.
+            (default: :obj:`1`)
+    """
+
+    def __init__(
+        self,
+        data_dir: str,
+        save_to: str,
+        retriever: Optional[RetrieverProtocol] = None,
+        processes: int = 1,
+    ):
+        r"""Initialize the GAIA benchmark.
+
+        Args:
+            data_dir (str): The directory to save the data.
+            save_to (str): The file to save the results.
+            retriever (Optional[RetrieverProtocol], optional): The retriever to
+                use. (default: :obj:`None`)
+            processes (int, optional): The number of processes to use for
+                parallel processing. (default: :obj:`1`)
+        """
+        super().__init__("gaia", data_dir, save_to, processes)
+        self.retriever = retriever or DefaultGAIARetriever()
+
+    def download(self):
+        r"""Download the GAIA dataset."""
+        from huggingface_hub import snapshot_download
+
+        snapshot_download(
+            repo_id="gaia-benchmark/GAIA",
+            repo_type="dataset",
+            local_dir=self.data_dir,
+            local_dir_use_symlinks=True,
+        )
+
+    def load(self, force_download=False):
+        r"""Load the GAIA dataset.
+
+        Args:
+            force_download (bool, optional): Whether to
+                force download the data.
+        """
+        if force_download:
+            logger.info("Force downloading data.")
+            self.download()
+
+        # Define validation and test directories
+        valid_dir = self.data_dir / "2023/validation"
+        test_dir = self.data_dir / "2023/test"
+
+        # Check if directories exist; if not, download the data
+        if not valid_dir.is_dir() or not test_dir.is_dir():
+            logger.info("Data not found. Downloading data.")
+            self.download()
+
+        # Load metadata for both validation and test datasets
+        for path, label in zip([valid_dir, test_dir], ["valid", "test"]):
+            self._data[label] = []
+            with open(path / "metadata.jsonl", "r") as f:
+                lines = f.readlines()
+                for line in lines:
+                    data = json.loads(line)
+                    if data["task_id"] == "0-0-0-0-0":
+                        continue
+                    if data["file_name"]:
+                        data["file_name"] = path / data["file_name"]
+                    self._data[label].append(data)
+        return self
+
+    @property
+    def train(self):
+        r"""Get the training set."""
+        raise NotImplementedError("GAIA does not have a training set.")
+
+    def run(  # type: ignore[override]
+        self,
+        agent: ChatAgent,
+        on: Literal["train", "valid", "test"],
+        level: Union[int, List[int], Literal["all"]],
+        randomize: bool = False,
+        subset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        r"""Run the benchmark.
+
+        Args:
+            agent (ChatAgent): The agent to run the benchmark.
+            on (Literal["valid", "test"]): The set to run the benchmark.
+            level (Union[int, List[int], Literal["all"]]): The level to run
+                the benchmark.
+            randomize (bool, optional): Whether to randomize the data.
+                (default: :obj:`False`)
+            subset (Optional[int], optional): The subset of data to run.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, Any]: The results of the benchmark.
+        """
+        # Validate inputs
+        if on not in ["valid", "test"]:
+            raise ValueError(
+                f"Invalid value for `on`: {on}, expected 'valid' or 'test'."
+            )
+
+        levels = (
+            [1, 2, 3]
+            if level == "all"
+            else [level]
+            if isinstance(level, int)
+            else level
+        )
+        if not all(
+            isinstance(level, int) and level in [1, 2, 3] for level in levels
+        ):
+            raise ValueError(
+                f"Invalid value for `level`: {level}, expected 1, 2, 3 "
+                "or 'all'."
+            )
+
+        logger.info(f"Running benchmark on {on} set at levels {levels}.")
+        datas = [data for data in self._data[on] if data["Level"] in levels]
+
+        # Shuffle and subset data if necessary
+        if randomize:
+            random.shuffle(datas)
+        if subset:
+            datas = datas[:subset]
+
+        logger.info(f"Number of tasks: {len(datas)}")
+
+        # Initialize results storage
+        self._results = []
+
+        # Process tasks
+        with open(self.save_to, "w") as f:
+            for task in tqdm(datas, desc="Running"):
+                if not self._prepare_task(task):
+                    continue
+
+                try:
+                    result = agent.step(self._create_user_message(task))
+                    self._process_result(agent, task, result, f)
+                except Exception as e:
+                    self._handle_error(task, e, f)
+                finally:
+                    agent.reset()
+
+        return self._generate_summary()
+
+    def _prepare_task(self, task: Dict[str, Any]) -> bool:
+        r"""Prepare the task by validating and enriching its data."""
+        if task["file_name"]:
+            file_path = Path(task["file_name"])
+            if not file_path.exists():
+                logger.info(
+                    f"Skipping task because file not found: {file_path}"
+                )
+                return False
+            if file_path.suffix in [".pdf", ".docx", ".doc", ".txt"]:
+                if not self.retriever.reset(task_id=task["task_id"]):
+                    return False
+                retrieved_info = self.retriever.retrieve(
+                    query=task["Question"], contents=[task["file_name"]]
+                )
+                retrieved_content = [
+                    item["text"]
+                    for item in retrieved_info.get("Retrieved Context", [])
+                ]
+                if retrieved_content:
+                    task["Question"] += "\n" + "\n".join(retrieved_content)
+            else:
+                logger.info(
+                    f"Skipping task due to unsupported file "
+                    f"format: {file_path.suffix}"
+                )
+                return False
+        return True
+
+    def _create_user_message(self, task: Dict[str, Any]) -> BaseMessage:
+        r"""Create a user message from a task."""
+        return BaseMessage.make_user_message(
+            role_name="User",
+            content=task["Question"],
+        )
+
+    def _process_result(
+        self,
+        agent: ChatAgent,
+        task: Dict[str, Any],
+        result: Any,
+        file_obj: Any,
+    ) -> None:
+        r"""Process and store the result of a task."""
+        model_answer = self.get_final_answer(result.msgs[0].content)
+        final_answer = task["Final answer"]
+        score = self.question_scorer(model_answer, final_answer)
+        tool_calls = result.info.get("tool_calls", [])
+
+        result_data = {
+            "task_id": task["task_id"],
+            "question": task["Question"],
+            "level": task["Level"],
+            "model_answer": model_answer,
+            "ground_truth": final_answer,
+            "tool_calls": [tool.model_dump() for tool in tool_calls],
+            "error": None,
+            "score": int(score),
+            "history": agent.memory.get_context(),
+        }
+        self._results.append(result_data)
+        file_obj.write(json.dumps(result_data, indent=2) + "\n")
+        file_obj.flush()
+
+    def _handle_error(
+        self, task: Dict[str, Any], error: Exception, file_obj: Any
+    ) -> None:
+        r"""Handle errors encountered during task processing."""
+        logger.warning(f"Error processing task {task['task_id']}: {error}")
+        error_data = {
+            "task_id": task["task_id"],
+            "question": task["Question"],
+            "level": task["Level"],
+            "model_answer": "ERROR",
+            "ground_truth": task["Final answer"],
+            "tool_calls": [],
+            "error": str(error),
+            "score": 0,
+        }
+        self._results.append(error_data)
+        file_obj.write(json.dumps(error_data, indent=2) + "\n")
+        file_obj.flush()
+
+    def _generate_summary(self) -> Dict[str, Any]:
+        r"""Generate and return a summary of the benchmark results."""
+        return {
+            "total": len(self._results),
+            "correct": sum(result["score"] for result in self._results),
+            "results": self._results,
+        }
+
+    def question_scorer(self, model_answer: str, ground_truth: str) -> bool:
+        r"""Scorer for the GAIA benchmark.
+        https://huggingface.co/spaces/gaia-benchmark/leaderboard/blob/main/
+        scorer.py
+
+        Args:
+            model_answer (str): The model answer.
+            ground_truth (str): The ground truth answer.
+
+        Returns:
+            bool: The score of the model
+        """
+
+        def is_float(element: Any) -> bool:
+            try:
+                float(element)
+                return True
+            except ValueError:
+                return False
+
+        if is_float(ground_truth):
+            logger.info(f"Evaluating {model_answer} as a number.")
+            normalized_answer = self.normalize_number_str(model_answer)
+            return normalized_answer == float(ground_truth)
+
+        elif any(char in ground_truth for char in [",", ";"]):
+            logger.info(
+                f"Evaluating {model_answer} as a comma separated list."
+            )
+            gt_elems = self.split_string(ground_truth)
+            ma_elems = self.split_string(model_answer)
+
+            if len(gt_elems) != len(ma_elems):
+                logger.warning(
+                    "Answer lists have different lengths, returning False.",
+                    UserWarning,
+                )
+                return False
+
+            comparisons = []
+            for ma_elem, gt_elem in zip(ma_elems, gt_elems):
+                if is_float(gt_elem):
+                    normalized_ma_elem = self.normalize_number_str(ma_elem)
+                    comparisons.append(normalized_ma_elem == float(gt_elem))
+                else:
+                    ma_elem = self.normalize_str(ma_elem, remove_punct=False)
+                    gt_elem = self.normalize_str(gt_elem, remove_punct=False)
+                    comparisons.append(ma_elem == gt_elem)
+            return all(comparisons)
+        else:
+            logger.info(f"Evaluating {model_answer} as a string.")
+            ma_elem = self.normalize_str(model_answer)
+            gt_elem = self.normalize_str(ground_truth)
+            return ma_elem == gt_elem
+
+    def normalize_number_str(self, number_str: str) -> float:
+        for char in ["$", "%", ","]:
+            number_str = number_str.replace(char, "")
+        try:
+            return float(number_str)
+        except ValueError:
+            logger.error(
+                f"String {number_str} cannot be normalized to number str."
+            )
+            return float("inf")
+
+    def split_string(
+        self, s: str, char_list: Optional[List[str]] = None
+    ) -> list[str]:
+        r"""Split a string based on a list of characters.
+
+        Args:
+            s (str): The string to split.
+            char_list (Optional[List[str]], optional): T
+                he list of characters to split on.
+                (default: :obj:`None`)
+        """
+        if char_list is None:
+            char_list = [",", ";"]
+        pattern = f"[{''.join(char_list)}]"
+        return re.split(pattern, s)
+
+    def normalize_str(self, input_str, remove_punct=True) -> str:
+        r"""Normalize a string.
+
+        Args:
+            input_str: The input string to normalize.
+            remove_punct: Whether to remove punctuation.
+
+        Returns:
+            str: The normalized string.
+        """
+        no_spaces = re.sub(r"\s", "", input_str)
+        if remove_punct:
+            translator = str.maketrans("", "", string.punctuation)
+            return no_spaces.lower().translate(translator)
+        else:
+            return no_spaces.lower()
+
+    def get_final_answer(self, content: str) -> str:
+        r"""Get the final answer from the content.
+
+        Args:
+            content (str): The content to extract the final answer from.
+
+        Returns:
+            str: The final answer.
+        """
+        final_answer_index = content.find("FINAL ANSWER")
+        if final_answer_index == -1:
+            return "FINAL ANSWER not found"
+        start_index = final_answer_index + len("FINAL ANSWER: ")
+        final_answer_content = content[start_index:].strip()
+        return final_answer_content

camel/benchmarks/nexus.py

@@ -0,0 +1,518 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import ast
+import json
+import logging
+import os
+import random
+import textwrap
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union
+
+import pandas as pd
+from datasets import load_dataset
+from tqdm import tqdm
+
+from camel.agents import ChatAgent
+from camel.benchmarks.base import BaseBenchmark
+from camel.messages import BaseMessage
+
+logger = logging.getLogger(__name__)
+
+
+# Define the data class
+@dataclass
+class NexusSample:
+    r"""Nexus benchmark dataset sample."""
+
+    input: str
+    output: str
+
+
+@dataclass
+class NexusTool:
+    r"""Nexus benchmark tool"""
+
+    function_calls: str
+    descriptions: str
+
+
+dataset_mapping = {
+    "NVDLibrary": "Nexusflow/NVDLibraryBenchmark",
+    "VirusTotal": "Nexusflow/VirusTotalBenchmark",
+    "PlacesAPI": "Nexusflow/PlacesAPIBenchmark",
+    "ClimateAPI": "Nexusflow/ClimateAPIBenchmark",
+    "OTX": "Nexusflow/OTXAPIBenchmark",
+    "VirusTotal-NestedCalls": "Nexusflow/vt_multiapi",
+    "VirusTotal-ParallelCalls": "Nexusflow/vt_multiapi",
+    "NVDLibrary-NestedCalls": "Nexusflow/CVECPEAPIBenchmark",
+}
+
+TOOL_CALLING_PROMPT = """
+You are given multiple functions and a user query.
+
+Please proceed with generating a function call for the function \
+with the proper arguments that best answers the given prompt.
+
+Respond with nothing but the function call ONLY, such that I can \
+directly execute your function call without any post processing \
+necessary from my end. Do not use variables. 
+If there are more than two function calls, separate them with a semicolon (;).
+
+{tools}
+
+Question: {input}
+"""
+
+
+class NexusBenchmark(BaseBenchmark):
+    r"""Nexus Function Calling Benchmark adapted from `NexusRaven V2
+    Function Calling Benchmark`
+    <https://huggingface.co/collections/Nexusflow/nexusraven-v2-function-calling-benchmark-657a597fb84dbe7a09ebfc3e>.
+
+    Args:
+        data_dir (str): The directory to save the data.
+        save_to (str): The file to save the results.
+        processes (int, optional): The number of processes to use.
+            (default: :obj:`1`)
+    """
+
+    def __init__(
+        self,
+        data_dir: str,
+        save_to: str,
+        processes: int = 1,
+    ):
+        r"""Initialize the Nexus Function Calling benchmark.
+
+        Args:
+            data_dir (str): The directory to save the data.
+            save_to (str): The file to save the results.
+            processes (int, optional): The number of processes to use for
+                parallel processing. (default: :obj:`1`)
+        """
+        super().__init__("nexus", data_dir, save_to, processes)
+        self._data: List[NexusSample] = []  # type: ignore[assignment]
+
+    def download(self):
+        r"""Download the Nexus Functional Calling Benchmark dataset."""
+        from huggingface_hub import snapshot_download
+
+        for dataset_name, repo_id in dataset_mapping.items():
+            local_dir = self.data_dir / dataset_name
+            snapshot_download(
+                repo_id=repo_id,
+                repo_type="dataset",
+                local_dir=local_dir,
+                local_dir_use_symlinks=True,
+            )
+
+    def load(self, dataset_name: str, force_download: bool = False):  # type: ignore[override]
+        r"""Load the Nexus Benchmark dataset.
+
+        Args:
+            dataset_name (str): Name of the specific dataset to be loaded.
+            force_download (bool): Whether to force download the data.
+        """
+
+        def _load_csv_data(dataset_dir: Path) -> List:
+            r"""Load datasets from CSV files."""
+            dataset = []
+            for file_name in os.listdir(dataset_dir):
+                file_path = dataset_dir / file_name
+                if file_name.endswith(".csv"):
+                    data = pd.read_csv(file_path)
+                    for _, sample in data.iterrows():
+                        dataset.append(
+                            NexusSample(
+                                sample["Input"], "".join(sample["Output"])
+                            )
+                        )
+                    continue
+
+                logger.warning(f"Skipping unsupported file: {file_name}")
+            return dataset
+
+        def _load_parquet_data(data_dir: Path, dataset_name: str) -> List:
+            r"""Load datasets from Parquet files."""
+            dataset = []
+            if not data_dir.exists():
+                raise FileNotFoundError(
+                    f"Data directory '{data_dir}' does not exist."
+                )
+
+            for file_name in os.listdir(data_dir):
+                file_path = data_dir / file_name
+                if file_name.endswith(".parquet"):
+                    data = pd.read_parquet(file_path)
+                    dataset.extend(_process_parquet_data(data, dataset_name))
+                    continue
+
+                logger.warning(f"Skipping unsupported file: {file_name}")
+
+            return dataset
+
+        def _process_parquet_data(
+            data: pd.DataFrame, dataset_name: str
+        ) -> List:
+            r"""Process data from Parquet files based on dataset name."""
+            dataset: List = []
+            dataset_handlers = {
+                "NVDLibrary": _process_nvdlibrary,
+                "VirusTotal": _process_simple,
+                "PlacesAPI": _process_simple,
+                "ClimateAPI": _process_simple,
+                "OTX": _process_simple,
+                "VirusTotal-NestedCalls": _process_nested_calls,
+                "VirusTotal-ParallelCalls": _process_parallel_calls,
+            }
+
+            if dataset_name not in dataset_handlers:
+                logger.warning(
+                    f"No specific handler for dataset: {dataset_name}"
+                )
+                return dataset
+
+            handler = dataset_handlers[dataset_name]
+            for _, sample in data.iterrows():
+                processed_sample = handler(sample)
+                if processed_sample:
+                    dataset.append(processed_sample)
+            return dataset
+
+        def _process_nvdlibrary(sample) -> NexusSample:
+            r"""Process samples for the NVDLibrary dataset."""
+            return NexusSample(
+                sample["Input"], sample["Output"].replace("r = nvdlib.", "")
+            )
+
+        def _process_simple(sample) -> NexusSample:
+            r"""Process samples for simple datasets (e.g., VirusTotal)."""
+            return NexusSample(sample["Input"], sample["Output"])
+
+        def _process_nested_calls(sample) -> Union[NexusSample, None]:
+            r"""Process samples for VirusTotal-NestedCalls dataset."""
+            if len(sample["fncall"]) == 1:
+                return NexusSample(
+                    sample["generated_question"], "".join(sample["fncall"])
+                )
+            return None
+
+        def _process_parallel_calls(sample) -> Union[NexusSample, None]:
+            r"""Process samples for VirusTotal-ParallelCalls dataset."""
+            if len(sample["fncall"]) > 1:
+                return NexusSample(
+                    sample["generated_question"], "; ".join(sample["fncall"])
+                )
+            return None
+
+        if force_download:
+            logger.info("Force downloading data.")
+            self.download()
+
+        # Validate dataset name
+        if dataset_name not in dataset_mapping:
+            available_datasets = list(dataset_mapping.keys())
+            raise ValueError(
+                f"Dataset '{dataset_name}' is not recognized. "
+                f"Available datasets: {available_datasets}"
+            )
+
+        # Get the dataset directory
+        dataset_dir = self.data_dir / dataset_name
+        if not dataset_dir.exists():
+            raise FileNotFoundError(
+                f"The dataset directory for '{dataset_name}' \
+                does not exist at {dataset_dir}. "
+                "Please download it first."
+            )
+
+        # Load the dataset
+        if dataset_name == "NVDLibrary-NestedCalls":
+            self._data = _load_csv_data(dataset_dir)
+        else:
+            self._data = _load_parquet_data(dataset_dir / "data", dataset_name)
+
+    @property
+    def train(self):
+        r"""Get the training set."""
+        raise NotImplementedError(
+            "Nexus Functional Calling has only a single 'train' set."
+        )
+
+    def run(  # type: ignore[override, return]
+        self,
+        agent: ChatAgent,
+        task: Literal[
+            "NVDLibrary",
+            "VirusTotal",
+            "OTX",
+            "PlacesAPI",
+            "ClimateAPI",
+            "VirusTotal-ParallelCalls",
+            "VirusTotal-NestedCalls",
+            "NVDLibrary-NestedCalls",
+        ],
+        randomize: bool = False,
+        subset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        r"""Run the benchmark.
+
+        Args:
+            agent (ChatAgent): The agent to run the benchmark.
+            task (Literal["NVDLibrary", "VirusTotal", "OTX",
+            "PlacesAPI", "ClimateAPI", "VirusTotal-ParallelCalls",
+            "VirusTotal-NestedCalls",
+            "NVDLibrary-NestedCalls"]): The task to run the benchmark.
+            randomize (bool, optional): Whether to randomize the data.
+                (default: :obj:`False`)
+            subset (Optional[int], optional): The subset of data to run.
+                (default: :obj:`None`)
+
+        Returns:
+            Dict[str, Any]: The results of the benchmark.
+        """
+
+        if task not in dataset_mapping:
+            raise ValueError(f"Invalid value for dataset: {task}.")
+
+        logger.info(f"Running Nexus Function Calling benchmark on {task}.")
+        self.load(task)
+        datas = self._data
+
+        # Shuffle and subset data if necessary
+        if randomize:
+            random.shuffle(datas)
+        if subset:
+            datas = datas[:subset]
+
+        logger.info(f"Number of tasks: {len(datas)}")
+
+        # Initialize results storage
+        self._results = []
+
+        # Process samples
+        tools = construct_tool_descriptions(task)
+        with open(self.save_to, "w") as f:
+            for sample in tqdm(datas, desc="Running"):
+                prompt = construct_prompt(input=sample.input, tools=tools)
+                msg = BaseMessage.make_user_message(
+                    role_name="User", content=prompt
+                )
+                ground_truth_call = sample.output
+                try:
+                    # Generate response
+                    response = agent.step(msg)
+                    agent_call = response.msgs[0].content
+
+                    # Evaluate response
+                    if agent_call:
+                        result = compare_function_calls(
+                            agent_call=agent_call,
+                            ground_truth_call=ground_truth_call,
+                        )
+                        self._results.append(
+                            {
+                                "input": sample.input,
+                                "agent_call": agent_call,
+                                "ground_truth_call": ground_truth_call,
+                                "result": result,
+                                "error": None,
+                            }
+                        )
+                except Exception as e:
+                    logger.warning(f"Error in processing task: {sample.input}")
+                    self._results.append(
+                        {
+                            "input": sample.input,
+                            "agent_call": None,
+                            "ground_truth_call": ground_truth_call,
+                            "result": 0,
+                            "error": str(e),
+                        }
+                    )
+
+                agent.reset()
+
+                f.write(json.dumps(self._results[-1], indent=2) + "\n")
+                f.flush()
+
+        total = len(self._results)
+        correct = sum(r["result"] for r in self._results)
+
+        return {
+            "total": total,
+            "correct": correct,
+            "accuracy": correct / total,
+        }
+
+
+# Utility functions
+def construct_tool_descriptions(dataset_name: str) -> str:
+    r"""Construct tool descriptions from function definitions and
+    descriptions."""
+    tool_dataset_mapping = {
+        "NVDLibrary": "CVECPE",
+        "VirusTotal": "VirusTotal",
+        "PlacesAPI": "Places",
+        "ClimateAPI": "Climate",
+        "OTX": "OTX",
+        "VirusTotal-NestedCalls": "VT_Multi (Nested)",
+        "VirusTotal-ParallelCalls": "VT_Multi (Parallel)",
+        "NVDLibrary-NestedCalls": "CVECPE_Multi (Nested)",
+    }
+
+    if dataset_name not in tool_dataset_mapping:
+        raise ValueError(
+            f"Dataset '{dataset_name}' is not recognized. "
+            f"Available datasets: {list(dataset_mapping.keys())}"
+        )
+
+    # Load the dataset based on the dataset name
+    dataset = load_dataset(
+        "Nexusflow/Function_Call_Definitions",
+        name=tool_dataset_mapping[dataset_name],
+    )["train"]
+
+    # Construct tool descriptions
+    tools = [
+        NexusTool(tool["function_calls"], tool["descriptions"])
+        for tool in dataset
+    ]
+
+    # Generate the tool prompt
+    tool_prompt = "".join(
+        f"Function:\ndef {tool.function_calls}:\n"
+        + "\"\"\"\n"
+        + f"{tool.descriptions}\n"
+        + "\"\"\"\n"
+        for tool in tools
+    )
+
+    return tool_prompt
+
+
+def construct_prompt(input: str, tools: str) -> str:
+    r"Construct prompt from tools and input."
+    return TOOL_CALLING_PROMPT.format(tools=tools, input=input)
+
+
+# Functions for function call evaluation
+def parse_function_call(
+    call: str,
+) -> Tuple[Optional[str], Optional[List[Any]], Optional[Dict[str, Any]]]:
+    r"""Parse a function call string to extract the function name,
+    positional arguments, and keyword arguments, including
+    nested function calls.
+
+    Args:
+        call (str): A string in the format `func(arg1, arg2, kwarg=value)`.
+
+    Returns:
+        tuple: (function_name (str), positional_args (list),
+        keyword_args (dict)) or (None, None, None).
+    """
+
+    def preprocess_input(call: str) -> str:
+        r"""Remove formatting like code blocks and whitespace."""
+        if call.strip().startswith("```python"):
+            call = call.strip().removeprefix("```python").removesuffix("```")
+        return textwrap.dedent(call).strip()
+
+    def evaluate_arg(arg):
+        r"""Recursively evaluate arguments, including nested calls."""
+        if isinstance(arg, ast.Call):
+            # Recursively parse nested calls
+            func_name, args, kwargs = parse_function_call(ast.unparse(arg))
+            return func_name, args, kwargs
+        elif isinstance(
+            arg, ast.Constant
+        ):  # Handle literals like numbers, strings, etc.
+            return arg.value
+        elif isinstance(arg, ast.List):  # Handle list literals
+            return [evaluate_arg(el) for el in arg.elts]
+        elif isinstance(arg, ast.Dict):  # Handle dictionary literals
+            return {
+                evaluate_arg(k): evaluate_arg(v)
+                for k, v in zip(arg.keys, arg.values)
+            }
+        elif isinstance(arg, ast.Tuple):  # Handle tuple literals
+            return tuple(evaluate_arg(el) for el in arg.elts)
+        else:
+            return ast.literal_eval(arg)  # Safely evaluate other types
+
+    call = preprocess_input(call)
+    parsed_calls = []
+
+    try:
+        # Parse the string into an AST
+        parsed_calls = call.split(";")
+        for single_call in parsed_calls:
+            tree = ast.parse(single_call, mode='eval')
+
+            # Ensure it's a function call
+            if isinstance(tree.body, ast.Call):
+                # Extract function name
+                if isinstance(
+                    tree.body.func, ast.Name
+                ):  # Simple function call
+                    func_name = tree.body.func.id
+                elif isinstance(
+                    tree.body.func, ast.Attribute
+                ):  # Attribute function call
+                    func_name = (
+                        f"{tree.body.func.value.id}.{tree.body.func.attr}"  # type: ignore[attr-defined]
+                    )
+                else:
+                    raise ValueError(f"Unsupported function call: {call}")
+
+                # Extract positional arguments
+                args = [evaluate_arg(arg) for arg in tree.body.args]
+
+                # Extract keyword arguments
+                kwargs: Dict[str, Any] = {
+                    kw.arg: evaluate_arg(kw.value)
+                    for kw in tree.body.keywords
+                    if kw.arg is not None
+                }
+                logger.info("Valid call.")
+                return func_name, args, kwargs
+        else:
+            raise ValueError(f"Not a valid function call: {call}")
+    except Exception as e:
+        logger.info(f"Error parsing call: {call}, {e}")
+        return None, None, None
+
+
+def compare_function_calls(agent_call: str, ground_truth_call: str) -> bool:
+    r"""Compare the function name and arguments of
+    agent_call and ground_truth_call.
+    Args:
+        agent_call (str): Function call by agent.
+        ground_truth_call (str): Ground truth function call.
+
+    Returns:
+        - `True` if the function names and arguments match.
+        - `False` otherwise.
+    """
+    # Parse both calls
+    agent_parsed = parse_function_call(agent_call)
+    gt_parsed = parse_function_call(ground_truth_call)
+
+    if agent_parsed and gt_parsed:
+        return agent_parsed == gt_parsed
+    else:
+        return False

camel/benchmarks/ragbench.py

@@ -0,0 +1,333 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from typing import Any, Callable, Dict, List, Literal, Optional, Sequence
+
+import numpy as np
+from datasets import Dataset, load_dataset
+
+from camel.agents import ChatAgent
+from camel.benchmarks import BaseBenchmark
+from camel.logger import get_logger
+from camel.retrievers import AutoRetriever
+
+logger = get_logger(__name__)
+
+
+class RagasFields:
+    r"""Constants for RAGAS evaluation field names."""
+
+    INPUT_CONTEXT = "contexts"
+    INPUT_QUESTION = "question"
+    INPUT_ANSWER = "answer"
+
+
+def annotate_dataset(
+    dataset: Dataset,
+    context_call: Optional[Callable[[Dict[str, Any]], List[str]]],
+    answer_call: Optional[Callable[[Dict[str, Any]], str]],
+) -> Dataset:
+    r"""Annotate the dataset by adding context and answers using the provided
+    functions.
+
+    Args:
+        dataset (Dataset): The input dataset to annotate.
+        context_call (Optional[Callable[[Dict[str, Any]], List[str]]]):
+            Function to generate context for each example.
+        answer_call (Optional[Callable[[Dict[str, Any]], str]]): Function to
+            generate answer for each example.
+
+    Returns:
+        Dataset: The annotated dataset with added contexts and/or answers.
+    """
+
+    def process_example(example: Dict[str, Any]) -> Dict[str, Any]:
+        if context_call:
+            example["contexts"] = context_call(example)
+        if answer_call:
+            example["answer"] = answer_call(example)
+        return example
+
+    return dataset.map(process_example)
+
+
+def rmse(
+    input_trues: Sequence[float],
+    input_preds: Sequence[float],
+) -> Optional[float]:
+    r"""Calculate Root Mean Squared Error (RMSE).
+
+    Args:
+        input_trues (Sequence[float]): Ground truth values.
+        input_preds (Sequence[float]): Predicted values.
+
+    Returns:
+        Optional[float]: RMSE value, or None if inputs have different lengths.
+    """
+    if len(input_trues) != len(input_preds):
+        logger.warning("Input lengths mismatch in RMSE calculation")
+        return None
+
+    trues = np.array(input_trues)
+    preds = np.array(input_preds, dtype=float)
+
+    # Ignore NaN values in predictions
+    eval_idx = ~np.isnan(preds)
+    if not np.any(eval_idx):
+        logger.warning("No valid predictions for RMSE calculation")
+        return None
+
+    trues = trues[eval_idx]
+    preds = preds[eval_idx]
+
+    return float(np.sqrt(np.mean((preds - trues) ** 2)))
+
+
+def auroc(trues: Sequence[bool], preds: Sequence[float]) -> float:
+    r"""Calculate Area Under Receiver Operating Characteristic Curve (AUROC).
+
+    Args:
+        trues (Sequence[bool]): Ground truth binary values.
+        preds (Sequence[float]): Predicted probability values.
+
+    Returns:
+        float: AUROC score.
+    """
+    from sklearn.metrics import roc_auc_score  # type: ignore[import-untyped]
+
+    eval_idx = ~np.isnan(preds)
+    if not np.any(eval_idx):
+        logger.warning("No valid predictions for AUROC calculation")
+        return 0.5  # Return random classifier score
+
+    return float(
+        roc_auc_score(np.array(trues)[eval_idx], np.array(preds)[eval_idx])
+    )
+
+
+def ragas_calculate_metrics(
+    dataset: Dataset,
+    pred_context_relevance_field: Optional[str],
+    pred_faithfulness_field: Optional[str],
+    metrics_to_evaluate: Optional[List[str]] = None,
+    ground_truth_context_relevance_field: str = "relevance_score",
+    ground_truth_faithfulness_field: str = "adherence_score",
+) -> Dict[str, Optional[float]]:
+    r"""Calculate RAGAS evaluation metrics.
+
+    Args:
+        dataset (Dataset): The dataset containing predictions and ground truth.
+        pred_context_relevance_field (Optional[str]): Field name for predicted
+            context relevance.
+        pred_faithfulness_field (Optional[str]): Field name for predicted
+            faithfulness.
+        metrics_to_evaluate (Optional[List[str]]): List of metrics to evaluate.
+        ground_truth_context_relevance_field (str): Field name for ground truth
+            relevance.
+        ground_truth_faithfulness_field (str): Field name for ground truth
+            adherence.
+
+    Returns:
+        Dict[str, Optional[float]]: Dictionary of calculated metrics.
+    """
+    metrics_to_evaluate = metrics_to_evaluate or [
+        "context_relevancy",
+        "faithfulness",
+    ]
+    calculated_metrics: Dict[str, Optional[float]] = {}
+
+    if (
+        "context_relevancy" in metrics_to_evaluate
+        and pred_context_relevance_field
+    ):
+        trues_relevance = dataset[ground_truth_context_relevance_field]
+        preds_relevance = dataset[pred_context_relevance_field]
+        calculated_metrics["relevance_rmse"] = rmse(
+            trues_relevance, preds_relevance
+        )
+
+    if "faithfulness" in metrics_to_evaluate and pred_faithfulness_field:
+        trues_hallucination = ~np.array(
+            dataset[ground_truth_faithfulness_field]
+        )
+        preds_hallucination = 1 - np.array(
+            dataset[pred_faithfulness_field], dtype=float
+        )
+        calculated_metrics["hallucination_auroc"] = auroc(
+            trues_hallucination.tolist(), preds_hallucination.tolist()
+        )
+
+    return calculated_metrics
+
+
+def ragas_evaluate_dataset(
+    dataset: Dataset,
+    contexts_field_name: Optional[str],
+    answer_field_name: Optional[str],
+    metrics_to_evaluate: Optional[List[str]] = None,
+) -> Dataset:
+    r"""Evaluate the dataset using RAGAS metrics.
+
+    Args:
+        dataset (Dataset): Input dataset to evaluate.
+        contexts_field_name (Optional[str]): Field name containing contexts.
+        answer_field_name (Optional[str]): Field name containing answers.
+        metrics_to_evaluate (Optional[List[str]]): List of metrics to evaluate.
+
+    Returns:
+        Dataset: Dataset with added evaluation metrics.
+    """
+    from ragas import evaluate
+    from ragas.metrics import (  # type: ignore[import-untyped]
+        context_relevancy,
+        faithfulness,
+    )
+
+    metrics_to_evaluate = metrics_to_evaluate or [
+        "context_relevancy",
+        "faithfulness",
+    ]
+
+    # Rename fields if necessary
+    if (
+        contexts_field_name
+        and contexts_field_name != RagasFields.INPUT_CONTEXT
+    ):
+        dataset = dataset.rename_column(
+            contexts_field_name, RagasFields.INPUT_CONTEXT
+        )
+    if answer_field_name and answer_field_name != RagasFields.INPUT_ANSWER:
+        dataset = dataset.rename_column(
+            answer_field_name, RagasFields.INPUT_ANSWER
+        )
+
+    metrics = []
+    if "context_relevancy" in metrics_to_evaluate:
+        metrics.append(context_relevancy)
+    if "faithfulness" in metrics_to_evaluate:
+        metrics.append(faithfulness)
+
+    ragas_result = evaluate(dataset, metrics=metrics)
+    return Dataset.from_pandas(ragas_result.to_pandas())
+
+
+class RAGBenchBenchmark(BaseBenchmark):
+    r"""RAGBench Benchmark for evaluating RAG performance.
+
+    This benchmark uses the rungalileo/ragbench dataset to evaluate
+    retrieval-augmented generation (RAG) systems. It measures context
+    relevancy and faithfulness metrics as described in
+    https://arxiv.org/abs/2407.11005.
+
+    Args:
+        processes (int, optional): Number of processes for parallel processing.
+        subset (str, optional): Dataset subset to use (e.g., "hotpotqa").
+        split (str, optional): Dataset split to use (e.g., "test").
+    """
+
+    def __init__(
+        self,
+        processes: int = 1,
+        subset: Literal[
+            "covidqa",
+            "cuad",
+            "delucionqa",
+            "emanual",
+            "expertqa",
+            "finqa",
+            "hagrid",
+            "hotpotqa",
+            "msmarco",
+            "pubmedqa",
+            "tatqa",
+            "techqa",
+        ] = "hotpotqa",
+        split: Literal["train", "test", "validation"] = "test",
+    ) -> None:
+        super().__init__("ragbench", "rag_bench", "", processes)
+        self.subset = subset
+        self.split = split
+        self.dataset: Optional[Dataset] = None
+
+    def download(self):
+        r"""Download the RAGBench dataset."""
+        try:
+            self.dataset = load_dataset(
+                "rungalileo/ragbench", self.subset, split=self.split
+            )
+        except Exception as e:
+            logger.error(f"Failed to download dataset: {e}")
+            raise
+
+    def load(self, force_download: bool = False):
+        r"""Load the RAGBench dataset.
+
+        Args:
+            force_download (bool, optional): Whether to force download the
+                data.
+        """
+        if force_download or self.dataset is None:
+            logger.info(
+                "%s dataset",
+                "Force downloading" if force_download else "Loading",
+            )
+            self.download()
+
+    def run(  # type: ignore[override, return]
+        self,
+        agent: ChatAgent,
+        auto_retriever: AutoRetriever,
+    ) -> Dict[str, Optional[float]]:
+        r"""Run the benchmark evaluation.
+
+        Args:
+            agent (ChatAgent): Chat agent for generating answers.
+            auto_retriever (AutoRetriever): Retriever for finding relevant
+                contexts.
+
+        Returns:
+            Dict[str, Optional[float]]: Dictionary of evaluation metrics.
+        """
+
+        def context_call(example):
+            retrieved_info = auto_retriever.run_vector_retriever(
+                query=example['question'],
+                contents=example['documents'],
+                top_k=1,
+                return_detailed_info=True,
+                similarity_threshold=0.5,
+            )
+            return [c['text'] for c in retrieved_info['Retrieved Context']]
+
+        def answer_call(example: Dict[str, Any]) -> str:
+            user_msg = str(example)
+            assistant_response = agent.step(user_msg)
+            return assistant_response.msg.content
+
+        # Annotate the dataset
+        annotated_ds = annotate_dataset(
+            self.dataset, context_call, answer_call
+        )
+        evaluated_ds = ragas_evaluate_dataset(
+            annotated_ds,
+            contexts_field_name="contexts",
+            answer_field_name="answer",
+            metrics_to_evaluate=["context_relevancy", "faithfulness"],
+        )
+
+        return ragas_calculate_metrics(
+            evaluated_ds,
+            pred_context_relevance_field="context_relevancy",
+            pred_faithfulness_field="faithfulness",
+        )

camel/bots/__init__.py

@@ -0,0 +1,34 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from .discord import DiscordApp
+from .slack.models import (
+    SlackAppMentionEventBody,
+    SlackAppMentionEventProfile,
+    SlackAuthProfile,
+    SlackEventBody,
+    SlackEventProfile,
+)
+from .slack.slack_app import SlackApp
+from .telegram_bot import TelegramBot
+
+__all__ = [
+    'DiscordApp',
+    'SlackApp',
+    'SlackAppMentionEventBody',
+    'SlackAppMentionEventProfile',
+    'SlackAuthProfile',
+    'SlackEventBody',
+    'SlackEventProfile',
+    'TelegramBot',
+]

camel/bots/discord/__init__.py

@@ -0,0 +1,26 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from .discord_app import DiscordApp
+from .discord_installation import DiscordInstallation
+from .discord_store import (
+    DiscordBaseInstallationStore,
+    DiscordSQLiteInstallationStore,
+)
+
+__all__ = [
+    "DiscordApp",
+    "DiscordInstallation",
+    "DiscordSQLiteInstallationStore",
+    "DiscordBaseInstallationStore",
+]

camel/bots/discord/discord_app.py

@@ -0,0 +1,384 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, List, Optional
+
+import discord
+import httpx
+from fastapi import FastAPI
+
+from camel.bots.discord.discord_installation import DiscordInstallation
+from camel.logger import get_logger
+from camel.utils import api_keys_required, dependencies_required
+
+from .discord_store import DiscordBaseInstallationStore
+
+if TYPE_CHECKING:
+    from discord import Message
+
+logger = get_logger(__name__)
+
+TOKEN_URL = "https://discord.com/api/oauth2/token"
+USER_URL = "https://discord.com/api/users/@me"
+
+
+class DiscordApp:
+    r"""A class representing a Discord app that uses the `discord.py` library
+    to interact with Discord servers.
+
+    This bot can respond to messages in specific channels and only reacts to
+    messages that mention the bot.
+
+    Attributes:
+        channel_ids (Optional[List[int]]): A list of allowed channel IDs. If
+            provided, the bot will only respond to messages in these channels.
+        token (Optional[str]): The Discord bot token used for authentication.
+    """
+
+    @dependencies_required('discord')
+    @api_keys_required(
+        [
+            ("token", "DISCORD_BOT_TOKEN"),
+        ]
+    )
+    def __init__(
+        self,
+        channel_ids: Optional[List[int]] = None,
+        token: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        redirect_uri: Optional[str] = None,
+        installation_store: Optional[DiscordBaseInstallationStore] = None,
+        intents: Optional[discord.Intents] = None,
+    ) -> None:
+        r"""Initialize the DiscordApp instance by setting up the Discord client
+        and event handlers.
+
+        Args:
+            channel_ids (Optional[List[int]]): A list of allowed channel IDs.
+                The bot will only respond to messages in these channels if
+                provided. (default: :obj:`None`)
+            token (Optional[str]): The Discord bot token for authentication.
+                If not provided, the token will be retrieved from the
+                environment variable `DISCORD_TOKEN`. (default: :obj:`None`)
+            client_id (str, optional): The client ID for Discord OAuth.
+                (default: :obj:`None`)
+            client_secret (Optional[str]): The client secret for Discord OAuth.
+                (default: :obj:`None`)
+            redirect_uri (str): The redirect URI for OAuth callbacks.
+                (default: :obj:`None`)
+            installation_store (DiscordAsyncInstallationStore): The database
+                stores all information of all installations.
+                (default: :obj:`None`)
+            intents (discord.Intents): The Discord intents of this app.
+                (default: :obj:`None`)
+
+        Raises:
+            ValueError: If the `DISCORD_BOT_TOKEN` is not found in environment
+                variables.
+        """
+        self.token = token or os.getenv("DISCORD_BOT_TOKEN")
+        self.channel_ids = channel_ids
+        self.installation_store = installation_store
+
+        if not intents:
+            intents = discord.Intents.all()
+            intents.message_content = True
+            intents.guilds = True
+
+        self._client = discord.Client(intents=intents)
+
+        # Register event handlers
+        self._client.event(self.on_ready)
+        self._client.event(self.on_message)
+
+        # OAuth flow
+        self.client_id = client_id or os.getenv("DISCORD_CLIENT_ID")
+        self.client_secret = client_secret or os.getenv(
+            "DISCORD_CLIENT_SECRET"
+        )
+        self.redirect_uri = redirect_uri
+
+        self.oauth_flow = bool(
+            self.client_id
+            and self.client_secret
+            and self.redirect_uri
+            and self.installation_store
+        )
+
+        self.app = FastAPI()
+
+    async def start(self):
+        r"""Asynchronously start the Discord bot using its token.
+
+        This method starts the bot and logs into Discord asynchronously using
+        the provided token. It should be awaited when used in an async
+        environment.
+        """
+        await self._client.start(self.token)
+
+    def run(self) -> None:
+        r"""Start the Discord bot using its token.
+
+        This method starts the bot and logs into Discord synchronously using
+        the provided token. It blocks execution and keeps the bot running.
+        """
+        self._client.run(self.token)  # type: ignore[arg-type]
+
+    async def exchange_code_for_token_response(
+        self, code: str
+    ) -> Optional[str]:
+        r"""Exchange the authorization code for an access token.
+
+        Args:
+            code (str): The authorization code received from Discord after
+                user authorization.
+
+        Returns:
+            Optional[str]: The access token if successful, otherwise None.
+
+        Raises:
+            ValueError: If OAuth configuration is incomplete or invalid.
+            httpx.RequestError: If there is a network issue during the request.
+        """
+        if not self.oauth_flow:
+            logger.warning(
+                "OAuth is not enabled. Missing client_id, "
+                "client_secret, or redirect_uri."
+            )
+            return None
+        data = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": self.redirect_uri,
+        }
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    TOKEN_URL, data=data, headers=headers
+                )
+                if response.status_code != 200:
+                    logger.error(f"Failed to exchange code: {response.text}")
+                    return None
+                response_data = response.json()
+
+                return response_data
+        except (httpx.RequestError, ValueError) as e:
+            logger.error(f"Error during token fetch: {e}")
+            return None
+
+    async def get_user_info(self, access_token: str) -> Optional[dict]:
+        r"""Retrieve user information using the access token.
+
+        Args:
+            access_token (str): The access token received from Discord.
+
+        Returns:
+            dict: The user information retrieved from Discord.
+        """
+        if not self.oauth_flow:
+            logger.warning(
+                "OAuth is not enabled. Missing client_id, "
+                "client_secret, or redirect_uri."
+            )
+            return None
+        headers = {"Authorization": f"Bearer {access_token}"}
+        async with httpx.AsyncClient() as client:
+            user_response = await client.get(USER_URL, headers=headers)
+            return user_response.json()
+
+    async def refresh_access_token(self, refresh_token: str) -> Optional[str]:
+        r"""Refresh the access token using a refresh token.
+
+        Args:
+            refresh_token (str): The refresh token issued by Discord that
+                can be used to obtain a new access token.
+
+        Returns:
+            Optional[str]: The new access token if successful, otherwise None.
+        """
+        if not self.oauth_flow:
+            logger.warning(
+                "OAuth is not enabled. Missing client_id, "
+                "client_secret, or redirect_uri."
+            )
+            return None
+        data = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "redirect_uri": self.redirect_uri,
+        }
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        async with httpx.AsyncClient() as client:
+            response = await client.post(TOKEN_URL, data=data, headers=headers)
+            if response.status_code != 200:
+                logger.error(f"Failed to refresh token: {response.text}")
+                return None
+            response_data = response.json()
+            return response_data.get("access_token")
+
+    async def get_valid_access_token(self, guild_id: str) -> Optional[str]:
+        r"""Retrieve a valid access token for the specified guild.
+
+        This method attempts to retrieve an access token for a specific guild.
+        If the current access token is expired, it will refresh the token using
+        the refresh token.
+
+        Args:
+            guild_id (str): The ID of the guild to retrieve the access
+                token for.
+
+        Returns:
+            Optional[str]: The valid access token if successful,
+                otherwise None.
+        """
+        if not self.oauth_flow:
+            logger.warning(
+                "OAuth is not enabled. Missing client_id, "
+                "client_secret, or redirect_uri."
+            )
+            return None
+        assert self.installation_store is not None
+        installation = await self.installation_store.find_by_guild(
+            guild_id=guild_id
+        )
+        if not installation:
+            logger.error(f"No installation found for guild: {guild_id}")
+            return None
+
+        if (
+            installation.token_expires_at
+            and datetime.now() >= installation.token_expires_at
+        ):
+            logger.info(
+                f"Access token expired for guild: {guild_id}, "
+                f"refreshing token..."
+            )
+            new_access_token = await self.refresh_access_token(
+                installation.refresh_token
+            )
+            if new_access_token:
+                installation.access_token = new_access_token
+                installation.token_expires_at = datetime.now() + timedelta(
+                    seconds=3600
+                )
+                await self.installation_store.save(installation)
+                return new_access_token
+            else:
+                logger.error(
+                    f"Failed to refresh access token for guild: {guild_id}"
+                )
+                return None
+
+        return installation.access_token
+
+    async def save_installation(
+        self,
+        guild_id: str,
+        access_token: str,
+        refresh_token: str,
+        expires_in: int,
+    ):
+        r"""Save the installation information for a given guild.
+
+        Args:
+            guild_id (str): The ID of the guild where the bot is installed.
+            access_token (str): The access token for the guild.
+            refresh_token (str): The refresh token for the guild.
+            expires_in: (int): The expiration time of the
+                access token.
+        """
+        if not self.oauth_flow:
+            logger.warning(
+                "OAuth is not enabled. Missing client_id, "
+                "client_secret, or redirect_uri."
+            )
+            return None
+        assert self.installation_store is not None
+        expires_at = datetime.now() + timedelta(seconds=expires_in)
+        installation = DiscordInstallation(
+            guild_id=guild_id,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            installed_at=datetime.now(),
+            token_expires_at=expires_at,
+        )
+        await self.installation_store.save(installation)
+        logger.info(f"Installation saved for guild: {guild_id}")
+
+    async def remove_installation(self, guild: discord.Guild):
+        r"""Remove the installation for a given guild.
+
+        Args:
+            guild (discord.Guild): The guild from which the bot is
+                being removed.
+        """
+        if not self.oauth_flow:
+            logger.warning(
+                "OAuth is not enabled. Missing client_id, "
+                "client_secret, or redirect_uri."
+            )
+            return None
+        assert self.installation_store is not None
+        await self.installation_store.delete(guild_id=str(guild.id))
+        print(f"Bot removed from guild: {guild.id}")
+
+    async def on_ready(self) -> None:
+        r"""Event handler that is called when the bot has successfully
+        connected to the Discord server.
+
+        When the bot is ready and logged into Discord, it prints a message
+        displaying the bot's username.
+        """
+        logger.info(f'We have logged in as {self._client.user}')
+
+    async def on_message(self, message: 'Message') -> None:
+        r"""Event handler for processing incoming messages.
+
+        This method is called whenever a new message is received by the bot. It
+        will ignore messages sent by the bot itself, only respond to messages
+        in allowed channels (if specified), and only to messages that mention
+        the bot.
+
+        Args:
+            message (discord.Message): The message object received from
+                Discord.
+        """
+        # If the message author is the bot itself,
+        # do not respond to this message
+        if message.author == self._client.user:
+            return
+
+        # If allowed channel IDs are provided,
+        # only respond to messages in those channels
+        if self.channel_ids and message.channel.id not in self.channel_ids:
+            return
+
+        # Only respond to messages that mention the bot
+        if not self._client.user or not self._client.user.mentioned_in(
+            message
+        ):
+            return
+
+        logger.info(f"Received message: {message.content}")
+
+    @property
+    def client(self):
+        return self._client

camel/bots/discord/discord_installation.py

@@ -0,0 +1,64 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from datetime import datetime
+from typing import Optional
+
+
+class DiscordInstallation:
+    r"""Represents an installation of a Discord application in a
+        specific guild (server).
+
+    Attributes:
+        guild_id (str): The unique identifier for the Discord guild (server)
+            where the application is installed.
+        access_token (str): The access token used to authenticate API requests
+            for the installed application.
+        refresh_token (str): The token used to refresh the access token when
+            it expires.
+        installed_at (datetime): The timestamp indicating when the application
+            was installed in the guild.
+        token_expires_at (Optional[datetime]): The optional timestamp
+            indicating when the access token will expire. Defaults to None
+            if the token does not have an expiration time.
+    """
+
+    def __init__(
+        self,
+        guild_id: str,
+        access_token: str,
+        refresh_token: str,
+        installed_at: datetime,
+        token_expires_at: Optional[datetime] = None,
+    ):
+        r"""Initialize the DiscordInstallation.
+
+        Args:
+            guild_id (str): The unique identifier for the Discord guild
+                (server) where the application is installed.
+            access_token (str): The access token used to authenticate API
+                requests for the installed application.
+            refresh_token (str): The token used to refresh the access token
+                when it expires.
+            installed_at (datetime): The timestamp indicating when the
+                application was installed in the guild.
+            token_expires_at (Optional[datetime]): The optional timestamp
+                indicating when the access token will expire. Defaults to None
+                if the token does not have an expiration time.
+                (default: :obj:`None`)
+        """
+        self.guild_id = guild_id
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.installed_at = installed_at
+        self.token_expires_at = token_expires_at

camel/bots/discord/discord_store.py

@@ -0,0 +1,160 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from typing import Optional
+
+from .discord_installation import DiscordInstallation
+
+
+class DiscordBaseInstallationStore:
+    r"""Abstract base class for managing Discord installations.
+
+    This class defines the interface for database operations related to storing
+    and retrieving Discord installation data. Subclasses must implement these
+    methods to handle database-specific logic.
+    """
+
+    async def init(self):
+        r"""Initializes the database connection or structure."""
+        pass
+
+    async def save(self, installation: DiscordInstallation):
+        r"""Saves or updates a Discord installation record."""
+        pass
+
+    async def find_by_guild(
+        self, guild_id: str
+    ) -> Optional[DiscordInstallation]:
+        r"""Finds an installation record by guild ID."""
+        pass
+
+    async def delete(self, guild_id: str):
+        r"""Deletes an installation record by guild ID."""
+        pass
+
+
+class DiscordSQLiteInstallationStore(DiscordBaseInstallationStore):
+    r"""SQLite-based implementation for managing Discord installations.
+
+    This class provides methods for initializing the database, saving,
+    retrieving, and deleting installation records using SQLite.
+
+    Attributes:
+        database (str): Path to the SQLite database file.
+    """
+
+    def __init__(self, database: str):
+        r"""Initializes the SQLite installation store.
+
+        Args:
+            database (str): Path to the SQLite database file.
+        """
+        self.database = database
+
+    async def init(self):
+        r"""Initializes the database by creating the required table if it
+        does not exist."""
+        import aiosqlite
+
+        async with aiosqlite.connect(self.database) as db:
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS discord_installations (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    guild_id TEXT NOT NULL UNIQUE,
+                    access_token TEXT NOT NULL,
+                    refresh_token TEXT NOT NULL,
+                    installed_at DATETIME NOT NULL,
+                    token_expires_at DATETIME
+                );
+                """
+            )
+            await db.commit()
+
+    async def save(self, installation: DiscordInstallation):
+        r"""Saves a new installation record or updates an existing one.
+
+        Args:
+            installation (DiscordInstallation): The installation data to save.
+        """
+        import aiosqlite
+
+        async with aiosqlite.connect(self.database) as db:
+            await db.execute(
+                """
+                INSERT INTO discord_installations (
+                    guild_id, access_token, refresh_token, 
+                    installed_at, token_expires_at
+                ) VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(guild_id) DO UPDATE SET
+                    access_token = excluded.access_token,
+                    refresh_token = excluded.refresh_token,
+                    token_expires_at = excluded.token_expires_at;
+                """,
+                [
+                    installation.guild_id,
+                    installation.access_token,
+                    installation.refresh_token,
+                    installation.installed_at,
+                    installation.token_expires_at,
+                ],
+            )
+            await db.commit()
+
+    async def find_by_guild(
+        self, guild_id: str
+    ) -> Optional[DiscordInstallation]:
+        r"""Finds an installation record by guild ID.
+
+        Args:
+            guild_id (str): The guild ID to search for.
+
+        Returns:
+            Optional[DiscordInstallation]: The installation record if found,
+                otherwise None.
+        """
+        import aiosqlite
+
+        async with aiosqlite.connect(self.database) as db:
+            async with db.execute(
+                "SELECT guild_id, access_token, refresh_token, "
+                "installed_at, token_expires_at FROM discord_installations "
+                "WHERE guild_id = ?",
+                [guild_id],
+            ) as cursor:
+                row = await cursor.fetchone()
+                if row:
+                    return DiscordInstallation(
+                        guild_id=row[0],
+                        access_token=row[1],
+                        refresh_token=row[2],
+                        installed_at=row[3],
+                        token_expires_at=row[4],
+                    )
+                return None
+
+    async def delete(self, guild_id: str):
+        r"""Deletes an installation record by guild ID.
+
+        Args:
+            guild_id (str): The guild ID of the record to delete.
+        """
+        import aiosqlite
+
+        async with aiosqlite.connect(self.database) as db:
+            await db.execute(
+                "DELETE FROM discord_installations WHERE guild_id = ?",
+                [guild_id],
+            )
+            await db.commit()

camel/bots/slack/__init__.py

@@ -0,0 +1,30 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from .models import (
+    SlackAppMentionEventBody,
+    SlackAppMentionEventProfile,
+    SlackAuthProfile,
+    SlackEventBody,
+    SlackEventProfile,
+)
+from .slack_app import SlackApp
+
+__all__ = [
+    'SlackApp',
+    'SlackAppMentionEventBody',
+    'SlackAppMentionEventProfile',
+    'SlackAuthProfile',
+    'SlackEventBody',
+    'SlackEventProfile',
+]

camel/bots/slack/models.py

@@ -0,0 +1,158 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class SlackAuthProfile(BaseModel):
+    r"""Represents the authorization profile within a Slack event.
+
+    Events will contain a single, compact authorizations field that shows one
+    installation of your app that the event is visible to.
+    In other words, lists of authorizations will be truncated to one element.
+
+    If there's more than one installing party that your app is keeping track
+    of, it's best not to rely on the single party listed in authorizations to
+    be any particular one.
+
+    To get a full list of who can see events, call the apps.event.
+    authorizations.list method after obtaining an app-level token. Read more on
+    the changes here; they have taken effect for existing apps as of
+    February 24, 2021.
+
+    References:
+
+    - https://api.slack.com/apis/events-api#authorizations
+    - https://api.slack.com/changelog/2020-09-15-events-api-truncate-authed-users#no_context
+    """
+
+    enterprise_id: Optional[str] = None
+    """The ID of the enterprise associated with the authorization."""
+
+    team_id: str
+    """The ID of the team associated with the authorization."""
+
+    user_id: str
+    """The ID of the user associated with the authorization."""
+
+    is_bot: bool
+    """Whether the authorized user is a bot."""
+
+    is_enterprise_install: bool
+    """Whether the authorization is for an enterprise installation."""
+
+
+class SlackEventProfile(BaseModel):
+    r"""Represents the detailed profile of a Slack event, including user,
+    message, and context data.
+    """
+
+    user: str
+    """The ID of the user associated with the event."""
+
+    type: str
+    """The type of the event (e.g., 'message')."""
+
+    ts: str
+    """A timestamp representing when the event was triggered."""
+
+    thread_ts: Optional[str] = None
+    """The timestamp of the parent message in a thread."""
+
+    client_msg_id: str
+    """A unique ID generated by the client for the message (if available)."""
+
+    text: str
+    """The message content text."""
+
+    team: str
+    """The ID of the team that the event is associated with."""
+
+    blocks: list
+    """The list of message blocks, providing structured information."""
+
+    channel: str
+    """The ID of the Slack channel where the event happened."""
+
+    event_ts: str
+    """The event-specific timestamp when it occurred."""
+
+    channel_type: Optional[str]
+    """The type of Slack channel (e.g., 'channel', 'im')."""
+
+
+class SlackEventBody(BaseModel):
+    r"""Represents the entire body of a Slack event, including the event
+    profile, authorization, and context.
+    """
+
+    token: str
+    """The token to verify the source of the event."""
+
+    team_id: str
+    """The ID of the team where the event is happening."""
+
+    context_team_id: Optional[str]
+    """The team ID for the shared channel context, if applicable."""
+
+    context_enterprise_id: Optional[str] = None
+    """The enterprise ID for the shared channel context, if applicable."""
+
+    api_app_id: str
+    """The unique identifier for the Slack app that received the event."""
+
+    event: SlackEventProfile
+    """A detailed profile of the event"""
+
+    type: str
+    """The overall type of event received (e.g., 'event_callback')."""
+
+    event_id: str
+    """A unique identifier assigned to this event by Slack."""
+
+    event_time: int
+    """The timestamp (in seconds) representing when the event was triggered."""
+
+    authorizations: Optional[list[SlackAuthProfile]] = None
+    """An optional list of authorizations that describe which installation can 
+    see the event."""
+
+    is_ext_shared_channel: bool
+    """Indicates if the event is part of a shared channel between different 
+    organizations."""
+
+    event_context: str
+    """A unique string representing the context of the event."""
+
+
+class SlackAppMentionEventProfile(SlackEventProfile):
+    r"""Represents the detailed profile of a Slack event where the app was
+    mentioned in a message.
+    """
+
+    channel_type: Optional[str] = None
+    """The type of Slack channel. it's None for app mentions."""
+
+
+class SlackAppMentionEventBody(SlackEventBody):
+    r"""Represents the entire body of a Slack event where the app was mentioned
+    in a message.
+    """
+
+    context_team_id: Optional[str] = None
+    """A detailed profile of the event. it's None for app mentions."""
+
+    event: SlackAppMentionEventProfile
+    """A detailed profile of the event"""

camel/bots/slack/slack_app.py

@@ -0,0 +1,255 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import logging
+import os
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from slack_sdk.oauth.installation_store.async_installation_store import (
+    AsyncInstallationStore,
+)
+from starlette import requests, responses
+
+from camel.bots.slack.models import (
+    SlackAppMentionEventBody,
+    SlackAppMentionEventProfile,
+    SlackEventBody,
+    SlackEventProfile,
+)
+from camel.utils import dependencies_required
+
+if TYPE_CHECKING:
+    from slack_bolt.context.async_context import AsyncBoltContext
+    from slack_bolt.context.say.async_say import AsyncSay
+    from slack_sdk.web.async_client import AsyncWebClient
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class SlackApp:
+    r"""Represents a Slack app that is powered by a Slack Bolt `AsyncApp`.
+
+    This class is responsible for initializing and managing the Slack
+    application by setting up event handlers, running the app server, and
+    handling events such as messages and mentions from Slack.
+
+    Args:
+        token (Optional[str]): Slack API token for authentication.
+        scopes (Optional[str]): Slack app scopes for permissions.
+        signing_secret (Optional[str]): Signing secret for verifying Slack
+            requests.
+        client_id (Optional[str]): Slack app client ID.
+        client_secret (Optional[str]): Slack app client secret.
+        redirect_uri_path (str): The URI path for OAuth redirect, defaults to
+            "/slack/oauth_redirect".
+        installation_store (Optional[AsyncInstallationStore]): The installation
+            store for handling OAuth installations.
+    """
+
+    @dependencies_required('slack_bolt')
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        scopes: Optional[str] = None,
+        signing_secret: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        redirect_uri_path: str = "/slack/oauth_redirect",
+        installation_store: Optional[AsyncInstallationStore] = None,
+    ) -> None:
+        r"""Initializes the SlackApp instance by setting up the Slack Bolt app
+        and configuring event handlers and OAuth settings.
+
+        Args:
+            token (Optional[str]): The Slack API token.
+            scopes (Optional[str]): The scopes for Slack app permissions.
+            signing_secret (Optional[str]): The signing secret for verifying
+                requests.
+            client_id (Optional[str]): The Slack app client ID.
+            client_secret (Optional[str]): The Slack app client secret.
+            redirect_uri_path (str): The URI path for handling OAuth redirects
+                (default is "/slack/oauth_redirect").
+            installation_store (Optional[AsyncInstallationStore]): An optional
+                installation store for OAuth installations.
+        """
+        from slack_bolt.adapter.starlette.async_handler import (
+            AsyncSlackRequestHandler,
+        )
+        from slack_bolt.app.async_app import AsyncApp
+        from slack_bolt.oauth.async_oauth_settings import AsyncOAuthSettings
+
+        self.token: Optional[str] = token or os.getenv("SLACK_TOKEN")
+        self.scopes: Optional[str] = scopes or os.getenv("SLACK_SCOPES")
+        self.signing_secret: Optional[str] = signing_secret or os.getenv(
+            "SLACK_SIGNING_SECRET"
+        )
+        self.client_id: Optional[str] = client_id or os.getenv(
+            "SLACK_CLIENT_ID"
+        )
+        self.client_secret: Optional[str] = client_secret or os.getenv(
+            "SLACK_CLIENT_SECRET"
+        )
+
+        if not all([self.token, self.scopes, self.signing_secret]):
+            raise ValueError(
+                "`SLACK_TOKEN`, `SLACK_SCOPES`, and `SLACK_SIGNING_SECRET` "
+                "environment variables must be set. Get it here: "
+                "`https://api.slack.com/apps`."
+            )
+
+        # Setup OAuth settings if client ID and secret are provided
+        if self.client_id and self.client_secret:
+            self._app = AsyncApp(
+                oauth_settings=AsyncOAuthSettings(
+                    client_id=self.client_id,
+                    client_secret=self.client_secret,
+                    scopes=self.scopes,
+                    redirect_uri_path=redirect_uri_path,
+                ),
+                logger=logger,
+                signing_secret=self.signing_secret,
+                installation_store=installation_store,
+                token=self.token,
+            )
+        else:
+            # Initialize Slack Bolt AsyncApp with settings
+            self._app = AsyncApp(
+                logger=logger,
+                signing_secret=self.signing_secret,
+                installation_store=installation_store,
+                token=self.token,
+            )
+
+        self._handler = AsyncSlackRequestHandler(self._app)
+        self.setup_handlers()
+
+    def setup_handlers(self) -> None:
+        r"""Sets up the event handlers for Slack events, such as `app_mention`
+        and `message`.
+
+        This method registers the `app_mention` and `on_message` event handlers
+        with the Slack Bolt app to respond to Slack events.
+        """
+        self._app.event("app_mention")(self.app_mention)
+        self._app.event("message")(self.on_message)
+
+    def run(
+        self,
+        port: int = 3000,
+        path: str = "/slack/events",
+        host: Optional[str] = None,
+    ) -> None:
+        r"""Starts the Slack Bolt app server to listen for incoming Slack
+        events.
+
+        Args:
+            port (int): The port on which the server should run (default is
+                3000).
+            path (str): The endpoint path for receiving Slack events (default
+                is "/slack/events").
+            host (Optional[str]): The hostname to bind the server (default is
+                None).
+        """
+        self._app.start(port=port, path=path, host=host)
+
+    async def handle_request(
+        self, request: requests.Request
+    ) -> responses.Response:
+        r"""Handles incoming requests from Slack through the request handler.
+
+        Args:
+            request (Request): A Starlette request object representing the
+                incoming request.
+
+        Returns:
+            The response generated by the Slack Bolt handler.
+        """
+        return await self._handler.handle(request)
+
+    async def app_mention(
+        self,
+        context: "AsyncBoltContext",
+        client: "AsyncWebClient",
+        event: Dict[str, Any],
+        body: Dict[str, Any],
+        say: "AsyncSay",
+    ) -> None:
+        r"""Event handler for `app_mention` events.
+
+        This method is triggered when someone mentions the app in Slack.
+
+        Args:
+            context (AsyncBoltContext): The Slack Bolt context for the event.
+            client (AsyncWebClient): The Slack Web API client.
+            event (Dict[str, Any]): The event data for the app mention.
+            body (Dict[str, Any]): The full request body from Slack.
+            say (AsyncSay): A function to send a response back to the channel.
+        """
+        event_profile = SlackAppMentionEventProfile(**event)
+        event_body = SlackAppMentionEventBody(**body)
+
+        logger.info(f"app_mention, context: {context}")
+        logger.info(f"app_mention, client: {client}")
+        logger.info(f"app_mention, event_profile: {event_profile}")
+        logger.info(f"app_mention, event_body: {event_body}")
+        logger.info(f"app_mention, say: {say}")
+
+    async def on_message(
+        self,
+        context: "AsyncBoltContext",
+        client: "AsyncWebClient",
+        event: Dict[str, Any],
+        body: Dict[str, Any],
+        say: "AsyncSay",
+    ) -> None:
+        r"""Event handler for `message` events.
+
+        This method is triggered when the app receives a message in Slack.
+
+        Args:
+            context (AsyncBoltContext): The Slack Bolt context for the event.
+            client (AsyncWebClient): The Slack Web API client.
+            event (Dict[str, Any]): The event data for the message.
+            body (Dict[str, Any]): The full request body from Slack.
+            say (AsyncSay): A function to send a response back to the channel.
+        """
+        await context.ack()
+
+        event_profile = SlackEventProfile(**event)
+        event_body = SlackEventBody(**body)
+
+        logger.info(f"on_message, context: {context}")
+        logger.info(f"on_message, client: {client}")
+        logger.info(f"on_message, event_profile: {event_profile}")
+        logger.info(f"on_message, event_body: {event_body}")
+        logger.info(f"on_message, say: {say}")
+
+        logger.info(f"Received message: {event_profile.text}")
+
+    def mention_me(
+        self, context: "AsyncBoltContext", body: SlackEventBody
+    ) -> bool:
+        r"""Check if the bot is mentioned in the message.
+
+        Args:
+            context (AsyncBoltContext): The Slack Bolt context for the event.
+            body (SlackEventBody): The body of the Slack event.
+
+        Returns:
+            bool: True if the bot is mentioned in the message, False otherwise.
+        """
+        message = body.event.text
+        bot_user_id = context.bot_user_id
+        mention = f"<@{bot_user_id}>"
+        return mention in message

camel/bots/telegram_bot.py

@@ -0,0 +1,82 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+from typing import TYPE_CHECKING, Optional
+
+from camel.agents import ChatAgent
+from camel.messages import BaseMessage
+from camel.utils import dependencies_required
+
+# Conditionally import telebot types only for type checking
+if TYPE_CHECKING:
+    from telebot.types import (  # type: ignore[import-untyped]
+        Message,
+    )
+
+
+class TelegramBot:
+    r"""Represents a Telegram bot that is powered by an agent.
+
+    Attributes:
+        chat_agent (ChatAgent): Chat agent that will power the bot.
+        telegram_token (str, optional): The bot token.
+    """
+
+    @dependencies_required('telebot')
+    def __init__(
+        self,
+        chat_agent: ChatAgent,
+        telegram_token: Optional[str] = None,
+    ) -> None:
+        self.chat_agent = chat_agent
+
+        if not telegram_token:
+            self.token = os.getenv('TELEGRAM_TOKEN')
+            if not self.token:
+                raise ValueError(
+                    "`TELEGRAM_TOKEN` not found in environment variables. "
+                    "Get it from t.me/BotFather."
+                )
+        else:
+            self.token = telegram_token
+
+        import telebot  # type: ignore[import-untyped]
+
+        self.bot = telebot.TeleBot(token=self.token)
+
+        # Register the message handler within the constructor
+        self.bot.message_handler(func=lambda message: True)(self.on_message)
+
+    def run(self) -> None:
+        r"""Start the Telegram bot."""
+        print("Telegram bot is running...")
+        self.bot.infinity_polling()
+
+    def on_message(self, message: 'Message') -> None:
+        r"""Handles incoming messages from the user.
+
+        Args:
+            message (types.Message): The incoming message object.
+        """
+        self.chat_agent.reset()
+
+        if not message.text:
+            return
+
+        user_msg = BaseMessage.make_user_message(
+            role_name="User", content=message.text
+        )
+        assistant_response = self.chat_agent.step(user_msg)
+
+        self.bot.reply_to(message, assistant_response.msg.content)

camel/configs/__init__.py

@@ -0,0 +1,85 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from .anthropic_config import ANTHROPIC_API_PARAMS, AnthropicConfig
+from .base_config import BaseConfig
+from .cohere_config import COHERE_API_PARAMS, CohereConfig
+from .deepseek_config import DEEPSEEK_API_PARAMS, DeepSeekConfig
+from .gemini_config import Gemini_API_PARAMS, GeminiConfig
+from .groq_config import GROQ_API_PARAMS, GroqConfig
+from .internlm_config import INTERNLM_API_PARAMS, InternLMConfig
+from .litellm_config import LITELLM_API_PARAMS, LiteLLMConfig
+from .mistral_config import MISTRAL_API_PARAMS, MistralConfig
+from .nvidia_config import NVIDIA_API_PARAMS, NvidiaConfig
+from .ollama_config import OLLAMA_API_PARAMS, OllamaConfig
+from .openai_config import OPENAI_API_PARAMS, ChatGPTConfig
+from .qwen_config import QWEN_API_PARAMS, QwenConfig
+from .reka_config import REKA_API_PARAMS, RekaConfig
+from .openrouter_config import OPENROUTER_API_PARAMS, OpenRouterConfig
+from .samba_config import (
+    SAMBA_CLOUD_API_PARAMS,
+    SAMBA_VERSE_API_PARAMS,
+    SambaCloudAPIConfig,
+    SambaVerseAPIConfig,
+)
+from .sglang_config import SGLANG_API_PARAMS, SGLangConfig
+from .togetherai_config import TOGETHERAI_API_PARAMS, TogetherAIConfig
+from .vllm_config import VLLM_API_PARAMS, VLLMConfig
+from .yi_config import YI_API_PARAMS, YiConfig
+from .zhipuai_config import ZHIPUAI_API_PARAMS, ZhipuAIConfig
+
+__all__ = [
+    'BaseConfig',
+    'ChatGPTConfig',
+    'OPENAI_API_PARAMS',
+    'AnthropicConfig',
+    'ANTHROPIC_API_PARAMS',
+    'GROQ_API_PARAMS',
+    'GroqConfig',
+    'LiteLLMConfig',
+    'LITELLM_API_PARAMS',
+    'NvidiaConfig',
+    'NVIDIA_API_PARAMS',
+    'OllamaConfig',
+    'OLLAMA_API_PARAMS',
+    'ZhipuAIConfig',
+    'ZHIPUAI_API_PARAMS',
+    'GeminiConfig',
+    'Gemini_API_PARAMS',
+    'VLLMConfig',
+    'VLLM_API_PARAMS',
+    'SGLangConfig',
+    'SGLANG_API_PARAMS',
+    'MistralConfig',
+    'MISTRAL_API_PARAMS',
+    'RekaConfig',
+    'REKA_API_PARAMS',
+    'SambaVerseAPIConfig',
+    'SAMBA_VERSE_API_PARAMS',
+    'SambaCloudAPIConfig',
+    'SAMBA_CLOUD_API_PARAMS',
+    'TogetherAIConfig',
+    'TOGETHERAI_API_PARAMS',
+    'CohereConfig',
+    'COHERE_API_PARAMS',
+    'YiConfig',
+    'YI_API_PARAMS',
+    'QwenConfig',
+    'QWEN_API_PARAMS',
+    'DeepSeekConfig',
+    'DEEPSEEK_API_PARAMS',
+    'InternLMConfig',
+    'INTERNLM_API_PARAMS',
+    'OPENROUTER_API_PARAMS',
+    'OpenRouterConfig',
+]

camel/configs/anthropic_config.py

@@ -0,0 +1,71 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from __future__ import annotations
+
+from typing import Any, ClassVar, List, Union
+
+from camel.configs.base_config import BaseConfig
+from camel.types import NotGiven
+
+
+class AnthropicConfig(BaseConfig):
+    r"""Defines the parameters for generating chat completions using the
+    Anthropic API.
+
+    See: https://docs.anthropic.com/claude/reference/complete_post
+    Args:
+        max_tokens (int, optional): The maximum number of tokens to
+            generate before stopping. Note that Anthropic models may stop
+            before reaching this maximum. This parameter only specifies the
+            absolute maximum number of tokens to generate.
+            (default: :obj:`8192`)
+        stop_sequences (List[str], optional): Sequences that will cause the
+            model to stop generating completion text. Anthropic models stop
+            on "\n\nHuman:", and may include additional built-in stop sequences
+            in the future. By providing the stop_sequences parameter, you may
+            include additional strings that will cause the model to stop
+            generating. (default: :obj:`[]`)
+        temperature (float, optional): Amount of randomness injected into the
+            response. Defaults to 1. Ranges from 0 to 1. Use temp closer to 0
+            for analytical / multiple choice, and closer to 1 for creative
+            and generative tasks. (default: :obj:`1`)
+        top_p (float, optional): Use nucleus sampling. In nucleus sampling, we
+            compute the cumulative distribution over all the options for each
+            subsequent token in decreasing probability order and cut it off
+            once it reaches a particular probability specified by `top_p`.
+            You should either alter `temperature` or `top_p`,
+            but not both. (default: :obj:`0.7`)
+        top_k (int, optional): Only sample from the top K options for each
+            subsequent token. Used to remove "long tail" low probability
+            responses. (default: :obj:`5`)
+        metadata: An object describing metadata about the request.
+        stream (bool, optional): Whether to incrementally stream the response
+            using server-sent events. (default: :obj:`False`)
+    """
+
+    max_tokens: int = 8192
+    stop_sequences: ClassVar[Union[List[str], NotGiven]] = []
+    temperature: float = 1
+    top_p: Union[float, NotGiven] = 0.7
+    top_k: Union[int, NotGiven] = 5
+    stream: bool = False
+
+    def as_dict(self) -> dict[str, Any]:
+        config_dict = super().as_dict()
+        if "tools" in config_dict:
+            del config_dict["tools"]  # TODO: Support tool calling.
+        return config_dict
+
+
+ANTHROPIC_API_PARAMS = {param for param in AnthropicConfig.model_fields.keys()}

camel/configs/base_config.py

@@ -0,0 +1,89 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+
+class BaseConfig(ABC, BaseModel):
+    r"""Base configuration class for all models.
+
+    This class provides a common interface for all models, ensuring that all
+    models have a consistent set of attributes and methods.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="forbid",
+        frozen=True,
+        # UserWarning: conflict with protected namespace "model_"
+        protected_namespaces=(),
+    )
+
+    tools: Optional[List[Any]] = None
+    """A list of tools the model may
+    call. Currently, only functions are supported as a tool. Use this
+    to provide a list of functions the model may generate JSON inputs
+    for. A max of 128 functions are supported.
+    """
+
+    @field_validator("tools", mode="before")
+    @classmethod
+    def fields_type_checking(cls, tools):
+        r"""Validate the type of tools in the configuration.
+
+        This method ensures that the tools provided in the configuration are
+        instances of `FunctionTool`. If any tool is not an instance of
+        `FunctionTool`, it raises a ValueError.
+        """
+        if tools is not None:
+            from camel.toolkits import FunctionTool
+
+            for tool in tools:
+                if not isinstance(tool, FunctionTool):
+                    raise ValueError(
+                        f"The tool {tool} should "
+                        "be an instance of `FunctionTool`."
+                    )
+        return tools
+
+    def as_dict(self) -> dict[str, Any]:
+        r"""Convert the current configuration to a dictionary.
+
+        This method converts the current configuration object to a dictionary
+        representation, which can be used for serialization or other purposes.
+
+        Returns:
+            dict[str, Any]: A dictionary representation of the current
+                configuration.
+        """
+        config_dict = self.model_dump()
+
+        tools_schema = None
+        if self.tools:
+            from camel.toolkits import FunctionTool
+
+            tools_schema = []
+            for tool in self.tools:
+                if not isinstance(tool, FunctionTool):
+                    raise ValueError(
+                        f"The tool {tool} should "
+                        "be an instance of `FunctionTool`."
+                    )
+                tools_schema.append(tool.get_openai_tool_schema())
+        config_dict["tools"] = tools_schema
+        return config_dict

camel/configs/cohere_config.py

@@ -0,0 +1,76 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from __future__ import annotations
+
+from typing import List, Optional
+
+from camel.configs.base_config import BaseConfig
+
+
+class CohereConfig(BaseConfig):
+    r"""Defines the parameters for generating chat completions using the
+    Cohere API.
+
+    Args:
+        temperature (float, optional): Sampling temperature to use, between
+            :obj:`0` and :obj:`2`. Higher values make the output more random,
+            while lower values make it more focused and deterministic.
+            (default: :obj:`0.3`)
+        documents (list, optional): A list of relevant documents that the
+            model can cite to generate a more accurate reply. Each document is
+            either a string or document object with content and metadata.
+            (default: :obj:`None`)
+        max_tokens (int, optional): The maximum number of tokens the model
+            will generate as part of the response. (default: :obj:`None`)
+        stop_sequences (List(str), optional): A list of up to 5 strings that
+            the model will use to stop generation. If the model generates a
+            string that matches any of the strings in the list, it will stop
+            generating tokens and return the generated text up to that point
+            not including the stop sequence. (default: :obj:`None`)
+        seed (int, optional): If specified, the backend will make a best
+            effort to sample tokens deterministically, such that repeated
+            requests with the same seed and parameters should return the same
+            result. However, determinism cannot be totally guaranteed.
+            (default: :obj:`None`)
+        frequency_penalty (float, optional): Min value of `0.0`, max value of
+            `1.0`. Used to reduce repetitiveness of generated tokens. The
+            higher the value, the stronger a penalty is applied to previously
+            present tokens, proportional to how many times they have already
+            appeared in the prompt or prior generation. (default: :obj:`0.0`)
+        presence_penalty (float, optional): Min value of `0.0`, max value of
+            `1.0`. Used to reduce repetitiveness of generated tokens. Similar
+            to `frequency_penalty`, except that this penalty is applied
+            equally to all tokens that have already appeared, regardless of
+            their exact frequencies. (default: :obj:`0.0`)
+        k (int, optional): Ensures only the top k most likely tokens are
+            considered for generation at each step. Min value of `0`, max
+            value of `500`. (default: :obj:`0`)
+        p (float, optional): Ensures that only the most likely tokens, with
+            total probability mass of `p`, are considered for generation at
+            each step. If both k and p are enabled, `p` acts after `k`. Min
+            value of `0.01`, max value of `0.99`. (default: :obj:`0.75`)
+    """
+
+    temperature: Optional[float] = 0.2
+    documents: Optional[list] = None
+    max_tokens: Optional[int] = None
+    stop_sequences: Optional[List[str]] = None
+    seed: Optional[int] = None
+    frequency_penalty: Optional[float] = 0.0
+    presence_penalty: Optional[float] = 0.0
+    k: Optional[int] = 0
+    p: Optional[float] = 0.75
+
+
+COHERE_API_PARAMS = {param for param in CohereConfig().model_fields.keys()}

camel/configs/deepseek_config.py

@@ -0,0 +1,134 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Type, Union
+
+from pydantic import BaseModel
+
+from camel.configs.base_config import BaseConfig
+from camel.types import NOT_GIVEN, NotGiven
+
+
+class DeepSeekConfig(BaseConfig):
+    r"""Defines the parameters for generating chat completions using the
+    DeepSeek API.
+
+    Args:
+        temperature (float, optional): Sampling temperature to use, between
+            :obj:`0` and :obj:`2`. Higher values make the output more random,
+            while lower values make it more focused and deterministic.
+            (default: :obj:`1.0`)
+        top_p (float, optional): Controls the diversity and focus of the
+            generated results. Higher values make the output more diverse,
+            while lower values make it more focused. (default: :obj:`1.0`)
+        response_format (object, optional): Specifies the format of the
+            returned content. The available values are `{"type": "text"}` or
+            `{"type": "json_object"}`. Setting it to `{"type": "json_object"}`
+            will output a standard JSON string.
+            (default: :obj:`{"type": "text"}`)
+        stream (bool, optional): If set, partial message deltas will be sent.
+            Tokens will be sent as data-only server-sent events (SSE) as
+            they become available, with the stream terminated by a
+            data: [DONE] message. (default: :obj:`False`)
+        stop (Union[str, list[str]], optional): Up to 16 sequences where
+            the API will stop generating further tokens. (default: :obj:`None`)
+        max_tokens (int, optional): The maximum number of tokens that can
+            be generated in the chat completion. The total length of input
+            tokens and generated tokens is limited by the model's context
+            length. (default: :obj:`None`)
+        presence_penalty (float, optional): Number between -2.0 and 2.0.
+            Positive values penalize new tokens based on whether they
+            appear in the text so far, increasing the model's likelihood
+            to talk about new topics. (default: :obj:`0.0`)
+        frequency_penalty (float, optional): Number between -2.0 and 2.0.
+            Positive values penalize new tokens based on their existing
+            frequency in the text so far, decreasing the model's likelihood
+            to repeat the same line verbatim. (default: :obj:`0`)
+        tools (list[FunctionTool], optional): A list of tools the model may
+            call. Currently, only functions are supported as a tool. Use
+            this to provide a list of functions the model may generate JSON
+            inputs for. A max of 128 functions are supported.
+            (default: :obj:`None`)
+        tool_choice (Union[dict[str, str], str], optional): Controls which
+            (if any) tool is called by the model. "none" means the model
+            will not call any tool and instead generates a message. "auto"
+            means the model can pick between generating a message or calling
+            one or more tools. "required" means the model must call one or
+            more tools. Specifying a particular tool via
+            {"type": "function", "function": {"name": "my_function"}} forces
+            the model to call that tool. "none" is the default when no tools
+            are present. "auto" is the default if tools are present.
+            (default: :obj:`"auto"`)
+        logprobs (bool, optional): Whether to return log probabilities of
+            the output tokens or not. If true, returns the log probabilities
+            of each output token returned in the content of message.
+            (default: :obj:`False`)
+        top_logprobs (int, optional): An integer between 0 and 20 specifying
+            the number of most likely tokens to return at each token
+            position, each with an associated log probability. logprobs
+            must be set to true if this parameter is used.
+            (default: :obj:`None`)
+        include_usage (bool, optional): When streaming, specifies whether to
+            include usage information in `stream_options`. (default:
+            :obj:`True`)
+    """
+
+    temperature: float = 1.0  # deepseek default: 1.0
+    top_p: float = 1.0
+    stream: bool = False
+    stop: Union[str, Sequence[str], NotGiven] = NOT_GIVEN
+    max_tokens: Union[int, NotGiven] = NOT_GIVEN
+    presence_penalty: float = 0.0
+    response_format: Union[Type[BaseModel], dict, NotGiven] = NOT_GIVEN
+    frequency_penalty: float = 0.0
+    tool_choice: Optional[Union[dict[str, str], str]] = None
+    logprobs: bool = False
+    top_logprobs: Optional[int] = None
+
+    def __init__(self, include_usage: bool = True, **kwargs):
+        super().__init__(**kwargs)
+        # Only set stream_options when stream is True
+        # Otherwise, it will raise error when calling the API
+        if self.stream:
+            self.stream_options = {"include_usage": include_usage}
+
+    def as_dict(self) -> dict[str, Any]:
+        r"""Convert the current configuration to a dictionary.
+
+        This method converts the current configuration object to a dictionary
+        representation, which can be used for serialization or other purposes.
+
+        Returns:
+            dict[str, Any]: A dictionary representation of the current
+                configuration.
+        """
+        config_dict = self.model_dump()
+        if self.tools:
+            from camel.toolkits import FunctionTool
+
+            tools_schema = []
+            for tool in self.tools:
+                if not isinstance(tool, FunctionTool):
+                    raise ValueError(
+                        f"The tool {tool} should "
+                        "be an instance of `FunctionTool`."
+                    )
+                tools_schema.append(tool.get_openai_tool_schema())
+        config_dict["tools"] = NOT_GIVEN
+        return config_dict
+
+
+DEEPSEEK_API_PARAMS = {param for param in DeepSeekConfig.model_fields.keys()}

camel/configs/gemini_config.py

@@ -0,0 +1,114 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Type, Union
+
+from pydantic import BaseModel
+
+from camel.configs.base_config import BaseConfig
+from camel.types import NOT_GIVEN, NotGiven
+
+
+class GeminiConfig(BaseConfig):
+    r"""Defines the parameters for generating chat completions using the
+    Gemini API.
+
+    Args:
+        temperature (float, optional): Sampling temperature to use, between
+            :obj:`0` and :obj:`2`. Higher values make the output more random,
+            while lower values make it more focused and deterministic.
+            (default: :obj:`0.2`)
+        top_p (float, optional): An alternative to sampling with temperature,
+            called nucleus sampling, where the model considers the results of
+            the tokens with top_p probability mass. So :obj:`0.1` means only
+            the tokens comprising the top 10% probability mass are considered.
+            (default: :obj:`1.0`)
+        n (int, optional): How many chat completion choices to generate for
+            each input message. (default: :obj:`1`)
+        response_format (object, optional): An object specifying the format
+            that the model must output. Compatible with GPT-4 Turbo and all
+            GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to
+            {"type": "json_object"} enables JSON mode, which guarantees the
+            message the model generates is valid JSON. Important: when using
+            JSON mode, you must also instruct the model to produce JSON
+            yourself via a system or user message. Without this, the model
+            may generate an unending stream of whitespace until the generation
+            reaches the token limit, resulting in a long-running and seemingly
+            "stuck" request. Also note that the message content may be
+            partially cut off if finish_reason="length", which indicates the
+            generation exceeded max_tokens or the conversation exceeded the
+            max context length.
+        stream (bool, optional): If True, partial message deltas will be sent
+            as data-only server-sent events as they become available.
+            (default: :obj:`False`)
+        stop (str or list, optional): Up to :obj:`4` sequences where the API
+            will stop generating further tokens. (default: :obj:`None`)
+        max_tokens (int, optional): The maximum number of tokens to generate
+            in the chat completion. The total length of input tokens and
+            generated tokens is limited by the model's context length.
+            (default: :obj:`None`)
+        tools (list[FunctionTool], optional): A list of tools the model may
+            call. Currently, only functions are supported as a tool. Use this
+            to provide a list of functions the model may generate JSON inputs
+            for. A max of 128 functions are supported.
+        tool_choice (Union[dict[str, str], str], optional): Controls which (if
+            any) tool is called by the model. :obj:`"none"` means the model
+            will not call any tool and instead generates a message.
+            :obj:`"auto"` means the model can pick between generating a
+            message or calling one or more tools.  :obj:`"required"` means the
+            model must call one or more tools. Specifying a particular tool
+            via {"type": "function", "function": {"name": "my_function"}}
+            forces the model to call that tool. :obj:`"none"` is the default
+            when no tools are present. :obj:`"auto"` is the default if tools
+            are present.
+    """
+
+    temperature: float = 0.2  # openai default: 1.0
+    top_p: float = 1.0
+    n: int = 1
+    stream: bool = False
+    stop: Union[str, Sequence[str], NotGiven] = NOT_GIVEN
+    max_tokens: Union[int, NotGiven] = NOT_GIVEN
+    response_format: Union[Type[BaseModel], dict, NotGiven] = NOT_GIVEN
+    tool_choice: Optional[Union[dict[str, str], str, NotGiven]] = NOT_GIVEN
+
+    def as_dict(self) -> dict[str, Any]:
+        r"""Convert the current configuration to a dictionary.
+
+        This method converts the current configuration object to a dictionary
+        representation, which can be used for serialization or other purposes.
+
+        Returns:
+            dict[str, Any]: A dictionary representation of the current
+                configuration.
+        """
+        config_dict = self.model_dump()
+        if self.tools:
+            from camel.toolkits import FunctionTool
+
+            tools_schema = []
+            for tool in self.tools:
+                if not isinstance(tool, FunctionTool):
+                    raise ValueError(
+                        f"The tool {tool} should "
+                        "be an instance of `FunctionTool`."
+                    )
+                tools_schema.append(tool.get_openai_tool_schema())
+        config_dict["tools"] = NOT_GIVEN
+        return config_dict
+
+
+Gemini_API_PARAMS = {param for param in GeminiConfig.model_fields.keys()}